API-for-Library

Описание проекта

RESTful API для управления библиотечным каталогом и процессом заимствования книг. Система позволяет:

• Аутентифицировать библиотекарей (регистрация, логин, JWT).
• Управлять CRUD операциями для книг и читателей.
• Выдавать и возвращать книги с бизнес-логикой лимитов и учётом доступных копий.
• Получать публичный список книг и защищённый список заимствований по читателю.

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

src/
├── main.py                # Точка входа и инициализация FastAPI
├── config.py              # Общие настройки приложения
├── database.py            # Настройка SQLAlchemy Engine и SessionLocal
├── auth/                  # Аутентификация и безопасность
│   ├── __init__.py
│   ├── config.py          # Конфигурация JWT и паролей
│   ├── constants.py       # Константы (ключи, префиксы)
│   ├── dependencies.py    # Depends для текущего пользователя и токена
│   ├── models.py          # User, UserToken
│   ├── route.py           # Маршруты /users и /auth
│   ├── schema.py          # Pydantic-схемы регистрации, логина, ответов
│   ├── security.py        # Хеширование паролей и генерация токенов
│   ├── service.py         # AuthService: регистрация, логин, refresh, reset
│   └── utils.py           # Вспомогательные функции для токенов и хешей
├── books/                 # Модуль управления книгами
│   ├── models.py          # Модель Books
│   ├── schemas.py         # Схемы BookCreate, BookUpdate, BookResponse
│   ├── service.py         # CRUD и бизнес-логика для книг
│   └── router.py          # Маршруты /books
├── reader/                # Модуль управления читателями
│   ├── models.py          # Модель Readers
│   ├── schemas.py         # Схемы ReaderCreate, ReaderUpdate, ReaderSchema
│   ├── service.py         # CRUD и бизнес-логика для читателей
│   └── router.py          # Маршруты /readers
├── borrow/                # Модуль заимствований
│   ├── models.py          # Модель BorrowedBook
│   ├── schemas.py         # Схемы BorrowRequest, BorrowResponse, ReturnResponse
│   ├── service.py         # Бизнес-логика выдачи/возврата и список заимствований
│   └── router.py          # Маршруты /borrow
└── common/                # Общие миксины и базовые модели
    ├── __init__.py
    ├── mixin.py           # AuditMixin
    ├── models.py          # BaseLibraryModel
    └── schema.py          # Базовые Pydantic-схемы

alembic/                  # Миграции Alembic
└── versions/              # Версии миграций

Запуск и настройка

1. Убедитесь, что установлены Docker и Docker Compose.

2. Запустите контейнеры (включая БД PostgreSQL):

   docker-compose up -d
   

3. При необходимости проверьте логи и статус сервиса БД:

   docker-compose ps
   docker-compose logs db
   

4. Создайте .env на основе .env.example:

   POSTGRES_USER=user
   POSTGRES_PASSWORD=password
   POSTGRES_HOST=0.0.0.0
   POSTGRES_PORT=5434
   POSTGRES_DB=postgres_db
   
   

5. Создайте виртуальное окружение и установите зависимости:

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

6. Инициализация alembic

alembic init alembic

7. Запустите миграции:

alembic upgrade head

8. Запустите приложение:

   uvicorn src.main:app --reload
   

Описание БД и миграций

• BaseLibraryModel: общий базовый класс для всех моделей, автоматическое определение __tablename__, dict(), __repr__.
• AuditMixin: id (UUID), created_by, created_at, updated_at, updated_by.
• Users и UserToken: модели для аутентификации.
• Books, Readers, BorrowedBook: модели каталога, читателей и заимствований.

Миграции Alembic:

1. initial tables — создание всех таблиц.
2. add description to books — добавление опционального поля description в books и массовое обновление старых записей.

Бизнес-логика

1. Выдача книги (POST /borrow):

   • Проверка наличия свободных копий (total_copies > 0).
   • Декремент total_copies и создание записи в BorrowedBook.
   • Ограничение: не более 3 активных заимствований на читателя.

2. Возврат книги (POST /borrow/return):

   • Поиск активной записи займа (return_date IS NULL).
   • Инкремент total_copies и запись return_date.

3. Список невозвращённых книг (GET /borrow/readers/{reader_id}/unreturned):

   • Возвращает книги по reader_id, где return_date IS NULL.

Аутентификация

• JWT via python-jose, хеширование паролей через passlib[bcrypt].

• Эндпоинты защищены частью маршрутов:

  • Публично: POST /users/register, POST /auth/token.
  • Защищено: все /books, /readers, /borrow, /users/me.

• Access и refresh токены:

  • Access token имеет короткий срок (ACCESS_TOKEN_EXPIRE_MINUTES).
  • Refresh token — REFRESH_TOKEN_EXPIRE_MINUTES, обновляется через POST /auth/token/refresh.

Тестирование

• Pytest + pytest-asyncio + TestClient.
• Юнит-тесты сервисов: попытка взять 4 книгу, взять нет в наличии, вернуть невыданную.
• Интеграционные тесты: регистрация, логин, доступ к защищённым эндпоинтам с токеном и без.

Дополнительная фича (идейное описание)

Система напоминаний читателю: автоматически отправлять email-уведомление читателю за день до дедлайна возврата.

Реализация:

• Добавить поле due_date в модель BorrowedBook.
• Фоновая задача (cron или Celery beat), проходящая по списку активных заимствований и отправляющая уведомления через SMTP или сторонний сервис (Mailgun).
• API для настройки срока возврата и настройки уведомлений в профиле библиотекаря.