Files

jpgiannetti 5e5fcf4714 refactor(docs): réorganiser la documentation selon principes DDD

Réorganise la documentation du projet selon les principes du Domain-Driven Design (DDD) pour améliorer la cohésion, la maintenabilité et l'alignement avec l'architecture modulaire du backend.

**Structure cible:**
```
docs/domains/
├── README.md (Context Map)
├── _shared/ (Core Domain)
├── recommendation/ (Supporting Subdomain)
├── content/ (Supporting Subdomain)
├── moderation/ (Supporting Subdomain)
├── advertising/ (Generic Subdomain)
├── premium/ (Generic Subdomain)
└── monetization/ (Generic Subdomain)
```

**Changements effectués:**

Phase 1: Création de l'arborescence des 7 bounded contexts
Phase 2: Déplacement des règles métier (01-19) vers domains/*/rules/
Phase 3: Déplacement des diagrammes d'entités vers domains/*/entities/
Phase 4: Déplacement des diagrammes flux/états/séquences vers domains/*/
Phase 5: Création des README.md pour chaque domaine
Phase 6: Déplacement des features Gherkin vers domains/*/features/
Phase 7: Création du Context Map (domains/README.md)
Phase 8: Mise à jour de mkdocs.yml pour la nouvelle navigation
Phase 9: Correction automatique des liens internes (script fix-markdown-links.sh)
Phase 10: Nettoyage de l'ancienne structure (regles-metier/, diagrammes/, features/)

**Configuration des tests:**
- Makefile: godog run docs/domains/*/features/
- scripts/generate-bdd-docs.py: features_dir → docs/domains

**Avantages:**
✅ Cohésion forte: toute la doc d'un domaine au même endroit
✅ Couplage faible: domaines indépendants, dépendances explicites
✅ Navigabilité améliorée: README par domaine = entrée claire
✅ Alignement code/docs: miroir de backend/internal/
✅ Onboarding facilité: exploration domaine par domaine
✅ Tests BDD intégrés: features au plus près des règles métier

Voir docs/REFACTOR-DDD.md pour le plan complet.

2026-02-07 17:15:02 +01:00

4.0 KiB

Raw Permalink Blame History

ADR-019 : Service de Géolocalisation par IP

Statut : Accepté Date : 2026-01-31

Contexte

RoadWave nécessite un service de géolocalisation par IP pour le mode dégradé (utilisateurs sans GPS activé). Ce service permet de détecter la ville/région de l'utilisateur à partir de son adresse IP et d'afficher du contenu régional même sans permission GPS.

Évolution du marché :

Avant 2019 : MaxMind GeoLite2 était téléchargeable gratuitement (base de données locale)
Depuis 2019 : MaxMind nécessite un compte + limite 1000 requêtes/jour (gratuit), puis 0.003$/requête au-delà

Usage RoadWave :

Mode dégradé : ~10% des utilisateurs (estimation)
Volume : 1000 utilisateurs × 10% = 100 requêtes/jour (MVP)
Critère : Aucune dépendance à un service tiers payant

Décision

IP2Location Lite DB (self-hosted) pour la géolocalisation par IP.

Alternatives considérées

Option	Coût/mois	Précision	Hébergement	Maintenance
IP2Location Lite	Gratuit	±50 km	Self-hosted	Mise à jour mensuelle
MaxMind GeoLite2 API	~10€ (dépassement)	±50 km	Cloud MaxMind	Nulle
Self-hosted MaxMind	Gratuit	±50 km	Self-hosted	Compte requis + MAJ

Justification

IP2Location Lite (choix retenu)

Avantages :

Gratuit (pas de limite de requêtes)
Self-hosted (souveraineté des données, cohérence avec ADR-004)
Base de données SQLite légère (50-100 MB)
Mise à jour mensuelle automatisable via cron
Licence permissive (Creative Commons BY-SA 4.0)
Pas de compte tiers requis

Inconvénients :

Maintenance mensuelle (mise à jour DB)
Précision équivalente à MaxMind (~±50 km)

MaxMind GeoLite2 API (rejeté)

Pourquoi rejeté :

Coût potentiel en cas de dépassement quota (risque faible mais existant)
Dépendance à un service tiers (perte de souveraineté)
Compte requis (friction opérationnelle)

Self-hosted MaxMind (rejeté)

Pourquoi rejeté :

Compte MaxMind obligatoire pour télécharger la DB (friction)
Complexité identique à IP2Location pour résultat équivalent
IP2Location offre même fonctionnalité sans compte tiers

Architecture technique

Composants

flowchart TD
    A[Backend Go<br/>API Handler]
    B[GeoIP Service<br/>Wrapper Go autour IP2Location]
    C[IP2Location DB<br/>SQLite ~50 MB<br/>Mise à jour mensuelle]

    A --> B
    B --> C

Flux de géolocalisation

Requête : API reçoit requête utilisateur sans GPS
Extraction IP : Lecture IP depuis en-têtes HTTP (X-Forwarded-For, X-Real-IP)
Lookup DB : Query SQLite IP2Location (index sur plages IP)
Réponse : Ville + région + code pays

Précision attendue : ±50 km (équivalent MaxMind)

Maintenance

Mise à jour mensuelle :

Cron job télécharge nouvelle DB IP2Location (1er du mois)
Backup DB actuelle avant remplacement
Rechargement service GeoIP (hot reload sans downtime)

Monitoring :

Alertes si DB > 60 jours (DB obsolète)
Logs requêtes "IP non trouvée" (détection problèmes DB)

Conséquences

Positives

Aucun coût récurrent (gratuit à l'infini)
Souveraineté complète des données (cohérence ADR-004)
Pas de dépendance externe (service tiers)
Latence minimale (lookup local SQLite < 1ms)

Négatives

Maintenance mensuelle requise (automatisable)
Précision limitée (±50 km, acceptable pour mode dégradé)
Taille base de données (~50-100 MB sur disque)

Risques atténués

DB obsolète : Alertes automatiques si > 60 jours
IP non trouvée : Fallback "France" par défaut (code pays FR)
Perte DB : Backup automatique avant chaque mise à jour

Références

ADR-004 : CDN (Souveraineté)
ADR-015 : Hébergement
Règle 02 : RGPD (Mode Dégradé)
IP2Location Lite : https://lite.ip2location.com/

4.0 KiB Raw Permalink Blame History Unescape Escape