@mostajs/recette 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
 
+## 0.5.0 — 2026-10-29
+
+### Ajouté
+
+- **`enveloppeRapport(campagneId, { declaration?, note?, pieces? })`** — l'enveloppe
+  `mostajs-recette-rapport/1` sans signature, à tout moment de la campagne. `rapportEtape` la signe :
+  c'est la même. **T-REC-19**.
+- **`@mostajs/recette/archive`** (chemin à part, seul à importer `@mostajs/archive-box`, pair
+  facultatif) : `vueRapport`, `formulaireHtml`, `archiveRapport` — le formulaire rempli en HTML
+  autonome, en PDF si l'application injecte un convertisseur (sinon l'absence est écrite), le JSON,
+  l'enveloppe, et chaque pièce rangée sous la ligne à laquelle elle répond, liée depuis le
+  formulaire. Né dans QaTrax le 29/10/2026 (relire un questionnaire répondu en « ok »), demandé
+  aussi par ValiTrax : deux consommateurs, donc ici. **T-REC-20**.
+
+## 0.4.0 — 2026-10-23
+
+### Corrigé
+
+- **Le feu s'allumait sans certificat.** `campagnes.avancer` menait de « validation » à « figee »,
+  « certifiee » puis « exploitation » à qui cliquait trois fois — constaté le 23/10/2026 sur
+  REC-2026-0001, sans un point, ni dossier, ni certificat. Avancer à la main s'arrête désormais à
+  « validation » ; les trois étapes suivantes ne s'atteignent que par leur acte (`dossiers.figer`,
+  `certificats.recevoir`, `autoriserExploitation`). **T-REC-16**.
+- Une campagne arrivée en « exploitation » **sans certificat** peut être abandonnée : elle n'a jamais
+  été autorisée. Avec certificat, elle ne s'abandonne toujours pas. **T-REC-17**.
+
+### Ajouté
+
+- **`campagnes.reculer(id, { by, motif })`** — revenir d'une étape (validation → recette →
+  verification → candidate) tant que le dossier n'est pas figé ; l'historique garde le retour et son
+  motif. **T-REC-17**.
+- **`rapportEtape(campagneId, { declaration: 'partiel' | 'urgent', sceller, note })`** — le rapport
+  d'étape SIGNÉ (`mostajs-recette-rapport/1`) : relevés qui font foi, avec l'exigence, l'action,
+  l'attendu, la remarque et l'heure ; anomalies ; compteurs. Il ne fige rien et ne demande aucun PV :
+  il sert à CORRIGER pendant que la recette continue. `declaration: 'fini'` accompagne le dossier
+  final. `pieces` décrit les pièces jointes et captures d'écran (cible, nom, type, taille, SHA-256)
+  sous la signature ; leur contenu voyage à côté. **T-REC-18**.
+
+> **Rupture** : `campagnes.avancer(id, 'figee' | 'certifiee' | 'exploitation')` lève désormais une
+> erreur. Un appelant qui s'en servait doit passer par l'acte correspondant.
+
 ## 0.3.0 — 2026-10-23
 
 ### Corrigé

package/README.md

