# ТЗ — Platform Core / Infrastructure Foundation для бухгалтерского Assistant Mode

**Версия:** 1.0  
**Дата:** 2026-03-24  
**Статус:** рабочее платформенное ТЗ  
**Назначение:** базовый архитектурно-инфраструктурный слой для развития бухгалтерского ассистента от текущего Assistant Mode к зрелой product system

---

## 0. Роль документа

Этот документ **не заменяет** roadmap, global status report и шесть этапных ТЗ.  
Он вводится как **надстроечное платформенное ТЗ**, которое:

- фиксирует, **на каком технологическом и архитектурном основании** должны реализовываться Этапы 1–6;
- закрывает дыры, которые не были полноценно оформлены в этапных документах;
- отделяет **platform core** от предметных reasoning-слоёв;
- задаёт правила, чтобы развитие системы не превращалось в рост локальных костылей и трудно переносимого кода.

Иными словами:

- Этапы 1–6 отвечают за **что должна уметь система**;
- настоящее ТЗ отвечает за **на чём и как это должно жить, храниться, исполняться, наблюдаться и поддерживаться**.

---

## 1. Основание документа

Документ построен поверх уже подготовленного пакета:

1. `Assistant_Mode_GLOBAL_STATUS_2026-03-24.md`
2. `Assistant_Mode_GLOBAL_STATUS_Appendix_2026-03-24.md`
3. `ROADMAP_endToReal.md`
4. `1 - TZ_Stage_1_Foundation_Hardening_Assistant_Mode.md`
5. `TZ_Stage_2_Retrieval_Unit_Shift_Assistant_Mode.md`
6. `TZ_Stage_3_Lifecycle_Formalization_Assistant_Mode.md`
7. `TZ_Stage_4_Accounting_Ontology_Graph_Core_Assistant_Mode.md`
8. `TZ_Stage_5_Investigation_Engine_Assistant_Mode.md`
9. `TZ_Stage_6_Live_Verification_Product_Modes_Assistant_Mode.md`
10. `accounting_assistant_architecture_roadmap.xlsx`

---

## 2. Что именно должен закрыть этот документ

Настоящее ТЗ вводится потому, что в существующем пакете хорошо разобраны:

- reasoning-слои;
- эволюция retrieval unit;
- lifecycle;
- graph core;
- investigation engine;
- live verification и product modes.

Но пока недостаточно формально описаны следующие платформенные зоны:

1. **Ingestion architecture**  
   Нет полного контура: raw source → immutable raw zone → canonical projection → serving projections → retrieval/graph/lifecycle/indexes.

2. **Разделение горячего state и тяжёлых артефактов**  
   Не разведены по классам хранения:
   - runtime state;
   - session/investigation state;
   - snapshot bundles;
   - raw extracts;
   - audit artifacts;
   - debug traces;
   - user-facing reports.

3. **Единая execution foundation**  
   Нет единого platform-level правила, где заканчивается:
   - API/runtime,
   - где начинается orchestration,
   - где живут batch jobs,
   - где живут live verification flows,
   - где проходит граница между sync и async контуром.

4. **Failure policy и degradation policy**  
   Не оформлены системно:
   - что происходит при недоступности live source;
   - как система деградирует;
   - что делать при конфликте snapshot vs live;
   - что делать при частичной недоступности источников.

5. **Security / RBAC / secret handling / auditability**  
   Эта зона пока не раскрыта как самостоятельный архитектурный слой.

6. **Versioning / migrations / schema evolution**  
   Вводится много новых сущностей, но не зафиксирована общая стратегия миграций и совместимости.

7. **Observability как product-contour, а не только debug**  
   Техническое логирование есть, но не описан взрослый контур:
   - traces,
   - business metrics,
   - run artifacts,
   - alerting,
   - dashboards,
   - SLO/SLA by mode.

8. **DevEx и controllability для разработки через Codex**  
   Нет жёстко оформленных правил, которые уменьшают вероятность самодельных архитектурных костылей:
   - единые контракты,
   - schema-first подход,
   - test harness,
   - deterministic job boundaries,
   - migration discipline,
   - generated clients / types.

---

## 3. Главная цель platform core

Сделать такой базовый слой, при котором дальнейшая реализация Этапов 1–6:

- не расползается по случайным JSON-файлам и ad hoc логике;
- не упирается в плоский snapshot-only runtime;
- не смешивает reasoning, transport, storage, orchestration и audit;
- остаётся переносимой, поддерживаемой и расширяемой;
- позволяет вводить новые сущности без каскада хаотичных переписываний.

Итоговая цель platform core:

> превратить текущий прототипный контур в управляемую self-hosted систему, в которой бухгалтерский assistant runtime, investigation runtime, audit runtime и live verification живут поверх единой, типизированной и наблюдаемой платформенной основы.

---

## 4. Базовые архитектурные принципы

