docs: update maintenance effort estimate

docs/reports/maintenance-effort-estimate.md

@@ -0,0 +1,132 @@
+# Оценка трудозатрат модуля Maintenance
+
+Дата оценки: 2026-09-29
+
+## Объект оценки
+
+Оценивается создание **фактически реализованного** maintenance-модуля по текущему коду ss-tools, без добавления новых возможностей.
+
+В состав фактического проекта входят:
+
+- запуск и завершение maintenance-событий в асинхронном режиме;
+- состояния событий и dashboard states, идемпотентность и повторные попытки;
+- поиск затронутых дашбордов по физическим и virtual SQL datasets;
+- фильтры published/draft/all, исключённые и принудительно включённые дашборды;
+- добавление, обновление, агрегация и удаление maintenance banner в layout Superset;
+- корректное восстановление layout и обработка нескольких событий на одном дашборде;
+- auto-end;
+- REST API для start/end/end-all, событий, dashboard banners, preview и settings;
+- библиотека HTML-шаблонов с CRUD, архивированием и default template;
+- RBAC и scoped API key-доступ для внешних вызовов;
+- TaskManager, прогресс выполнения и WebSocket-уведомления;
+- MCP и Assistant Tool-интеграции;
+- frontend-страницы запуска и истории, настройки и templates UI;
+- dashboard badge в Dashboard Hub;
+- русская и английская локализация;
+- unit, API, integration, lifecycle, frontend и E2E-тесты;
+- миграции, конфигурация, логирование и эксплуатационная проверка.
+
+## Фактический объём кода
+
+По состоянию текущей реализации:
+
+- около **6 300 строк production-кода** в явно maintenance-файлах;
+- **26 backend-тестовых файлов**;
+- **12 frontend-тестовых файлов**;
+- отдельные ORM-модели, REST route package, service package, TaskManager plugin и MCP adapter;
+- отдельная Alembic-миграция;
+- интеграции с общими `SupersetClient`, `TaskManager`, auth/RBAC, API-key, WebSocket, MCP и Dashboard Hub.
+
+Оценка ниже является оценкой трудозатрат на создание такого же фактического проекта, а не оценкой текущего незавершённого backlog.
+
+## Методика
+
+- Единица измерения: **1 человеко-час = 1 час работы одного специалиста**.
+- Включены анализ, реализация, отладка, code review и целевая тестовая проверка.
+- Не включены отпуск, ожидание внешних команд, закупка инфраструктуры и календарные задержки.
+- Для отдельного сервиса включена повторная реализация платформенных границ, которые сейчас предоставляет ss-tools.
+- Для модуля внутри ss-tools предполагается, что существующие общие механизмы ss-tools доступны и используются по их текущим контрактам.
+- Верхняя граница включает запас на реальные интеграционные дефекты, но не включает новые функции.
+
+## Вариант 1: отдельный сервис
+
+Под «отдельным сервисом» понимается самостоятельный backend, который реализует тот же maintenance API и workflow, имеет собственное хранение состояния и worker/job-контур, а также может обслуживать текущий UI через API. Отдельный frontend сверх текущего UI в оценку не добавляется.
+
+| Работы | Оценка, ч-ч | Что входит |
+|---|---:|---|
+| Доменная модель и БД | 100–160 | Сущности events, banners, states, settings, templates, индексы и миграции |
+| REST API и схемы | 140–220 | Фактические endpoints, validation, idempotency, error responses |
+| Lifecycle и orchestration | 220–340 | Start/end/end-all, partial failures, retries, auto-end, concurrency |
+| Superset adapter | 180–300 | Authenticated client, dataset/dashboard discovery, layout read/write, restore |
+| Banner renderer и layout logic | 100–160 | HTML templates, height, aggregation нескольких событий, native Markdown layout |
+| Worker и job execution | 180–280 | Очередь, task states, progress, retry, recovery, orphan reconciliation |
+| Auth, RBAC и API keys | 120–200 | JWT/service auth, scoped keys, permissions, environment restrictions |
+| Realtime events | 60–100 | WebSocket/event delivery, reconnect-compatible contract, authorization |
+| MCP и Assistant adapters | 80–140 | Approval/enqueue flow, validation, dispatch и parity фактических операций |
+| Frontend API/store contract | 60–100 | Typed API boundary и state model, необходимый для существующего UI |
+| Backend tests | 180–300 | Unit, API, RBAC, integration, lifecycle, failure/retry cases |
+| Contract/E2E tests | 100–180 | Superset-compatible integration, external API and end-to-end workflows |
+| CI/CD, Docker, observability и release setup | 140–240 | Health checks, secrets, logs, metrics, deploy configuration, runbook |
+| Data migration и cutover | 80–140 | Перенос существующих maintenance rows, compatibility window, rollback plan |
+| **Итого** | **1 740–2 860** | Верхняя граница: **около 2 860 ч-ч** |
+
+Практическая верхняя оценка для планирования: **2 800–2 900 человеко-часов**.
+
+## Вариант 2: модуль внутри ss-tools
+
+Под «модулем внутри ss-tools» понимается реализация того же фактического maintenance-модуля в существующем backend/frontend, с использованием уже имеющихся БД, TaskManager, SupersetClient, auth/RBAC, API-key, WebSocket, MCP, UI primitives и CI.
+
+| Работы | Оценка, ч-ч | Что входит |
+|---|---:|---|
+| Анализ существующей архитектуры и контракты | 50–80 | Встраивание в текущие модели, permissions, routes и task lifecycle |
+| ORM-модели и миграции | 50–90 | Maintenance tables, constraints, indexes, template migration |
+| REST API и схемы | 100–160 | Текущие route groups, validation, settings, preview, events, templates |
+| Lifecycle и orchestration | 180–280 | Start/end/end-all, partial failures, idempotency, auto-end |
+| Superset discovery и banner layout | 180–280 | Dataset scan, SQL extraction, dashboard states, layout restore |
+| TaskManager plugin и progress | 60–100 | Existing plugin boundary, task context, progress and event broadcasts |
+| Auth/RBAC/API-key integration | 50–90 | Existing permission model and external key scope |
+| WebSocket, MCP и Assistant integration | 70–120 | Existing event channel, approval/enqueue adapters and assistant tools |
+| Frontend API/store/pages/components | 220–340 | API client, rune store, launch form, tables, settings, templates, badge |
+| i18n и Dashboard Hub integration | 50–80 | EN/RU strings, navigation and dashboard-row indicator |
+| Backend/frontend/integration tests | 260–420 | Current test surface and regression coverage for the implemented behavior |
+| CI, release hardening и production verification | 100–170 | Lint, build, migration check, environment checks, failure rehearsal |
+| **Итого** | **1 370–2 130** | Верхняя граница: **около 2 130 ч-ч** |
+
+Практическая верхняя оценка для планирования: **2 000–2 150 человеко-часов**.
+
+## Сравнение
+
+| Вариант | Диапазон | Верхняя граница для плана |
+|---|---:|---:|
+| Отдельный сервис без нового frontend | 1 740–2 860 ч-ч | **2 860 ч-ч** |
+| Модуль внутри ss-tools | 1 370–2 130 ч-ч | **2 130 ч-ч** |
+| Дополнительная стоимость выделения | +370–730 ч-ч | **примерно +730 ч-ч** |
+| Относительный рост | 1,27–1,53x | **около 1,5x** |
+
+Разница ниже, чем при оценке отдельного продукта с самостоятельным UI, потому что в сравнении выше frontend переиспользует текущий ss-tools UI-контракт. Если отдельному сервису понадобится собственный frontend, к нему следует добавить ещё примерно **500–800 человеко-часов** на перенос существующих maintenance-страниц, layout, auth/session и frontend E2E.
+
+## Что уже оплачено общей платформой ss-tools
+
+При варианте модуля не нужно заново создавать:
+
+- SQLAlchemy/Alembic foundation;
+- `TaskManager`, `TaskContext` и task logs;
+- общий `SupersetClient` и environment configuration;
+- JWT, API keys и permission checks;
+- WebSocket infrastructure;
+- общий request wrapper и frontend auth/session;
+- UI primitives, navigation, notifications и i18n wiring;
+- MCP approval/dispatch infrastructure;
+- CI и локальный development/test harness.
+
+Именно это даёт экономию примерно **700 человеко-часов** по верхней границе. Бизнес-логика maintenance при этом остаётся почти одинаковой в обоих вариантах.
+
+## Вывод
+
+Для создания именно такого фактического maintenance-проекта следует закладывать:
+
+- **внутри ss-tools: до 2 130 человеко-часов**;
+- **как отдельный сервис: до 2 860 человеко-часов**;
+- разница: **до 730 человеко-часов** в пользу модуля внутри ss-tools.
+
+Оценка не включает новые функции, отдельный продуктовый frontend, дополнительные интеграции или расширение SLA. Это сравнение стоимости воспроизведения уже существующего объёма реализации в двух архитектурных вариантах.