NODEDC_1C/IN/TZ_1C_OData_MCP_MVP.md

# ТЗ: MVP-мост между 1С и AI-ассистентом бухгалтерии через OData → канонический слой → MCP

## 1. Контекст и цель

### 1.1. Что дано
- Есть отдельная **изолированная копия** базы 1С для экспериментов. Это **не прод**, но контур должен быть приближен к реальному.
- По предоставленным скриншотам рабочая среда на Windows организована так:
  - `X:\1C\8.3.27.1936` — установленная платформа 1С.
  - `X:\1C\NDC_1C` — целевой отдельный контур под нашу интеграцию и сервисы.
  - `X:\1C\База бухгалтерии` — файловая база 1С.
  - Внутри `X:\1C\База бухгалтерии` присутствует `1Cv8.1CD`, то есть сейчас это **файловая информационная база**, а не SQL-серверная.
- Есть `.dt`-выгрузка и уже развёрнутая копия базы.
- Есть Windows-машина, 1С 8.3, Visual Studio Code / Codex, но **нет 1С-разработчика**.

### 1.2. Что нужно получить
Нужно построить **прототип интеграционного контура**, в котором:
1. 1С доступна **только на чтение**.
2. Внешний сервис может **самостоятельно получать данные из 1С**, без ручных выгрузок таблиц и отчётов.
3. Слой интеграции видит не только отдельные сущности, но и **их взаимосвязи**.
4. Поверх данных можно строить:
   - каноническую модель / "онтологию" бухгалтерии,
   - поисково-аналитический слой,
   - в дальнейшем — **MCP-сервер** для ассистента.
5. Решение должно быть **минимально инвазивным** к базе и пригодным для перехода от тестового контура к боевому сценарию.

### 1.3. Почему выбран такой путь
По материалам исследования, для подобного MVP ключевой поворот — уйти от ручных выгрузок и перейти к модели **постоянного доступа к данным**, с канонической моделью поверх 1С и прикладными сценариями типа сверок, поиска оснований проводок и контроля аномалий. Для старта быстрее всего использовать **OData** как стандартный интерфейс доступа к сущностям 1С, а дальше уже строить внешний адаптер и AI-слой. fileciteturn4file0

Также в исследовании отмечено, что готовой практичной OSS-онтологии 1С-бухгалтерии почти нет, поэтому MVP надо строить вокруг **собственной канонической модели**: `Posting`, `Document`, `Account`, `Subconto`, `Counterparty`, `Contract` и т. д. fileciteturn4file0turn4file1

---

## 2. Целевая архитектура MVP

### 2.1. Архитектурный принцип
На первом этапе делаем не "AI внутри 1С", а **внешний безопасный мост**:

```text
1С (read-only) -> OData -> Python adapter -> Canonical layer -> MCP/API -> Codex / ассистент
```

### 2.2. Почему именно так
Это даёт:
- минимум вмешательства в конфигурацию 1С;
- быстрый запуск на копии базы;
- возможность проверить, насколько OData реально раскрывает объекты и связи;
- возможность потом заменить или усилить внешний слой, не ломая 1С;
- прямой путь к MCP через OData bridge.

Исследование прямо указывает, что MVP-дружелюбный путь — это **OData → внешний коннектор → канонический слой**, а MCP-мосты можно использовать как ускоритель для AI-слоя поверх живых данных. fileciteturn4file0turn4file1

### 2.3. Что считается успешным результатом этапа
Успех этапа = на Windows-машине развёрнут рабочий read-only контур, который умеет:
- подключаться к 1С без ручных выгрузок;
- перечислять доступные сущности 1С через OData metadata;
- читать основные объекты бухгалтерии;
- извлекать связи между документами, проводками, счетами, контрагентами и договорами;
- отдавать эти данные наружу через локальный API / MCP-интерфейс.

---

## 3. Основная гипотеза и ограничения

### 3.1. Основная гипотеза
Гипотеза этапа: **стандартный интерфейс 1С OData даст достаточно данных и связей**, чтобы:
1. построить MVP-каноническую модель;
2. дать ассистенту доступ к прикладным сущностям;
3. подготовить переход к MCP без разработки тяжёлой подсистемы внутри 1С.

### 3.2. Что надо доказать тестами
Нужно проверить:
- доступны ли через OData основные типы сущностей;
- доступны ли регистры, документы и ссылочные поля;
- можно ли строить цепочки типа:
  - документ -> движения / проводки,
  - проводка -> счёт / субконто,
  - документ -> контрагент / договор,
  - документ -> основание / связанный объект,
  - отчётный вопрос -> набор OData-запросов.

