BOOK-LIBRARY: roadmap

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

Этот roadmap описывает план развития. Пункты ниже не нужно читать как уже реализованные возможности, если они не подтверждены текущим кодом.

1. Усилить безопасность загрузки файлов

В проекте уже есть ограничения по расширениям и размеру файлов. Но для более спокойной эксплуатации этого мало, особенно при ZIP-архивах и внешних источниках обложек.

Что стоит сделать:

• закрыть Zip Slip риск: проверять, что каждый путь после распаковки остаётся внутри временной директории;
• проверять MIME и magic bytes, а не только расширение файла;
• добавить отдельные лимиты на количество файлов в архиве;
• аккуратно очищать временные файлы после ошибок;
• ограничить типы и размеры скачиваемых обложек;
• добавить rate limiting на login, batch upload и download-token endpoints.

В docs/SECURITY.md уже перечислены похожие риски. Следующий шаг — не просто держать их в документе, а закрыть в коде и проверках.

2. Сделать миграции и резервное копирование

Сейчас SQLite-схема создаётся при старте приложения. Для личного проекта это удобно, но при накопленной библиотеке хочется более управляемый процесс.

План:

• завести явные миграции схемы;
• добавить версию базы;
• описать backup/restore для library.db, uploads/books и uploads/covers;
• добавить команду проверки целостности: есть ли файл книги и обложка для каждой записи;
• подготовить экспорт каталога в JSON/Markdown.

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

3. Улучшить качество каталога и поиска

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

Возможные шаги:

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

Важно не усложнять интерфейс раньше времени. Если библиотека используется как личный каталог, простая навигация по категориям может быть ценнее перегруженного поиска.

4. Улучшить batch import

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

Что стоит добавить:

• dry-run режим: показать, что будет импортировано, до записи в базу;
• отчёт по конфликтам и дублям;
• повторный запуск только ошибочных файлов;
• сохранение отчёта импорта в базе;
• ручное сопоставление спорных категорий;
• очередь задач, чтобы долгий импорт не держался только на одном HTTP-запросе.

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

5. Интеграция с этим Quartz-сайтом

Отдельное roadmap-направление — связать BOOK-LIBRARY с текущим Quartz-сайтом. Здесь лучше выбрать интеграцию, которая не требует публиковать сами файлы книг, но даёт сайту полезный контент.

Конкретный план:

1. Экспорт Markdown-карточек книг. Добавить команду в BOOK-LIBRARY, которая берёт выбранные записи из SQLite и создаёт Markdown-файлы для Quartz: название, автор, категория, описание, формат, ссылка на внутреннюю карточку библиотеки или заметка о доступности.
2. Публикация подборок. Экспортировать не всю библиотеку, а curated-подборки: «что почитать по теме», «книги по разработке», «художественная полка», «научпоп». Такие страницы хорошо ложатся в content/ и не превращают сайт в зеркало файлового каталога.
3. Синхронизация обложек как статических изображений. Для публичных подборок копировать выбранные WebP-обложки в content/images/book-library/ и прописывать их в frontmatter или в карточках страниц.
4. Связь заметок и обзоров. Если по книге появляется отдельная заметка или обзор на Quartz-сайте, хранить в BOOK-LIBRARY поле quartz_slug или отдельную таблицу связей. Тогда карточка книги сможет вести на заметку, а статья на сайте — обратно к записи в библиотеке.
5. Автоматический индекс подборок. На стороне Quartz можно держать проектный раздел и страницы подборок, а BOOK-LIBRARY будет генерировать только данные: Markdown или JSON, который затем попадает в сборку сайта.

Такой вариант интеграции аккуратнее, чем просто открыть скачивание книг на публичном сайте. Quartz остаётся витриной заметок, обзоров и подборок, а BOOK-LIBRARY — рабочей системой хранения и администрирования каталога.

6. Наблюдаемость и админские отчёты

Для маленькой библиотеки достаточно видеть ошибки в консоли. Но по мере роста коллекции лучше иметь простые отчёты.

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

• лог импорта по каждому файлу;
• список книг без обложек;
• список книг с пустым или слишком коротким описанием;
• статистику по категориям и форматам;
• отчёт по временным токенам и скачиваниям без персональных данных;
• healthcheck, который проверяет БД и наличие директорий uploads.

Это не обязательно делать сложной observability-системой. Для проекта такого масштаба часто достаточно понятной админской страницы «Проблемы каталога».

7. Аккуратный production-деплой

Если проект переносить из локального режима в постоянную эксплуатацию, нужны отдельные инфраструктурные решения:

• HTTPS и корректные secure cookie;
• CORS по конкретному домену;
• хранение секретов вне репозитория;
• reverse proxy перед Express;
• отдельная директория или volume для uploads;
• регулярный backup;
• понятный deploy script и smoke-test после запуска.

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