Files
state-corp-backend/README.md
Aleksandr Meshchryakov 0c4309a1bd
All checks were successful
State Corp Backend CI/CD / Quality gate (push) Successful in 3m54s
State Corp Backend CI/CD / Build linux/amd64 images once (push) Successful in 7m19s
State Corp Backend CI/CD / Refresh and release internal main (push) Has been skipped
State Corp Backend CI/CD / Release customer main (push) Has been skipped
State Corp Backend CI/CD / Release dev (push) Successful in 40s
Use registered IAS SSO target fkc_ecos
2026-09-25 12:31:21 +02:00

261 lines
9.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` или любым удобным способом.
База State Corp должна быть создана в кодировке `UTF8`. Если шаблоны внешнего
PostgreSQL-кластера используют `SQL_ASCII`, кодировку нужно задать явно:
```bash
createdb --owner=state_corp_app --encoding=UTF8 \
--locale=C.utf8 --template=template0 state_corp
```
Контейнеры web/Celery/migrate проверяют кодировку при запуске и не стартуют на
не-UTF8 базе, чтобы ограничения `varchar` не зависели от байтового представления
кириллицы.
### 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
```
## Вход через ИАС ЕЦП
Дополнительный SSO-вход включается переменной `SSO_ENABLED=true`. Публичный P-256 PEM-ключ провайдера должен быть смонтирован вне репозитория и webroot, а путь к нему передан в `SSO_PUBLIC_KEY_PATH`.
Используются настройки `SSO_PROVIDER_URL`, `SSO_SERVICE_CODE` (по умолчанию `fkc_ecos` — зарегистрированный IAS ECP target), `SSO_ISSUER` (по умолчанию `dvr`) и `SSO_SESSION_TTL_SECONDS` (по умолчанию `7200`). Перед включением зарегистрируйте callback `https://<state-corp-host>/api/v1/auth/sso/` в ИАС ЕЦП и сначала включите backend, затем frontend-кнопку. Для отката достаточно установить `SSO_ENABLED=false`; JWT-вход продолжит работать.
`SSO_GROUP_ROLE_MAP_JSON` — JSON-объект с именами доверенных групп ИАС ЕЦП в ключах и значениями только `user` или `admin`, например `{"ias_admin":"admin"}`. Группы вне этого списка не дают повышенных прав. Созданный через SSO пользователь без группы из списка получает `user`; при последующем входе исчезнувшая admin-группа понижает его до `user`. У ранее существовавшей локальной учётной записи ручная роль сохраняется. Только явная настройка `SSO_MANAGE_LINKED_USER_ROLES=true` передаёт управление её ролью SSO. Нормализованные группы, ОКПО, тип пользователя и организация сохраняются в `SsoIdentity`, исходный JWT не сохраняется.
Публичный PEM следует монтировать в контейнер как отдельный read-only файл и указывать его контейнерный путь в `SSO_PUBLIC_KEY_PATH`. Не размещайте PEM, реальные `.env` и токены обмена в webroot или offline-архиве. Полностью изолированная установка описана в [deploy/offline/README.md](deploy/offline/README.md).