State Corp Backend

Backend-сервис на Django/DRF для загрузки, хранения и выдачи корпоративной отчётности по организациям и формам Ф-1...Ф-6, с асинхронной обработкой через Celery.

Что умеет проект

• JWT-аутентификация и профиль пользователя.
• Swagger UI документация API.
• Health/Liveness/Readiness эндпоинты.
• Фоновые задачи с трекингом статуса (BackgroundJob).
• Справочник организаций.
• Импорт и хранение данных по формам:
  • Ф-1: выпуск продукции, НИОКР, кадры.
  • Ф-2: бухгалтерский баланс и финрезультаты.
  • Ф-3: кадры и оборудование.
  • Ф-4: сводные финансовые показатели.
  • Ф-5: инвентаризация оборудования.
  • Ф-6: возрастная структура оборудования.
• Админ-панель на Jazzmin с кастомным dashboard для мониторинга импортов и наполнения форм.

Технологии

• Python 3.11
• Django 3.2
• Django REST Framework
• PostgreSQL 15
• Redis 7
• Celery + django-celery-beat + django-celery-results
• drf-yasg (Swagger/OpenAPI)
• uv
• Docker / Docker Compose

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

.
├── src/
│   ├── apps/
│   │   ├── core/          # health, background jobs, openapi, startup checks
│   │   ├── user/          # auth, профиль пользователя
│   │   ├── organization/  # справочник организаций
│   │   ├── form_1/        # форма Ф-1
│   │   ├── form_2/        # форма Ф-2
│   │   ├── form_3/        # форма Ф-3
│   │   ├── form_4/        # форма Ф-4
│   │   ├── form_5/        # форма Ф-5
│   │   └── form_6/        # форма Ф-6
│   ├── core/              # urls/asgi/wsgi/celery
│   ├── settings/          # base/dev/production/test
│   └── manage.py
├── tests/
├── docker/
│   ├── Dockerfile
│   └── scripts/
├── docker-compose.dev.yml
├── docker-compose.service.yml
├── docker-compose.prod.yml
└── Makefile

Переменные окружения

Ключевые переменные:

• DJANGO_SETTINGS_MODULE: settings.dev, settings.production, settings.test.
• POSTGRES_*: доступ к PostgreSQL.
• REDIS_CACHE_URL, CELERY_BROKER_URL, CELERY_RESULT_BACKEND: Redis/Celery.
• COLLECTSTATIC_ON_MIGRATE: 1 или 0.
• STARTUP_CHECKS_ENABLED: fail-fast проверки DB/Redis перед стартом runtime-процессов.

Проект поддерживает старые config.settings.* импорты только как compatibility layer. Новая точка правды: settings.*.

Локальный запуск в Docker

1. Подготовка

cp .env.prod.example .env.prod

Для dev используется .env.dev.

2. Полный dev-стек

make dev-up

Или напрямую:

docker compose -f docker-compose.dev.yml up -d

Сервисы:

• db
• redis
• migrate
• web
• celery_worker
• celery_beat

3. Только инфраструктурные сервисы

make services-up

Это удобно для локального запуска Django на хосте.

4. Проверка и остановка

docker compose -f docker-compose.dev.yml ps
docker compose -f docker-compose.dev.yml logs -f web
make dev-down

Локальный запуск без Docker

1. Зависимости

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.cargo/env"
uv sync --dev

2. Поднять PostgreSQL и Redis

Можно через make services-up или любым удобным способом.

3. Экспорт переменных

export DJANGO_SETTINGS_MODULE=settings.dev
export POSTGRES_HOST=127.0.0.1
export POSTGRES_PORT=5432
export POSTGRES_DB=state_corp
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
export REDIS_HOST=127.0.0.1
export REDIS_CACHE_URL=redis://127.0.0.1:6379/1
export CELERY_BROKER_URL=redis://127.0.0.1:6379/0
export CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/0

4. Миграции и запуск

cd src
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver

В отдельных терминалах:

cd src && DJANGO_SETTINGS_MODULE=settings.dev uv run celery -A core worker --loglevel=INFO
cd src && DJANGO_SETTINGS_MODULE=settings.dev uv run celery -A core beat --loglevel=INFO

API

Базовый URL в dev: http://localhost:8000

• Swagger UI: GET /
• Admin: GET /admin/
• Health: GET /health/, GET /health/live/, GET /health/ready/

Версионированный API: /api/v1/

• Пользователи и auth: /api/v1/users/
• Фоновые задачи: /api/v1/jobs/
• Организации: /api/v1/organizations/
• Форма Ф-1: /api/v1/forms/f1/
• Форма Ф-2: /api/v1/forms/f2/
• Форма Ф-3: /api/v1/forms/f3/
• Форма Ф-4: /api/v1/forms/f4/
• Форма Ф-5: /api/v1/forms/f5/
• Форма Ф-6: /api/v1/forms/f6/

Основные auth-эндпоинты:

• POST /api/v1/users/register/
• POST /api/v1/users/login/
• POST /api/v1/users/token/refresh/
• POST /api/v1/users/token/verify/
• GET /api/v1/users/me/

Фоновые задачи

Основные Celery-задачи:

• apps.form_1.tasks.process_form_f1_file
• apps.form_2.tasks.process_form_f2_file
• apps.form_3.tasks.process_form_f3_file
• apps.form_4.tasks.process_form_f4_file
• apps.form_5.tasks.process_form_f5_file
• apps.form_6.tasks.process_form_f6_file

celery beat используется для системных периодических задач и готов к расширению, но доменно-специфичные расписания в этом проекте не преднастроены.

Тесты

• Все тесты находятся в tests/.
• Базовый запуск:

./scripts/run-tests.sh

• Запуск конкретного набора:

./scripts/run-tests.sh ../tests/apps/form_1
./scripts/run-tests.sh ../tests/apps/core/test_views.py

• Прогон в режиме, близком к production:

make test-prod

Команды разработки

make install
make setup-dev
make test
make test-prod
make dev-up
make services-up
make migrate
make pre-commit