### 3.3. Что считаем риском
Главный риск: OData отдаёт только часть сущностей или отдаёт их слишком "плоско", без достаточной глубины взаимосвязей. В этом случае OData остаётся полезным как быстрый тестовый слой, но для production-уровня может понадобиться более жёсткая схема: HTTP-сервисы 1С, шлюз `1c-gateway` или "агент внутри 1С" через интеграционные подсистемы. fileciteturn4file0turn4file1

---

## 4. Подготовка среды для работы

### 4.1. Структура каталогов
Использовать следующий контур:

```text
X:\1C\
  8.3.27.1936\        # платформа 1С
  База бухгалтерии\   # файловая база-копия с 1Cv8.1CD
  NDC_1C\             # наш рабочий контур интеграции
```

### 4.2. Что создать в `X:\1C\NDC_1C`
Нужно подготовить структуру проекта:

```text
X:\1C\NDC_1C\
  docs\
  scripts\
  logs\
  config\
  odata_probe\
  canonical_layer\
  mcp\
  tests\
  tmp\
```

### 4.3. Что должно быть установлено на машине
Обязательно:
- Windows с доступом к текущей файловой базе 1С.
- 1С 8.3.27.x.
- Python 3.11+.
- Git.
- VS Code.
- curl или PowerShell Invoke-WebRequest.

Желательно:
- Postman или Bruno для проверки HTTP/OData.
- jq для разбора JSON.
- Docker Desktop — опционально, если позже будем поднимать отдельные сервисы контейнерами.

### 4.4. Правило доступа
Сразу зафиксировать архитектурный принцип:
- **никакой записи в 1С** на этапе MVP;
- только **read-only** пользователь / сервисный доступ;
- никакого выполнения операций изменения документов, проведения, перепроведения, записи справочников.

Если библиотека или мост по умолчанию поддерживает `create/edit`, все такие операции должны быть **запрещены на уровне конфигурации доступа и на уровне кода адаптера**. Это особенно важно, поскольку `belov38/1c-odata` демонстрирует не только чтение, но и create/edit-сценарии. Исследование рекомендует использовать read-only контур и тестировать мост именно как безопасный канал чтения. fileciteturn4file0

### 4.5. Что нужно сделать в 1С до начала кода
1. Определить, можно ли включить / опубликовать OData для этой базы.
2. Создать или выделить отдельного технического пользователя.
3. Ограничить ему права до чтения.
4. Зафиксировать, какая именно конфигурация используется:
   - Бухгалтерия предприятия, редакция 2.0 / 3.0 или иная;
   - файловая или серверная база;
   - версия платформы;
   - список основных подсистем.
5. В Конфигураторе открыть конфигурацию и зафиксировать наличие:
   - документов,
   - справочников,
   - регистров бухгалтерии,
   - регистров накопления,
   - планов счетов,
   - общих модулей,
   - ролей.

Результат этого шага — короткий технический отчёт `docs/1c_inventory.md`.

---

## 5. Техническая стратегия реализации

### 5.1. Этап 1 — OData probe
Первая задача — не строить сразу продукт, а быстро проверить: **что реально видит OData в этой базе**.

Для этого делаем маленький сервис / набор скриптов `odata_probe`, который:
- подключается к OData endpoint;
- тянет `$metadata`;
- перечисляет entity sets;
- пробует читать первые записи по ключевым сущностям;
- логирует ошибки доступа и ограничения.

### 5.2. Этап 2 — canonical layer
После OData probe строим не "полную онтологию мира", а **каноническую схему MVP**.

Минимальный состав сущностей:
- `Organization`
- `Document`
- `Posting`
- `Account`
- `Subconto`
- `Counterparty`
- `Contract`
- `BankAccount`
- `Item`
- `Department`
- `Period`
- `RegisterMovement`

Это соответствует подходу из исследования: вместо поиска готовой 1С-онтологии нужно строить свою минимальную модель вокруг проводки, документа и измерений. fileciteturn4file0turn4file1

### 5.3. Этап 3 — прикладной query/API слой
После нормализации поднять API, которое отвечает не сырыми OData-объектами, а прикладными выборками:
- документы за период;
- проводки по счёту;
- движения по контрагенту;
- документы по договору;
- цепочка связей по документу;
- объяснение остатка по счёту;
- поиск нетипичных корреспонденций.

### 5.4. Этап 4 — MCP слой
После подтверждения, что OData даёт достаточную глубину, добавить MCP-слой.

