Files
state-corp-backend/README.md
2026-09-28 14:20:17 +02:00

284 lines
15 KiB
Markdown
Raw 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).
### Контракт callback ИАС
ИАС отправляет `POST /api/v1/auth/sso/` с `Content-Type: application/x-www-form-urlencoded`: обязательное поле `sso_token`, необязательное `redirect_path` (локальный путь, по умолчанию `/main`). Вариант URL без завершающего `/` тоже принимает форму напрямую: промежуточного 301, теряющего POST, нет. Для регистрации в ИАС используйте канонический URL со слешем.
`SSO_CLOCK_SKEW_SECONDS` задаёт допустимое расхождение часов в секундах: по умолчанию 5, разрешено от 0 до 60. Увеличивайте его только при измеренном расхождении с ИАС: допуск применяется к `iat`, `nbf` и `exp`, поэтому продлевает окно принятия просроченного токена на указанное число секунд. Ограничение `exp - iat <= 60` и защита от повторного использования сохраняются. Для stage-портала ИАС используйте маршрут `/sso-redirect` без завершающего слеша; вариант со слешем может перенаправить на главную страницу вместо SSO.
Email в SSO-токене необязателен: отсутствующее поле, `null` и пустая строка означают отсутствие почты. Новый SSO-пользователь создаётся с `email=NULL` и `is_verified=false`; фиктивный адрес не генерируется. Переданный непустой email проверяется на формат, длину и конфликты. Если при следующем входе email отсутствует, сохранённый адрес и его признак подтверждения остаются прежними. Обычная регистрация по-прежнему требует email.
Повторный вход использует неизменяемую пару `(iss, user_id)`. Автоматическая первичная привязка к локальному аккаунту по-прежнему требует совпадения логина и непустой почты. При совпадении только логина вход отклоняется. Администратор может явно привязать существующий аккаунт после проверки принадлежности внешнего `user_id` пользователю:
```bash
python src/manage.py link_sso_identity --user-id <local-id> --expected-username <local-login> --subject <ias-user-id> --dry-run
# После проверки соответствия повторить без --dry-run.
```
Команда использует настроенный `SSO_ISSUER`, не переносит уже занятую identity и не меняет локальные права. До первого успешного входа `last_authenticated_at` равен `NULL`. Сам по себе одинаковый логин не является подтверждением принадлежности аккаунта.
Миграция `0010_sso_optional_email` разрешает NULL в email и времени последнего SSO-входа; данные пользователей сохраняются. При откате приложения оставьте эту совместимую схему: обратная миграция к NOT NULL требует предварительно обработать пользователей без почты и ещё не использованные привязки.
После успешной проверки одноразового ES256 JWT backend устанавливает Django session cookie и CSRF cookie и отвечает `303 Location: <redirect_path>`. GET callback возвращает 405; токен в URL не принимается. Пустая форма при включённом SSO возвращает 400, при выключенном — 503.
Перед выпуском проверяйте каждый контур отдельно: `SSO_ENABLED`, issuer, service code/target, соответствие callback у ИАС и доступность публичного ключа в контейнере. Включение dev не включает main. Правка маршрута не заменяет настройку провайдера и полный вход с настоящим SSO-токеном. Не копируйте токены/cookie в логи или отчёты.