petitspas/docs/24_DECISIONS-PROJET.md

# 📋 Décisions Projet - P'titsPas

**Version** : 1.0  
**Date** : 25 Novembre 2025  
**Auteur** : Équipe PtitsPas

---

## 🎯 Objectif de ce document

Ce document trace toutes les **décisions importantes** prises lors de la conception du projet P'titsPas. Il sert de référence pour comprendre les choix techniques et fonctionnels.

---

## 📊 Décisions Architecture

### 1. Mono-repo vs Multi-repo

**Décision** : ✅ **Mono-repo**

**Justification** :
- Code cohérent dans un seul dépôt Git
- Commits atomiques (frontend + backend + BDD en même temps)
- CI/CD simplifié (un seul webhook)
- Facilite le travail collaboratif

**Structure** :
```
ptitspas-app/
├── frontend/          # Application Flutter
├── backend/           # API NestJS
├── database/          # Migrations SQL/Prisma
├── api-contracts/     # Contrats OpenAPI + Prisma
├── docs/              # Documentation
└── docker-compose.yml # Orchestration
```

---

### 2. Déploiement On-Premise

**Décision** : ✅ **Application on-premise avec configuration dynamique**

**Justification** :
- Chaque collectivité a son infrastructure (SMTP, domaines, ports)
- Autonomie totale (pas de dépendance à notre infra)
- Conformité aux politiques IT locales
- Sécurité (données restent dans le SI de la collectivité)

**Solution technique** :
- Table `configuration` en BDD (clé/valeur)
- Setup Wizard à la première connexion
- Configuration SMTP dynamique
- Personnalisation (nom app, logo, URL)

**Référence** : [21_CONFIGURATION-SYSTEME.md](./21_CONFIGURATION-SYSTEME.md)

---

### 3. Gestion des fichiers uploadés

**Décision** : ✅ **Système de fichiers local avec volume Docker**

**Justification** :
- Simplicité (pas de S3/MinIO pour on-premise)
- Performance (accès direct au disque)
- Coût (pas de service externe)

**Solution technique** :
- Stockage dans `/uploads/photos/`
- Volume Docker persistant
- Service Upload avec Multer
- Validation taille (depuis config)

**Alternatives rejetées** :
- ❌ Base de données (BYTEA) : Mauvaise performance
- ❌ S3/MinIO : Overkill pour on-premise

---

### 4. Documents légaux (CGU/Privacy)

**Décision** : ✅ **Versioning automatique avec traçabilité RGPD**

