--- id: DOM-COM-FUL-002 title: Fulfilment Policy realises: CON-COM-FUL-002 product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-FUL-fulfillment readable_by: [] custom_fields: none identity: >- A workspace-local policy record has one product, ordering-profile or workspace-default scope. Scope uniqueness prevents competing configured policies at the same level. attributes: - name: name and description kind: text required: true computed: false notes: >- Provides the required display name and an optional administrator description. - name: scope kind: enum required: true computed: false notes: >- Selects product, ordering-profile or workspace-default scope with the applicable identity. - name: financial condition kind: enum required: true computed: false notes: >- Selects the financial eligibility condition and its matching threshold properties. - name: minimum amount kind: money required: false computed: false notes: >- Stores a nonnegative threshold in minor units of the order currency, allowing zero. - name: minimum percentage kind: number required: false computed: false notes: >- Calculates the invoice percentage threshold by rounding upward to a minor unit. - name: approved terms satisfy kind: enum required: false computed: false notes: Allows qualifying approved terms to satisfy the full-payment condition. - name: requires approval kind: enum required: false computed: false notes: Requires staff approval before the gate opens when enabled. - name: application readiness required kind: enum required: false computed: false notes: Requires the application’s readiness report when enabled. - name: after a financial reversal kind: enum required: true computed: false notes: >- Chooses review, notify, suspension, line cancellation or no reversal action. - name: bank-debit timing kind: enum required: false computed: false notes: Selects whether bank-debit money qualifies at acceptance or settlement. - name: follow parent kind: enum required: false computed: false notes: Controls whether child delivery waits for the parent gate. - name: active kind: enum required: true computed: false notes: Excludes inactive policies from new selection. - name: version kind: number required: true computed: true notes: Retains the record version copied into a frozen gate. - name: effective policy kind: computed required: false computed: true notes: >- Resolves the policy and source that would apply to a product and profile now. relationships: - to: DOM-COM-FUL-001 cardinality: One policy version is frozen on many obligations. ownership: Each obligation owns its frozen copy. cross_service: false invariants: - id: INV-DOM-COM-FUL-002-01 statement: >- A scope identifies one policy, and only the workspace default omits its scope identity. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/fulfillment/db/fulfillment-policies.table.ts:fulfillment_policies_scope_uq,fulfillment_policies_tenant_default_uidx,fulfillment_policies_scope_check - id: INV-DOM-COM-FUL-002-02 statement: >- Policy writes validate the stored configuration against the shared delivery contract. enforced_at: - api - service provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/fulfillment-policies.ts:storedPolicy - id: INV-DOM-COM-FUL-002-03 statement: >- Resolution selects the first active policy in product, ordering-profile and workspace-default order, then uses the built-in fallback. enforced_at: - service provenance: test source: >- services-commerce:modules/fulfillment/tests/unit/policies/policy-resolution.spec.js#takes the product’s policy over the ordering profile’s and the tenant default’s - id: INV-DOM-COM-FUL-002-04 statement: >- Existing gates retain their frozen policy after configuration changes unless staff explicitly override or apply a policy. enforced_at: - service provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/fulfillment-policies.e2e.spec.js#freezes the product policy on the obligation with the row’s version and source, and the replacement changes nothing on it - id: INV-DOM-COM-FUL-002-05 statement: >- Preparation adds application-required approval and readiness without removing configured safeguards. enforced_at: - service provenance: documented source: 'services-commerce:docs/migrations/obligation-register/README.md#D-P4-05' - id: INV-DOM-COM-FUL-002-06 statement: >- Policy replacement checks the expected version, and locked policies refuse replacement or deletion. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/fulfillment/services/persistence/fulfillment-policies.ts:updateFulfillmentPolicy physical: - fulfillment_policies evidence: - >- services-commerce at c8b66a98: modules/fulfillment/db/fulfillment-policies.table.ts, policy-scopes.ts; services/persistence/fulfillment-policies.ts; services/policies/policy-resolution.ts, evaluate-gate.ts, retroactive-policy.ts; aws/api/fulfillment.routes.ts. --- # Fulfilment Policy ## What It Models A fulfilment policy supplies the delivery conditions used when a sale is placed. Administrators can scope it to a product, an ordering profile or the workspace default. Obligations retain a copy so later administration does not silently alter an existing sale. ## Identity and Attributes A policy has a stable record identity, one scope and a version. Financial eligibility can use full payment, a threshold, a deposit, immediate billing or no financial condition. Approval, application readiness, reversal response, bank-debit timing and parent-line behavior qualify that condition. ## Relationships One policy can supply many frozen obligation gates. Selection prefers an active product policy, then an active ordering-profile policy, then the workspace default, before using the built-in fallback. ## Invariants Scope uniqueness and valid stored policies protect selection. Replacements check the version read and refuse locked records. Policy application preserves existing approval and readiness safeguards while changing only eligible pending records. ## How It Is Stored and Shared Fulfillment owns policy storage and resolution. Preparation contributes application requirements, and the register stores the resulting gate. The registration declares no custom-field capability for these records. ## Open Design Questions Large policy applications need a reliable continuation design: repeating the current request can keep inspecting the same first page.