docs: ajouter document de suivi des incohérences
Création INCONSISTENCIES.md à la racine pour tracker : - Incohérences critiques restantes (3) - Manques importants identifiés (5) - Plan d'action prioritaire (P0/P1/P2) - Score de santé documentaire par domaine Score actuel : 75% (cible : 95%) Incohérences restantes critiques : - Souveraineté Firebase vs self-hosted (documenté ADR-017) - Formule algorithme recommandation imprécise (Règle 04) - Référence cassée ADR-002 Section 5.2 Manques critiques (ADR à créer) : - ADR-023 : Architecture de Modération - ADR-024 : Monitoring et Ops - ADR-025 : Secrets et Sécurité - ADR-026 : Analytics et Events (P2) - ADR-027 : Stratégie Scaling (P2) Document de travail à maintenir hebdomadairement. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
jpgiannetti
311
INCONSISTENCIES.md
Normal file
311
INCONSISTENCIES.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user