Les choix d’ingénierieÉtudes de cas techniques11 min de lecture
Une veille qui dit ce qu’elle n’a pas pu lire
Il n’y a ni file d’attente ni astreinte, donc rien ne garantit qu’une commande payée soit expédiée ou qu’un remboursement parte. Chaque matin, l’ERP cherche dans ses données ce qui ne devrait pas durer, et il fait la différence entre « rien à signaler » et « je n’ai pas pu regarder ».
Le problème
Le logiciel n’a ni file d’attente durable ni astreinte (Dette, risques et évolutions). Quand une étape lève une erreur, l’alerte part tout de suite. Sauf qu’une bonne partie de ce qui tourne mal dans un magasin ne lève aucune erreur. Par exemple : une commande payée que personne n’expédie, une rétractation reçue dont le remboursement n’est pas parti, de l’argent arrivé chez Stripe sur une commande que l’ERP a refusée, ou un trou dans la numérotation des factures. Pour le code, chacune de ces situations est un état valide.
L’audit du backend du 31 août 2026 en a fait son premier point. Celui du 6 septembre a posé la question comme ça : « si la boutique encaissait demain, qu’est-ce qui casserait en silence, et qui l’apprendrait ? » (c71be614ed).
Les contraintes
- L’équipe n’a pas d’informaticien et ne regarde aucun écran de supervision. Elle lit ses e-mails et son téléphone. Donc l’alerte doit arriver là, avec ses mots à elle, et avec le geste qui règle le problème.
- Certains retards ont un prix fixé par la loi. Une rétractation se rembourse dans les quatorze jours qui suivent la demande (Code de la consommation, article L221-24), et chaque palier de retard augmente la somme due (article L242-4).
- Il n’y a qu’une tâche planifiée. Elle tourne une fois par jour (
cronsdeapps/erp/vercel.json), dans une fonction limitée à cinq minutes (maxDuration,apps/erp/app/api/veille/route.ts). - Un contrôle en panne ne doit pas ressembler à un contrôle qui n’a rien trouvé.
- L’alerte part par e-mail, chez un fournisseur qui peut être en panne le même matin.
Les alternatives
- Une file d’attente durable, avec des reprises. Elle garantit qu’un message arrive à son destinataire. Mais dans la plupart des situations décrites plus haut, aucun message n’est perdu, puisque personne n’a rien envoyé. C’est une question qu’un lecteur se poserait, et aucune trace ne montre que cette piste a été étudiée pour ce problème.
- La supervision des erreurs. Le collecteur reçoit déjà les erreurs du serveur et du navigateur (
packages/infra/src/collector.ts). Il voit ce qui casse, mais une commande oubliée ne casse rien. Le commit qui a ajouté la plupart des lectures le dit comme ça : « Vingt relevés qui cherchent l’écart plutôt que la panne » (dc334345d7). - Ne rien dire quand tout va bien, et laisser le silence servir de signal. C’était la première version, le 31 août : la tâche « n’envoie un e-mail QUE si l’une d’elles rend des lignes. Le silence est le dead-man’s switch » (
63ae5133dc). Six jours plus tard, l’audit relevait que ce silence « n’avait aucun témoin » (c71be614ed). Le schéma d’environnement en garde la raison : « une veille qui cesse de battre se tait exactement comme une veille saine » (apps/erp/shared/schemas/env.schema.ts).
La décision
Chaque matin, l’ERP relit ses propres données et y cherche les situations qui ne devraient pas durer. Chaque situation est une lecture : une requête, un titre et le geste qui la règle. Quand une lecture échoue, elle est rapportée comme « aveugle ». Un service extérieur reçoit un signal seulement quand la veille a tout lu et que son rapport est parti. Et c’est ce service qui prévient quand le signal manque.
L’implémentation
Une lecture cherche un état qui ne devrait pas durer
- anomalies que la veille de l’ERP recherche en production
- 28
- apps/erp/modules/monitoring/constants/anomaly-readings.ts#ANOMALY_READINGS
Chaque lecture est un fichier de apps/erp/modules/monitoring/data/ qui interroge la base et rend des lignes. Celle-ci cherche l’argent pris sans vente. C’est une commande du site qui a un paiement Stripe, que l’ERP n’a pas encaissée, à laquelle rien n’a touché depuis une heure et qu’aucun remboursement en cours ne couvre.
apps/erp/modules/monitoring/data/get-collected-without-sale.ts · lignes 19–42export async function getCollectedWithoutSale(): Promise<CollectedWithoutSale[]> {
return prisma.order.findMany({
where: {
channel: SaleChannel.WEB,
stripePaymentIntentId: { not: null },
paidAt: null,
paymentStatus: {
in: [PaymentStatus.PENDING, PaymentStatus.CANCELED, PaymentStatus.FAILED],
},
updatedAt: { lt: new Date(wallClockMs() - COLLECTED_WITHOUT_SALE_MIN_AGE_MS) },
refunds: { none: { status: { notIn: FALLEN_REFUND_STATUSES } } },
},
orderBy: [{ updatedAt: "asc" }, { id: "asc" }],
take: ANOMALY_MAX_ROWS,
select: {
id: true,
orderNumber: true,
amountTotalCents: true,
paymentStatus: true,
stripePaymentIntentId: true,
createdAt: true,
},
});
}Les seuils sont regroupés dans apps/erp/shared/constants/anomalies.ts, et ils se calculent à partir du mécanisme qu’ils surveillent. Une session de paiement est considérée en souffrance une heure après la durée de vie d’une session (STALE_PENDING_SESSION_MAX_AGE_MS). Du coup, si on change cette durée, le seuil bouge avec elle. Une commande annulée et pas encore remboursée entre dans le rapport à la moitié du délai légal de remboursement (CANCELED_ORDER_REFUND_MAX_AGE_MS, tiré de WITHDRAWAL_REFUND_DEADLINE_MS), quand il reste encore le temps d’agir. Un test compare ces constantes et refuse un seuil qui ne tomberait pas avant l’échéance qu’il surveille (apps/erp/test/monitoring-anomalies.regression.test.ts).
Une lecture rend un nombre limité de lignes (ANOMALY_MAX_ROWS). Quand elle atteint ce plafond, le rapport écrit « au moins » devant le compte et précise qu’il y en a peut-être plus.
Chaque rubrique arrive avec son geste
Le registre ANOMALY_READINGS (apps/erp/modules/monitoring/constants/anomaly-readings.ts) donne à chaque lecture un titre, le geste qui la règle et un enjeu. Les enjeux suivent un seul classement, celui de INCIDENT_STAKES : ce qu’on perd si on attend, un client qui attend, ce qui bloque une commande, ce qui est dû sans urgence. Le tableau de bord range ses incidents dans ces groupes, l’e-mail du matin y range ses rubriques, et la notification sur le téléphone nomme la première.
Dans l’e-mail, chaque rubrique a en plus une consigne écrite pour l’équipe et le passage du manuel qui l’explique (MORNING_GUIDES). Ce guide est typé sur les clés du registre. Donc une lecture ajoutée sans sa consigne ne compile pas.
Les lignes du rapport ne contiennent ni l’adresse e-mail d’un client ni un numéro de suivi, parce qu’elles partent dans une boîte aux lettres. Elles nomment la commande, et le lien mène à sa fiche, derrière la connexion. Le test de régression le vérifie sur chaque ligne construite.
Le tableau de bord relit une partie de ces lectures à chaque ouverture, avec le même état « aveugle » (getAdminWatchReadings). Donc quelqu’un qui ouvre l’ERP n’attend pas le lendemain matin pour les voir.
« Je n’ai pas pu regarder » n’est pas « il n’y a rien »
Les lectures partent ensemble, et chacune réussit ou échoue de son côté (Promise.allSettled). Une lecture qui échoue devient une rubrique « aveugle » du rapport, avec sa cause. Le rapport part quand même avec les autres.
Ce choix vient d’un défaut trouvé le 1er septembre. À ce moment-là, les lectures partaient en Promise.all, et un seul rejet faisait tomber le rapport entier. Ça incluait la rubrique des commandes annulées à rembourser, la seule qui avait un délai légal. Une seule lecture sortait de la base, pour relire des documents dans le stockage de fichiers. Si ce stockage avait été indisponible trois jours, on aurait perdu trois rapports pendant que le délai courait (3bd0e66aa5).
Dans le journal, une lecture aveugle s’écrit null. Un zéro se lirait comme une rubrique saine. Quand toutes les lectures sont aveugles, c’est sans doute que la base est injoignable. Dans ce cas, la veille envoie une alerte, répond en erreur et s’arrête là, sans lancer les purges.
apps/erp/modules/monitoring/services/monitoring.service.ts · lignes 60–119async function runMonitoring(
request: Request,
secret: string | undefined,
options: MonitoringOptions,
): Promise<MonitoringOutcome> {
if (secret === undefined || !isAuthorized(request, secret)) {
return { status: 401, body: "Battement de veille\u00A0: jeton absent ou invalide.\n" };
}
const withdrawalAcknowledgements =
options.acknowledgeWithdrawal === undefined
? undefined
: await resendWithdrawalAcknowledgements(options.acknowledgeWithdrawal);
const outcomes = await Promise.allSettled(READINGS.map((entry) => entry.run()));
const sections: MorningSection[] = READINGS.map(({ key, title, geste }, index) => {
const outcome = outcomes[index]!;
return outcome.status === "fulfilled"
? { key, title, geste, status: "read", entries: outcome.value }
: { key, title, geste, status: "blind", cause: describeError(outcome.reason).message };
});
const blind = sections.filter(
(section): section is Extract<MorningSection, { status: "blind" }> =>
section.status === "blind",
);
if (blind.length === READINGS.length) {
await sendAlert({
source: "veille",
context: "veille",
message: "la vérification du matin n’a pu lire aucune rubrique",
jour: day(wallClock()),
cause: blind[0]?.cause ?? "cause inconnue",
digest: VEILLE_DOWN_DIGEST,
});
return { status: 500, body: "Battement de veille\u00A0: lecture des anomalies en échec.\n" };
}
const total = anomalyCount(sections);
const outcome = await reportReadings(sections, blind, total, options);
const retention = await runRetention(options.retentionSteps);
logInfo({
source: "veille",
context: "veille",
message: "battement de veille",
anomalies: total,
sections: Object.fromEntries(
sections.map((section) => [
section.key,
section.status === "read" ? section.entries.length : null,
]),
),
retention,
...(withdrawalAcknowledgements === undefined ? {} : { withdrawalAcknowledgements }),
});
return outcome;
}Un témoin extérieur, prévenu quand tout a été lu
Après un passage réussi, la veille appelle un service de heartbeat extérieur (VEILLE_HEARTBEAT_URL). Quand l’appel manque, ce service prévient par son propre canal.
Le schéma d’environnement exige cette adresse sur une preview. En prod, il ne l’exige pas au démarrage, parce que le code traite encore cet environnement comme un site en construction (isConstructionEnvironment). C’est une lecture de la veille qui prend le relais. Une fois le site ouvert, elle signale chaque matin les variables d’ouverture qui manquent, dont celle-ci (getOpenSiteMissingVariables, OPENING_REQUIRED_VARIABLES).
Le passage compte comme réussi seulement si le jeton est bon, si chaque lecture a pu lire, et si le rapport est parti quand il y avait quelque chose à dire. Une seule lecture aveugle suffit pour répondre en erreur, même si le rapport est arrivé. Un rapport que le fournisseur d’e-mails n’a pas pris répond aussi en erreur. Dans les deux cas, le témoin ne reçoit rien et donne l’alerte de son côté. Il couvre donc la tâche planifiée qui ne se déclenche pas, la base injoignable et l’e-mail en panne.
Quand c’est le témoin qui ne répond pas, la veille le dit à l’équipe par e-mail (signalHeartbeat).
Un matin sans anomalie, l’équipe ne reçoit rien. Le lundi, elle reçoit quand même un rapport « tout est calme » (isWeeklyReportDue). Ça lui montre que la veille tourne, sans qu’elle ait besoin d’aller voir le témoin.
apps/erp/modules/monitoring/services/monitoring.service.ts · lignes 216–225export async function processMonitoringRequest(
request: Request,
secret: string | undefined,
heartbeatUrl: string | undefined,
options: MonitoringOptions,
): Promise<MonitoringOutcome> {
const outcome = await runMonitoring(request, secret, options);
if (outcome.status === 200) await signalHeartbeat(heartbeatUrl);
return outcome;
}On répare avant de lire, on purge après
La veille commence par renvoyer les accusés de réception de rétractation qui sont restés en souffrance. Elle lit ensuite, pour que le rapport décrive l’état après la réparation.
Une fois le rapport parti, elle joue ses étapes d’entretien. La route les lui passe en liste (apps/erp/app/api/veille/route.ts) : la vérification de la chaîne des encaissements, les clôtures de caisse, les durées de conservation, le registre des effacements. Chaque étape est isolée. Si l’une échoue, elle alerte et s’écrit null dans le journal, et les suivantes passent quand même (runRetention). La confirmation des livraisons par le suivi de La Poste est en dernier, pour qu’une API lente ne prenne pas le temps des autres (apps/erp/test/veille-step-order.regression.test.ts).
Si on rejoue la veille le même jour, le même rapport ne repart pas. La clé d’idempotence de l’e-mail est une empreinte de son contenu (contentKey, apps/erp/shared/server/alert.ts), et le fournisseur refuse un second envoi avec la même clé.
Une lecture écrite est forcément branchée
Un test relève les fichiers de lecture et le tableau du service, et les associe dans les deux sens. Une lecture écrite sans être branchée serait « un observateur qui n’observe rien » (63ae5133dc), et une lecture importée sans être appelée ne tournerait pas. Un autre test associe chaque tâche planifiée à sa route (apps/erp/test/vercel-crons.regression.test.ts).
apps/erp/test/monitoring-anomalies.regression.test.ts · lignes 55–63it.each(readings)("%s est APPELÉE, pas seulement importée", (file) => {
const functionName = readingFunctionName(file);
expect(
service.includes(`read: ${functionName},`),
`${file} est importée par ${SERVICE} sans être branchée sur une entrée ` +
`\`read:\` du tableau \`READINGS\` — elle ne sera jamais exécutée.`,
).toBe(true);
});Ce qu’une lecture trouve se vérifie sur une vraie base. Il y a une suite par famille, qui crée la situation et attend sa ligne (apps/erp/test/db/monitoring-sequence-gap.db.test.ts, monitoring-payments-without-sale.db.test.ts).
Les résultats
Le 31 août 2026, la veille avait quatre lectures. Aujourd’hui, elle en a le nombre affiché plus haut, relu dans le dépôt à chaque build de cette page. Les commits qui ont ajouté les premières citent chacun l’audit qui avait trouvé l’écart à la main (3bd0e66aa5, c71be614ed).
Pour chaque panne de la veille elle-même, il y a quelqu’un qui l’apprend.
| Ce qui tombe | Ce que fait la veille | Qui l’apprend |
|---|---|---|
| Une lecture | la rubrique passe « aveugle », le rapport part avec les autres | l’équipe par e-mail, puis le témoin |
| La base | une alerte, une réponse en erreur, aucune purge | l’équipe par e-mail, puis le témoin |
| Le fournisseur d’e-mails | le rapport ne part pas, la réponse est en erreur | le témoin, par son propre canal |
| La tâche planifiée, ou le déploiement tout entier | rien ne tourne | le témoin, par son propre canal |
| Le témoin | la veille a tourné, et une alerte le signale | l’équipe par e-mail |
| Une étape d’entretien | une alerte, null au journal, les étapes suivantes passent | l’équipe par e-mail |
Les limites
- La veille passe une fois par jour, à 6 h UTC. Une anomalie qui ne lève pas d’erreur peut rester presque un jour sans alerte. Le tableau de bord la montre plus tôt, mais il faut que quelqu’un l’ouvre.
- Une lecture trouve seulement l’écart qu’on a pensé à décrire. Un écart d’un nouveau genre reste invisible jusqu’à l’audit ou l’incident qui le fait apparaître.
- Chaque lecture ajoutée demande une requête, un titre, un geste, une consigne et un passage du manuel. Le service qui les assemble dépasse déjà le seuil de 500 lignes (Dette, risques et évolutions).
- Le témoin est un fournisseur de plus, et personne ne le surveille. Si lui et l’e-mail tombent le même matin, l’équipe n’apprend rien.
- En prod, rien n’empêche l’ERP de démarrer sans l’adresse du témoin. Dans ce cas, la veille tourne sans lui, et il n’y a que son propre rapport qui le signale, une fois le site ouvert.
- Le signal au témoin dit que les lectures ont lu et que le rapport est parti. Une étape d’entretien en échec ne le bloque pas. Elle alerte par e-mail, et si l’e-mail est en panne à ce moment-là, il ne reste que le journal.
- La route est protégée par un jeton porteur, sans signature horodatée (Webhooks et échanges).