ros_control/docs/changes/017-events-ui-rotation/plan.md

План: 017 — журнал событий в UI, ротация и защищённая очистка

Статус: выполнено — макет утверждён (этап A), реализация выполнена (этап B), итоги — в summary.md.

Context

Журнал событий (events, 016) сейчас читается только через API. Нужно: (1) страница «Журнал» в UI; (2) настройки ротации; (3) кнопка очистки журнала, которая срабатывает только через модальное окно с вводом пароля пользователя.

Решения (согласованы): сначала макет на ревью, реализация после его одобрения; настройки ротации — в БД, редактируются из UI (значения по умолчанию из .env); ротация по возрасту и по числу записей; очистка удаляет всё и оставляет запись о факте очистки.

Работа идёт в два этапа. Этап A (макет) выполняется сразу после одобрения этого плана и заканчивается остановкой на ваше ревью. Этап B (код) — только после того, как макет утверждён.

Этап A — макет (артефакт claude.ai/artifact/QdhgQWbQEWRYtBoAWMjGq6, новые листы)

Оформление — тем же генератором и компонентами, что и утверждённые листы (h36 r8, метки h22 r6, карточки r12, IBM Plex); существующие листы не меняются, кроме заметки на холсте о новом пункте меню.

1. «Журнал» — верхнее меню получает пятый пункт «Журнал» (в макете показан на новых листах; в приложении добавится во все экраны). Заголовок «Журнал», подзаголовок со сводкой («N записей · старейшая … · ротация: 90 дней / 100 000»). Кнопки справа: «Обновить» (secondary), «Настройки» (secondary), «Очистить журнал» (secondary, красный текст — тот же вид «опасного» действия, что «Удалить» на бэкапах). Primary-кнопки на странице нет. Карточка: полоса фильтров (Тип ▾, Актор ▾, Устройство ▾, период с/по, поиск по сообщению или ID, «Сбросить (N)»), таблица: Время (UTC) · Тип (метка по смыслу: ok/warn/bad/run/neutral) · Сущность (вид + короткий ID) · Сообщение · Актор · ID записи (короткий, моноширинный; полный — в подсказке и в окне записи), футер «Показано N из M» и кнопка «Показать ещё» (постраничная подгрузка по курсору).
2. «Журнал · запись» — окно с полным содержимым записи: evt_…, тип, время, актор, ID сущности, устройство, задача, сообщение, данные (JSON), кнопки «Копировать» у ID; закрывается «Закрыть».
3. «Журнал · настройки ротации» — окно: «Хранить записи, дней» и «Максимум записей» (0 = не ограничивать), справка («ротация раз в час и при сохранении удаляет самые старые записи и фиксируется записью в журнале»), сводка «сейчас N записей, старейшая …», «Отмена» / «Сохранить» (primary).
4. «Журнал · очистка» — два состояния рядом: первичное и «неверный пароль». Окно: предупреждение (жёлтая заметка: «будет удалено N записей без возможности восстановления; останется одна запись об очистке»), поле «Пароль пользователя <имя>» (type=password), кнопка «Очистить» (secondary, красный текст) неактивна, пока пароль не введён, «Отмена». Состояние ошибки: красное сообщение «Неверный пароль» и состояние блокировки «Слишком много попыток, повторите через N мин».
5. Заметка на холсте: пункт «Журнал» добавляется в верхнее меню всех экранов. Результат — ссылка на артефакт и вопросы на ревью; дальше — стоп до вашего ответа.

Этап B — реализация (после одобрения макета)

Данные и настройки.

• Таблица app_settings(key PK, value JSON, updated_at) (app/models.py, миграция v2 в app/migrations.py через create_all, user_version 1→2). Ключи: events.retention_days, events.max_rows.
• app/services/settings.py (новый): чтение/запись с валидацией (целые, 0 = без ограничения, верхние границы), значения по умолчанию из Settings (EVENTS_RETENTION_DAYS=90, EVENTS_MAX_ROWS=100000, app/config.py, .env.example); изменение пишет событие journal.settings_changed (старое/новое).

Ротация (app/services/events.py, app/services/rotation.py — новый).

