avm/state-corp-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add Pass 1 delta matrix for endpoint contract gaps

Browse Source
This commit is contained in:
Aleksandr Meshchriakov
2026-04-14 10:33:18 +02:00
parent ce805f9f20
commit 0ff16ffadf
1 changed files with 36 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/implementation/contract-delta-matrix.md Normal file
View File

@@ -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.