### 4.1. Проектирование идёт от целевой архитектуры назад
Новые задачи описываются не как “улучшить ответ”, а как изменение одного из слоёв:

- data truth layer;
- canonical model layer;
- retrieval layer;
- lifecycle layer;
- graph layer;
- investigation/orchestration layer;
- live verification layer;
- trust/provenance layer;
- output contract layer.

### 4.2. LLM не является ядром архитектуры
LLM используется как:

- интерпретатор;
- планировщик bounded-проверок;
- synthesizer;
- explanation composer.

Но не как замена:

- typed storage;
- lifecycle;
- graph;
- investigation_state;
- policy engine;
- trust computation.

### 4.3. Никаких автономных агентных циклов без bounded policy
Система должна строиться как **bounded investigation system**, а не как “сам себе агент”.

Обязательны:

- stop criteria;
- max depth;
- max branches;
- explicit escalation policy;
- explicit live verification policy;
- explicit degradation policy.

### 4.4. Истина разделяется по слоям
Нельзя смешивать:

- snapshot-derived truth;
- inferred truth;
- graph-supported truth;
- investigation-supported truth;
- live-confirmed truth.

### 4.5. Сначала Postgres-first platform, потом усложнение
Если задача решается в рамках:
- PostgreSQL,
- object storage,
- Redis,
- queue/orchestrator,
- structured services,

то отдельные специализированные платформы не вводятся преждевременно.

### 4.6. Взрослая платформа важнее красивого кода отдельных модулей
Критичны не локальные рефакторинги, а наличие:
- typed contracts;
- storage boundaries;
- migration discipline;
- observability;
- reproducible execution;
- rollback strategy;
- acceptance metrics.

---

## 5. Что не является целью platform core

В рамки настоящего ТЗ **не входят**:

- полная предметная реализация lifecycle по всем доменам;
- полный граф бухгалтерской онтологии сам по себе;
- финальная UX-реализация всех режимов;
- автономный general-purpose agent;
- преждевременный переход на Kubernetes;
- преждевременное введение отдельного graph DB;
- преждевременное введение Kafka или тяжёлой event-driven архитектуры;
- переписывание всего существующего backend с нуля на другой стек.

---

## 6. Целевая платформа: верхнеуровневая схема

Целевая взрослая схема должна состоять из следующих обязательных контуров:

1. **Source Adapter Layer**
2. **Raw Ingestion Layer**
3. **Canonical Projection Layer**
4. **Serving / Retrieval Storage Layer**
5. **Reasoning Runtime Layer**
6. **Investigation / Audit Orchestration Layer**
7. **Live Verification Bridge**
8. **Trust / Provenance Layer**
9. **Observability / Eval Layer**
10. **Security / Access / Audit Layer**
11. **Deployment / Backup / Migration Layer**

---

## 7. Рекомендуемый стек platform core

Ниже фиксируется рекомендуемая технологическая база, исходя из текущего проекта, self-hosted контура и необходимости уменьшить объём самодельной инфраструктурной разработки.

### 7.1. Базовое решение по платформе

#### Обязательное ядро
- **Node.js + TypeScript** для application/runtime слоя
- **PostgreSQL 16+** как основной system of record
- **pgvector** как встроенный vector layer внутри Postgres
- **JSONB** как контейнер для полу-структурированных projection payloads
- **Redis** как cache / queue coordination / idempotency layer
- **BullMQ** как практический текущий job/orchestration layer
- **S3-compatible object storage** (предпочтительно MinIO) для raw и тяжелых артефактов
- **OpenTelemetry + Prometheus + Grafana + Loki + Tempo** как стандартный observability stack
- **Docker Compose** как базовый способ локального и серверного развёртывания на текущем этапе

#### Допустимый следующий уровень
- **Temporal** как следующий orchestration-class engine, но не в нулевой волне, а после появления зрелых long-running investigation/audit/live flows

#### Что не брать сейчас как обязательный слой
- Kubernetes
- Kafka
- Neo4j / отдельный graph DB
- отдельный vector DB
- тяжелую service mesh
- отдельный distributed config server

---

## 8. Почему выбран именно такой стек

### 8.1. Почему PostgreSQL является обязательным ядром
PostgreSQL должен стать хранилищем для:

- investigation runtime state;
- problem units;
- lifecycle entities;
- graph nodes/edges;
- trust/provenance;
- live verification requests/results;
- audit runs;
- eval metrics;
- user/system audit trail;
- configuration and policy data.

Причины:
- нужна транзакционность;
- нужны typed relations;
- нужны JSONB-поля для гибридной схемы;
- нужна возможность хранить vector embeddings рядом с доменными сущностями;
- нужна единая база для runtime state, projections и cross-layer queries;
- нужна зрелая миграционная и backup-модель.

