Aller au contenu principal

Guide de Debugging - MyTV v2 API

Guide pour diagnostiquer et résoudre les problèmes courants de l'API MyTelevision.

Table des matières​

  1. Démarrage et configuration
  2. Base de données (Prisma/PostgreSQL)
  3. Authentification et sessions
  4. Multi-tenant
  5. Account Deletion (RGPD)
  6. Notifications (Email & Push)
  7. Streaming et DRM
  8. Performance et cache Redis
  9. Tests
  10. Docker et déploiement
  11. Logs et monitoring

1. Démarrage et configuration​

L'API ne démarre pas​

# Vérifier que les services Docker sont actifs
npm run docker:up
docker ps  # PostgreSQL et Redis doivent être running

# Vérifier les variables d'environnement
cat .env | grep DATABASE_URL
cat .env | grep REDIS_HOST

# Vérifier que le client Prisma est généré
npm run prisma:generate

# Vérifier que les migrations sont appliquées
npm run prisma:migrate:dev

Erreur "Cannot find module '@prisma/client'"​

npm run prisma:generate
# Si persist: supprimer node_modules/.prisma et regenerer
rm -rf node_modules/.prisma
npm run prisma:generate

Erreur "Port 3000 already in use"​

# Windows
netstat -ano | findstr :3000
taskkill /PID <pid> /F

# Linux/Mac
lsof -i :3000
kill -9 <pid>

Variables d'environnement manquantes​

Le fichier .env.example contient toutes les variables avec leurs valeurs par défaut. Variables critiques :

VariableObligatoireDefaultDescription
DATABASE_URLOui-Connection PostgreSQL
REDIS_HOSTNonlocalhostHôte Redis
JWT_SECRETOui (prod)dev defaultMin 32 caractères
TMDB_API_KEYNon-Auto-fill contenu
FIREBASE_PROJECT_IDNon-Social auth uniquement

2. Base de données (Prisma/PostgreSQL)​

Migrations en erreur​

# Voir le statut des migrations
npx prisma migrate status

# Reset complet (ATTENTION: perte de données)
npx prisma migrate reset

# Appliquer les migrations manquantes
npm run prisma:migrate:dev

Requêtes lentes​

# Activer le logging Prisma dans .env
# DATABASE_LOG_LEVEL=query,info,warn,error

# Vérifier les index dans Prisma Studio
npm run prisma:studio

Erreur "Unique constraint violation"​

Vérifier les contraintes d'unicité dans prisma/schema.prisma :

  • Account: unique sur (email, tenantId)
  • Profile: unique sur (accountId, name, tenantId)
  • AccountDevice: unique sur (fingerprint, accountId, tenantId)
  • AccountSession: unique sur (tokenHash)

Transactions échouées​

Les opérations critiques utilisent prisma.$transaction(). En cas d'échec partiel :

# Vérifier l'état dans Prisma Studio
npm run prisma:studio

# Chercher les données incohérentes
# Ex: compte en PENDING_DELETION mais profils encore ACTIVE

3. Authentification et sessions​

JWT Token invalide / expiré​

# Décoder un JWT (sans vérification)
echo "<token>" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

# Vérifier la configuration JWT dans .env
# JWT_EXPIRATION=15m        (access token)
# JWT_REFRESH_EXPIRATION=7d (refresh token)

Erreur 401 sur des endpoints protégés​

  1. Vérifier que le header Authorization: Bearer <token> est présent
  2. Vérifier que le token n'est pas expiré
  3. Vérifier que la session n'a pas été révoquée
  4. Vérifier que le tenantId du token correspond au tenant de la requête

Social Auth (Firebase) échoue​

# Vérifier les credentials Firebase dans .env
echo $FIREBASE_PROJECT_ID
echo $FIREBASE_CLIENT_EMAIL

# Tester la connexion Firebase
# Le service vérifie: signature RS256, issuer, audience, expiration

Session révoquée inattendue​

