#region UxReference [C:3] [TYPE ADR] [SEMANTICS ux, reference, task, status, monitoring]
@BRIEF UX interaction reference — операторский центр просмотра статусов всех фоновых задач superset-tools. Описывает персону, потоки взаимодействия, состояния интерфейса и сценарии восстановления.

**Feature Branch**: `034-task-status-center`
**Created**: 2026-06-18 | **Status**: Draft

## 1. User Persona & Context

*   **Who is the user?**: DevOps-инженер или администратор superset-tools, отвечающий за мониторинг фоновых операций: переводы контента БД, миграции дашбордов между средами, резервное копирование, LLM-валидацию дашбордов.
*   **What is their goal?**: В одном месте быстро оценить состояние всех фоновых задач системы — что выполняется, что ждёт очереди, что упало; найти конкретную задачу и перейти к её логам для диагностики.
*   **Context**: Работа в браузере (десктоп, планшет) в корпоративной сети. Пользователь может находиться на любой странице superset-tools и перейти в раздел «Отчёты» (`/reports`) через навигацию. Страница `/reports` перерабатывается: существующий список отчётов дополняется сводной панелью и real-time обновлениями.

## 2. The "Happy Path" Narrative

Администратор открывает раздел «Отчёты» (`/reports`) из бокового меню. Страница загружается мгновенно: в верхней части — сводная панель с цветными счётчиками: «Выполняется: 3 перевода, 1 миграция», «Упало: 2 валидации». Ниже — знакомый список отчётов (задач), по умолчанию активные сверху. Администратор замечает, что миграция дашборда «Отчёт по энергопотреблению» выполняется уже 15 минут — кликает по задаче, открывается Task Drawer с живыми логами. Пока администратор изучает логи, в сводке счётчик «Выполняется» уменьшается — бекап только что завершился успешно, и администратор видит это без перезагрузки страницы.

## 3. Interface Mockups

### UI Layout & Flow

**Page**: `/reports` — переработанный раздел «Отчёты» (Task Status Center)

*   **Layout**: Одноколоночный, максимальная ширина 7xl, с отступами. Три зоны по вертикали:
    1.  **PageHeader** — заголовок «Центр статусов» с кнопкой ручного обновления (на случай проблем с WebSocket).
    2.  **Summary Panel** — горизонтальная панель сводки: сетка из карточек (2-3 строки × 4-6 колонок), каждая карточка = тип задачи × статус, показывает количество задач. Цвета: running — синий/primary, pending — серый/muted, success — зелёный/success, failed — красный/destructive, awaiting_input — жёлтый/warning.
    3.  **Task List** — основная область: фильтры (горизонтальная панель) + таблица/список задач с пагинацией.

*   **Key Elements**:
    *   **Summary Card**: Кликабельная карточка сводки. При клике — фильтрует список задач по типу и статусу карточки. Пример: клик по карточке «Миграция / Выполняется (3)» → список показывает только выполняющиеся миграции.
    *   **Filter Bar**: Горизонтальная панель фильтров над списком. Содержит: выпадающий список типов задач (multi-select), выпадающий список статусов (multi-select), текстовое поле поиска, селект временного диапазона (последний час / сегодня / неделя / всё время).
    *   **Task Row**: Строка задачи в списке. Содержит: иконку типа, название/идентификатор задачи, статус-бейдж, время запуска (относительное: «2 мин назад»), длительность, название связанного ресурса (дашборда/конфигурации). При наведении — тултип с подробностями. При клике — открывает Task Drawer.
    *   **Connection Indicator**: Маленький индикатор в углу экрана (зелёный = connected, жёлтый = reconnecting, красный = disconnected). При клике показывает статус соединения и время последнего обновления.

