# ТЗ — 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 сценариев.