crowdlending-app/README.md

# Crowdlending Tracker

Application web de suivi de crowdlending : dépôts/retraits, investissements, remboursements (réels & simulés), tableau de bord global et récapitulatif fiscal **2778-SD**.

**Stack** : React (Vite) + Node.js / Express + SQLite (better-sqlite3) + Docker.

## Modules

1. **Dépôts / Retraits** — mouvements de cash par plateforme.
2. **CF Investissements** — liste des projets souscrits (montant, taux, durée, statut).
3. **Remboursements** — échéances réellement perçues, avec ventilation fiscale.
4. **Simul Remboursements** — échéancier prévisionnel (in fine, amortissable, mensuel, différé).
5. **TdB Global** — KPI cumulés, soldes par plateforme, intérêts par année, échéances à venir, projets en défaut.
6. **2778-SD** — récap annuel : intérêts, prélèvements sociaux, PFNL, pertes en capital, **export CSV**.

Chaque module supporte la **saisie manuelle** et l'**import Excel** (avec mappage de colonnes).

## Authentification

JWT, multi-utilisateurs. Chaque user peut gérer plusieurs **comptes investisseurs** (Monsieur, Madame, SCI…) — toutes les données sont scopées au compte actif (sélecteur en haut à droite).

## Interface

- **Menu masquable** : un bouton ☰ en haut de la barre d'outils permet de masquer / réafficher la sidebar (état persisté). Sur mobile, la sidebar est masquée par défaut et s'ouvre en overlay.
- **Thème clair / sombre / système** : sélecteur en haut à droite (☀ Clair, ☾ Sombre, ◐ Système). Le mode "Système" suit la préférence OS et réagit en temps réel quand vous changez le thème système. Choix persisté dans le navigateur.

## Démarrage rapide (Docker)

```bash
cp .env.example .env       # éditez JWT_SECRET
docker compose up -d --build
```

- Frontend : http://localhost:8080
- Backend  : http://localhost:4000/api/health

Les données SQLite et les uploads Excel sont persistés dans des volumes Docker (`backend_data`, `backend_uploads`).

## Démarrage en local (dev)

### Backend
```bash
cd backend
npm install
cp ../.env.example .env
npm run db:init      # crée le schéma SQLite
npm run dev          # http://localhost:4000
```

### Frontend
```bash
cd frontend
npm install
npm run dev          # http://localhost:5173 (proxie /api -> 4000)
```

## Premier usage

1. Allez sur `/register` et créez votre compte. Un compte investisseur "Compte principal" est créé automatiquement.
2. **Paramètres** → ajoutez vos plateformes (ClubFunding, October, La Première Brique, …).
3. **Paramètres** → ajoutez d'autres comptes investisseurs si besoin (Madame, SCI…).
4. **Dépôts / Retraits** → saisissez vos versements initiaux.
5. **CF Investissements** → ajoutez vos projets (avec taux + durée pour pouvoir simuler).
6. **Simul Remboursements** → choisissez un investissement et "Générer" pour créer l'échéancier.
7. **Remboursements** → saisissez les échéances reçues au fil de l'eau.
8. **2778-SD** → consultez le récap fiscal et exportez le CSV au moment de la déclaration.

## Import Excel

Module **Import Excel** dans le menu :
1. Choisir le module cible (Dépôts/Retraits, Investissements, ou Remboursements).
2. Uploader le fichier `.xlsx` ou `.csv`.
3. Mapper chaque champ cible avec la colonne Excel correspondante (auto-détection sur les noms exacts).
4. Pour les champs non présents dans le fichier, fournir une valeur par défaut.
5. Valider — les lignes sont insérées en bloc (transaction), avec un récap des erreurs ligne par ligne.

Les imports sont historisés (table `imports`).

## Schéma de la base

Voir `backend/src/db/schema.sql`. Tables principales :

| Table | Rôle |
|-------|------|
| `users` | comptes de connexion |
| `investisseurs` | profils d'investissement (multi-comptes) |
| `plateformes` | ClubFunding, October, … |
| `depots_retraits` | mouvements de cash |
| `investissements` | projets souscrits |
| `remboursements` | échéances réellement perçues |
| `simul_remboursements` | échéancier prévisionnel |
| `imports` | historique des imports |