**Justification** :
- Conformité juridique (preuve d'acceptation)
- Flexibilité (chaque collectivité adapte ses CGU)
- Traçabilité (hash SHA-256, IP, User-Agent)
- Sécurité juridique (pas de retour en arrière)

**Solution technique** :
- Table `documents_legaux` (versioning auto-incrémenté)
- Table `acceptations_documents` (traçabilité RGPD)
- Upload PDF par l'admin
- Activation manuelle après prévisualisation
- Documents génériques v1 fournis par défaut

**Référence** : [22_DOCUMENTS-LEGAUX.md](./22_DOCUMENTS-LEGAUX.md)

---

## 🔧 Décisions Fonctionnelles

### 5. Workflow inscription sans mot de passe

**Décision** : ✅ **Pas de mot de passe lors de l'inscription, lien email après validation**

**Justification** :
- Simplifie l'inscription (moins de friction)
- Adapté aux parents séparés/divorcés (communication difficile)
- Sécurité (token UUID avec expiration)
- Validation gestionnaire avant activation

**Workflow** :
1. Parent/AM s'inscrit (sans MDP)
2. Gestionnaire valide
3. Email envoyé avec lien création MDP (valable 7 jours)
4. Utilisateur crée son MDP
5. Compte activé

**Référence** : [20_WORKFLOW-CREATION-COMPTE.md](./20_WORKFLOW-CREATION-COMPTE.md)

---

### 6. Genre enfant obligatoire (H/F)

**Décision** : ✅ **Genre obligatoire (H/F uniquement)**

**Justification** :
- Contexte métier : Enfants à garder (pas de genre neutre)
- Conformité CDC
- Simplicité

**Implémentation** :
- Champ `genre` ENUM('H', 'F') NOT NULL dans table `enfants`

---

### 7. Suppression champs téléphone

**Décision** : ✅ **Un seul champ "Téléphone" (mobile privilégié)**

**Justification** :
- Simplification (plus besoin de "Mobile" et "Téléphone fixe")
- Réalité terrain : Tout le monde a un mobile
- Note dans l'interface : "(mobile privilégié)"

**Implémentation** :
- Supprimer `mobile` et `telephone_fixe`
- Garder uniquement `telephone`

---

### 8. NIR obligatoire pour Assistantes Maternelles

**Décision** : ✅ **NIR (Numéro de Sécurité sociale) obligatoire**

**Justification** :
- Conformité CDC
- Nécessaire pour génération automatique du contrat
- Stockage sécurisé (chiffrement recommandé)

**Implémentation** :
- Champ `nir_chiffre` VARCHAR(15) NOT NULL dans `assistantes_maternelles`
- Validation : 15 chiffres exactement
- Affichage masqué dans l'interface (XXX XX XX XX XXX 123)

---

### 9. Suppression notifications SMS

**Décision** : ✅ **Supprimer les notifications SMS, garder uniquement Email**

**Justification** :
- Pas de plus-value identifiée
- Coût supplémentaire (service SMS)
- Complexité (intégration Twilio/OVH)
- Email suffit largement

**Action** :
- Amender le CDC v1.4
- Remplacer "Email OU SMS" par "Email"
- Supprimer toute mention de SMS

**Référence** : Ticket #57

---

## 🚫 Décisions Phase 2 (reportées)

### 10. Gestion erreurs SMTP (renvoyer email)

**Décision** : ⏸️ **Phase 2 ou cas par cas**

**Justification** :
- Pas prioritaire pour MVP
- Downtime SMTP rare (< 24h)
- Recréation dossier acceptable en phase de test
- Peut être ajouté plus tard si besoin terrain

---

### 11. Sauvegarde & Restauration automatique

**Décision** : ⏸️ **Phase finale (quand tout fonctionne)**

**Justification** :
- Pas bloquant pour développement
- Nécessite application stable
- Script `pg_dump` simple à ajouter
- Documentation pour admins sys

**À faire** :
- Script `backup.sh` avec cron
- Guide sauvegarde/restauration
- Test restauration

---

### 12. RGPD avancé (droit à l'oubli, export données)

**Décision** : ⏸️ **Phase 2**

**Justification** :
- Conformité de base assurée (consentement, traçabilité)
- Droit à l'oubli : Peu de demandes en phase test
- Export données : Peut être fait manuellement en phase test

**À faire** :
- API suppression compte (soft delete)
- API export données personnelles (JSON)
- Anonymisation comptes inactifs

---

### 13. Statistiques dashboard

**Décision** : ⏸️ **Phase 2 (besoin d'utilisateurs d'abord)**

**Justification** :
- Pas de données = pas de statistiques
- Fonctionnalité importante pour vente
- Nécessite application en production

**À faire** :
- API statistiques (comptes, enfants, AM, validations)
- Widgets dashboard (graphiques)
- Export rapports

---

### 14. Migration de données

**Décision** : ❌ **Pas de migration prévue**

**Justification** :
- Pas de système existant à migrer
- Application nouvelle
- Import CSV peut être ajouté cas par cas si besoin

---

### 15. Documentation utilisateur

**Décision** : ⏸️ **Phase 2 (formation présentiel prioritaire)**

**Justification** :
- Premiers utilisateurs : Formation directe par l'équipe
- Documentation nécessaire pour scalabilité
- Vidéos tutoriels utiles mais pas bloquant

**À faire** :
- Guide utilisateur gestionnaire
- Guide utilisateur parent/AM
- FAQ
- Vidéos tutoriels

---

## 🔐 Décisions Sécurité

### 16. Chiffrement mots de passe configuration

**Décision** : ✅ **AES-256-CBC pour mots de passe SMTP**

**Justification** :
- Sécurité (mots de passe SMTP en clair = risque)
- Conformité sécurité
- Déchiffrement uniquement en mémoire

**Implémentation** :
- Type `encrypted` dans table `configuration`
- Clé de chiffrement dans `.env` (32 caractères)
- Service ConfigService gère chiffrement/déchiffrement

---

### 17. Hash mots de passe utilisateurs

**Décision** : ✅ **Bcrypt avec 12 rounds**

**Justification** :
- Standard industrie
- Résistant aux attaques brute-force
- Configurable (rounds dans config)

---

### 18. Tokens création mot de passe

**Décision** : ✅ **UUID avec expiration 7 jours**

**Justification** :
- Sécurité (UUID impossible à deviner)
- Expiration (limite fenêtre d'attaque)
- Durée configurable (dans table `configuration`)

---

### 19. JWT sessions

**Décision** : ✅ **JWT avec expiration 24h**

**Justification** :
- Stateless (pas de session en BDD)
- Performance (pas de lookup BDD à chaque requête)
- Durée configurable

---

## 📊 Décisions Base de Données

### 20. PostgreSQL vs autres SGBD

**Décision** : ✅ **PostgreSQL 17**

**Justification** :
- Open-source
- Robuste et performant
- Support JSON (flexibilité)
- Support UUID natif
- Communauté active

---

### 21. ORM : Prisma vs TypeORM

**Décision** : ✅ **Prisma** (mais TypeORM déjà en place)

**Justification Prisma** :
- Type-safety
- Migrations claires
- Génération client automatique

**Note** : Le projet YNOV utilise TypeORM. À évaluer si migration vers Prisma nécessaire.

---

### 22. Migrations versionnées

**Décision** : ✅ **Migrations SQL versionnées**

**Justification** :
- Traçabilité des changements schéma
- Rollback possible
- Déploiement automatisé

**Implémentation** :
- Fichiers `XX_nom_migration.sql`
- Exécution via `prisma migrate deploy`
- User `app_admin` pour DDL
- User `app_user` pour DML (runtime)

---

## 🧪 Décisions Tests

### 23. Stratégie de tests

**Décision** : ✅ **Tests unitaires + intégration + E2E**

**Justification** :
- Qualité code
- Confiance déploiement
- Détection régression

**Couverture cible** :
- Tests unitaires : > 80%
- Tests intégration : Workflows complets
- Tests E2E : Parcours utilisateurs critiques

---

## 📝 Décisions Documentation

### 24. Structure documentation

**Décision** : ✅ **Documentation centralisée dans `/docs/` avec numérotation**

**Justification** :
- Lisibilité (ordre logique)
- Maintenance (tout au même endroit)
- Versioning (Git)

**Structure** :
```
docs/
├── 00_INDEX.md
├── 01_CAHIER-DES-CHARGES.md
├── 02_ARCHITECTURE.md
├── 03_DEPLOYMENT.md
├── 10_DATABASE.md
├── 11_API.md
├── 20_WORKFLOW-CREATION-COMPTE.md
├── 21_CONFIGURATION-SYSTEME.md
├── 22_DOCUMENTS-LEGAUX.md
├── 23_LISTE-TICKETS.md
├── 24_DECISIONS-PROJET.md (ce document)
├── 90_AUDIT.md
└── test-data/
```

---

## 🔄 Décisions Workflow

### 25. Gitea + Webhook + Déploiement automatique

**Décision** : ✅ **Déploiement automatique sur push master**

**Justification** :
- Productivité (pas de déploiement manuel)
- Fiabilité (script testé)
- Rapidité (feedback immédiat)

**Workflow** :
1. Push sur `master`
2. Webhook Gitea déclenché
3. Script `deploy-ptitspas.sh` exécuté
4. Git pull + Migrations + Docker rebuild + Restart

---

### 26. Branches Git

**Décision** : ✅ **Stratégie simple : master + feature branches**

**Justification** :
- Simplicité (petite équipe)
- Flexibilité

**Branches** :
- `master` : Production
- `archive/*` : Archives (ex: maquette initiale)
- `migration/*` : Migrations (ex: intégration YNOV)
- `feature/*` : Nouvelles fonctionnalités

---

## 🎫 Décisions Ticketing

### 27. Taille des tickets

**Décision** : ✅ **Tickets relativement petits (2-6h)**

**Justification** :
- Granularité (suivi précis)
- Motivation (tickets terminables rapidement)
- Revue de code facilitée

---

### 28. Organisation tickets

**Décision** : ✅ **1 ticket = 1 fonctionnalité complète (Front + Back + BDD si nécessaire)**

**Justification** :
- Cohérence (toute la feature développée ensemble)
- Testable (end-to-end immédiatement)
- Atomique (livraison de valeur fonctionnelle)

**Alternative rejetée** :
- ❌ 1 ticket Front + 1 ticket Back + 1 ticket BDD = Dépendances complexes

---

## 🚀 Décisions Déploiement

### 29. Docker Compose vs Kubernetes

**Décision** : ✅ **Docker Compose**

**Justification** :
- Simplicité (on-premise petite/moyenne collectivité)
- Pas de besoin de scalabilité horizontale
- Maintenance facile

**Alternative rejetée** :
- ❌ Kubernetes : Overkill pour on-premise mono-instance

---

### 30. Traefik comme reverse proxy

**Décision** : ✅ **Traefik**

**Justification** :
- Configuration automatique (labels Docker)
- SSL Let's Encrypt automatique
- Dashboard intégré

---

## 📊 Logs & Monitoring

### 31. Système de logs

**Décision** : ✅ **Winston avec rotation quotidienne**

**Justification** :
- Standard NestJS
- Rotation automatique (pas de disque plein)
- Niveaux de log (info, warn, error)
- Transports multiples (console + fichier)

**Logs à capturer** :
- Logs applicatifs (info, warn, error)
- Logs emails (succès/échec SMTP)
- Logs connexions (qui se connecte quand)
- Logs validations (qui valide quoi)

---

## 📋 Résumé des décisions critiques

| # | Décision | Statut | Impact |
|---|----------|--------|--------|
| 1 | Mono-repo | ✅ Phase 1 | Architecture |
| 2 | On-premise avec config dynamique | ✅ Phase 1 | Déploiement |
| 3 | Système de fichiers pour uploads | ✅ Phase 1 | Stockage |
| 4 | Versioning documents légaux | ✅ Phase 1 | RGPD |
| 5 | Inscription sans MDP | ✅ Phase 1 | UX |
| 6 | Genre enfant obligatoire (H/F) | ✅ Phase 1 | Métier |
| 7 | Un seul champ téléphone | ✅ Phase 1 | Simplification |
| 8 | NIR obligatoire AM | ✅ Phase 1 | Conformité |
| 9 | Suppression SMS | ✅ Phase 1 | Simplification |
| 10 | Renvoyer email | ⏸️ Phase 2 | Nice-to-have |
| 11 | Sauvegarde auto | ⏸️ Phase finale | Ops |
| 12 | RGPD avancé | ⏸️ Phase 2 | Conformité |
| 13 | Statistiques | ⏸️ Phase 2 | Business |
| 14 | Migration données | ❌ Rejeté | N/A |
| 15 | Doc utilisateur | ⏸️ Phase 2 | Formation |
| 31 | Logs Winston | ✅ Phase 1 | Monitoring |

---

## 🔄 Historique des modifications

| Date | Version | Modifications |
|------|---------|---------------|
| 25/11/2025 | 1.0 | Création du document - Toutes les décisions initiales |

---

**Dernière mise à jour** : 25 Novembre 2025  
**Version** : 1.0  
**Statut** : ✅ Document validé