jpgiannetti/roadwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(bdd): réorganiser features en catégories api/ui/e2e et créer ADR-024

Browse Source 
Résolution des incohérences #10, #11, et #12 de l'analyse d'architecture.

## Phase 1 : Réorganisation Features BDD (Point #10 - RÉSOLU)

- Créer structure features/{api,ui,e2e}
- Déplacer 83 features en 3 catégories via git mv (historique préservé)
  - features/api/ : 53 features (tests API backend)
  - features/ui/ : 22 features (tests UI mobile)
  - features/e2e/ : 8 features (tests end-to-end)

Domaines déplacés :
- API : authentication, recommendation, rgpd-compliance, content-creation,
  moderation, monetisation, premium, radio-live, publicites
- UI : audio-guides, navigation, interest-gauges, mode-offline,
  partage, profil, recherche
- E2E : abonnements, error-handling

## Phase 2 : Mise à jour Documentation

### ADR-007 - Tests BDD
- Ajouter section "Convention de Catégorisation des Features"
- Documenter règles api/ui/e2e avec exemples concrets
- Spécifier step definitions (backend Go, mobile Dart)

### ADR-024 - Stratégie CI/CD Monorepo (NOUVEAU)
- Créer ADR dédié pour stratégie CI/CD avec path filters
- Architecture workflows séparés (backend.yml, mobile.yml, shared.yml)
- Configuration path filters détaillée avec exemples YAML
- Matrice de déclenchement et optimisations (~70% gain temps CI)
- Plan d'implémentation (~2h, reporté jusqu'au développement)

### ADR-016 - Organisation Monorepo
- Simplifier en retirant section CI/CD détaillée
- Ajouter référence vers ADR-024 pour stratégie CI/CD

### INCONSISTENCIES-ANALYSIS.md
- Point #10 (Tests BDD synchronisés) : ✅ RÉSOLU
  - Catégorisation features implémentée
  - ADR-007 mis à jour avec convention complète
- Point #11 (70/30 Split paiements) : ✅ ANNULÉ (faux problème)
  - ADR-009 et Règle 18 parfaitement cohérents
  - Documentation exhaustive existante (formule, SQL, comparaisons)
- Point #12 (Monorepo path filters) : ⏸️ DOCUMENTÉ
  - Architecture CI/CD complète dans ADR-024
  - Implémentation reportée (projet en phase documentation)
- Métriques mises à jour :
  - MODERATE : 6/9 traités (4 résolus + 1 annulé + 1 documenté)
  - ADR à jour : 100% (19/19 avec ADR-024)

## Phase 3 : Validation

- Structure features validée (api/ui/e2e, aucun répertoire restant)
- Historique Git préservé (git mv, renommages détectés)
- 83 features total (API: 53, UI: 22, E2E: 8)

Closes: Point #10 (résolu), Point #11 (annulé), Point #12 (documenté)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
jpgiannetti
2026-02-01 11:31:41 +01:00
parent 841028d1b2
commit 37c62206ad
88 changed files with 625 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

412
docs/adr/024-strategie-cicd-monorepo.md Normal file
View File

