5e5fcf4714
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.
119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# 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](004-cdn.md))
|
||
- 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
|
||
|
||
```mermaid
|
||
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
|
||
|
||
1. **Requête** : API reçoit requête utilisateur sans GPS
|
||
2. **Extraction IP** : Lecture IP depuis en-têtes HTTP (`X-Forwarded-For`, `X-Real-IP`)
|
||
3. **Lookup DB** : Query SQLite IP2Location (index sur plages IP)
|
||
4. **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é)](004-cdn.md)
|
||
- [ADR-015 : Hébergement](015-hebergement.md)
|
||
- [Règle 02 : RGPD (Mode Dégradé)](../domains/_shared/rules/rgpd.md#136-géolocalisation-optionnelle)
|
||
- IP2Location Lite : https://lite.ip2location.com/
|