state-corp-backend/docs/backend-endpoints-implementation-plan.md

План реализации 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-документацией.

Проходы и статус выполнения

• Pass 0 — Инициация: создана отдельная ветка от dev и зафиксирован общий план в репозитории.
• Pass 1 — Discovery & контрактный каркас: подготовка сериализаторов контрактов, уточнение форматов, матрица соответствий.
• Pass 2 — Пользователи и аутентификация: доработка users/me + user-management.
• Pass 3 — Формы: выравнивание upload F-2…F-6.
• Pass 4 — Аналитика: financial-summary / economics / personnel / equipment / products / risk / forecast.
• Pass 5 — Внешние контуры: industrial/prosecutor/procurements/arbitration/corporation-memberships.
• 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 corporation-memberships/ с фильтрами 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.
  • полный прогон suite завершился успешно:
    • DJANGO_SETTINGS_MODULE=settings.test pytest -q → 463 passed (SQLite, без миграций).
    • TEST_POSTGRES_HOST=192.168.1.33 DJANGO_SETTINGS_MODULE=settings.test_postgres pytest -q → 463 passed (PostgreSQL, миграции включены).

---

Риск-оценка перед стартом

• Некоторые поля периодов требуют согласования формата валидации (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/corporation-memberships/

• Добавить модель/миграцию/serializer/viewset при отсутствии.
• Добавить фильтр по organization, presence_status и пагинацию.

Deliverable: все внешние endpoints доступны в одном стиле и с единым форматированием.

---

Этап 6. OpenAPI + документация (0.5 дня)

• Обновить api_docs/swagger_auto_schema для всех touched endpoints.
• Добавить/обновить ручные схемы ошибок.
• Убедиться, что path-tags корректны (Пользователь, Организации, Аналитика, Внешние данные, Форма F-*).

---

Чеклист проходов (обновлять после завершения)

Pass 1. Discovery & контрактный каркас

• Создать ветку для плана.
• Зафиксировать базовую версию плана в Git.
• Собрать и верифицировать список endpoint’ов и текущую реализацию в коде.
• Сопоставить требования из frontend-документов с текущими контрактами.
• Закрыть риск-реестр и уточнить спорные бизнес-правила (в рамках черновика).
• Подготовить проектные черновики контрактов для ключевых payload (users/me, upload, org fields).
• Составить матрицу изменений для всех endpoint’ов.

Текущий статус Pass 1: завершён (все артефакты собраны в docs/implementation/*).

• Переход к Pass 2.

Pass 2. Пользователи и организации

• Вынести/подтвердить контракт GET /api/v1/users/me/.
• Доработать user-management поля и обязательности.
• Довести organizations list/detail до контрактов.
• Добавить/проверить /api/v1/dictionaries/corporation-scopes/.

Pass 3. Формы

• Унифицировать upload-схемы Ф-2…Ф-6 (request).
• Унифицировать upload-ответы Ф-2…Ф-6 (response).
• Зафиксировать async/pending статус и job_id.
• Добавить общий error serializer для валидации multipart.

Pass 4. Аналитика

• Финализировать financial-summary и добавить расчёты deltas/period. (2026-04-14)
• Вынести/довести economics, personnel, equipment, products. (2026-04-14)
• Проверить/документировать risk-profile, forecast. (2026-04-14)
• Добавить dashboard фильтрацию и стабильные cluster метрики. (2026-04-14)

Pass 5. Внешние данные

• Довести внешние реестры к единообразным фильтрам/ответам. (2026-04-14)
• Добавить corporation-memberships. (2026-04-14)

Pass 6. Финализация

• Обновить OpenAPI по всем контрактам.
• Прогнать контрактные и smoke тесты.
• Проверить:
  • 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 рабочих дней (без учёта миграций и согласований по бизнес-правилам).