### 8.2. Почему pgvector, а не отдельная vector DB сейчас
Отдельная vector DB не вводится на текущем этапе, потому что:
- главный потолок системы не в отсутствии специализированной vector-платформы, а в retrieval unit, lifecycle, graph и investigation_state;
- embeddings и семантический поиск должны жить рядом с основными сущностями и фильтрами;
- переносимость и поддержка выигрывают от единого data core.

### 8.3. Почему object storage обязателен
Нельзя хранить в Postgres как обычные runtime-строки:
- full snapshots;
- raw extracts;
- source dumps;
- audit packs;
- big evidence bundles;
- generated reports;
- trace exports;
- before/after benchmark artifacts.

Для этого нужен отдельный S3-compatible слой.

### 8.4. Почему Redis обязателен
Redis нужен не как truth layer, а как:
- short-lived cache;
- queue backend;
- idempotency registry;
- lock/lease layer для некоторых bounded jobs;
- rate-limit и dedupe layer.

### 8.5. Почему BullMQ подходит на ближайший горизонт
BullMQ целесообразен как текущий практический orchestrator для:
- snapshot import jobs;
- canonical projection jobs;
- reindex jobs;
- async investigation continuation;
- audit runs;
- report generation;
- live verification retries/compensations.

Это позволяет быстро получить управляемый async-контур без введения слишком тяжёлой orchestration-платформы.

### 8.6. Когда нужен Temporal
Temporal вводится только когда одновременно выполняются условия:
- long-running кейсы становятся штатным режимом;
- investigations живут дольше одного короткого запроса;
- нужны устойчивые retries/resume на уровне workflow history;
- audit/live verification flows становятся массовыми;
- требуется формальная durable execution model.

До этого момента достаточно заложить **интерфейсы совместимости**:
- workflow IDs,
- execution history,
- retry policy abstraction,
- explicit step boundaries,
- compensation hooks.

### 8.7. Почему Kubernetes не обязателен сейчас
Kubernetes не является ближайшим обязательным шагом, потому что текущие узкие места лежат не в зоне:
- container autoscaling;
- multi-cluster ops;
- service mesh.

А в зоне:
- storage model;
- runtime boundaries;
- orchestration;
- trust/live verification;
- schema discipline;
- observability.

Ранний переход на Kubernetes добавит сложность, но не поднимет потолок качества reasoning.

---

## 9. Решение по deployment maturity

### 9.1. Этап A — Docker Compose как стандарт
На ближайшем этапе обязательны:
- reproducible local environment;
- reproducible staging environment;
- reproducible production-like environment;
- разнесённые сервисы;
- volume strategy;
- backup/restore scripts;
- health checks;
- dependency readiness checks.

### 9.2. Этап B — выделение worker pools
После ввода audit/live/import контуров появляются отдельные сервисные роли:
- api/runtime;
- sync worker;
- batch worker;
- live verification worker;
- report worker;
- scheduler.

Это всё ещё может жить без Kubernetes.

### 9.3. Этап C — gate на Kubernetes
Переход на Kubernetes допускается только если появятся одновременно:
- несколько инсталляций/клиентов;
- явное требование к HA на уровне orchestration;
- горизонтально масштабируемые batch/live workloads;
- централизованное управление секретами и ingress;
- зрелые runbooks и SRE-практики.

---

## 10. Целевое разбиение на сервисы и bounded contexts

Платформа должна быть разделена не по “случайным папкам в коде”, а по устойчивым контурам.

### 10.1. `assistant-api`
Назначение:
- внешний API продукта;
- auth context;
- request intake;
- mode pre-selection;
- synchronous direct-answer path;
- job submission для investigation/audit/live.

Не должен содержать:
- тяжёлую batch-логику;
- прямую raw-ingestion логику;
- долгоживущие workflow state machines;
- прямую работу с source adapters в обход policy layer.

### 10.2. `source-adapter-service`
Назначение:
- работа с источниками:
  - 1С proxy;
  - UD8;
  - full snapshot source;
  - дополнительные будущие источники.
- нормализация доступа к разным source protocols;
- rate limiting и connection policy;
- source capability registry.

### 10.3. `ingestion-service`
Назначение:
- raw import jobs;
- checksum/versioning;
- immutable storage of raw extracts;
- staging parse jobs;
- detection of import failures and schema drift.

### 10.4. `projection-service`
Назначение:
- преобразование raw data в canonical entities;
- построение serving projections;
- enrichment fields;
- graph/lifecycle-ready structures;
- index update orchestration.

### 10.5. `retrieval-service`
Назначение:
- semantic profile execution;
- problem-unit assembly integration;
- ranking policy;
- retrieval payload normalization;
- explanation-facing evidence schema.

### 10.6. `reasoning-service`
Назначение:
- direct reasoning path;
- bounded planner;
- answer policy;
- trust pre-computation;
- recommendation of escalation.

### 10.7. `investigation-service`
Назначение:
- `investigation_case`;
- `investigation_hypothesis`;
- `investigation_branch`;
- `investigation_step`;
- `investigation_decision`;
- bounded orchestration;
- continuation between turns;
- partial conclusion assembly.

