ros_control/docs/changes/001-initial-implementation/plan.md

План: ros_control — централизованное управление парком MikroTik RouterOS

Context

Нужно приложение для группового администрирования множества устройств MikroTik RouterOS через API и WEB UI. Источник требований — ros_control.svg (draw.io): архитектура, список функций, ссылки на API.

Из схемы:

• Control Server связан двусторонне с Local Metadata DB (DB transactions), S3 Bucket (Yandex Object Storage: ListObjectsV2, GetObject, PutObject, DeleteObject) и Admin Dashboard.
• Dashboard ↔ Control Server: JSON payload, UI Forms (ввод), JSON payload render (вывод).
• Control Server ↔ Endpoint API Server (on device) = RouterOS REST API (GET/PATCH/PUT/POST/DELETE, JSON), N устройств.

Функции dashboard: список устройств и управление списком (добавить, изменить, удалить); статус (модель, канал обновлений, версия ROS, версия FW, uptime, время запроса бэкапа); бэкап по каждому устройству (бинарный .backup без шифрования + текстовый .rsc, загрузка в S3, удаление с устройства, скачивание из бакета, список бэкапов в бакете); выбор канала обновлений; обновление ROS до актуальной версии канала (перезагрузка после скачивания); обновление FW (перезагрузка сразу после обновления).

Принятые решения: Python FastAPI + Jinja2/HTMX, SQLite (SQLAlchemy), пароли устройств шифруются (Fernet), вход в UI по логину/паролю, API — Bearer-токен, Docker Compose для развёртывания + venv в корне проекта для разработки.

Артефакты процесса (по CLAUDE.md проекта)

• docs/changes/001-initial-implementation/plan.md — копия этого плана (создаётся первым шагом реализации)
• docs/changes/001-initial-implementation/summary.md — итоги по выполненному (создаётся последним шагом)
• README.md — описание, запуск, конфигурация, ссылки на API; обновляется при каждом изменении
• Тесты — минимальный набор (см. Verification)

Структура проекта

app/
  main.py              # FastAPI, роутинг, lifespan
  config.py            # настройки из env (pydantic-settings)
  db.py, models.py     # SQLAlchemy + SQLite: users, devices, backups, jobs
  security.py          # Fernet для паролей устройств, хэш пароля админа, API-токен
  ros/client.py        # httpx-клиент RouterOS REST (basic auth, verify_tls per device)
  ros/operations.py    # status, backup, update channel/install, firmware upgrade
  s3.py                # boto3: list/get(presigned)/put(presigned)/delete, endpoint Yandex
  services/            # devices, backups, updates, jobs (фоновые задачи + batch)
  api/v1.py            # JSON API
  ui/routes.py, templates/, static/   # Jinja2 + HTMX
tests/                 # минимальный набор
Dockerfile, docker-compose.yml, requirements.txt, .env.example, README.md
docs/changes/001-initial-implementation/{plan,summary}.md

Ключевые технические решения

1. RouterOS REST (https://<host>/rest/..., ROS ≥ 7.1, сервис www-ssl). Для самоподписанных сертификатов — флаг verify_tls на устройство. Ограничение: только ROS 7.
2. Статус — параллельный опрос (asyncio.gather + семафор): /rest/system/resource (модель, версия ROS, uptime), /rest/system/routerboard (current/upgrade firmware), /rest/system/package/update (channel, installed/latest version). Недоступное устройство отображается как offline, не ломает список.
3. Бэкап:
   • POST /rest/system/backup/save (dont-encrypt=yes) и POST /rest/export (.rsc);
   • REST не отдаёт содержимое крупных файлов, поэтому устройство само загружает файлы в S3 через /tool/fetch (http-method=put upload=yes src-path=…) по presigned PUT URL, выданному Control Server. Ключи S3: backups/<device>/<timestamp>.backup|.rsc;
   • после успешной загрузки — DELETE /rest/file/<id> на устройстве; время запроса пишется в БД;
   • список — ListObjectsV2 по префиксу, скачивание — presigned GET (редирект).
4. Обновление ROS: POST /rest/system/package/update/set {channel} → check-for-updates → install (устройство скачивает пакет и перезагружается само — соответствует требованию «перезагрузка после скачивания»).
5. Обновление FW: POST /rest/system/routerboard/upgrade → опрос до current-firmware == upgrade-firmware → POST /rest/system/reboot.
6. Долгие операции — таблица jobs + фоновые задачи; UI опрашивает статус через HTMX. Групповые операции: эндпоинты принимают список device_ids, выполняются параллельно с ограничением конкурентности.
7. API v1: /api/v1/devices (CRUD), /devices/{id}/status, /devices/{id}/backups (POST/GET), /backups/download, /devices/{id}/update/channel (PUT), /devices/{id}/update/install, /devices/{id}/firmware/upgrade (POST), /jobs/{id}. UI использует те же сервисы.
8. Безопасность: пароли устройств не возвращаются в API/UI; ключ шифрования и S3-ключи — только из env; UI — сессия после логина; API — Bearer-токен.

Этапы реализации

1. Артефакты: plan.md, каркас проекта, venv, requirements.txt, .env.example.
2. Модели БД, security (Fernet, логин, токен), конфиг.
3. RouterOS-клиент и операции статуса; CRUD устройств; список со статусами (API + UI).
4. S3-модуль; бэкап (2 формата, загрузка с устройства, очистка), список и скачивание.
5. Каналы обновлений, обновление ROS, обновление FW; jobs и групповые операции.
6. Docker/compose, README, минимальные тесты, summary.md.

Риски / проверить на реальном устройстве

• /tool/fetch с http-method=put upload=yes на целевой версии ROS (основной вариант). Запасной: устройство отправляет файл на эндпоинт Control Server.
• Синхронные REST-вызовы (fetch, install) могут упереться в таймаут — использовать duration/асинхронные задачи и опрос состояния.
• Сертификат www-ssl на устройствах и доступность 443 от Control Server; доступность S3 (storage.yandexcloud.net) с устройств.

Verification

• Автотесты (минимум, ~4): шифрование/расшифровка пароля; разбор статуса RouterOS (mock httpx); сценарий бэкапа с мокнутыми RouterOS и S3 (порядок: save → export → fetch → delete file → запись в БД); авторизация API (401 без токена).
• Ручная проверка: RouterOS CHR (ROS 7) в лаборатории + тестовый бакет Yandex Object Storage: добавить устройство → статус в списке → бэкап (оба файла в бакете, на устройстве удалены) → скачивание → смена канала → обновление ROS → обновление FW.
• docker compose up — приложение поднимается, UI на :8000, /docs показывает OpenAPI.