Aleksandr Meshchriakov
345b1d0cc8
Some checks failed
CI/CD Pipeline / Run Tests (push) Failing after 45s
CI/CD Pipeline / Code Quality Checks (push) Failing after 48s
CI/CD Pipeline / Build Docker Images (push) Has been skipped
CI/CD Pipeline / Push to Gitea Registry (push) Has been skipped
CI/CD Pipeline / Deploy to Server (push) Has been skipped
240 lines
6.9 KiB
Markdown
240 lines
6.9 KiB
Markdown
# 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
|
||
|
||
## Структура проекта
|
||
|
||
```text
|
||
.
|
||
├── 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. Подготовка
|
||
|
||
```bash
|
||
cp .env.prod.example .env.prod
|
||
```
|
||
|
||
Для dev используется `.env.dev`.
|
||
|
||
### 2. Полный dev-стек
|
||
|
||
```bash
|
||
make dev-up
|
||
```
|
||
|
||
Или напрямую:
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
Сервисы:
|
||
|
||
- `db`
|
||
- `redis`
|
||
- `migrate`
|
||
- `web`
|
||
- `celery_worker`
|
||
- `celery_beat`
|
||
|
||
### 3. Только инфраструктурные сервисы
|
||
|
||
```bash
|
||
make services-up
|
||
```
|
||
|
||
Это удобно для локального запуска Django на хосте.
|
||
|
||
### 4. Проверка и остановка
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml ps
|
||
docker compose -f docker-compose.dev.yml logs -f web
|
||
make dev-down
|
||
```
|
||
|
||
## Локальный запуск без Docker
|
||
|
||
### 1. Зависимости
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
source "$HOME/.cargo/env"
|
||
uv sync --dev
|
||
```
|
||
|
||
### 2. Поднять PostgreSQL и Redis
|
||
|
||
Можно через `make services-up` или любым удобным способом.
|
||
|
||
### 3. Экспорт переменных
|
||
|
||
```bash
|
||
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. Миграции и запуск
|
||
|
||
```bash
|
||
cd src
|
||
uv run python manage.py migrate
|
||
uv run python manage.py createsuperuser
|
||
uv run python manage.py runserver
|
||
```
|
||
|
||
В отдельных терминалах:
|
||
|
||
```bash
|
||
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/`.
|
||
- Базовый запуск:
|
||
|
||
```bash
|
||
./scripts/run-tests.sh
|
||
```
|
||
|
||
- Запуск конкретного набора:
|
||
|
||
```bash
|
||
./scripts/run-tests.sh ../tests/apps/form_1
|
||
./scripts/run-tests.sh ../tests/apps/core/test_views.py
|
||
```
|
||
|
||
- Прогон в режиме, близком к production:
|
||
|
||
```bash
|
||
make test-prod
|
||
```
|
||
|
||
## Команды разработки
|
||
|
||
```bash
|
||
make install
|
||
make setup-dev
|
||
make test
|
||
make test-prod
|
||
make dev-up
|
||
make services-up
|
||
make migrate
|
||
make pre-commit
|
||
```
|