Initial import NDC_1C

IN/Accounting_Analytics_Layer_Architecture.md

@@ -0,0 +1,501 @@
+# ТЗ — Accounting Analytics Layer Architecture
+
+## 1. Назначение документа
+
+Документ фиксирует архитектуру следующего слоя системы после успешного PoC runtime-моста к 1С.
+
+Цель этапа:
+- спроектировать **полный аналитический контур** поверх живого read-only runtime bridge;
+- развести **live-доступ к 1С** и **тяжёлую аналитику**;
+- исключить ошибочную архитектуру, при которой LLM в реальном времени пытается анализировать всю бухгалтерию напрямую через 1С;
+- определить слои, режимы работы, refresh-модель, canonical schema, anomaly engine и роль ассистента.
+
+---
+
+## 2. Контекст
+
+На предыдущем этапе подтверждён рабочий runtime semantic bridge к 1С:
+- read-only контур поднят;
+- доказаны цепочки `document -> posting -> account`;
+- доказаны цепочки `posting -> subconto[1..3]`;
+- доказана расшифровка saldo через движения;
+- bridge принят со статусом `adopt with restrictions`.
+
+Это означает:
+- живой доступ к бухгалтерскому смыслу есть;
+- но **полный аналитический контур нельзя строить как чатовый runtime-проход по всей 1С**;
+- нужен отдельный слой аналитики, кэша, baseline, anomaly detection и исторического анализа.
+
+---
+
+## 3. Главный архитектурный принцип
+
+Система должна быть разделена на **разные режимы работы**, а не пытаться решать всё одной и той же цепочкой `LLM -> 1С -> JSON -> LLM`.
+
+### 3.1. Режим A — Live Query
+Используется для:
+- точечных запросов;
+- drill-down;
+- проверки одного факта;
+- открытия документа;
+- расшифровки проводки;
+- объяснения сальдо;
+- прохода по конкретной цепочке связей.
+
+### 3.2. Режим B — Batch Analytics
+Используется для:
+- анализа всего периода;
+- анализа всех счетов;
+- поиска аномалий;
+- сравнения закрытых и открытых периодов;
+- поиска поведенческих паттернов;
+- выявления разрывов, дыр, хвостов и коллизий;
+- исторического анализа по месяцам/кварталам/годам.
+
+### 3.3. Режим C — Interactive Assistant
+Используется для общения с пользователем:
+- понимает намерение;
+- определяет, нужен live-доступ или уже есть готовый аналитический результат;
+- маршрутизирует запрос;
+- объясняет результат человеку.
+
+---
+
+## 4. Целевая архитектура
+
+## Layer 1. 1С Source Layer
+
+Источник истины:
+- документы;
+- проводки;
+- регистры;
+- планы счетов;
+- субконто;
+- остатки;
+- обороты;
+- закрытые и открытые периоды.
+
+### Жёсткое правило
+**Ничего в клиентскую 1С не пишем.**
+- не редактируем документы;
+- не проводим документы;
+- не меняем регистры;
+- не меняем конфигурацию ради аналитики;
+- не строим операционный write-layer.
+
+---
+
+## Layer 2. Runtime Semantic Bridge
+
+Основной live-мост к 1С.
+
+На текущем этапе:
+- `1c-mcp-toolkit`
+- только read-only
+- только локально / в изоляции
+- без `execute_code`
+- только approved read methods
+
+### Назначение слоя
+- читать метаданные;
+- выполнять безопасные read-only запросы;
+- читать документы, объекты, движения, счета, субконто;
+- обеспечивать live drill-down по конкретным фактам.
+
+### Не назначение слоя
+- не использовать как движок тяжёлой аналитики по всей компании в реальном времени;
+- не использовать как единственное хранилище семантики;
+- не использовать как вычислительный комбайн для whole-slice анализа.
+
+---
+
+## Layer 3. Extraction / Refresh Layer
+
+Контролируемый слой извлечения данных из 1С в аналитическое хранилище.
+
+### Задачи
+- запускать штатные extraction jobs;
+- читать данные из 1С пакетно и инкрементально;
+- формировать canonical payloads;
+- обновлять аналитическое хранилище;
+- минимизировать нагрузку на live-runtime.
+
+### Режимы извлечения
+1. **Initial Historical Load**
+   - первичная загрузка истории;
+   - по месяцам / кварталам / годам;
+   - по закрытым периодам.
+
+2. **Incremental Refresh**
+   - догрузка изменений по открытому периоду;
+   - обновление новых и изменившихся документов и движений.
+
+3. **Targeted Refresh**
+   - загрузка конкретного счета;
+   - загрузка конкретного контрагента;
+   - загрузка конкретного периода;
+   - загрузка конкретного документа.
+
+### Требование
+Extraction layer должен быть:
+- воспроизводимым;
+- логируемым;
+- перезапускаемым;
+- устойчивым к частичным сбоям.
+
+---
+
+## Layer 4. Canonical Accounting Store
+
+Нормализованное хранилище бухгалтерского смысла.
+
+Это не “снапшот ради снапшота”, а основной аналитический слой.
+
+### Базовые сущности
+- `Document`
+- `Posting`
+- `RegisterMovement`
+- `Account`
+- `SubcontoEntity`
+- `Counterparty`
+- `Contract`
+- `Organization`
+- `Item`
+- `Warehouse`
+- `Period`
+- `BalanceSnapshot`
+- `TurnoverSnapshot`
+- `EntityState`
+- `AnomalySignal`
+- `RiskPattern`
+
+### Базовые связи
+- `Document -> creates -> Posting`
+- `Posting -> debit -> Account`
+- `Posting -> credit -> Account`
+- `Posting -> hasSubconto1 -> SubcontoEntity`
+- `Posting -> hasSubconto2 -> SubcontoEntity`
+- `Posting -> hasSubconto3 -> SubcontoEntity`
+- `Posting -> belongsTo -> Organization`
+- `Posting -> belongsToPeriod -> Period`
+- `Counterparty -> hasContract -> Contract`
+- `Account -> hasBalanceSnapshot -> BalanceSnapshot`
+- `Period -> hasTurnoverSnapshot -> TurnoverSnapshot`
+
+### Требование
+Canonical store должен быть:
+- семантически стабильным;
+- независимым от сырой структуры 1С;
+- пригодным для SQL/graph/pattern-анализа;
+- пригодным для feed в feature/anomaly engine.
+
+---
+
+## Layer 5. Feature Store / Analytics Store
+
+Слой производных признаков, baseline и аналитических индикаторов.
+
+### Что здесь хранится
+- признаки по счетам;
+- признаки по контрагентам;
+- признаки по документам;
+- частотные поведенческие паттерны;
+- baseline по периодам;
+- отклонения от baseline;
+- anomaly flags;
+- drift signals;
+- risk score;
+- derived relation signals.
+
+### Примеры признаков
+- нетипичная корреспонденция счетов;
+- новый тип субконто в периоде;
+- резкий рост активности по счету;
+- аномальное увеличение оборота;
+- повторяющиеся нестандартные проводки;
+- контрагент, резко изменивший тип операций;
+- хвосты и незакрытые цепочки;
+- проводки, не похожие на исторический baseline.
+
+---
+
+## Layer 6. Analytical Engine
+
+Вычислительный слой, который считает и сравнивает, но не является LLM.
+
+### Что делает engine
+- rule-based проверки;
+- статистические проверки;
+- anomaly detection;
+- baseline modelling;
+- drift analysis;
+- pattern mining;
+- graph analysis;
+- scoring;
+- объяснение причинности через расчётные модели.
+
+### Что engine не делает
+- не общается с пользователем напрямую;
+- не генерирует красивый текст ответа;
+- не выполняет роль conversational assistant.
+
+### Режимы работы
+- по расписанию;
+- по ручному запуску;
+- по триггеру;
+- по событию;
+- по запросу от assistant-layer, если нет свежего результата.
+
+---
+
+## Layer 7. Assistant / Orchestrator Layer
+
+LLM-слой и логика маршрутизации.
+
+### Роль слоя
+- принимать пользовательский вопрос;
+- определять тип вопроса;
+- решать, где лежит ответ:
+  - в analytics store,
+  - в live bridge,
+  - или нужен новый batch-run;
+- объяснять результат человеку.
+
+### Что LLM не должна делать
+- не должна перебирать всю 1С в реальном времени;
+- не должна сама быть anomaly engine;
+- не должна получать целиком весь срез компании в промпт;
+- не должна по каждому тяжёлому вопросу инициировать полное живое сканирование 1С.
+
+### Что LLM должна делать
+- классифицировать вопрос;
+- маршрутизировать запрос;
+- выбирать инструменты;
+- суммировать результаты;
+- превращать аналитические факты в понятный ответ.
+
+---
+
+## 5. Почему нельзя делать всё через live bridge
+
+### Проблема
+Если делать всё как:
+`LLM -> toolkit -> 1С -> JSON -> LLM`
+
+то на тяжёлых вопросах система будет:
+- медленной;
+- дорогой;
+- хрупкой;
+- плохо воспроизводимой;
+- чувствительной к latency;
+- зависимой от размера данных и количества round-trip операций.
+
+### Особенно плохо это работает для запросов типа:
+- “проанализируй весь срез на сегодня”;
+- “найди все аномалии по всем счетам”;
+- “сравни компанию за 10 лет по месяцам”;
+- “найди все техкомпании-прокладки и аномальные паттерны”.
+
+### Следствие
+Live bridge должен использоваться **точечно**, а тяжёлый анализ должен идти через отдельный аналитический слой.
+
+---
+
+## 6. Как должна работать система на практике
+
+### Сценарий 1. Точечный вопрос
+Пользователь:
+> Что по счёту 68.02?
+
+Маршрут:
+1. assistant проверяет analytics store;
+2. если есть готовый balance/anomaly context — использует его;
+3. если нужен drill-down — идёт через runtime bridge;
+4. возвращает объяснение.
+
+### Сценарий 2. Массовый анализ
+Пользователь:
+> Проанализируй весь текущий срез и найди аномалии.
+
+Маршрут:
+1. assistant не идёт напрямую в 1С по всей базе;
+2. проверяет, есть ли свежий batch-run;
+3. если есть — отдаёт summary;
+4. если нет — запускает analytic job;
+5. после завершения показывает результаты и даёт drill-down.
+
+### Сценарий 3. Историческое сравнение
+Пользователь:
+> Сравни поведение компании по кварталам за 5 лет.
+
+Маршрут:
+1. используются historical baseline и snapshots;
+2. analytical engine считает изменения;
+3. assistant объясняет выводы.
+
+---
+
+## 7. Модель обновления данных
+
+### 7.1. Закрытые периоды
+- загружаются один раз;
+- считаются эталоном;
+- меняются только по отдельному регламенту.
+
+### 7.2. Открытые периоды
+- обновляются инкрементально;
+- по расписанию;
+- по событию;
+- по ручной кнопке;
+- по запросу при необходимости.
+
+### 7.3. Refresh granularity
+Поддержать:
+- period-level refresh;
+- account-level refresh;
+- document-level refresh;
+- counterparty-level refresh.
+
+---
+
+## 8. Что хранить и что не хранить
+
+### Хранить
+- canonical facts;
+- balance snapshots;
+- turnover snapshots;
+- derived features;
+- anomaly signals;
+- relation graph edges;
+- baseline state;
+- analytical summaries.
+
+### Не хранить бездумно
+- полный сырой JSON от каждого live-вызова навсегда;
+- дубли всей 1С на каждый пользовательский запрос;
+- полный срез компании в контексте LLM.
+
+---
+
+## 9. Технологический стек (рекомендуемый уровень)
+
+### Runtime bridge
+- `1c-mcp-toolkit`
+
+### Extraction / jobs
+- Python
+- job runner / scheduler
+- очередь задач по необходимости
+
+### Canonical store
+- PostgreSQL как основной store
+
+### Heavy analytics
+- DuckDB / Polars / Pandas для batch-прогонов
+- при росте объёмов — возможен переход на более тяжёлый аналитический backend
+
+### Assistant layer
+- OpenAI / локальная LLM
+- tool calling
+- оркестрация между analytics store и runtime bridge
+
+---
+
+## 10. Ограничения безопасности
+
+### Жёсткие ограничения
+- только read-only доступ к 1С;
+- никакого `execute_code`;
+- никакой записи в 1С;
+- никакой модификации конфигурации продовой 1С;
+- endpoint не публикуется наружу;
+- доступ только из локального / доверенного контура;
+- отдельный технический пользователь 1С.
+
+### Важно
+Этот проект является **аналитической надстройкой**, а не операционным контуром.
+
+---
+
+## 11. Этапы реализации
+
+## Stage 1. Фиксация runtime bridge
+- зафиксировать `1c-mcp-toolkit` как основной live semantic bridge;
+- описать approved methods;
+- зафиксировать guardrails.
+
+## Stage 2. Canonical schema
+- спроектировать canonical accounting schema;
+- описать сущности, связи, ключи и snapshots.
+
+## Stage 3. Historical loader
+- реализовать initial historical load;
+- загрузить закрытые периоды;
+- собрать baseline history.
+
+## Stage 4. Incremental refresh
+- реализовать обновление открытого периода;
+- определить правила инкрементальной синхронизации.
+
+## Stage 5. Feature / anomaly engine
+- реализовать rule engine;
+- реализовать baseline comparison;
+- реализовать anomaly signals и risk patterns.
+
+## Stage 6. Assistant orchestration
+- реализовать маршрутизацию вопроса;
+- выбор между analytics store и live bridge;
+- сформировать интерактивный слой ответов.
+
+---
+
+## 12. Deliverables
+
+На выходе этапа должны появиться:
+
+1. `accounting_canonical_schema.md`
+2. `analytics_store_design.md`
+3. `refresh_strategy.md`
+4. `historical_load_plan.md`
+5. `incremental_refresh_plan.md`
+6. `anomaly_engine_spec.md`
+7. `assistant_orchestration_spec.md`
+8. `security_guardrails_readonly.md`
+
+---
+
+## 13. Критерии приёмки
+
+Этап считается успешным, если:
+
+1. live bridge используется только для точечных запросов и drill-down;
+2. тяжёлая аналитика вынесена в отдельный analytical layer;
+3. закрытые периоды загружаются как baseline;
+4. открытые периоды обновляются инкрементально;
+5. аномалии и паттерны считаются вне LLM;
+6. assistant отвечает быстро на типовые вопросы за счёт analytics store;
+7. assistant может идти в live bridge только по необходимости;
+8. система не требует write-доступа в 1С.
+
+---
+
+## 14. Резюме
+
+`1c-mcp-toolkit` решает важнейшую задачу:
+он даёт **живой runtime semantic bridge** к 1С.
+
+Но он **не должен** быть единственным аналитическим слоем.
+
+Полный аналитический контур строится так:
+
+**1С -> Runtime Semantic Bridge -> Canonical Accounting Store -> Feature / Anomaly Engine -> Assistant Orchestrator**
+
+И рядом:
+**1С -> OData Discovery Layer**
+
+Именно такая архитектура:
+- масштабируется;
+- не убивает производительность;
+- не делает LLM вычислительным ядром;
+- позволяет анализировать большие срезы, периоды и паттерны;
+- сохраняет живой доступ к актуальной 1С для точечных drill-down сценариев.