Files
MikrotikManager/docs/mcp-completion-plan.md
T

116 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MCP: план завершения работ (ветка `codex/mcp-foundation`)
Составлен 15 ноября 2026. Отмечать выполненное: `- [x]`. Источники остатка: [передача от 15 ноября](mcp-handoff-20261115.md), [именованный реестр](mcp-evidence-statistics-20261101.md), [полный план MCP](mcp-implementation-plan.md).
## Исходное состояние
- В ветке нет коммитов поверх `main` (HEAD `5efd0339`). Вся работа в рабочем дереве: 257 изменённых и 1985 новых файлов.
- `tsc --noEmit` для фронтенда и бэкенда проходит. Тесты при составлении плана не запускались.
- По записям Codex: 368 MCP-инструментов, 202 из 265 REST-маршрутов покрыты, 63 исключены, необработанных нет. Миграции `0015`–`0057`, веб-раздел `/mcp`, транспорты HTTP и stdio, OAuth.
- Открыты 7 направлений приёмки: POLL, DB, ROUTING, NATIVE, PATHS, EXTERNAL-UI, FINAL.
- Мусор вне `.gitignore`: 2048 `tmp-*` в корне, 12 каталогов `backend/dist-installation-memory*`, `.next-poll-rest-route-v2-20261030` (442 МБ), `.serena`. В `docs/` 965 файлов, в основном JSON-квитанции. `tsconfig.tsbuildinfo` отслеживается Git.
## Критерий завершения
Этапы 0–2 и 5 выполнены, MCP и контроллер выключены по умолчанию, ветка слита в `main`. Этап 3 идёт отдельными задачами по мере доступности стенда, этап 4 оформлен как явные решения.
## Этап 0. Зафиксировать работу
- [x] Сделать копию `tmp/`: `C:\Users\shats\Backups\MikrotikManager-3-tmp-20261115`, 1 563 185 файлов, 33,658 ГБ. Сухой прогон robocopy подтвердил, что всё идентично (к копированию 0, ошибок по файлам 0). Пустой каталог `mcp-scoped-controller-two-chr-20261105/v29-budget-candidate` даёт ошибку атрибутов каталога, файлов в нём нет. Частичная копия `D:\Backups\MikrotikManager-3-tmp-20261115` лишняя, удалить можно с согласия владельца
- [x] Дополнить `.gitignore`: `tmp-*`, `backend/dist-installation-memory*`, `.next-poll-*`, `.serena`
- [x] Снять с отслеживания `tsconfig.tsbuildinfo`
- [x] Реорганизовать квитанции в `docs/` — **решение владельца: оставить как есть.** Изучено, не выполнено. Безопасно переносимы 238 из 773 JSON (31%): 52 читает или пишет код и тесты (в том числе по шаблонным именам), 6 нужны раннерам в `tmp/`, 467 упомянуты по имени внутри других JSON (закреплённые пути), 6 связаны с закреплёнными md. Нужны решение владельца и переписывание закреплений. Сейчас всё закоммичено как есть, ссылки не сломаны
- [x] DB-3: LF/CRLF в миграциях 0008–0013 проверено, **кода менять не нужно.** Выводы: (1) таблица `schema_migrations` в `main` и в этой ветке хранит только `id`, хеш содержимого миграции в БД не записывается, поэтому «записанных LF-хешей» в существующей БД нет; (2) `controlled-migration-history.ts` сверяет не файлы, а квитанции контрольной истории (`mmapp_control`), которых у БД из `main` нет; (3) байты файлов сверяет `analyzeMigration` в `exactFiles()` на каждом запуске, и LF-версии 0008–0013 отвергаются с «Unclassified or changed migration file», так что коммит `42f59f14` с CRLF-блобами обязателен для Docker-образов из Linux-чекаута; (4) в этих шести файлах нет непрозрачных тел и одиночных CR, SQL по смыслу одинаков в обоих вариантах; (5) существующая БД с маркерами и без контрольной истории контрольным путём не принимается (`baseline(prefix=0)`: «Legacy or unmarked application state cannot be enrolled», есть тест `controlled-migrations.sql.test.ts`), это уже открытый пункт DB-3 про перенос непустой legacy-БД, к LF/CRLF отношения не имеет. Не запускалось: SQL-тесты на одноразовой PostgreSQL, проверена только логика и байты
- [x] Прогнать поиск секретов по всем новым файлам
- [x] Сверить число миграций: 57 sql-файлов `0000`–`0057`, все совпадают с хешами `migration-manifest.ts`; «58» в документах — линия профилей Source58, не номер миграции
- [x] Коммит: контракты и миграции
- [x] Коммит: ядро `backend/src/modules/mcp`
- [x] Коммит: адаптеры по разделам
- [x] Коммит: веб-раздел `/mcp`
- [x] Коммит: тесты и скрипты
- [x] Коммит: CI и deploy
- [x] Коммит: документация
## Этап 1. Локальная заморозка (FINAL-1)
- [x] `npm run lint`: 0 ошибок, 41 предупреждение. В `eslint.config.mjs` добавлены игнорирования локальных каталогов (`tmp`, `tmp-*`, `.next-*`, `backend/dist-*`, `.serena`, `.claude/worktrees`, `.ci/docker`); без них lint падал на недоступном каталоге в `tmp/`. Ошибки Codex в новых скриптах и тестах устранены, старые ошибки в `components/reui`, `nav-user`, `theme-provider` исправлены или подавлены `eslint-disable` с причиной (вендорный код ReUI не переписывался)
- [x] `npm run build` (корень и backend): обе сборки проходят, `tsc --noEmit` фронтенда и бэкенда чистый
- [x] `test:mcp` (корень и backend): корень 4 из 4, backend проходит после синхронизации заглушек `scheduler-automatic-root.test.mjs` с кодом (карантин восстановления, общий шлюз БД, проверка активации)
- [x] `test:mcp:pg:all`: все профили и монолит `integration.test.ts` проходят (147 проверок, в том числе `verifyMcpDatabaseBackup` с настоящим `pg_dump` из PostgreSQL 18, установленного через winget только как клиентские утилиты). Монолит после последней проверки висел: `native-create-id-acceptance.ts` ждал `router.close()` при открытых keep-alive соединениях; исправлено `closeAllConnections()`, точечная проверка `--native-create-id` завершается с кодом 0. Полный монолит после этой правки не гонялся (по решению владельца не перезапускать всё)
- [x] Playwright: `playwright.mcp.config.ts` 43 из 43, `playwright.mcp-auth.config.ts` 16 из 16 (на итоговом коде)
- [x] Сверка карты покрытия: `coverage.test.ts` проходит. 265 маршрутов (202 покрыты MCP, 63 исключены, 0 необработанных), 383 инструмента (цифра 368 в исходном плане была устаревшей)
## Этап 2. Хвосты кода без стенда
- [x] VRF: поправка сборщика для `afi=link` — **переносить некуда.** `sampleGreAfterAck` и `gre-liveness.mjs` существуют только в замороженной нагрузке стенда `tmp/owned-windows-vrf-*/payload`, в git их нет. Поправка `tmp/vrf-r2-gre-activation-review/sampler-projection.mjs` (потолок 4 вместо 3 для `/routing/route`) применяется к этой нагрузке при повторе GRE на стенде, пункт перенесён в этап 3
- [x] VRF: разбор keepalive есть в исходниках: `parseKeepalive` в `backend/src/services/gre-live.ts` (`10s,10` → 10 с и 10 повторов, `1m,3` → 60 и 3). Допуск бита `I`: исходное требование в документах не найдено, не проверено, нужно пояснение владельца
- [x] ROUTING: `/ip/dhcp-client` в сверке уже есть в `backend` (`chrTopologyCataloguePaths` через `wireguardInterfaceDependencyPaths`, обратный отсчёт `expires-after` игнорируется). Тесты `traffic-flow-chr-topology-inventory.test.ts` 9 из 9; без пути падают 2 (проверено временным удалением). Списки без `/ip/dhcp-client` лежат в незатрекенном `tmp/` (`REQUIRED_CATALOGUES` в `verify-manual-terminal.py`, `native-topology-conservation.mjs`), это стендовые скрипты, обновить при повторе A → B → A на этапе 3
- [x] POLL: причина `unknown` из CI2713 — **оформлена как неустановленная.** Факты (`mcp-remaining-work-20261026.md`): в изолированном Linux-опросе выборка на 177,409 с дала 16 намерений публикации, 15 подтверждений и `unknown/inconclusive` без итоговой квитанции; на VPS последнее чтение вернуло `running` до истечения лимита наблюдения 180 с, квитанция не указывает этап. Локально тот же backend с синтетическим RouterOS завершается за ~32 с, 143 действия в 18 атомарных группах прошли на одноразовой PostgreSQL. Число полных чтений контекста на группу снижено с пяти до четырёх. Причина задержки на VPS и замер версии на VPS открыты, `unknown` не перекрашивается в успех; остаток уходит в этап 3 (POLL: 336 операций, deadline Linux)
- [x] Inspector 2.13.0 по прямому HTTP (Bearer) и OAuth (PKCE) принят на текущем коде (HEAD `85a5fdb9`), оба прогона с кодом 0, хеши исходников до и после совпали. HTTP: каталог из одного инструмента `mm_servers_list`, вызов разрешённого сервера, отказ на запрещённом (`SERVER_DENIED`), старый и отозванный Bearer отклонены, новый принят. OAuth: обнаружение метаданных, обмен кода PKCE выполнил сам Inspector, один запрос авторизации использован один раз, обновление токена (оба токена ротированы), повтор старого refresh даёт 400 `invalid_grant` и отзыв семьи, новое согласие не запрашивалось. Результаты: `tmp/mcp-inspector-http-oauth-20261116/{http,oauth}/result.json`. **Не покрыто:** настоящий портал и интерфейс согласия в браузере (согласие синтетическое), обновление по 401 и естественное истечение, современная эра протокола по Bearer, RFC 7009 revoke от Inspector; Inspector взят из уже установленной копии с совпавшими хешами, не через npx; регистрация клиента заранее (dynamic registration не объявлена); отказ внеобластного инструмента проверен только фильтрацией `tools/list`
- [x] NetFlow: точный локальный адрес при wildcard-привязке — **закрыто как ограничение Node.** `dgram` отдаёт в `message` только `(msg, rinfo)` без адреса назначения, `sock.address()` после bind остаётся `0.0.0.0` (проверено на Node v25.5.0, Windows; Linux и IPv6 не проверялись, слушатель только udp4). Точный адрес даёт `IP_PKTINFO`, то есть нативный модуль или raw-сокет. Обходной путь (адрес интерфейса по маршруту к экспортёру) не равен адресу получения и ломается при policy routing и нескольких адресах, поэтому не внедрялся. Область шаблонов от адреса не зависит. Вернуть в работу, если потребуется точная идентичность
- [x] Корневые `tmp-*-pending.patch` и `tmp-db-*-draft/`, `tmp-speed-principal-draft/` сверены с HEAD (только чтение). Применены: `tmp-flow-drain-wiring-pending.patch`, `tmp-db-control-draft/` (правка COMMIT на `database-schema-control.ts:118-119`), `tmp-speed-principal-draft/` (тест побайтно совпадает). Заменены более новым кодом, применять нельзя (откатит код): `tmp-flow-engine-strict-pending.patch` (HEAD содержит все его экспорты и больше), `tmp-db-runner-draft/` (режим `--profiles-only` уже есть в расширенном виде), `tmp-check-flow-engine-pending.cjs` устарел. **Единственное неприменённое:** `tmp-db-enrollment-draft/` (`source-attestation.ts`, тест, `enrollment-host-contract.ts`): в HEAD аналога нет, помечено «TMP review component only», `productionApplied:false`, потребителей нет; решение владельца, нужен ли он. Логи `tmp-mcp-*-v1.log` не источники. Файлы не удалялись
- [x] `.claude/settings.local.json` отслеживается Git ещё с ранних коммитов, `.gitignore` его скрывает, секретов нет — **решение владельца: оставить как есть** (с учёта не снимать)
## Этап 3. Стендовые приёмки (CHR и VPS)
Пункты ниже закрываются тремя прогонами вместо отдельных ожиданий. Каждый пункт пишет собственную квитанцию; `failed` и `unknown` не перекрашиваются, при падении объединённого прогона причина разбирается по квитанциям пунктов.
**Прогон A. Два CHR (маршрутизация), один сквозной сценарий.** Пункты: VRF отпечаток при активации GRE; VRF 56 записей и трафик при смене участников; ROUTING A → B → A после правки сверки (с `/ip/dhcp-client` в списках `tmp/`, включая поправку сборщика `afi=link` в нагрузке `gre-liveness.mjs`); WireGuard / IPsec / GRE с трафиком; NetFlow IPFIX с реального RouterOS (включить экспорт на CHR на время тех же окон трафика); нестабильные Edge (39 из 41) и маршрутизация (203 из 205) как повторы того же прогона.
**Прогон B. Linux VPS (опрос), запускать первым, идёт в фоне.** Пункты: POLL 336 операций с естественным истечением (окно от 252 минут) и POLL deadline Linux. Это один и тот же прогон.
**Прогон C. VPS (внешний интерфейс и БД), одна сессия на целевом Linux.** Пункты: EXTERNAL-UI восстановить SSH (блокер, делается первым), сквозной прогон на образах CI2736, приёмка подписанного защищённого восстановления; DB-3 перенос непустой legacy-базы; DB-4 POSIX-права целевой среды (проверяются на той же среде образов).
Ограничения: B и C нельзя запускать одновременно на одном VPS (лимит 2 ГиБ, RAM-1 отложен): развести по машинам или по времени. A независим от B и C. Порядок: восстановить SSH, затем B в фоне, A, затем C.
- [ ] VRF: отпечаток стабильных полей при активации GRE
- [ ] VRF: полный прогон на 56 записей и проверка трафика при смене участников
- [ ] ROUTING: повтор A → B → A после правки сверки
- [ ] POLL: 336 операций с естественным истечением на Linux (окно от 252 минут)
- [ ] POLL: deadline целевого Linux
- [ ] EXTERNAL-UI: восстановить SSH к тестовому VPS (блокер)
- [ ] EXTERNAL-UI: сквозной прогон на образах CI2736
- [ ] EXTERNAL-UI: приёмка подписанного защищённого восстановления
- [ ] DB-3: перенос непустой legacy-базы
- [ ] DB-4: настоящие POSIX-права целевой среды
- [ ] NetFlow: захват IPFIX с реального RouterOS
- [ ] WireGuard / GRE: жизненный цикл с трафиком (прогон A; IPsec вынесен отдельным пунктом по решению D9)
- [ ] IPsec: новый MCP-сценарий `mm_ipsec_*` с подтверждением, трафиком и SA на стенде CHR (единственный прежний сценарий `tmp/ipsec-network82.mjs` октябрьский и идёт через REST приложения, не MCP)
- [ ] Нестабильные сценарии Edge (39 из 41 без повтора): исторический прогон управления в Edge из `mcp-remaining-work-20261026.md`, оба отказавших прошли при целевом повторе. Локально не воспроизводится, нужен стенд; перенесено в этап 3 по решению владельца
- [ ] Нестабильные сценарии маршрутизации (203 из 205 без повтора): исторический локальный прогон сверки, оба случая прошли при целевом повторе. Профили маршрутизации в `--profiles-only` прошли (36 из 38, ipsec и system-database исправлены). Перенесено в этап 3 по решению владельца
## Этап 4. Заблокировано или отложено
- [ ] PATHS: нет третьего независимого узла — получить узел или записать как ограничение
- [ ] RAM-1 (лимит 2 ГиБ): отложен владельцем — вернуть в работу или записать как ограничение
- [ ] autoRecovery: нет источника событий RouterOS с обнаружением пропусков — оставить выключенным, записать решение
- [ ] ROUTING: RT-3, выдача одноразового допуска автоматическому возврату — **реализовать нельзя без решения владельца.** Единственная формулировка: пункт открыт (`mcp-evidence-statistics-20261101.md`, стр. 57). Код отказывает намеренно: `recordForwardOutcome` в `routing-reservation-store.ts` не возвращает `RoutingReservedInverseAllocation`, при `failed` бросает «Authenticated network evidence for automatic recovery unavailable». Автовозврат зависит от RT-1 (полный источник событий с обнаружением пропусков), REST `/log` его не заменяет; отказ принят и покрыт `--routing-reservations` (20 сценариев). Перенесено в этап 4 к autoRecovery по решению владельца; вернуть в работу после RT-1
## Этап 5. Закрытие (FINAL-2 и FINAL-3)
- [ ] Манифест: критерий плана → доказательство → статус, без перекраски `failed` и `unknown`
- [ ] Инструкция по включению: наблюдение → подтверждения → ограниченная автономность
- [ ] Проверить, что MCP и контроллер выключены по умолчанию
- [ ] Сократить `docs/mcp.md` (417 КБ) до пользовательской документации
- [ ] PR в `main`
## Журнал
| Дата | Что сделано |
| --- | --- |
| 2026-11-15 | План составлен, код не менялся |
| 2026-11-15 | Этап 0: 7 коммитов на ветке (`bd4ce590`…`42f59f14`), дерево чисто, typecheck фронтенда и бэкенда проходит, ничего не отправлено в remote. Исправлены CRLF-байты миграций 0008–0013 (в блобах были LF, манифест закреплён за CRLF). Секреты в 2478 новых и изменённых файлах не найдены. Промежуточные коммиты по отдельности не собираются. Не сделано: копия `tmp/`, реорганизация `docs/` |
| 2026-11-15 | Проверка DB-3 по LF/CRLF миграций 0008–0013 завершена, код не менялся (вывод в этапе 2) |
| 2026-11-15 | Копия `tmp/` на C: готова и сверена. Реорганизация `docs/` изучена и остановлена (переносимо 31%). Коммит `3c78c55c`: CRLF-байты 28 закреплённых квитанций |
| 2026-11-16 | Этап 1: `test:mcp:pg:all` починен по устаревшим фикстурам (коммиты `07aaa40b`…`77e52f15`, добавлены `test:changed` и режим `MCP_INTEGRATION_CONTINUE=1`). Единственный остаток: нет `pg_dump` для `verifyMcpDatabaseBackup`. Playwright зелёный |
| 2026-11-16 | Этап 1: `pg:all` закрыт (установлены `pg_dump`/`pg_restore`, исправлено зависание завершения в `native-create-id-acceptance.ts`). Открыты два пункта про нестабильные сценарии: стендовые, нужно решение владельца |
| 2026-11-16 | Этап 1 закрыт. Два пункта про нестабильные сценарии Edge и маршрутизации перенесены в этап 3 (стендовые) |
| 2026-11-16 | Этап 2: NetFlow wildcard закрыт как ограничение Node; `/ip/dhcp-client` уже в `backend`; поправка VRF `afi=link` относится к стендовой нагрузке в `tmp/`; RT-3 ждёт решения владельца |
| 2026-11-16 | RT-3 перенесён в этап 4 к autoRecovery |
| 2026-11-16 | Этап 3: пункты сгруппированы в три прогона (A: два CHR, B: опрос Linux, C: внешний интерфейс и БД) |
| 2026-11-16 | Этап 2: Inspector HTTP и OAuth приняты на HEAD `85a5fdb9` (с оговорками о покрытии). В этапе 2 открытых пунктов нет |
| 2026-11-16 | План прогона A: решены D1 (REST с Windows), D2 (CHR2 закрыт по адресам, ftp и telnet выключены), D3 (раннеры под `claude`), D4 (пароли из переменных), D5 (контроллер локально), D7 (снят), D9 (IPsec вынесен), D10 (захват на CHR) |
| 2026-11-16 | VPS подготовлен к прогонам: очищено 8 ГБ Docker (свободно 11 ГБ), снят дамп базы, ветка `codex/mcp-foundation` отправлена в Gitea, Gitea собрала образы (запуск `2738`, успешно), на VPS заменены backend и frontend установки `mmapp-test` на HEAD `5ec95a7c`. Применены миграции со старых 12 до 57 (`0057`), 34 таблицы `mcp_*`, данные сохранены (2 сервера), backend `healthy`. Обновление прошло по прежнему (legacy) пути, схема `mmapp_control` пуста: контрольный путь миграций и пункт DB-3 этим не закрыты. MCP и контроллер по умолчанию выключены, не проверялось |