### 10.8. `live-verification-service`
Назначение:
- `live_verification_request`;
- `live_verification_result`;
- source-of-record checks;
- conflict resolution between snapshot and live;
- timeout/retry/degradation policy;
- provenance contribution.

### 10.9. `audit-service`
Назначение:
- `audit_run`;
- batch scope execution;
- aggregation;
- grouped problem clusters;
- reporting artifacts;
- drilldown materials.

### 10.10. `eval-observability-service` или отдельный контур
Назначение:
- accountant-facing metrics;
- benchmark execution;
- regression comparisons;
- quality dashboards;
- before/after reports.

### 10.11. `policy-config-service` или policy submodule
Назначение:
- centralized configs:
  - mode policy,
  - live verification policy,
  - trust policy,
  - branching policy,
  - stop criteria,
  - source availability policy,
  - SLA budgets by mode.

---

## 11. Модель хранения данных

### 11.1. Обязательное разделение по классам хранения

#### A. Transactional relational state (Postgres)
Хранится:
- runtime entities;
- cases;
- branches;
- hypotheses;
- decisions;
- trust states;
- mode transitions;
- live verification registry;
- eval results;
- configs;
- RBAC;
- audit logs.

#### B. Semi-structured serving data (Postgres JSONB)
Хранится:
- normalized retrieval payloads;
- projection fragments;
- evidence packs;
- source metadata;
- step result summaries;
- run summaries.

#### C. Vectors (Postgres + pgvector)
Хранится:
- embeddings ключевых retrieval/projection entities;
- embeddings problem units;
- embeddings lifecycle patterns;
- embeddings normalized textual contexts.

#### D. Immutable raw artifacts (S3/MinIO)
Хранится:
- snapshots;
- source extracts;
- raw JSON dumps;
- import archives;
- benchmark source packs;
- generated heavy reports.

#### E. Runtime ephemeral state (Redis)
Хранится:
- job queues;
- temporary locks;
- short-lived cache;
- dedupe tokens;
- rate limiting state.

---

## 12. Обязательные storage zones

### 12.1. `raw_zone`
Назначение:
- хранение неизменяемых исходных выгрузок.

Требования:
- immutable;
- versioned;
- content-addressable checksum;
- source metadata;
- import timestamp;
- source descriptor;
- schema fingerprint.

### 12.2. `staging_zone`
Назначение:
- промежуточный разбор raw payload.

Требования:
- может пересобираться;
- живёт ограниченное время;
- не используется как source-of-truth.

### 12.3. `canonical_zone`
Назначение:
- нормализованные сущности верхнего уровня:
  - document;
  - posting;
  - register movement;
  - account;
  - counterparty;
  - contract;
  - asset;
  - deferred expense;
  - VAT chain object;
  - period step.

### 12.4. `projection_zone`
Назначение:
- retrieval-ready и reasoning-ready представления:
  - problem-unit candidates;
  - lifecycle candidates;
  - graph edges;
  - summary views;
  - mode-specific serving projections.

### 12.5. `runtime_zone`
Назначение:
- investigation/audit/live runtime state.

### 12.6. `artifact_zone`
Назначение:
- итоговые audit artifacts;
- benchmark reports;
- user-facing downloadable results;
- trace exports.

---

## 13. Обязательные схемы сущностей platform core

Ниже перечислены сущности, которые должны быть заведены на уровне platform foundation, независимо от предметных деталей конкретных этапов.

### 13.1. Source / ingest сущности
- `source_system`
- `source_capability`
- `source_connection_profile`
- `ingest_run`
- `ingest_artifact`
- `schema_fingerprint`
- `projection_run`

### 13.2. Runtime execution сущности
- `execution_mode`
- `mode_router_decision`
- `mode_transition_decision`
- `runtime_request`
- `runtime_response_artifact`

### 13.3. Investigation сущности
- `investigation_case`
- `investigation_hypothesis`
- `investigation_branch`
- `investigation_step`
- `investigation_decision`

### 13.4. Audit сущности
- `audit_run`
- `audit_scope`
- `audit_cluster`
- `audit_report_artifact`

### 13.5. Live verification сущности
- `live_verification_request`
- `live_verification_probe`
- `live_verification_result`
- `live_verification_conflict`

### 13.6. Trust / provenance сущности
- `trust_state`
- `provenance_marker`
- `evidence_reference`
- `confidence_component`

### 13.7. Quality / eval сущности
- `benchmark_suite`
- `benchmark_case`
- `benchmark_run`
- `quality_metric_result`
- `comparison_report`

### 13.8. Human-in-the-loop сущности
- `human_review`
- `human_verdict`
- `resolution_action`
- `feedback_signal`
- `accepted_fix_reference`

