BOOK-LIBRARY: roadmap

BOOK-LIBRARY уже прошёл стадию простого каталога с формой загрузки. Это уже не черновая полка для файлов, а система, где рядом живут Express backend, SQLite, публичная SvelteKit-витрина, отдельная React-админка, legacy EJS UI, дерево категорий, очереди импорта, внешний поиск, LLM-провайдеры, translation pipeline и частичная интеграция с Quartz.

Roadmap здесь нужен не для того, чтобы механически перечислить «что ещё прикрутить». Он помогает удерживать фокус: где проект уже стал рабочим, где ему не хватает спокойной эксплуатации, а какие идеи лучше не смешивать в одну кучу.

Поэтому эту страницу стоит читать как карту состояния: что уже стало частью продукта, что требует доводки, а что сознательно оставлено на следующий этап. В таком виде план развития превращается в историю взросления BOOK-LIBRARY — от удобного каталога к системе, которой можно доверять данные, переводы и ежедневные операции.

Что уже продвинуто

В раннем плане многое звучало как намерение. Теперь часть этого уже можно проверять руками, поэтому важно отделить сделанное от того, что ещё только предстоит довести.

Уже сделано или заметно продвинуто:

• публичная витрина с деревом категорий, breadcrumbs, подкатегориями и subtree counts;
• постраничная выдача книг внутри категории через limit, offset, hasMore и total;
• отдельная React-админка вместо старой Svelte-admin части;
• durable jobs и polling для долгих операций;
• одиночный импорт, batch ZIP, Anna’s Archive, Flibusta и LLM-переводы как задачи;
• SearchPage в админке как единая точка внешнего поиска;
• интеллектуальная замена обложек через candidates, preview и replace;
• LLM providers как runtime-сущности в SQLite с priority и fallback;
• translation pipeline с сегментами, QA findings, retry/cancel, artifacts и publish/unpublish;
• SQLite-backed admin sessions, admin_users, смена пароля и emergency env override;
• CSRF для state-changing admin API;
• CORS-разделение public/admin origins и public CORP для обложек;
• production pipeline для backend и hosted React admin;
• частичная Quartz-интеграция через страницу библиотеки, generated catalog и mirrored covers.

Это не означает, что все эти зоны закончены навсегда. Скорее, это база, от которой теперь приходится отталкиваться: её уже нельзя подавать как абстрактный план, потому что она стала частью текущего состояния проекта.

1. Качество данных и управление каталогом

Следующий рост каталога связан не с новой кнопкой импорта, а с качеством данных после импорта: книга должна находиться, категория — быть объяснимой, карточка — не выглядеть случайной.

Что стоит усилить:

• отчёты по дублям и спорным совпадениям;
• ручное подтверждение сомнительных category matcher результатов;
• список книг без обложек или с подозрительными обложками;
• список карточек с коротким описанием или пустыми полями;
• отметку карточек, где метаданные получены автоматически и требуют проверки;
• отдельные проверки целостности: есть ли файл книги, обложка и публичная карточка.

Это особенно важно после подключения Anna’s Archive, Flibusta и batch ZIP. Чем проще добавить много книг, тем нужнее инструменты, которые помогают сохранить порядок и не превратить каталог в свалку, где каждая новая пачка исправлений создаёт новые сомнения.

2. Импорт: dry-run, отчёты и повтор

Durable import queue уже даёт хорошую основу: задача сохраняет статус, прогресс и ошибки. Дальше логично развивать не транспорт, а управляемость операции — чтобы перед импортом было понятно, что произойдёт, а после импорта было видно, где всё прошло нормально и где нужно вмешаться вручную.

Полезные шаги:

• dry-run для ZIP и внешнего импорта: показать, что будет добавлено, до записи в базу;
• отчёт по каждому файлу или найденной книге;
• отдельный список skipped/failed/suspected duplicate;
• повтор только неудачных элементов;
• ручное решение конфликтов до финального commit;
• экспорт отчёта импорта в JSON или Markdown.

Такие вещи редко выглядят ярко на скриншотах, зато сильно снижают тревожность при работе с большой коллекцией. Они отвечают на простой вопрос администратора: можно ли попробовать, увидеть последствия и исправить только проблемные места, а не разгребать всё вручную.

3. Переводы: deferred scope

LLM translation pipeline уже оформлен как отдельная система: jobs, canonical document, segmentation, provider selection, batch translation, QA findings, retry/cancel, artifacts и публикация. Следующий этап — не «добавить LLM», а закрыть сложные края вокруг качества и форматов. Здесь ценна не сама магия генерации, а контроль над процессом: получить результат, проверить его, сохранить артефакты и не выпускать наружу сырой перевод.

В deferred scope остаются:

• OCR для сканов и плохо извлекаемых PDF;
• production PDF renderer;
• извлечение медиа из DOCX/PDF;
• translation memory;
• budget dashboards и прогноз стоимости;
• более удобный review-интерфейс для больших книг;
• сравнение версий перевода после повторной генерации.

Эти задачи лучше не смешивать с базовым импортом. Перевод книги — отдельный производственный процесс, где важны воспроизводимость, стоимость, ручная проверка и возможность не публиковать сырой результат.

