Dice Chess Wiki

07 Backend API Architecture

2 min read

Phase 3: Backend API Architecture (FastAPI)

База данных работает и наполняется, поэтому мы переходим к проектированию слоя API. Мы будем использовать FastAPI, так как он идеально подходит для создания быстрых аналитических эндпоинтов, отлично работает с асинхронным SQLAlchemy (asyncpg) и Pydantic v2.

Архитектура будет строиться по паттерну Репозиториев (Repository Pattern) для изоляции SQL запросов от логики роутеров.

Open Questions

Пожалуйста, посмотри список предложенных эндпоинтов ниже.

  1. Хватает ли этих эндпоинтов для начала работы над фронтендом лаборатории?
  2. Нужно ли нам сразу добавить эндпоинты для вычисления “Винрейта” (Win Rates) по конкретной позиции (FEN), или оставим это на следующий этап?

Proposed Changes: REST API Endpoints

Мы разобьем API на логические роутеры (модули). В первую очередь мы реализуем функционал только для чтения (Аналитика) и базовый функционал для Тренажера.

1. Роутер Игр и Поиска (/api/games)

Этот модуль отвечает за Лабораторию (поиск и фильтрация игр, просмотр ходов).

  • GET /api/games
    • Описание: Получение списка партий с пагинацией и мощными фильтрами.
    • Параметры (Query): min_rating, player_username, limit_time_min, result (победа белых/черных).
    • Цель: Заполнение таблицы в интерфейсе лаборатории самыми интересными или коммерческими партиями.
  • GET /api/games/{game_id}
    • Описание: Получение метаданных конкретной партии.
  • GET /api/games/{game_id}/turns
    • Описание: Получение всех ходов (Turns) и микро-ходов (played_moves) конкретной партии.
    • Цель: Пошаговый реплей (replay) игры на доске. Возвращает массивы FEN и кубиков.

2. Роутер Игроков (/api/players)

Модуль для поиска профессионалов и просмотра их статистики.

  • GET /api/players
    • Описание: Поиск игроков по имени или сортировка по рейтингу (топ-100 сильнейших).
  • GET /api/players/{player_id}/stats
    • Описание: Агрегированная статистика игрока (процент побед белыми/черными, частота выигрыша).

3. Роутер Тренажера (/api/trainer)

Модуль для режима “Угадай ход” и банка позиций. В будущем он будет защищен авторизацией (Google OAuth).

  • GET /api/trainer/positions/random
    • Описание: Выдает случайную интересную позицию из базы (например, позицию, где топ-игрок сделал неочевидный ход) для тренировки.
  • POST /api/trainer/attempts
    • Описание: Сохранение результата (угадал / не угадал).
    • Цель: Ведение личной статистики прогресса обучения.
  • GET /api/trainer/favorites
    • Описание: Получение списка сохраненных тобой “избранных” позиций (Банк позиций).
  • POST /api/trainer/favorites
    • Описание: Добавление текущей позиции на доске в личный Банк позиций.
    • Body: FEN позиции.

Verification Plan

Automated Tests

  • Для каждого эндпоинта мы напишем unit-тесты используя pytest и httpx.AsyncClient.
  • Тесты будут проверять логику фильтрации (например, что min_rating=2000 действительно возвращает только игры профи).

Manual Verification

  • FastAPI автоматически сгенерирует интерактивную документацию Swagger UI по адресу http://localhost:8000/docs. Мы сможем вручную протестировать все фильтры прямо в браузере, прежде чем писать код для фронтенда.

Graph View