Home Library

Home Library - Telegram-бот для учета домашней библиотеки.

Как Это Работает

Обычный сценарий работы с ботом выглядит так:

• Вы фотографируете штрихкод на задней стороне книги.
• Бот распознает ISBN по фотографии.
• Затем он проверяет, есть ли эта книга уже в каталоге домашней библиотеки.
• Если книга уже есть, бот показывает ее карточку и дает перейти к редактированию.
• Если книги еще нет, бот ищет информацию о ней по ISBN во внешних источниках: Лабиринт, Piter, Google Books и DuckDuckGo.
• Когда данные найдены, бот предлагает добавить книгу в каталог домашней библиотеки.
• После добавления можно указать или изменить статус, оценку, комментарий, темы и местоположение книги (например: дома, на даче, у мамы, дал Саше).

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

• отправьте /start, чтобы увидеть краткую справку
• отправьте /search <запрос> или просто текстовое сообщение, чтобы найти книгу в каталоге
• отправьте фото штрихкода, если хотите найти и добавить книгу по ISBN
• используйте кнопки в боте, чтобы менять статус, оценку, комментарий, темы и местоположение
• если вы админ, используйте /add_access_to_library для выдачи Telegram-доступа членам семьи
• если вы админ, используйте /export <json|xlsx|csv|yaml|db> для выгрузки каталога

Дополнительно бот умеет:

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

Быстрый старт

Требуется Python 3.13.

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Создайте файл .env в корне проекта и запишите в него следующее:

LIBRARY_BOT_TOKEN=<токен от BotFather>
# Один из двух вариантов ниже обязателен для самого первого запуска:
LIBRARY_BOT_ADMIN_USERNAME=<username админа без @ или с @>
# LIBRARY_BOT_ADMIN_TELEGRAM_USER_ID=<числовой Telegram user ID>

Запустите бота:

python -m home_library

Если library.db еще нет, приложение само создаст ее из example_library.xlsx.

Первый Запуск

• LIBRARY_BOT_TOKEN обязателен всегда. Получить токен можно у @BotFather.
• На самом первом запуске нужен LIBRARY_BOT_ADMIN_USERNAME или LIBRARY_BOT_ADMIN_TELEGRAM_USER_ID.
• Надежнее использовать LIBRARY_BOT_ADMIN_TELEGRAM_USER_ID: он не зависит от смены username (в сети есть инфа как узнать свой telegram user_id).
• Первым в бота должен написать именно этот Telegram-аккаунт.
• После первого входа бот сохраняет admin telegram_user_id в users.db.
• После этого обычные перезапуски уже не зависят от LIBRARY_BOT_ADMIN_USERNAME, пока users.db не потеряна.

Вместо .env можно использовать обычные переменные окружения:

export LIBRARY_BOT_TOKEN="<токен от BotFather>"
export LIBRARY_BOT_ADMIN_USERNAME="<username админа>"
python -m home_library

Доступ И Привязка

• Бот всегда работает только по списку доступа.
• Админ настраивается при первом запуске и потом определяется по сохраненному telegram_user_id.
• Только админ может использовать /add_library_member, /add_access_to_library, /remove_access_to_library и /export.
• Пользователь библиотеки и Telegram-доступ - это разные сущности.
• Пользователи библиотеки живут в library.db и используются для статусов, оценок и комментариев.
• Telegram-доступ живет в users.db и определяет только то, кто вообще может войти в бота.
• Выдача Telegram-доступа двухшаговая:

1. Админ открывает /add_access_to_library.
2. Админ вручную вводит @username. Администратору стоит сразу написать новому пользователю в личку и отправить ник бота.
3. Бот ждет первое сообщение именно от этого Telegram-аккаунта.
4. После первого сообщения бот сохраняет telegram_user_id в users.db.

• При редактировании статуса, оценки или комментария бот сначала спрашивает, за какого пользователя библиотеки сохранить изменение.
• /remove_access_to_library позволяет администратору удалить Telegram-доступ выбранного аккаунта и при желании сразу удалить выбранного члена библиотеки вместе со всеми его данными.

Пример добавления нового человека:

1. Админ делает /add_library_member Ваня.
2. Админ делает /add_access_to_library и вводит @vanya.
3. Админ пишет Ване в личку и скидывает ник Telegram-бота, после чего Ваня пишет боту первое сообщение.
4. После этого Ваня может искать книги и через Редактировать выбирать, за кого поставить статус, оценку или комментарий.

