--- id: CAP-CRM-REG-007 title: Check an address against the saved policy feature: FEAT-CRM-REG-02 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-CRM-CFG-016 source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-crm:docs/migrations/crm-regions/README.md#2026-10-11 second pass (Andrew, 2026-10-11: rules are managed one at a time; an organization has a preferred address) - >- services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) purpose: Staff inspect the saved policy’s answer for an address before relying on that policy in their work. outcomes: - 'Staff can inspect the saved policy’s region, winning rule and explanation.' concepts: - CON-CRM-REG-002 actors: - ACT-CRM-003 - ACT-CRM-002 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: crm.regions.read where_checked: api scope: tenant rules: - id: BR-CAP-CRM-REG-007-01 proved_by: [ATS-CRM-REG-004-09, ATS-CRM-REG-006-10, ATS-CRM-REG-007-01, ATS-CRM-REG-007-06, ATS-CRM-REG-007-07, TST-CRM-REG-047] statement: 'Address preview returns the region, winning rule and explanation supplied by the saved policy.' kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the preview › answers the region the address would be given and the rule that decides it origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-11 second pass (Andrew, 2026-10-11: rules are managed one at a time; an organization has a preferred address) - id: BR-CAP-CRM-REG-007-02 proved_by: [ATS-CRM-REG-007-02, ATS-CRM-REG-007-06, TST-CRM-REG-047] statement: Preview commits no writes. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the preview › writes nothing: the tenant still has the rules it had origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-11 second pass (Andrew, 2026-10-11: rules are managed one at a time; an organization has a preferred address) - id: BR-CAP-CRM-REG-007-03 proved_by: [] statement: 'Preview, automatic assignment and recalculation use the same geographic matcher.' kind: invariant enforced_at: - service must_prove: false provenance: observed source: 'services-crm:modules/regions/services/region-assignment/region-assignment.ts:previewRegionAssignment' origin: none - id: BR-CAP-CRM-REG-007-04 proved_by: [ATS-CRM-REG-007-03, ATS-CRM-REG-013-07, TST-CRM-REG-047, TST-CRM-REG-067] statement: Preview requires regional read authority and rejects callers without regional permissions. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the preview › answers 403 to a context carrying no regions permission at all origin: none - id: BR-CAP-CRM-REG-007-05 proved_by: [ATS-CRM-REG-007-04, TST-CRM-REG-047] statement: >- Preview rejects a request without an address and ignores supplied fields that its geographic criteria do not compare. kind: validation enforced_at: - api must_prove: true provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the preview › answers 400 for a body with no address origin: none - id: BR-CAP-CRM-REG-007-06 proved_by: [ATS-CRM-REG-007-05, TST-CRM-REG-047] statement: 'An unmatched address returns neither region nor winning rule, together with an explanation.' kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#the preview › answers no region and no rule for an address no rule covers origin: none - id: BR-CAP-CRM-REG-007-07 proved_by: [ATS-CRM-REG-007-08] statement: Preview evaluates the saved rules independently of the assignment switch and the selected record kinds. kind: calculation enforced_at: - service must_prove: true provenance: inferred source: >- services-crm:modules/regions/services/region-assignment/region-assignment.ts:previewRegionAssignment; services-crm:modules/regions/services/region-assignment/region-matching.ts:matchRegionRule origin: none - id: BR-CAP-CRM-REG-007-08 proved_by: [] statement: >- With rules available, the console offers a preview dialog that identifies the region and winning position, labels inactive targets and highlights the winning rule on return. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/test-address-dialog.test.tsx#a match › names the region, and the rule that won it in its place in the order origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) - id: BR-CAP-CRM-REG-007-09 proved_by: [] statement: A rejected preview displays the service explanation as an alert and removes any earlier result. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/test-address-dialog.test.tsx#a refusal › shows what the service said, as an alert origin: none scenarios: - id: SC-CAP-CRM-REG-007-01 given: Saved rules include Boston postal coverage and a fallback. when: Staff preview a Boston address. then: 'The result identifies Northeast and its first postal rule, which the view highlights.' provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0357.spec.ts#CRM-ACC-0357' edge_cases: - id: SC-CAP-CRM-REG-007-02 given: The saved winning rule targets an inactive region. when: Staff inspect its preview result. then: The dialog identifies the target as inactive. provenance: test source: >- react-console:components/regions/__tests__/test-address-dialog.test.tsx#a match › says so when the region a record would land in is inactive constraints: [] depends_on: - CAP-CRM-REG-006 related: - CAP-CRM-REG-004 - CAP-CRM-REG-006 journeys: - JNY-CRM-REG-001 open_questions: [] evidence: - >- services-crm: Examined the pinned regional implementation, its declared constraints and the supporting records. - 'react-console: Examined the pinned regional configuration surfaces and their available test evidence.' - 'services-crm:docs/migrations/crm-regions/README.md' - 'services-crm:modules/regions/tests/e2e/regions.e2e.spec.js' - 'services-crm:modules/regions/services/region-assignment/region-assignment.ts' - 'services-crm:modules/regions/services/region-assignment/region-matching.ts' - 'react-console:components/regions/__tests__/test-address-dialog.test.tsx' - 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0357.spec.ts' controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003] exercised_by: [FAS-CRM-REG-02-01, FAS-CRM-REG-02-02, FAS-CRM-REG-02-04] suites: [TST-CRM-REG-047, TST-CRM-REG-067] --- # Check an address against the saved policy ## Purpose Staff inspect the saved policy’s answer for an address before relying on that policy in their work. ## How It Works Staff choose Test an Address from the saved Assignment Rules view. The dialog sends an address to the shared geographic matcher. It reports the target region, deciding rule and explanation without changing configuration or records. An inactive target receives an inactive indication. Returning to the view highlights the winning rule. A refusal appears as an alert and replaces an earlier result. The preview evaluates saved coverage even when automatic placement is disabled. It does not evaluate an unsaved editor draft. Staff save and return to the view before testing an edited policy. ## Relationships - Determine an address’s geographic region supplies the common geographic decision. - Build the geographic assignment policy maintains the geographic policy that other regional workflows evaluate.