ГЛОБАЛЬНЫЙ РЕФАКТОРИНГ АРХИТЕКТУРЫ - Архитектурный фундамент: capability-guard, navigation state и трассируемый route-контракт

2026-04-12 14:40:48 +03:00
parent fbd156e58e
commit c10260dedf
22 changed files with 1842 additions and 23 deletions
@@ -0,0 +1,103 @@
+# ARCH Layer Foundation (Safe Multi-Layer Evolution)
+
+## Purpose
+
+This foundation prepares the assistant runtime for independent evolution of:
+
+1. `compute` layer (deterministic financial routes),
+2. `navigation` layer (result-set and drilldown state),
+3. `conversational` layer (language, formatting, clarification UX).
+
+The goal is to make fixes in one layer without accidental regressions in the others.
+
+## Implemented Building Blocks
+
+### 1) Capability Route Policy (`compute` boundary)
+
+Files:
+
+- `llm_normalizer/backend/src/services/addressCapabilityPolicy.ts`
+- `llm_normalizer/backend/src/config.ts` (new per-capability flags)
+- `llm_normalizer/backend/src/services/addressQueryService.ts` (guard integration)
+
+What it gives:
+
+- explicit capability identity per intent (`capability_id`),
+- explicit layer classification (`compute` / `navigation` / `conversational`),
+- route-mode marker (`exact` / `heuristic`),
+- hard guard by feature flags (route can be disabled safely),
+- shadow-route planning hook for controlled rollout.
+
+### 2) Address Navigation State (`navigation` boundary)
+
+Files:
+
+- `llm_normalizer/backend/src/types/addressNavigation.ts`
+- `llm_normalizer/backend/src/services/addressNavigationState.ts`
+- `llm_normalizer/backend/src/services/assistantSessionStore.ts`
+- `llm_normalizer/backend/src/services/assistantSessionLogger.ts`
+
+What it gives:
+
+- first-class `session_context` with:
+  - `active_result_set_id`,
+  - `active_focus_object`,
+  - `last_confirmed_route`,
+  - date/org scope carryover,
+- persisted `result_sets` with entity refs parsed from assistant lists,
+- persisted `navigation_history` (`open` / `drilldown` / `refine`),
+- backward-compatible session normalization.
+
+### 3) Runtime Traceability (`cross-layer safety`)
+
+Files:
+
+- `llm_normalizer/backend/src/types/addressQuery.ts`
+- `llm_normalizer/backend/src/types/assistant.ts`
+- `llm_normalizer/backend/src/services/addressQueryService.ts`
+- `llm_normalizer/backend/src/services/assistantService.ts`
+
+What it gives in debug payload:
+
+- `capability_id`,
+- `capability_layer`,
+- `capability_route_mode`,
+- `capability_route_enabled`,
+- `capability_route_reason`,
+- `shadow_route_intent`,
+- `shadow_route_selected_recipe`,
+- `shadow_route_status`.
+
+This makes route regressions observable and testable.
+
+## Guard-Rail Flags
+
+New flags in `config.ts`:
+
+- `FEATURE_ASSISTANT_ADDRESS_NAVIGATION_STATE_V1`
+- `FEATURE_ASSISTANT_CAPABILITY_ROUTE_GUARD_V1`
+- `FEATURE_ASSISTANT_ROUTE_ADDRESS_GENERIC_V1`
+- `FEATURE_ASSISTANT_ROUTE_DRILLDOWN_V1`
+- `FEATURE_ASSISTANT_ROUTE_BALANCE_EXACT_V1`
+- `FEATURE_ASSISTANT_ROUTE_PAYABLES_CONFIRMED_V1`
+- `FEATURE_ASSISTANT_ROUTE_PAYABLES_HEURISTIC_V1`
+- `FEATURE_ASSISTANT_ROUTE_RECEIVABLES_HEURISTIC_V1`
+- `FEATURE_ASSISTANT_ROUTE_SHADOW_PAYABLES_EXACT_V1`
+
+## Validation Coverage Added
+
+Tests:
+
+- `llm_normalizer/backend/tests/addressCapabilityPolicy.test.ts`
+- `llm_normalizer/backend/tests/addressNavigationState.test.ts`
+- `llm_normalizer/backend/tests/sessionBackwardCompat.test.ts` (extended)
+
+## Why This Is a Foundation, Not a Patch
+
+This change does not only tune one scenario. It introduces stable contracts:
+
+- capability contracts for compute routing,
+- persistent navigation model for multi-step dialog chains,
+- explicit debug semantics to separate route decisions from answer wording.
+
+This is the base for parallel development across layers with lower regression risk.