289 lines
16 KiB
Markdown
289 lines
16 KiB
Markdown
# План реализации backend-контрактов по требованиям frontend
|
||
|
||
## Контекст
|
||
Фронт прислал два источника требований:
|
||
- `backend-endpoints-from-mocks.md`
|
||
- `backend-form-upload-endpoints.md`
|
||
|
||
Цель: привести backend к `backend-first` контрактам и закрыть расхождения между текущей API-реализацией и ожидаемым shape.
|
||
|
||
Текущая ветка:
|
||
- `feature/backend-endpoints-contract-implementation-plan` (от ветки `dev`)
|
||
|
||
## Ключевой результат
|
||
1. Все эндпоинты и payload строго совпадают с договорёнными контрактами.
|
||
2. Upload контракт для Ф-2…Ф-6 нормализован (multipart request + единый ответ + единая схема ошибок).
|
||
3. Аналитика и внешние контуры предоставляются через backend-first агрегированные endpoint’ы.
|
||
4. План покрыт автотестами и OpenAPI-документацией.
|
||
|
||
## Проходы и статус выполнения
|
||
|
||
- [x] **Pass 0 — Инициация:** создана отдельная ветка от `dev` и зафиксирован общий план в репозитории.
|
||
- [x] **Pass 1 — Discovery & контрактный каркас:** подготовка сериализаторов контрактов, уточнение форматов, матрица соответствий.
|
||
- [x] **Pass 2 — Пользователи и аутентификация:** доработка `users/me` + user-management.
|
||
- [x] **Pass 3 — Формы:** выравнивание upload F-2…F-6.
|
||
- [x] **Pass 4 — Аналитика:** financial-summary / economics / personnel / equipment / products / risk / forecast.
|
||
- [x] **Pass 5 — Внешние контуры:** industrial/prosecutor/procurements/arbitration/security registries.
|
||
- [x] **Pass 6 — Финализация:** OpenAPI + массовое тестирование + smoke.
|
||
|
||
### Журнал выполненных шагов
|
||
|
||
- **Pass 0 — Инициация (2026-04-14): завершён**
|
||
- создана рабочая ветка `feature/backend-endpoints-contract-implementation-plan` от `dev`.
|
||
- создан и закоммичен базовый план по требованиям фронта.
|
||
- добавлены pass-стадии и статусный трекер в сам документ.
|
||
- **Pass 1 — Discovery (2026-04-14): завершён**
|
||
- сформированы текущие и целевые артефакты контрактов в `docs/implementation/*`.
|
||
- **Pass 2 — Users/me + dictionaries (2026-04-14): завершён**
|
||
- доработан `GET /api/v1/users/me/` по полям `is_active` и `middle_name`.
|
||
- добавлен `GET /api/v1/dictionaries/corporation-scopes/` и базовые тесты (не прогонены без Postgres).
|
||
- доработан `GET /api/v1/users/admin/users/` под контракт импорта.
|
||
- переведены поля `corporation_scope`/`corporation_scope_label` на скалярный контракт в `organizations` list/detail.
|
||
- добавлены метрики `progress_message`, `result`, `error`, `started_at`, `completed_at`, `duration`, `is_successful` для user-management.
|
||
- **Pass 3 — Формы (2026-04-14): завершён**
|
||
- введены общие upload-сериализаторы и payload helpers для F-2…F-6.
|
||
- выровнен request/response контракт upload-эндпоинтов (sync/async, report-период, `upload_id`, `job_id`).
|
||
- добавлена единая схема ошибок валидации multipart.
|
||
- добавлены contract tests на upload endpoints F-2…F-6.
|
||
- **Pass 4 — Аналитика (2026-04-14): завершён**
|
||
- добавлены contract checks для всех analytics endpoint’ов:
|
||
- `financial-summary`, `economics`, `personnel`, `equipment`, `products`, `forecast`, `risk-profile`, `dashboard`.
|
||
- дополнена проверка query-валидации для invalid `economics`-запроса.
|
||
- **Pass 5 — Внешние контуры (2026-04-14): завершён**
|
||
- добавлен endpoint `information-security-registry-entries/` с фильтрами `organization` и `presence_status`.
|
||
- расширены contract checks для внешних списков (prod/products/prosecutor/public-procurement/arbitration/security).
|
||
- **Pass 6 — Финализация (2026-04-14): завершён**
|
||
- доработан выбор "последней" фоновой задачи в `admin/users` по фактическому временному событию:
|
||
`completed_at` → `started_at` → `updated_at` → `created_at`.
|
||
- запущены целевые smoke-тесты:
|
||
`tests/apps/user`, `tests/apps/organization/test_api.py`, `tests/apps/organization/test_analytics_api.py`, `tests/apps/external_data/test_api.py`.
|
||
- smoke прогнан локально и на удалённой базе `TEST_POSTGRES_HOST=192.168.1.33` — `106 passed`.
|
||
|
||
---
|
||
|
||
## Риск-оценка перед стартом
|
||
- Некоторые поля периодов требуют согласования формата валидации (`report_period_display`/`report_half_year`).
|
||
- Отдельное решение по async upload: порог `1MB` определяет фоновую обработку.
|
||
- Нужно подтвердить, где `organization`/`profile` поля могут быть `null`.
|
||
|
||
---
|
||
|
||
## Этап 0. Подготовка (0.5 дня)
|
||
- Преобразовать требования в контрактные `serializers` (без бизнес-логики): request/response/error payload.
|
||
- Собрать матрицу `Текущий endpoint -> Целевой контракт`.
|
||
- Определить инварианты:
|
||
- формат дат (`YYYY-MM-DD`, ISO datetime),
|
||
- единицы измерения (`rub`, `rub_thousands`, флаги),
|
||
- статус-коды для upload.
|
||
- Зафиксировать, какие endpoint’ы относятся к `REFACTOR`, `ADD`, `NEW`.
|
||
|
||
---
|
||
|
||
## Этап 1. Пользователь и админ-данные (1 день)
|
||
|
||
### 1.1 `GET /api/v1/users/me/`
|
||
- Проверить и довести payload:
|
||
- `role`
|
||
- `role_label`
|
||
- `capabilities.can_access_admin_page`
|
||
- Убедиться, что профиль возвращает полное имя и `middle_name`.
|
||
- Рефактор теста и OpenAPI-декларации.
|
||
|
||
### 1.2 `user-management`
|
||
По смежному списку улучшений дополнить:
|
||
- `GET /api/v1/users/admin/users/` — `middle_name`, обязательность `first_name`/`last_name`.
|
||
- Добавить поля метрик задач импорта:
|
||
- `progress_message`, `result`, `error`, `started_at`, `completed_at`, `duration`, `is_successful`.
|
||
|
||
**Deliverable:** контрактные тесты для user payload + профиль + админ-списка.
|
||
|
||
---
|
||
|
||
## Этап 2. Организации и словари (1–2 дня)
|
||
|
||
### 2.1 `GET /api/v1/organizations/`
|
||
- Сохранить существующий список + пагинацию.
|
||
- Проверить и добавить/нормализовать:
|
||
- query: `corporation_scope`, `organization_type`;
|
||
- response: `short_name`, `full_name`, `corporation_scope`, `corporation_scope_label`, `organization_type`, `organization_type_label`, `kpp`, `okpo`.
|
||
|
||
### 2.2 `GET /api/v1/organizations/{id}/`
|
||
- Довести детальную карточку до полного агрегированного контракта:
|
||
- `short_name`, `full_name`, `corporation_scope`, `organization_type` (+ labels),
|
||
- `registration_date`, `legal_address`, `activity_type`, `founder_name`, `ownership_type`, `legal_form`, `charter_capital_amount`,
|
||
- `general_director`, `summary`, `active_registries`.
|
||
|
||
### 2.3 Новый `GET /api/v1/dictionaries/corporation-scopes/`
|
||
- Реализовать read-only endpoint со списком:
|
||
- `code`, `name`, `short_name`, `sort_order`.
|
||
- Формат сортировки по `sort_order`.
|
||
|
||
**Deliverable:** контрактные тесты org-list/detail + словаря.
|
||
|
||
---
|
||
|
||
## Этап 3. Upload форм Ф-2…Ф-6 (2 дня)
|
||
|
||
Для каждого endpoint:
|
||
- `POST /api/v1/forms/f2/upload/`
|
||
- `POST /api/v1/forms/f3/upload/`
|
||
- `POST /api/v1/forms/f4/upload/`
|
||
- `POST /api/v1/forms/f5/upload/`
|
||
- `POST /api/v1/forms/f6/upload/`
|
||
|
||
### 3.1 Request-часть (multipart)
|
||
Стабилизировать сериализаторы:
|
||
- общий `file` (формат `.xlsx/.xls`, лимит размера);
|
||
- общий `report_year`;
|
||
- период:
|
||
- f2 — `report_quarter`
|
||
- f3 — по текущей бизнес-логике (квартал/год);
|
||
- f4 — `report_half_year`
|
||
- f5,f6 — год.
|
||
- Ввести явный error-serializer для валидации и описать его в OpenAPI.
|
||
|
||
### 3.2 Response-часть
|
||
Единый контракт ответа:
|
||
- `upload_id`
|
||
- `form`
|
||
- `status` (`queued|processing|done|error`)
|
||
- `job_id` для async
|
||
- `created_at`
|
||
- поля периода и `report_period_display`
|
||
- (для sync) блок `data` или финальное подтверждение обработки.
|
||
|
||
### 3.3 Async/Sync модель
|
||
- Прописать порог асинхронной обработки и зафиксировать его в конфиге или service.
|
||
- Для sync — единый формат успеха/ошибки.
|
||
- Для async — единый статус-кит с `job_id`.
|
||
|
||
### 3.4 Тестирование
|
||
- Unit для upload serializer’ов.
|
||
- Интеграционные тесты sync и async сценариев.
|
||
- Контракт-assert по полям `upload_id/form/status/job_id`.
|
||
|
||
**Deliverable:** все пять upload имеют единый JSON контракт и валидируемые ошибки.
|
||
|
||
---
|
||
|
||
## Этап 4. Аналитика организаций (2 дня)
|
||
|
||
### 4.1 `GET /api/v1/organizations/{id}/analytics/financial-summary/`
|
||
- Проверить query `report_year`, `report_quarter`.
|
||
- Обязательные блоки: `revenue`, `net_profit`, `taxes_paid`, `insurance_contributions` с `amount`, `previous_amount`, `delta_percent`.
|
||
|
||
### 4.2 `GET /api/v1/organizations/{id}/analytics/economics/`
|
||
- Проверить `group`, `from_year`, `to_year`.
|
||
- Добавить/подтвердить `periods`, `kpis`, `series`, `ratios` в соответствии с docs.
|
||
|
||
### 4.3 `GET /api/v1/organizations/{id}/analytics/personnel/`
|
||
- query: `report_year`, `history_years`.
|
||
- вернуть `headcount`, `age_distribution`, `history`.
|
||
|
||
### 4.4 `GET /api/v1/organizations/{id}/analytics/equipment/`
|
||
- query: `report_year`.
|
||
- вернуть `summary`, `age_distribution`, `categories`.
|
||
|
||
### 4.5 `GET /api/v1/organizations/{id}/analytics/products/`
|
||
- query: `frequency`, `price_mode`, `report_year`.
|
||
- нормализовать `summary`, `production_series`, `sales_series`.
|
||
|
||
### 4.6 Risk & forecast
|
||
- проверить `/organizations/{id}/risk-profile/` и `/analytics/forecast/` на соответствие названий полей и enum-сценариев.
|
||
|
||
**Deliverable:** `contract tests` для всех analytics endpoints и `dashboard`.
|
||
|
||
---
|
||
|
||
## Этап 5. Внешние контуры (1 день)
|
||
|
||
### 5.1 `GET /api/v1/industrial-products/`
|
||
- Проверить query: `organization`, `product_class`, `search`, пагинация.
|
||
|
||
### 5.2 `GET /api/v1/prosecutor-checks/`, `public-procurements/`, `arbitration-cases/`
|
||
- Проверить фильтры дат и enum-валидаторы.
|
||
- Свести response к единой форме пагинации.
|
||
|
||
### 5.3 Новый `GET /api/v1/information-security-registry-entries/`
|
||
- Добавить модель/миграцию/serializer/viewset при отсутствии.
|
||
- Добавить фильтр по `organization`, `presence_status` и пагинацию.
|
||
|
||
**Deliverable:** все внешние endpoints доступны в одном стиле и с единым форматированием.
|
||
|
||
---
|
||
|
||
## Этап 6. OpenAPI + документация (0.5 дня)
|
||
- Обновить `api_docs`/`swagger_auto_schema` для всех touched endpoints.
|
||
- Добавить/обновить ручные схемы ошибок.
|
||
- Убедиться, что path-tags корректны (`Пользователь`, `Организации`, `Аналитика`, `Внешние данные`, `Форма F-*`).
|
||
|
||
---
|
||
|
||
## Чеклист проходов (обновлять после завершения)
|
||
|
||
### Pass 1. Discovery & контрактный каркас
|
||
- [x] Создать ветку для плана.
|
||
- [x] Зафиксировать базовую версию плана в Git.
|
||
- [x] Собрать и верифицировать список endpoint’ов и текущую реализацию в коде.
|
||
- [x] Сопоставить требования из frontend-документов с текущими контрактами.
|
||
- [x] Закрыть риск-реестр и уточнить спорные бизнес-правила (в рамках черновика).
|
||
- [x] Подготовить проектные черновики контрактов для ключевых payload (users/me, upload, org fields).
|
||
- [x] Составить матрицу изменений для всех endpoint’ов.
|
||
|
||
Текущий статус Pass 1: **завершён** (все артефакты собраны в `docs/implementation/*`).
|
||
|
||
- [x] Переход к Pass 2.
|
||
|
||
### Pass 2. Пользователи и организации
|
||
- [x] Вынести/подтвердить контракт `GET /api/v1/users/me/`.
|
||
- [x] Доработать `user-management` поля и обязательности.
|
||
- [x] Довести `organizations` list/detail до контрактов.
|
||
- [x] Добавить/проверить `/api/v1/dictionaries/corporation-scopes/`.
|
||
|
||
### Pass 3. Формы
|
||
- [x] Унифицировать upload-схемы Ф-2…Ф-6 (request).
|
||
- [x] Унифицировать upload-ответы Ф-2…Ф-6 (response).
|
||
- [x] Зафиксировать async/pending статус и `job_id`.
|
||
- [x] Добавить общий error serializer для валидации multipart.
|
||
|
||
### Pass 4. Аналитика
|
||
- [x] Финализировать `financial-summary` и добавить расчёты deltas/period. (2026-04-14)
|
||
- [x] Вынести/довести `economics`, `personnel`, `equipment`, `products`. (2026-04-14)
|
||
- [x] Проверить/документировать `risk-profile`, `forecast`. (2026-04-14)
|
||
- [x] Добавить dashboard фильтрацию и стабильные `cluster` метрики. (2026-04-14)
|
||
|
||
### Pass 5. Внешние данные
|
||
- [x] Довести внешние реестры к единообразным фильтрам/ответам. (2026-04-14)
|
||
- [x] Добавить `information-security-registry-entries`. (2026-04-14)
|
||
|
||
### Pass 6. Финализация
|
||
- [x] Обновить OpenAPI по всем контрактам.
|
||
- [x] Прогнать контрактные и smoke тесты.
|
||
- [x] Проверить:
|
||
- `pytest tests/apps/user`
|
||
- `pytest tests/apps/organization/test_api.py tests/apps/organization/test_analytics_api.py`
|
||
- `pytest tests/apps/external_data/test_api.py`
|
||
|
||
---
|
||
|
||
## Этап 6. Финальная валидация и релиз-критерии (0.5 дня)
|
||
|
||
- Добавить новые контрактные тесты в отдельный набор (если будет слишком много — отдельный файл).
|
||
- Smoke-check через API для:
|
||
- `/users/me/`, org list/detail, analytics, dashboard,
|
||
- все upload-эндпоинты (sync/async),
|
||
- внешние контуры и dictionaries.
|
||
|
||
---
|
||
|
||
## План-график по времени
|
||
- Этап 0: 0.5 дня
|
||
- Этап 1: 1 день
|
||
- Этап 2: 1.5–2 дня
|
||
- Этап 3: 2 дня
|
||
- Этап 4: 2 дня
|
||
- Этап 5: 1 день
|
||
- Этап 6: 0.5 дня
|
||
|
||
Итого: **8.5–9.5 рабочих дней** (без учёта миграций и согласований по бизнес-правилам).
|