diff --git a/.gitignore b/.gitignore index cffdb3f..1f9bf62 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ # IDE /.idea/ /.vscode/ +/.claude/agent-memory/ diff --git a/docs/backlog.md b/docs/backlog.md index 478f92e..740b373 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -122,8 +122,82 @@ qBittorrent с файлами), подтверждение осознаннос Связано: [recognition.md](specs/recognition.md) (конвейер, модель уверенности), пакет `recognize`. +### НФТ: масштаб до 100 одновременных загрузок (потолок — 1000) + +Сейчас потолок по нагрузке нигде не зафиксирован: воркер, поллинг +qBittorrent, пул LLM-вызовов и запись в SQLite спроектированы «на глаз». +Записать в **нефункциональные требования** целевой ориентир — архитектура +держит до **100 одновременных загрузок** в работе (приём → распознавание → +раскладка), план-максимум — **1000**. Сама запись требования дешева и +высокоценна: она задаёт рамку для решений ниже по списку. Отдельно (уже +дороже) — аудит узких мест под эту цифру: одиночное соединение SQLite и +сериализация записи, конкурентность воркера и лимит параллельных +распознаваний, частота/стоимость поллинга и дедуп при наплыве. + +Связано: [architecture.md](specs/architecture.md) → «Отслеживание +загрузки»/«Хранилище», пакеты `worker`, `store`, `qbt`, `llm`. + ## Средний +### Словарь единого языка (ubiquitous language) + +Свести термины домена в один глоссарий, чтобы пользователь, документация, +код и агент говорили на одном языке: загрузка, раздача, распознавание, матч, +кандидат, раскладка, источник/цель, хардлинк, ревью, переход состояния и +т.д. — русский термин, английский идентификатор в коде, краткое определение. +Сейчас наименования расходятся между спеками, UI и кодом, и в диалоге с +агентом приходится каждый раз сверять понятия. Глоссарий — источник истины +по именам; на нём же строится агент-ревьювер наименований (см. +[«Агенты-ревьюверы качества»](#агенты-ревьюверы-качества-наименования-архитектура-конвенции-стиль)). + +Связано: [docs/conventions](conventions/README.md) (кросс-каттинг), +[architecture.md](specs/architecture.md) (домен), новый файл-глоссарий. + +### Агенты-ревьюверы качества (наименования, архитектура, конвенции, стиль) + +Набор узких сабагентов-ревьюверов поверх ревью-процесса из `CLAUDE.md`, +каждый со своей оптикой: соответствие наименований словарю единого языка, +соблюдение архитектурных границ (единое ядро/тонкие транспорты, инварианты +безопасности данных), конвенций (ошибки, логирование, конфиг, TZ), стиля +кода на высоком уровне и поиск дублирования. Запускаются как чекпоинт перед +`archive`/коммитом. Развивает ревью-процесс OpenSpec в сторону +воспроизводимых автоматических проверок, не заменяя человеческое ревью. + +Связано: `CLAUDE.md` (ревью-процесс, конвенции), +[docs/conventions](conventions/README.md), +[«Словарь единого языка»](#словарь-единого-языка-ubiquitous-language). + +### Автогенерируемый идентификатор загрузки (ULID/UUID) + +Сейчас загрузка фактически идентифицируется хешем торрента (`infohash`). Это +хрупко: у одной логической загрузки может быть **несколько** хешей +(перезаливы, докачивание, репаки, v1/v2 infohash), и привязка домена к хешу +мешает слиянию и истории. Ввести собственный стабильный идентификатор +(ULID/UUID), генерируемый при приёме, как первичный ключ домена; +`infohash`(ы) — отдельный атрибут/таблица «многие к одному», по которому +**остаётся** поиск и дедуп для обратной совместимости. Enabler для +«докачивания», «второго сезона», «версий/качества» и истории переходов. + +Связано: [database.md](specs/database.md) (PK `download`, `infohash`), +[«Раздачи с докачиванием»](#раздачи-с-докачиванием-слияние-при-повторном-добавлении), +[architecture.md](specs/architecture.md) → «Идентификация торрента», пакет +`store`. + +### История переходов загрузки + +Сохранять полную историю переходов состояний загрузки (что/когда/почему/кто +инициировал — воркер, человек, сверка), а не только текущее состояние. +Сейчас по задаче виден лишь актуальный статус, а разбор «как мы сюда попали» +идёт по логам сервера. Отдельная таблица истории даёт лог переходов в +карточке/расширенной информации и фундамент для метрик длительности стадий. +Естественно ложится на собственный идентификатор загрузки. + +Связано: [«Расширенная информация о загрузке»](#расширенная-информация-о-загрузке-в-web-ui) +(лог переходов), [workflow.md](specs/workflow.md) (граф состояний), +[«Наблюдаемость: метрики»](#наблюдаемость-метрики-и-учёт-стоимости-llm) +(длительности стадий), [database.md](specs/database.md), пакеты `worker`, +`store`. + ### Главная: список загрузок вместо таблицы Переделать главную страницу из таблицы в **список** карточек. Для каждой @@ -291,6 +365,34 @@ qBittorrent, без исходящих запросов на пользоват ## Низкий +### Мгновенные обновления через SSE + +Живые обновления прогресса сейчас на htmx-поллинге (фаза 2 веб-UI) — просто +и работает, но с задержкой в интервал опроса и холостыми запросами. +Перевести динамический контент (прогресс загрузки, смена статуса, раздача) +на Server-Sent Events, чтобы обновления приходили почти мгновенно и без +лишнего поллинга. Поллинг работает, поэтому это улучшение, а не блокер; SSE — +один долгоживущий ответ на соединение, ложится на server-rendered UI без +тяжёлого фронтенда. + +Связано: [architecture.md](specs/architecture.md) → «Транспорты», +[review-ux.md](specs/review-ux.md), пакет `httpapi`. + +### Полировка веб-UI: список и карточка загрузки + +Мелкие правки вёрстки и согласованности (низкая цена, заметный эффект): + +- в списке на главной показывать имя загрузки **ровно то**, что отдаём в + qBittorrent как имя раздачи, — чтобы список и клиент были синхронны + (уточняет [«Главная: список загрузок»](#главная-список-загрузок-вместо-таблицы)); +- в карточке блок «Распознано как» растянуть на всю ширину блока (сейчас + обрывается на середине); +- в блоке «Файлы и раскладка» приклеить стрелку к первой строке + (файл-источник), чтобы источник и цель выводились строго один под другим. + +Связано: [«Главная: список загрузок»](#главная-список-загрузок-вместо-таблицы), +[review-ux.md](specs/review-ux.md), пакет `httpapi`. + ### Многоступенчатая верификация привязки _(идея)_ Несколько раз извлекать данные из раздачи и контекста разными промптами,