--- id: CAP-COM-ORD-010 title: Locate orders and understand their progress feature: FEAT-COM-ORD-03 product_area: commerce module: orders revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - CAP-COM-BIL-010 - CAP-COM-REG-049 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' purpose: 'Staff find previous sales and explain their lines, payment progress and outstanding balance.' outcomes: - Staff can identify a customer’s order without its number. - Displayed money reflects the latest Accounting position held by the order. concepts: - CON-COM-ORD-002 actors: - ACT-COM-014 - ACT-COM-015 - ACT-COM-016 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: commerce.orders.read where_checked: api scope: tenant - key: commerce.orders.read where_checked: console scope: tenant rules: - id: BR-CAP-COM-ORD-010-01 proved_by: [ATS-COM-ORD-001-20, ATS-COM-ORD-010-01, ATS-COM-ORD-010-12, TST-COM-ORD-025, TST-COM-ORD-104, TST-COM-ORD-135] statement: >- The workspace list returns orders in descending placement order with buyer names from CRM when available, default pages of fifty, a maximum of two hundred and a continuation cursor. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#lists every order of the tenant newest placed first, and none of another tenant’s origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - id: BR-CAP-COM-ORD-010-02 proved_by: [ATS-COM-ORD-010-02, TST-COM-ORD-104, TST-COM-ORD-135] statement: >- Literal case-insensitive search matches displayed or partial order numbers and buyer names, with search text limited to one hundred characters. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#finds an order by part of its buyer’s name in any case origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - id: BR-CAP-COM-ORD-010-03 proved_by: [ATS-COM-ORD-010-03, TST-COM-ORD-104] statement: >- Status, payment, kind and inclusive placement dates filter together, with paid based on an invoiced zero balance and unpaid excluding voided and cancelled orders. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#filters the unpaid orders: owing or not yet billed, never a voided one origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - id: BR-CAP-COM-ORD-010-04 proved_by: [ATS-COM-ORD-010-04, ATS-COM-ORD-010-10, ATS-COM-ORD-011-10, TST-COM-ORD-025, TST-COM-ORD-135] statement: >- Buyer lists require both buyer kind and identifier and allow only kind and policy narrowing; incompatible workspace filters are refused, and portal callers can list their own buyer scope only. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/unit/orders/orders-list-query.spec.js#refuses a search beside a buyer origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - id: BR-CAP-COM-ORD-010-05 proved_by: [ATS-COM-ORD-010-09, TST-COM-ORD-104] statement: >- Reading an order returns its lines and frozen purchases, price explanations, sequenced payment attempts, invoices, delivery obligations and events. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#answers the order whole: every column mapped, the system properties, the mirror absent until derived origin: none - id: BR-CAP-COM-ORD-010-06 proved_by: [ATS-COM-ORD-006-14, ATS-COM-ORD-007-18, ATS-COM-ORD-010-05, ATS-COM-ORD-010-11, TST-COM-ORD-094, TST-COM-ORD-095, TST-COM-ORD-133] statement: >- The order mirrors Accounting’s invoiced, paid, credited and balance figures after payments and acceptance and during sweeps, while raising reconciliation exceptions without suppressing the available figures. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/orders/tests/integration/services/mirror/refresh-money-mirror.integration.spec.js#raises accepted_without_invoice_line on the billed line the view lacks, one open row counting both findings, and still writes the mirror it could derive origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' - id: BR-CAP-COM-ORD-010-07 proved_by: [ATS-COM-ORD-010-06, TST-COM-ORD-016] statement: >- The Orders table displays order number, customer, placement date, status, total and balance, links to detail, handles voided balances and foreign currencies, explains missing names and requires order-read authority. kind: policy enforced_at: - console must_prove: true provenance: test source: >- react-console:components/commerce/orders/__tests__/orders-list-screen.test.tsx#shows the number, the customer, the status, the total and the balance due origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - id: BR-CAP-COM-ORD-010-08 proved_by: [ATS-COM-ORD-010-07, TST-COM-ORD-017] statement: >- Order 360 presents promotion names, money and invoice links, line discounts, tax and delivery errors, payment-attempt states and a message when Accounting has not yet supplied money figures. kind: policy enforced_at: - console must_prove: true provenance: test source: >- react-console:components/console/order/__tests__/order-360-live-cards.test.tsx#shows the totals with the promotion's name, the money, and the invoice as a link to Accounting origin: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' - id: BR-CAP-COM-ORD-010-09 proved_by: [] statement: The workspace order-detail page uses the order’s buyer when opened without a contact in the route. kind: policy enforced_at: - console must_prove: false provenance: observed source: 'react-console:app/(console)/console/[tenantId]/orders/[orderId]/page.tsx:OrderPage' origin: none - id: BR-CAP-COM-ORD-010-10 proved_by: [] statement: >- Order records, events and after-sale documents are available as datasets for workspace queries and exports. kind: policy enforced_at: - service must_prove: false provenance: observed source: 'services-commerce:modules/orders/export/orders.dataset.ts' origin: none scenarios: - id: SC-CAP-COM-ORD-010-01 given: Pat asks about an order from last Tuesday but cannot give its number. when: Staff use a partial surname search and the placement date. then: The result provides the matching order and balance with a link to its detail. provenance: documented source: 'services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' edge_cases: - id: SC-CAP-COM-ORD-010-02 given: An accepted sale is cancelled and its refunded balance reaches zero. when: A manager applies the Paid filter. then: The recorded list behavior includes it based on money rather than cancellation status. provenance: documented source: 'services-commerce:docs/milestones/plans/COMM-M2-W1-report.md#Things to know / for Andrew' constraints: [] depends_on: - CAP-COM-ORD-006 - CAP-COM-ORD-007 related: - CAP-COM-ORD-011 - CAP-COM-ORD-014 journeys: - JNY-COM-ORD-003 open_questions: [] evidence: - 'Examined reference: react-console:app/(console)/console/[tenantId]/orders/[orderId]/page.tsx:OrderPage' - >- Examined reference: react-console:components/commerce/orders/__tests__/orders-list-screen.test.tsx#shows the number, the customer, the status, the total and the balance due - >- Examined reference: react-console:components/console/order/__tests__/order-360-live-cards.test.tsx#shows the totals with the promotion's name, the money, and the invoice as a link to Accounting - >- Examined reference: services-commerce:docs/milestones/plans/COMM-M2-W1-report.md#Things to know / for Andrew - 'Examined reference: services-commerce:docs/milestones/plans/COMM-M2-plan.md#2. Scope' - 'Examined reference: services-commerce:docs/milestones/plans/COMM-M2-plan.md#D1' - 'Examined reference: services-commerce:modules/orders/export/orders.dataset.ts' - >- Examined reference: services-commerce:modules/orders/tests/integration/services/mirror/refresh-money-mirror.integration.spec.js#raises accepted_without_invoice_line on the billed line the view lacks, one open row counting both findings, and still writes the mirror it could derive - >- Examined reference: services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#answers the order whole: every column mapped, the system properties, the mirror absent until derived - >- Examined reference: services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#filters the unpaid orders: owing or not yet billed, never a voided one - >- Examined reference: services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#finds an order by part of its buyer’s name in any case - >- Examined reference: services-commerce:modules/orders/tests/integration/services/persistence/orders.queries.integration.spec.js#lists every order of the tenant newest placed first, and none of another tenant’s - >- Examined reference: services-commerce:modules/orders/tests/unit/orders/orders-list-query.spec.js#refuses a search beside a buyer controls: [TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, 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-DAT-004, TC-DAT-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-ORD-03-01, FAS-COM-ORD-03-02, FAS-COM-ORD-03-03, FAS-COM-ORD-03-04, FAS-COM-ORD-03-05] suites: [TST-COM-ORD-016, TST-COM-ORD-017, TST-COM-ORD-025, TST-COM-ORD-094, TST-COM-ORD-095, TST-COM-ORD-104, TST-COM-ORD-133, TST-COM-ORD-135] --- # Locate orders and understand their progress ## Purpose Staff find previous sales and explain their lines, payment progress and outstanding balance. Lists and detail views serve different parts of that investigation. ## How It Works A reader opens Orders and narrows the list using the customer or sale details they know. The result supplies enough financial context to choose an order for inspection. Opening the number leads to Order 360, where lines and transaction links provide the fuller account. The reader can distinguish an unavailable money summary from a reported zero balance. Reconciliation exceptions identify gaps between the sale and Accounting’s position. Customer-specific lists serve a narrower scope than workspace search. ## Relationships Placement establishes the order, billing and payment connect its money, and record protection constrains which reader can inspect it.