SRV-17 — Preparation & delivery module
Delivery records per order, picking list, carrier assignment and tracking number, proof of delivery, delivery-fee policy.
| Field | Details |
|---|---|
| Task code | SRV-17 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 0.5 person-day(s) planned · 3 from scratch · size XS |
| Area · app | Server · server |
| Depends on | SRV-16 |
| Unblocks | DSH-06 |
| Milestones | — |
Summary
Delivery records per order, picking list, carrier assignment and tracking number, proof of delivery, delivery-fee policy.
Description
After confirmation, orders go through preparation and delivery handled by the delivery manager (cahier §3, §4.4, §11; DLV-01…DLV-04, DLV-06). This task implements one Delivery per order with the DeliveryStatus lifecycle (TO_PREPARE, PREPARING, READY, SHIPPED, DELIVERED, FAILED, RETURNED) kept in step with the order statuses through the orders state machine, the picking list, carrier assignment (DeliveryMode OWN_FLEET, CARRIER, PICKUP; Carrier list flagged API-capable or manual) and tracking number, proof of delivery (photo, recipient name, timestamp), failed-delivery handling with reason and retry, and the delivery-fee policy (free threshold, fee per wilaya) consumed by checkout options. Stock deduction at SHIPPED and the delivery note at READY are triggered through the existing hooks. Out of scope: carrier APIs (V2, SRV-34) and the delivery board UI (DSH-06).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Delivery creation on VALIDATED and DeliveryStatus transitions synced with OrderStatus PREPARING/READY/SHIPPED/DELIVERED | Anis |
| 2 | admin.deliveries.pickingList (lines grouped by product, barcodes, quantities, order note) as JSON and printable PDF | Anis |
| 3 | Carrier management admin.carriers.crud (name, mode, API-capable flag, tracking URL template, active) | Anis |
| 4 | admin.deliveries.update: mode, carrier, driver, tracking number, planned date; SHIPPED triggers stock deduction via stock.deductOn | Anis |
| 5 | admin.deliveries.proof: DELIVERY_PROOF photo, recipient name, timestamp → DELIVERED; FAILED with reason and retry or return | Anis |
| 6 | Delivery-fee policy (free-delivery threshold, fee table per wilaya, pickup free) used by cart.checkoutOptions and snapshotted on the order | Anis |
| 7 | admin.deliveries.list for the board (status columns, carrier, wilaya, date filters) | Anis |
| 8 | Events delivery.shipped / delivery.delivered / delivery.failed feeding order status notifications | Anis |
Deliverables
- apps/server/src/modules/fulfillment/{deliveries,carriers,fees,picking-list}.{service,router}.ts
- packages/contracts/src/admin/deliveries.ts
- Picking list PDF template on the shared PDF base
Acceptance criteria
- Marking a delivery SHIPPED moves the order to SHIPPED and writes SHIPMENT stock movements once (DLV-02, STK-03)
- DELIVERED requires a recipient name and either a photo or a documented exception; the reseller is notified (DLV-03)
- An order above the free-delivery threshold has a zero delivery fee; otherwise the fee of the delivery wilaya applies (DLV-06)
- The picking list lists every order line with quantity and barcode (DLV-01)
- Inactive carriers cannot be assigned (DLV-04)
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| DLV-01 | Preparation workflow (picking list) up to 'ready' | V1 |
| DLV-02 | Shipping: carrier assignment (own fleet or company), tracking number | V1 |
| DLV-03 | Delivery confirmation with proof (photo, recipient name) | V1 |
| DLV-04 | Carrier list management (API-capable vs manual) | V1 |
| DLV-06 | Delivery-fee policy (free threshold, per wilaya) | V1 |
Screens
API surface
| Endpoint group | Operations |
|---|---|
| Orders & delivery | 21 |
Test measures
- Unit tests for the fee policy
- DB tests for delivery/order status synchronisation and single deduction
- Manual print check of the picking list on A4
KPI
- Delivered by Mon 19 Oct 2026 within 0.5 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.
SRV-23 — Offline sync — batch replay, delta pulls, idempotency
Idempotency records for every mutation, /sync/batch replay with per-item results and conflict codes, /sync/delta cursors for the delegate's offline scopes, occurredAt plausibility rules.
SRV-18 — Billing V1 — invoices, payments, declarations, credit control
Invoices with legal mentions and statuses, payment recording and reseller declarations with proof, allocations, credit limit/exposure used at checkout, reseller finance summary.