Наполнение Каталога

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

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

python init_db.py
python -m home_library

Важно:

• python init_db.py всегда пересоздает library.db заново
• существующие данные каталога в library.db будут заменены содержимым Excel
• users.db при этом не изменяется

Минимальное заполнение

1. Оставьте первую строку с названиями колонок.
2. Одна строка ниже - одна книга.
3. Минимально обязательные поля: author, title.
4. Остальные поля можно оставлять пустыми и заполнять позже.

Основные колонки:

Колонка	Описание
id	Порядковый номер
author	Автор книги
title	Название книги
topics	Темы или жанры
publisher	Издательство
link	Ссылка на книгу или магазин
livelib_url	Ссылка на страницу в LiveLib
location	Где сейчас книга
post_links	Полезные ссылки по книге
isbn	ISBN для поиска метаданных

Пользовательские данные задаются отдельными колонками для каждого человека:

• статус <имя> или status_<имя>
• оценка <имя> или rating_<имя>
• комментарий <имя> или comment_<имя>

Пример:

| id | author         | title                  | topics    | isbn          | статус Анна | оценка Анна |
|----|----------------|------------------------|-----------|---------------|-------------|-------------|
| 1  | Рик Дюффер     | Спиноза и попкорн      | философия | 9785001695882 | прочитана   | 5           |
| 2  | Филипп Гузенюк | Счастье в деятельности | бизнес    | 9785001955580 |             |             |

Не стоит:

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

Важно

• /search и обычное текстовое сообщение ищут только по уже сохраненным книгам в каталоге домашней библиотеки
• внешний поиск используется только в сценарии добавления книги по фото штрихкода
• экспорт /export db отдает только library.db; users.db в экспорт не входит

Файлы Данных

• example_library.xlsx - демонстрационный Excel-файл для настройки каталога
• library.db - локальная база каталога книг
• users.db - локальная база Telegram-привязок, admin state и списка доступа

В library.db основными таблицами являются:

• books
• users
• user_book_data

users.db хранит отдельно:

• Telegram username и user id админа
• Telegram username и user id допущенных пользователей
• pending-доступы, ожидающие первое сообщение

library.db удобно смотреть через SQLite-клиент вроде DBeaver или DB Browser for SQLite.

Команды

Команда	Описание
/start	Краткая справка
/search <запрос>	Поиск книги в локальном каталоге
/stats	Статистика каталога
/users	Список пользователей библиотеки
/add_library_member <имя>	Добавить пользователя библиотеки, только для админа
/add_access_to_library	Выдать Telegram-доступ, только для админа
/remove_access_to_library	Удалить Telegram-доступ и при желании пользователя библиотеки, только для админа
`/export <json	xlsx
/cancel	Отменить редактирование

Для Разработки

Для разработки установите зависимости через requirements-dev.txt, затем запускайте проверки:

python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest tests -v

Есть и более короткий прогон:

python -m pytest tests -q

Примеры точечного запуска:

python -m pytest tests/test_home_library_db.py::TestUsers -v
python -m pytest tests/test_home_library_providers.py::TestFetchFromGoogleBooks::test_success -v

В GitHub Actions настроен прогон, который запускает ruff, mypy и pytest.

Структура Проекта

home_library/
  domain/                 # модели предметной области
  services/               # сервисы статистики и экспорта
  storage/                # SQLite, схемы и Excel bootstrap
  providers/              # barcode и внешние книжные провайдеры
  interfaces/
    telegram/
      handlers/           # main.py, commands.py, callbacks.py, access.py

Основной entrypoint:

python -m home_library

Если Что-То Не Работает

1. Проверьте, что активировано venv: source venv/bin/activate.
2. Проверьте, что зависимости установлены: python -m pip install -r requirements-dev.txt.
3. Убедитесь, что задан LIBRARY_BOT_TOKEN.
4. Если это первый запуск или потерян users.db, проверьте LIBRARY_BOT_ADMIN_USERNAME или LIBRARY_BOT_ADMIN_TELEGRAM_USER_ID.
5. Убедитесь, что рядом лежит example_library.xlsx.
6. Если library.db отсутствует или повреждена, пересоздайте ее: python init_db.py.
7. Если сломались Telegram-привязки или список доступа, удалите users.db, заново задайте admin-переменную и пройдите первичную настройку админа.
8. Для проверки кода запустите python -m pytest tests -q.

TODO

• реализация TUI
• vk бот