На этом этапе возможны два пути:
1. **Быстрый мост от OData к MCP**.
2. Собственный MCP-сервер поверх уже нормализованного API.

Для MVP начать с готового моста, но не считать его финальным production-решением.

---

## 6. Инструменты и репозитории, которые берём в работу

### 6.1. Базовый инструмент первого этапа
#### `belov38/1c-odata`
GitHub: `https://github.com/belov38/1c-odata` citeturn910914search0turn910914search4

Зачем берём:
- самый быстрый путь проверить 1С OData без разработки тяжёлого клиента;
- подходит для Python-пробника и первых сервисных вызовов;
- позволяет быстро читать сущности и проверять фильтры/select/top/skip.

Что важно:
- библиотека умеет и запись, поэтому использовать её **только в режиме чтения**, с ограничением на уровне прав пользователя и без вызова write-операций.

### 6.2. Инструмент второго этапа, если OData окажется рабочим
#### `SysUtils/1c-gateway`
GitHub: `https://github.com/SysUtils/1c-gateway` citeturn910914search3

Зачем нужен:
- если захочется более типизированный фасад;
- если понадобится GraphQL / gRPC / нормальный middleware над OData;
- если нужно преобразовать кириллицу и сырой OData в более удобный internal API.

### 6.3. Кандидаты на MCP-слой
#### `oisee/odata_mcp_go`
GitHub: `https://github.com/oisee/odata_mcp_go` citeturn910914search2turn910914search18

#### `lemaiwo/odata-mcp-proxy`
GitHub: `https://github.com/lemaiwo/odata-mcp-proxy` (репозиторий подтверждён в стороннем описании экосистемы MCP/OData) citeturn910914search9turn910914search13

Зачем нужны:
- если OData endpoint живой, можно быстро превратить его в MCP tools;
- это даст ассистенту возможность ходить по данным как по инструментам, а не как по файлам;
- это ускоряет прототип и позволяет проверить формат взаимодействия ассистента с живой системой.

### 6.4. Резервный путь, если OData не взлетит
Как fallback держать в уме:
- FoxyLink;
- Universal Tools;
- Connector.

Их не брать первым шагом, но держать как план B, если OData не даст нужную глубину или окажется недоступен. Исследование прямо раскладывает эти инструменты как сценарий "когда OData недоступен или неудобен". fileciteturn4file0turn4file1

---

## 7. Что именно нужно сделать Codex'у

### 7.1. Создать рабочую структуру проекта
В `X:\1C\NDC_1C` развернуть каркас:
- `docs/`
- `scripts/`
- `config/`
- `odata_probe/`
- `canonical_layer/`
- `mcp/`
- `tests/`
- `logs/`

### 7.2. Подготовить Python-окружение
Примерно так:

```powershell
cd X:\1C\NDC_1C
py -3.11 -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install odata1cw requests lxml pydantic fastapi uvicorn python-dotenv
```

Если пакет `odata1cw` не ставится из PyPI, Codex должен:
1. клонировать `belov38/1c-odata`;
2. проверить способ локальной установки;
3. зафиксировать реальный рабочий способ установки в `docs/setup.md`.

### 7.3. Создать `.env.example`
Нужен шаблон параметров:

```env
ONEC_BASE_URL=http://localhost
ONEC_INFOBASE=AccountingBase
ONEC_USERNAME=readonly_user
ONEC_PASSWORD=change_me
ONEC_ODATA_PATH=/odata/standard.odata/
ONEC_TIMEOUT=30
ONEC_VERIFY_TLS=false
```

Если OData будет опубликован не на localhost, а на другой машине / IIS / Apache, переменные должны это учитывать.

### 7.4. Написать OData probe
Создать минимальный набор скриптов:

- `odata_probe/fetch_metadata.py`
- `odata_probe/list_entity_sets.py`
- `odata_probe/probe_entities.py`
- `odata_probe/dump_sample_links.py`

#### `fetch_metadata.py`
Должен:
- сходить в `$metadata`;
- сохранить XML в `logs/metadata.xml`;
- вытащить список entity sets;
- сохранить summary в `logs/entity_sets.json`.

#### `list_entity_sets.py`
Должен:
- прочитать metadata;
- вывести сущности в консоль и в файл;
- отметить подозрительно важные сущности по ключевым словам:
  - `Документ`
  - `Справочник`
  - `Регистр`
  - `ПланСчетов`
  - `Хозрасчетный`
  - `Контрагенты`
  - `Договоры`
  - `Организации`
  - `БанковскиеСчета`

