# Rapport Global de Livraison — Thinkers Backend API

**Date** : Février 2026
**Version** : 1.0.0
**Stack** : Node.js + TypeScript + Express + Prisma + MySQL

---

## 1. Endpoints livrés + exemples

### Public API

#### `GET /health`
```json
{ "status": "ok", "version": "1.0.0", "timestamp": "2026-02-25T10:00:00Z", "environment": "production" }
```

#### `GET /api/settings`
```json
{ "success": true, "data": { "site_name": "Tinkers Production", "phone": "+225 07 00 00 00 00", ... } }
```

#### `GET /api/services`
```json
{ "success": true, "data": [{ "id": 1, "title": "Production Vidéo", "slug": "production-video", "cover_image_url": "https://api.thinkers-production.com/uploads/services/uuid.jpg", ... }] }
```

#### `GET /api/gallery?type=photo&category=photographie&page=1&limit=12`
```json
{ "success": true, "data": { "items": [...], "page": 1, "limit": 12, "total": 50, "totalPages": 5 } }
```

#### `POST /api/contact`
```json
// Request
{ "name": "Jean Dupont", "email": "jean@example.com", "message": "Je suis intéressé par vos services.", "service_id": 1, "website": "" }
// Response 201
{ "success": true, "data": { "message": "Message sent successfully. We will get back to you soon." } }
```

#### `POST /api/contact` (honeypot rempli)
```json
// Retourne 201 silencieusement — ne révèle pas la détection bot
```

### Admin API

#### `POST /api/admin/auth/login`
```json
// Request
{ "email": "admin@thinkers-production.com", "password": "MonMotDePasse" }
// Response 200 + Set-Cookie: access_token (httpOnly), refresh_token (httpOnly)
{ "success": true, "data": { "user": { "id": 1, "email": "admin@...", "name": "Thinkers Admin", "is_admin": true } } }
```

#### `GET /api/admin/stats`
```json
{ "success": true, "data": { "counts": { "services": 4, "gallery": 12, "partners": 5, "messages": { "total": 30, "new": 3 } }, "recentMessages": [...] } }
```

#### `PATCH /api/admin/settings` (avec whitelist)
```json
// Request body
{ "site_name": "Tinkers Production", "email": "contact@thinkers-production.com", "unknown_key": "malicious" }
// Response 200
{ "success": true, "data": { "updated": ["site_name", "email"], "rejected": ["unknown_key"], "errors": ["Rejected unknown keys: unknown_key"] } }
```

---

## 2. Choix techniques et justifications

### Framework : Express.js (vs NestJS)

**Choix retenu : Express + TypeScript avec architecture modulaire**

| Critère | Express | NestJS |
|---------|---------|--------|
| Déploiement cPanel | ✅ Simple (node dist/main.js) | ⚠️ Lourd, overhead |
| Performance | ✅ Minimal overhead | ⚠️ DI container |
| Courbe d'apprentissage | ✅ Standard | Steep |
| Scope du projet | ✅ Adapté | Over-engineering |
| Production-ready | ✅ Avec bonne structure | ✅ |

### Base de données : MySQL (vs PostgreSQL)

**Choix retenu : MySQL**

- cPanel fournit MySQL nativement (phpMyAdmin, GUI)
- PostgreSQL nécessite une config serveur supplémentaire sur mutualisé
- Performance équivalente pour le scope de ce projet
- Prisma gère les deux identiquement

### ORM : Prisma

- Type-safety native avec TypeScript
- Migrations déclaratives propres
- Excellent DX (Prisma Studio pour la gestion de la DB en dev)
- Compatible MySQL et PostgreSQL

### Authentification : JWT httpOnly Cookies + Refresh Token

- **Access token** (15 min) : stocké en cookie httpOnly — inaccessible en JavaScript
- **Refresh token** (7 jours) : stocké en cookie httpOnly + en DB pour révocation
- **Rotation** des refresh tokens : chaque refresh génère un nouveau token
- Résistance aux attaques XSS (cookies httpOnly)

### Validation : Zod

- Schémas TypeScript natifs (inférence de types)
- Composable et maintenable
- Messages d'erreur précis pour le frontend

---

## 3. Points d'attention production (cPanel)

### Critique

1. **Secrets JWT** : Générer avec `openssl rand -hex 32`, JAMAIS les valeurs d'exemple
2. **COOKIE_SECURE=true** : Obligatoire en HTTPS production
3. **CORS_ORIGINS** : Contenir exactement les origines frontend (sans trailing slash)
4. **Dossier uploads** : `chmod 755 uploads/`, vérifier les permissions d'écriture
5. **Migrations** : Exécuter `npm run migrate` avant `npm run seed`, et avant chaque mise à jour

### Performance

6. **PM2** : Utiliser PM2 pour le redémarrage automatique et la gestion des logs
7. **NODE_ENV=production** : Désactive les logs de query Prisma, active les logs Winston en fichier

### Sécurité

8. **Rate limiting** : Login (10/15min/IP), Contact (3/5min/IP) — ajuster si nécessaire
9. **Whitelist settings** : Toute modification du whitelist `settings.whitelist.ts` doit être délibérée
10. **Uploads** : Max 8MB, MIME: jpg/jpeg/png/webp uniquement (configurable dans `.env`)

---

## 4. Cohérence avec le front Next.js (Codex)