Causes possibles :

  • Logout global (POST /account-auth/logout-all) révoque toutes les sessions
  • Limite de sessions dépassée (max concurrent sessions configurable par tenant)
  • Account deletion en cours (sessions révoquées lors de la suppression)
  • Device révoqué entraîne la révocation des sessions associées

4. Multi-tenant​

Erreur "Tenant not found"​

# Résoudre un tenant par slug
curl http://localhost:3000/api/v2/tenant/my-brand/info

# Résoudre un tenant par domaine
curl "http://localhost:3000/api/v2/tenant/resolve?domain=app.mybrand.com"

Données cross-tenant visibles​

Toutes les requêtes doivent inclure tenantId dans leur clause WHERE. Vérifier :

  1. Le guard TenantGuard est appliqué sur le controller
  2. Le service passe tenantId à chaque requête Prisma
  3. Les relations sont filtrées par tenant (ex: account.findFirst({ where: { id, tenantId } }))

5. Account Deletion (RGPD)​

Compte non restauré au login​

Le système auto-restore fonctionne uniquement si :

  • Le compte est en statut PENDING_DELETION
  • La date scheduledDeletionAt n'est pas encore passée
  • L'appel checkAndRestoreOnLogin() est bien invoqué dans le flux d'authentification

Cron job ne s'exécute pas​

# Vérifier que @nestjs/schedule est importé dans AppModule
# Vérifier que ScheduleModule.forRoot() est dans les imports

# Les crons :
# - 1:00 AM → sendPreDeletionWarnings (3 jours avant)
# - 2:00 AM → processScheduledDeletions (suppression effective)

# Tester manuellement via le service
# POST /api/v2/admin/account-deletion/trigger (si endpoint admin exposé)

Email de suppression non envoyé​

L'email est envoyé AVANT l'anonymisation du compte. Si l'email n'est pas reçu :

  1. Vérifier la configuration SMTP dans .env (SMTP_HOST, SMTP_PORT, etc.)
  2. Vérifier les logs : Failed to send email to <email>
  3. L'email est fire-and-forget : un échec d'envoi ne bloque PAS la suppression

6. Notifications (Email & Push)​

Emails non reçus​

# Vérifier la configuration SMTP
cat .env | grep SMTP

# Vérifier les logs d'erreur
# Pattern: "Failed to send email to <email>:"

Les templates email sont dans EmailService :

  • generateDeletionConfirmationEmail() - Demande de suppression
  • generateAccountRestoredEmail() - Restauration du compte
  • generatePreDeletionWarningEmail() - Avertissement 3 jours avant
  • generateDeletionCompletedEmail() - Suppression effectuée

Push notifications non reçues​

# Vérifier que NotificationsModule est importé
# NotificationsService est @Optional() - l'absence ne cause pas d'erreur

# Vérifier les logs
# Pattern: "Failed to send push notification for account <id>:"

Le service utilise NotificationType.SYSTEM et passe les userIds au service de notifications.

7. Streaming et DRM​

Token de streaming invalide​

# Vérifier STREAMING_SIGNING_SECRET dans .env
# Les tokens sont liés à : IP, userId, contentId, expiration

# Générer un nouveau token via l'API
curl -X POST http://localhost:3000/api/v2/streaming/token \
  -H "Authorization: Bearer <jwt>" \
  -d '{"contentId": "xxx", "quality": "1080p"}'

Erreur DRM​

Vérifier :

  • Les clés DRM sont générées et stockées (table DrmKey)
  • Le content a bien un drmKeyId associé
  • La licence est valide et non expirée

8. Performance et cache Redis​

Cache Redis non fonctionnel​

# Tester la connexion Redis
redis-cli -h localhost -p 6379 ping
# Réponse attendue: PONG

# Vérifier les clés de cache
redis-cli keys "mytv:*"

# Flush le cache (ATTENTION en production)
redis-cli flushall

Rate limiting trop agressif​

Le rate limiting est par profil (pas par compte) :

  • Short: 3 req / 1 sec
  • Medium: 20 req / 10 sec
  • Long: 100 req / 1 min
# Vérifier les overrides tenant
# Configurable via TenantConfig.rateLimitOverrides

