diff --git a/INCONSISTENCIES.md b/INCONSISTENCIES.md new file mode 100644 index 0000000..62dc9da --- /dev/null +++ b/INCONSISTENCIES.md @@ -0,0 +1,311 @@ +# Incohérences et Manques - RoadWave + +> **Statut** : Document de travail +> **Dernière mise à jour** : 2026-02-01 +> **Score de santé documentaire** : 75% (après corrections récentes) + +Ce document liste les incohérences et manques critiques identifiés dans la documentation technique (ADR + Règles Métier) du projet RoadWave. + +--- + +## ✅ Incohérences récemment corrigées + +- **✅ Références ADR dans CLAUDE.md** : Décalage -2 corrigé (commit `c3abdd7`) +- **✅ Geofencing MVP vs Phase 2** : ADR-020 clarifié avec séparation Phase 1/Phase 2 (commit `69a7bd8`) + +--- + +## 🔴 Incohérences critiques restantes + +### 1. Souveraineté données : Firebase vs Self-hosted + +**Conflit** : +- [ADR-008](docs/adr/008-authentification.md) : "100% self-hosted, souveraineté France" +- [ADR-015](docs/adr/015-hebergement.md) : "OVH France, aucune dépendance US" +- **MAIS** [ADR-017](docs/adr/017-notifications-geolocalisees.md) : Firebase Cloud Messaging = **Google Cloud** + +**Détails** : +- Les tokens FCM sont stockés chez Google (hors EU) +- Nécessite Data Processing Agreement (DPA) Google +- Contradictoire avec la promesse de souveraineté + +**Statut ADR-017** : ✅ Incohérence **documentée et assumée** avec mitigation : +- Abstraction layer `NotificationProvider` pour faciliter migration +- Exit path vers solution custom < 1 sprint +- Probabilité de changement : faible (gratuit, fiable) + +**Action requise** : Valider DPA Google avec DPO avant production. + +--- + +### 2. Algorithme de recommandation : Formule imprécise + +**Problème** : [Règle 04](docs/regles-metier/04-algorithme-recommandation.md):37 +``` +score_interets = moyenne des jauges utilisateur pour les tags du contenu +``` + +**Incohérences** : +- Les jauges sont stockées en pourcentage [0-100] +- Le score final doit être [0-1] pour la pondération +- Formule exacte manquante : `SUM(gauges) / NB_TAGS / 100` ? +- Aucun exemple concret avec nombres réels + +**Impact** : L'équipe backend ne saura pas comment implémenter le scoring exact. + +**Action requise** : +```markdown +## 2.2 Calcul score_interets (à ajouter dans Règle 04) + +**Formule exacte** : +score_interets ∈ [0.0, 1.0] = (SUM(gauge_values) / NB_TAGS) / 100 + +**Exemple concret** : +Contenu : tags ["Musique", "Tourisme"] +Utilisateur : jauge Musique = 75%, jauge Tourisme = 60% + +score_interets = ((75 + 60) / 2) / 100 = 67.5 / 100 = 0.675 + +**Impact dans le scoring final** : +score_final = 0.5 * score_geo + 0.3 * score_interets + 0.2 * score_engagement + = 0.5 * 0.8 + 0.3 * 0.675 + 0.2 * 0.5 + = 0.4 + 0.2025 + 0.1 + = 0.7025 / 1.0 +``` + +--- + +### 3. Référence cassée dans ADR-002 + +**Problème** : [ADR-002](docs/adr/002-protocole-streaming.md):180 +``` +Règle Métier 05 : Section 5.2 (Mode Voiture, lignes 16-84) +``` + +**Réalité** : [Règle 05](docs/regles-metier/05-interactions-navigation.md) ne contient pas de "Section 5.2". La structure réelle est : +- Section 5.1 : File d'attente et commande Suivant +- Section 5.2 n'existe pas + +**Action requise** : Corriger ADR-002 ligne 180 +```diff +- Règle Métier 05 : Section 5.2 (Mode Voiture, lignes 16-84) ++ Règle Métier 05 : Section 5.1 (File d'attente, lignes 16-84) +``` + +--- + +## ⚠️ Manques critiques + +### 1. Architecture de modération non documentée + +**État actuel** : +- [Règle 14-15](docs/regles-metier/14-moderation-flows.md) : décrivent les flux métier +- **AUCUN ADR** ne couvre l'architecture technique + +**Manque** : +- Comment l'IA pré-filtre fonctionne (Whisper + NLP) ? +- Quelle architecture de queue (PostgreSQL, Redis, RabbitMQ) ? +- Stack technique des modérateurs (dashboard) ? +- API endpoints pour signalement ? +- Workflow de traitement (automatique vs manuel) ? + +**Impact** : 3-4 semaines de surprise en développement, pas de consensus technique. + +**Action recommandée** : Créer **ADR-023 : Architecture de Modération** +```markdown +Contenu suggéré : +- Architecture queue signalements (PostgreSQL LISTEN/NOTIFY) +- Intégration Whisper API (transcription audio) +- ML pré-filtrage (OpenAI Moderation API ou modèle local) +- Dashboard modérateurs (interface web) +- Workflow et SLA (24h critique, 72h standard) +- Métriques et observabilité +``` + +--- + +### 2. Monitoring et Ops absents + +**État actuel** : +- [ADR-015](docs/adr/015-hebergement.md) : mentionne OVH VPS +- **AUCUN ADR** sur monitoring, alerting, incident response + +**Manque** : +- Stack de monitoring (Grafana + Prometheus ?) +- Alerting (PagerDuty, Slack, email ?) +- Incident runbooks (crash, data loss, breach) +- Backup/Disaster Recovery strategy +- SLO/SLA définition (99.9% availability = combien downtime ?) +- Performance metrics (p99 latency, throughput) + +**Impact** : Équipe ops sera perdue le jour du lancement production. + +**Action recommandée** : Créer **ADR-024 : Monitoring, Observabilité et Incident Response** +```markdown +Contenu suggéré : +- Stack monitoring (Prometheus + Grafana self-hosted) +- Alerting rules (latency p99 > 100ms, error rate > 1%) +- Incident response workflow (on-call rotation, escalation) +- Runbook templates (database down, API crash, high load) +- Backup strategy (PostgreSQL WAL-E, 7 jours retention) +- Disaster Recovery (RTO/RPO : 1h / 15min) +``` + +--- + +### 3. Gestion des secrets non documentée + +**État actuel** : +- Aucun ADR ne couvre la gestion des secrets + +**Manque** : +- Où stocker secrets production (Mangopay credentials, DB password, JWT signing key) ? +- Solution : Vault self-hosted ? Kubernetes secrets ? Variables d'environnement ? +- Rotation des secrets (fréquence, automatisation) ? +- Field-level encryption PII (GPS coordinates, emails, phone numbers) ? +- OWASP Top 10 checklist (injection, CSRF, XSS) ? + +**Impact** : Secrets en plaintext dans env vars = faille de sécurité critique. + +**Action recommandée** : Créer **ADR-025 : Sécurité - Secrets et Encryption** +```markdown +Contenu suggéré : +- Secrets management (HashiCorp Vault self-hosted vs managed) +- Field-level encryption (AES-256-GCM pour PII sensibles) +- HTTPS/TLS configuration (Let's Encrypt automatique) +- CORS/CSRF protection (middleware Fiber) +- API rate limiting (token bucket, 100 req/min/user) +- OWASP Top 10 mitigation checklist +``` + +--- + +### 4. Analytics et events tracking flous + +**État actuel** : +- [Règle 02](docs/regles-metier/02-conformite-rgpd.md):13.7 : "Matomo self-hosted" +- Aucun détail sur les events à tracer + +**Manque** : +- Quels events tracer (play, pause, like, skip, duration, GPS updates) ? +- Schéma JSON des events (format standardisé) ? +- Dashboard principales métriques (DAU, WAU, engagement, churn) ? +- Funnel analytics (signup → première écoute → monétisation) ? +- Retention cohort analysis ? + +**Impact** : Analytics sera chaos, équipe produit ne saura pas quoi mesurer. + +**Action recommandée** : Créer **ADR-026 : Analytics et Métriques Produit** +```markdown +Contenu suggéré : +- Events à tracer (JSON Schema pour validation) +- Matomo setup (Docker self-hosted, data retention 90j) +- Dashboard KPI (DAU, WAU, engagement rate, churn by cohort) +- Funnel metrics (signup → content discovery → monetization) +- Privacy-preserving analytics (IP anonymization, no cookies tiers) +``` + +--- + +### 5. Stratégie de scaling Post-MVP absente + +**État actuel** : +- [ADR-015](docs/adr/015-hebergement.md) : "Phase 2 à 20K users = Scaleway managé" +- Aucun détail sur comment scaler + +**Manque** : +- Database sharding strategy (par user_id ? par région géographique ?) ? +- Cache invalidation at scale (comment éviter cache stampede) ? +- Load balancing multi-région (GeoDNS pour latence optimale) ? +- API rate limiting global (par IP, par user, quotas) ? +- CDN multi-région (Cloudflare ? BunnyCDN ?) ? + +**Impact** : Architecture ne tiendra pas à 100K+ users sans refonte complète. + +**Action recommandée** : Créer **ADR-027 : Stratégie de Scaling 20K-500K Users** +```markdown +Contenu suggéré : +- Database partitioning (sharding horizontal par région EU) +- Cache strategy (locality-aware, TTL adaptatif, invalidation patterns) +- Load balancing (Nginx + health checks, failover automatique) +- API rate limiting (Redis + token bucket, quotas différenciés free/premium) +- Multi-région CDN (Bunny CDN pour souveraineté EU) +``` + +--- + +## 📊 Évaluation par domaine + +| Domaine | Score | Verdict | Manques principaux | +|---------|-------|---------|-------------------| +| **Géolocalisation** | 90% | ✅ Excellent | - | +| **Authentification** | 85% | ✅ Bon | Glossaire OAuth2 PKCE | +| **Streaming Audio** | 80% | ✅ Bon | Détails pre-buffering | +| **Mobile & Permissions** | 80% | ✅ Bon | - (corrigé ✅) | +| **Paiements** | 80% | ✅ Bon | Multi-devise taux change | +| **Modération** | 20% | ❌ Insuffisant | **ADR-023 requis** | +| **Ops & Monitoring** | 30% | ❌ Insuffisant | **ADR-024 requis** | +| **Sécurité** | 40% | ⚠️ Minimal | **ADR-025 requis** | +| **Analytics** | 35% | ⚠️ Minimal | **ADR-026 recommandé** | +| **Scaling** | 40% | ⚠️ Minimal | **ADR-027 recommandé** | +| **Testing** | 85% | ✅ Bon | - | + +**Score global** : **75%** (après corrections récentes, était 70%) + +--- + +## 🎯 Plan d'action prioritaire + +### P0 - Bloquant implémentation (à faire AVANT coding) + +1. **✅ FAIT** : Corriger références ADR dans CLAUDE.md +2. **✅ FAIT** : Clarifier geofencing Phase 1/Phase 2 dans ADR-020 +3. **🔴 TODO** : Préciser formule algorithme recommandation (Règle 04) + - Ajouter section "2.2 Calcul score_interets" avec exemple chiffré + - Domaine jauges : 0-100, score final : 0-1 +4. **🔴 TODO** : Corriger référence cassée ADR-002 (Section 5.2 → 5.1) + +### P1 - Important design (avant Sprint 3-4) + +5. **🔴 TODO** : Créer **ADR-023 : Architecture de Modération** + - Queue signalements, workflow IA, dashboard modérateurs +6. **🔴 TODO** : Créer **ADR-024 : Monitoring et Ops** + - Prometheus + Grafana, alerting, runbooks, backup/DR +7. **🔴 TODO** : Créer **ADR-025 : Secrets et Sécurité** + - Vault, encryption PII, OWASP Top 10 checklist + +### P2 - Nice-to-have (avant Sprint 6-8) + +8. **🟡 TODO** : Créer **ADR-026 : Analytics et Events** + - JSON Schema events, dashboard KPI, funnel metrics +9. **🟡 TODO** : Créer **ADR-027 : Stratégie Scaling** + - Sharding DB, cache invalidation, load balancing multi-région +10. **🟡 TODO** : Ajouter glossaire dans CLAUDE.md + - OAuth2 PKCE vs Providers + - MVP vs Phase 2 vs Post-MVP + - Cache strategies (hot/cold, TTL) + +--- + +## 📈 Objectif cible + +**Score santé documentaire cible** : **95%** avant démarrage Sprint 3 + +**Actions minimales requises** : +- ✅ Corriger 2 incohérences critiques (P0) +- ✅ Créer 3 ADR manquants (P1 : Modération, Ops, Sécurité) +- 🎯 Atteindre score 95% dans tous les domaines critiques + +**Deadline recommandée** : 2 semaines avant démarrage développement backend/mobile + +--- + +## 🔄 Maintenance de ce document + +Ce document doit être mis à jour à chaque : +- Correction d'incohérence identifiée +- Création d'un nouvel ADR comblant un manque +- Identification d'une nouvelle incohérence + +**Responsable** : Tech Lead / Architecte +**Fréquence de revue** : Hebdomadaire pendant phase documentation, mensuelle ensuite