SRV-20 — Returns & after-sales (SAV) module

SummaryCopy Anchor Link

Return requests on delivered orders, approval, reception with automatic RETURN stock movements, credit notes; after-sales claims as tickets on order items with photos, resolved by replacement order, return, credit note, repair or rejection.

DescriptionCopy Anchor Link

The 17 Oct decisions move returns and after-sales service into V1 (decisions 9 and 10; ORD-13, SUP-04, STK-03, FIN-08). This task implements return requests on delivered orders (ReturnRequest RET-YYYY-NNNNNN, ReturnItem) with the ReturnStatus lifecycle REQUESTED → APPROVED/REJECTED → IN_TRANSIT → RECEIVED → REFUNDED, within the return window and never above delivered minus already-returned quantities; back-office decision and reception (admin.returns.decide, admin.returns.receive) where reception posts RETURN stock movements automatically through the inventory hook and issues a CreditNote linked to the invoice. It also implements the resolution of after-sales claims (AFTER_SALES tickets with TicketItem lines, AfterSalesIssue and photos, opened through SRV-24) via admin.tickets.resolve with AfterSalesResolution: REPLACEMENT creates a zero-priced replacement order that still goes through the confirmation queue, RETURN creates an approved return, CREDIT_NOTE issues a credit note, REPAIR tracks the repair, REJECTED requires a reason. Out of scope: returns and SAV pages (DSH-13) and the reseller screens (MRA-10, WEB-04/05).

SubtasksCopy Anchor Link

DeliverablesCopy Anchor Link

• apps/server/src/modules/orders/returns/{router,service,state-machine,events}.ts
• apps/server/src/modules/billing/credit-notes.{service,pdf}.ts
• apps/server/src/modules/support/after-sales/resolution.service.ts
• packages/contracts/src/{returns.ts,admin/returns.ts,admin/support.ts (resolve)}

Acceptance criteriaCopy Anchor Link

• A return request on an order delivered more than orders.returnWindowDays ago returns 422 RETURN_WINDOW_EXPIRED; quantities above delivered minus returned return 422 RETURN_QTY_EXCEEDED (ORD-13)
• Receiving a return writes one RETURN movement per accepted line and increases physical and available stock automatically (STK-03)
• Reception issues a credit note whose total equals the returned lines at their order snapshot prices incl. VAT, and the return becomes REFUNDED (FIN-08)
• Resolving an AFTER_SALES ticket with REPLACEMENT creates a zero-priced order linked to the ticket in the confirmation queue (SUP-04, ORD-14)
• Resolving with REJECTED without a reason returns 422 VALIDATION_FAILED
• Each return status change reaches the reseller live and as a notification (ORD-15)

Requirements coveredCopy Anchor Link

ScreensCopy Anchor Link

API surfaceCopy Anchor Link

Test measuresCopy Anchor Link

• Table-driven tests for the ReturnStatus transitions and quantity rules
• DB tests against real Postgres for reception: stock movements, credit note totals, idempotent reception
• E2E on staging: reseller return request → approve → receive → credit note visible in the reseller finance view

RisksCopy Anchor Link

• Defective returned items should not re-enter sellable stock — reception lets the operator route quantities to a non-selling (quarantine) warehouse; only sellable quantities raise availability
• Credit note legal format not yet validated — reuse the invoice legal mentions from DQA-09 and confirm with HOCO's accountant

KPICopy Anchor Link

• Delivered by Mon 19 Oct 2026 within 1.25 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.