Files

Lino Mallevaey b399e803b3 Version : 2025.11.22

2025-11-23 16:34:11 +01:00

11 KiB

Raw Blame History

🧮 Abacus

Application de comptabilité simplifiée pour associations

Abacus est une application web moderne conçue spécifiquement pour la gestion comptable des associations. Elle offre une interface intuitive et élégante permettant de gérer facilement vos balances financières, d'enregistrer vos opérations et de visualiser vos données comptables en temps réel.

🎯 Présentation

Abacus est née du besoin de simplifier la comptabilité associative. Au lieu de jongler avec des tableurs complexes, Abacus propose une solution web tout-en-un qui centralise :

✅ La gestion de vos balances (compte principal, caisse, épargne, etc.)
✅ L'enregistrement de vos opérations (recettes et dépenses)
✅ La visualisation de vos données avec des graphiques interactifs
✅ L'export PDF de vos rapports financiers
✅ La sécurité avec un système d'authentification utilisateur
✅ Le multi-tenant pour gérer plusieurs associations sur une même instance

L'application a été pensée pour être minimaliste, rapide et accessible, même pour les utilisateurs non techniques.

⚡ Fonctionnalités

🏠 Dashboard interactif

Vue d'ensemble de votre santé financière
Affichage en carrousel de toutes vos balances
Graphiques d'évolution des revenus et dépenses
Tableaux détaillés de toutes les opérations

💰 Gestion des balances

Création et suppression de balances multiples
Modification du nom et du montant initial
Suivi du solde actuel en temps réel
Organisation par cartes visuelles

📊 Gestion des opérations

Enregistrement de recettes et dépenses
Catégorisation des opérations (salaires, achats, dons, etc.)
Ajout de descriptions détaillées
Menu contextuel pour éditer ou supprimer
Modal de confirmation pour les suppressions

📈 Visualisations

Graphiques : Évolution temporelle avec Recharts
Tableaux : Liste détaillée et filtrable de toutes les opérations
Carrousel : Navigation fluide entre vos différentes balances

📄 Export PDF

Génération de rapports PDF professionnels
Consolidation de toutes les opérations par période
Une page par balance avec design soigné
Export direct depuis le dashboard

🔐 Sécurité

Authentification par utilisateur (login/password)
Hachage sécurisé des mots de passe (bcrypt)
Isolation multi-tenant des données
Sessions sécurisées

🛠️ Technologies utilisées

Frontend

Technologie	Version	Description
React	19.2.0	Framework UI moderne et performant
TypeScript	5.8.2	JavaScript typé pour plus de robustesse
Vite	6.2.0	Build tool ultra-rapide
Tailwind CSS	-	Framework CSS utilitaire
Recharts	3.3.0	Bibliothèque de graphiques React
React PDF	4.3.1	Génération de documents PDF
date-fns	4.1.0	Manipulation de dates

Backend

Technologie	Description
FastAPI	Framework Python moderne et performant
SQLModel	ORM basé sur SQLAlchemy et Pydantic
MySQL	Base de données relationnelle
PyMySQL	Connecteur MySQL pour Python
Uvicorn	Serveur ASGI haute performance
Typer	CLI moderne pour Python
Rich	Rendu de texte enrichi dans le terminal
Passlib	Hachage sécurisé de mots de passe (bcrypt)

📦 Installation

Prérequis

Avant de commencer, assurez-vous d'avoir installé :

Node.js (v16 ou supérieur) - Télécharger
Python (v3.8 ou supérieur) - Télécharger
MySQL (v5.7 ou supérieur) - Télécharger

1️⃣ Cloner le projet

git clone <url-du-repo>
cd abacus

2️⃣ Configuration du Backend

Installer les dépendances Python

cd backend
pip install -r requirements.txt

Note

: Il est recommandé d'utiliser un environnement virtuel :
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

Configurer la base de données

Créer une base de données MySQL :

CREATE DATABASE abacus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Configurer les variables d'environnement :
- Copier le fichier d'exemple :
```
# Linux/Mac
cp .env.example .env
# Windows
copy .env.example .env
```
- Éditer le fichier .env et renseigner vos informations MySQL :
```
DATABASE_URL=mysql+pymysql://utilisateur:motdepasse@localhost:3306/abacus
```
  Remplacez utilisateur, motdepasse et localhost:3306 par vos paramètres MySQL.
Initialiser les tables :
```
python cli.py setup-db
```

3️⃣ Configuration du Frontend

Installer les dépendances Node.js

Depuis la racine du projet :

npm install

🚀 Lancement de l'application

Mode développement

Pour développer avec rechargement automatique, lancez le backend et le frontend dans deux terminaux séparés :

Terminal 1 : Backend

cd backend
python cli.py start