• rotate(): удаляет записи старше срока и, если записей больше лимита, самые старые сверх лимита (по возрастанию ID — ID сортируется по времени); пакетами, чтобы не блокировать БД; если что-то удалено — одна запись journal.rotated (сколько, по какой причине, действующие настройки).
• Запуск: при старте, сразу после сохранения настроек и раз в час фоновой задачей в lifespan (app/main.py, рядом с опросом; актор system).

Очистка (events.clear(user); маршрут только в UI).

• POST /events/clear (нужна сессия): пароль сверяется с паролем пользователя сессии (security.verify_admin_password, hmac.compare_digest; логин берётся из сессии, а не из формы). Неверный пароль → окно остаётся открытым с ошибкой, событие journal.clear_denied (без пароля), счётчик попыток; после 5 неверных за 10 минут — блокировка на 10 минут (в памяти, по пользователю) с сообщением о времени ожидания.
• Успех: в одной транзакции удаляются все записи и добавляется journal.cleared (кто, сколько удалено); окно закрывается, страница обновляется (HX-Refresh).
• Через API очистки нет (только чтение журнала и настроек) — иначе токен обходил бы окно с паролем; прямой POST без пароля отклоняется.

UI (app/ui/routes.py, шаблоны events.html, _events_rows.html, _event_dialog.html, _events_settings.html, _events_clear.html, base.html — пункт меню, static/style.css — только новые классы на существующих токенах, static/app.js — кнопка «Копировать»).

• GET /events — страница с фильтрами (GET-форма, как «Бэкапы»: тип/группа типов, актор, устройство, период, поиск; закладки), «Показать ещё» — HTMX-подгрузка следующих 100 по курсору before=<evt_…> (тот же events.list_events, к нему добавляются фильтры по актору, периоду и тексту).
• Окна через существующую инфраструктуру <dialog> + HTMX: /ui/dialog/event/{id}, /ui/dialog/events-settings, /ui/dialog/events-clear; ошибки — внутри окна, успех — HX-Refresh (как у окон устройства/групп).
• Кнопка «Очистить» в окне неактивна, пока поле пароля пусто (JS); проверка — на сервере.

API (app/api/v1.py): GET/PUT /api/v1/events/settings (настройки ротации и сводка); фильтры actor, date_from, date_to, q в GET /api/v1/events. Очистки нет.

Документы: docs/changes/017-events-ui-rotation/{plan,summary}.md; README (раздел «Журнал», настройки .env, история).

Проверка

• Макет (этап A): публикация листов; сверка при ревью — на вашей стороне.
• Тесты (pytest, сейчас 17; +3): (1) ротация: по возрасту, по числу, 0 = без ограничения, запись journal.rotated; (2) очистка: неверный пароль не удаляет и пишет journal.clear_denied, верный удаляет всё и оставляет одну journal.cleared, блокировка после 5 неверных, DELETE /api/v1/events не существует, POST без пароля отклонён; (3) страница /events: фильтры, курсор «Показать ещё», окно записи, сохранение настроек с валидацией.
• Браузер (Playwright) на копии боевой БД — второй экземпляр приложения на другом порту с копией файла БД и выключенным опросом, чтобы не стереть ваш реальный журнал: страница и фильтры, окно записи, настройки (сохранение, ошибка валидации), очистка (неверный пароль → ошибка, блокировка, верный → пустой журнал с одной записью об очистке), ротация по срокам на искусственно состаренных записях, тёмная тема и узкое окно (меню/окна не обрезаются). На боевом журнале очистку не запускаю без вашей команды.
• Регрессия: весь прежний набор тестов и сценарий интерфейса (устройства, группы, бэкапы) без ошибок.

Риски и оговорки

• Изменение настроек (уменьшение срока/лимита) сразу удаляет старые записи — это фиксируется в журнале (journal.settings_changed, journal.rotated); пароль для смены настроек не требуется (по вашему ТЗ он нужен только для очистки).
• Пароль пользователя — единственный (ADMIN_PASSWORD из .env); счётчик блокировки хранится в памяти процесса и сбрасывается перезапуском.
• Журнал не заменяет резервное копирование БД: очистка необратима (кроме восстановления из .bak/копии тома).