SRV-16 — Orders module — lifecycle, assisted orders, history, documents

SummaryCopy Anchor Link

The 11-status state machine (no automatic confirmation — every order is confirmed in the back-office), controls, refusal and controlled modification, assisted orders and confirmations, first-order attribution, cancellation with automatic restock, invoice and delivery-note PDFs.

DescriptionCopy Anchor Link

Orders are the core flow of the cahier (§4.4, §5.4, §6.7, §15.2; ORD-04…ORD-12, ORD-14, ORD-15, STK-03, STK-08). This task implements the 11-status OrderStatus state machine with an explicit transition table and actors, and the 17 Oct rule that no order is confirmed automatically: app, web, assisted and phone orders all land in SUBMITTED (or PENDING on hold) and appear in admin.orders.toConfirm until someone with orders.validate confirms them. It covers validation controls (stock, credit, minimums, reseller status) with stock reservation per stock.reserveOn, refusal with a reason, controlled modification with OrderChange history, cancellation by actor and status with automatic restock, assisted orders (delegate draft → reseller confirmation or administration validation, 72 h expiry), back-office orders on behalf of a reseller, first-order flag and attribution to the source delegate, reorder, and invoice/delivery-note PDFs. Every status change emits an outbox event that reaches the reseller live over SSE (SRV-26) and as a notification (ORD-15). Out of scope: delivery records (SRV-17), invoices/payments (SRV-18), returns (SRV-20).

SubtasksCopy Anchor Link

DeliverablesCopy Anchor Link

• apps/server/src/modules/orders/{router,service,repo,state-machine,assisted,events,jobs}.ts
• packages/contracts/src/{orders.ts,delegate/orders.ts,admin/orders.ts}
• apps/server/src/modules/orders/documents/{invoice,delivery-note}.tsx PDF templates
• Order lifecycle table in /docs/srs/lifecycles-and-statuses matching the transition table code

Acceptance criteriaCopy Anchor Link

• No code path moves an order to VALIDATED without an explicit admin.orders.validate by a user holding orders.validate (ORD-14)
• Every transition not in the table returns 409 ORDER_TRANSITION_NOT_ALLOWED; a user without the permission gets 403 PERMISSION_DENIED (ORD-04)
• A reseller can cancel only while SUBMITTED or PENDING; cancellation releases reserved stock automatically (ORD-10, STK-03)
• An assisted order not confirmed within 72 h becomes EXPIRED/CANCELLED and the delegate is notified (ORD-08)
• Each status change writes an OrderStatusChange and emits order.status_changed received by the reseller's SSE stream within 2 seconds (ORD-06, ORD-15)
• The first delivered-path order of a reseller is flagged and attributed to the source delegate in reports (ORD-09)
• Invoice and delivery-note PDFs are downloadable by the reseller through a signed URL (ORD-12)

Requirements coveredCopy Anchor Link

ScreensCopy Anchor Link

API surfaceCopy Anchor Link

Test measuresCopy Anchor Link

• Table-driven unit tests over the full transition matrix (status × actor × permission)
• DB tests against real Postgres for validate/cancel stock and credit side effects
• Job test for assisted expiry with a fake clock
• E2E on staging: reseller checkout → back-office confirm → status visible live in the reseller web

RisksCopy Anchor Link

• Back-office becomes a bottleneck since every order needs manual confirmation — to-confirm queue sorted by age with counters and SSE alerts; bulk confirmation of clean orders (all controls green) as a pilot option
• Modification after reservation leaves stock inconsistent — modification re-runs reserve/release deltas in the same transaction

KPICopy Anchor Link

• Delivered by Mon 19 Oct 2026 within 2 person-day(s).
• Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
• Zero open critical defects, permission gaps or data-integrity regressions at sign-off.

---

Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.