arm-core/openspec/changes/archive/2026-10-07-front-api-gaps/proposal.md

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.
• Фронт: новые поля только добавляются; существующие клиенты не ломаются.