Describe the order lifecycle with a state diagram — states, transitions, events and guards — and derive API rules from it: what is allowed in which status and what to return for a forbidden transition.
Statuses and transitions
The order lifecycle
A state diagram (UML 2.5.1) describes one object's life, here an order's. A state is a stable situation: the order is paid or being assembled. A transition is an arrow labeled “event [condition] / action”, e.g. “cancel [before handover to the courier] / request a refund”. The condition in brackets is a guard: while it is false, the transition doesn't fire. Initial state: a filled circle; final: a circle in a ring.
A Romashka order has six statuses: created, paid, assembling, in_delivery, delivered, cancelled; delivered and cancelled are final. A return after delivery is a separate process, not shown here. Transitions and triggers: see the table.
What the analyst gets:
• the allowed transitions: ready-made rules for the API and data checks;
• anything not on the diagram is forbidden: no way back from delivered to paid; a cancellation in in_delivery gets 409 Conflict with the current status in the error body;
• every transition publishes a fact event: OrderPaid, OrderCancelled. Some events don't change the status: OrderReadyForPickup (assembled, awaiting the courier).
Cancelling a cancelled order is a repeat, not a transition: 200 with the same order, no second refund. 409 is for in_delivery and delivered.
A status names a situation, not a command: paid, not pay, and is precise enough to carry rules: in_delivery means the courier has the order; a vague in_progress doesn't.
Transition table
| From | Event [condition] / action | To |
|---|---|---|
| created | payment succeeded (provider webhook) | paid |
| created | payment declined or cancelled by the customer | cancelled |
| paid | the store accepted the order | assembling |
| paid | cancelled by the customer / refund | cancelled |
| assembling | the courier picked up the order | in_delivery |
| assembling | cancelled by the customer or the store [before handover to the courier] / refund | cancelled |
| in_delivery | the courier handed over the order | delivered |
Lesson notes
The order lifecycle
A state diagram (UML 2.5.1) describes one object's life, here an order's. A state is a stable situation: the order is paid or being assembled. A transition is an arrow labeled “event [condition] / action”, e.g. “cancel [before handover to the courier] / request a refund”. The condition in brackets is a guard: while it is false, the transition doesn't fire. Initial state: a filled circle; final: a circle in a ring.
A Romashka order has six statuses: created, paid, assembling, in_delivery, delivered, cancelled; delivered and cancelled are final. A return after delivery is a separate process, not shown here. Transitions and triggers: see the table.
What the analyst gets:
• the allowed transitions: ready-made rules for the API and data checks;
• anything not on the diagram is forbidden: no way back from delivered to paid; a cancellation in in_delivery gets 409 Conflict with the current status in the error body;
• every transition publishes a fact event: OrderPaid, OrderCancelled. Some events don't change the status: OrderReadyForPickup (assembled, awaiting the courier).
Cancelling a cancelled order is a repeat, not a transition: 200 with the same order, no second refund. 409 is for in_delivery and delivered.
A status names a situation, not a command: paid, not pay, and is precise enough to carry rules: in_delivery means the courier has the order; a vague in_progress doesn't.