docs: add detailed backend endpoint implementation plan

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 рабочих дней** (без учёта миграций и согласований по бизнес-правилам).
+