avm/state-corp-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ce805f9f2027555f622d97f10fb38ea3eb65fcc7
state-corp-backend/docs/backend-endpoints-implementation-plan.md

14 KiB
Raw Blame History

План реализации 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 — Организации и словари: organizations, dictionaries/corporation-scopes.
  • Pass 4 — Формы загрузки: выравнивание upload F-2…F-6.
  • Pass 5 — Аналитика: financial-summary / economics / personnel / equipment / products / risk / forecast.
  • Pass 6 — Внешние контуры: industrial/prosecutor/procurements/arbitration/security registries.
  • Pass 7 — Финализация: OpenAPI + массовое тестирование + smoke.

Журнал выполненных шагов

  • Pass 0 — Инициация (2026-04-14): завершён
    • создана рабочая ветка feature/backend-endpoints-contract-implementation-plan от dev.
    • создан и закоммичен базовый план по требованиям фронта.
    • добавлены pass-стадии и статусный трекер в сам документ.

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

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

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

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

  • Создать ветку для плана.
  • Зафиксировать базовую версию плана в Git.
  • Собрать и верифицировать список endpoint’ов и текущую реализацию в коде.
  • Сопоставить требования из frontend-документов с текущими контрактами.
  • Закрыть риск-реестр и уточнить спорные бизнес-правила.
  • Подготовить проектные serializers для контрактов и ошибок.
  • Составить матрицу изменений для всех endpoint’ов.

Текущий статус Pass 1: выполняется (собран список изменений, подготовка матрицы и serializers).

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.
  • Вынести/довести economics, personnel, equipment, products.
  • Проверить/документировать risk-profile, forecast.
  • Добавить dashboard фильтрацию и стабильные cluster метрики.

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

  • Довести внешние реестры к единообразным фильтрам/ответам.
  • Добавить information-security-registry-entries.
  • Обновить OpenAPI по всем контрактам.
  • Прогнать контрактные и smoke тесты.

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

Reference in New Issue View Git Blame Copy Permalink