BookShelf

Справка о репозитории / Repository note

RU: мобильное приложение для учета книг и книжной полки.

EN: a mobile application for book and bookshelf tracking.

Статус / Status: активный проект 2026 года; ожидает рефакторинга и переименования. / active 2026 project; refactoring and repository rename are pending.

Текущее имя / Current name: BookShelf

Плановое имя / Planned name: bookshelf

Topics: book-management, cleanup-pending, kotlin, mobile-app, needs-rename, needs-review, status-active, type-app

Android-приложение для отслеживания прочитанных книг.

Тема дипломного проекта: "Приложение для отслеживания прочитанных книг".

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

Стек

Язык: Kotlin
UI: Jetpack Compose
Платформа: Android
IDE: Android Studio
Локальная БД: SQLite через Room
Сеть: Retrofit + Gson
Загрузка обложек: Coil
Тесты: JUnit

Основные возможности

Регистрация и вход пользователей.
Демо-вход с заранее заполненной библиотекой и статистикой.
Поиск книг по названию, автору или жанру.
Выбор источника поиска: все источники, Google Books, Open Library или локальный каталог.
Быстрый поиск по основным жанрам.
Загрузка данных из Google Books API и Open Library API.
Резервный локальный каталог, если внешние API временно недоступны.
Личная библиотека пользователя.
Статусы книг:
- Хочу прочитать
- Читаю
- Прочитано
- Отложено
- Брошено
Детальный экран книги с описанием, жанрами, источником, оценкой и отзывом.
Чтение/предпросмотр книги внутри приложения через встроенный WebView.
Автоматический учет времени чтения при выходе из встроенного экрана чтения.
Ручное добавление дня чтения: минуты и страницы.
Статистика:
- количество книг по статусам;
- прочитанные книги;
- книги в процессе чтения;
- минуты чтения;
- страницы;
- средняя оценка;
- календарь чтения за 30 дней;
- популярные жанры.
Рекомендации на основе жанров прочитанных книг.

Демо-пользователь

На экране входа есть кнопка демо-входа. Она автоматически выполняет вход и заполняет поля учетными данными.

Логин:  demo
Пароль: demo1234

При демо-входе приложение добавляет тестовые данные:

10 книг с разными статусами;
прочитанные книги с оценками и отзывами;
20 сессий чтения за последние 30 дней;
жанры для проверки рекомендательной системы.

Демо-сессии чтения пересоздаются при каждом демо-входе, поэтому календарь всегда остается актуальным для текущей даты. Пользовательские сессии чтения при этом не удаляются.

Источники книг

Сейчас используются:

Google Books API: https://www.googleapis.com/books/v1/
Open Library API: https://openlibrary.org/
локальный fallback-каталог внутри приложения

Поиск объединяет результаты Google Books и Open Library, удаляет дубликаты и показывает книги в общем списке. Если оба внешних источника недоступны или вернули пустой результат, используется локальный набор книг.

Google Books может временно вернуть 429 Too Many Requests, если исчерпана анонимная квота. Для стабильной работы можно добавить API-ключ в локальный файл local.properties:

GOOGLE_BOOKS_API_KEY=ваш_ключ_google_books

Файл local.properties не хранится в Git. Если ключ не указан, приложение продолжает делать публичные запросы без параметра key.

Чтение внутри приложения

На экране книги кнопка "Читать в приложении" открывает страницу источника во встроенном WebView.

Важно: приложение показывает тот режим чтения или предпросмотра, который предоставляет источник. Например, Open Library может показывать только Preview Only, если полный текст недоступен.

При выходе из экрана чтения появляется диалог:

Засчитать чтение?

Если нажать "Засчитать", приложение:

рассчитывает время с момента открытия экрана чтения;
сохраняет минимум 1 минуту, если чтение было короче минуты;
добавляет запись в reading_sessions;
если книги еще нет в библиотеке, добавляет ее со статусом Читаю;
обновляет статистику и календарь чтения.

Архитектура проекта

Проект использует простую MVVM-структуру:

UI Jetpack Compose
        |
        v