Эти сущности нужны, чтобы система росла не только за счёт машинного inference, но и за счёт формализованной обратной связи.

---

## 14. Контуры исполнения: как должна работать система

### 14.1. Direct Answer Path
Путь используется, если:
- вопрос локальный;
- нужен быстрый ответ;
- evidence volume ограничен;
- нет необходимости открывать полноценный кейс;
- live verification не обязательна.

Pipeline:
1. request intake
2. pre-normalization
3. decomposition / route summary
4. mode router
5. retrieval execution
6. reasoning
7. trust pre-computation
8. output contract assembly
9. response artifact logging

### 14.2. Investigation Path
Путь используется, если:
- вопрос многосоставный;
- есть гипотезы;
- нужен branch traversal;
- follow-up должен углублять анализ;
- direct answer не даёт честной достаточности.

Pipeline:
1. request intake
2. mode router
3. case open / attach
4. hypothesis initialization
5. branch execution
6. step decisions
7. optional live recommendation or live call
8. bounded conclusion
9. case state persist
10. response artifact logging

### 14.3. Audit / Batch Path
Путь используется, если:
- запрошен широкий анализ;
- scope — период/зона/класс рисков;
- нужен report, а не chat answer.

Pipeline:
1. scope parse
2. audit_run create
3. batch retrieval
4. problem-unit assembly
5. lifecycle/graph enrichment
6. grouping
7. prioritization
8. report synthesis
9. artifact generation
10. audit summary + drilldown materials

### 14.4. Live Verification Path
Путь используется, если:
- high-stakes case;
- snapshot недостаточен;
- найден конфликт;
- пользователь требует подтверждения current state.

Pipeline:
1. create `live_verification_request`
2. select source/probe policy
3. execute bounded probes
4. map result to canonical form
5. compare with inferred state
6. update `trust_state`
7. attach provenance marker
8. emit verified / conflicted / inconclusive outcome

---

## 15. Требования к mode governance

### 15.1. `mode_router` — отдельный runtime слой
`mode_router` не должен быть косметической логикой поверх ответа.

Он обязан учитывать:
- query scope;
- evidence size expectation;
- presence of hypotheses;
- domain risk;
- need for live;
- follow-up continuity;
- user intent class.

### 15.2. У каждого режима должны быть свои execution contracts
Для каждого из режимов обязательно фиксируются:
- allowed depth;
- max secondary checks;
- max branches;
- stop criteria;
- timeout budget;
- live verification policy;
- output contract.

### 15.3. Пример обязательных бюджетов
Бюджеты задаются как platform config и могут позже уточняться.

#### `direct_answer`
- цель: быстрый и честный ответ;
- max branch count: `0` или `1` короткая secondary check;
- soft timeout: `<= 8–10 сек`;
- hard timeout: `<= 15 сек`;
- обязательна явная деградация, если evidence слабый.

#### `investigation`
- max active hypotheses: ограниченно;
- max branch count: bounded;
- max branch depth: bounded;
- результат может возвращаться как промежуточный + продолжение;
- live verification разрешается по policy.

#### `audit_batch`
- отдельный async contour;
- пользователь получает не длинный чат-ответ, а статус + итоговый artifact;
- обязательна трассировка прогресса;
- обязательна группировка результатов.

---

## 16. Требования к trust / provenance

### 16.1. Обязательный `trust_state`
Каждый результат любого режима должен иметь `trust_state`.

### 16.2. Trust не может считаться из общей “уверенности модели”
Trust должен вычисляться из компонент:
- качество snapshot;
- полнота problem unit;
- graph support;
- lifecycle support;
- branch completeness;
- unresolved contradictions;
- live verification;
- freshness;
- source health;
- human review outcome, если есть.

### 16.3. Минимальные trust-классы
Система должна различать как минимум:
- `snapshot_inferred`
- `graph_lifecycle_supported`
- `investigation_supported`
- `live_confirmed`
- `conflicted`
- `inconclusive`

### 16.4. Пользовательская подача
Trust не должен жить только во внутреннем JSON.  
Он должен входить в output contract и быть видимым в продукте.

---

## 17. Требования к source adapters

### 17.1. Поддерживаемые источники на текущем этапе
С учётом текущего контура минимально должны поддерживаться:
- локальный 1С proxy/plugin bridge;
- UD8 как дополнительный upstream слой сущностей;
- full snapshot как источник hard-analysis.

### 17.2. Общие требования к каждому adapter
Каждый адаптер обязан предоставлять:
- capability description;
- supported operations list;
- source freshness info;
- auth method;
- timeout policy;
- retry policy;
- response normalization contract;
- error taxonomy;
- health check endpoint.

### 17.3. Нельзя обращаться к источникам “как получится”
Запрещён pattern:
- код runtime напрямую ходит в разные источники по месту использования;
- source-specific shape протекает в answer/reasoning logic.

Все source calls идут через adapter boundary и canonical mapper.

---

