jellybit/openspec/specs/notifications/spec.md

# notifications Specification

## Purpose
Уведомление автора загрузки о значимых событиях: падения (`failed`/`stuck`,
включая приёмный `qbit_add` мимо поллинга) с дебаунсом повторов, приглашение в
`review` и готовность, рассинхрон (`orphaned`/`target_missing`). Единое место
доставки пингов, над которым транспорты (Telegram и др.) — тонкие адаптеры.
## Requirements
### Requirement: Уведомление о падении загрузки

Любой переход загрузки в `failed`/`stuck` система SHALL сопровождать уведомлением
автора загрузки через настроенный механизм (`notifier`), чтобы падение не
оставалось незамеченным. Это SHALL включать приёмное падение `qbit_add` (не
удалось добавить раздачу в qBittorrent), которое идёт мимо поллинг-цикла worker.

#### Scenario: Уведомление при падении приёма

- **GIVEN** приём загрузки, где добавление в qBittorrent не удалось
- **WHEN** загрузка помечается `failed` с `error_code` `qbit_add`
- **THEN** автор загрузки получает уведомление о падении

### Requirement: Дебаунс повторных падений

Повторные падения одной задачи в пределах окна дебаунса система SHALL уведомлять
лишь один раз, чтобы мерцающий stalled-торрент (`stuck` ↔ `downloading`) не спамил
автора.

#### Scenario: Мерцающий stalled не спамит

- **GIVEN** задача, многократно переходящая `stuck` ↔ `downloading` в пределах окна дебаунса
- **WHEN** происходят повторные падения
- **THEN** уведомление отправляется один раз за окно

### Requirement: Пинг о входе в review и готовности

При переходе загрузки в `review` система SHALL пинговать автора (сообщение в
Telegram / бейдж в вебе) — пользователя зовут, а не он опрашивает. После
успешного применения (готовность) система SHALL показывать, что создано.

#### Scenario: Пинг при входе в review

- **GIVEN** загрузка переходит в `review`
- **WHEN** происходит переход
- **THEN** автор получает пинг с приглашением подтвердить раскладку

### Requirement: Уведомление о рассинхроне

При переходе задачи в `orphaned` или `target_missing` система SHALL
уведомлять автора загрузки через настроенный механизм уведомлений
(`notifier`), чтобы рассинхрон не оставался незамеченным.

#### Scenario: Уведомление при потере источника

- **WHEN** задача переходит в `orphaned`
- **THEN** автор загрузки получает уведомление о рассинхроне

### Requirement: Download id в уведомлениях моноширинным для tap-to-copy

Уведомления, содержащие download id, система SHALL отображать id моноширинным
блоком (в Telegram — `<code>`), чтобы в клиенте работало tap-to-copy: id можно
скопировать одним касанием для перехода на `/download/{id}` или диагностики по
логам. Визуальный префикс (`#` / `download_id=`) SHALL оставаться вне
моноширинного блока, чтобы копировался чистый id без лишних символов.

#### Scenario: Id карточки review копируется одним касанием

- **GIVEN** уведомление о входе загрузки в `review` с download id
- **WHEN** бот рендерит сообщение
- **THEN** download id выводится моноширинным блоком (tap-to-copy), а префикс `#`
  остаётся обычным текстом вне блока

#### Scenario: Id в сообщении об ошибке копируется

- **GIVEN** сообщение об отказе операции с `download_id`
- **WHEN** бот рендерит сообщение
- **THEN** значение download id выводится моноширинным блоком для копирования

### Requirement: Экранирование внешнего текста при форматированных уведомлениях

При включённом форматировании исходящих сообщений (parse mode) система MUST
экранировать все внешние/недоверенные фрагменты перед вставкой в размеченное
сообщение: display name, распознанное название, источник/контекст, целевой путь,
причины распознавания, provider, id матча, ссылку на запись метабазы (URL), код и
текст ошибки. Экранирование MUST учитывать контекст вставки: для значения в
атрибуте (URL в `href`) — в том числе кавычку, чтобы недоверенное значение не
разорвало атрибут. Это защищает от того, что спецсимволы разметки сломают
сообщение или что разметка будет инъектирована из недоверенного источника
(инвариант «выход LLM недоверенный»). Секреты (токены/ключи/пароли) MUST NOT
попадать в текст уведомлений и логи.

#### Scenario: Спецсимволы в названии не ломают разметку

- **GIVEN** уведомление, где display name или распознанное название содержит
  символы разметки (`<`, `>`, `&`)
- **WHEN** бот рендерит форматированное сообщение
- **THEN** эти символы экранируются, сообщение доставляется корректно, а разметка
  из недоверенного текста не интерпретируется

#### Scenario: Внешний путь и причины экранируются

- **GIVEN** уведомление с целевым путём плана и причинами распознавания
- **WHEN** бот рендерит форматированное сообщение
- **THEN** символы разметки в пути и причинах экранируются перед вставкой

#### Scenario: Кавычка в URL записи не разрывает атрибут href

- **GIVEN** уведомление со ссылкой на запись метабазы, где id (а значит URL)
  содержит кавычку
- **WHEN** бот рендерит ссылку матча
- **THEN** кавычка в значении `href` экранируется, атрибут остаётся целым и
  сообщение доставляется

### Requirement: Показ записи матча метабазы в уведомлениях

Уведомления и подтверждения бота по загрузке с матчем метабазы система SHALL
сопровождать записью матча: provider и id, а при возможности построить URL
записи — ссылкой на страницу записи (тот же канонический билдер URL, что и веб).
Это SHALL применяться в карточке подтверждения (`review`) и в уведомлении о
готовности. Provider и id SHALL отражать эффективный выбор (с учётом ручных
правок), консистентно с веб-страницей загрузки и экраном ревью. Когда URL не
строится, матч SHALL показываться текстом (provider и id без ссылки), чтобы
ошибочную привязку было видно из бота.