BooksViewModel
        |
        v
Repositories
        |
        +--> Room / SQLite
        |
        +--> Retrofit APIs

Основные директории:

app/src/main/java/com/finenkodenis/bookshelf
├── MainActivity.kt
├── BooksApplication.kt
├── data
│   ├── AppContainer.kt
│   ├── Book.kt
│   ├── BookSearchSource.kt
│   ├── BooksRepository.kt
│   ├── LibraryRepository.kt
│   ├── UserRepository.kt
│   ├── RecommendationEngine.kt
│   ├── DemoLibrarySeed.kt
│   ├── FallbackBooks.kt
│   └── local
│       ├── BooksDatabase.kt
│       ├── Entities.kt
│       ├── BookDao.kt
│       ├── UserDao.kt
│       ├── UserBookDao.kt
│       └── ReadingSessionDao.kt
├── network/model
│   ├── BookService.kt
│   └── OpenLibraryService.kt
└── ui/theme
    ├── BooksApp.kt
    ├── BooksViewModel.kt
    └── screens
        ├── AuthScreen.kt
        ├── SearchScreen.kt
        ├── LibraryScreen.kt
        ├── BookDetailScreen.kt
        ├── ReaderScreen.kt
        ├── RecommendationsScreen.kt
        └── StatsScreen.kt

База данных

Приложение использует Room поверх SQLite.

Файл настройки БД:

app/src/main/java/com/finenkodenis/bookshelf/data/local/BooksDatabase.kt

Имя БД:

bookshelf.db

Путь на устройстве или эмуляторе:

/data/data/com.finenkodenis.bookshelf/databases/bookshelf.db

Таблицы текущей реализации:

users
books
user_books
reading_sessions

Текущая Room-схема

┌────────────────────┐
│ users              │
│--------------------│
│ PK user_id         │
│ username           │
│ email              │
│ password_hash      │
│ password_salt      │
│ created_at         │
│ last_login_at      │
└─────────┬──────────┘
          │ 1
          │
          │ N
┌─────────▼──────────┐        N          1        ┌────────────────────┐
│ user_books         │────────────────────────────►│ books              │
│--------------------│                             │--------------------│
│ PK user_book_id    │                             │ PK book_id         │
│ FK user_id         │                             │ source             │
│ FK book_id         │                             │ external_id        │
│ status             │                             │ title              │
│ rating             │                             │ authors            │
│ review             │                             │ description        │
│ added_at           │                             │ categories         │
│ started_at         │                             │ published_date     │
│ finished_at        │                             │ page_count         │
│ updated_at         │                             │ language           │
└─────────┬──────────┘                             │ thumbnail_url      │
          │ 1                                      │ preview_link       │
          │                                        │ created_at         │
          │ N                                      │ updated_at         │
┌─────────▼──────────┐                             └────────────────────┘
│ reading_sessions   │
│--------------------│
│ PK session_id      │
│ FK user_book_id    │
│ read_date          │
│ minutes_read       │
│ pages_read         │
│ note               │
│ created_at         │
└────────────────────┘

В Room поля authors и categories хранятся как списки строк через AppConverters.

Документы по БД:

docs/database_schema.md
docs/database_schema.sql
docs/classes_overview.md

Файл docs/database_schema.sql содержит расширенную проектную SQL-схему для пояснительной записки. Она подробнее нормализует авторов, жанры, источники и рекомендации. Текущая Android-реализация использует более компактную Room-схему, показанную выше.

Файл docs/classes_overview.md содержит описание основных классов, экранов, репозиториев, DAO и моделей проекта.

Как посмотреть БД

Через Android Studio:

View -> Tool Windows -> App Inspection -> Database Inspector

Выбрать процесс:

com.finenkodenis.bookshelf

Затем открыть:

bookshelf.db

Через adb:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell run-as com.finenkodenis.bookshelf ls databases

Скопировать БД на компьютер:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" exec-out run-as com.finenkodenis.bookshelf cat databases/bookshelf.db > bookshelf.db

Установка и запуск

