0101bca165
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
66 lines
6.7 KiB
Markdown
66 lines
6.7 KiB
Markdown
# Proposal: API до сводной ОСВ — пробелы по макету и комментариям фронтенда
|
||
|
||
**Срез:** доработка Срезов 4 и 3b (`../docs/context/09-delivery-plan.md`) — API пути пользователя до сводной ОСВ.
|
||
**Репозиторий:** arm-core. **Issue:** RSHB/arm-core#42. Документация — bounded-PR в docs (контракт для фронта, OQ-43,
|
||
`10-user-journey.md`, `mockup/INDEX.md`) после реализации; сквозного change нет: DBML и контракт распознавания не
|
||
меняются.
|
||
|
||
## Why
|
||
|
||
Аудит «экраны макета ↔ API» (07.10.2026) и первые комментарии фронтенд-разработчика показали, что три экрана пути
|
||
пользователя нельзя собрать без обходных цепочек вызовов:
|
||
|
||
- **[42] «Новая консолидация»** — в макете после выбора ГК и ГСК открывается блок «ЮЛ консолидации»: все неархивные ЮЛ
|
||
ГК, отмечены члены выбранной ГСК, отметки меняются, «Создать» активна при двух и более отмеченных. `POST /consolidations`
|
||
берёт периметр только из состава ГСК; обход «создать → взять в работу → `PUT …/members`» не атомарен, пишет два события
|
||
аудита и не спасает ГСК из одного ЮЛ (422 `PERIMETER_TOO_SMALL` по ГСК).
|
||
- **[34] панель «Организации»** — ячейки `members[].checklist[]` карточки версии позиционные: какая ячейка ББ, ОФР или
|
||
ОСВ 60, фронт узнаёт только из второго запроса `GET …/checklist` (`rules[]`). Колонок «Тип» и «ОСВ» (перечень счетов
|
||
загруженных ОСВ, в макете — и вне комплекта: 51, 52, 55) взять неоткуда.
|
||
|
||
## What Changes
|
||
|
||
- **`POST /consolidations`** — необязательное `legal_entity_ids` (≤ 500): без него периметр — текущие члены ГСК, как
|
||
сейчас; с ним — ровно выбранные ЮЛ ГК (422 `ENTITY_NOT_IN_GROUP`, `PERIMETER_TOO_SMALL` — по выбранным после
|
||
схлопывания дублей). ГСК остаётся обязательной и проверяется (`RELATED_GROUP_MISMATCH`), в версии не хранится.
|
||
Одна транзакция, одно событие `CONSOLIDATION_CREATE` с выбранным периметром.
|
||
- **Ячейки чек-листа самоописывающие** — `ChecklistCellOut` получает `document_type` и `account` своего правила; меняются
|
||
и карточка версии, и `GET …/checklist` (поля только добавляются; CSV не меняется).
|
||
- **Участник периметра в карточке** — `MemberOut.entity_type` (`ЮЛ`/`ИП`) и `MemberOut.osv_accounts` — счета действующих
|
||
ОСВ-документов ЮЛ за год версии с кварталом не позже квартала версии, в натуральном порядке.
|
||
|
||
Таблицы DBML v5.16 (только чтение, без изменений): `consolidation`, `consolidation_version`, `consolidation_member`,
|
||
`legal_entity`, `related_group`, `related_group_member`, `document`, `stored_file`, `required_document_rule`,
|
||
`audit_event`. Правила: `05-domain-rules.md` §9 (статусы версии), §3 п. 1 (подходящесть документа версии — не меняется).
|
||
|
||
## Решения владельца (07.10.2026)
|
||
|
||
- **П-1:** баннер «Осталось: N» и «Показать ЮЛ без ИНН» — все несопоставленные строки свода (`unmapped`,
|
||
`unmapped_total`); API не меняется, меняется описание в docs.
|
||
- **П-2:** ГСК в версии не хранится; периметр живёт в `consolidation_member`, в справочник переезжает по факту
|
||
верификации (Срез 7). Колонка «ГСК» на [34] до верификации не заполняется.
|
||
- **П-3:** допущение OQ-43 пересматривается — «К отчетности» доступна и в статусах «в работе» (только docs; API читает
|
||
свод в любом статусе).
|
||
- Фильтр файлов ЮЛ по версии не делается: drawer [39] в макете показывает все документы ЮЛ; существующий
|
||
`GET /legal-entities/{id}/files` описывается в контракте; «Проверка: Период» остаётся «—» (OQ-120).
|
||
- Колонка «ОСВ» — действующие документы за год версии до её квартала в любом статусе (вариант B).
|
||
- Ячейки чек-листа — самоописывающие, без `rules[]` в карточке (подход B).
|
||
|
||
## Non-goals
|
||
|
||
- UI (делает другой разработчик).
|
||
- Хранение ГСК версии, «Утверждён в РФ» / «Верифицирован в ГО» / «Дата верификации» (Срез 7).
|
||
- `period_check` документа относительно версии (OQ-120), фильтр файлов по версии.
|
||
- Шапка формы ОКЕИ/ОПФ/форма собственности/аудит (П-4, нужна новая версия контракта), монозаёмщики [60] (П-6),
|
||
поиск ГК по РФ (П-11), «Прочие документы» в чек-листе (П-12), единицы в экспорте (П-13).
|
||
- Изменение DBML, миграции, контракт распознавания.
|
||
|
||
## Impact
|
||
|
||
- `api/src/schemas/consolidations.py` (`ConsolidationCreate`, `ChecklistCellOut`, `MemberOut`),
|
||
`api/src/services/consolidations.py` (`create`, `set_members`, `_card`, `checklist`, `_cell_out`),
|
||
`api/src/repositories/consolidations.py` (счета ОСВ участников).
|
||
- Тесты: `test_api_consolidations.py`, `test_api_consolidation_members.py`, `test_api_consolidation_checklist.py`,
|
||
`test_schemas_consolidations.py`, `test_openapi_routes.py`.
|
||
- Фронт: новые поля только добавляются; существующие клиенты не ломаются.
|