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