Add sandbox/live environments to API doc, update TASK_CHECKUP for JWT auth

API doc: - Add sandbox (/api/sandbox) and live (/api/live) environments with badges - Auth (/api/auth/login) is shared between environments - Endpoint paths show both prefixes: /api/sandbox|/api/live/... - Auth endpoints show path without prefix TASK_CHECKUP: - Replace API key auth with JWT auth (ETicket-Email + ETicket-JWT headers) - All routes use {env} prefix (sandbox/live) - /mon-compte API tab redirects to /api/doc - Sandbox: read-only mode (POST/PATCH/DELETE return result without DB modification) - Mark documentation tasks as done Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 18:58:17 +01:00
parent ece406d50e
commit 2e01f1f4c0
3 changed files with 77 additions and 29 deletions
--- a/TASK_CHECKUP.md
+++ b/TASK_CHECKUP.md
@@ -42,46 +42,53 @@

 ### API Organisateur (portail orga + scanner mobile)

-#### Authentification & clés API
- [ ] Ajouter un champ `apiKey` (string 64, unique, nullable) à l'entité User + migration
- [ ] Page /mon-compte/api : générer, afficher, régénérer, révoquer la clé API (bin2hex(random_bytes(32)))
- [ ] Créer un `ApiKeyAuthenticator` custom Symfony (header `X-API-Key`) pour les routes `/api/*`
- [ ] Rate limiting spécifique API (60 req/min par clé)
- [ ] Audit log à chaque génération/révocation de clé API
+#### Environnements
+- Sandbox (test, données non modifiées) : `/api/sandbox/*`
+- Live (production, données réelles) : `/api/live/*`
+- Auth commune aux deux : `/api/auth/login`
+
+#### Authentification JWT
+- [ ] POST `/api/auth/login` : authentification email + password, retourne un JWT token (24h)
+- [ ] Headers requis sur toutes les routes : `ETicket-Email` + `ETicket-JWT`
+- [ ] Créer un `JwtAuthenticator` custom Symfony pour les routes `/api/sandbox/*` et `/api/live/*`
+- [ ] Rate limiting spécifique API (60 req/min par token)
+- [ ] Onglet /mon-compte API → redirige vers /api/doc

 #### Événements
- [ ] GET `/api/events` : liste des événements de l'orga (id, title, startAt, endAt, address, city, isOnline, isSecret)
- [ ] GET `/api/events/{id}` : détail d'un événement avec catégories et billets (nom, prix, quantité, quantité vendue, type)
- [ ] GET `/api/events/{id}/stats` : stats de l'événement (CA, nb commandes, nb billets vendus, nb billets scannés)
+- [ ] GET `/api/{env}/events` : liste des événements de l'orga (id, title, startAt, endAt, address, city, isOnline, isSecret)
+- [ ] GET `/api/{env}/events/{id}` : détail d'un événement avec catégories et billets (nom, prix, quantité, quantité vendue, type)
+- [ ] GET `/api/{env}/events/{id}/stats` : stats de l'événement (CA, nb commandes, nb billets vendus, nb billets scannés)

 #### Commandes
- [ ] GET `/api/events/{id}/orders` : liste des commandes (orderNumber, status, firstName, lastName, email, totalHT, paidAt, items[])
- [ ] GET `/api/events/{id}/orders?status=paid` : filtrage par statut (pending, paid, cancelled, refunded)
- [ ] GET `/api/orders/{orderNumber}` : détail d'une commande avec items et tickets générés
+- [ ] GET `/api/{env}/events/{id}/orders` : liste des commandes (orderNumber, status, firstName, lastName, email, totalHT, paidAt, items[])
+- [ ] GET `/api/{env}/events/{id}/orders?status=paid` : filtrage par statut (pending, paid, cancelled, refunded)
+- [ ] GET `/api/{env}/orders/{orderNumber}` : détail d'une commande avec items et tickets générés

 #### Scanner (application mobile)
- [ ] GET `/api/events/{id}/tickets` : liste des billets générés (reference, billetName, state, isInvitation, firstScannedAt, buyerName)
- [ ] POST `/api/scan` : scanner un billet (body: {reference}) → decode QR, vérifier reference, vérifier state, marquer scanné (firstScannedAt), gérer sortie définitive (hasDefinedExit), retourner infos billet + acheteur
- [ ] POST `/api/scan/verify` : vérifier un billet sans le scanner (lecture seule, retourne state + infos)
- [ ] GET `/api/events/{id}/scan-stats` : stats de scan temps réel (nb scannés, nb restants, nb invalides, dernier scan)
+- [ ] GET `/api/{env}/events/{id}/tickets` : liste des billets générés (reference, billetName, state, isInvitation, firstScannedAt, buyerName)
+- [ ] POST `/api/{env}/scan` : scanner un billet (body: {reference}) → decode QR, vérifier reference, vérifier state, marquer scanné (firstScannedAt), gérer sortie définitive (hasDefinedExit), retourner infos billet + acheteur
+- [ ] POST `/api/{env}/scan/verify` : vérifier un billet sans le scanner (lecture seule, retourne state + infos)
+- [ ] GET `/api/{env}/events/{id}/scan-stats` : stats de scan temps réel (nb scannés, nb restants, nb invalides, dernier scan)

 #### Billets & Stock
- [ ] GET `/api/events/{id}/billets` : liste des billets avec stock (nom, prix, quantity, quantitéVendue, type, isGeneratedBillet)
- [ ] PATCH `/api/billets/{id}/stock` : modifier le stock d'un billet (body: {quantity})
+- [ ] GET `/api/{env}/events/{id}/billets` : liste des billets avec stock (nom, prix, quantity, quantitéVendue, type, isGeneratedBillet)
+- [ ] PATCH `/api/{env}/billets/{id}/stock` : modifier le stock d'un billet (body: {quantity})

 #### Export
- [ ] GET `/api/events/{id}/export/orders.csv` : export CSV des commandes de l'événement
- [ ] GET `/api/events/{id}/export/tickets.csv` : export CSV des billets/entrées scannées
+- [ ] GET `/api/{env}/events/{id}/export/orders.csv` : export CSV des commandes de l'événement
+- [ ] GET `/api/{env}/events/{id}/export/tickets.csv` : export CSV des billets/entrées scannées

 #### Réponses & format
 - [ ] Toutes les réponses en JSON avec structure uniforme : `{success: bool, data: {...}, error: ?string}`
 - [ ] Pagination sur les listes (query params: page, limit, max 100)
 - [ ] Codes HTTP standards (200, 201, 400, 401, 403, 404, 429)
 - [ ] Vérifier que l'orga ne peut accéder qu'à ses propres événements/commandes
+- [ ] Sandbox : lecture seule (POST/PATCH/DELETE retournent le résultat sans modifier la DB)

-#### Documentation & SDK
- [ ] Générer un fichier `api-spec.json` (OpenAPI 3.1) décrivant tous les endpoints
- [ ] Page /mon-compte/api/documentation : afficher la doc interactive (swagger-ui ou redoc)
+#### Documentation
+- [x] Page /api/doc : documentation custom avec design brutal (pas de Swagger externe)
+- [x] Spec JSON disponible à /api/doc/spec.json
+- [x] Environnements sandbox/live documentés
 - [ ] Tests PHPUnit pour tous les endpoints API (auth, CRUD, scan, edge cases)

 ### Billetterie — Manquants
--- a/src/Controller/ApiDocController.php
+++ b/src/Controller/ApiDocController.php
@@ -13,6 +13,7 @@ class ApiDocController extends AbstractController
    {
        return $this->render('api/doc.html.twig', [
            'sections' => $this->getApiSpec(),
+            'environments' => $this->getEnvironments(),
        ]);
    }

@@ -22,6 +23,31 @@ class ApiDocController extends AbstractController
        return $this->json($this->getApiSpec());
    }

+    /**
+     * @return list<array{name: string, slug: string, baseUrl: string, description: string, badge: string, badgeColor: string}>
+     */
+    private function getEnvironments(): array
+    {
+        return [
+            [
+                'name' => 'Sandbox',
+                'slug' => 'sandbox',
+                'baseUrl' => '/api/sandbox',
+                'description' => 'Environnement de test. Les donnees ne sont pas modifiees. Ideal pour developper et tester votre integration.',
+                'badge' => 'TEST',
+                'badgeColor' => 'bg-orange-500',
+            ],
+            [
+                'name' => 'Live',
+                'slug' => 'live',
+                'baseUrl' => '/api/live',
+                'description' => 'Environnement de production. Les donnees sont reelles. A utiliser uniquement en production.',
+                'badge' => 'PROD',
+                'badgeColor' => 'bg-green-600',
+            ],
+        ];
+    }
+
    /**
     * @return list<array<string, mixed>>
     */
--- a/templates/api/doc.html.twig
+++ b/templates/api/doc.html.twig
@@ -16,10 +16,6 @@
            <p class="text-lg font-bold text-gray-300 max-w-2xl">Documentation complete de l'API REST pour les organisateurs. Gestion des evenements, commandes, billets et scan.</p>

            <div class="mt-8 flex flex-wrap gap-4">
-                <div class="border-2 border-gray-700 bg-gray-800 px-4 py-3">
-                    <p class="text-[10px] font-black uppercase tracking-widest text-gray-500 mb-1">Base URL</p>
-                    <p class="font-mono font-bold text-sm text-[#fabf04]">https://ticket.e-cosplay.fr/api</p>
-                </div>
                <div class="border-2 border-gray-700 bg-gray-800 px-4 py-3">
                    <p class="text-[10px] font-black uppercase tracking-widest text-gray-500 mb-1">Format</p>
                    <p class="font-mono font-bold text-sm">JSON (application/json)</p>
@@ -30,6 +26,21 @@
                </div>
            </div>

+            <div class="mt-8 grid grid-cols-1 sm:grid-cols-2 gap-4">
+                {% for env in environments %}
+                <div class="border-2 border-gray-700 bg-gray-800 p-4">
+                    <div class="flex items-center gap-2 mb-2">
+                        <span class="{{ env.badgeColor }} text-white text-[10px] font-black uppercase tracking-widest px-2 py-0.5">{{ env.badge }}</span>
+                        <span class="font-black text-sm uppercase tracking-tighter">{{ env.name }}</span>
+                    </div>
+                    <p class="font-mono font-bold text-sm text-[#fabf04] mb-2">https://ticket.e-cosplay.fr{{ env.baseUrl }}</p>
+                    <p class="text-xs font-bold text-gray-400">{{ env.description }}</p>
+                </div>
+                {% endfor %}
+            </div>
+
+            <p class="mt-4 text-xs font-bold text-gray-400">L'authentification (<span class="font-mono">/api/auth/login</span>) est commune aux deux environnements : <span class="font-mono text-[#fabf04]">https://ticket.e-cosplay.fr/api/auth/login</span></p>
+
            <div class="mt-8">
                <a href="{{ path('app_api_doc_json') }}" target="_blank" class="inline-flex items-center gap-2 px-6 py-3 border-4 border-[#fabf04] bg-[#fabf04] text-gray-900 font-black uppercase text-xs tracking-widest shadow-[6px_6px_0px_rgba(0,0,0,1)] hover:shadow-[8px_8px_0px_rgba(0,0,0,1)] hover:translate-y-[-2px] transition-all">
                    <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"/></svg>
@@ -130,8 +141,12 @@
                    <div class="{{ method_colors[endpoint.method] ?? 'bg-gray-600' }} text-white px-4 py-3 flex items-center min-w-[80px] justify-center">
                        <span class="font-black text-xs tracking-widest">{{ endpoint.method }}</span>
                    </div>
-                    <div class="flex-1 bg-gray-900 text-white px-4 py-3 flex items-center">
-                        <code class="font-mono font-bold text-sm">{{ endpoint.path }}</code>
+                    <div class="flex-1 bg-gray-900 text-white px-4 py-3 flex items-center gap-2 flex-wrap">
+                        {% if endpoint.path starts with '/api/auth' %}
+                            <code class="font-mono font-bold text-sm">{{ endpoint.path }}</code>
+                        {% else %}
+                            <code class="font-mono font-bold text-sm"><span class="text-orange-400">/api/sandbox</span><span class="text-gray-500">|</span><span class="text-green-400">/api/live</span>{{ endpoint.path|replace({'/api': ''}) }}</code>
+                        {% endif %}
                    </div>
                </div>