--- id: CAP-COM-FUL-005 title: Understand and intervene in an order's delivery feature: FEAT-COM-FUL-01 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-REG-001 - CAP-COM-REG-002 - CAP-COM-REG-004 - CAP-COM-REG-005 - CAP-COM-REG-006 - CAP-COM-REG-007 - CAP-COM-REG-008 - CAP-COM-REG-009 - CAP-COM-REG-026 - CAP-COM-REG-033 - CAP-COM-REG-034 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: [] purpose: >- Operations staff explain outstanding delivery and record exceptional manual decisions. outcomes: - Staff can explain the outstanding delivery on an order. - Manual decisions retain attribution for later review. concepts: - CON-COM-FUL-001 actors: - ACT-COM-008 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: commerce.obligations.read where_checked: api scope: tenant - key: commerce.obligations.approve where_checked: api scope: tenant - key: commerce.obligations.override where_checked: api scope: tenant - key: commerce.obligations.reauthorize where_checked: api scope: tenant - key: commerce.obligations.resolve where_checked: api scope: tenant - key: commerce.obligations.hold where_checked: api scope: tenant - key: commerce.obligations.complete-manually where_checked: api scope: tenant - key: orders.obligations.view where_checked: console scope: tenant rules: - id: BR-CAP-COM-FUL-005-01 proved_by: [ATS-COM-FUL-001-11, ATS-COM-FUL-002-12, ATS-COM-FUL-005-01, ATS-COM-FUL-005-08, TST-COM-FUL-022] statement: >- Staff can list an order's obligations by line and unit and inspect gates, states, authorizations, attempts and interventions; portal callers cannot read the register. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#lists each order’s one pending obligation with the built-in default gate frozen on it, and refuses a portal member the register origin: none - id: BR-CAP-COM-FUL-005-02 proved_by: [ATS-COM-FUL-005-02, TST-COM-FUL-021, TST-COM-FUL-022, TST-COM-FUL-025, TST-COM-FUL-039] statement: >- Staff interventions require a reason, first append the acting person and reason to the intervention log, and add an order-history entry. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#refuses an approval to a reader, 403 permission_missing, and without a reason, 400 origin: none - id: BR-CAP-COM-FUL-005-03 proved_by: [ATS-COM-FUL-005-03, TST-COM-FUL-022, TST-COM-FUL-040, TST-COM-FUL-054] statement: >- One approval can release and immediately evaluate an obligation awaiting approval, while competing approvals are rejected with the successful approval identified. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#releases the blocked obligation on one of five simultaneous approvals, which opens its gate at once since the line is paid, with the one intervention recorded; the other four are refused 409 naming it (DEF-COM-0869) origin: DEF-COM-0869 (acceptance defect) - id: BR-CAP-COM-FUL-005-04 proved_by: [ATS-COM-FUL-005-04, TST-COM-FUL-022, TST-COM-FUL-040] statement: >- A separately authorized sensitive override opens a waiting obligation regardless of its gate facts and retains the overriding person and time. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#overrides the gate of the unpaid obligation, authorizing it regardless of the facts, with the override on the obligation origin: none - id: BR-CAP-COM-FUL-005-05 proved_by: [ATS-COM-FUL-003-07, ATS-COM-FUL-005-04, ATS-COM-FUL-005-09, ATS-COM-FUL-005-11, ATS-COM-FUL-008-07, ATS-COM-FUL-008-09, TST-COM-FUL-022, TST-COM-FUL-040] statement: >- Only failed obligations accept re-authorization with a new sequence or staff resolution, and resolution also closes their open exceptions. kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#re-authorizes the failed obligation at sequence two, which the participant fails again, then resolves it with its exceptions origin: none - id: BR-CAP-COM-FUL-005-06 proved_by: [ATS-COM-FUL-005-05, TST-COM-FUL-021, TST-COM-FUL-039] statement: >- A hold keeps a waiting obligation blocked despite payment, release immediately evaluates it, and holds cannot be placed on authorized obligations or released from unheld ones. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-holds.e2e.spec.js#keeps the gate shut while the hold stands, though the line is paid and Accounting’s event arrives origin: none - id: BR-CAP-COM-FUL-005-07 proved_by: [ATS-COM-FUL-004-10, ATS-COM-FUL-005-06, ATS-COM-FUL-005-10, TST-COM-FUL-021, TST-COM-FUL-039] statement: >- Manual completion requires both reason and evidence, applies only to delivery in flight, closes the authorization and rejects a later application callback. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-holds.e2e.spec.js#refuses the manual completion without the evidence (400) and to a reader (403), then completes it with the records and the note origin: none - id: BR-CAP-COM-FUL-005-08 proved_by: [ATS-COM-FUL-005-02, TST-COM-FUL-021, TST-COM-FUL-022, TST-COM-FUL-025, TST-COM-FUL-039] statement: >- Each intervention requires its specific administrator permission; register read authority permits no intervention. kind: permission enforced_at: - api must_prove: true provenance: observed source: 'services-commerce:modules/fulfillment/aws/api/fulfillment.routes.ts' origin: none - id: BR-CAP-COM-FUL-005-09 proved_by: [] statement: >- An intervention calls the selected audit provider without rolling back if publication fails; the Platform provider currently writes an error log instead of storing a Platform audit event. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-commerce:modules/fulfillment/services/register/intervention-audit.ts origin: none - id: BR-CAP-COM-FUL-005-10 proved_by: [ATS-COM-FUL-005-07] statement: >- The Fulfilment card exposes re-authorization, resolution, hold release and gate override under their individual permissions, with no controls for approval, placing holds or manual completion. kind: permission enforced_at: - console must_prove: true provenance: observed source: 'react-console:lib/commerce/order-flows/live.ts:obligationRoutes' origin: none scenarios: - id: SC-CAP-COM-FUL-005-01 given: A paid obligation is waiting for approval. when: Submit five staff approvals concurrently. then: >- One attributed approval opens the gate and the competing requests conflict with it. provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#releases the blocked obligation on one of five simultaneous approvals, which opens its gate at once since the line is paid, with the one intervention recorded; the other four are refused 409 naming it (DEF-COM-0869) - id: SC-CAP-COM-FUL-005-02 given: An application has not answered an in-progress instruction. when: Record manual completion with delivery evidence. then: >- The obligation completes and a subsequent callback cannot change that result. provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/obligation-holds.e2e.spec.js#refuses the participant’s late callback as not in flight, leaving the manual completion edge_cases: [] constraints: [] depends_on: - CAP-COM-FUL-004 related: - CAP-COM-FUL-001 - CAP-COM-FUL-008 journeys: - JNY-COM-FUL-001 - JNY-COM-FUL-002 open_questions: [] evidence: - repository: services-commerce sources: - >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#lists each order’s one pending obligation with the built-in default gate frozen on it, and refuses a portal member the register - >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#refuses an approval to a reader, 403 permission_missing, and without a reason, 400 - >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#releases the blocked obligation on one of five simultaneous approvals, which opens its gate at once since the line is paid, with the one intervention recorded; the other four are refused 409 naming it (DEF-COM-0869) - >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#overrides the gate of the unpaid obligation, authorizing it regardless of the facts, with the override on the obligation - >- services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#re-authorizes the failed obligation at sequence two, which the participant fails again, then resolves it with its exceptions - >- services-commerce:modules/fulfillment/tests/e2e/obligation-holds.e2e.spec.js#keeps the gate shut while the hold stands, though the line is paid and Accounting’s event arrives - >- services-commerce:modules/fulfillment/tests/e2e/obligation-holds.e2e.spec.js#refuses the manual completion without the evidence (400) and to a reader (403), then completes it with the records and the note - 'services-commerce:modules/fulfillment/aws/api/fulfillment.routes.ts' - >- services-commerce:modules/fulfillment/services/register/intervention-audit.ts - repository: react-console sources: - 'react-console:lib/commerce/order-flows/live.ts:obligationRoutes' controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-FUL-01-01, FAS-COM-FUL-01-03, FAS-COM-FUL-01-04] suites: [TST-COM-FUL-021, TST-COM-FUL-022, TST-COM-FUL-025, TST-COM-FUL-039, TST-COM-FUL-040, TST-COM-FUL-054] --- # Understand and intervene in an order's delivery ## Purpose Operations staff explain outstanding delivery and record exceptional manual decisions. ## How It Works Staff inspect the register for an order and open an obligation's detail. They review its gate, delivery attempts and intervention history before deciding what to do. The service offers distinct approval, hold, override, recovery, resolution and manual-completion actions. Each action has its own authority and records the explanation supplied by the person acting. The console currently exposes only part of that service workflow. Audit publication also remains limited by the selected provider. The product should give staff consistent access to the supported interventions and their consequences. ## Relationships - Carry authorized work to its delivering application supplies or consumes related delivery records. - Choose delivery conditions for sold items supplies or consumes related delivery records. - Review and resolve operations findings supplies or consumes related delivery records.