llm/docs/adapter-observer-handoff.md

Аналитика адаптера 1С: передача проекта

Дата актуализации: 2026-08-07.

Назначение

adapter-observer — независимый read-only веб-интерфейс аналитики для SQL-only адаптера 1С. Он читает журналы REST и MCP, получает разрешённые снимки метаданных через публичный API адаптера и не имеет прямого доступа к SQL-базе 1С.

Сервис не является зависимостью adapter-1c-rest или adapter-1c-mcp: остановка либо обновление observer не должна влиять на работу адаптера.

Описание адаптера 1С

Адаптер 1С — SQL-only сервис для чтения метаданных и выполнения строго контролируемых операций с saved-state конфигурации 1С. Он работает через подтверждённые структуры SQL-хранилища; не запускает Configurator и не должен выдумывать метаданные, маршруты или двоичные payload.

Основные части:

• adapter-1c-rest — REST API адаптера;
• adapter-1c-mcp — MCP-шлюз, который вызывает REST API;
• adapter-1c-audit — аудит-контур REST;
• adapter-observer — независимая аналитика журналов и разрешённых read-only вызовов.

Код адаптера находится в текущем репозитории:

plugins/1c/connector/adapter_1c_server.py   реализация REST/RPC методов
plugins/1c/connector/contracts/openapi.yaml публичный HTTP-контракт
plugins/1c/mcp/adapter_1c_mcp.py             MCP-шлюз
plugins/1c/observer/                         аналитика адаптера

Где развёрнут адаптер

Контур	REST	MCP	Docker-хост	Назначение
Production / внешний	http://docker.cin.su:8011	http://docker.cin.su:8021/mcp	docker.cin.su	Основной внешний адаптер и observer.
Staging / тестовый	http://docker-test.cin.su:8011 при наличии тестового стека	http://docker-test.cin.su:8021/mcp при наличии тестового стека	test-docker	Проверка перед production.
Изолированная тестовая база	base_id=upo_test	через соответствующий MCP	выбранный контур	Разрешены контролируемые тесты и rollback.

Production-контейнеры на docker.cin.su:

adapter-1c-rest     порт 8011
adapter-1c-mcp      порт 8021
adapter-1c-audit    внутренний аудит REST
adapter-observer    порт 8031

Как проверять новые функции адаптера

До развёртывания

1. Изменить реализацию в plugins/1c/connector/adapter_1c_server.py и зафиксировать публичный контракт в plugins/1c/connector/contracts/openapi.yaml.
2. Добавить либо обновить unit/smoke-тест в tests/1c/ или scripts/smoke_1c_*.py.
3. Для новой метадаты или SQL-маршрута сначала получить доказательства из live SQL в upo_test; при неполном codec вернуть unsupported/protocol_incomplete, а не предполагать данные.
4. Прогнать тесты и smoke-проверку на upo_test.

Staging-проверка

Развернуть обновлённые adapter-1c-rest и при необходимости adapter-1c-mcp на test-docker. Не использовать staging вместо external MCP production без явного запроса.

Проверять новый read-only метод через REST/RPC с явным base_id=upo_test. Проверка write-маршрута должна пройти обязательные plan/preflight/apply/rollback-gates и не даёт права заявлять, что Configurator принял или активировал изменение.

Полезные проверки:

# Контейнеры и порты выбранного контура
docker --host ssh://test-docker ps --format '{{.Names}} {{.Image}} {{.Status}} {{.Ports}}'

# Контракт/доступные методы на REST
Invoke-WebRequest -UseBasicParsing http://docker-test.cin.su:8011/methods

# Health observer после тестового вызова
Invoke-WebRequest -UseBasicParsing http://docker-test.cin.su:8031/health

Пути и аргументы нового метода нельзя составлять по догадке: использовать только его документированный контракт и подтверждённые публичные селекторы.

Как обновлять аналитику вместе с адаптером

Каждое изменение адаптера нужно оценивать как изменение наблюдаемого контракта.

Изменение адаптера	Что изменить в observer
Новый метод аудита или новый статус	Проверить event_view, фильтр статусов, группировку summary и русские подписи.
Новый read-only метод для объекта	Добавить его в жёсткий allowlist /api/object/action только после проверки публичного селектора и безопасного ответа.
Новый тип метаданных	Добавить его в treeGroups, если он должен быть виден в дереве.
Новое поле длительности	Оставить в API машинское значение, а в UI провести через duration().
Изменение схемы audit JSONL	Сохранить обратную совместимость: неизвестные поля показывать только в деталях, отсутствующие поля считать необязательными.
Новый write-маршрут	Не добавлять кнопку выполнения в observer. Допустимо отобразить только подтверждённую capability/статус после отдельного проектного решения.

Обязательная последовательность релиза:

1. Сначала обновить адаптер и проверить его новый метод на upo_test.
2. Убедиться, что REST/MCP audit содержит безопасную запись вызова без SQL, BSL, payload и секретов.
3. Обновить observer в staging; открыть новый сценарий в UI и проверить, что метод не классифицируется как exception ошибочно.
4. Обновить observer на production вместе с совместимой версией адаптера.
5. Проверить /health, журнал, аналитику и конкретный объект в дереве.

Observer не должен требовать одновременный рестарт адаптера. При выпуске только frontend/observer достаточно пересоздать adapter-observer; REST и MCP остаются запущенными.

Что сделано

Интерфейс