## 18. Ingestion и canonicalization

### 18.1. Требования к raw import
Каждый import обязан:
- иметь `ingest_run_id`;
- сохранять checksum;
- сохранять source metadata;
- быть воспроизводимым;
- поддерживать rerun без потери истории.

### 18.2. Требования к canonicalization
Canonicalization должна:
- быть идемпотентной;
- отделять parse failures от source failures;
- сохранять ссылку на raw artifact;
- иметь schema version;
- поддерживать backfill/rebuild.

### 18.3. Требования к schema drift handling
Если структура источника изменилась, система обязана:
- зафиксировать drift;
- пометить affected projections;
- не silently ломать downstream reasoning;
- иметь downgrade/degradation mode;
- создавать alert для разработчика.

---

## 19. Политика миграций и эволюции схем

### 19.1. Все схемы — versioned
Каждая ключевая схема должна иметь:
- `schema_version`;
- forward migration path;
- rollback note;
- compatibility note.

### 19.2. Запрещены непроверяемые silent changes
Нельзя:
- менять shape runtime сущностей без миграции;
- менять retrieval payload без version bump;
- менять trust contract без обновления output contracts;
- менять adapter mapping без before/after test pack.

### 19.3. Обязательные типы миграций
- DB migrations
- canonical projection migrations
- reindex migrations
- artifact compatibility migrations
- benchmark/schema migrations

---

## 20. Решение по graph и vector-слоям

### 20.1. Graph на ближайшем горизонте живёт в Postgres
Графовое ядро на текущем этапе должно строиться на:
- typed node tables;
- typed edge tables;
- provenance fields;
- traversal services.

Причины:
- нет доказанной необходимости тащить отдельный graph DB;
- нужна сильная связка graph ↔ lifecycle ↔ runtime ↔ trust;
- проще миграции, backup, observability и эксплуатация.

### 20.2. Условия для возможного выделения graph DB в будущем
Отдельный graph DB рассматривается только если:
- сложные traversal query стали bottleneck;
- graph rules и traversals вышли за комфортный предел SQL/adjacency модели;
- есть реальная эксплуатационная выгода, а не абстрактная “красивость архитектуры”.

### 20.3. Vector layer
Vector layer должен оставаться рядом с доменными сущностями в Postgres до тех пор, пока:
- не появится объём и нагрузка, оправдывающие отдельную платформу;
- retrieval архитектурно не упрётся в Postgres, а не в problem unit / lifecycle / graph design.

---

## 21. Требования к observability

### 21.1. Обязательные технические контуры
Должны быть:
- structured logs;
- distributed traces;
- metrics;
- dashboards;
- alerting;
- correlation IDs;
- artifact links.

### 21.2. Observability должна видеть не только технику, но и продукт
Обязательны метрики:
- `retrieval_differentiation_rate`
- `generic_explanation_rate`
- `accountant_actionability_score`
- `false_confidence_rate`
- `broad_answer_rate`
- `mechanism_specificity_score`
- `followup_context_retention_score`

### 21.3. Обязательные dashboards
Минимум:
1. Runtime overview
2. Job health dashboard
3. Live verification dashboard
4. Accountant-quality dashboard
5. Source adapter health dashboard
6. Audit run dashboard
7. Investigation case dashboard

### 21.4. Обязательные correlation keys
Во всех логах и трассах должны быть:
- `request_id`
- `session_id`
- `case_id`
- `audit_run_id`
- `live_verification_request_id`
- `user_id`
- `tenant_id` или эквивалент, если вводится multi-tenant contour

---

## 22. Требования к quality harness

### 22.1. Benchmark suite обязателен
Изменение не считается принятым только потому, что:
- тесты зелёные;
- код собирается;
- route resolved;
- grounding nominally ok.

Нужен benchmark suite на канонических бухгалтерских сценариях.

### 22.2. Обязательные категории тестов
- unit tests
- contract tests
- migration tests
- adapter tests
- retrieval regression tests
- investigation continuity tests
- trust/provenance tests
- live verification conflict tests
- audit report assembly tests

### 22.3. Testcontainers / disposable env
Интеграционные тесты должны запускаться в воспроизводимой среде с настоящими:
- Postgres,
- Redis,
- object storage.

---

## 23. Security / access / audit

### 23.1. Общие требования
Платформа должна быть пригодна для бухгалтерских данных, а значит обязана иметь:
- auth integration;
- RBAC/ABAC policy;
- secret isolation;
- source credential isolation;
- audit trail по доступу к данным и live verification.

### 23.2. Модель доступа
Необходимо ввести минимум:
- `subject`
- `role`
- `resource`
- `action`
- `policy_rule`

Примеры действий:
- `read_snapshot`
- `run_direct_answer`
- `open_investigation_case`
- `run_audit`
- `request_live_verification`
- `read_live_result`
- `download_audit_artifact`
- `manage_source_connection`