@@ -126,6 +126,28 @@ const { feuillet, cases } = await recette.feuillets.composer({ campagneId: c.id,
 // … consigner · rendre · figer · exporter · recevoir le certificat · autoriser l'exploitation
 ```
 
+## L'archive d'un rapport — `@mostajs/recette/archive` (0.5.0)
+
+Un questionnaire répondu en recette n'est fait que de « ok » avec une remarque : rien à corriger, mais tout à relire.
+L'archive rend le formulaire rempli et ses pièces, **chacune sous la ligne à laquelle elle répond**. QaTrax l'exporte
+d'un rapport reçu, ValiTrax d'une campagne : une seule fabrication, la même archive.
+
+```js
+import { vueRapport, archiveRapport } from '@mostajs/recette/archive';   // chemin à part : lui seul importe archive-box
+
+const enveloppe = await recette.enveloppeRapport(campagneId, { pieces });  // non signée, à tout moment
+const vue = vueRapport(enveloppe, { id, idDe: (sha) => maPiece(sha)?.id });
+const { buffer, nom } = await archiveRapport(vue, {
+  contenu: async (sha) => contenuDeMaPiece(sha),       // Buffer ou null (la pièce manquante est nommée dans l'archive)
+  pdf: async (html) => monConvertisseur(html),          // facultatif : sinon « PDF absent » est écrit, pas tu
+  enveloppe, sourceApp: 'valitrax',
+});
+```
+
+Contenu du zip : `LISEZMOI.txt`, `formulaire.html` (autonome, liens relatifs), `formulaire.pdf` (si un convertisseur
+est injecté), `rapport.json`, `enveloppe.json`, `pieces/<ligne>/<nom>`, et le manifeste `@mostajs/archive-box`
+(SHA-256 par fichier). Aucun appel réseau : le PDF vient de l'application.
+
 ## Signer et sceller ne sont pas la même chose
 
 | | avec quelle clé | ce que ça prouve |

package/llms.txt

@@ -8,6 +8,7 @@ QUESTION À LAQUELLE IL RÉPOND
 NIVEAU N3 · métier · forme : moteur · dépend de : aucun autre N3
   @mostajs/qa-engine n'est ni importé ni appelé : ce qui circule est un FICHIER SIGNÉ.
   @mostajs/crypto-box n'est importé que par `@mostajs/recette/sceau`, chemin à part.
+  @mostajs/archive-box n'est importé que par `@mostajs/recette/archive`, chemin à part (0.5.0).
 
 ENTITÉS (7)  Campagne · Point · Feuillet · Releve · Anomalie · Dossier · Certificat
 VERBES       ouvrir · synchroniser · importer · enrichir · retenir · composer · remettre · consigner ·
@@ -89,3 +90,14 @@ USAGE       createRecette({ repositories, ports: { sceau, trameSource, audit },
             creerSceau({ signature, destinataire, certificateur })  ← @mostajs/recette/sceau
             engendrerClefs()  ← une fois, à la mise en service ; les clés vont au coffre
 ESSAIS      npm test — 13 essais, tous sur ce que le moteur REFUSE
+
+ARCHIVE D'UN RAPPORT (0.5.0) — @mostajs/recette/archive
+  recette.enveloppeRapport(campagneId, { declaration?, note?, pieces? })  → mostajs-recette-rapport/1, NON signée,
+    à tout moment (rapportEtape la signe : même enveloppe).
+  vueRapport(enveloppe, { id?, recuLe?, piecesAbsentes?, idDe?(sha) })    → lignes { ref, exigence, issue, question,
+    attendu, reponse, le, pieces[{ id, nom, type, sha256, chemin }] }, anomalies, sansReponse.
+  formulaireHtml(vue, { emetteur? })                                       → page autonome, liens relatifs vers pieces/.
+  archiveRapport(vue, { contenu(sha) → Buffer|null, pdf?(html) → { ok, octets }, enveloppe?, sourceApp? })
+    → { buffer (zip archive-box), nom, sha256, pdf } : LISEZMOI, formulaire.html, formulaire.pdf (si pdf injecté,
+    sinon « PDF absent » dit), rapport.json, enveloppe.json, pieces/<ligne>/<nom> ; manifeste SHA-256.
+  Consommateurs : QaTrax (rapports reçus, PDF par mdseal), ValiTrax (export de la campagne).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/recette",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Validation & recette applicative : trame `mostajs-devtest/1` reçue signée du certificateur, points enrichis POUR LE CLIENT (l'import n'écrase jamais l'enrichissement), feuillets composés à l'image du manifeste PDF (ok/ko/er), anomalies déclarées puis qualifiées, dossier figé et EXPORTÉ SIGNÉ — aucun appel réseau —, certificat reçu et vérifié, feu d'exploitation DÉRIVÉ du certificat. Powers ValiTrax (valitrax.mostajs.dev).",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -10,7 +10,8 @@
     ".": "./src/index.js",
     "./schemas": "./src/schemas.js",
     "./register": "./src/register.js",
-    "./sceau": "./src/sceau.js"
+    "./sceau": "./src/sceau.js",
+    "./archive": "./src/archive.js"
   },
   "files": [
     "src",
@@ -71,12 +72,15 @@
       "lire une feuille papier photographiée": "@mostajs/ocr",
       "implémenter la cryptographie": "@mostajs/crypto-box — Ed25519 pour signer, enveloppe X25519 pour sceller",
       "déposer le dossier chez le certificateur": "personne : l'export est un FICHIER que le client ou notre service transporte",
-      "produire les formulaires du client": "ce module — QaTrax n'envoie que la TRAME (mostajs-devtest/1) ; la formulation appartient à la recette"
+      "produire les formulaires du client": "ce module — QaTrax n'envoie que la TRAME (mostajs-devtest/1) ; la formulation appartient à la recette",
+      "zipper et empreinter une archive": "@mostajs/archive-box — importé par le seul chemin `@mostajs/recette/archive`",
+      "convertir le formulaire en PDF": "un convertisseur INJECTÉ par l’application (mdseal chez QaTrax) — aucun appel réseau ici"
     }
   },
   "peerDependencies": {
     "@mostajs/mjs-unit": ">=0.4.0",
-    "@mostajs/crypto-box": ">=0.3.0"
+    "@mostajs/crypto-box": ">=0.3.0",
+    "@mostajs/archive-box": ">=0.2.0"
   },
   "peerDependenciesMeta": {
     "@mostajs/mjs-unit": {
@@ -84,9 +88,13 @@
     },
     "@mostajs/crypto-box": {
       "optional": true
+    },
+    "@mostajs/archive-box": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@mostajs/archive-box": "file:../../mosta-content-stack/mosta-archive-box",
     "@mostajs/crypto-box": "file:../../mosta-kernel-stack/mosta-crypto-box",
     "@mostajs/mjs-unit": "^0.6.0"
   }

package/src/archive.js

@@ -0,0 +1,141 @@
+// @mostajs/recette/archive — L'ARCHIVE D'UN RAPPORT DE RECETTE : le formulaire rempli, ses pièces sous leur ligne.
+// Author: Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+//
+// 29/10/2026 (demande du fondateur). Né dans QaTrax pour relire un questionnaire répondu dans ValiTrax — des relevés
+// « ok » avec une remarque, qui n'ouvrent aucun défaut — puis demandé aussi depuis ValiTrax : deux consommateurs, donc
+// le module. Les deux partent de la MÊME enveloppe `mostajs-recette-rapport/1` : `enveloppeRapport` (ValiTrax, à tout
+// moment) ou le rapport d'étape reçu (QaTrax).
+//
+//   - `vueRapport`     : le rapport relu ligne par ligne — question, attendu, réponse, heure, exigence, et SES pièces
+//                        (identifiant chez l'appelant, chemin dans l'archive) ;
+//   - `formulaireHtml` : le formulaire rempli, page autonome, qui renvoie à chaque pièce par un lien relatif ;
+//   - `archiveRapport` : un zip `@mostajs/archive-box` (manifeste, SHA-256 par fichier) — LISEZMOI, formulaire HTML,
+//                        formulaire PDF quand l'appelant fournit un convertisseur, JSON, enveloppe, `pieces/<ligne>/<nom>`.
+//
+// Chemin à part, comme `./sceau` : lui seul importe `@mostajs/archive-box`. Aucun appel réseau : le PDF vient d'une
+// fonction INJECTÉE (mdseal chez QaTrax) ; sans elle, l'archive le dit au lieu de se taire.
+import { buildArchive } from '@mostajs/archive-box';
+
+/** Les déclarations, dites au lecteur. `null` : un export à date, sans déclaration. */
+export const LIBELLES_DECLARATION = Object.freeze({ partiel: 'partiellement fini', urgent: 'l’urgent est fini', fini: 'fini' });
+
+const esc = (s = '') => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** Un segment de chemin sûr dans un zip : ni séparateur, ni caractère que Windows refuse, ni « . » ou « .. ». */
+const segment = (s, repli) => {
+  const x = String(s || '').replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').replace(/^\.+$/, '').trim().slice(0, 120);
+  return x || repli;
+};
+const lienRelatif = (chemin) => chemin.split('/').map(encodeURIComponent).join('/');
+const parRef = (a, b) => String(a.ref).localeCompare(String(b.ref), 'fr', { numeric: true });
+
+/**
+ * Le rapport relu ligne par ligne.
+ * @param {object} enveloppe  `mostajs-recette-rapport/1` (signée ou non : la signature n'est pas lue ici)
+ * @param {object} [o]
+ * @param {string} [o.id]  l'identifiant du rapport chez l'appelant
+ * @param {string} [o.recuLe]  quand il a été reçu (QaTrax) ou exporté (ValiTrax) ; défaut : `enveloppe.emisLe`
+ * @param {string[]} [o.piecesAbsentes]  pièces annoncées dont le contenu n'est pas arrivé
+ * @param {(sha256:string) => string|null} [o.idDe]  l'identifiant d'une pièce chez l'appelant (pour la télécharger)
+ */
+export function vueRapport(enveloppe, { id = null, recuLe = null, piecesAbsentes = [], idDe = () => null } = {}) {
+  const e = enveloppe || {};
+  const pris = new Set();
+  const ranger = (dossier, p) => {
+    const nom = segment(p.nom, 'piece');
+    let chemin = `pieces/${dossier}/${nom}`;
+    for (let i = 2; pris.has(chemin); i++) chemin = `pieces/${dossier}/${nom.replace(/(\.[^.]*)?$/, ` (${i})$1`)}`;
+    pris.add(chemin);
+    return { id: idDe(p.sha256) || null, nom: p.nom, type: p.type || 'application/octet-stream', taille: p.taille || 0, sha256: p.sha256, chemin };
+  };
+  const piecesDe = (cible, dossier) => (e.pieces || []).filter((p) => p.cible === cible).map((p) => ranger(dossier, p));
+  const lignes = [...(e.releves || [])].sort(parRef).map((x) => ({
+    ref: x.ref, exigence: x.specRef || null, issue: x.issue, question: x.action || '', attendu: x.attendu || '',
+    reponse: x.texte || '', le: x.at || null, pieces: piecesDe(x.ref, segment(x.ref, 'ligne')),
+  }));
+  const anomalies = (e.anomalies || []).map((a, i) => ({
+    titre: a.titre, description: a.description || '', gravite: a.graviteQualifiee || a.graviteProposee || null, etat: a.state || null,
+    declareePar: a.declareePar || null, pieces: piecesDe(`anomalie:${i}`, `anomalie-${i + 1}`),
+  }));
+  const retenus = Number(e.compteurs?.retenus) || 0;
+  return {
+    id, recuLe: recuLe || e.emisLe || null, projet: e.campagne?.projet || '', declaration: e.declaration || null,
+    declarationLibelle: LIBELLES_DECLARATION[e.declaration] || (e.declaration ? String(e.declaration) : 'relevé à date'),
+    note: e.note || '', campagne: e.campagne || {}, feuillets: e.feuillets || [], compteurs: e.compteurs || {},
+    sansReponse: Math.max(0, retenus - lignes.length), lignes, anomalies, piecesAbsentes,
+  };
+}
+
+/** Le formulaire rempli, en une page HTML autonome. `emetteur` : le nom affiché en pied. */
+export function formulaireHtml(v, { emetteur = '' } = {}) {
+  const ISSUE = { ok: ['ok', '#15803d'], ko: ['ko', '#b45309'], er: ['er', '#b91c1c'] };
+  const pastille = (i) => { const [t, c] = ISSUE[i] || [i || '—', '#64748b']; return `<span style="color:#fff;background:${c};border-radius:4px;padding:1px 6px;font-size:12px">${esc(t)}</span>`; };
+  const liens = (ps) => ps.map((p) => `<a href="${esc(lienRelatif(p.chemin))}">${esc(p.nom)}</a>`).join('<br>');
+  const heure = (s) => (s ? String(s).slice(0, 16).replace('T', ' ') : '');
+  const lignes = v.lignes.map((l) => `<tr><td><b>${esc(l.ref)}</b>${l.exigence ? `<br><small>${esc(l.exigence)}</small>` : ''}</td>
+    <td>${esc(l.question)}${l.attendu ? `<br><small>Attendu : ${esc(l.attendu)}</small>` : ''}</td>
+    <td style="white-space:pre-wrap">${esc(l.reponse) || '<i>—</i>'}</td><td>${pastille(l.issue)}<br><small>${esc(heure(l.le))}</small></td><td>${liens(l.pieces)}</td></tr>`).join('\n');
+  const anos = v.anomalies.map((a) => `<tr><td>${esc(a.titre)}<br><small>${esc(a.description)}</small></td><td>${esc(a.gravite || '')}</td><td>${liens(a.pieces)}</td></tr>`).join('\n');
+  return `<!doctype html>
+<html lang="fr"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(v.campagne.no || 'Rapport')} — ${esc(v.projet)}</title>
+<style>body{font-family:system-ui,sans-serif;color:#0f172a;margin:24px;line-height:1.4}table{border-collapse:collapse;width:100%;margin:12px 0}
+th,td{border:1px solid #cbd5e1;padding:6px 8px;vertical-align:top;text-align:left}th{background:#f1f5f9}small{color:#64748b}h1{font-size:20px;margin:0 0 4px}
+.meta{color:#475569;font-size:14px}@media print{a{color:inherit}}</style></head><body>
+<h1>${esc(v.campagne.no || '')} · ${esc(v.projet)}</h1>
+<p class="meta">${esc(v.declarationLibelle)} · ${esc(heure(v.recuLe))} UTC · ${esc(v.campagne.releaseRef || '')}${v.feuillets.length ? ` · ${v.feuillets.map((f) => `${esc(f.role)} : ${esc(f.destinataire || '—')}`).join(' · ')}` : ''}</p>
+${v.note ? `<p style="white-space:pre-wrap"><b>Note :</b> ${esc(v.note)}</p>` : ''}
+<p class="meta">${v.lignes.length} ligne(s) relevée(s)${v.sansReponse ? ` · ${v.sansReponse} ligne(s) retenue(s) sans réponse` : ''}${v.piecesAbsentes.length ? ` · pièce(s) non reçue(s) : ${v.piecesAbsentes.map(esc).join(', ')}` : ''}</p>
+<table><thead><tr><th>Réf.</th><th>Question / ce qui était à faire</th><th>Réponse / remarque</th><th>Relevé</th><th>Pièces</th></tr></thead><tbody>
+${lignes || '<tr><td colspan="5"><i>Aucune ligne relevée.</i></td></tr>'}
+</tbody></table>
+${anos ? `<h2 style="font-size:16px">Anomalies</h2><table><thead><tr><th>Titre</th><th>Gravité</th><th>Pièces</th></tr></thead><tbody>${anos}</tbody></table>` : ''}
+<p class="meta">${v.id ? `Rapport ${esc(v.id)}` : ''}${v.id && emetteur ? ' · ' : ''}${esc(emetteur)}</p>
+</body></html>
+`;
+}
+
+/**
+ * L'archive d'un rapport.
+ * @param {object} v  `vueRapport(...)`
+ * @param {object} o
+ * @param {(sha256:string) => Promise<Buffer|null>} o.contenu  le contenu d'une pièce chez l'appelant
+ * @param {(html:string) => Promise<{ok:boolean, octets?:Buffer, motif?:string}>} [o.pdf]  un convertisseur, facultatif
+ * @param {string} [o.pdfAbsent]  ce que dit l'archive quand aucun convertisseur n'est fourni
+ * @param {object} [o.enveloppe]  l'enveloppe, versée telle quelle (`enveloppe.json`)
+ * @param {string} [o.sourceApp]  l'application qui exporte (`qatrax`, `valitrax`)
+ * @returns {Promise<{buffer:Buffer, nom:string, sha256:string, pdf:boolean}>}
+ */
+export async function archiveRapport(v, { contenu, pdf = null, pdfAbsent = 'aucun convertisseur PDF configuré', enveloppe = null, emetteur = '', creePar = '', sourceApp = '' } = {}) {
+  const html = formulaireHtml(v, { emetteur });
+  const files = [{ path: 'formulaire.html', content: html }, { path: 'rapport.json', content: `${JSON.stringify(v, null, 2)}\n` }];
+  if (enveloppe) files.push({ path: 'enveloppe.json', content: `${JSON.stringify(enveloppe, null, 2)}\n` });
+  const manquantes = [];
+  for (const p of [...v.lignes, ...v.anomalies].flatMap((x) => x.pieces)) {
+    const b = await contenu(p.sha256);
+    if (b) files.push({ path: p.chemin, content: b }); else manquantes.push(p.chemin);
+  }
+  let motifPdf = pdfAbsent;
+  let avecPdf = false;
+  if (pdf) {
+    try {
+      const r = await pdf(html);
+      if (r?.ok && r.octets?.length) { files.push({ path: 'formulaire.pdf', content: r.octets }); avecPdf = true; } else motifPdf = r?.motif || 'le convertisseur n’a rien rendu';
+    } catch (e) { motifPdf = e?.message || String(e); }
+  }
+  const lisezmoi = [
+    `${v.campagne.no || 'Rapport'} — ${v.projet} — ${v.declarationLibelle}`, '',
+    'formulaire.html   le formulaire rempli : chaque ligne, sa réponse, ses pièces (liens relatifs : dépliez l’archive avant d’ouvrir)',
+    avecPdf ? 'formulaire.pdf    le même formulaire en PDF' : `formulaire.pdf    PDF absent : ${motifPdf}`,
+    'rapport.json      les mêmes données, pour un programme',
+    ...(enveloppe ? ['enveloppe.json    le rapport tel que la recette l’a relevé (mostajs-recette-rapport/1)'] : []),
+    'pieces/<ligne>/   chaque pièce jointe, rangée sous la ligne à laquelle elle répond',
+    'manifest.json     l’empreinte SHA-256 de chaque fichier', '',
+    ...(manquantes.length ? [`Pièce(s) annoncée(s) mais non reçue(s) : ${manquantes.join(', ')}`, ''] : []),
+  ].join('\n');
+  files.unshift({ path: 'LISEZMOI.txt', content: `${lisezmoi}\n` });
+  const nom = `${segment(v.campagne.no, 'rapport')}-${segment(v.projet, 'projet')}`.replace(/\s+/g, '_');
+  const a = await buildArchive({ files, name: nom, description: `Rapport de recette ${v.campagne.no || ''} (${v.declarationLibelle})`, kind: 'recette-rapport',
+    createdBy: creePar || undefined, sourceApp: sourceApp || undefined,
+    extra: { projet: v.projet, campagne: v.campagne.no || null, rapport: v.id, pdf: avecPdf ? 'joint' : 'absent', ...(avecPdf ? {} : { pdfMotif: motifPdf }), piecesManquantes: manquantes } });
+  return { buffer: a.buffer, nom: `${nom}.zip`, sha256: a.sha256, pdf: avecPdf };
+}

package/src/recette.js

@@ -62,7 +62,11 @@ export function createRecette({ repositories, ports = {}, clock = () => new Date
     if (vers === 'abandonnee') {
       // On abandonne de partout, sauf une fois l'exploitation autorisée : à ce moment le logiciel
       // est en production, et « abandonner la recette » ne veut plus rien dire.
-      if (campagne.state === 'exploitation') throw new Error("l'exploitation est autorisée : la campagne ne s'abandonne plus");
+      // 0.4.0 — SAUF si elle y est arrivée SANS certificat : avant cette version, `campagnes.avancer` menait de
+      // « validation » à « exploitation » par trois clics (constaté le 23/10/2026, REC-2026-0001, 0 point). Une telle
+      // campagne n'a jamais été autorisée ; la garder irrécupérable serait garder l'erreur.
+      if (campagne.state === 'exploitation' && (await certificats.of(campagne.id))) throw new Error("l'exploitation est autorisée : la campagne ne s'abandonne plus");
+      if (campagne.state === 'abandonnee') throw new Error('la campagne est déjà abandonnée');
     } else {
       const de = rang(campagne.state), a = rang(vers);
       if (a < 0) throw new Error(`étape inconnue : ${vers}`);
@@ -96,7 +100,37 @@ export function createRecette({ repositories, ports = {}, clock = () => new Date
     },
     get: getCampagne,
     list: (filtre = () => true) => repo.campagnes.find(filtre),
-    avancer: async (id, vers, opts) => avancer(await getCampagne(id), vers, opts),
+    /**
+     * AVANCER À LA MAIN — seulement les étapes de TRAVAIL : verification, recette, validation (et l'abandon).
+     *
+     * 0.4.0 : « figee », « certifiee » et « exploitation » ne se franchissent QUE par leur acte — figer le dossier,
+     * recevoir le certificat, autoriser l'exploitation. Avant, ce verbe public les accordait à qui cliquait trois fois,
+     * et le feu « dérivé du certificat » s'allumait sans certificat.
+     */
+    avancer: async (id, vers, opts) => {
+      const ACTE = { figee: '« figer le dossier »', certifiee: '« recevoir le certificat »', exploitation: '« autoriser l’exploitation » (avec un certificat qui la permet)' };
+      if (ACTE[vers]) throw new Error(`« ${vers} » ne s'atteint pas en avançant : il faut ${ACTE[vers]}`);
+      return avancer(await getCampagne(id), vers, opts);
+    },
+    /**
+     * REVENIR D'UNE ÉTAPE (0.4.0) — tant que le dossier n'est pas figé : validation → recette → verification → candidate.
+     * Une recette relancée parce qu'une correction est arrivée n'est pas une faute ; l'historique garde le retour et son motif.
+     */
+    async reculer(id, { by = null, motif = '' } = {}) {
+      const c = await getCampagne(id);
+      const de = rang(c.state);
+      if (!['verification', 'recette', 'validation'].includes(c.state)) {
+        throw new Error(`on ne revient pas en arrière depuis « ${c.state} »${rang(c.state) >= rang('figee') ? ' : le dossier est figé, ouvrez une nouvelle campagne' : ''}`);
+      }
+      const vers = PARCOURS[de - 1];
+      const at = clock();
+      const out = await repo.campagnes.update(c.id, {
+        state: vers,
+        stateHistory: [...(c.stateHistory || []), { from: c.state, to: vers, at, by, reason: `retour : ${motif || 'sans motif'}` }],
+      });
+      await trace('recette.campagne.reculer', by, { campagneId: c.id, from: c.state, to: vers, motif });
+      return out;
+    },
   };
 
   /** Les champs que l'import a le droit d'écrire. Tout le reste appartient à ValiTrax. */
@@ -537,5 +571,67 @@ export function createRecette({ repositories, ports = {}, clock = () => new Date
     };
   }
 
-  return { campagnes, trame, points, feuillets, releves, anomalies, dossiers, certificats, autoriserExploitation, etat, PARCOURS };
+  /**
+   * LE RAPPORT D'ÉTAPE (0.4.0) — ce que le client déclare EN COURS de recette : « partiellement fini », ou « l'urgent est
+   * fini ». Il part vers QaTrax SIGNÉ (et scellé si son destinataire est configuré), comme le dossier ; mais il ne fige rien
+   * et ne demande aucun PV : il sert à CORRIGER — chaque `ko`, chaque `er`, chaque anomalie y devient un défaut à traiter
+   * pendant que la recette continue. Le dossier final, lui, reste l'affaire de `dossiers.figer` puis `exporter`.
+   */
+  // « fini » accompagne le dossier final : le dossier porte le PV, le rapport porte de quoi corriger (et les pièces).
+  const DECLARATIONS = ['partiel', 'urgent', 'fini'];
+  /**
+   * @param {Array} [pieces]  les pièces jointes DÉCRITES — `{ cible: '<réf>' | 'anomalie:<n>', nom, type, taille, sha256 }`.
+   *   Leur CONTENU voyage à côté de l'enveloppe ; la signature couvre leurs empreintes : une pièce échangée en chemin
+   *   ne correspond plus.
+   */
+  /**
+   * L'ENVELOPPE D'UN RAPPORT (0.5.0) — ce que la campagne a relevé, sans signer ni envoyer : le contenu même du rapport
+   * d'étape. `rapportEtape` la signe pour QaTrax ; `@mostajs/recette/archive` en fait l'archive que le client exporte
+   * (formulaire rempli, pièces sous leur ligne). Sans `declaration`, c'est un relevé à date, à tout moment de la campagne.
+   */
+  async function enveloppeRapport(campagneId, { declaration = null, note = '', pieces = [] } = {}) {
+    const c = await getCampagne(campagneId);
+    const fs = await feuillets.of(campagneId);
+    const rs = derniers(await releves.of(campagneId));
+    const as = await anomalies.of(campagneId);
+    const ps = await points.of(campagneId);
+    const parRef = new Map(ps.map((p) => [p.ref, p]));
+    const enveloppe = {
+      type: 'mostajs-recette-rapport/1',
+      emisLe: clock().toISOString(),
+      declaration, note: String(note || ''),
+      campagne: { no: c.no, releaseRef: c.releaseRef, projet: c.projet, instanceUrl: c.instanceUrl, state: c.state },
+      feuillets: fs.map((f) => ({ role: f.role, destinataire: f.destinataire || '', state: f.state })),
+      // Chaque relevé porte de quoi le CORRIGER : l'exigence, ce que le testeur devait faire et voir, sa remarque, l'heure.
+      releves: rs.map((r) => {
+        const p = parRef.get(r.ref);
+        return { ref: r.ref, issue: r.issue, at: r.at, texte: r.texte || '', specRef: p?.specRef || null,
+          action: p?.libelle || p?.titreTrame || '', attendu: p?.attendu || (p?.etapesTrame || []).map((e) => e.expected).filter(Boolean).join(' · ') };
+      }),
+      anomalies: as.map((a) => ({ titre: a.titre, description: a.description || '', graviteProposee: a.graviteProposee, graviteQualifiee: a.graviteQualifiee, state: a.state, declareePar: a.declareePar })),
+      compteurs: { ...compter(rs), retenus: ps.filter((p) => p.retenu).length },
+      pieces: (pieces || []).map((x) => ({ cible: String(x.cible || ''), nom: String(x.nom || ''), type: String(x.type || ''), taille: Number(x.taille) || 0, sha256: String(x.sha256 || '') })),
+    };
+    for (const x of enveloppe.pieces) if (!/^[0-9a-f]{64}$/.test(x.sha256)) throw new Error(`pièce « ${x.nom} » : empreinte SHA-256 absente ou invalide`);
+    return enveloppe;
+  }
+
+  async function rapportEtape(campagneId, { declaration, by = null, sceller = false, note = '', pieces = [] } = {}) {
+    const c = await getCampagne(campagneId);
+    if (!DECLARATIONS.includes(declaration)) throw new Error(`déclaration inconnue : ${declaration} (attendu : ${DECLARATIONS.join(' ou ')})`);
+    if (!['verification', 'recette', 'validation'].includes(c.state)) throw new Error(`un rapport d'étape s'envoie pendant la recette (la campagne est « ${c.state} »)`);
+    const sceau = ports.sceau;
+    if (!sceau?.signer) throw new Error("aucun sceau configuré : un rapport non signé ne prouve rien, il est refusé");
+    const enveloppe = await enveloppeRapport(campagneId, { declaration, note, pieces });
+    const signature = await sceau.signer(JSON.stringify(enveloppe));
+    let corps = { enveloppe, signature };
+    if (sceller) {
+      if (!sceau.sceller) throw new Error("scellement demandé mais aucun destinataire configuré (clé publique du certificateur)");
+      corps = { type: 'mostajs-recette-scelle/1', scelle: await sceau.sceller(JSON.stringify(corps)) };
+    }
+    await trace('recette.rapport.etape', by, { campagneId, declaration });
+    return corps;
+  }
+
+  return { campagnes, trame, points, feuillets, releves, anomalies, dossiers, certificats, autoriserExploitation, rapportEtape, enveloppeRapport, etat, PARCOURS };
 }