SILVER/NODEDC_1C
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Initial import NDC_1C

Browse Source
This commit is contained in:
dctouch
2026-03-26 10:38:25 +03:00
commit a162d77ef7
2943 changed files with 3615871 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
IN/TZ_1C_OData_MCP_MVP.md
+592
View File
@@ -0,0 +1,592 @@
# ТЗ: 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 слою данных.