diff --git a/CLAUDE.md b/CLAUDE.md index 8decbd5f3..a397821e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,462 +1,463 @@ -# CLAUDE.md — Instructions Maître pour l'Agent Autonome Veza +# CLAUDE.md — Instructions pour agents autonomes sur le projet Veza > **Ce fichier est le system prompt de Claude Code pour le projet Veza.** -> Placez-le à la racine du repo. Claude Code le lira automatiquement. +> Il est lu automatiquement à chaque session. > -> **Usage** : `claude "implémente la prochaine version"` — c'est tout. +> **Dernière mise à jour** : 2026-04-14 (v1.0.4, post-audit). +> Les versions antérieures du fichier référençaient `backend/`, `frontend/`, `ORIGIN/` et un chat server Rust qui **n'existent plus ou n'ont jamais existé à ces emplacements**. Voir §Historique à la fin. --- -## 🎯 IDENTITÉ ET MISSION +## 🎯 Identité -Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en totale autonomie. Quand on te dit "implémente la prochaine version", tu exécutes le cycle complet sans intervention humaine. +Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en autonomie sur un monorepo qui mélange Go, Rust et TypeScript. Tu es expert en : -- **Go** (backend API, architecture hexagonale, middlewares, handlers) -- **Rust** (stream server, performance, safety) -- **TypeScript/React** (frontend, design system SUMI, accessibilité) -- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infrastructure) -- **Docker, CI/CD GitHub Actions** (DevOps) + +- **Go** (backend API — Gin, GORM, hexagonal-ish) +- **Rust** (stream server — Axum, Tokio, Symphonia) +- **TypeScript/React** (frontend — Vite 5, React 18, Zustand, React Query) +- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infra) +- **Docker, GitHub Actions / Forgejo Actions** (DevOps) --- -## 📋 PROTOCOLE D'EXÉCUTION — "IMPLÉMENTE LA PROCHAINE VERSION" +## 🏗️ Architecture réelle du repo (à jour 2026-04-14) -À chaque invocation, exécute ces étapes **dans l'ordre exact** : - -### ÉTAPE 0 — ORIENTATION (30 secondes) -```bash -# Comprendre l'état actuel du repo -git status -git log --oneline -5 -cat VEZA_VERSIONS_ROADMAP.md | head -50 +``` +veza/ +├── apps/ +│ └── web/ # Frontend React 18 + Vite 5 + TypeScript strict +│ ├── src/ +│ │ ├── components/ # UI + design system (~145 composants) +│ │ ├── features/ # Modules métier (auth, library, player, chat, live, ...) +│ │ ├── pages/ # Entry points de routes +│ │ ├── router/ # routeConfig.tsx +│ │ ├── services/api/ # Client Axios + services REST +│ │ ├── stores/ # Zustand (auth, library, chat, cart, UI) +│ │ ├── hooks/ +│ │ └── types/ # Types TS (+ generated/ depuis OpenAPI) +│ ├── tsconfig.json # strict + noUncheckedIndexedAccess +│ ├── vite.config.ts +│ └── package.json +│ +├── veza-backend-api/ # Backend Go 1.25 + Gin +│ ├── cmd/ +│ │ ├── api/main.go # Serveur principal +│ │ ├── migrate_tool/ # Runner de migrations +│ │ ├── backup/ # Gestion backups +│ │ ├── generate-config-docs/ +│ │ └── tools/ # seed, hash_gen, create_test_user, encrypt_oauth_tokens +│ ├── internal/ +│ │ ├── api/ # router.go + routes_*.go (28 fichiers) +│ │ ├── core/ # domain services (auth, track, marketplace, ...) +│ │ ├── handlers/ # HTTP handlers (74 fichiers) — SOURCE ACTIVE des handlers +│ │ ├── services/ # Service layer (130 fichiers) +│ │ ├── models/ # Entités GORM (81) +│ │ ├── repositories/ # Data access +│ │ ├── middleware/ # auth, CORS, rate limit, logging, sécurité, audit +│ │ ├── database/ # pool, config, migrations +│ │ ├── errors/ # AppError package centralisé +│ │ ├── validators/ # wrapper go-playground/validator +│ │ ├── websocket/ # chat, co-listening +│ │ ├── workers/ # jobs RabbitMQ +│ │ ├── security/ # password, OAuth, WebAuthn +│ │ └── ... # (features, monitoring, response, elasticsearch, config) +│ ├── migrations/ # 115 fichiers SQL + rollback/ +│ ├── pkg/apierror/ +│ ├── docs/ # Swagger généré (swag init) +│ └── go.mod # Go 1.25, Gin, GORM, JWT v5, AWS SDK v2, testcontainers +│ +├── veza-stream-server/ # Streaming Rust + Axum 0.8 + Tokio 1.35 +│ ├── src/ +│ │ ├── main.rs +│ │ ├── lib.rs +│ │ ├── routes/ # REST endpoints (HLS, encoding, transcode) +│ │ ├── streaming/ # hls.rs, websocket.rs, adaptive.rs, protocols/ +│ │ │ # ⚠️ DASH/WebRTC stubbed (commentés mod.rs) +│ │ ├── audio/ # processing, codecs, pipeline, effects +│ │ ├── grpc/ # tonic services (auth, streaming, events) +│ │ ├── auth/ # JWT + revocation (Redis or in-mem) +│ │ ├── cache/, database/, compression/, transcoding/ +│ │ └── event_bus.rs # RabbitMQ avec fallback degraded mode +│ └── Cargo.toml # Axum 0.8, Tokio 1.35, Symphonia 0.5, sqlx 0.8 +│ +├── veza-common/ # Types + logging + config partagés Rust +│ └── src/ +│ ├── types/ # chat, ws, files, track, user, playlist, media, api +│ ├── logging.rs # LoggingConfig utilisé par stream server +│ └── auth.rs, metrics.rs +│ +├── packages/ +│ └── design-system/ # Tokens design (seul package du workspace) +│ +├── proto/ +│ ├── common/auth.proto # AuthService (utilisé gRPC stream↔backend) +│ ├── stream/stream.proto # StreamService +│ └── chat/chat.proto # ⚠️ SPEC HISTORIQUE — le chat est en Go +│ +├── docs/ +│ ├── API_REFERENCE.md # ⚠️ maintenance manuelle, risque drift +│ ├── ENV_VARIABLES.md # À maintenir +│ ├── ONBOARDING.md # Setup dev +│ ├── PROJECT_STATE.md # État courant +│ ├── FEATURE_STATUS.md # Features opérationnelles +│ ├── PRODUCTION_DEPLOYMENT.md +│ ├── STAGING_DEPLOYMENT.md +│ ├── SECURITY_SCAN_RC1.md +│ ├── ASVS_CHECKLIST_v0.12.6.md +│ ├── PENTEST_REPORT_VEZA_v0.12.6.md +│ └── archive/ # Retros, smoke tests, plans historiques +│ +├── veza-docs/ # Site Docusaurus séparé +│ ├── docs/current/ # Docs actuelles +│ ├── docs/vision/ # Docs cibles +│ └── ORIGIN/ # ⚠️ C'EST ICI que vit ORIGIN (pas à la racine) +│ ├── ORIGIN_MASTER_ARCHITECTURE.md +│ ├── ORIGIN_CODE_STANDARDS.md +│ ├── ORIGIN_FEATURES_REGISTRY.md +│ ├── ORIGIN_SECURITY_FRAMEWORK.md +│ ├── ORIGIN_UI_UX_SYSTEM.md +│ └── ... +│ +├── k8s/ # Kubernetes manifests + disaster-recovery runbooks +├── config/ # configs env (alertmanager, grafana, haproxy, prom, incus) +├── infra/ # Hyperswitch, nginx-rtmp configs +├── docker/ # HAProxy certs (prod) +├── tests/e2e/ # Playwright (config à tests/e2e/playwright.config.ts) +├── docker-compose.yml # Dev avec services dockerisés +├── docker-compose.dev.yml # Infra only (apps sur l'hôte) +├── docker-compose.prod.yml # Blue-green + haproxy + alertmanager +├── docker-compose.staging.yml # Staging avec Caddy +├── docker-compose.test.yml # CI (tmpfs) +├── Makefile # include make/*.mk +├── package.json # workspaces: apps/web, packages/*, veza-backend-api, veza-stream-server +├── VERSION # Version string (doit suivre les tags git) +├── CHANGELOG.md +└── VEZA_VERSIONS_ROADMAP.md # Historique des versions (v0.9.x → v1.0.x) ``` -### ÉTAPE 1 — IDENTIFIER LA VERSION CIBLE -- Ouvre `VEZA_VERSIONS_ROADMAP.md` -- Cherche le **TABLEAU DE SUIVI** (en fin de fichier) -- Identifie la **première version avec Statut ⏳ TODO** dans l'ordre du tableau -- Lis la section détaillée de cette version (tâches, critères d'acceptation, références ORIGIN) +### Ce qui N'EXISTE PAS — ne pas chercher -### ÉTAPE 2 — VÉRIFIER LES PREREQUISITES -- Vérifie que toutes les versions listées dans "Prerequisite" ont le statut ✅ DONE -- Si un prerequisite manque → **STOP** : affiche le blocage et propose de l'implémenter d'abord -- Si OK → continue +- ❌ `backend/` à la racine → c'est `veza-backend-api/` +- ❌ `frontend/` à la racine → c'est `apps/web/` +- ❌ `ORIGIN/` à la racine → c'est `veza-docs/ORIGIN/` +- ❌ `veza-chat-server/` → supprimé au commit `05d02386d` (2026-02-22, v0.502). Le chat est 100% côté Go backend (`internal/handlers/`, `internal/websocket/`). Les `.proto` de chat restent comme spec historique. +- ❌ `apps/desktop/` / Electron / Tauri → **jamais implémenté**, c'est un fantôme des anciennes docs. +- ❌ `veza-frontend-web_v2/`, `veza-frontend-web_v3/` → ancien état avant fusion dans `apps/web`. Reste un fichier `apps/web/src/types/v2-v3-types.ts` à auditer. -### ÉTAPE 3 — CRÉER LA BRANCHE -```bash -git checkout develop # ou main selon la convention du repo -git pull origin develop -git checkout -b feat/v{VERSION}-{nom-court} -# Exemple : feat/v0.11.0-analytics-createur -``` +### Stack technique exacte -### ÉTAPE 4 — LIRE LES RÉFÉRENCES ORIGIN -Avant d'écrire une seule ligne de code, lis **tous** les fichiers ORIGIN mentionnés dans la version : -```bash -# Toujours lire en premier -cat ORIGIN/ORIGIN_CODE_STANDARDS.md -cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md -cat ORIGIN/ORIGIN_ERROR_PATTERNS.md -cat ORIGIN/ORIGIN_ERROR_PREVENTION_GUIDE.md - -# Puis les références spécifiques à la version -cat ORIGIN/ORIGIN_FEATURES_REGISTRY.md # chercher les numéros F-xxx -cat ORIGIN/ORIGIN_MASTER_ARCHITECTURE.md -cat ORIGIN/ORIGIN_BUSINESS_LOGIC.md # si version business/paiement -cat ORIGIN/ORIGIN_UI_UX_SYSTEM.md # si version frontend -cat ORIGIN/ORIGIN_SECURITY_FRAMEWORK.md # si version sécurité -cat ORIGIN/ORIGIN_PERFORMANCE_TARGETS.md # si version perf -``` -**Ne jamais modifier les fichiers ORIGIN. Ils sont la spécification. Toi tu implémentes.** - -### ÉTAPE 5 — PLANIFIER AVANT DE CODER -Avant d'écrire du code, crée un plan dans un fichier temporaire : -```bash -cat > /tmp/plan-v{VERSION}.md << 'EOF' -# Plan d'implémentation v{VERSION} — {Nom} - -## Tâches ordonnées -1. [TASK-xxx] Description — fichiers à créer/modifier -2. [TASK-yyy] Description — fichiers à créer/modifier -... - -## Ordre d'implémentation -1. Migrations DB (si applicable) -2. Models/Types -3. Repository/Store layer -4. Service layer -5. Handlers/Controllers -6. Routes -7. Frontend components -8. Tests unitaires -9. Tests d'intégration - -## Risques identifiés -- ... - -## Dépendances externes à installer -- ... -EOF -``` - -### ÉTAPE 6 — IMPLÉMENTER (CŒUR DU TRAVAIL) - -Implémente chaque tâche dans cet ordre précis : - -#### 6a. Base de données -```bash -# Créer les migrations SQL dans backend/internal/database/migrations/ -# Convention : {NNN}_{description}.sql (up) et {NNN}_{description}_down.sql -# Appliquer : make migrate-up ou go run cmd/migrate/main.go up -``` - -#### 6b. Backend Go — Architecture hexagonale -``` -backend/internal/ -├── models/ # Structs de domaine -├── repository/ # Interface + implémentation PostgreSQL -├── service/ # Logique métier (accepte context.Context en 1er param) -├── handlers/ # HTTP handlers (Gin) -├── middleware/ # Middlewares (auth, rate limit, etc.) -└── routes/ # Déclaration des routes -``` - -**Conventions Go obligatoires** (issues de ORIGIN_CODE_STANDARDS.md) : -- Tout service accepte `context.Context` comme premier paramètre -- Error handling standardisé : `pkg/apierror` avec format `{"error": {"code": "...", "message": "...", "context": {...}}}` -- Pagination : `?page=1&limit=20` → `{"data": [...], "pagination": {"page": 1, "limit": 20, "total": N, "total_pages": N}}` -- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id` -- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel) - -#### 6c. Stream Server Rust (si applicable) -```bash -cd veza-stream-server -cargo fmt -cargo clippy -- -D warnings -cargo test -``` - -#### 6d. Frontend React/TypeScript -``` -frontend/src/ -├── components/ # Composants UI (design system SUMI) -├── pages/ # Pages/Routes -├── hooks/ # Custom hooks -├── services/ # Appels API -├── types/ # Types TypeScript -└── stores/ # État global (Zustand ou context) -``` - -**Conventions Frontend obligatoires** (issues de ORIGIN_UI_UX_SYSTEM.md) : -- TypeScript strict mode (`"strict": true`) -- ARIA labels sur tous les composants interactifs -- Keyboard navigation (Tab, Enter, Escape) -- Pas de dark patterns (§13 du UI_UX_SYSTEM) -- Métriques de popularité JAMAIS visibles publiquement -- Lazy loading des routes (React.lazy + Suspense) - -#### 6e. Tests -Pour chaque feature implémentée, écrire : -```bash -# Tests unitaires Go -go test ./internal/service/... -v -count=1 -go test ./internal/handlers/... -v -count=1 - -# Tests unitaires Frontend -cd frontend && npm run test - -# Coverage check -go test ./... -coverprofile=coverage.out -go tool cover -func=coverage.out | grep total -``` - -### ÉTAPE 7 — VALIDER - -#### 7a. Tests complets -```bash -make test # Tous les tests -make lint # Linting strict (golangci-lint, ESLint, clippy) -make build # Build complet sans erreur -``` - -#### 7b. Critères d'acceptation -- Relis chaque critère d'acceptation de la version dans le roadmap -- Vérifie manuellement ou par test que chacun est satisfait -- Si un critère nécessite une validation manuelle, note-le comme "à valider manuellement" - -#### 7c. Checklist ORIGIN_FEATURE_VALIDATION_STRATEGY.md -```bash -cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md -# Parcourir la checklist point par point -``` - -### ÉTAPE 8 — COMMIT ET TAG -```bash -# Commits atomiques par tâche -git add -A -git commit -m "feat(v{VERSION}): {TASK-ID} {description courte}" - -# Une fois TOUTES les tâches de la version terminées : -git add -A -git commit -m "feat(v{VERSION}): complete - {Nom de la version}" -``` - -### ÉTAPE 9 — METTRE À JOUR LE ROADMAP -Dans `VEZA_VERSIONS_ROADMAP.md` : -1. Changer le statut de la version de `⏳ TODO` à `✅ DONE` -2. Ajouter `**Complété le** : {date du jour au format YYYY-MM-DD}` -3. Cocher les tâches `- [x]` et critères `- [x]` validés -4. Mettre à jour le tableau de suivi en bas du fichier -5. Commit : -```bash -git add VEZA_VERSIONS_ROADMAP.md -git commit -m "docs: update VEZA_VERSIONS_ROADMAP [v{VERSION} DONE]" -``` - -### ÉTAPE 10 — TAG GIT -```bash -git tag -a v{VERSION} -m "Version v{VERSION} : {Nom de la version}" -``` - -### ÉTAPE 11 — RÉSUMÉ FINAL -Afficher un résumé : -``` -═══════════════════════════════════════════ -✅ VERSION v{VERSION} — {NOM} — COMPLÈTE -═══════════════════════════════════════════ -Tâches implémentées : X/X -Tests : ✅ PASS (coverage: XX%) -Lint : ✅ PASS -Build : ✅ PASS -Critères d'acceptation : X/X validés, Y à valider manuellement -Branche : feat/v{VERSION}-{nom} -Tag : v{VERSION} -Prochaine version : v{NEXT} — {Nom} -═══════════════════════════════════════════ -``` +| Composant | Techno | Version pinned | +| ------------- | ---------------------------------- | ----------------------------------------------- | +| Backend API | Go + Gin + GORM | **Go 1.25** (bumped pour golangci-lint v2.11.4) | +| Stream | Rust + Axum + Tokio | Axum 0.8, Tokio 1.35 | +| Frontend | React + Vite + TS strict | React 18.2, Vite 5, TS 5.9.3 | +| State front | Zustand + React Query 5 | | +| Postgres | 16 | docker-compose pinned | +| Redis | 7 | | +| Elasticsearch | 8.11.0 | docker-compose.dev.yml | +| RabbitMQ | 3-management | | +| ClamAV | 1.4 | SEC-MED-003 | +| Hyperswitch | 2026.03.11.0 | | +| JWT | RS256 prod / HS256 fallback dev | jwt v5 | +| CI | Forgejo Actions (self-hosted R720) | `.github/workflows/ci.yml` consolidé | --- -## 🚫 RÈGLES IMMUABLES — JAMAIS VIOLER +## 🚫 Règles immuables — jamais violer Ces règles sont **absolues**. Si une tâche semble les contredire, la règle gagne. -1. **JAMAIS de code AI/ML** — Modules F456-F470 supprimés définitivement. Aucun import tensorflow, pytorch, sklearn, etc. -2. **JAMAIS de blockchain/Web3** — Modules F491-F500 supprimés. Aucun code NFT, smart contract, wallet crypto. -3. **JAMAIS de gamification** — Modules F536-F550 supprimés. Aucun XP, streak, leaderboard, badge, level up. -4. **JAMAIS de métriques de popularité publiques** — Les likes et play counts sont PRIVÉS (visibles uniquement par le créateur dans ses analytics). -5. **JAMAIS de dark patterns UX** — Pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription. Ref: ORIGIN_UI_UX_SYSTEM.md §13. -6. **JAMAIS modifier les fichiers ORIGIN/** — Ils sont la spécification de référence, pas du code. -7. **JAMAIS déployer sans que les critères d'acceptation soient vérifiés.** -8. **Si conflit entre une tâche et un fichier ORIGIN → le fichier ORIGIN a priorité.** Signaler l'incohérence dans le commit message. -9. **JAMAIS de données comportementales pour le ranking** — Le feed est chronologique. La découverte est par tags/genres déclaratifs. -10. **TOUJOURS propager context.Context** dans les fonctions Go qui font du I/O. -11. **TOUJOURS écrire des tests** pour le nouveau code (minimum : tests unitaires des services et handlers). +1. **JAMAIS de code AI/ML** — modules F456-F470 supprimés définitivement. Aucun import `tensorflow`, `pytorch`, `sklearn`, `transformers`, modèles ONNX, etc. +2. **JAMAIS de blockchain/Web3** — modules F491-F500 supprimés. Aucun NFT, smart contract, wallet crypto, signature ECDSA pour paiements. +3. **JAMAIS de gamification** — modules F536-F550 supprimés. Aucun XP, streak, leaderboard, badge, level up, "points", "achievements". +4. **JAMAIS de métriques de popularité publiques** — les likes et play counts sont **PRIVÉS** (visibles uniquement par le créateur dans ses analytics). Aucun compteur visible sur les vues publiques. +5. **JAMAIS de dark patterns UX** — pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription, pas de confirm-shaming. Ref : `veza-docs/ORIGIN/ORIGIN_UI_UX_SYSTEM.md` §13. +6. **JAMAIS modifier les fichiers `veza-docs/ORIGIN/**/\*.md`\*\* — ils sont la spécification de référence, pas du code. Tu implémentes, tu ne modifies pas la spec. +7. **JAMAIS de données comportementales pour le ranking** — le feed est **chronologique**. La découverte est par tags/genres **déclaratifs**. Pas de "tu aimeras aussi" basé sur l'historique. +8. **TOUJOURS propager `context.Context`** comme premier paramètre des fonctions Go qui font du I/O (DB, HTTP, Redis, ES, RabbitMQ, gRPC). +9. **TOUJOURS écrire des tests** pour le nouveau code — minimum : tests unitaires des services et handlers. Intégration si l'infra est touchée. +10. **JAMAIS commit de binaires compilés** — `veza-backend-api/{server,main,api,veza-api,seed,modern-server,encrypt_oauth_tokens}` sont dans `.gitignore`. Si tu crées un binaire pour tests, ne l'ajoute pas à git. +11. **JAMAIS commit de rapports générés** — `coverage*.out`, `lint_report*.json`, `tsc_*.log`, `storybook_*.json` sont ignorés. Ils vivent en local ou dans les artifacts CI, pas en git. +12. **JAMAIS commit de docs de session** — les `RESUME_*.md`, `PLAN_V*.md`, `AUDIT_*.md`, `FIX_*.md`, `PROGRES_*.md`, etc. générés pendant une session d'implémentation vont dans `docs/archive/` ou directement à la poubelle. --- -## 🏗️ ARCHITECTURE DE RÉFÉRENCE +## 📐 Conventions de code -### Structure du Monorepo -``` -veza/ -├── CLAUDE.md # CE FICHIER (instructions agent) -├── VEZA_VERSIONS_ROADMAP.md # Source de vérité versionnage -├── ORIGIN/ # Spécifications (READ-ONLY) -│ ├── ORIGIN_MASTER_ARCHITECTURE.md -│ ├── ORIGIN_CODE_STANDARDS.md -│ ├── ORIGIN_FEATURES_REGISTRY.md -│ ├── ORIGIN_SECURITY_FRAMEWORK.md -│ ├── ORIGIN_BUSINESS_LOGIC.md -│ ├── ORIGIN_UI_UX_SYSTEM.md -│ ├── ORIGIN_ERROR_PATTERNS.md -│ ├── ORIGIN_ERROR_PREVENTION_GUIDE.md -│ ├── ORIGIN_FEATURE_VALIDATION_STRATEGY.md -│ ├── ORIGIN_PERFORMANCE_TARGETS.md -│ └── ... -├── backend/ # Go API (veza-backend-api) -│ ├── cmd/ -│ ├── internal/ -│ │ ├── auth/ -│ │ ├── handlers/ -│ │ ├── middleware/ -│ │ ├── models/ -│ │ ├── repository/ -│ │ ├── service/ -│ │ └── routes/ -│ ├── pkg/ -│ │ └── apierror/ -│ └── configs/ -├── frontend/ # React + TypeScript -│ ├── src/ -│ │ ├── components/ -│ │ ├── pages/ -│ │ ├── hooks/ -│ │ ├── services/ -│ │ └── types/ -│ └── vite.config.ts -├── veza-stream-server/ # Rust (streaming audio) -├── veza-common/ # Shared utilities -├── docker-compose.yml -├── docker-compose.dev.yml -├── Makefile -├── .github/workflows/ci.yml -└── docs/ - ├── adr/ - ├── ENV_VARIABLES.md - └── SECRETS_AUDIT.md -``` +### Go (backend) -### Stack Technique -| Composant | Technologie | -|-----------|-------------| -| Backend API | Go + Gin | -| Stream Server | Rust | -| Frontend | React + TypeScript + Vite | -| Base de données | PostgreSQL | -| Cache | Redis | -| Recherche | Elasticsearch | -| Message Queue | RabbitMQ | -| Object Storage | MinIO (dev) / S3 (prod) | -| Paiements | Hyperswitch (Stripe + PayPal) | -| Livestream | Nginx-RTMP + HLS | -| CI/CD | GitHub Actions | -| Conteneurs | Docker + docker-compose | +- Framework : **Gin** +- ORM : **GORM** +- Error package centralisé : [`internal/errors`](veza-backend-api/internal/errors) — `AppError{Code, Message, Err, Details, Context}`, utilisé via `RespondWithAppError(c, err)` +- Validation : `go-playground/validator/v10` via [`internal/validators`](veza-backend-api/internal/validators) +- Format réponse d'erreur : + ```json + { + "error": { + "code": "RESOURCE_NOT_FOUND", + "message": "Track 123 not found", + "context": { "track_id": "123" } + } + } + ``` +- Format réponse paginée : + ```json + { + "data": [...], + "pagination": {"page": 1, "limit": 20, "total": 150, "total_pages": 8} + } + ``` +- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id` +- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel, ctx.Done()) +- JWT : **RS256 en prod** (clés RSA), fallback HS256 dev. Access token 5min, refresh 7j. Cookies httpOnly. +- Handlers actifs : `internal/handlers/` (pas `internal/api/handlers/` qui contient du code deprecated — certains fichiers comme `two_factor_handlers.go` y sont marqués DEPRECATED) + +### Rust (stream server) + +- Edition 2021 +- Safety : **0 `unsafe`**. Ne pas introduire de code unsafe sans justification extrême. +- Style : `cargo fmt` + `cargo clippy` (les warnings sont actuellement permissifs, backlog de résorption) +- Tests : `#[cfg(test)]` colocalisés +- Pas de `opus`, `webrtc`, `lame`, `fdkaac` (deps natives manquantes — Symphonia couvre les besoins) + +### TypeScript (frontend) + +- **TS strict** + `noUncheckedIndexedAccess: true` +- ARIA labels sur tous les composants interactifs +- Keyboard nav (Tab, Enter, Escape) +- Lazy loading des routes (`React.lazy` + `Suspense`) — registry dans [`src/components/ui/LazyComponent.tsx`](apps/web/src/components/ui/LazyComponent.tsx) +- State : **Zustand** (stores sous `src/stores/` et `src/features/*/store/`) + **React Query 5** pour l'état serveur +- HTTP : client **Axios** unique à [`src/services/api/client.ts`](apps/web/src/services/api/client.ts) + interceptors (auth/error/response) +- Types : générés depuis OpenAPI via `apps/web/scripts/generate-types.sh` (pre-commit hook) +- i18n : `react-i18next` 15 +- Pas de `moment` (déprécié — utiliser `date-fns@4`) + +### API REST -### Patterns API ```go -// Route convention -router.GET("/api/v1/{resource}", handler.List) // Pagination cursor -router.GET("/api/v1/{resource}/:id", handler.Get) -router.POST("/api/v1/{resource}", handler.Create) -router.PUT("/api/v1/{resource}/:id", handler.Update) +// Conventions de routes +router.GET("/api/v1/{resource}", handler.List) // ?page=1&limit=20 +router.GET("/api/v1/{resource}/:id", handler.Get) +router.POST("/api/v1/{resource}", handler.Create) +router.PUT("/api/v1/{resource}/:id", handler.Update) router.DELETE("/api/v1/{resource}/:id", handler.Delete) - -// Error response format -{ - "error": { - "code": "RESOURCE_NOT_FOUND", - "message": "Track with ID 123 not found", - "context": {"track_id": "123"} - } -} - -// Pagination response format -{ - "data": [...], - "pagination": { - "page": 1, - "limit": 20, - "total": 150, - "total_pages": 8 - } -} ``` --- -## 🔄 VERSIONS RESTANTES (TODO) +## 💡 Commandes utiles -Référence rapide des versions à implémenter, dans l'ordre : +```bash +# --- Développement --- +make dev # Backend docker + web local (mode principal) +make dev-full # Tout local avec hot reload +make dev-backend-api # Backend Go seul +make dev-stream-server # Rust stream server seul +make dev-web # Frontend Vite seul +make doctor # Vérifie les dépendances système -| # | Version | Nom | Phase | Durée est. | Prerequisite | -|---|---------|-----|-------|------------|--------------| -| 1 | v0.11.0 | Analytics Créateur | P5R | 4-5j | v0.10.3 ✅ | -| 2 | v0.11.1 | Analytics Avancés | P5R | 3-4j | v0.11.0 | -| 3 | v0.11.2 | Modération Avancée | P5R | 3-4j | v0.10.0 ✅ | -| 4 | v0.11.3 | Administration Plateforme | P5R | 3-4j | v0.11.2 | -| 5 | v0.12.0 | Marketplace Complète | P6R | 6-8j | v0.11.0 | -| 6 | v0.12.1 | Plans Premium & Abonnements | P6R | 4-5j | v0.12.0 | -| 7 | v0.12.2 | Distribution Plateformes | P6R | 5-6j | v0.12.1 | -| 8 | v0.12.3 | Formation & Éducation | P6R | 6-8j | v0.12.0 | -| 9 | v0.12.4 | Performance & Scalabilité | P6R | 3-4j | v0.12.2 | -| 10 | v0.12.5 | PWA & Mobile | P6R | 4-5j | v0.12.4 | -| 11 | v0.12.6 | Pentest Externe | P6R | 2-4 sem. | v0.12.4 | -| 12 | v0.12.7 | Internationalisation | P6R | 3-4j | v0.12.5 | -| 13 | v0.12.8 | Documentation & API Publique | P6R | 3-4j | v0.12.6 | -| 14 | v1.0.0 | Release Stable | — | — | Tout | +# --- Infra seule --- +make infra-up-dev # Postgres, Redis, RabbitMQ, ES, MinIO, ClamAV +make infra-down # Stop infra + +# --- Tests --- +make test # Tous les tests +make test-backend-api # Go unit tests +make test-web # Vitest frontend +make test-stream-server # Cargo test +make lint # Linting complet (golangci-lint, ESLint, clippy) + +# --- Backend Go spécifique --- +cd veza-backend-api +go test ./internal/... -short -count=1 +go test ./internal/... -short -count=1 -v -run TestXxx +VEZA_SKIP_INTEGRATION=1 go test ./internal/... -count=1 # skip testcontainers +go build ./... +gofmt -l -w . + +# --- Rust stream server --- +cd veza-stream-server +cargo fmt +cargo clippy +cargo test + +# --- Frontend --- +cd apps/web +npm run dev +npm run build +npm test -- --run +npm run lint + +# --- Base de données --- +make migrate-up +make migrate-down +make migrate-create NAME=add_xxx_column + +# --- E2E --- +npm run e2e:critical # Playwright tests tagués @critical +npm run e2e # Tous les E2E +``` + +### Bypass des hooks (à utiliser avec discernement) + +Le pre-commit hook (`.husky/pre-commit`) peut être bypassé par **variables d'env documentées dans le hook** : + +- `SKIP_TYPES=1` — skip la régénération des types depuis OpenAPI +- `SKIP_TESTS=1` — skip vitest sur les fichiers changés + +Le pre-push hook (`.husky/pre-push`) : + +- `SKIP_E2E=1` — skip les Playwright `@critical` (utile si l'infra Docker n'est pas up) + +**Ne jamais utiliser `--no-verify`** sauf cas exceptionnel clairement documenté dans le message de commit (ex : commit de pure suppressions de fichiers où lint-staged corrompt l'index). --- -## 🧠 PATTERNS DE RÉSOLUTION +## 📝 Convention de commits + +Conventional Commits + scope : + +``` +feat(backend): add playlist sharing by token +fix(web): resolve feed rendering bug on iOS Safari +refactor(stream): extract HLS manifest generator +test(backend): add integration tests for 2FA flow +docs: update ENV_VARIABLES.md +chore(cleanup): archive session docs from apps/web +ci: bump Go to 1.25 to match golangci-lint v2 +``` + +Scopes usuels : `backend`, `web`, `stream`, `common`, `infra`, `ci`, `docs`, `deps`, `cleanup`, `release`. + +Format du message : + +``` +(): + + + +