Le projetCompétences et preuves4 min de lecture
Full-stack
Des features qui vont de la base à l’écran, dans deux applications : une règle écrite une fois, un paiement qui correspond à la page, un stock qui ne se vend pas deux fois, un cache qui suit l’ERP.
Chaque promesse ci-dessous est faite au client ou à l’équipe. Pour chacune, je montre le code qui la respecte et le test qui la vérifie. Les extraits sont lus dans le dépôt au build (Comment lire ces pages).
Une règle écrite une fois sert au site et à l’atelier
Avant le paiement, le site promet une date. Après, l’atelier suit une échéance. Les deux doivent sortir du même calcul. Avec deux copies, il suffirait d’un jour férié mal compté pour qu’elles divergent, et le client verrait le retard avant l’équipe.
Du coup, le calcul n’est écrit qu’une fois, dans packages/domain. Il compte en jours ouvrés, avec les fermetures du magasin et le fuseau de Paris. Les deux applications l’importent depuis ce paquet. Le site passe par un relais d’une ligne (apps/site/shared/lib/workshop-due-date.ts). Et si une copie revient, le contrôle des jumeaux la refuse (Architecture).
packages/domain/src/workshop-due-date.ts · lignes 21–34export function workshopDueDate(
paidAt: Date,
closures: readonly ClosurePeriodLike[],
leadTimeWeeks: LeadTimeWeeks = REFERENCE_LEAD_TIME_WEEKS,
timeZone: string = STORE_TIME_ZONE,
): Date {
const paidDay = toIsoDateIn(paidAt, timeZone);
const day = addWorkshopBusinessDays(
paidDay,
workshopShippingBusinessDays(leadTimeWeeks),
closures,
) as CivilDay;
return new Date(zonedMidnight(day, timeZone).getTime() + localTimeOfDayMs(paidAt, timeZone));
}Pour aller plus loin : Délais et dates promises, ADR 0005.
Le client paie ce que la page lui a montré
Entre le moment où le panier s’affiche et le clic sur « Payer », un prix peut changer, une remise peut expirer, une pièce peut partir au magasin. Si on débite un autre montant que celui affiché, on trompe le client. Par contre, si la page montrait déjà le nouveau prix et qu’on refuse la commande, on l’agace pour rien.
Donc la page de commande envoie les lignes qu’elle a affichées, et le serveur relit les prix et le stock dans la base pour comparer. Si la page affichait déjà l’état actuel, la commande part. Sinon, le serveur refuse en nommant la pièce concernée (la première, si plusieurs prix ont changé), et le panier se met à jour. Le client peut vérifier avant de relancer.
apps/site/modules/checkout/services/checkout.service.ts · lignes 88–207/**
* Le panier du cookie relu en base, ligne par ligne, avant toute écriture de commande. `email` :
* l'adresse saisie, dont les paiements en attente ne retiennent pas les pièces contre elle.
*
* `shown` : les lignes que la page de commande a montrées (`expectedLines`). Quand elles disent
* exactement ce qui sera débité, la cliente a déjà lu l'état présent — pièces retirées annoncées
* hors de la commande, nouveau prix affiché : le panier se met à jour sans refus, et la commande
* part. Quand elles diffèrent, ou sans elles (une page d'avant ce champ), chaque écart se dit par
* un refus, et la page relue montre l'état présent. Jamais un montant que la page n'a pas affiché.
*/
export async function reconcileCartWithCatalogue(
shown?: readonly ShownLine[],
email?: string,
): Promise<CheckoutLineInput[]> {
const cart = await readCartCookie();
if (cart.items.length === 0) throw new BusinessError(CHECKOUT_ERROR_MESSAGES.EMPTY_CART);
const rows = await prisma.productVariant.findMany({
where: { id: { in: cart.items.map((item) => item.variantId) } },
select: RECONCILE_SELECT,
});
const nowMs = wallClockMs();
const variants = rows.map((row) => settleEndedDiscount(row, nowMs));
const byId = new Map(variants.map((variant) => [variant.id, variant]));
// Le stock libre, comme le panier et la page de commande (`withFreeStock`) : une pièce qu'un autre
// paiement tient en entier reste au panier, hors de cette commande, sans refus. Ce que la même
// adresse paie déjà ailleurs (un autre appareil) ne compte pas contre elle, comme au paiement
// (`findTrackedStockShortage`).
const free = await withFreeStock(rows, cart.pendingOrderId ?? null, email ?? null);
const heldIds = new Set(
free.flatMap((variant) =>
variant.inventoryPolicy === InventoryPolicy.TRACKED &&
variant.heldElsewhere > 0 &&
variant.stock <= 0
? [variant.id]
: [],
),
);
const resolved = cart.items.map((item) => ({ item, variant: byId.get(item.variantId) }));
const withdrawn = resolved.filter(({ variant }) => isWithdrawn(variant));
const sellable = resolved.flatMap(({ item, variant }) =>
variant === undefined || isWithdrawn(variant) || heldIds.has(variant.id)
? []
: [{ item, variant, unitPriceCents: announcedPriceCents(variant) }],
);
const priced = new Map(
sellable.map(({ item, unitPriceCents }) => [item.variantId, unitPriceCents]),
);
const keptItems = (reprice: boolean) =>
cart.items.flatMap((item) => {
if (heldIds.has(item.variantId)) return [item];
const unitPriceCents = priced.get(item.variantId);
if (unitPriceCents === undefined) return [];
return [reprice ? { ...item, priceAtAddCents: unitPriceCents } : item];
});
const repriced = sellable.filter(
({ item, unitPriceCents }) => unitPriceCents !== item.priceAtAddCents,
);
const isAsShown =
shown !== undefined &&
sellable.length > 0 &&
sameShownLines(
shown,
sellable.map(({ item, unitPriceCents }) => ({
variantId: item.variantId,
quantity: item.quantity,
unitPriceCents,
})),
);
if (isAsShown && (withdrawn.length > 0 || repriced.length > 0)) {
await writeCartCookie({ items: keptItems(true) });
}
if (!isAsShown && withdrawn.length > 0) {
const kept = keptItems(false);
await writeCartCookie({ items: kept });
throw new CartPiecesRemovedError(withdrawalMessage(withdrawn.map(({ variant }) => variant)), {
variantIds: withdrawn.map(({ item }) => item.variantId),
// Rien de commandable ne reste : le panier est vide, ou ne garde que des pièces qu'un autre
// paiement tient. La page relue n'aurait plus de formulaire pour dire ce refus.
nothingLeftToOrder: kept.every((item) => heldIds.has(item.variantId)),
});
}
for (const { item, variant } of sellable) {
if (variant.inventoryPolicy === InventoryPolicy.TRACKED && variant.stock < item.quantity) {
throw new BusinessError(CHECKOUT_ERROR_MESSAGES.INSUFFICIENT_STOCK(variant.product.name));
}
}
if (!isAsShown) {
const first = repriced[0];
if (first !== undefined) {
await writeCartCookie({ items: keptItems(true) });
throw new BusinessError(CHECKOUT_ERROR_MESSAGES.PRICE_CHANGED(first.variant.product.name));
}
// La page a montré un autre panier (un autre onglet l'a changé, ou elle date d'avant une
// baisse de prix) : rien à corriger dans le cookie, mais la cliente doit relire le dû.
if (shown !== undefined) throw new BusinessError(CHECKOUT_ERROR_MESSAGES.CART_CHANGED);
}
return sellable.map<CheckoutLineInput>(({ item, variant }) => ({
variantId: variant.id,
quantity: item.quantity,
unitPriceCents: variant.priceCents,
ecoContributionUnitCents: variant.ecoContributionCents,
vatRateBps: STANDARD_VAT_RATE_BPS,
kind: LineKind.GOODS,
unitCostCents: null,
nameSnapshot: variant.product.name,
variantSnapshot: variant.label,
referenceSnapshot: variant.reference,
gtinSnapshot: variant.gtin,
madeToOrderSnapshot: variant.inventoryPolicy === InventoryPolicy.MADE_TO_ORDER,
weightG: variant.weightG,
}));
}Pour aller plus loin : Panier et paiement.
Le dernier exemplaire ne se vend qu’une fois, même payé deux fois à la même seconde
Le magasin et le site vendent le même stock. Si deux paiements sont confirmés au même instant sur la dernière pièce, il ne faut pas qu’elle soit vendue deux fois. Et il ne faut pas non plus qu’une des deux commandes reste sans explication.
Le stock est décrémenté par une mise à jour conditionnelle, dans la transaction du paiement. La base ne retire donc la pièce que s’il en reste. La commande qui arrive en second est marquée en rupture, et l’équipe la traite. En plus, sous le code, une contrainte de la base interdit un stock négatif, quoi que fasse l’application.
apps/erp/modules/payments/services/paid-stock.ts · lignes 32–66export async function decrementPaidStock(
tx: Prisma.TransactionClient,
order: { id: string; items: readonly PaidOrderLine[] },
): Promise<PaidStockOutcome> {
const oversold: OversoldItem[] = [];
const decremented = new Set<string>();
let decrementedCount = 0;
const tracked = order.items.filter(isStockTracked);
const applied = await changeOrderStock(
tx,
order.id,
tracked.map((item) => ({
variantId: item.variantId,
by: -item.quantity,
reason: StockMovementReason.SALE,
where: { inventoryPolicy: InventoryPolicy.TRACKED, stock: { gte: item.quantity } },
})),
);
for (const [index, item] of tracked.entries()) {
if (applied[index] !== true) {
oversold.push({ variantId: item.variantId, quantity: item.quantity });
await tx.orderItem.updateMany({
where: { id: item.id, orderId: order.id, backorderedAt: null },
data: { backorderedAt: wallClock() },
});
continue;
}
decrementedCount += 1;
const slug = item.variant?.product.slug;
if (slug !== undefined) decremented.add(slug);
}
return { oversold, decrementedCount, decrementedSlugs: [...decremented] };
}Pour aller plus loin : Stock, Données.
Ce qu’on change dans l’ERP se voit tout de suite sur le site, sans le faire tomber
Le site sert ses pages depuis un cache. Après une vente au magasin ou une baisse de prix, il ne doit plus afficher l’ancien prix ni le stock déjà vendu. Sauf que si on invalide tout le cache à chaque mouvement de stock, chaque page se refait pendant que le visiteur attend. Et si la base est lente à ce moment-là, c’est tout le site qui tombe.
Du coup, après chaque écriture, l’ERP envoie au site les tags concernés, par un canal authentifié. Le site fait expirer tout de suite ce qui contient un prix, un stock ou une date. Pour la taxonomie, il sert l’ancienne version le temps de la refaire.
apps/site/app/api/revalidate/route.ts · lignes 19–41/**
* Les tags de pure taxonomie : quelles pièces, catégories et collections les listes et la barre
* nomment. Ils passent en stale-while-revalidate (`"max"`) : la page suivante sert la dernière copie
* et se refait en arrière-plan — et garde cette copie si la base flanche à ce moment-là.
*
* Tous les autres expirent IMMÉDIATEMENT (`expire: 0`) : prix et stock (`variants`, `product:<slug>`),
* port (`shipping`), dates promises (`closures`, `workshop`), ouverture du magasin
* (`store-settings`). Chaque lecture qui montre un prix, un stock ou un délai porte `variants`, et
* l'ERP l'envoie avec `products` dès qu'une écriture peut les changer (`revalidateCatalogue`). Une
* retouche photo ne les change pas : elle n'envoie que `products` et la fiche
* (`revalidateProductPhotos`).
*
* Sans cette part, chaque mouvement de stock expirait sans repli les lectures de la barre et du pied
* (catégories, collections), présentes sur toutes les pages : la visite suivante de chaque adresse
* refaisait tout en bloquant, et une base lente à cet instant faisait tomber le site entier.
*/
const SWR_TAGS: ReadonlySet<string> = new Set([
PRODUCTS_CACHE_TAG,
CATEGORIES_CACHE_TAG,
COLLECTIONS_CACHE_TAG,
COLORS_CACHE_TAG,
MATERIALS_CACHE_TAG,
]);Côté ERP, un test classe chaque action serveur du dépôt. Celles qui changent ce que le site affiche doivent invalider son cache. Les autres ne doivent pas le faire. Et une nouvelle action doit entrer dans l’une des deux listes (Qualité).
Pour aller plus loin : Échanges entre les applications, ADR 0007.