### 23.3. Секреты
Секреты запрещено хранить:
- в исходном коде;
- в ad hoc локальных JSON;
- в таблицах без шифрования;
- в логах и артефактах.

Должен быть введён единый secret handling policy.

### 23.4. Audit trail
Обязательна запись:
- кто запросил live verification;
- к какому источнику был доступ;
- по какому объекту;
- когда;
- с каким результатом;
- какой trust-state это изменило.

---

## 24. Failure policy и degradation policy

### 24.1. Недоступность live source
Если live source недоступен:
- direct/investigation/audit не должны silently изображать live-confirmed result;
- должен формироваться `trust_state = inconclusive` или эквивалентный статус;
- результат маркируется как snapshot-only / verification-unavailable.

### 24.2. Конфликт snapshot vs live
Если snapshot и live расходятся:
- создаётся formal conflict artifact;
- trust понижается;
- результат должен различать:
  - “snapshot inference”,
  - “live contradiction”.

### 24.3. Частичная доступность источников
Система должна поддерживать:
- partial source availability;
- selective degradation;
- per-source timeout policies;
- per-source retry budgets.

### 24.4. Job failure handling
Для async jobs обязательны:
- retry policy;
- dead-letter handling;
- idempotent rerun;
- operator-visible failure reason.

---

## 25. Human-in-the-loop контур

### 25.1. Почему он обязателен
Ассистент не должен развиваться как замкнутый машинный контур.

Нужна формализация:
- что бухгалтер подтвердил;
- что отклонил;
- что пометил как false confidence;
- что признано полезным;
- что требует ручного добора.

### 25.2. Что должно быть введено
- `human_verdict`
- `review_reason`
- `accepted_resolution`
- `rejected_explanation`
- `needs_manual_followup`
- `feedback_to_benchmark`

### 25.3. Роль этого слоя
Этот слой:
- повышает trustworthiness;
- помогает benchmark/eval;
- даёт материал для правил, а не только для “тюнинга модели”.

---

## 26. Требования к DevEx и controllability

### 26.1. Schema-first / contract-first подход
Для всех ключевых контуров должны существовать:
- явные schema definitions;
- generated types;
- versioned contracts;
- API docs / internal docs;
- example payloads.

### 26.2. Единая дисциплина конфигов
Конфиги должны быть разделены на:
- environment config;
- source config;
- runtime policy config;
- mode config;
- feature flags;
- benchmark config.

### 26.3. Запрет на архитектурные “шорткаты”
Запрещены:
- прямые записи в случайные JSON-файлы как основной runtime state;
- обход adapter layer;
- смешение domain logic с transport/controller;
- отсутствие idempotency у batch/live jobs;
- отсутствие migrations для новых сущностей;
- логирование данных, содержащих чувствительные поля, без masking policy.

### 26.4. Требования к разработке через Codex
Чтобы уменьшить объём костыльного кода, должны быть введены:
- шаблоны модулей;
- шаблоны migrations;
- шаблоны contract tests;
- единые patterns для job handlers;
- единый способ описывать runtime entities;
- единый способ писать retry/dead-letter logic;
- единый способ писать source adapters;
- checklists на code review.

---

## 27. Что брать из готовых решений, а что писать самим

### 27.1. Обязательно брать готовое
Нужно использовать готовые mature-решения для:
- relational DB;
- vector storage внутри Postgres;
- queue/job processing;
- object storage;
- observability stack;
- backup/restore utilities;
- health checks;
- migration tooling.

### 27.2. Не нужно писать с нуля
Не нужно писать с нуля:
- собственную queue system;
- собственный distributed scheduler;
- собственный object storage;
- собственную metrics platform;
- собственный tracing backend;
- собственую формальную durable workflow engine, если её можно отложить до обоснованного момента.

### 27.3. Нужно писать самим
Своя разработка оправдана только там, где лежит уникальная бизнес-ценность:
- problem-unit assembly;
- lifecycle logic;
- graph semantics;
- investigation policy;
- trust computation;
- бухгалтерские explanation contracts;
- live verification decision policy.

---

## 28. План по волнам внедрения platform core

### Волна 0. Архитектурная фиксация
Результат:
- утверждён platform blueprint;
- утверждены storage zones;
- утверждены service boundaries;
- утверждён базовый stack;
- зафиксированы anti-patterns.

### Волна 1. Data/storage foundation
Что делается:
- Postgres как единый core;
- MinIO/S3;
- Redis;
- migrations;
- raw/canonical/projection/runtime/artifact zones;
- backup/restore.

### Волна 2. Runtime foundation
Что делается:
- execution_mode;
- mode_router;
- runtime_request/runtime_response_artifact;
- investigation_case baseline;
- audit_run baseline;
- trust_state baseline.

### Волна 3. Source/ingestion foundation
Что делается:
- source adapters;
- ingest_run;
- raw imports;
- projection pipeline;
- schema drift handling.