✅ Le backend sera accessible sur http://localhost:8000

API REST : http://localhost:8000/api
Documentation Swagger : http://localhost:8000/docs

Terminal 2 : Frontend

npm run dev

✅ L'application sera accessible sur http://localhost:9873

Mode production

Pour lancer l'application complète en production :

python run_prod.py

✅ L'application sera accessible sur http://0.0.0.0:9874

Ce script :

Compile le frontend React en version optimisée
Copie les fichiers statiques dans le dossier backend
Lance le serveur FastAPI en mode production

📖 Utilisation

1. Première connexion

Ouvrez votre navigateur sur http://localhost:9873 (dev) ou http://localhost:9874 (prod)
Créez un compte en cliquant sur "Register"
Remplissez vos informations (nom d'utilisateur et mot de passe)
Connectez-vous avec vos identifiants

2. Créer votre première balance

Sur le dashboard, cliquez sur le bouton "+ Ajouter une balance"
Remplissez les informations :
- Nom : ex. "Compte Principal", "Caisse", "Épargne"
- Montant initial : le solde de départ (peut être 0)
Validez

3. Ajouter des opérations

Sélectionnez une balance dans le carrousel
Cliquez sur "+ Ajouter une opération"
Renseignez les détails :
- Type : Recette ou Dépense
- Montant : montant de l'opération
- Date : date de l'opération
- Catégorie : type d'opération (salaire, achat, don, etc.)
- Description : détails complémentaires
Validez

4. Visualiser vos données

Carrousel : Naviguez entre vos balances avec les flèches
Graphiques : Consultez l'évolution de vos revenus/dépenses au fil du temps
Tableau : Visualisez toutes les opérations en détail, triables et filtrables

5. Modifier ou supprimer

Opérations : Clic droit sur une opération → Modifier ou Supprimer
Balances : Menu contextuel sur chaque carte de balance

6. Exporter en PDF

Cliquez sur le bouton "Exporter PDF" dans l'en-tête
Le rapport complet sera généré et téléchargé automatiquement
Le PDF contient toutes vos balances et opérations avec un design professionnel

🎛️ Commandes CLI

Le backend dispose d'un outil CLI (cli.py) pour faciliter les tâches courantes :

Commande	Description
`python cli.py start`	Démarre le serveur de développement FastAPI (avec rechargement automatique)
`python cli.py setup-db`	Crée toutes les tables nécessaires dans la base de données
`python cli.py reset-db`	⚠️ DANGER : Supprime et recrée toutes les tables (perte de données)

Exemples :

# Démarrer le serveur
python cli.py start

# Créer les tables (première installation)
python cli.py setup-db

# Réinitialiser complètement la base (développement uniquement)
python cli.py reset-db

🏗️ Architecture

abacus/
├── backend/              # Backend FastAPI
│   ├── api/             # Routes API
│   ├── models/          # Modèles SQLModel
│   ├── database.py      # Configuration DB
│   ├── cli.py           # Outil CLI
│   ├── .env             # Variables d'environnement
│   └── requirements.txt # Dépendances Python
│
├── components/          # Composants React
│   ├── Dashboard.tsx
│   ├── BalanceCard.tsx
│   ├── OperationsTable.tsx
│   ├── OperationsChart.tsx
│   ├── AddBalanceModal.tsx
│   ├── AddOperationModal.tsx
│   ├── ExportButton.tsx
│   ├── PDFDocument.tsx
│   └── ...
│
├── public/              # Ressources statiques
├── App.tsx              # Composant principal
├── api.ts               # Client API
├── types.ts             # Types TypeScript
├── index.tsx            # Point d'entrée React
├── vite.config.ts       # Configuration Vite
├── package.json         # Dépendances Node.js
└── README.md            # Ce fichier

Flux de données

Frontend (React) → HTTP Request → Backend (FastAPI)
Backend → SQL Query → Database (MySQL)
Database → Data → Backend → JSON Response → Frontend

Multi-tenant

Chaque utilisateur a ses propres données isolées. Le backend filtre automatiquement toutes les requêtes en fonction de l'utilisateur connecté.

📄 Licence

Ce projet est sous licence CC BY-NC-SA 4.0 (Creative Commons Attribution - Pas d'Utilisation Commerciale - Partage dans les Mêmes Conditions).

Auteur : Coodlab, Mallevaey Lino
Version : 2025.11.22

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

Signaler des bugs
Proposer de nouvelles fonctionnalités
Soumettre des pull requests

📞 Support

Pour toute question ou problème :

Ouvrez une issue sur le dépôt GitHub
Consultez la documentation Swagger : http://localhost:8000/docs

Fait avec ❤️ pour simplifier la comptabilité associative

11 KiB Raw Blame History Unescape Escape