|
|
|
|
@ -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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### É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)
|
|
|
|
|
|
|
|
|
|
### É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
|
|
|
|
|
|
|
|
|
|
### É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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### É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}
|
|
|
|
|
═══════════════════════════════════════════
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🚫 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).
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🏗️ ARCHITECTURE DE RÉFÉRENCE
|
|
|
|
|
|
|
|
|
|
### Structure du Monorepo
|
|
|
|
|
```
|
|
|
|
|
veza/
|
|
|
|
|
├── CLAUDE.md # CE FICHIER (instructions agent)
|
|
|
|
|
├── VEZA_VERSIONS_ROADMAP.md # Source de vérité versionnage
|
|
|
|
|
├── ORIGIN/ # Spécifications (READ-ONLY)
|
|
|
|
|
├── 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_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
|
|
|
|
|
│
|
|
|
|
|
├── 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)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 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 |
|
|
|
|
|
### Ce qui N'EXISTE PAS — ne pas chercher
|
|
|
|
|
|
|
|
|
|
- ❌ `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.
|
|
|
|
|
|
|
|
|
|
### Stack technique exacte
|
|
|
|
|
|
|
|
|
|
| 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
|
|
|
|
|
|
|
|
|
|
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`, `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.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 📐 Conventions de code
|
|
|
|
|
|
|
|
|
|
### Go (backend)
|
|
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
// 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 :
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
<type>(<scope>): <sujet court impératif, minuscule, ≤70 chars>
|
|
|
|
|
|
|
|
|
|
<corps optionnel: explique pourquoi, pas quoi>
|
|
|
|
|
|
|
|
|
|
<footer optionnel: Co-Authored-By, Refs, Closes>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Co-author requis quand l'agent contribue :
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🎯 Scope du projet — ce qu'on fait, ce qu'on refuse
|
|
|
|
|
|
|
|
|
|
Veza est une **plateforme de streaming musical éthique** pour créateurs et auditeurs. Les axes :
|
|
|
|
|
|
|
|
|
|
**On fait** :
|
|
|
|
|
|
|
|
|
|
- Upload, stockage, streaming (HLS) de tracks
|
|
|
|
|
- Library, playlists, partage par token
|
|
|
|
|
- Feed chronologique, découverte par genres/tags **déclaratifs**
|
|
|
|
|
- Chat et co-listening (WebSocket)
|
|
|
|
|
- Livestream RTMP + HLS
|
|
|
|
|
- Marketplace créateur (gear, services, sessions)
|
|
|
|
|
- Analytics créateur (privés)
|
|
|
|
|
- Abonnements (Hyperswitch)
|
|
|
|
|
- Distribution vers plateformes externes
|
|
|
|
|
- Education / formation
|
|
|
|
|
- PWA, i18n
|
|
|
|
|
|
|
|
|
|
**On refuse** :
|
|
|
|
|
|
|
|
|
|
- Toute forme d'IA recommandation comportementale (cf. règle 7)
|
|
|
|
|
- Popularité publique (cf. règle 4)
|
|
|
|
|
- Gamification (cf. règle 3)
|
|
|
|
|
- Dark patterns (cf. règle 5)
|
|
|
|
|
- NFT / Web3 (cf. règle 2)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 🧠 Patterns de résolution
|
|
|
|
|
|
|
|
|
|
### Quand tu ne sais pas quoi faire
|
|
|
|
|
1. Relis la section de la version dans `VEZA_VERSIONS_ROADMAP.md`
|
|
|
|
|
2. Relis le fichier ORIGIN référencé
|
|
|
|
|
3. Regarde le code existant similaire dans le repo (ex: comment les autres handlers sont structurés)
|
|
|
|
|
4. En dernier recours, implémente la solution la plus simple qui satisfait les critères d'acceptation
|
|
|
|
|
|
|
|
|
|
1. Lis `docs/PROJECT_STATE.md` et `docs/FEATURE_STATUS.md` pour l'état courant.
|
|
|
|
|
2. Si spec : lis `veza-docs/ORIGIN/` (lecture seule).
|
|
|
|
|
3. Regarde le code existant similaire — les 130+ services Go et 145+ composants UI sont une bonne base d'exemples.
|
|
|
|
|
4. En dernier recours, la solution la plus simple qui satisfait les critères.
|
|
|
|
|
|
|
|
|
|
### Quand un test échoue
|
|
|
|
|
1. Lis l'erreur complète
|
|
|
|
|
2. Vérifie que les migrations DB sont appliquées
|
|
|
|
|
3. Vérifie que les services infra tournent (Postgres, Redis, Elasticsearch)
|
|
|
|
|
4. Fix le test ou le code, pas les deux en même temps
|
|
|
|
|
|
|
|
|
|
1. Lis l'erreur complète.
|
|
|
|
|
2. Vérifie que les migrations DB sont appliquées (`make migrate-up`).
|
|
|
|
|
3. Vérifie que l'infra tourne (`make infra-up-dev`).
|
|
|
|
|
4. Reproduire localement, pas deviner.
|
|
|
|
|
5. Fix soit le test soit le code — pas les deux en même temps.
|
|
|
|
|
|
|
|
|
|
### Quand tu trouves un bug existant
|
|
|
|
|
1. Fix-le si c'est dans le scope de la version actuelle
|
|
|
|
|
2. Sinon, crée un commentaire `// TODO(v{NEXT}): description du bug`
|
|
|
|
|
3. Ne jamais laisser un bug casser les tests de la version en cours
|
|
|
|
|
|
|
|
|
|
### Quand une dépendance externe manque
|
|
|
|
|
1. Fix-le si dans le scope de ta tâche actuelle.
|
|
|
|
|
2. Sinon `// TODO(<scope>): description` et note dans le PR description.
|
|
|
|
|
3. Ne jamais casser un test qui passait pour en faire passer un nouveau.
|
|
|
|
|
|
|
|
|
|
### Quand une dépendance manque
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Go
|
|
|
|
|
go get {package}
|
|
|
|
|
cd veza-backend-api && go get <module>@<version>
|
|
|
|
|
|
|
|
|
|
# Frontend
|
|
|
|
|
cd frontend && npm install {package}
|
|
|
|
|
cd apps/web && npm install <package>
|
|
|
|
|
|
|
|
|
|
# Rust
|
|
|
|
|
cd veza-stream-server && cargo add {crate}
|
|
|
|
|
cd veza-stream-server && cargo add <crate>
|
|
|
|
|
```
|
|
|
|
|
Toujours vérifier la licence (MIT, Apache-2.0, BSD OK — pas de GPL dans le backend).
|
|
|
|
|
|
|
|
|
|
Licence acceptable : MIT, Apache-2.0, BSD-2/3, ISC, MPL-2.0. **GPL interdit** dans le backend.
|
|
|
|
|
|
|
|
|
|
### Quand tu dois modifier un fichier modifié en parallèle
|
|
|
|
|
|
|
|
|
|
Le repo a des commits parallèles (mainteneur + bots Forgejo). Si `git pull` donne un conflit :
|
|
|
|
|
|
|
|
|
|
1. Ne jamais force-push sur `main`.
|
|
|
|
|
2. Résoudre proprement, commit de résolution explicite.
|
|
|
|
|
3. Si doute, demander.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 💡 COMMANDES UTILES
|
|
|
|
|
## 🚨 Actions qui nécessitent une confirmation humaine
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Développement
|
|
|
|
|
make dev # Démarre tout l'environnement
|
|
|
|
|
make dev-backend-api # Backend seul
|
|
|
|
|
make dev-stream-server # Stream server seul
|
|
|
|
|
make doctor # Vérifie les dépendances
|
|
|
|
|
**NE JAMAIS faire sans demander** :
|
|
|
|
|
|
|
|
|
|
# Tests
|
|
|
|
|
make test # Tous les tests
|
|
|
|
|
make test-backend # Tests Go
|
|
|
|
|
make test-frontend # Tests React
|
|
|
|
|
make lint # Linting complet
|
|
|
|
|
- `git push --force` ou `git push --force-with-lease` sur `main`
|
|
|
|
|
- `git reset --hard` qui perd du travail
|
|
|
|
|
- `git filter-repo` / purge d'historique
|
|
|
|
|
- Supprimer des branches distantes (`git push --delete`)
|
|
|
|
|
- Supprimer des tags distants
|
|
|
|
|
- Modifier `.github/workflows/*.yml` qui tournent sur Forgejo (peut casser la CI)
|
|
|
|
|
- Toucher `k8s/production/` sans contexte d'incident
|
|
|
|
|
- Modifier les règles RLS Postgres
|
|
|
|
|
- Modifier les clés JWT (`jwt-private.pem`, `jwt-public.pem`)
|
|
|
|
|
- Modifier les secrets (`docker-compose.prod.yml` env, `.env.production`)
|
|
|
|
|
|
|
|
|
|
# Base de données
|
|
|
|
|
make migrate-up # Appliquer migrations
|
|
|
|
|
make migrate-down # Rollback dernière migration
|
|
|
|
|
make migrate-create NAME=x # Créer nouvelle migration
|
|
|
|
|
**Peut faire sans demander** :
|
|
|
|
|
|
|
|
|
|
# Build
|
|
|
|
|
make build # Build complet
|
|
|
|
|
make build-backend # Build Go
|
|
|
|
|
make build-frontend # Build React
|
|
|
|
|
|
|
|
|
|
# Docker
|
|
|
|
|
make infra-up-dev # Postgres, Redis, RabbitMQ, etc.
|
|
|
|
|
make infra-down # Stop infra
|
|
|
|
|
```
|
|
|
|
|
- Tout commit local + push simple (`git push origin main`) si la branche ne diverge pas
|
|
|
|
|
- Éditer les fichiers `.md` de documentation
|
|
|
|
|
- Éditer le code applicatif (Go, Rust, TS) avec tests
|
|
|
|
|
- Ajouter des migrations SQL
|
|
|
|
|
- Modifier `docker-compose.dev.yml` et configs de dev
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 📝 CONVENTION DE COMMITS
|
|
|
|
|
## 📜 Historique
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
feat(v0.11.0): TASK-xxx description courte
|
|
|
|
|
fix(v0.11.0): correction du bug dans xxx
|
|
|
|
|
test(v0.11.0): ajout tests unitaires pour xxx
|
|
|
|
|
docs: update VEZA_VERSIONS_ROADMAP [v0.11.0 DONE]
|
|
|
|
|
refactor(v0.11.0): extraction du service xxx
|
|
|
|
|
chore: mise à jour dépendances
|
|
|
|
|
```
|
|
|
|
|
- **2026-04-14** : Réécriture complète post-audit (v1.0.4). L'ancienne version référençait `backend/`, `frontend/`, `ORIGIN/` à la racine, un chat server Rust et un desktop Electron qui n'existaient pas ou plus. Voir `AUDIT_REPORT.md` pour le détail.
|
|
|
|
|
- **2026-02-22** (commit `05d02386d`) : suppression de `veza-chat-server/` (chat intégré au backend Go depuis v0.502).
|
|
|
|
|
- **2026-03-03** : release `v1.0.0`.
|
|
|
|
|
- **2026-03-13** : tag `v1.0.2`.
|
|
|
|
|
- **2026-04-14** : tag `v1.0.3` existant, cible `v1.0.4` pour la release post-cleanup.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
*Ce fichier est la source de vérité pour le comportement de l'agent Claude Code sur le projet Veza.*
|
|
|
|
|
*Ne jamais le modifier sans commit explicite : `docs: update CLAUDE.md [raison]`*
|
|
|
|
|
_Source de vérité pour le comportement de Claude Code sur Veza. Ne jamais modifier sans commit explicite (`docs: update CLAUDE.md [raison]`)._
|
|
|
|
|
|
senke