Отсутствие матча (`none`/пусто) поверхности отражают по-разному: карточка
подтверждения SHALL показывать явный индикатор «нет матча» (в ревью полезно
видеть, что база не выбрана), а уведомление о готовности строку матча в этом
случае SHALL опускать (в финальном пинге «нет матча» — шум).

Provider, id и URL — недоверенные (метабаза/LLM/ручной ввод), поэтому система
MUST экранировать их перед вставкой в размеченное сообщение так, чтобы значение
не могло разорвать разметку в своём контексте (для URL в атрибуте `href` — с
учётом кавычки), иначе изготовленный id способен сломать сообщение и подавить
доставку уведомления (инвариант «выход LLM недоверенный»).

#### Scenario: Матч со ссылкой в карточке review

- **GIVEN** загрузка в `review` с подтверждённым матчем метабазы, для которого
  строится URL записи
- **WHEN** бот рендерит карточку подтверждения
- **THEN** матч выводится ссылкой на страницу записи с provider и id, а provider,
  id и URL экранированы (в т.ч. кавычка в значении `href`)

#### Scenario: Матч без строящегося URL показывается текстом

- **GIVEN** загрузка с матчем, для провайдера которого URL записи не строится
- **WHEN** бот рендерит карточку подтверждения
- **THEN** матч выводится текстом (provider и id) без ссылки

#### Scenario: Показ матча в уведомлении о готовности

- **GIVEN** загрузка с матчем метабазы, перешедшая в готовность
- **WHEN** бот рендерит уведомление о готовности
- **THEN** уведомление содержит запись матча (provider, id, при возможности —
  ссылку), чтобы ошибочную привязку было видно после раскладки

#### Scenario: Нет матча — индикатор в review, пропуск в готовности

- **GIVEN** загрузка без матча метабазы (`none`/пусто)
- **WHEN** бот рендерит карточку подтверждения, а затем уведомление о готовности
- **THEN** карточка подтверждения показывает индикатор «нет матча», а уведомление
  о готовности строку матча не содержит

#### Scenario: Эффективный провайдер после ручной правки

- **GIVEN** загрузка, где провайдер/id матча переопределены вручную
- **WHEN** бот рендерит запись матча
- **THEN** показываются эффективные provider и id (как на веб-странице загрузки),
  а не значения сырого распознавания

### Requirement: Выбор кандидата метабазы из карточки подтверждения бота

Карточка подтверждения бота SHALL предлагать выбрать источник из сохранённых
кандидатов метабазы inline-кнопками, когда для распознавания загрузки есть хотя
бы один такой кандидат (типичный триггер ревью — несколько подходящих записей без
единичного сильного матча), а не молча оставлять загрузку с первым/лучшим или без
базы. Когда сохранённых кандидатов нет, карточка кнопку выбора базы показывать
SHALL NOT. Выбор SHALL быть двухшаговым: кнопка выбора базы разворачивает список
кандидатов (по кнопке на кандидата, выбранный помечен), а нажатие кандидата
пиннит его как источник и обновляет карточку. Отдельная кнопка SHALL возвращать
карточку без изменений.

Выбор кандидата из бота — **ручной матч** (пиннинг источника): он SHALL NOT
запускать авто-раскладку; раскладка выполняется отдельным подтверждением
(«Применить»). Бот SHALL оставаться быстрым выбором из готового короткого списка
кандидатов, тогда как точные правки (ручной ввод id/URL, «без базы») — на веб-
поверхности.

Id кандидата приходит в `callback_data` и является недоверенным входом: перед
доменным вызовом выбора система MUST валидировать его как ULID на границе
транспорта; невалидный id MUST отклоняться без изменения состояния загрузки.
Текст inline-кнопок Telegram не интерпретируется как разметка, поэтому название
кандидата в подписи кнопки инъекции разметки не создаёт.

#### Scenario: Карточка с кандидатами предлагает выбор базы

- **GIVEN** загрузка в `review`, для распознавания которой сохранены кандидаты метабазы
- **WHEN** бот рендерит карточку подтверждения
- **THEN** карточка содержит кнопку выбора базы, ведущую к списку кандидатов inline-кнопками

#### Scenario: Выбор кандидата пиннит источник без авто-раскладки

- **GIVEN** развёрнутый в карточке список кандидатов метабазы
- **WHEN** пользователь нажимает кнопку кандидата
- **THEN** этот кандидат закрепляется как источник (ручной матч), карточка
  обновляется на месте, а авто-раскладка не запускается — для раскладки нужно
  явное «Применить»

#### Scenario: Id кандидата из callback валидируется на границе

- **GIVEN** callback выбора кандидата, где значение id кандидата недоверенное/невалидное
- **WHEN** бот обрабатывает callback
- **THEN** id кандидата валидируется как ULID до доменного вызова, а невалидное
  значение отклоняется без изменения состояния загрузки

#### Scenario: Возврат из списка не меняет состояние

- **GIVEN** развёрнутый в карточке список кандидатов
- **WHEN** пользователь нажимает кнопку возврата
- **THEN** бот возвращает исходную карточку подтверждения, не меняя выбранный источник

#### Scenario: Без кандидатов кнопки выбора базы нет

- **GIVEN** загрузка в `review`, для распознавания которой кандидаты метабазы не сохранены
- **WHEN** бот рендерит карточку подтверждения
- **THEN** карточка не содержит кнопку выбора базы