SILVER
/
NODEDC_1C
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_1C/IN/TZ_1C_OData_MCP_MVP.md

32 KiB
Raw Blame History

ТЗ: 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С", а внешний безопасный мост:

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. Структура каталогов

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

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

4.2. Что создать в X:\1C\NDC_1C

Нужно подготовить структуру проекта:

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-окружение

Примерно так:

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

Нужен шаблон параметров:

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.

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

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 слою данных.