# En dev, augmenter les limites dans .env ou via seed

Réponses lentes​

  1. Activer le logging Prisma pour identifier les requêtes lentes
  2. Vérifier le cache Redis (hit/miss ratio)
  3. Vérifier les N+1 queries dans les services (utiliser include dans Prisma)
  4. Consulter les métriques Prometheus : http://localhost:3000/metrics

9. Tests​

Tests qui échouent après modification​

# Lancer les tests d'un module spécifique
npx jest "account-deletion"
npx jest "risk"
npx jest "tenant"

# Lancer tous les tests avec couverture
npm run test:cov

# Lancer en mode verbose
npx jest --verbose

# Lancer un fichier de test spécifique
npx jest src/application/services/account-deletion/account-deletion.service.spec.ts

Mocks manquants​

Les tests utilisent des mocks NestJS standards :

// Pattern standard pour les mocks
const module = await Test.createTestingModule({
  providers: [
    MyService,
    { provide: PrismaService, useValue: mockPrisma },
    { provide: ConfigService, useValue: mockConfig },
  ],
}).compile();

Couverture insuffisante​

Objectif minimum : 80% global. Vérifier :

npm run test:cov
# Examiner le rapport dans coverage/lcov-report/index.html

10. Docker et déploiement​

Build Docker échoue​

# Vérifier le Dockerfile
docker build -t mytv/api:latest . --no-cache

# Vérifier les étapes multi-stage
# Stage 1: npm ci + prisma generate + npm run build
# Stage 2: copie dist/ + node_modules (production)

Containers ne communiquent pas​

# Vérifier le réseau Docker
docker network ls
docker network inspect mytv-network

# Vérifier que les services sont sur le même réseau
docker-compose ps

Migration en production​

# Utiliser deploy (pas migrate:dev) en production
npx prisma migrate deploy

# Seed en production (via runner script)
docker exec -it mytv-api ./node_modules/.bin/prisma db seed

Profils Docker​

ProfilPortBase de donnéesUsage
dev3000PostgreSQL localDéveloppement
staging3000PostgreSQL stagingPré-production
prod3000PostgreSQL prodProduction
local3000PostgreSQL DockerCompatible legacy

11. Logs et monitoring​

Accéder aux logs​

# Logs NestJS (développement)
npm run start:dev  # Les logs sont dans la console

# Logs Docker
docker logs mytv-api --tail 100 -f
docker logs mytv-api 2>&1 | grep "ERROR"

# Logs structurés (production)
# Utiliser LoggerService de NestJS avec le context approprié

Alertes Prometheus​

# Vérifier les alertes actives
curl http://localhost:9090/api/v1/alerts

# Vérifier les règles d'alerte
cat monitoring/prometheus/alerts/*.yml

Dashboards Grafana​

DashboardURLMétriques
API Overviewhttp://localhost:3001/d/api-overviewRequêtes, latence, erreurs
Auth & Sessionshttp://localhost:3001/d/auth-sessionsLogins, sessions, sécurité
Databasehttp://localhost:3001/d/database-perfConnexions PostgreSQL
Businesshttp://localhost:3001/d/business-metricsUtilisateurs, paiements
Infrastructurehttp://localhost:3001/d/infrastructureCPU, mémoire, réseau

Métriques custom de l'API​

# Endpoint: GET /metrics
mytelevision_http_requests_total{method, path, status_code}
mytelevision_http_request_duration_seconds{method, path}
mytelevision_auth_login_total{provider, status}
mytelevision_auth_active_sessions_total
mytelevision_content_views_total{content_type, access_type}
mytelevision_payment_transactions_total{status, payment_method}

Contacts et ressources​

  • Swagger UI : http://localhost:3000/api/docs
  • Prisma Studio : npm run prisma:studio (port 5555)
  • Grafana : http://localhost:3001 (admin/admin)
  • Prometheus : http://localhost:9090
  • Collections Postman : ./postman/
  • Spécifications complètes : ./MASTER_SPEC.md
  • Conventions : ./CLAUDE.md