#### `probe_entities.py`
Должен:
- по списку ключевых сущностей сделать запросы `top=3..10`;
- проверить, какие поля реально приходят;
- определить, есть ли ссылочные поля на другие сущности;
- сохранить результаты в `logs/probe_report.json`.

#### `dump_sample_links.py`
Должен:
- выбрать несколько сущностей;
- собрать карту полей, которые выглядят как ссылки / GUID / navigation fields;
- показать, можно ли двигаться от документа к связанным объектам.

### 7.5. Реализовать канонический слой
Создать `canonical_layer/models.py` и `canonical_layer/mappers.py`.

Нужна первая версия канонической схемы:

```python
Organization
Counterparty
Contract
Account
Subconto
Document
Posting
RegisterMovement
Period
```

Для каждой сущности описать:
- `source_entity`
- `source_id`
- `display_name`
- ключевые реквизиты
- набор ссылок на связанные сущности

### 7.6. Реализовать тестовый API
Создать FastAPI-приложение `canonical_layer/app.py`.

Минимальные эндпоинты:
- `GET /health`
- `GET /metadata/entity-sets`
- `GET /documents?from=...&to=...`
- `GET /documents/{id}`
- `GET /postings?account=...&from=...&to=...`
- `GET /counterparties/{id}/documents`
- `GET /graph/document/{id}`

`/graph/document/{id}` должен быть первым прикладным доказательством, что система видит **связи**, а не только плоские записи.

### 7.7. Подготовить черновой MCP-слой
В папке `mcp/` подготовить два варианта:

#### Вариант A — через готовый OData→MCP мост
- описать конфиг для `oisee/odata_mcp_go` или `lemaiwo/odata-mcp-proxy`;
- проверить, можно ли поднять read-only инструменты поверх OData.

#### Вариант B — собственный MCP поверх канонического API
Если готовый мост не подходит, заложить каркас собственного MCP-сервера, который работает уже не с OData напрямую, а с нашими нормализованными эндпоинтами.

---

## 8. Подробное описание этапов работ

### Этап A. Инвентаризация 1С-копии
**Цель:** понять, что именно перед нами и к чему мы подключаемся.

Нужно:
1. В Конфигураторе открыть конфигурацию.
2. Зафиксировать список подсистем и ключевых объектов.
3. Составить инвентаризационный файл:
   - тип базы: файловая;
   - путь к базе;
   - версия платформы;
   - название конфигурации;
   - основные разделы учёта.

**Результат:** `docs/1c_inventory.md`

### Этап B. Включение и проверка OData
**Цель:** доказать, что стандартный интерфейс OData вообще доступен.

Нужно:
1. Настроить публикацию OData.
2. Убедиться, что endpoint отвечает.
3. Проверить доступ к `$metadata`.
4. Протестировать авторизацию read-only пользователем.

**Результат:** `logs/metadata.xml`, `logs/entity_sets.json`

### Этап C. Пробный доступ к сущностям
**Цель:** понять, достаточно ли глубины для бухгалтерского AI-слоя.

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

**Результат:** `logs/probe_report.json`

### Этап D. Тест связей
**Цель:** понять, можно ли строить граф связей.

Нужно доказать минимум такие переходы:
- от документа к контрагенту;
- от документа к договору;
- от документа к организации;
- от документа к движениям / проводкам;
- от проводки к счетам и аналитикам.

**Результат:** `docs/linkage_report.md`

### Этап E. Каноническая модель
**Цель:** зафиксировать минимальную внутреннюю онтологию MVP.

Нужно:
- описать сущности;
- описать поля;
- описать связи;
- описать правила маппинга из OData в канонический слой.

**Результат:** `docs/canonical_model.md`

### Этап F. API и прикладные сценарии
**Цель:** доказать практическую применимость.

Нужно реализовать минимум 5 сценариев:
1. Найти документы по периоду.
2. Найти проводки по счёту.
3. Показать документы контрагента.
4. Показать граф связей документа.
5. Подготовить базовый сценарий "объясни остаток / основание проводки".

**Результат:** рабочий FastAPI-прототип.

### Этап G. MVP MCP
**Цель:** подготовить переход к ассистенту.

Нужно:
- проверить готовый OData→MCP мост;
- если взлетает — задокументировать способ запуска;
- если не взлетает — заложить собственный MCP поверх канонического API.

**Результат:** `docs/mcp_strategy.md`

---

## 9. Что именно надо проверить по OData

Это ключевой блок, потому что от него зависит весь следующий путь.