*   **Contract Mapping**:
    *   **`@UX_STATE`**:
        *   **idle** — страница загружена, данные актуальны, WebSocket подключён.
        *   **loading** — первоначальная загрузка: скелетон-заглушки (pulse-анимация) вместо сводки и списка.
        *   **empty** — нет ни одной задачи в системе: пустое состояние с иконкой и пояснительным текстом.
        *   **disconnected** — WebSocket разорван: индикатор красный, баннер «Соединение потеряно. Переподключение...», данные последнего известного состояния заморожены.
        *   **reconnecting** — WebSocket переподключается: индикатор жёлтый с анимацией.
        *   **error** — ошибка загрузки данных: баннер с сообщением об ошибке и кнопкой «Повторить».
    *   **`@UX_FEEDBACK`**:
        *   Изменение статуса задачи в списке — анимированное обновление (плавное изменение цвета бейджа).
        *   Новая задача появляется в списке — анимированное появление (slide-in сверху).
        *   Завершение задачи — кратковременное выделение строки (зелёное/красное) и обновление счётчика в сводке.
        *   Ошибка фильтрации — инлайн-сообщение «Нет задач, соответствующих фильтрам» с кнопкой «Сбросить фильтры».
    *   **`@UX_RECOVERY`**:
        *   Разрыв WebSocket → автоматический reconnect с экспоненциальной задержкой (1с, 2с, 4с, 8с, макс 30с). Кнопка «Подключиться сейчас» для ручного reconnect.
        *   Ошибка загрузки → кнопка «Повторить загрузку».
        *   Пустой результат поиска → кнопка «Сбросить фильтры».
    *   **`@UX_REACTIVITY`**: Сводка и список — производные от модели (`TaskCenterModel` в `.svelte.ts`). Модель подписывается на WebSocket `/ws/task-events` через `$effect`. Данные сводки — `$derived` от полного списка задач в модели. Фильтры — `$state` атомы модели, изменение любого фильтра пересчитывает отфильтрованный список через `$derived`.
    *   **Screen Model**: `TaskCenterModel` (`frontend/src/lib/models/TaskCenterModel.svelte.ts`) — [TYPE Model], объявляет `@STATE` (screenState, tasks, summary, filters), `@ACTION` (applyFilter, clearFilters, selectTask, refresh), `@INVARIANT` (активные задачи всегда сверху, счётчики сводки = агрегация tasks).
*   **States**:
    *   **Idle/Default**: Сводка и список загружены, индикатор соединения зелёный, фильтры пустые (показываются все задачи, активные сверху).
    *   **Loading**: Вся страница — skeleton placeholder: 4 карточки-скелетона в сводке, 10 строк-скелетонов в списке.
    *   **Empty**: Иконка (inbox) + текст «Нет активных задач» + ссылки «Запустить перевод», «Запустить миграцию», «Запустить бекап».
    *   **Disconnected**: Данные последнего известного состояния остаются видимыми, индикатор красный, баннер сверху: «Соединение потеряно. Попытка переподключения... [Подключиться сейчас]».
    *   **Error**: Баннер с ошибкой + кнопка «Повторить». Сводка и список скрыты или показывают последние кешированные данные с пометкой «Данные могут быть неактуальны».

## 4. The "Error" Experience

**Philosophy**: Не просто сообщать об ошибке — направлять оператора к решению. Каждый сценарий отказа имеет путь восстановления.

**Semantic Requirement**: Every documented failure path here should map to `@UX_RECOVERY` and, where relevant, `@UX_FEEDBACK` in the generated component contracts.

### Scenario A: WebSocket разрыв соединения

*   **User Action**: Сетевой сбой, перезапуск backend, или таймаут бездействия.
*   **System Response**:
    *   Индикатор соединения меняется на жёлтый (Reconnecting) с анимацией пульсации.
    *   Через 2 секунды неудачных попыток — баннер «Соединение потеряно. Попытка переподключения... [Подключиться сейчас]».
    *   Данные последнего известного состояния остаются на экране с пометкой «Обновлено: 2 мин назад».
*   **Recovery**: Автоматический reconnect с экспоненциальной задержкой (1с → 2с → 4с → 8с → ... макс 30с). Кнопка «Подключиться сейчас» для немедленной попытки.

### Scenario B: Ошибка загрузки начальных данных

*   **User Action**: Открытие страницы, а backend API недоступен (503).
*   **System Response**:
    *   Баннер: «Не удалось загрузить данные задач. Сервер временно недоступен.»
    *   Кнопка «Повторить загрузку».
*   **Recovery**: Ручная повторная попытка. Автоматический retry через 10 секунд с уведомлением.

### Scenario C: Пустой результат фильтрации

*   **User Action**: Применил фильтр «Тип: Бекап, Статус: Выполняется», но выполняющихся бекапов нет.
*   **System Response**:
    *   Вместо списка — EmptyState с текстом «Нет выполняющихся бекапов».
    *   Кнопка «Сбросить фильтры» возвращает к полному списку.
*   **Recovery**: Оператор сбрасывает фильтры одним кликом.

### Scenario D: Задача упала — быстрый переход к логам

*   **User Action**: Оператор видит красный бейдж «FAILED» на задаче.
*   **System Response**: Строка задачи подсвечена красным слева (destructive ring border).
*   **Recovery**: Клик по задаче → открывается Task Drawer, скроллится к последней ошибке в логах. Кнопка «Перезапустить» в Task Drawer (если тип задачи поддерживает перезапуск).

## 5. Tone & Voice

*   **Style**: Деловой, лаконичный, технический. Русский язык.
*   **Terminology**: «Задача» (не job), «Выполняется» (не in progress), «Упала» (не error/failed в UI), «Ожидает» (не pending), «Ожидает ввода» (не awaiting input). Иконки типов: перевод (globe), миграция (arrows-right-left), бекап (archive), валидация (shield-check), документация (file-text).

#endregion UxReference