From 596d6cc84cc51ff5a9cf50195b6a134d67fc9b23 Mon Sep 17 00:00:00 2001 From: busya Date: Tue, 29 Sep 2026 14:27:58 +0300 Subject: [PATCH] docs: update maintenance effort estimate --- docs/reports/maintenance-effort-estimate.md | 132 ++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/reports/maintenance-effort-estimate.md diff --git a/docs/reports/maintenance-effort-estimate.md b/docs/reports/maintenance-effort-estimate.md new file mode 100644 index 000000000..c47a0ea6e --- /dev/null +++ b/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. Это сравнение стоимости воспроизведения уже существующего объёма реализации в двух архитектурных вариантах.