### Волна 4. Async/orchestration foundation
Что делается:
- BullMQ queues;
- worker separation;
- retry/dead-letter;
- live verification queue;
- audit queue;
- report queue.

### Волна 5. Observability and quality foundation
Что делается:
- OTel;
- dashboards;
- benchmark harness;
- accountant-facing metrics;
- before/after reporting.

### Волна 6. Security and governance
Что делается:
- RBAC/ABAC;
- secret policy;
- audit trail;
- source access policy.

---

## 29. Решения, которые надо зафиксировать прямо сейчас

### 29.1. Принять
- Postgres как основной system of record
- pgvector как встроенный vector layer
- MinIO/S3 как artifact/raw storage
- Redis + BullMQ как текущий async foundation
- Docker Compose как текущий deployment standard
- OTel + Prometheus + Grafana + Loki + Tempo как observability standard

### 29.2. Не принимать сейчас
- Kubernetes
- Neo4j как обязательный graph layer
- отдельную vector DB
- Kafka
- unbounded autonomous agent loop

### 29.3. Подготовить interfaces на будущее
- Temporal-compatible orchestration abstraction
- optional graph DB abstraction
- multi-tenant readiness
- external auth provider integration

---

## 30. Definition of Done для platform core

Platform core считается готовым к использованию как основание для дальнейших этапов, только если одновременно выполнены условия ниже.

### 30.1. По хранилищам
- введены и работают `raw`, `canonical`, `projection`, `runtime`, `artifact` zones;
- есть backup/restore plan;
- есть migration discipline;
- данные не размазаны по случайным файлам как primary state.

### 30.2. По execution foundation
- есть `execution_mode`;
- есть `mode_router`;
- есть formal runtime entities;
- direct/investigation/audit/live paths различаются как execution contracts, а не длиной ответа.

### 30.3. По async foundation
- import, audit, report, live verification работают как отдельные jobs;
- есть retries;
- есть dead-letter handling;
- есть operator-visible statuses.

### 30.4. По source integration
- каждый источник живёт за adapter boundary;
- есть health/status;
- есть timeout/retry/error taxonomy;
- есть canonical mapping.

### 30.5. По trust и provenance
- каждый результат имеет formal trust state;
- live verification влияет на trust;
- snapshot/live conflict обрабатывается честно.

### 30.6. По observability
- есть traces, logs, metrics, dashboards;
- есть business-quality metrics;
- есть correlation IDs между request, case, audit, live verification.

### 30.7. По безопасности
- есть role/resource/action model;
- секреты не хранятся в коде и логах;
- есть audit trail.

### 30.8. По DevEx
- новый модуль нельзя добавить вне contract-first discipline;
- есть шаблоны для migrations/jobs/adapters/tests;
- Codex не вынужден каждый раз изобретать архитектурный путь заново.

---

## 31. Явные анти-паттерны

Следующее должно считаться архитектурной ошибкой:

1. Попытка лечить качество только prompt tuning’ом.
2. Смешение chat history и `investigation_state`.
3. Хранение тяжёлых raw artifacts в Postgres как обычных runtime-записей.
4. Прямые походы в 1С/UD8 из произвольных частей кода.
5. Отсутствие `trust_state` в пользовательском результате.
6. Ранний переход на Kubernetes без закрытого platform foundation.
7. Замена orchestration policy “серией if-ов по месту”.
8. Отсутствие versioning у контрактов и схем.
9. Косметическое разделение direct / investigation / audit без отдельных execution contracts.
10. Логирование чувствительных данных без masking policy.
11. Использование объектного graph DB “потому что граф звучит красиво”, без доказанного bottleneck.
12. Попытка построить свой собственный durable workflow engine до появления обоснованной необходимости.

---

## 32. Управленческое резюме

Для текущего проекта критичен не “ещё один этап улучшения ассистента”, а **правильный platform core**, на котором эти этапы перестанут быть набором локальных кодовых надстроек.

Правильное решение на текущем горизонте выглядит так:

- **Postgres** как единый system of record;
- **pgvector** как встроенный vector layer;
- **MinIO/S3** как raw/artifact storage;
- **Redis + BullMQ** как текущий async/orchestration foundation;
- **Docker Compose** как стандарт развёртывания;
- **OTel + Prometheus/Grafana + Loki + Tempo** как обязательный контур наблюдаемости;
- **typed adapters + canonical projection + versioned contracts** как обязательная дисциплина разработки;
- **без Kubernetes, без отдельного graph DB, без отдельной vector DB, без автономного agent loop** на текущем этапе.

Именно такая основа лучше всего:
- уменьшит объём самодельной инфраструктурной разработки;
- снизит число архитектурных костылей;
- облегчит Codex работу;
- даст нормальную поддержку, переносимость и масштабирование;
- позволит этапам 1–6 реализовываться как системная эволюция, а не как накопление локальных латок.