--- id: STATE-COM-ORD-011 title: Return lifecycle object: DOM-COM-ORD-005 product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b states: - name: requested meaning: The return request is stored before immediate policy evaluation. - name: evaluating meaning: 'Resolved line terms determine authorization, refusal or approval needs.' - name: awaiting_approval meaning: The request waits for approval of an exceptional return. - name: authorized meaning: A numbered return authorization has been issued. - name: awaiting_receipt meaning: Authorized goods have not all arrived. - name: partially_received meaning: A portion of the authorized quantity has arrived. - name: received meaning: All authorized quantities have arrived. - name: inspecting meaning: Received units await inspection results. - name: dispositioned meaning: Received units have their required dispositions recorded. - name: financially_settled meaning: Settlement has occurred at the configured policy stage. - name: completed meaning: The goods process and money process have both finished. - name: completed_with_exceptions meaning: The return ended with exceptions requiring attention. - name: rejected meaning: Evaluation or an approver refused the return. - name: withdrawn meaning: The requester stopped the return before receiving goods. - name: expired meaning: 'Expiry is declared, but no current background check enters it.' transitions: - from: evaluating to: authorized trigger: Evaluation finds authorized line quantities within the resolved terms. guard: The sale is accepted or closed and quantities remain returnable. side_effects: - create the customer authorization and handling terms - notify the receiving boundary once authorization commits who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#authorizes at once under the built-in policy: the RMA numbered with its deadline, the lines authorized, the customer told to send it back - from: evaluating to: awaiting_approval trigger: Evaluation identifies exceptional terms needing approval. guard: A line's outcome requires a person. side_effects: [] who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#holds the member’s request for approval; the approver authorizes it and the RMA is issued - from: evaluating to: rejected trigger: Evaluation refuses all requested quantities. guard: Resolved terms leave no authorized line. side_effects: [] who: System provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#rejects the member with final_sale; the administrator’s override authorizes it - from: awaiting_approval to: authorized trigger: An approver permits the exceptional return with an explanation. guard: Console access and return approval authority are required. side_effects: - retain approval accountability and create authorization who: Approver provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#holds the member’s request for approval; the approver authorizes it and the RMA is issued - from: authorized to: financially_settled trigger: The configured policy settles at authorization. guard: Refund timing is on approval. side_effects: - settle the authorized return quantities through an adjustment who: System provenance: observed source: 'services-commerce:modules/orders/services/returns/return-workflow.ts' - from: awaiting_receipt to: received trigger: Receiving reports the complete authorized quantity. guard: Reported references belong to this return. side_effects: - apply disposed returned units to the purchased-line quantities - commit returned acquisition value with the receiving work who: System (receiving report) provenance: test source: >- services-commerce:modules/orders/tests/e2e/returns.e2e.spec.js#takes the warehouse’s receipt: the goods back on the line, the memo and the refund run, the document completed and the RMA closed - from: dispositioned to: completed trigger: Disposition and settlement have both finished. guard: Completion follows the settled return outcome. side_effects: - end the authorization as closed who: System provenance: observed source: 'services-commerce:modules/orders/services/returns/return-workflow.ts' - from: awaiting_receipt to: withdrawn trigger: The requester ends the return before goods arrive. guard: 'Withdrawal is limited to requested, awaiting approval, authorized or awaiting receipt.' side_effects: - close authorization and notify the receiving boundary who: Requester with the return update permission provenance: observed source: 'services-commerce:modules/orders/services/returns/return-workflow.ts:withdrawReturn' - from: awaiting_receipt to: expired trigger: The map declares elapsed-deadline expiry. guard: The automatic reconciler check is not implemented. side_effects: [] who: Nobody today provenance: observed source: 'services-commerce:modules/operations/services/reconciler/reconciler.ts:returns_overdue' invalid: - from: partially_received to: withdrawn why: Receiving has started and the remaining return processing must finish. - from: completed to: awaiting_receipt why: Completed returns have no outgoing transition. concurrency: >- Receipt and disposition changes share the reporter's transaction. Deadline expiry has no running check. A short receipt after an early refund raises an exception instead of recovering the money automatically. invariants: - INV-DOM-COM-ORD-005-01 - INV-DOM-COM-ORD-005-07 - INV-DOM-COM-ORD-005-08 evidence: - >- services-commerce at c8b66a98: modules/orders/services/persistence/returns.ts (RETURN_TRANSITIONS); services/returns/return-workflow.ts, return-policy.ts, returns-handling-port.ts; tests/e2e/returns.e2e.spec.js. --- # Return lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> requested requested --> evaluating requested --> withdrawn evaluating --> authorized evaluating --> awaiting_approval evaluating --> rejected awaiting_approval --> authorized awaiting_approval --> rejected awaiting_approval --> withdrawn authorized --> awaiting_receipt authorized --> financially_settled: money on approval authorized --> withdrawn awaiting_receipt --> partially_received awaiting_receipt --> received awaiting_receipt --> financially_settled awaiting_receipt --> expired: declared, unused awaiting_receipt --> withdrawn partially_received --> received partially_received --> inspecting partially_received --> expired received --> inspecting received --> dispositioned received --> financially_settled inspecting --> dispositioned inspecting --> financially_settled dispositioned --> financially_settled dispositioned --> completed dispositioned --> completed_with_exceptions financially_settled --> awaiting_receipt financially_settled --> completed financially_settled --> completed_with_exceptions ``` ## Transitions Explained Return evaluation resolves product, store, workspace or built-in terms and applies more favorable frozen promises. Allowed quantities receive an authorization; exceptional requests can need approval. Settlement follows the selected authorization, receipt or inspection stage and deducts applicable fees. ## What Cannot Happen Goods already received prevent withdrawal. Terminal returns do not reopen, and a line cannot occupy two live return documents. Accepted and closed orders are eligible targets. ## Concurrency and Timing Receipt and disposition changes share the reporter's transaction. Deadline expiry has no running check. A short receipt after an early refund raises an exception instead of recovering the money automatically.