В этой секции стоит дать общее описание проекта (что за проект, основное назначение, тезисно функционал и др.)

Сервис используется как шаблонный для создания других сервисов.

В этом блоке описываем все, что делает сервис: Например:

• Отправка уведомлений на почту
• Отправка пушей

В этой секции описываем основную логику работы приложения.

Например:

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

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

Настроить переменные окружения:

Тут указываем все настройки, которые приложение использует для работы.

Создаем docker-compose.yml и описываем в нем профили запуска. Пример лежит в проекте

Запуск возможен в 3x вариациях:

• docker compose up --profile app up - запуск только текущего сервиса;
• docker compose --profile db up - запуск pg
• docker compose --profile dev up - запуск сервиса + postgresql + выполнятся мииграции;

флаг -d запустит контейнер в фоновом режиме флаг --build перебилдит текущий проект

• Устанавливаем зависимости uv sync;
• Ставим pre-commit install для линта кода;
• Устанавливаем переменные окружения
• Запускаем pg docker compose --profile db up -d --build;
• Запускам миграции alembic командой alembic -x data=true upgrade head;
• Запускаем приложение uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload;

Здесь можно указывать все, что связано с тестами. Допустим указать параметры для пропуска "долгих" тестов, какие тесты отключены и почему и тд

pytest --maxfail=1 --cov=app -vv --cov-config .coveragerc

docker-compose exec template_service pytest --maxfail=1 --cov=app -vv --cov-config .coveragerc

Пропуск "долгих" тестов:

pytest --maxfail=1 --cov=app -vv --cov-config .coveragerc -m "not long"

Блок с линтерами. Идейно пока хватает pre-commit, но мало ли что.

Запуск линтеров по всему проекту:

pre-commit run --all-files

Блок с алембиком (если он нужен)

• alembic revision --autogenerate -m "message" - генерация новой миграции
• alembic upgrade head - накат миграций
• alembic -x data=true upgrade head - накат миграций вместе с данными. Выполняется функция data_upgrades() в файле миграции
• alembic upgrade head --sql > migration.sql - генерация SQL файла с миграциями.
• alembic downgrade -1 - откат миграции на 1 версию назад

В этом блоке указываем дополнительную информацию, которую сложно структурировать по существующим блокам

В ключевых местах проекта оставлены теги FIXME и TODO.

• Удалить все миграции из папки migrations/versions;
• Удалить все модели из папки app/v1/models;
• Удалить все контроллеры из папки app/v1/controllers;
• Удалить лишние импорты и роуты из app/v1/__init__py;
• Удалить файлы role_schema.py и user_schema.py из папки app/v1/controllers;
• Удалить файлы role_crud.py и user_crud.py из папки app/v1/crud;
• Удалить все тесты в папке app/tests/api/v1

Если планируется использовать Alembic и SQLAlchemy:

• в файле migrations/env.py прописываем schema = "Используемая схема"
• описать модели и импортировать их в файл app/api/db/enabled_migrations_models.py для включения этих моделей в миграции

Если алембик и SQLAlchemy использовать не планируется:

• Удаляем зависимости uv remove alembic sqlalchemy
• Удаляем файл alembic.ini
• Удаляем папку migrations
• Удаляем папку app/api/db
• Удаляем папки app/api/v1/crud и app/api/v1/models
• Удаляем из app/tests/conftest.py все фикстуры, использующие БД

Все настройки проекта находятся в файле app/config.py. Конфигурация автоматически собирает переменные из окружения. Для валидации конфига используется pydantic.BaseSettings https://docs.pydantic.dev/usage/settings/

По умолчанию подключено:

• Тесты миграций (файл app/tests/api/utils/test_migrations). test_up_down_consistency() является довольно медленным тестом при большом количестве миграций;
• Тестовый клиент fastapi;
• Тест хелсчека
• Все тесты по умолчанию интеграционные, т.е. используется тестовая БД.

Все модели стоит наследовать от app/api/db/base_class.py:BaseDBModel, т.к. базовый класс легче расширять

Все ENUM стоит так же наследовать от app/api/utils/enums/base_enum.py:BaseENUM.

Все схемы Pydantic так же стоит наследовать от app/api/v1/schemas/base_schema.py:BaseSchema. В ней по умолчанию прописаны корректная работа с datetime, указан декодер по умолчанию

• В контроллере всегда должен быть только юзкейс
• Юзкейс можно вызвать только FromDishka сразу со всеми его зависимостями, т.е. Если в юзкейсе будет использована сессия пг или использован какой нибудь клиент например в гпт, то эти элементы должны быть определены в провайдере Dishka и инициализированы вместе с юзкейсом.
• Отсюда все классы кроме CRUD (тут как кому удобно) и различных DTO так или иначе должны быть "зарегистрированы" в провайдерах.

Makefile это удобный способ назначать короткие для запоминания имена для "длинных" команд.

Допустим у Вас есть команда alembic upgrade head, которая применяет миграцию.

Вы можете назначить ей удобное короткое, для запоминания имя в файле Makefile:

migrate:	alembic upgrade head

Теперь Вам достаточно ввести в консоли:

make migrate

Искомая команда будет выполнена.