Initial import NDC_1C

2026-03-26 10:38:25 +03:00
commit a162d77ef7
2943 changed files with 3615871 additions and 0 deletions
@@ -0,0 +1,252 @@
+# Bootstrap Runbook: Полный пайплайн запуска с нуля (новая машина)
+
+Дата: 2026-03-23  
+Статус: рабочий контур подтвержден (`adopt with restrictions`)  
+Цель: поднять наш текущий live read-only bridge к 1С с нуля на новой Windows-машине.
+
+## 1. Что в итоге должно работать
+
+После выполнения шагов должны одновременно работать:
+
+1. Python proxy (`onec_mcp_toolkit_proxy`) на `http://127.0.0.1:6003`
+2. 1С:Предприятие с открытой обработкой `MCP_Toolkit.epf` в режиме `Прокси`
+3. Успешные read-only вызовы:
+   - `get_metadata`
+   - `execute_query`
+   - `get_link_of_object`
+   - `get_object_by_link`
+
+Важно: это live request/response мост, не оффлайн-реплика.
+
+## 2. Архитектура (минимум)
+
+```text
+Клиент/ассистент -> HTTP -> Python Proxy (6003) -> /1c/poll,/1c/result -> MCP_Toolkit.epf -> База 1С
+```
+
+## 3. Что нужно на новой машине
+
+1. Windows (рекомендуемо 64-bit).
+2. Установленная платформа 1С (в нашем контуре: `8.3.27.1936`).
+3. Тестовая база 1С (БП 2.0) и рабочий пользователь с read-only правами.
+4. Git.
+5. Miniconda.
+6. Доступ к репозиторию `ROCTUP/1c-mcp-toolkit`.
+
+## 4. Рекомендованная структура папок
+
+```text
+X:\1C\
+  NDC_1C\
+    docs\
+    external\
+      1c-mcp-toolkit\
+```
+
+Если диска `X:` нет, можно использовать любой путь, но держать единую структуру.
+
+## 5. Установка и подготовка окружения
+
+### 5.1 Клонировать toolkit
+
+```powershell
+git clone https://github.com/ROCTUP/1c-mcp-toolkit X:\1C\NDC_1C\external\1c-mcp-toolkit
+```
+
+### 5.2 Проверить `.epf` артефакты
+
+```powershell
+Get-ChildItem X:\1C\NDC_1C\external\1c-mcp-toolkit\build
+```
+
+Ожидаемые файлы:
+
+- `MCP_Toolkit.epf` (x64)
+- `MCP_Toolkit_x86.epf` (x86 fallback)
+
+### 5.3 Создать изолированную conda-среду
+
+```powershell
+& 'C:\Users\<USER>\miniconda3\Scripts\conda.exe' create -y -n ndc_1c_toolkit python=3.11
+```
+
+### 5.4 Установить зависимости proxy
+
+```powershell
+& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m pip install --upgrade pip
+& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m pip install -r X:\1C\NDC_1C\external\1c-mcp-toolkit\requirements.txt
+```
+
+## 6. Запуск proxy (read-only профиль)
+
+Запускать из PowerShell:
+
+```powershell
+$env:PORT='6003'
+$env:TIMEOUT='180'
+$env:ALLOW_DANGEROUS_WITH_APPROVAL='false'
+$env:ANONYMIZATION_ENABLED='false'
+$env:RESPONSE_FORMAT='json'
+$env:LOG_LEVEL='INFO'
+& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m onec_mcp_toolkit_proxy
+```
+
+Проверка:
+
+```powershell
+Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing
+```
+
+Ожидаемо: HTTP 200 и `status=healthy`.
+
+## 7. Запуск 1С и обработчика
+
+### 7.1 Открыть 1С:Предприятие
+
+Открывать в **режиме Предприятия** (не Конфигуратор).  
+Если UI обработки не появляется в обычном режиме, запускать в управляемом приложении.
+
+### 7.2 Открыть внешнюю обработку
+
+`Файл -> Открыть -> X:\1C\NDC_1C\external\1c-mcp-toolkit\build\MCP_Toolkit.epf`
+
+### 7.3 Настроить форму MCP Toolkit
+
+1. Режим: `Прокси`
+2. Адрес сервера: `http://127.0.0.1:6003`
+3. Идентификатор канала: `default` (или ваш фиксированный channel)
+4. Нажать `Подключиться`
+
+Ожидаемо в логе формы:
+
+- `Подключение к серверу: http://127.0.0.1:6003`
+- `Успешное подключение к серверу`
+
+## 8. Smoke-проверка после подключения
+
+### 8.1 Metadata
+
+```powershell
+Invoke-WebRequest "http://127.0.0.1:6003/api/get_metadata?channel=default&meta_type=Документ&limit=20" -UseBasicParsing
+```
+
+Ожидаемо: `success=true`.
+
+### 8.2 Query
+
+```powershell
+$body = @{ query = "ВЫБРАТЬ ПЕРВЫЕ 1 1 КАК Test"; limit = 1 } | ConvertTo-Json
+Invoke-WebRequest "http://127.0.0.1:6003/api/execute_query?channel=default" `
+  -Method POST -ContentType "application/json; charset=utf-8" -Body $body -UseBasicParsing
+```
+
+Ожидаемо: `success=true`, `Test=1`.
+
+### 8.3 Object link flow
+
+1. Получить `object_description` (например, из `execute_query`).
+2. Вызвать `get_link_of_object`.
+3. Передать ссылку в `get_object_by_link`.
+
+Ожидаемо: объект документа читается.
+
+## 9. Ежедневный рабочий цикл (операторский)
+
+### Старт дня
+
+1. Запустить proxy.
+2. Проверить `/health`.
+3. Запустить 1С и открыть `MCP_Toolkit.epf`.
+4. Проверить статус `Подключено`.
+5. Выполнить быстрый test query.
+
+### Стоп дня
+
+1. Отключиться в форме MCP Toolkit.
+2. Закрыть 1С.
+3. Остановить proxy (Ctrl+C/Stop-Process).
+
+## 10. Траблшутинг (частые проблемы)
+
+### 10.1 Ошибка `Не могу установить соединение` в форме 1С
+
+Причина: proxy не запущен или не слушает `6003`.  
+Проверка:
+
+```powershell
+Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing
+```
+
+### 10.2 `timeout waiting for 1C response` на API
+
+Причина: нет активного `.epf` в том же `channel`, форма закрыта, либо канал не совпадает.
+
+### 10.3 `UI не показывается` при открытии `.epf`
+
+Обработка имеет управляемые формы.  
+Запускать в 1С:Предприятии (управляемый режим), не в Конфигураторе для рабочего контура.
+
+### 10.4 Кодировка ссылки из `get_link_of_object` выглядит “кракозябрами”
+
+Нюанс текущего ответа proxy; вызов рабочий, ссылку можно нормализовать при постобработке.
+
+## 11. Жёсткие правила безопасности
+
+1. Только read-only операции.
+2. Не использовать `execute_code`.
+3. Не выставлять `6003` во внешний интернет.
+4. Держать `ALLOW_DANGEROUS_WITH_APPROVAL=false`.
+5. Работать под отдельным техпользователем с минимальными правами чтения.
+
+## 12. Что это даёт и чего не даёт
+
+### Даёт
+
+- Живой доступ к текущим данным 1С по запросу.
+- Runtime metadata + deep read semantics (документы, проводки, субконто, сальдо).
+
+### Не даёт
+
+- Мгновенный “весь срез компании” в одном запросе для тяжёлой аналитики.
+- Автоматическую фоновой репликацию без отдельного слоя витрин/снэпшотов.
+
+## 13. Рекомендованный next step после bootstrap
+
+1. Добавить one-click старт скрипт (`Start-NDC1CBridge.ps1`).
+2. Добавить one-click smoke скрипт (`Test-NDC1CBridge.ps1`).
+3. Поднять плановую аналитическую витрину (например, 15/60 минут) для тяжёлых задач.
+
+---
+
+Итог bootstrap: на новой машине поднимаем контур за последовательность  
+`Proxy -> MCP_Toolkit.epf -> Подключение -> Smoke`  
+и получаем рабочий live read-only мост к 1С на текущем этапе проекта.
+
+_________________________________________________
+
+ЗАПУСК ПРКСИ ПЕРЕД ПОДКЛЮЮЧЕНИЕМ К ТУЛКИТ 1С
+
+_________________________________________________
+Запускай так в PowerShell:
+
+$env:PORT='6003'
+$env:TIMEOUT='180'
+$env:ALLOW_DANGEROUS_WITH_APPROVAL='false'
+$env:ANONYMIZATION_ENABLED='false'
+$env:RESPONSE_FORMAT='json'
+$env:LOG_LEVEL='INFO'
+& 'C:\Users\DCTOUCH\miniconda3\envs\ndc_1c_toolkit\python.exe' -m onec_mcp_toolkit_proxy
+
+
+Проверка, что поднялся:
+
+Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing
+
+Должен вернуть status":"healthy".
+
+Остановить:
+
+в том же окне Ctrl + C.
+
+
+