### Endpoints attendus par le frontend

| Frontend consomme | Backend livre | Statut |
|-------------------|---------------|--------|
| `GET /api/settings` | ✅ `publicSettingsRouter` | Aligné |
| `GET /api/services` | ✅ `publicServicesRouter` | Aligné |
| `GET /api/services/:slug` | ✅ | Aligné |
| `GET /api/gallery?type=&category=&page=&limit=12` | ✅ Pagination standard | Aligné |
| `GET /api/gallery/categories` | ✅ | Aligné |
| `GET /api/partners` | ✅ | Aligné |
| `POST /api/contact` | ✅ + honeypot + rate limit | Aligné |
| `POST /api/admin/auth/login` | ✅ httpOnly cookie | Aligné |
| `GET /api/admin/auth/me` | ✅ | Aligné |
| `POST /api/admin/auth/logout` | ✅ | Aligné |
| `POST /api/admin/auth/refresh` | ✅ Rotation token | Aligné |
| Admin CRUD complet | ✅ Tous modules | Aligné |

### Format JSON

Toutes les réponses suivent le standard :
- **Succès** : `{ success: true, data: ... }`
- **Liste paginée** : `{ success: true, data: { items, page, limit, total, totalPages } }`
- **Erreur** : `{ success: false, error: { code, message, details } }`

### Champs image

Les URLs d'images sont toujours des URLs absolues calculées avec `UPLOADS_PUBLIC_URL` :
- `cover_image_url` pour les services
- `logo_url` pour les partenaires
- `file_url` + `thumbnail_url` pour la galerie

### Authentication (cookies)

Le frontend doit envoyer `credentials: 'include'` dans tous les fetch vers l'API admin :
```typescript
// Next.js
fetch('/api/admin/stats', { credentials: 'include' })
// ou Axios
axios.defaults.withCredentials = true;
```

---

## 5. Checklist de recette

### Recette Public

- [ ] `GET /health` → `{ status: "ok" }`
- [ ] `GET /api/settings` → objet clé-valeur des settings publics
- [ ] `GET /api/services` → tableau des services actifs avec `cover_image_url`
- [ ] `GET /api/services/production-video` → service par slug
- [ ] `GET /api/gallery?page=1&limit=12` → pagination correcte
- [ ] `GET /api/gallery?type=photo` → filtre par type
- [ ] `GET /api/gallery?type=video` → items vidéo avec `embed_url`
- [ ] `GET /api/gallery/categories` → liste des catégories
- [ ] `GET /api/partners` → partenaires actifs avec `logo_url`
- [ ] `POST /api/contact` (valide) → 201
- [ ] `POST /api/contact` (email invalide) → 422
- [ ] `POST /api/contact` (honeypot rempli) → 201 silencieux
- [ ] `POST /api/contact` (4ème req / 5min) → 429

### Recette Admin

- [ ] `POST /api/admin/auth/login` (mauvais mdp) → 401
- [ ] `POST /api/admin/auth/login` (correct) → 200 + cookies httpOnly
- [ ] `GET /api/admin/auth/me` (sans cookie) → 401
- [ ] `GET /api/admin/auth/me` (avec cookie) → 200 + user info
- [ ] `GET /api/admin/stats` → counts + messages récents
- [ ] `GET /api/admin/services` → liste paginée
- [ ] `POST /api/admin/services` (multipart + image) → 201
- [ ] `PATCH /api/admin/services/:id` → mise à jour
- [ ] `DELETE /api/admin/services/:id` → 204
- [ ] `GET /api/admin/gallery` → liste paginée avec filtres
- [ ] `POST /api/admin/gallery` (photo + thumbnail Sharp) → 201 + thumbnail_url
- [ ] `POST /api/admin/gallery` (vidéo YouTube) → embed_url calculé
- [ ] `GET /api/admin/partners` → liste
- [ ] `POST /api/admin/partners` (avec logo) → 201
- [ ] `GET /api/admin/messages` → liste avec statut
- [ ] `GET /api/admin/messages/:id` → auto-mark read
- [ ] `POST /api/admin/messages/:id/archive` → statut archived
- [ ] `DELETE /api/admin/messages/:id` → 204
- [ ] `GET /api/admin/settings` → groupé par group
- [ ] `PATCH /api/admin/settings` (clé valide) → updated: [key]
- [ ] `PATCH /api/admin/settings` (clé inconnue) → rejected: [key]
- [ ] `PATCH /api/admin/settings` (email invalide pour clé email) → error
- [ ] `POST /api/admin/auth/logout` → 200 + cookies effacés
- [ ] `GET /api/admin/auth/me` (après logout) → 401

---

## 6. Tests automatisés

```bash
npm run test
```

Tests couverts :
- ✅ Auth : login (succès/échec/non-admin), logout, me non-auth
- ✅ Settings whitelist : clés inconnues rejetées, validation email/url/text
- ✅ Contact : validation, honeypot, rate limit
- ✅ Gallery : pagination, filtres type/category, embed URL

---

## 7. Documentation

- **Swagger/OpenAPI** : `GET /docs` (interface interactive)
- **Spec JSON** : `GET /docs.json`
- **README** : [README.md](./README.md)
- **Déploiement** : [DEPLOY_CPANEL.md](./DEPLOY_CPANEL.md)