mercadodevida/work/artifacts/F-021/documenter.md

Documenter — F-021 Orders module

Summary

Orders module records purchase truth with immutable item snapshots, an explicit state machine, and ownership-scoped reads. OrderCreated is emitted on every creation; OrderPaid and OrderCancelled are emitted on those transitions.

Public API notes

Route	Access	Result
POST /orders	authenticated	Creates order with snapshots, returns PENDING
POST /orders/:id/transitions	authenticated	Validates and applies state transition
GET /orders/:id	authenticated	Returns order with items, scoped to user

Errors

• ORDER_STATE_TRANSITION_INVALID — HTTP 409
• ORDER_NOT_FOUND — HTTP 404

State machine

PENDING -> AWAITING_PAYMENT or CANCELLED AWAITING_PAYMENT -> PAID or CANCELLED PAID -> PROCESSING, SHIPPED, CANCELLED, REFUNDED PROCESSING -> SHIPPED, CANCELLED, REFUNDED SHIPPED -> DELIVERED, PARTIALLY_REFUNDED DELIVERED -> PARTIALLY_REFUNDED CANCELLED, REFUNDED, PARTIALLY_REFUNDED are terminal.

Evidence

• work/artifacts/F-021/architect.md
• work/artifacts/F-021/implementer.md
• work/artifacts/F-021/reviewer.json
• work/artifacts/F-021/security.json
• work/artifacts/F-021/qa.json