# Архитектурный Stage Report (AS-IS)

Дата фиксации: 2026-03-23  
Проект: NDC 1C analytics bridge  
Контур: локальный стенд (Windows, тестовая база 1С)

## 1. Резюме этапа

На текущем этапе подтверждён рабочий **read-only runtime мост** к живой 1С через `1c-mcp-toolkit` в proxy-режиме.  
Три критические бухгалтерские проверки закрыты как `PROVEN`:

1. `document -> posting -> debit/credit account`
2. `posting -> subconto[1..3] -> counterparty / contract / item`
3. Объяснение реального сальдо через агрегат движений (`delta = 0.0`)

Официальный статус решения: `adopt with restrictions`.

## 2. Цель этапа (что фиксируем)

Зафиксировать не идею, а фактическое состояние архитектуры:

- как реально ходят данные;
- что именно работает в live режиме;
- что является ограничением;
- какие артефакты подтверждают результаты;
- что берём в следующий этап.

## 3. Текущая архитектура (AS-IS)

```text
AI/клиент аналитики
    |
    | HTTP (read-only API calls)
    v
Local Proxy: onec_mcp_toolkit_proxy (FastAPI)  [127.0.0.1:6003]
    |\
    | \-- /health, /api/get_metadata, /api/execute_query, /api/get_object_by_link, ...
    |
    | Long polling bridge
    |   GET  /1c/poll
    |   POST /1c/result
    v
1C External Processing MCP_Toolkit.epf (управляемая форма, режим "Прокси")
    |
    v
Тестовая база 1С: Бухгалтерия предприятия 2.0 (2.0.67.20), платформа 8.3.27.1936
```

Дополнительно параллельно существует OData read-only слой (базовый широкий вход), но в этом stage фиксируется именно runtime-mост toolkit.

## 4. Компоненты и роль

1. `MCP_Toolkit.epf`
- Путь: `X:\1C\NDC_1C\external\1c-mcp-toolkit\build\MCP_Toolkit.epf`
- Роль: 1С-сторона моста, выполнение read-запросов в контексте базы и возврат результатов в proxy.
- Важно: форма управляемая; в обычном режиме UI может не открываться.

2. `onec_mcp_toolkit_proxy` (Python/FastAPI)
- Путь: `X:\1C\NDC_1C\external\1c-mcp-toolkit\onec_mcp_toolkit_proxy`
- Роль: единая HTTP/MCP точка входа для аналитики.
- Runtime: Miniconda env `ndc_1c_toolkit`.
- Базовый endpoint: `http://127.0.0.1:6003`.

3. 1С тестовая база
- Платформа: `8.3.27.1936`
- Конфигурация: `БП 2.0 (2.0.67.20)`
- Роль: source of truth для всех live чтений.

4. Артефактный слой (доказательства)
- Путь: `X:\1C\NDC_1C\docs\snapshots\toolkit`
- Роль: хранение фактических ответов/логов проверки этапа.

## 5. Семантика доступа к данным (очень важно)

### 5.1 Что это сейчас

Это **live request/response bridge**:

- каждый запрос читается из текущего состояния 1С на момент вызова;
- данные не берутся из локальной копии/реплики;
- нет постоянного stream-пайплайна “само обновляется”.

### 5.2 Что это не сейчас

- это не полноценная витрина данных по всей компании;
- это не always-on snapshot pipeline;
- это не CDC/стриминг изменений в фоновом режиме.

### 5.3 Практический вывод

Для точечных и средних аналитических задач мост подходит в near real-time режиме.  
Для очень широких срезов (вся компания, тяжёлые многомерные отчёты) потребуется отдельный слой агрегаций/снэпшотов.

## 6. API-поверхность, которую используем в проекте

Разрешённый operational набор:

- `get_metadata`
- `execute_query`
- `get_object_by_link`
- `get_link_of_object`
- при необходимости другие read-only методы

Запрещено в operational контуре:

- `execute_code`
- любые write/mutation операции.

## 7. Ограничения и guardrails

Обязательные ограничения на текущем этапе:

1. Только read-only вызовы.
2. `ALLOW_DANGEROUS_WITH_APPROVAL=false`.
3. Endpoint не публиковать наружу.
4. Использовать отдельного техпользователя 1С с правами чтения.
5. Все спорные/рисковые действия маркировать как `manual required`.

## 8. Подтверждённые доказательства этапа

### 8.1 Проверка 1: document -> posting -> debit/credit

- Есть реальная проводка:
  - документ: `Счет-фактура полученный 00000000001 от 03.08.2030 12:00:00`
  - Дт: `68.02`
  - Кт: `19.04`
  - сумма: `500`
- Документ прочитан по ссылке через `get_object_by_link`.

### 8.2 Проверка 2: posting -> subconto[1..3]

Есть реальные примеры:

- `Контрагент + Договор`:
  - `СубконтоКт1 (Контрагенты)` = `Ассоциация "СРО"СОВЕТ ПРОЕКТИРОВЩИКОВ"`
  - `СубконтоКт2 (Договоры)` = `дело А40-201628/21`
- `Номенклатура/склад`:
  - `СубконтоКт1 (Номенклатура)` = `Портьерные шторы Garden kolor`
  - `СубконтоКт3 (Склады)` = `Основной склад`

### 8.3 Проверка 3: объяснение сальдо движениями

По счёту `68.02`:

- `СальдоИтого (Остатки) = 28363.8`
- `ОборотДт - ОборотКт = 49600886.74 - 49572522.94 = 28363.8`
- `delta = 0.0`

## 9. Риски и технический долг

1. Heavy analytics latency
- На очень широких задачах модель вынуждена собирать картину по частям.

2. Отсутствие материализованной витрины
- Нет быстрого “единый срез по компании” без серии запросов.

3. Нюанс кодировки
- В отдельных ответах (`get_link_of_object`) требуется нормализация строки ссылки.

4. Риск регресса через опасные инструменты
- `execute_code` существует в toolkit и должен быть процедурно/технически заблокирован в operational потоке.

## 10. Решения, принятые по итогу этапа

1. Оставляем `OData` как базовый read-only широкий слой.
2. `1c-mcp-toolkit` фиксируем как рабочий runtime/deeper слой для семантических проверок и интерактивной аналитики.
3. Статус внедрения: `adopt with restrictions`.

## 11. Что делаем следующим этапом

Этап 2 (production-hardening):

1. Ввести жёсткие технические guardrails на запрет `execute_code`.
2. Формализовать query-профили (шаблоны безопасных read-only запросов).
3. Добавить слой агрегатов/плановых снэпшотов для тяжёлой аналитики.
4. Настроить эксплуатационный регламент:
   - health-check;
   - контроль channel;
   - таймауты;
   - логирование и аудит вызовов.

## 12. Список ключевых артефактов этапа

- `X:\1C\NDC_1C\docs\toolkit_inventory.md`
- `X:\1C\NDC_1C\docs\toolkit_install_runbook.md`
- `X:\1C\NDC_1C\docs\toolkit_smoke_test_report.md`
- `X:\1C\NDC_1C\docs\toolkit_semantic_probe_report.md`
- `X:\1C\NDC_1C\docs\toolkit_decision_note.md`
- `X:\1C\NDC_1C\docs\snapshots\toolkit\semantic_probe_live_summary.json`

---

Stage считаем зафиксированным на дату `2026-03-23`:  
**Live read-only bridge подтверждён, критические бухгалтерские цепочки доказаны, архитектурный статус — `adopt with restrictions`.**