### 9.1. Проверки доступа
Нужно ответить на вопросы:
- отвечает ли `$metadata`;
- сколько entity sets публикуется;
- есть ли ограничения по ролям;
- не режет ли OData важные сущности;
- не отваливаются ли запросы по таймауту.

### 9.2. Проверки структуры
Нужно понять:
- насколько имена сущностей и полей понятны;
- есть ли navigation properties / ссылочные поля;
- можно ли восстановить структуру документа и его связей;
- как представлены планы счетов и аналитики.

### 9.3. Проверки пригодности для ассистента
Нужно ответить на главный вопрос:

> OData даёт только плоские сущности или даёт достаточно данных и связей, чтобы строить рассуждение и навигацию по бухгалтерскому контексту?

Если ответ **да**, то OData остаётся базовым мостом.
Если ответ **частично**, OData остаётся probe-слоем, а production-слой проектируется через middleware или собственный сервис.
Если ответ **нет**, идти в fallback: HTTP-сервисы 1С / агент в 1С / 1c-gateway / интеграционные подсистемы.

---

## 10. Что считать успешным исходом тестов

### Успех уровня 1
- OData опубликован.
- `belov38/1c-odata` подключается.
- metadata читается.
- entity sets видны.

### Успех уровня 2
- читаются ключевые бухгалтерские сущности;
- у сущностей видны связующие поля;
- можно собрать простую цепочку связей.

### Успех уровня 3
- построен канонический слой;
- API возвращает прикладные сущности;
- можно показать `document graph` и базовый `posting trace`.

### Успех уровня 4
- MCP-слой может ходить по этим данным как по инструментам;
- ассистент получает не статическую выгрузку, а живой read-only доступ к слою.

---

## 11. Что не делать на этом этапе

Не делать:
- прямую запись в базу;
- любые write-операции через OData;
- попытку сразу завязать ассистента на прод;
- попытку сразу построить "идеальную онтологию всего предприятия";
- перенос всех данных в огромную SQL-схему без проверки ценности;
- тяжёлое внедрение внутренних 1С-подсистем до проверки, что OData реально недостаточен.

---

## 12. Прикладные сценарии MVP, на которые надо ориентироваться

Исследование рекомендует строить MVP вокруг 3–5 операционно полезных сценариев, а не вокруг абстрактного "чат-бота про бухгалтерию". Наиболее подходящие сценарии здесь такие: fileciteturn4file0turn4file1

1. **Найти документы и проводки за период.**
2. **Показать движения по счёту / контрагенту / договору.**
3. **Показать, какие документы сформировали остаток или отклонение.**
4. **Найти нетипичные корреспонденции / аномальные паттерны.**
5. **Найти цепочку “документ -> основание -> движения -> аналитики”.**

Именно эти сценарии лучше использовать как критерий, подходит ли выбранный мост для будущего ассистента.

---

## 13. Deliverables

По итогам первой итерации Codex должен выдать:

1. `docs/1c_inventory.md`
2. `docs/setup.md`
3. `docs/canonical_model.md`
4. `docs/linkage_report.md`
5. `docs/mcp_strategy.md`
6. `logs/metadata.xml`
7. `logs/entity_sets.json`
8. `logs/probe_report.json`
9. Python-код OData probe
10. FastAPI-прототип канонического слоя
11. Черновик конфигурации MCP-моста

---

## 14. Краткое управленческое решение по стеку

На текущем этапе решение такое:

- **Стартуем с `belov38/1c-odata`** как самого короткого пути проверить 1С OData. citeturn910914search0turn910914search4
- **Строим внешний read-only адаптер**, а не тяжёлый агент внутри 1С. Это соответствует MVP-подходу из исследования. fileciteturn4file0turn4file1
- **Проверяем глубину связей**, а не просто чтение сущностей.
- **Плавно идём к MCP**, но сначала через доказательство пригодности OData.
- Если OData не даст нужной глубины, **переходим к более жёсткому слою**: `1c-gateway`, HTTP-сервисы 1С или агент внутри 1С. fileciteturn4file0turn4file1

---

## 15. Команда Codex'у в одном абзаце

Развернуть в `X:\1C\NDC_1C` read-only MVP-контур интеграции с 1С на базе OData. Сначала доказать техническую доступность и полноту `belov38/1c-odata`: получить metadata, перечислить сущности, протестировать доступ к ключевым объектам бухгалтерии и проверить, видны ли взаимосвязи между документами, проводками, счетами, контрагентами и договорами. Затем построить минимальный канонический слой и локальный API. После этого подготовить черновой MCP-слой. Главный критерий — не просто чтение записей, а способность строить прикладную навигацию и reasoning по живому read-only слою данных.