Initial import NDC_1C
This commit is contained in:
@@ -0,0 +1,324 @@
|
||||
# 1S MCP Toolkit — ТЗ на установку и первичный PoC
|
||||
|
||||
## 1. Контекст и цель
|
||||
|
||||
Нужно поднять **локальный, изолированный runtime-мост** к уже существующей 1С-базе без передачи данных во внешние сервисы и без изменения операционной логики бухгалтерии.
|
||||
|
||||
Цель этого этапа:
|
||||
- проверить, можно ли использовать **1c-mcp-toolkit** как **живой read-only semantic bridge** рядом с существующей 1С;
|
||||
- получить не только доступ к OData, но и более глубокий runtime-доступ к метаданным, объектам и запросам;
|
||||
- подтвердить, что мост можно запустить **без merge чужой тяжёлой конфигурации** в базу и без ломки клиентского контура;
|
||||
- проверить, подходит ли этот инструмент как основа для:
|
||||
- runtime-анализа бухгалтерии;
|
||||
- фоновых аналитических прогонов;
|
||||
- интерактивных запросов ассистента;
|
||||
- построения полной семантической картины по документам, движениям, счетам, субконто и связям.
|
||||
|
||||
Ожидаемый результат этапа:
|
||||
- поднят локальный экземпляр **1c-mcp-toolkit**;
|
||||
- подтверждён запуск на нашей платформе 1С;
|
||||
- проверены read-only методы;
|
||||
- подтверждено или опровергнуто, что toolkit пригоден как основной runtime-мост.
|
||||
|
||||
---
|
||||
|
||||
## 2. Почему рассматривается именно 1c-mcp-toolkit
|
||||
|
||||
`ROCTUP/1c-mcp-toolkit` позиционируется как мост через внешнюю обработку `.epf`, с встроенным HTTP-сервером, без публикации 1С-сервера и без COM-соединения как обязательного требования. В репозитории также заявлены:
|
||||
- MCP Server;
|
||||
- local REST API;
|
||||
- `execute_query`;
|
||||
- `get_metadata`;
|
||||
- `get_object_by_link`;
|
||||
- анонимизация/токенизация сущностей.
|
||||
|
||||
Для нашей архитектуры это важно, потому что инструмент выглядит как:
|
||||
- **минимально инвазивный**;
|
||||
- **локально разворачиваемый**;
|
||||
- **не требующий передачи данных наружу**;
|
||||
- **не требующий тяжёлого внедрения в конфигурацию**;
|
||||
- потенциально дающий более глубокий доступ, чем OData.
|
||||
|
||||
---
|
||||
|
||||
## 3. Наша архитектурная позиция
|
||||
|
||||
### 3.1. Что мы делаем
|
||||
Мы строим **аналитическую надстройку** над существующей 1С.
|
||||
|
||||
### 3.2. Что мы не делаем
|
||||
**Ни на каком этапе этого проекта мы не пишем в клиентскую 1С-базу операционные данные.**
|
||||
**Мы не редактируем документы, не проводим документы, не меняем движения, не меняем регистры, не меняем бухгалтерскую логику и не берём на себя ответственность за операционный контур 1С.**
|
||||
|
||||
Это принципиальное и жёсткое ограничение проекта.
|
||||
|
||||
### 3.3. Допустимый формат работы
|
||||
Допустим только:
|
||||
- read-only доступ;
|
||||
- выполнение запросов на чтение;
|
||||
- чтение метаданных;
|
||||
- чтение объектов по ссылкам;
|
||||
- чтение связей и аналитик;
|
||||
- локальный runtime-мост рядом с 1С.
|
||||
|
||||
---
|
||||
|
||||
## 4. Главный риск и как с ним работать
|
||||
|
||||
В toolkit есть не только read-only методы, но и возможность выполнения произвольного кода (`execute_code`) через интерфейс проекта. Это **неприемлемо** для нашего проекта как рабочий режим.
|
||||
|
||||
### Жёсткое правило:
|
||||
Использовать **только read-only методы**, в первую очередь:
|
||||
- `get_metadata`
|
||||
- `get_object_by_link`
|
||||
- `execute_query`
|
||||
- и иные методы чтения, если они не меняют состояние базы.
|
||||
|
||||
### Категорически запрещено:
|
||||
- `execute_code`
|
||||
- любые write-операции
|
||||
- любые операции, создающие или изменяющие объекты
|
||||
- любые действия, меняющие состояние базы
|
||||
|
||||
### Требование к внедрению:
|
||||
- организационно запретить использование write/mutation-вызовов;
|
||||
- сетево не публиковать мост наружу;
|
||||
- запускать только в локальном/изолированном контуре;
|
||||
- ограничить доступ к endpoint только локальной машине или доверенной внутренней сети;
|
||||
- использовать отдельного технического пользователя 1С.
|
||||
|
||||
---
|
||||
|
||||
## 5. Совместимость и текущая гипотеза
|
||||
|
||||
По документации проекта явно фигурирует совместимость с диапазоном `8.2.13+ / 8.3.25`. У нас платформа:
|
||||
- **1С:Предприятие 8.3.27.1936**
|
||||
- конфигурация: **Бухгалтерия предприятия, редакция 2.0 (2.0.67.20)**
|
||||
|
||||
Это значит:
|
||||
- явного подтверждения `8.3.27` в документации нет;
|
||||
- явного запрета на `8.3.27` тоже нет;
|
||||
- значит нужен **практический smoke test**.
|
||||
|
||||
Текущая гипотеза:
|
||||
**1c-mcp-toolkit — приоритетный PoC-кандидат, но совместимость с 8.3.27.1936 должна быть подтверждена на стенде.**
|
||||
|
||||
---
|
||||
|
||||
## 6. Что конкретно мы хотим получить от этой штуки
|
||||
|
||||
Инструмент должен, по возможности, дать:
|
||||
|
||||
### 6.1. Discovery / introspection
|
||||
- список сущностей и типов;
|
||||
- метаданные;
|
||||
- структуру объектов;
|
||||
- типы ссылок;
|
||||
- поля и их типы;
|
||||
- навигацию по объектам.
|
||||
|
||||
### 6.2. Runtime access
|
||||
- чтение документа по ссылке;
|
||||
- чтение движений/регистров;
|
||||
- чтение проводок;
|
||||
- чтение аналитик `subconto[1..3]`;
|
||||
- выполнение произвольных **read-only** запросов на языке запросов 1С.
|
||||
|
||||
### 6.3. Semantic bridge
|
||||
- возможность проходить цепочки:
|
||||
- `document -> posting`
|
||||
- `posting -> debit/credit account`
|
||||
- `posting -> subconto[1..3]`
|
||||
- `counterparty -> contract -> documents`
|
||||
- `account -> movements -> balance`
|
||||
|
||||
### 6.4. Privacy / masking
|
||||
- анонимизация сущностей, если нужно для AI-слоя;
|
||||
- токенизация чувствительных идентификаторов без передачи наружу.
|
||||
|
||||
---
|
||||
|
||||
## 7. Что должен сделать Codex
|
||||
|
||||
### 7.1. Подготовка
|
||||
1. Скачать репозиторий:
|
||||
- <https://github.com/ROCTUP/1c-mcp-toolkit>
|
||||
2. Изучить:
|
||||
- `README.md`
|
||||
- `README_FULL.md`
|
||||
- `ANONYMIZATION.md`
|
||||
3. Зафиксировать:
|
||||
- способ запуска;
|
||||
- требуемые компоненты;
|
||||
- какой файл `.epf` нужен для запуска;
|
||||
- какой локальный endpoint должен подняться.
|
||||
|
||||
### 7.2. Проверка состава репозитория
|
||||
Codex должен определить:
|
||||
- где лежит финальный `.epf` или как он собирается;
|
||||
- нужен ли предварительный build;
|
||||
- нужен ли OneScript / .NET / Node / Python runtime вокруг проекта;
|
||||
- какие environment variables обязательны.
|
||||
|
||||
### 7.3. Подготовка стенда
|
||||
Codex должен подготовить:
|
||||
- локальную инструкцию запуска под нашу Windows-машину;
|
||||
- чеклист запуска рядом с уже существующей 1С;
|
||||
- список того, что пользователь должен сделать руками в 1С, если это необходимо.
|
||||
|
||||
### 7.4. Запуск PoC
|
||||
Codex должен:
|
||||
1. Поднять toolkit локально;
|
||||
2. Проверить, что endpoint отвечает;
|
||||
3. Проверить read-only методы;
|
||||
4. Провести smoke test по метаданным;
|
||||
5. Провести test query;
|
||||
6. Проверить пригодность для наших бухгалтерских цепочек.
|
||||
|
||||
---
|
||||
|
||||
## 8. Предварительные ограничения для Codex
|
||||
|
||||
Codex **не должен**:
|
||||
- пытаться встроить toolkit в конфигурацию 1С без явной необходимости;
|
||||
- включать write-режимы;
|
||||
- использовать `execute_code`;
|
||||
- публиковать endpoint во внешний интернет;
|
||||
- открывать доступ неограниченному числу клиентов;
|
||||
- менять конфигурацию продовой 1С.
|
||||
|
||||
Codex **должен**:
|
||||
- ориентироваться только на изолированный контур;
|
||||
- трактовать проект как read-only analytics bridge;
|
||||
- сначала подтвердить локальный запуск;
|
||||
- все сомнительные действия помечать как `manual required`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Практический план установки
|
||||
|
||||
### Этап A. Подготовка артефактов
|
||||
1. Клонировать репозиторий.
|
||||
2. Найти финальный `.epf` или build-инструкцию.
|
||||
3. Проверить наличие:
|
||||
- примеров запуска;
|
||||
- конфигурации endpoint;
|
||||
- описания REST/MCP режима.
|
||||
|
||||
### Этап B. Локальный запуск
|
||||
1. Открыть `.epf` в нашей тестовой 1С.
|
||||
2. Попробовать поднять встроенный сервер toolkit.
|
||||
3. Зафиксировать:
|
||||
- URL;
|
||||
- порт;
|
||||
- режим запуска;
|
||||
- тип авторизации.
|
||||
|
||||
### Этап C. Smoke test
|
||||
Проверить:
|
||||
- `get_metadata`
|
||||
- `get_object_by_link`
|
||||
- `execute_query` на безопасном select
|
||||
- наличие анонимизации
|
||||
- отсутствие необходимости публикации 1С через IIS для базового запуска, если toolkit реально работает через свой внутренний сервер
|
||||
|
||||
### Этап D. Семантический PoC
|
||||
Проверить, можно ли через toolkit достать:
|
||||
- документ + движения;
|
||||
- счёт + проводки;
|
||||
- `subconto[1..3]`;
|
||||
- реальное сальдо и его расшифровку;
|
||||
- метаданные по нужным бухгалтерским объектам.
|
||||
|
||||
---
|
||||
|
||||
## 10. Что считать успехом
|
||||
|
||||
### Минимальный успех
|
||||
- toolkit запускается на 8.3.27.1936;
|
||||
- endpoint отвечает локально;
|
||||
- `get_metadata` работает;
|
||||
- `execute_query` на чтение работает.
|
||||
|
||||
### Рабочий успех
|
||||
- toolkit позволяет читать нужные бухгалтерские сущности;
|
||||
- toolkit позволяет проходить критические цепочки;
|
||||
- toolkit может использоваться как runtime semantic bridge рядом с OData.
|
||||
|
||||
### Провал PoC
|
||||
- toolkit не стартует на 8.3.27;
|
||||
- toolkit требует неприемлемых модификаций 1С;
|
||||
- toolkit не даёт read-only универсального доступа;
|
||||
- toolkit usable only through dangerous mutation/code paths.
|
||||
|
||||
---
|
||||
|
||||
## 11. Deliverables от Codex
|
||||
|
||||
Codex должен вернуть:
|
||||
|
||||
1. `toolkit_inventory.md`
|
||||
- состав проекта
|
||||
- способ запуска
|
||||
- файлы и зависимости
|
||||
|
||||
2. `toolkit_install_runbook.md`
|
||||
- пошаговая инструкция запуска под наш стенд
|
||||
|
||||
3. `toolkit_smoke_test_report.md`
|
||||
- что завелось
|
||||
- что не завелось
|
||||
- ошибки
|
||||
- версия 1С
|
||||
- endpoint
|
||||
|
||||
4. `toolkit_semantic_probe_report.md`
|
||||
- что доступно по метаданным
|
||||
- какие цепочки реально читаются
|
||||
- где остались провалы
|
||||
|
||||
5. `toolkit_decision_note.md`
|
||||
- verdict:
|
||||
- `adopt`
|
||||
- `adopt with restrictions`
|
||||
- `reject`
|
||||
|
||||
---
|
||||
|
||||
## 12. Отдельный акцент для Codex
|
||||
|
||||
Нужно смотреть на проект **не как на “чат-надстройку”**, а как на **универсальный runtime-мост**.
|
||||
|
||||
Нас интересует не “умеет ли он ответить на 5 сценариев”, а:
|
||||
- даёт ли он живой доступ к актуальной 1С;
|
||||
- даёт ли он runtime-метаданные;
|
||||
- даёт ли он доступ к семантике;
|
||||
- можно ли его использовать как базовый нижний слой для:
|
||||
- онтологии;
|
||||
- графа связей;
|
||||
- фоновой аналитики;
|
||||
- ассистента.
|
||||
|
||||
---
|
||||
|
||||
## 13. Ссылки
|
||||
|
||||
- GitHub: <https://github.com/ROCTUP/1c-mcp-toolkit>
|
||||
- README FULL: <https://github.com/ROCTUP/1c-mcp-toolkit/blob/main/README_FULL.md>
|
||||
- Anonymization: <https://github.com/ROCTUP/1c-mcp-toolkit/blob/main/ANONYMIZATION.md>
|
||||
|
||||
---
|
||||
|
||||
## 14. Резюме
|
||||
|
||||
На текущем этапе `1c-mcp-toolkit` — **лучший кандидат для первого серьёзного PoC** под runtime semantic bridge рядом с существующей 1С, потому что он обещает:
|
||||
- локальный запуск;
|
||||
- минимальную инвазивность;
|
||||
- read-oriented runtime access;
|
||||
- query/metadata layer;
|
||||
- анонимизацию.
|
||||
|
||||
Но это всё должно быть **доказано практическим запуском на нашей версии 1С**.
|
||||
|
||||
Главное правило этапа:
|
||||
**никаких write/mutation-операций, никакого изменения операционного контура 1С, только read-only аналитическая надстройка.**
|
||||
Reference in New Issue
Block a user