• Журнал REST-запросов с фильтрами по методу, базе, статусу, периоду и минимальной длительности.
• Аналитика p50/p95, медленных методов, исключений и ожидаемых безопасных отказов.
• Корреляция MCP ↔ REST по request_id.
• Дерево метаданных конфигурации с разделом «Справочники».
• Для каждого доступного справочника отображаются read-only действия:
  • Карточка;
  • Свойства;
  • Реквизиты;
  • Формы;
  • Команды;
  • Модули;
  • Макеты;
  • Связи.
• Результат действия открывается в диалоге с названием операции, объектом, статусом и длительностью.
• Поиск по уже загруженному списку справочников и счётчик Показано: N из M.

Время выполнения

• Во всех пользовательских представлениях миллисекунды форматируются в секунды, минуты и часы.
• Фильтр минимальной длительности вводится в секундах.
• В технических API-полях сохраняется duration_ms: это контрактное машинное значение, не пользовательская подпись.

Производительность

• Observer отдаёт до 1000 объектов за один запрос к metadata.objects.list.
• Для базы upo загружается 798 доступных справочников из 825 объектов одного типа одним запросом; 27 объектов скрыты адаптером как отсутствующие/нечитаемые.
• Проверенное время live-сканирования этого списка: около 18,7 секунды. Это время адаптера и SQL-чтения, а не рендеринга кнопок в браузере.

Безопасность

• Observer вызывает только жёстко заданный allowlist read-only методов для строки справочника.
• Новые действия не выполняют запись, подготовку saved-state, активацию конфигурации или операции Configurator.
• В интерфейсе не восстанавливаются исторические запросы из audit JSONL.

Что ещё нужно сделать

Приоритетный следующий этап:

1. Добавить быстрый серверный поиск справочника по имени, чтобы не ожидать полное live-сканирование при работе с одним объектом.
2. Добавить отображение прогресса при загрузке больших разделов: число прочитанных объектов, текущая страница и время ожидания.
3. Вынести перечень разрешённых действий и русские названия в отдельную конфигурацию/контракт, а не хранить в фронтенд-коде.
4. Добавить компактные пользовательские карточки результатов действий вместо показа полного JSON; JSON сохранить как диагностическую вкладку.
5. Добавить тесты UI/HTTP для сценария: открыть «Справочники» → загрузить → увидеть кнопки → выполнить «Карточка».
6. Добавить version/release marker в /health и UI, чтобы быстро отличать старую Docker-сборку от актуальной.
7. Добавить снимки и сравнение аналитики между релизами: список методов, покрытие метаданных, p50/p95 и изменения ошибок.
8. До публикации вне внутренней сети определить аутентификацию, роли, срок хранения audit-данных и экспортируемые поля.

Не реализовывать без отдельного разрешения:

• повтор исторических write/activation/repository-запросов;
• прямое подключение observer к SQL 1С;
• запуск или автоматизацию Configurator;
• вывод BSL-текста, SQL-полей, паролей или ключей из журналов.

Исходные файлы

plugins/1c/observer/
  observer_server.py          HTTP API и безопасный allowlist действий
  web/index.html              оболочка интерфейса
  web/assets/app.js           UI, форматирование времени, дерево, действия
  web/assets/style.css        стили
  Dockerfile                  образ observer

core/deploy/docker/adapter-observer/
  compose.yaml                отдельный Docker Compose стек
  .env.example                пример runtime-переменных

docs/runbooks/adapter-observer.md
  эксплуатационный контракт и ограничения

Docker-развёртывание

Текущий production-хост

• Docker host: docker.cin.su.
• Контейнер: adapter-observer.
• URL: http://docker.cin.su:8031/.
• Образ: adapter-observer:latest.
• Порт: 8031.
• Внешняя сеть адаптера: adapter-1c_default.
• Read-only тома журналов:
  • adapter-1c_adapter-1c-data → /audit:ro;
  • adapter-1c-mcp_adapter-1c-mcp-data → /mcp-audit:ro.
• Собственный state-том: adapter-observer_adapter-observer-state.

Команда обновления

Из корня текущего репозитория:

$env:DOCKER_HOST = 'ssh://docker.cin.su'
docker compose `
  --project-directory 'Z:\codex\LLM\core\deploy\docker\adapter-observer' `
  -f 'Z:\codex\LLM\core\deploy\docker\adapter-observer\compose.yaml' `
  up -d --build adapter-observer

После обновления:

Invoke-WebRequest -UseBasicParsing http://docker.cin.su:8031/health
docker --host ssh://docker.cin.su ps --filter 'name=^/adapter-observer$'

Команда пересоздаёт только adapter-observer. Не запускать docker compose down в проектах REST/MCP адаптера и не перезапускать adapter-1c-rest или adapter-1c-mcp ради обновления аналитики.

Тестовый хост

Для staging используется тот же стек с DOCKER_HOST='ssh://test-docker' и URL http://docker-test.cin.su:8031/.

Проверки после переноса

1. GET /health возвращает status: ok и показывает файлы REST/MCP audit.
2. Открыть «Дерево объектов» и загрузить upo.
3. Нажать «Читать» у «Справочники»: блок должен остаться раскрытым.
4. Убедиться, что видна строка вида 798 объектов · N с без единицы мс.
5. У первой строки должны быть восемь кнопок действий.
6. Нажать «Карточка»: открывается диалог с успешным статусом и читаемой длительностью.