From bac70ad9dfd4388ace4090567eab1941dbd1a679 Mon Sep 17 00:00:00 2001 From: Aleksandr Meshchriakov Date: Tue, 14 Apr 2026 10:29:05 +0200 Subject: [PATCH] docs: add detailed backend endpoint implementation plan --- docs/backend-endpoints-implementation-plan.md | 202 ++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/backend-endpoints-implementation-plan.md diff --git a/docs/backend-endpoints-implementation-plan.md b/docs/backend-endpoints-implementation-plan.md new file mode 100644 index 0000000..2462bd7 --- /dev/null +++ b/docs/backend-endpoints-implementation-plan.md @@ -0,0 +1,202 @@ +# План реализации 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-документацией. + +--- + +## Риск-оценка перед стартом +- Некоторые поля периодов требуют согласования формата валидации (`report_period_display`/`report_half_year`). +- Для `/information-security-registry-entries/` в кодовой базе нет модели и данных — потребуется новая модель/миграция или адаптер. +- Отдельное решение по async upload: при каком пороге или условиях всегда возвращать `queued`. +- Нужно подтвердить, где `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-*`). + +--- + +## Этап 7. Финальная валидация и релиз-критерии (0.5 дня) +- Прогнать: + - `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` +- Добавить новые контрактные тесты в отдельный набор (если будет слишком много — отдельный файл). +- 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 дня +- Этап 7: 0.5 дня + +Итого: **8.5–9.5 рабочих дней** (без учёта миграций и согласований по бизнес-правилам). +