@@ -0,0 +1,412 @@
# ADR-024 : Stratégie CI/CD avec Path Filters pour Monorepo
**Statut** : Accepté (non implémenté)
**Date** : 2026-02-01
## Contexte
RoadWave est organisé en monorepo contenant backend Go, mobile Flutter, documentation et features BDD ([ADR-016](016-organisation-monorepo.md)). Sans optimisation, chaque commit déclencherait **tous** les builds (backend + mobile + docs), même si seul un composant a changé.
**Problématique** :
- ❌ Temps de CI/CD inutilement longs (rebuild complet ~15 min)
- ❌ Gaspillage de ressources GitHub Actions
- ❌ Ralentissement du feedback développeur
- ❌ Coûts CI/CD élevés pour changements isolés
**Exemple** : Modification d'un fichier markdown dans `/docs` déclenche les tests backend (5 min) + tests mobile (8 min) + build (2 min) alors que seule la validation docs (~30s) est nécessaire.
## Décision
**Workflows GitHub Actions séparés** avec **path filters** pour rebuild sélectif basé sur les fichiers modifiés.
## Alternatives considérées
| Option | Optimisation | Complexité | Maintenance | Coût CI |
|--------|--------------|------------|-------------|---------|
| **Workflows séparés + path filters** | Excellente (~70%) | Faible | Simple | Minimal |
| Workflow monolithique | Nulle | Très faible | Simple | Élevé |
| Turborepo/Nx orchestration | Bonne (~50%) | Élevée | Complexe | Moyen |
| Multirepo (repos séparés) | Excellente | Élevée | Complexe | Variable |
## Architecture
### Structure Workflows
```
.github/workflows/
├── backend.yml # Backend Go (tests, lint, build)
├── mobile.yml # Mobile Flutter (tests, lint, build)
└── shared.yml # Docs + code partagé (validation, génération)
```
### Configuration Path Filters
#### Workflow Backend (`backend.yml`)
```yaml
name: Backend CI
on:
push:
branches: [main, develop]
paths:
- 'backend/**' # Code Go modifié
- 'features/api/**' # Tests API modifiés
- 'features/e2e/**' # Tests E2E (impliquent backend)
- '.github/workflows/backend.yml'
pull_request:
branches: [main, develop]
paths:
- 'backend/**'
- 'features/api/**'
- 'features/e2e/**'
jobs:
test-unit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.21'
- run: cd backend && go test ./...
test-integration:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.21'
- run: cd backend && make test-integration
test-bdd:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.21'
- run: |
go install github.com/cucumber/godog/cmd/godog@latest
godog run features/api/ features/e2e/
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: golangci/golangci-lint-action@v4
build:
runs-on: ubuntu-latest
needs: [test-unit, test-integration, test-bdd, lint]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.21'
- run: cd backend && make build
```
**Déclenché par** :
- Modifications dans `/backend` (code Go, migrations, config)
- Nouvelles features API dans `/features/api`
- Tests end-to-end dans `/features/e2e` (backend impliqué)
---
#### Workflow Mobile (`mobile.yml`)
```yaml
name: Mobile CI
on:
push:
branches: [main, develop]
paths:
- 'mobile/**' # Code Flutter modifié
- 'features/ui/**' # Tests UI modifiés
- 'features/e2e/**' # Tests E2E (impliquent mobile)
- '.github/workflows/mobile.yml'
pull_request:
branches: [main, develop]
paths:
- 'mobile/**'
- 'features/ui/**'
- 'features/e2e/**'
jobs:
test-unit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.16.0'
- run: cd mobile && flutter test
test-integration:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.16.0'
- run: cd mobile && flutter test integration_test/
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.16.0'
- run: cd mobile && flutter analyze
build-android:
runs-on: ubuntu-latest
needs: [test-unit, test-integration, lint]
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.16.0'
- run: cd mobile && flutter build apk --release
build-ios:
runs-on: macos-latest
needs: [test-unit, test-integration, lint]
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.16.0'
- run: cd mobile && flutter build ios --release --no-codesign
```
**Déclenché par** :
- Modifications dans `/mobile` (code Flutter/Dart, assets, config)
- Nouvelles features UI dans `/features/ui`
- Tests end-to-end dans `/features/e2e` (mobile impliqué)
---
#### Workflow Shared (`shared.yml`)
```yaml
name: Shared CI
on:
push:
branches: [main, develop]
paths:
- 'docs/**' # Documentation modifiée
- 'shared/**' # Code partagé modifié
- '.github/workflows/shared.yml'
pull_request:
branches: [main, develop]
paths:
- 'docs/**'
- 'shared/**'
jobs:
docs-validation:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: |
pip install mkdocs mkdocs-material
mkdocs build --strict
docs-links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lycheeverse/lychee-action@v1
with:
args: 'docs/**/*.md'
shared-tests:
runs-on: ubuntu-latest
if: contains(github.event.head_commit.modified, 'shared/')
steps:
- uses: actions/checkout@v4
# Tests pour code partagé si nécessaire
```
**Déclenché par** :
- Modifications dans `/docs` (ADR, règles métier, documentation technique)
- Modifications dans `/shared` (contrats API, types partagés)
---
### Matrice de Déclenchement
| Modification | Backend | Mobile | Shared | Temps total |
|-------------|---------|--------|--------|-------------|
| `backend/internal/auth/service.go` | ✅ | ❌ | ❌ | ~5 min |
| `mobile/lib/screens/home.dart` | ❌ | ✅ | ❌ | ~8 min |
| `features/api/authentication/*.feature` | ✅ | ❌ | ❌ | ~5 min |
| `features/ui/audio-guides/*.feature` | ❌ | ✅ | ❌ | ~8 min |
| `features/e2e/abonnements/*.feature` | ✅ | ✅ | ❌ | ~13 min (parallèle) |
| `docs/adr/018-email.md` | ❌ | ❌ | ✅ | ~30s |
| **Commit mixte (backend + mobile + docs)** | ✅ | ✅ | ✅ | ~13 min (parallèle) |
**Économie de temps** :
- Commit backend-only : ~5 min (vs 15 min sans path filters) = **67% plus rapide**
- Commit docs-only : ~30s (vs 15 min) = **97% plus rapide**
### Cas Particulier : Features E2E
Les tests end-to-end dans `/features/e2e/` **déclenchent les deux workflows** (backend ET mobile) car ils testent l'intégration complète :
**Exemples de features E2E** :
- `features/e2e/abonnements/` : Formulaire mobile → API Zitadel → API RoadWave → Mangopay → Confirmation UI
- `features/e2e/error-handling/` : Perte réseau → Fallback mode offline → Reprise auto après reconnexion
**Justification** : Les features E2E valident le contrat backend-mobile, donc les deux doivent être testés.
---
## Justification
### Avantages
✅ **Rebuild sélectif** : changement backend → seulement backend rebuild (~5 min au lieu de 15 min)
✅ **Économie de temps CI** : ~70% de réduction sur commits isolés (backend-only ou mobile-only)
✅ **Économie de coûts** : GitHub Actions facturé à la minute → réduction proportionnelle des coûts
✅ **Parallélisation** : workflows indépendants exécutés en parallèle par GitHub Actions
✅ **Features E2E** : déclenchent backend ET mobile → cohérence end-to-end garantie
✅ **Feedback rapide** : développeur backend voit uniquement résultats backend (moins de bruit)
✅ **Scalabilité** : ajout de nouveaux composants (admin panel, worker, etc.) = nouveau workflow isolé
### Inconvénients
❌ **Duplication config** : certains éléments (checkout, cache) dupliqués entre workflows
❌ **Maintenance** : 3 workflows à maintenir au lieu de 1
❌ **Complexité initiale** : setup plus complexe que workflow monolithique
**Mitigation** :
- Utiliser des **composite actions** pour partager la config commune
- Documentation claire dans ce ADR
- Coût initial faible (~2h setup) vs gains à long terme importants
---
## Implémentation
### Prérequis
- ✅ Code backend implémenté avec tests unitaires + intégration
- ✅ Code mobile implémenté avec tests Flutter
- ✅ Step definitions BDD implémentées pour `api/`, `ui/`, `e2e/`
- ✅ Catégorisation features BDD en `/features/{api,ui,e2e}` ([ADR-007](007-tests-bdd.md))
### Plan d'Implémentation
**Phase 1** : Setup workflows de base (~1h)
- Créer `backend.yml` avec jobs test + lint + build
- Créer `mobile.yml` avec jobs test + lint + build
- Créer `shared.yml` avec validation docs
**Phase 2** : Configuration path filters (~30 min)
- Ajouter `paths:` à chaque workflow
- Tester avec commits isolés (backend-only, mobile-only, docs-only)
**Phase 3** : Optimisations (~30 min)
- Ajouter caching (Go modules, Flutter dependencies, node_modules)
- Créer composite actions pour config partagée
- Ajouter badges status dans README
**Effort total estimé** : ~2h
### Validation
```bash
# Test 1 : Commit backend-only
git add backend/
git commit -m "test: backend change"
git push
# → Vérifier que SEULEMENT backend.yml s'exécute
# Test 2 : Commit mobile-only
git add mobile/
git commit -m "test: mobile change"
git push
# → Vérifier que SEULEMENT mobile.yml s'exécute
# Test 3 : Commit E2E
git add features/e2e/
git commit -m "test: e2e change"
git push
# → Vérifier que backend.yml ET mobile.yml s'exécutent
# Test 4 : Commit docs-only
git add docs/
git commit -m "docs: update ADR"
git push
# → Vérifier que SEULEMENT shared.yml s'exécute
```
---
## Conséquences
### Positives
- **Productivité développeur** : feedback 3x plus rapide sur commits isolés
- **Coûts réduits** : ~70% d'économie sur minutes GitHub Actions
- **Meilleure expérience PR** : reviews plus rapides, moins d'attente CI
- **Scalabilité** : facile d'ajouter nouveaux composants (worker, admin, etc.)
### Négatives
- **Maintenance** : 3 workflows à maintenir vs 1
- **Setup initial** : ~2h vs ~30 min pour workflow simple
- **Complexité** : nécessite compréhension path filters GitHub Actions
### Risques
⚠️ **Faux négatifs** : path filter mal configuré → test non exécuté → bug en production
**Mitigation** :
- Features E2E déclenchent toujours backend + mobile (safety net)
- Tests de validation dans le plan d'implémentation
- Review obligatoire des modifications de workflows
---
## Références
- [ADR-007 - Tests BDD et Catégorisation Features](007-tests-bdd.md)
- [ADR-016 - Organisation Monorepo](016-organisation-monorepo.md)
- [GitHub Actions - Path Filters](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
- [Monorepo CI/CD Best Practices](https://monorepo.tools/#ci-cd)
---
## Statut d'Implémentation
**Actuel** : **Documenté mais non implémenté**
**Quand** : Lors du Sprint d'implémentation backend/mobile (code production)
**Pourquoi reporté** : Le projet est actuellement en phase de documentation uniquement. Aucun code backend/mobile n'est implémenté, donc pas de tests à exécuter. L'implémentation CI/CD sera faite lors du développement.
**Prochaines étapes** :
1. Implémenter code backend avec tests
2. Implémenter code mobile avec tests
3. Implémenter step definitions BDD
4. Créer workflows CI/CD selon ce ADR
5. Valider avec commits de test