Открыть проект в Android Studio.
Дождаться Gradle Sync.
Выбрать эмулятор или Android-устройство.
Запустить конфигурацию app.

Минимальная версия Android:

minSdk = 25

Целевая версия:

targetSdk = 33
compileSdk = 34

Команды Gradle

Сборка debug APK:

.\gradlew.bat :app:assembleDebug

Запуск unit-тестов:

.\gradlew.bat test

Сборка и тесты:

.\gradlew.bat :app:assembleDebug test

Установка на подключенный эмулятор или устройство:

.\gradlew.bat :app:installDebug

Тесты

Unit-тесты находятся здесь:

app/src/test/java/com/finenkodenis/bookshelf

Покрыты:

конвертеры Room;
хеширование паролей;
рекомендательная система;
fallback-каталог книг;
обработка URL обложек;
расчет времени чтения;
демо-данные для статистики и рекомендаций.

Запуск:

.\gradlew.bat test

Основные сценарии проверки

Демо-вход

Запустить приложение.
Нажать "Войти как демо-пользователь".
Перейти в "Статистика".
Проверить, что отображаются книги, минуты, страницы и календарь за 30 дней.

Поиск книг

Открыть "Поиск".
Ввести название, автора или жанр.
Нажать "Найти".
Открыть карточку книги.
Добавить книгу в библиотеку.

Проверка рекомендаций

Войти демо-пользователем.
Открыть "Рекомендации".
Проверить строку основных тем.
Нажать "Обновить", если нужно повторно загрузить подборку.

Проверка чтения

Открыть книгу.
Нажать "Читать в приложении".
На экране чтения нажать "Назад".
В диалоге нажать "Засчитать".
Проверить, что книга получила статус Читаю, а статистика обновилась.

Ограничения

Полный текст книги доступен только если его предоставляет внешний источник.
Google Books и Open Library могут временно возвращать пустые ответы, 429 или 503. Для этого в приложении есть fallback-каталог.
Демо-данные предназначены для проверки интерфейса, статистики и рекомендаций, а не для реального каталога.
Текущие рекомендации основаны на частоте жанров, без ML-модели.

Связь с требованиями диплома

Требование	Реализация
Хранение книг и пользователей	Room/SQLite, таблицы `users`, `books`, `user_books`, `reading_sessions`
Статусы книг	`WANT_TO_READ`, `READING`, `READ`, `PAUSED`, `DROPPED`
Рекомендации	`RecommendationEngine`, подбор по жанрам прочитанных книг
Личный кабинет	Экран библиотеки, фильтрация по статусам, экран статистики
Графики и календарь	Статистика по статусам, календарь чтения за 30 дней, жанровая диаграмма
Экран книги	`BookDetailScreen`, описание, жанры, источник, статус, оценка, отзыв
Интеграции	Google Books API, Open Library API, fallback-каталог
Чтение внутри приложения	`ReaderScreen` со встроенным WebView

Репозиторий

https://github.com/MaximillianVoss/BookShelf.git

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.idea		.idea
app		app
docs		docs
gradle/wrapper		gradle/wrapper
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

BookShelf

Справка о репозитории / Repository note

Стек

Основные возможности

Демо-пользователь

Источники книг

Чтение внутри приложения

Рекомендации

Архитектура проекта

База данных

Текущая Room-схема

Как посмотреть БД

Установка и запуск

Команды Gradle

Тесты

Основные сценарии проверки

Демо-вход

Поиск книг

Проверка рекомендаций

Проверка чтения

Ограничения

Связь с требованиями диплома

Репозиторий

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

BookShelf

Справка о репозитории / Repository note

Стек

Основные возможности

Демо-пользователь

Источники книг

Чтение внутри приложения

Рекомендации

Архитектура проекта

База данных

Текущая Room-схема

Как посмотреть БД

Установка и запуск

Команды Gradle

Тесты

Основные сценарии проверки

Демо-вход

Поиск книг

Проверка рекомендаций

Проверка чтения

Ограничения

Связь с требованиями диплома

Репозиторий

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages