feat(api): /api/v1/grid calcule le fournisseur à la demande

L'API lisait uniquement la table grid_rows, écrite en effet de bord quand un
humain ouvre la page Grille. Un fournisseur jamais ouvert renvoyait donc
202 not_ready : une app ou un agent externe ne pouvait consulter que ce qui
avait déjà été parcouru dans l'interface, ce qui vide l'API de son intérêt.

/api/v1/grid déclenche désormais getProductRows() quand l'instantané manque.
Le calcul est déjà protégé en amont (cache 10 min + verrou anti-concurrence)
et persiste l'instantané, donc seul le premier appel paie le coût ; les
suivants repassent par le chemin SQL rapide.

- compute=1 (défaut) : calcul à la demande, meta.computedOnDemand signale
  quand il a eu lieu. compute=0 : comportement strict d'avant.
- Fournisseur inconnu ou sans article : 404 explicite, distinct d'une panne
  (500) et de « pas encore calculé » (202).
- /api/v1/products/{codein} fait de même lorsque `fournisseur` est fourni,
  le calcul se faisant par lot fournisseur.
- openapi.json mis à jour : c'est ce document que lit un agent externe, il
  annonçait « aucun endpoint ne déclenche de recalcul ».

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26nRZxTR57K7h8yqsF675

src/app/api/v1/openapi.json/route.ts

@@ -54,10 +54,12 @@ export async function GET(req: NextRequest) {
             description:
                 "Lecture des données de la grille CollectFlow : ventes sur 12 mois par magasin, stock, marges, "
                 + "gammes et métriques du réseau Qlik (~270 magasins Foir'Fouille), plus la recherche de produits.\n\n"
-                + "**Aucun endpoint ne déclenche de recalcul ni d'appel à Qlik.** Les réponses proviennent de "
-                + "données déjà persistées : l'instantané de grille, écrit quand la Grille est calculée dans "
-                + "l'application, et le cache des métriques réseau. Un fournisseur dont l'instantané n'existe pas "
-                + "encore renvoie `202 not_ready`.\n\n"
+                + "**N'importe quel fournisseur peut être interrogé directement.** Les réponses sont servies "
+                + "depuis un instantané persisté ; si le fournisseur demandé n'en a pas encore, `/grid` le calcule "
+                + "à la demande. Ce premier appel prend alors plusieurs secondes, les suivants sont immédiats. "
+                + "Passez `compute=0` pour refuser ce calcul et obtenir un `202 not_ready` immédiat.\n\n"
+                + "**Aucun endpoint ne contacte Qlik en direct** : les métriques réseau viennent d'un cache "
+                + "alimenté par une synchronisation séparée.\n\n"
                 + "Deux informations sont relues à chaque appel car elles évoluent indépendamment : les métriques "
                 + "réseau Qlik (`network`, `null` s'il n'y en a pas) et la gamme serveur non modifiée "
                 + "(`codeGammeServeur`).",
@@ -190,8 +192,10 @@ export async function GET(req: NextRequest) {
                     summary: "Lister les produits d'un fournisseur",
                     description:
                         "Lignes de grille d'un fournisseur : ventes 12 mois, stock, marges, gammes et métriques "
-                        + "réseau. Renvoie `202 not_ready` si les données de ce fournisseur n'ont pas encore été "
-                        + "calculées — le signaler, plutôt que de conclure à l'absence de produits.",
+                        + "réseau. Fonctionne pour **n'importe quel** fournisseur : si ses données n'ont jamais été "
+                        + "calculées, l'API les calcule à la demande (premier appel de quelques secondes, "
+                        + "`meta.computedOnDemand = true`). Un `404` signifie que le code fournisseur n'existe pas "
+                        + "ou n'a aucun article — le signaler plutôt que de conclure à une panne.",
                     parameters: [
                         { name: "fournisseur", in: "query", required: true, schema: { type: "string" }, description: "Code fournisseur (voir listerFournisseurs)." },
                         { name: "gamme", in: "query", schema: { type: "string" }, description: "Filtre sur la gamme (A, B, C, D, Z)." },
@@ -199,6 +203,14 @@ export async function GET(req: NextRequest) {
                         { name: "code2", in: "query", schema: { type: "string" }, description: "Filtre nomenclature niveau 2." },
                         { name: "code3", in: "query", schema: { type: "string" }, description: "Filtre nomenclature niveau 3." },
                         { name: "search", in: "query", schema: { type: "string" }, description: "Filtre texte : libellé, codein, GTIN, référence ou code centrale." },
+                        {
+                            name: "compute",
+                            in: "query",
+                            schema: { type: "string", enum: ["0", "1"], default: "1" },
+                            description:
+                                "1 (défaut) : calcule les données du fournisseur si elles n'existent pas encore. "
+                                + "0 : refuse le calcul et répond immédiatement 202 not_ready.",
+                        },
                         ...sortParams,
                         ...paginationParams,
                     ],
@@ -218,9 +230,10 @@ export async function GET(req: NextRequest) {
                                 },
                             },
                         },
-                        "202": { description: "Données pas encore calculées pour ce fournisseur", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
+                        "202": { description: "Données pas encore calculées (uniquement avec compute=0)", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
                         "400": { description: "Paramètres invalides", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
                         "401": { description: "Clé d'API absente, invalide ou révoquée", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
+                        "404": { description: "Fournisseur inconnu ou sans article", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
                     },
                 },
             },