Aller au contenu
Meubles Morinière

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 (crons de apps/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
Mesuré dans le dépôt à chaque build de cette documentation.

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.

getCollectedWithoutSaleapps/erp/modules/monitoring/data/get-collected-without-sale.ts · lignes 19–42
export 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.

runMonitoringapps/erp/modules/monitoring/services/monitoring.service.ts · lignes 60–119
async 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.

processMonitoringRequestapps/erp/modules/monitoring/services/monitoring.service.ts · lignes 216–225
export 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).

test « %s est APPELÉE, pas seulement importée »apps/erp/test/monitoring-anomalies.regression.test.ts · lignes 55–63
it.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 tombeCe que fait la veilleQui l’apprend
Une lecturela rubrique passe « aveugle », le rapport part avec les autresl’équipe par e-mail, puis le témoin
La baseune alerte, une réponse en erreur, aucune purgel’équipe par e-mail, puis le témoin
Le fournisseur d’e-mailsle rapport ne part pas, la réponse est en erreurle témoin, par son propre canal
La tâche planifiée, ou le déploiement tout entierrien ne tournele témoin, par son propre canal
Le témoinla veille a tourné, et une alerte le signalel’équipe par e-mail
Une étape d’entretienune alerte, null au journal, les étapes suivantes passentl’é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).

Sur cette page