4. Безопасность файлов и внешних источников

Базовый security-слой уже продвинут: sessions в SQLite, admin_users, смена пароля, emergency override, CSRF, CORS split и CORP для обложек. Но именно потому, что проект умеет принимать архивы, тянуть данные из внешних источников и работать с обложками, файловые операции остаются зоной, где осторожность нужна всегда.

Что стоит держать в roadmap:

• проверка ZIP-путей и защита от выхода за временную директорию;
• проверка MIME и magic bytes, а не только расширения;
• лимиты на количество файлов и глубину архива;
• лимиты на размер и тип скачиваемых обложек;
• аккуратная очистка temp-директорий после ошибок;
• rate limiting для login, import, search и download-token endpoints;
• журналирование опасных или отклонённых операций.

Эти пункты не отменяют уже сделанную security-работу. Они просто относятся к другой поверхности риска: пользовательские файлы, архивы и внешние URL, то есть всё то, что приходит в систему извне и не должно получать лишнего доверия.

5. Бэкапы, миграции и проверка целостности

SQLite удобен для частной библиотеки, но по мере взросления проекта ценность быстро смещается из кода в данные: карточки, категории, обложки, переводы, artifacts и сами книги.

Нужны более явные процедуры:

• миграции схемы с версией базы;
• backup/restore для SQLite и uploads;
• проверка соответствия записей и файлов на диске;
• проверка artifacts переводов;
• понятная команда healthcheck;
• документированный перенос библиотеки на другой сервер.

Это не самая эффектная часть roadmap, но без неё любая богатая админка остаётся удобной только до первого серьёзного сбоя. Восстановление и проверка целостности должны быть не героическим ручным подвигом, а нормальной процедурой.

6. Quartz-интеграция без превращения сайта в файловое зеркало

Интеграция с Quartz уже началась: есть страница content/library.md, компонент quartz/components/LibraryPage.tsx, конфиг quartz/static/data/bookshelf.json, generated catalog quartz/static/generated/bookshelf-catalog.json и mirrored covers через quartz/util/bookshelfCatalog.ts.

Дальше важно сохранить правильную границу. Quartz — сайт заметок, подборок и контекста. BOOK-LIBRARY — система хранения, импорта, администрирования и скачивания файлов. Roadmap помогает не смешать эти роли и не потерять сильные стороны каждой части.

Хорошие следующие идеи:

• curated-подборки вместо полного зеркала библиотеки;
• Markdown-карточки для выбранных книг;
• обратные ссылки заметок на книги и книг на заметки;
• отдельные страницы подборок по темам;
• статический generated catalog для публичного отображения;
• download только через BOOK-LIBRARY и temp-token flow.

Такой подход даёт сайту полезный книжный слой, но не превращает репозиторий Quartz в хранилище книг.

7. Наблюдаемость и операционные страницы

React-админка уже стала операционным центром. Следующий шаг — лучше показывать состояние системы, а не заставлять администратора смотреть логи и догадываться, где именно копится проблема.

Что можно добавить:

• страницу «Проблемы каталога»;
• статус очередей и последних задач;
• фильтры по failed/cancelled jobs;
• отчёт по внешним источникам;
• ошибки LLM providers и частоту fallback;
• статистику по категориям, форматам и переводам;
• healthcheck для БД, uploads и прав доступа.

Для проекта такого масштаба не нужна тяжёлая observability-платформа. Достаточно нескольких честных страниц, которые отвечают на вопрос: что сейчас сломано, что требует внимания и что можно повторить. Это делает админку не просто набором действий, а местом, где видно здоровье библиотеки.

8. Production-эксплуатация

Production pipeline для backend и hosted React admin уже есть. Публичная SvelteKit-витрина может выкатываться отдельно, если она нужна. Дальше остаётся не сам факт деплоя, а спокойная эксплуатация: понятные проверки, предсказуемые настройки и готовность к восстановлению.

В roadmap остаются:

• smoke-test после деплоя;
• проверка secure cookie и HTTPS-настроек;
• документированные secrets и env-переменные;
• volume-стратегия для uploads;
• регулярный backup;
• rollback-процедура;
• проверка public/admin origins после смены домена.

Это нормальная стадия для проекта, который уже перестал быть локальным экспериментом. Чем больше данных и переводов появляется в системе, тем важнее простые процедуры восстановления.

Итог

Главный следующий шаг BOOK-LIBRARY — не наращивать количество возможностей любой ценой, а укреплять уже появившиеся рабочие контуры: импорт, каталог, переводы, безопасность, бэкапы, Quartz-интеграцию и операционную админку.

Проект уже умеет больше, чем ранний план. Поэтому новый roadmap должен быть честнее: не обещать заново сделанное, а показывать, какие места требуют доводки до спокойной повседневной эксплуатации.

Именно поэтому roadmap важен не только как список задач. Он фиксирует зрелость: какие решения уже доказали пользу, какие требуют защиты от хаоса, а какие нужно отложить, чтобы система росла без потери управляемости.