--- id: SCR-CRM-REG-002 title: Assignment Rules view route: '/console/{tenantId}/configuration/crm/regions?tab=rules' surface: console product_area: crm module: regions revision: 2 status: draft design_intent: confirmed origin: >- 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), cited in services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) implementation_evidence: observed inference: [] source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 purpose: >- Let staff inspect saved geographic coverage, test an address and apply changed coverage through a monitored recalculation. supports: - JNY-CRM-REG-001 - JNY-CRM-REG-002 - CAP-CRM-REG-003 - CAP-CRM-REG-004 - CAP-CRM-REG-007 - CAP-CRM-REG-010 - CAP-CRM-REG-011 - CAP-CRM-REG-012 permission: >- The console's CRM settings view alias; Recalculate needs the maintenance run alias (crm.regions.recalculate); Edit Assignment Rules needs the settings management alias entry_from: - '/console/{tenantId}/configuration/crm/regions (default selection when assignment is enabled)' - Selection of the policy tab from the regional catalogue - Return from the policy editor after save or guarded cancellation exits_to: - '/console/{tenantId}/configuration/crm/regions/assignmentRules' - '/console/{tenantId}/configuration/crm/regions?tab=regions' displays: - field: >- Assignment status and, when enabled, participating kinds and deciding sources. The response’s change time is not displayed. source: getRegionAssignmentSettings; listAddressTypes (Entities) - field: 'Coverage in evaluation order, including criteria, target, enabled status and description.' source: listRegionAssignmentRules; listRegions - field: 'Browser warnings identifying covered rules, retired targets and fallback coverage issues.' source: the browser's analysis of the rules and regions - field: The outstanding-recalculation banner and its available action. source: getRegionAssignmentSettings (recalculation needed) - field: >- An adopted run’s phase and counts, with a reason for failed status only. History restores running runs; monitoring errors are not displayed. source: listRegionRecalculations; getRegionRecalculation (polled every 1.5 seconds) - field: 'Address-test outcome with target name, retirement badge, winning rule position and explanation.' source: previewRegionAssignment actions: - label: Recalculate operation_id: recalculateRegionAssignments permission: crm.regions.recalculate (console alias maintenance.operations.run) confirm: false - label: Test an Address operation_id: previewRegionAssignment permission: crm.regions.read confirm: false - label: Edit Assignment Rules operation_id: 'none: opens the rules editor, which loads getRegionAssignmentSettings' permission: crm.regions.update (console alias crm.settings.manage) confirm: false - label: Dismiss a failed or completed run operation_id: 'none: hides the failure panel in the browser' permission: crm.regions.read confirm: false states: - loading - empty - error - read-only - inactive validation: - BR-CAP-CRM-REG-003-11 - BR-CAP-CRM-REG-003-13 - BR-CAP-CRM-REG-004-13 - BR-CAP-CRM-REG-007-05 - BR-CAP-CRM-REG-007-08 - BR-CAP-CRM-REG-007-09 - BR-CAP-CRM-REG-010-09 - BR-CAP-CRM-REG-010-10 - BR-CAP-CRM-REG-011-12 - BR-CAP-CRM-REG-012-09 - BR-CAP-CRM-REG-013-05 patterns: - 'Full-width PageLayout, ConfigBreadcrumb and PageHeader' - URL-selected line Tabs - Read-only assignment summary and ordered RuleDetails rows - A single available Recalculate location selected by run and policy state - RecalculationPanel for adopted progress and terminal outcomes - TestAddressDialog with SearchableSelect country input - Alert feedback for preview failure and temporary matching-row highlight - 'EmptyState for disabled assignment, absent catalogue or missing coverage' component: >- components/regions/assignment-rules-view.tsx (AssignmentRulesView), recalculation.tsx, test-address-dialog.tsx, in components/regions/regions-page.tsx evidence: - >- react-console at baf6dae3: components/regions/assignment-rules-view.tsx, recalculation.tsx, test-address-dialog.tsx, rule-details.tsx, regions-page.tsx, use-regions.ts; lib/configuration/regions.ts; lib/configuration/regions-analysis.ts; lib/authz/backend-aliases.ts; components/regions/__tests__/assignment-rules-view.test.tsx, recalculation.test.tsx, test-address-dialog.test.tsx, rules-tab.test.tsx. controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Assignment Rules view ## What the Screen Is For The policy tab explains the saved assignment choices and coverage. It provides address preview and the explicit recalculation action for applying coverage to existing records. Editing opens a separate screen. Enabled assignment makes this tab the default when no tab was selected. ## What It Shows and Lets People Do Enabled policy shows participating kinds, deciding sources and ordered coverage. Browser analysis warns about coverage and target problems without changing matching. Test an Address evaluates saved rules and highlights the winning row after closing its dialog. The policy change time is returned by the service but absent from this view. The needed banner carries Recalculate unless an adopted run takes its place. Running progress and undismissed failure move that action to the toolbar; otherwise it lives in the action menu. Completed and failed panels can be dismissed locally. ## States and Errors Disabled assignment hides coverage and recalculation controls while retaining a status summary. Catalogue and coverage absence have separate prompts. Displayed settings and rule-load failures have retry controls, and preview failures replace previous results. Monitoring is narrower: history adopts only running runs, failed historical runs are not restored, recoverable running errors are not displayed, and history or polling failures have no screen-level retry message. Start errors appear as toasts even when backend insertion already committed. ## Patterns It Must Respect The existing view uses shared summary, ordered-rule, dialog and run-panel components. Run authority disables Recalculate with an explanation. Preview stays outside the unsaved editor, and only one action location is selected at a time.