From 0ff16ffadf56a936a8b3480371efeca32204b439 Mon Sep 17 00:00:00 2001 From: Aleksandr Meshchriakov Date: Tue, 14 Apr 2026 10:33:18 +0200 Subject: [PATCH] docs: add Pass 1 delta matrix for endpoint contract gaps --- docs/implementation/contract-delta-matrix.md | 36 ++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/implementation/contract-delta-matrix.md diff --git a/docs/implementation/contract-delta-matrix.md b/docs/implementation/contract-delta-matrix.md new file mode 100644 index 0000000..a53789e --- /dev/null +++ b/docs/implementation/contract-delta-matrix.md @@ -0,0 +1,36 @@ +# Матрица изменений контрактов (первичный черновик) + +| Pass | Endpoint | Текущий статус | Разрыв | Режим | Что меняем | +|---|---|---|---|---|---| +| 1 | GET /api/v1/users/me/ | Есть | Полный/неполный профайл | API | Проверить и зафиксировать `role`, `role_label`, `capabilities.can_access_admin_page`, `profile.middle_name` | +| 2/3 | GET /api/v1/organizations/ | Есть | Часть полей/labels/filters | API | Проверить `short_name`, `full_name`, корп/тип + label, kpp/okpo, фильтры `corporation_scope`, `organization_type` | +| 2/3 | GET /api/v1/organizations/{id}/ | Есть | Детализация поля для карточки | API | Довести поля `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/ | Нет | Отсутствует endpoint | NEW | Добавить read-only endpoint + сортировка | +| 3 | POST /api/v1/forms/f2/upload/ | Есть | Не тот request/response контракт | NEW-CONTRACT | Добавить обязательные поля периода, единую обёртку ответа, единый error response | +| 3 | POST /api/v1/forms/f3/upload/ | Есть | Не тот request/response контракт | NEW-CONTRACT | То же | +| 3 | POST /api/v1/forms/f4/upload/ | Есть | Не тот request/response контракт | NEW-CONTRACT | Переход на `report_half_year`, единая обёртка | +| 3 | POST /api/v1/forms/f5/upload/ | Есть | Не тот request/response контракт | NEW-CONTRACT | Единая обёртка и валидация | +| 3 | POST /api/v1/forms/f6/upload/ | Есть | Не тот request/response контракт | NEW-CONTRACT | Единая обёртка и валидация | +| 4 | GET /api/v1/organizations/{id}/analytics/financial-summary/ | Есть | Частичная проверка period/дельт | API | Закрыть гарантии наличия `taxes_paid`, `insurance_contributions`, `report_period` | +| 4 | GET /api/v1/organizations/{id}/analytics/economics/ | Есть | Проверка структуры `series`/`ratios`/`periods` | API | Зафиксировать выходной schema по docs | +| 4 | GET /api/v1/organizations/{id}/analytics/personnel/ | Есть | Проверка `age_distribution`, `history` | API | Проверить schema для history_years + headcount блок | +| 4 | GET /api/v1/organizations/{id}/analytics/equipment/ | Есть | Проверка summary+age+categories | API | Сверить contract fields и единицы | +| 4 | GET /api/v1/organizations/{id}/analytics/products/ | Есть | Проверить `frequency`, `price_mode`, series | API | Сверить shape +| 4 | GET /api/v1/organizations/{id}/analytics/forecast/ | Есть | Может отличаться by docs | API | Проверить сценарии/horizon/поля риска | +| 4 | GET /api/v1/analytics/dashboard/ | Есть | Может отсутствовать часть статистик | API | Проверить поля dashboard metrics | +| 5 | GET /api/v1/industrial-products/ | Есть | Частичная валидация/filters | API | Проверить `product_class`, `search`, пагинация | +| 5 | GET /api/v1/prosecutor-checks/ | Есть | Проверить filters | API | Проверить `law_type`, дата-диапазон | +| 5 | GET /api/v1/public-procurements/ | Есть | Проверить filters | API | Проверить `law_type`, дата-диапазон | +| 5 | GET /api/v1/arbitration-cases/ | Есть | Проверить filters | API | Проверить `party_role`, дата-диапазон | +| 5 | GET /api/v1/information-security-registry-entries/ | Нет | Отсутствует endpoint | NEW | Добавить сущность/endpoint/фильтр | +| 6 | OpenAPI | Частично | Недостаточная детализация multipart/error | DOC | Обновить документацию для всех touched endpoints | + +## Риск-реестр (Pass 1) + +1) Неоднозначный формат периодов: `f3/f5/f6` период в данных может считаться квартальным; нужно зафиксировать годовой/квартальный контракт. +2) `users/me` источник `first_name/middle_name/last_name` берётся из профиля: важно зафиксировать `null` vs `""`. +3) `corporation_scope` в организациях сейчас выдаётся как список (множественные реестровые принадлежности); требуется согласовать с фронтом (массив vs scalar). +4) Для новых upload ответов пока нет согласованного mapping `upload_id` к факту (`batch_id`/`task_id`) — выбрать единый источник. + +## Примечание +- Матрица — рабочая. После согласования может перейти в `contracts/CHANGELOG.md` как часть ADR.