ros_control/docs/changes/022-async-db-remainder/plan.md

# План: 022 — остаток п. 9: синхронная БД в async-коде

## Context

Ревью `docs/reviews/2026-09-28-1243-codebase-review.md`, п. 9 (частично закрыт в 019). В 019 обработчики без `await` стали `def`,
фоновые записи ушли в `asyncio.to_thread`, но в **async-функциях** остались прямые синхронные вызовы сервисов, которые ходят в SQLite
(`session_scope`) и блокируют event loop. В ревью названы два места; разведка (AST: async-функции, вызывающие функции с `session_scope`
напрямую или через одну ступень) нашла их больше:

| Где | Синхронные вызовы БД |
|---|---|
| `app/services/backups.py::search` | `groups.list_groups`, `devices.list_devices` |
| `app/services/ops.py::run_backup`, `set_channel`, `run_ros_update`, `run_fw_update` | `devices.get_conn` (чтение + расшифровка пароля) |
| `app/services/ops.py::refresh_many` | `devices.list_devices` |
| `app/api/v1.py::refresh_device`, `put_channel`, `list_backups` | `devices.get_device` |
| `app/api/v1.py::refresh_all` | `devices.list_devices` |
| `app/api/v1.py::create_backup`, `install_update`, `upgrade_firmware`, `batch`, `batch_channel` | `jobs.start_jobs`, `BatchIn.resolve` |
| `app/ui/routes.py::refresh`, `device_action` | `_visible`, `_devices_ctx`, `jobs.list_jobs`, `jobs.start_jobs` |
| `app/ui/routes.py::batch` | `jobs.start_jobs`, `jobs.list_jobs` |
| `app/ui/routes.py::device_create` | `devices.create_device`, `_device_form` |
| `app/ui/routes.py::backups_page` | `devices.list_devices`, `groups.list_groups` |

Ложные срабатывания: `events.record` внутри `ops.run_backup` — во вложенных `_create_row/_finish_row`, уже через `to_thread`.
`app/main.py::lifespan` (`init_db`, `fail_stale_jobs`) — выполняется до приёма запросов; **не меняем**.

Решений пользователя не требуется: объём — «оставшиеся задачи п. 9», подход тот же, что в 019.

## Изменения

### Общий подход
- Синхронный вызов в async-функции → `await asyncio.to_thread(fn, *args)` (контекст копируется — актор и `job_id` в ContextVar сохраняются, как в 019).
  Сигнатуры синхронных сервисов не меняются.
- Где несколько подряд идущих синхронных вызовов готовят данные для одного ответа (`_devices_ctx` + `list_jobs`, `list_devices` + `list_groups`) —
  одна вложенная синхронная функция и один `to_thread`, а не серия переключений.

### `app/services/jobs.py` — `start_jobs`
- Сейчас синхронная: создаёт строки задач в БД и затем `asyncio.create_task` (нужен работающий event loop — поэтому вызывающие обработчики остались `async`).
- Разделить: `_create_jobs(job_type, device_ids, params) -> list[tuple[job_id, device_id]]` — синхронная, только БД и события (с проверками
  типа задачи и ID, как сейчас); `async def start_jobs(job_type, device_ids, params=None) -> list[str]` — `await asyncio.to_thread(_create_jobs, …)`,
  затем `create_task` в event loop. Все вызовы `start_jobs` — с `await` (API, UI, тесты).

### `app/services/ops.py`
- Хелпер `async def _conn(device_id) -> devices.Conn` = `await asyncio.to_thread(devices.get_conn, device_id)`; использовать в
  `refresh_status`, `poll_device` (уже через `to_thread` — заменить на хелпер для единообразия), `run_backup`, `set_channel`, `run_ros_update`, `run_fw_update`.
- `refresh_many`: `devices.list_devices` → `to_thread`.

### `app/services/backups.py::search`
- `groups.list_groups()` и `devices.list_devices()` — одним `to_thread` (вложенная функция, возвращающая `group_names`, `device_group`).

### `app/api/v1.py`
- `refresh_device`, `put_channel`, `list_backups`: `devices.get_device` → `to_thread`.
- `refresh_all`: итоговый `devices.list_devices` → `to_thread`.
- `batch`, `batch_channel`: `body.resolve()` → `to_thread`; `await jobs.start_jobs(...)`. `create_backup`, `install_update`, `upgrade_firmware` — `await jobs.start_jobs(...)`.

### `app/ui/routes.py`
- `refresh`, `batch`, `device_action`: подготовка контекста (`_visible`, `_devices_ctx`, `jobs.list_jobs`) — через `to_thread`; `await jobs.start_jobs(...)`.
  `await request.form()` остаётся в event loop (до `to_thread`).
- `device_create`: `devices.create_device` и повторный рендер формы с ошибкой (`_device_form` читает группы) — через `to_thread`;
  `await ops.refresh_status` без изменений.
- `backups_page`: `devices.list_devices`, `groups.list_groups` — через `to_thread`.

## Тесты (минимально)
- **Регрессионный тест-линтер** (`tests/test_app.py`): AST-обход `app/` — в `async def` нет прямых вызовов функций, использующих
  `session_scope` (напрямую или через одну ступень вызовов), кроме разрешённого списка (`lifespan`); вызовы, переданные ссылкой в
  `asyncio.to_thread(fn, …)`, и вложенные `def` не считаются. Логика — как у скрипта разведки из Context. Это закрепляет п. 9 от регресса.
- Существующие тесты, вызывающие `jobs.start_jobs`, — перевести на `await`. Актор в событиях задач (`api`, `ui:<user>`) должен сохраниться —
  подтверждается существующими тестами журнала.

## Документация
README: строка 022 в «История изменений», число тестов. `summary.md` — оркестратор.

## Исполнение
Исполнитель (Sonnet): код, тест, README, пересборка стенда. Тесты не запускает, не коммитит, `.env` не читает.

## Проверка
- `pytest` — все зелёные; тест-линтер падает, если временно вернуть прямой вызов в async-функцию (мутационная проверка — оркестратор).
- Повторный запуск скрипта разведки — пусто (кроме `lifespan`).
- Стенд (override 8001, `--force-recreate`): `/login` 200, новый код в контейнере; сценарий: временное устройство `192.0.2.1` →
  `POST /api/v1/devices/{id}/backups` → 202, задача `backup` завершается `failed` (недоступно) с актором `api` в событиях; `PUT /batch/channel` → 202;
  параллельный `GET /api/v1/devices` во время `refresh` отвечает сразу; устройство удаляется. Боевые данные — сверка по ID.
- Ручная проверка UI — пользователь: «Обновить статус», групповые действия, меню «⋯» устройства, добавление устройства, страница «Бэкапы».