Перейти к содержанию

Getting Started

Руководство для нового разработчика проекта App Factory.

Требования

  • Python 3.12+
  • Flutter SDK 3.38+ (stable channel)
  • Docker & Docker Compose
  • Git

Быстрый старт (Backend)

1. Клонирование

git clone git@github.com:aleshkovskiy/app-factory.git
cd app-factory

2. Запуск сервисов (PostgreSQL + Redis)

make docker-up

3. Python-окружение

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

4. Миграции

make migrate

5. Загрузка тестовых данных

cd backend
source .venv/bin/activate
python manage.py seed_sample_data

Создаёт курс «Pushkin: 60 Days of Poetry» с 5 уроками, 7 медиа-файлами, 8 переводами и 10 quiz-вопросами. Команда идемпотентна — можно запускать повторно. Для пересоздания: python manage.py seed_sample_data --flush.

6. Запуск сервера

make run-backend

7. Тесты

make test-backend

Быстрый старт (Flutter)

1. Установка зависимостей

cd frontend
flutter pub get

2. Генерация кода (Freezed DTOs, Riverpod providers, Drift DB)

cd frontend
dart run build_runner build --delete-conflicting-outputs

Важно: build_runner генерирует .g.dart файлы для Freezed, Riverpod и Drift. Эти файлы коммитятся в git. Для тестов Drift на сервере (без Flutter runtime) необходим пакет libsqlite3-dev.

3. Тесты

flutter test

4. Анализ и форматирование

dart analyze
dart format --set-exit-if-changed .

5. Запуск на устройстве (macOS)

flutter run

Примечание: На сервере (VPS) доступны только unit/widget тесты. Для запуска на эмуляторе используйте git pull на macOS → flutter run.

API-документация

URL Описание
/api/docs/ Swagger UI — интерактивная документация
/api/redoc/ ReDoc — альтернативный вид
/api/schema/ OpenAPI schema (YAML)
/api/schema/?format=json OpenAPI schema (JSON)

URL для доступа

Production: https://app-factory.online/api/docs/ Staging: https://dev.app-factory.online/api/docs/ Local: http://localhost:8000/api/docs/

Документация проекта

make docs-venv    # Создать venv и установить зависимости (один раз)
make docs-serve   # Локальный сервер на порту 8100
make docs-build   # Сборка статического сайта

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

app-factory/
├── backend/          # Django REST API
│   ├── config/       # Settings, URLs, ASGI/WSGI, Celery
│   ├── apps/         # Django apps (auth, bootstrap, content, progress, quiz) + Django Unfold admin
│   ├── core/         # Shared middleware, exceptions
│   ├── tests/        # Test suite (320 tests)
│   └── Dockerfile    # Multistage (dev + production)
├── frontend/         # Flutter app (Riverpod, GoRouter, Dio, Freezed, Drift)
├── docs/             # Project documentation (MkDocs)
├── infra/            # CI/CD, Docker, Fastlane
├── .github/workflows/# GitHub Actions
├── Makefile          # Development commands
└── docker-compose.yml# Local services

Команды

Команда Описание
make test-backend Запуск pytest
make lint-backend Проверка ruff + black + isort
make test-frontend Запуск flutter test
make lint-frontend dart format + analyzer
make docs-serve Локальный сервер документации
make docker-up Запуск PostgreSQL + Redis
make docker-down Остановка сервисов

Правила проекта

  1. TDD обязательно — RED → GREEN → REFACTOR
  2. CLAUDE.md в каждой директории
  3. Structured logging по стандарту (structlog + Graylog GELF)
  4. Conventional Commits — feat(AF-XX): description
  5. После каждой задачи — /write-docs (обновить документацию в docs/)
  6. После каждой задачи — /update-docs (обновить CLAUDE.md затронутых директорий)
  7. Jira lifecycle — задача переводится в «В работе» в начале, /sync-jira done в конце
  8. Порядок завершения — тесты → линтеры → docs → CLAUDE.md → коммит → Jira close

Полезные ссылки