Vues : `v_solde_plateforme`, `v_synthese_inv`, `v_interets_annuels`.

## Structure du projet

```
crowdlending-app/
├── backend/
│   ├── src/
│   │   ├── server.js              # Express bootstrap
│   │   ├── db/
│   │   │   ├── schema.sql         # schéma SQLite
│   │   │   ├── index.js           # connexion + apply schema
│   │   │   └── init.js            # script `npm run db:init`
│   │   ├── middleware/
│   │   │   ├── auth.js            # JWT
│   │   │   ├── investisseurScope.js
│   │   │   └── errorHandler.js
│   │   └── routes/
│   │       ├── auth.js
│   │       ├── investisseurs.js
│   │       ├── plateformes.js
│   │       ├── depotsRetraits.js
│   │       ├── investissements.js
│   │       ├── remboursements.js
│   │       ├── simul.js           # CRUD + générateur d'échéancier
│   │       ├── dashboard.js
│   │       ├── fiscal2778.js      # récap + export CSV
│   │       └── imports.js         # preview + apply
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── main.jsx               # bootstrap React
│   │   ├── App.jsx                # router
│   │   ├── api.js                 # fetch wrapper
│   │   ├── styles.css
│   │   ├── context/               # AuthContext, InvestisseurContext
│   │   ├── components/            # Layout, Modal
│   │   ├── pages/                 # Login/Register + 6 modules + Imports + Settings
│   │   └── utils/format.js
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── vite.config.js
│   └── package.json
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md
```

## Endpoints API (sélection)

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| POST | `/api/auth/register` | crée user + compte principal |
| POST | `/api/auth/login` | retourne JWT |
| GET  | `/api/auth/me` | user courant |
| GET/POST/PUT/DELETE | `/api/investisseurs` | gérer les comptes investisseurs |
| GET/POST/PUT/DELETE | `/api/plateformes` | gérer les plateformes |
| GET/POST/PUT/DELETE | `/api/depots-retraits` | mouvements de cash |
| GET/POST/PUT/DELETE | `/api/investissements` | projets |
| GET  | `/api/investissements/:id` | détail + remboursements + simul |
| GET/POST/PUT/DELETE | `/api/remboursements` | échéances réelles |
| GET/POST/DELETE | `/api/simul` | échéances prévisionnelles |
| POST | `/api/simul/generate` | générer l'échéancier d'un investissement |
| GET  | `/api/dashboard` | TdB global |
| GET  | `/api/fiscal-2778?annee=2025` | récap fiscal |
| GET  | `/api/fiscal-2778/export?annee=2025` | export CSV |
| POST | `/api/imports/preview` | analyse fichier Excel |
| POST | `/api/imports/apply` | insère les lignes selon mappage |
| GET  | `/api/imports/history` | historique des imports |

Tous les endpoints (sauf `/auth/*`) requièrent :
- header `Authorization: Bearer <jwt>`
- header `X-Investisseur-Id: <id>` pour les routes scopées (depots-retraits, investissements, remboursements, simul, dashboard, fiscal-2778, imports).

## Notes fiscales 2778-SD

Les cases calculées (2TR, 2CK, 2BH) sont **indicatives**. La logique est :

- **2TR** : somme des `interets_bruts` des remboursements payés/partiels de l'année.
- **2CK** : somme des `prelev_forfaitaire` (PFNL 12,8 % déjà retenu à la source par la plateforme) — c'est un crédit d'impôt.
- **2BH** : base CSG/CRDS (par défaut = intérêts bruts ; à ajuster selon votre situation).
- **Pertes en capital** : `montant_investi - capital_remboursé` pour les projets passés en `defaut` ou `cloture` dans l'année (`updated_at`). Vérifier l'éligibilité à l'imputation (CGI art. 125-00 A).

L'export CSV inclut le détail ligne par ligne, prêt à être joint à votre déclaration.

## Sécurité — TODO si déploiement public

- Forcer un `JWT_SECRET` long et aléatoire en prod.
- Ajouter HTTPS (reverse proxy Caddy/Traefik).
- Activer un CORS explicite (origin exacte).
- Ajouter une politique de rotation de tokens / refresh tokens.
- Sauvegarde régulière du volume `backend_data`.

## Licence

Privé / personnel.