# API до сводной ОСВ: пробелы по макету и комментариям фронтенда — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** экран [42] создаёт консолидацию одним запросом с выбранным периметром, экран [34] строится из одной карточки
версии (подписанные ячейки чек-листа, тип ЮЛ, счета ОСВ), контракт для фронта описывает всё, что фронт использует.

**Architecture:** только расширение существующих схем и сервиса консолидаций arm-core (`ConsolidationCreate`,
`ChecklistCellOut`, `MemberOut`, `services/consolidations.py`) и один новый запрос репозитория; миграций и DBML нет.
Документы — отдельный bounded-PR в arm-ka-docs.

**Tech Stack:** Python 3.11, FastAPI, pydantic v2, SQLAlchemy 2 async, PostgreSQL 16, pytest-asyncio; `make` из корня
arm-core.

**Spec:** `openspec/changes/front-api-gaps/` (proposal, design D-1…D-4 и «Decisions made without discussion» №1–8,
`specs/consolidations-api/spec.md`). Issue — RSHB/arm-core#42.

## Global Constraints

- Рабочая копия: `/Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/arm-core`, ветка `feat/42-front-api-gaps`. Никаких
  `cd` в основные checkout'ы (`/Users/andrey.epifancev/projects/awp-ca/{arm-core,docs}`): хук guard-main блокирует запись,
  когда cwd — репозиторий на `main`.
- Команды — из корня arm-core: `make check` (ruff + mypy + unit), `make test-integration` (нужен compose: PostgreSQL/NATS
  уже подняты — `docker ps` показывает `arm-ka-postgres-1`, `arm-ka-nats-1`, `arm-ka-minio-1`). Точечный прогон —
  `cd api && .venv/bin/pytest <путь>::<тест> -v` (venv создаётся `make venv`, если `api/.venv` нет).
- DBML, миграции, контракт распознавания (`api/contracts/`) — **не менять**.
- Ответы API только расширяются; запрос `POST /consolidations` без `legal_entity_ids` ведёт себя как прежде.
- Значения `entity_type` — `"ЮЛ"` / `"ИП"` (enum `EntityType`, как в DBML).
- Сортировка счетов — только `src.domain.osv_mapping.account_sort_key` (одно определение порядка счетов).
- Язык комментариев, docstring и коммитов — русский; идентификаторы — английские. Docstring ссылается на спеку/design.
- Каждый коммит заканчивается строками:
  ```
  Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
  Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
  ```
- Сообщения коммитов — `feat(consolidations): …`, `test(consolidations): …`, `docs: …` по-русски.

## Review Focus

- **Пустой список `legal_entity_ids: []`** — это явный периметр из нуля ЮЛ, а не «поле не передано»: ожидается 422
  `PERIMETER_TOO_SMALL`, а не периметр из ГСК. Тест — Task 1, `test_create_with_empty_selected_perimeter_is_too_small`.
- **Несуществующий `uuid` в `legal_entity_ids`** — ожидается 422 `ENTITY_NOT_IN_GROUP` с этим `uuid` в перечне (не 404
  и не 500). Тест — Task 1, `test_create_with_unknown_entity_is_not_in_group`.
- **Неверная ГСК при явном списке** — проверка ГСК раньше периметра: 422 `RELATED_GROUP_MISMATCH`, даже если список
  тоже неверный. Тест — Task 1, `test_create_gsk_mismatch_reported_before_perimeter`.
- **Один счёт в нескольких кварталах** — в `osv_accounts` один раз. Тест — Task 3, в
  `test_card_member_osv_accounts_loaded_to_version_period` (ОСВ 60 за Q1 и Q2).
- **Версия за Q1** — документы Q2+ того же года в `osv_accounts` не попадают. Тест — Task 3,
  `test_card_member_osv_accounts_q1_version_ignores_later_quarters`.

---

## File Structure

| Файл | Что меняется |
|---|---|
| `api/src/schemas/consolidations.py` | `ConsolidationCreate.legal_entity_ids`; `ChecklistCellOut.document_type/account`; `MemberOut.entity_type/osv_accounts` |
| `api/src/services/consolidations.py` | `_validate_perimeter` (общая для `create` и `set_members`); `create`/`_insert` по списку `uuid`; `_cell_out(rule, cell)`; `_card` — новые поля участника |
| `api/src/repositories/consolidations.py` | новая `osv_accounts(...)` |
| `api/tests/test_api_consolidations.py` | тесты создания с периметром, карточки (тип ЮЛ, счета ОСВ) |
| `api/tests/test_api_consolidation_checklist.py` | ячейки с `document_type`/`account` |
| `api/tests/test_schemas_consolidations.py`, `api/tests/test_domain_checklist_csv.py` | конструкторы ячеек, граница `legal_entity_ids` |
| `api/tests/test_openapi_routes.py` | новые поля в схеме OpenAPI |
| `README.md`, `CLAUDE.md`, `openspec/changes/front-api-gaps/tasks.md` | описание (Task 5) |
| docs: `dev/api-contract-files-directories.md` (новый), `dev/api-contract-slice-4.md`, `context/07-open-questions.md`, `context/10-user-journey.md`, `mockup/INDEX.md` | Task 4, отдельный worktree и PR |

---

### Task 1: Создание консолидации с выбранным периметром

**Files:**
- Modify: `api/src/schemas/consolidations.py` (класс `ConsolidationCreate`, ~стр. 44)
- Modify: `api/src/services/consolidations.py` (`create` ~стр. 89–131, `set_members` ~стр. 237–258, `_insert` ~стр. 294–341)
- Test: `api/tests/test_api_consolidations.py`, `api/tests/test_schemas_consolidations.py`, `api/tests/test_openapi_routes.py`

**Interfaces:**
- Consumes: `repo.entities_in_group(session, group_id, entity_ids) -> set[uuid.UUID]` (есть),
  `directories_repo.current_members(session, related_group_id)` (есть), `MIN_PERIMETER = 2`, `MAX_MEMBERS = 500`.
- Produces: `ConsolidationCreate.legal_entity_ids: list[uuid.UUID] | None`;
  `ConsolidationService._validate_perimeter(self, company_group_id: uuid.UUID, entity_ids: Sequence[uuid.UUID]) -> list[uuid.UUID]`;
  `ConsolidationService._insert(self, group_id: uuid.UUID, data: ConsolidationCreate, entity_ids: list[uuid.UUID]) -> tuple[Consolidation, ConsolidationVersion]`.
  Класс сервиса — `ConsolidationService`.

- [ ] **Step 1: Тест схемы — граница и значение по умолчанию**

В `api/tests/test_schemas_consolidations.py` после `test_consolidation_create_year_bounds` добавить:

```python
def test_consolidation_create_selected_perimeter_bounds() -> None:
    """D-1: `legal_entity_ids` необязателен (`None` — периметр из ГСК), не больше `MAX_MEMBERS`."""
    ids = {"company_group_id": uuid.uuid4(), "related_group_id": uuid.uuid4(), "year": 2024, "quarter": "Q3"}
    assert ConsolidationCreate(**ids).legal_entity_ids is None
    selected = [uuid.uuid4() for _ in range(MAX_MEMBERS)]
    assert len(ConsolidationCreate(**ids, legal_entity_ids=selected).legal_entity_ids or []) == MAX_MEMBERS
    with pytest.raises(ValidationError):
        ConsolidationCreate(**ids, legal_entity_ids=[*selected, uuid.uuid4()])
```

- [ ] **Step 2: Интеграционные тесты API**

В `api/tests/test_api_consolidations.py`: в импорт `from src.models.directories import …` добавить `RelatedGroupMember`;
`from collections.abc import Sequence` — в стандартные импорты. После `_body` добавить помощник и после
`test_create_ignores_closed_memberships` — тесты:

```python
def _with_ids(body: dict[str, Any], ids: Sequence[uuid.UUID | str]) -> dict[str, Any]:
    """Тело создания с явным периметром (модалка [42], design D-1)."""
    return {**body, "legal_entity_ids": [str(entity_id) for entity_id in ids]}


async def _gsk_members(session: AsyncSession, gsk: RelatedGroup) -> set[uuid.UUID]:
    stmt = select(RelatedGroupMember.legal_entity_id).where(
        RelatedGroupMember.related_group_id == gsk.id, RelatedGroupMember.is_current.is_(True)
    )
    return set((await session.execute(stmt)).scalars())


@pytest.mark.integration
async def test_create_with_selected_perimeter_wider_than_gsk(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """Выбранный периметр шире ГСК: ровно эти ЮЛ, одно событие создания, состав ГСК не меняется."""
    group, gsk, entities = await _scenario(seeded)
    outsider = await make_legal_entity(seeded, name="ООО Вне ГСК", group=group)
    selected = [*entities, outsider]
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [e.id for e in selected]))

    assert response.status_code == HTTP_CREATED, response.text
    assert {member["id"] for member in response.json()["members"]} == {str(e.id) for e in selected}
    event = (
        await seeded.execute(select(AuditEvent).where(AuditEvent.action == AuditAction.CONSOLIDATION_CREATE))
    ).scalar_one()
    assert event.after_value["members"] == sorted(str(e.id) for e in selected)
    membership = select(func.count()).select_from(AuditEvent).where(AuditEvent.action == AuditAction.MEMBERSHIP_CHANGE)
    assert (await seeded.execute(membership)).scalar_one() == 0
    assert await _gsk_members(seeded, gsk) == {e.id for e in entities}
    assert await _count(seeded, ConsolidationLock) == 0


@pytest.mark.integration
async def test_create_gsk_of_one_with_second_entity_selected(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """ГСК из одного ЮЛ, второе отмечено вручную — периметр из двух (проверка размера — по выбранным)."""
    group, gsk, (single,) = await _scenario(seeded, members=1)
    second = await make_legal_entity(seeded, name="ООО Второе", group=group)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [single.id, second.id]))

    assert response.status_code == HTTP_CREATED, response.text
    assert {member["id"] for member in response.json()["members"]} == {str(single.id), str(second.id)}


@pytest.mark.integration
async def test_create_with_entity_of_other_group_is_rejected(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    group, gsk, entities = await _scenario(seeded)
    other_group = await make_company_group(seeded, name="ГК Соседняя", office=await _office(seeded, ROSTOV))
    stranger = await make_legal_entity(seeded, name="ООО Чужое", group=other_group)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [*[e.id for e in entities], stranger.id]))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    detail = response.json()["detail"]
    assert detail["code"] == "ENTITY_NOT_IN_GROUP"
    assert detail["legal_entity_ids"] == [str(stranger.id)]
    assert await _count(seeded, Consolidation) == 0


@pytest.mark.integration
async def test_create_with_unknown_entity_is_not_in_group(auth_client: AuthClientFactory, seeded: AsyncSession) -> None:
    group, gsk, entities = await _scenario(seeded)
    ghost = uuid.uuid4()
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [*[e.id for e in entities], ghost]))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    assert response.json()["detail"]["code"] == "ENTITY_NOT_IN_GROUP"
    assert response.json()["detail"]["legal_entity_ids"] == [str(ghost)]


@pytest.mark.integration
async def test_create_with_duplicates_collapsing_to_one_is_too_small(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    group, gsk, entities = await _scenario(seeded)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [entities[0].id, entities[0].id]))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    assert response.json()["detail"]["code"] == "PERIMETER_TOO_SMALL"
    assert await _count(seeded, Consolidation) == 0


@pytest.mark.integration
async def test_create_with_empty_selected_perimeter_is_too_small(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """Review Focus: `[]` — явный пустой периметр, а не «поле не передано» (ГСК из двух не подставляется)."""
    group, gsk, _ = await _scenario(seeded)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), []))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    assert response.json()["detail"]["code"] == "PERIMETER_TOO_SMALL"


@pytest.mark.integration
async def test_create_with_null_selected_perimeter_takes_gsk(auth_client: AuthClientFactory, seeded: AsyncSession) -> None:
    """Решение №3: `legal_entity_ids: null` равнозначно отсутствию поля."""
    group, gsk, entities = await _scenario(seeded)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json={**_body(group, gsk), "legal_entity_ids": None})

    assert response.status_code == HTTP_CREATED, response.text
    assert {member["id"] for member in response.json()["members"]} == {str(e.id) for e in entities}


@pytest.mark.integration
async def test_create_gsk_mismatch_reported_before_perimeter(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """Порядок проверок (решение №5): ГСК раньше периметра."""
    group, _, _ = await _scenario(seeded)
    gsz = await make_related_group(seeded, group=group, kind=RelatedGroupKind.gsz, name="ГСЗ")
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsz), [uuid.uuid4()]))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    assert response.json()["detail"]["code"] == "RELATED_GROUP_MISMATCH"


@pytest.mark.integration
async def test_create_selected_perimeter_longer_than_limit(auth_client: AuthClientFactory, seeded: AsyncSession) -> None:
    group, gsk, _ = await _scenario(seeded)
    client = await auth_client(KA_RF)

    response = await client.post(CONSOLIDATIONS, json=_with_ids(_body(group, gsk), [uuid.uuid4() for _ in range(501)]))

    assert response.status_code == HTTP_UNPROCESSABLE, response.text
    assert response.json()["detail"][0]["loc"] == ["body", "legal_entity_ids"]
    assert await _count(seeded, Consolidation) == 0
```

Если `make_related_group` не принимает `kind=` — посмотреть `test_create_gsk_must_belong_to_group_and_be_gsk` (там тот
же вызов `make_related_group(seeded, group=group, kind=RelatedGroupKind.gsz, name="ГСЗ")`). Если поле членства ГСК в
модели называется не `is_current` — взять фактическое имя из `api/src/models/directories.py` (`class RelatedGroupMember`).
Строки длиннее 120 символов разбить, как требует ruff (`make lint` подскажет).

- [ ] **Step 3: Тест OpenAPI**

В `api/tests/test_openapi_routes.py` в конец файла:

```python
def test_consolidation_create_has_optional_selected_perimeter(schema: dict[str, Any]) -> None:
    """front-api-gaps D-1: `legal_entity_ids` в теле создания — необязательный массив."""
    create = schema["components"]["schemas"]["ConsolidationCreate"]
    assert "legal_entity_ids" in create["properties"]
    assert "legal_entity_ids" not in create.get("required", [])
```

- [ ] **Step 4: Запустить — тесты падают**

Run: `cd api && .venv/bin/pytest tests/test_schemas_consolidations.py::test_consolidation_create_selected_perimeter_bounds tests/test_openapi_routes.py::test_consolidation_create_has_optional_selected_perimeter -v && .venv/bin/pytest -m integration tests/test_api_consolidations.py -k "selected or other_group or unknown_entity or duplicates_collapsing or gsk_of_one or mismatch_reported" -v`
Expected: FAIL — `ConsolidationCreate` не знает `legal_entity_ids` (pydantic игнорирует лишнее поле: `legal_entity_ids is None` в теле с 500 id → `AttributeError`/assert; API создаёт периметр из ГСК).

- [ ] **Step 5: Схема**

`api/src/schemas/consolidations.py`, класс `ConsolidationCreate`:

```python
class ConsolidationCreate(BaseModel):
    """Тело `POST /consolidations`: ГК, ГСК, период и необязательный выбранный периметр (модалка [42], design D-1).

    `legal_entity_ids` нет или `null` — периметр из текущих членов ГСК; список — ровно эти ЮЛ ГК (дубли схлопывает сервис).
    """

    company_group_id: uuid.UUID
    related_group_id: uuid.UUID
    year: int = Field(ge=YEAR_MIN, le=YEAR_MAX)
    quarter: PeriodQuarter
    legal_entity_ids: list[uuid.UUID] | None = Field(default=None, max_length=MAX_MEMBERS)
```

`MAX_MEMBERS` объявлен выше в том же модуле (стр. ~31) — проверить, что объявление стоит до класса.

- [ ] **Step 6: Сервис — общая проверка периметра**

В `api/src/services/consolidations.py`: в импорты `from collections.abc import Sequence` (если нет). В класс сервиса
(рядом с `_insert`) добавить:

```python
    async def _validate_perimeter(
        self, company_group_id: uuid.UUID, entity_ids: Sequence[uuid.UUID]
    ) -> list[uuid.UUID]:
        """Периметр консолидации — одно правило для создания и `PUT …/members` (design D-1): дубли схлопываются в порядке
        первого вхождения → все ЮЛ существуют и принадлежат ГК (422 `ENTITY_NOT_IN_GROUP`, `legal_entity_ids` — чужие в
        порядке запроса) → не меньше двух (422 `PERIMETER_TOO_SMALL`)."""
        requested = list(dict.fromkeys(entity_ids))
        valid = await repo.entities_in_group(self._session, company_group_id, requested)
        foreign = [entity_id for entity_id in requested if entity_id not in valid]
        if foreign:
            raise DomainValidationError(
                "ENTITY_NOT_IN_GROUP", "ЮЛ не принадлежат ГК консолидации", legal_entity_ids=foreign
            )
        if len(requested) < MIN_PERIMETER:
            raise DomainValidationError(
                "PERIMETER_TOO_SMALL", f"В периметре должно быть не меньше {MIN_PERIMETER} ЮЛ, сейчас {len(requested)}"
            )
        return requested
```

В `set_members` заменить блок от `requested = list(dict.fromkeys(data.legal_entity_ids))` до конца проверки
`PERIMETER_TOO_SMALL` одной строкой:

```python
        requested = await self._validate_perimeter(consolidation.company_group_id, data.legal_entity_ids)
```

- [ ] **Step 7: Сервис — создание по списку**

В `create` заменить строки от `entities = [entity for _, entity in await directories_repo.current_members(...)]` до конца
проверки `PERIMETER_TOO_SMALL` (по ГСК):

```python
        if data.legal_entity_ids is None:
            entity_ids = [entity.id for _, entity in await directories_repo.current_members(self._session, related.id)]
            if len(entity_ids) < MIN_PERIMETER:
                raise DomainValidationError(
                    "PERIMETER_TOO_SMALL", f"В ГСК должно быть не меньше {MIN_PERIMETER} ЮЛ, сейчас {len(entity_ids)}"
                )
        else:
            entity_ids = await self._validate_perimeter(group.id, data.legal_entity_ids)
```

Далее в `create`: `consolidation, version = await self._insert(group.id, data, entity_ids)` и в аудите
`"members": sorted(entity_ids),`. Обновить docstring `create`: «Проверки по порядку: ГК видима (404) → ГСК видима (404),
принадлежит ГК и `kind = gsk` (422 `RELATED_GROUP_MISMATCH`) → периметр: без `legal_entity_ids` — члены ГСК, не меньше
двух; со списком — `_validate_perimeter` (422 `ENTITY_NOT_IN_GROUP` / `PERIMETER_TOO_SMALL`) → периода ещё нет (409 …)».
Модульный docstring: «Периметр версии при создании — текущие члены ГСК или выбранные ЮЛ ГК (`legal_entity_ids`,
front-api-gaps D-1), `is_head_entity = false`; …».

В `_insert`: параметр `entities: list[LegalEntity]` → `entity_ids: list[uuid.UUID]`;
`ConsolidationMember(..., legal_entity_id=entity_id, ...) for entity_id in entity_ids`;
`bind_confirmed(..., entity_ids=entity_ids)`. Если `LegalEntity` больше нигде в модуле не используется — убрать импорт
(ruff `F401` подскажет; он нужен `_checklist_cells` — тогда оставить).

- [ ] **Step 8: Запустить — тесты проходят, прежние не сломаны**

Run: `cd api && .venv/bin/pytest tests/test_schemas_consolidations.py tests/test_openapi_routes.py -v && .venv/bin/pytest -m integration tests/test_api_consolidations.py tests/test_api_consolidation_members.py -v`
Expected: PASS (все, включая `test_create_with_single_member_is_perimeter_too_small`,
`test_foreign_entity_is_reported_before_size`, `test_duplicates_are_collapsed`).

- [ ] **Step 9: Линтеры**

Run: `make lint`
Expected: без ошибок.

- [ ] **Step 10: Коммит**

```bash
git add api/src/schemas/consolidations.py api/src/services/consolidations.py api/tests/test_api_consolidations.py api/tests/test_schemas_consolidations.py api/tests/test_openapi_routes.py
git commit -m "feat(consolidations): создание с выбранным периметром legal_entity_ids, общая проверка периметра (#42)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
```

---

### Task 2: Самоописывающие ячейки чек-листа

**Files:**
- Modify: `api/src/schemas/consolidations.py` (`ChecklistCellOut`, ~стр. 95)
- Modify: `api/src/services/consolidations.py` (`checklist` ~стр. 169, `_cell_out` ~стр. 231, `_card` ~стр. 358)
- Test: `api/tests/test_api_consolidation_checklist.py`, `api/tests/test_schemas_consolidations.py`,
  `api/tests/test_domain_checklist_csv.py`, `api/tests/test_openapi_routes.py`

**Interfaces:**
- Consumes: `checklist_domain.Rule(document_type, account, is_mandatory)`, `checklist_domain.Cell(status, missing_quarters, document_ids)`,
  `_checklist_cells(...) -> tuple[list[Rule], list[tuple[LegalEntity, list[Cell]]]]` (есть).
- Produces: `ChecklistCellOut(document_type: DocumentType, account: str | None, status, missing_quarters, document_ids)`;
  `ConsolidationService._cell_out(rule: checklist_domain.Rule, cell: checklist_domain.Cell) -> ChecklistCellOut`.
  Task 3 меняет `_card` рядом — после Task 2 в `_card` есть переменная `rules`.

- [ ] **Step 1: Обновить существующие ожидания и добавить тест карточки**

`api/tests/test_api_consolidation_checklist.py`:

```python
    assert cells[OSV_60] == {
        "document_type": "OSV",
        "account": "60",
        "status": "CONFIRMED",
        "missing_quarters": [],
        "document_ids": [str(i) for i in documents],
    }
    assert cells[OSV_90] == {
        "document_type": "OSV",
        "account": "90",
        "status": "MISSING",
        "missing_quarters": [],
        "document_ids": [],
    }
```

(в `test_checklist_osv_60_confirmed_osv_90_missing`), и в `test_checklist_gap_needs_check_and_processing`:

```python
    assert first_cells[OSV_60] == {
        "document_type": "OSV",
        "account": "60",
        "status": "MISSING",
        "missing_quarters": ["Q2"],
        "document_ids": [str(first_q1), str(third_q3)],
    }
```

После `test_card_members_have_same_cells_as_checklist` добавить:

```python
@pytest.mark.integration
async def test_card_cells_are_self_describing(auth_client: AuthClientFactory, seeded: AsyncSession) -> None:
    """front-api-gaps D-2: ячейка несёт правило — фронт не сопоставляет ячейки с `rules` по индексу."""
    version, _ = await _bound_world(seeded)
    client = await auth_client(KA_RF)

    checklist = (await client.get(f"/consolidations/versions/{version.id}/checklist")).json()
    card = (await client.get(f"/consolidations/versions/{version.id}")).json()

    expected = [(rule["document_type"], rule["account"]) for rule in checklist["rules"]]
    assert expected == EXPECTED_RULES
    for member in card["members"]:
        assert [(cell["document_type"], cell["account"]) for cell in member["checklist"]] == expected
    for row in checklist["rows"]:
        assert [(cell["document_type"], cell["account"]) for cell in row["cells"]] == expected
    balance = next(cell for cell in card["members"][0]["checklist"] if cell["document_type"] == "BALANCE")
    assert balance["account"] is None
```

`api/tests/test_schemas_consolidations.py`, `test_checklist_cell_status_is_the_domain_enum` — конструкторы:

```python
        cell = ChecklistCellOut(
            document_type=DocumentType.OSV, account="60", status=status.value, missing_quarters=[], document_ids=[]  # type: ignore[arg-type]
        )
    ...
        ChecklistCellOut(
            document_type=DocumentType.OSV, account="60", status="UNKNOWN", missing_quarters=[], document_ids=[]  # type: ignore[arg-type]
        )
```

и импорт `DocumentType` в `from src.models.enums import …`. Добавить тест:

```python
def test_checklist_cell_requires_its_rule() -> None:
    """D-2: `document_type` обязателен, `account` — обязателен, но может быть `None` (ББ/ОФР)."""
    with pytest.raises(ValidationError):
        ChecklistCellOut(status=CellStatus.MISSING, missing_quarters=[], document_ids=[])  # type: ignore[call-arg]
    cell = ChecklistCellOut(
        document_type=DocumentType.BALANCE, account=None, status=CellStatus.MISSING, missing_quarters=[], document_ids=[]
    )
    assert cell.account is None
```

`api/tests/test_domain_checklist_csv.py` — в `test_render` ячейки:

```python
                    ChecklistCellOut(
                        document_type=DocumentType.BALANCE,
                        account=None,
                        status=CellStatus.CONFIRMED,
                        missing_quarters=[],
                        document_ids=[],
                    ),
                    ChecklistCellOut(
                        document_type=DocumentType.OSV,
                        account="60",
                        status=CellStatus.MISSING,
                        missing_quarters=[PeriodQuarter.Q2],
                        document_ids=[],
                    ),
```

и помощник `_cell`:

```python
def _cell(status: CellStatus, *quarters: PeriodQuarter) -> ChecklistCellOut:
    return ChecklistCellOut(
        document_type=DocumentType.OSV, account="60", status=status, missing_quarters=list(quarters), document_ids=[]
    )
```

`api/tests/test_openapi_routes.py` — в конец:

```python
def test_checklist_cell_declares_its_rule(schema: dict[str, Any]) -> None:
    """front-api-gaps D-2: ячейка чек-листа самоописывающая."""
    cell = schema["components"]["schemas"]["ChecklistCellOut"]
    assert {"document_type", "account", "status", "missing_quarters", "document_ids"} <= set(cell["required"])
```

- [ ] **Step 2: Запустить — падают**

Run: `cd api && .venv/bin/pytest tests/test_schemas_consolidations.py tests/test_domain_checklist_csv.py tests/test_openapi_routes.py -v; .venv/bin/pytest -m integration tests/test_api_consolidation_checklist.py -v`
Expected: FAIL — `ChecklistCellOut` не принимает/не отдаёт `document_type`, `account`.

- [ ] **Step 3: Схема ячейки**

```python
class ChecklistCellOut(BaseModel):
    """Ячейка чек-листа — самоописывающая (front-api-gaps D-2): правило ячейки (`document_type`, `account` — счёт ОСВ,
    `None` у ББ/ОФР), статус пары (ЮЛ, правило), недостающие кварталы ОСВ и привязанные документы."""

    document_type: DocumentType
    account: str | None
    status: CellStatus  # единственное определение — `domain.checklist.CellStatus` (T2.8)
    missing_quarters: list[PeriodQuarter]
    document_ids: list[uuid.UUID]
```

- [ ] **Step 4: Сервис**

`_cell_out`:

```python
    @staticmethod
    def _cell_out(rule: checklist_domain.Rule, cell: checklist_domain.Cell) -> ChecklistCellOut:
        """Ячейка ответа с правилом (D-2); `rule` — правило того же столбца, что и `cell`."""
        return ChecklistCellOut(
            document_type=rule.document_type,
            account=rule.account,
            status=cell.status,
            missing_quarters=list(cell.missing_quarters),
            document_ids=list(cell.document_ids),
        )
```

В `checklist`: `cells=[self._cell_out(rule, cell) for rule, cell in zip(rules, cells, strict=True)],`.
В `_card`: `rules, cells = await self._checklist_cells(...)` (вместо `_, cells = …`) и в `MemberOut(...)`:
`checklist=[self._cell_out(rule, cell) for rule, cell in zip(rules, cells[position][1], strict=True)],`.

- [ ] **Step 5: Запустить — проходят**

Run: `cd api && .venv/bin/pytest tests/test_schemas_consolidations.py tests/test_domain_checklist_csv.py tests/test_openapi_routes.py -v && .venv/bin/pytest -m integration tests/test_api_consolidation_checklist.py tests/test_api_consolidations.py tests/test_api_consolidation_members.py -v`
Expected: PASS; CSV-тесты (`test_checklist_csv_*`) проходят без изменения ожидаемого текста.

- [ ] **Step 6: Линтеры и коммит**

Run: `make lint` → без ошибок.

```bash
git add api/src/schemas/consolidations.py api/src/services/consolidations.py api/tests/test_api_consolidation_checklist.py api/tests/test_schemas_consolidations.py api/tests/test_domain_checklist_csv.py api/tests/test_openapi_routes.py
git commit -m "feat(consolidations): ячейки чек-листа с document_type и account своего правила (#42)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
```

---

### Task 3: Участник периметра — тип ЮЛ и счета ОСВ

**Files:**
- Modify: `api/src/repositories/consolidations.py` (новая функция после `unconfirmed_documents`, ~стр. 351)
- Modify: `api/src/schemas/consolidations.py` (`MemberOut`, импорт `EntityType`)
- Modify: `api/src/services/consolidations.py` (`_card`; импорт `quarters_through`)
- Test: `api/tests/test_api_consolidations.py`, `api/tests/test_openapi_routes.py`

**Interfaces:**
- Consumes: `account_sort_key(code: str)` из `src.domain.osv_mapping`; `quarters_through(quarter: PeriodQuarter) -> tuple[PeriodQuarter, ...]`
  из `src.domain.consolidation_periods`; после Task 2 в `_card` есть `rules, cells`.
- Produces: `repo.osv_accounts(session: AsyncSession, entity_ids: Collection[uuid.UUID], year: int, quarters: Collection[PeriodQuarter]) -> dict[uuid.UUID, list[str]]`;
  `MemberOut.entity_type: EntityType`, `MemberOut.osv_accounts: list[str]`.

- [ ] **Step 1: Интеграционные тесты карточки**

В `api/tests/test_api_consolidations.py` в импорты фабрик добавить `make_document`, `make_stored_file`; в импорт enums —
`DocumentStatus`, `EntityType`, `FileStatus`, `RecognitionStatus`. Добавить в конец файла:

```python
async def _osv(  # noqa: PLR0913 - параметры документа сценария
    session: AsyncSession,
    entity: LegalEntity,
    account: str,
    year: int,
    quarter: PeriodQuarter,
    *,
    status: DocumentStatus = DocumentStatus.RECOGNIZED,
    file_status: FileStatus = FileStatus.PROCESSED,
) -> None:
    """ОСВ-документ ЮЛ в отдельном файле (на файл — одна ОСВ по счёту)."""
    file, job = await make_stored_file(session, entity=entity, status=file_status, job_status=RecognitionStatus.done)
    await make_document(session, file=file, job=job, account=account, year=year, quarter=quarter, status=status)


async def _card_world(
    session: AsyncSession, quarter: PeriodQuarter = PeriodQuarter.Q3
) -> tuple[ConsolidationVersion, LegalEntity, LegalEntity]:
    """Версия 2024 `quarter` ГК Ростовского филиала: ЮЛ «ООО А» и ИП «ИП Б»."""
    group = await make_company_group(session, name="ГК Карточка", office=await _office(session, ROSTOV))
    company = await make_legal_entity(session, name="ООО А", group=group)
    person = await make_legal_entity(
        session, name="ИП Б", group=group, entity_type=EntityType.ИП, inn="770100000012"
    )
    _, version = await make_consolidation(
        session, group=group, year=2024, quarter=quarter, members=[company, person], initiator=await _user(session, KA_RF)
    )
    return version, company, person


@pytest.mark.integration
async def test_card_member_entity_type(auth_client: AuthClientFactory, seeded: AsyncSession) -> None:
    version, company, person = await _card_world(seeded)
    client = await auth_client(KA_RF)

    card = (await client.get(f"{VERSIONS}/{version.id}")).json()

    types = {member["id"]: member["entity_type"] for member in card["members"]}
    assert types == {str(company.id): "ЮЛ", str(person.id): "ИП"}


@pytest.mark.integration
async def test_card_member_osv_accounts_loaded_to_version_period(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """D-3 (вариант B): счета действующих ОСВ за год версии с кварталом ≤ версии, в любом статусе, кроме ERROR."""
    version, company, person = await _card_world(seeded)
    q1, q2, q3, q4 = PeriodQuarter.Q1, PeriodQuarter.Q2, PeriodQuarter.Q3, PeriodQuarter.Q4
    await _osv(seeded, company, "60", 2024, q1)  # RECOGNIZED
    await _osv(seeded, company, "60", 2024, q2)  # тот же счёт ещё раз — один раз в списке
    await _osv(seeded, company, "51", 2024, q3, status=DocumentStatus.CONFIRMED)
    await _osv(seeded, company, "58.03", 2024, q3, status=DocumentStatus.NEEDS_CHECK)
    await _osv(seeded, company, "62", 2024, q4)  # позже квартала версии
    await _osv(seeded, company, "01", 2023, q3)  # прошлый год
    await _osv(seeded, company, "76", 2024, q3, file_status=FileStatus.SUPERSEDED)  # заменённый файл
    await _osv(seeded, company, "90", 2024, q3, status=DocumentStatus.ERROR)  # документ в ошибке
    await _osv(seeded, company, "10", 2024, q3, file_status=FileStatus.ERROR)  # файл в ошибке
    client = await auth_client(KA_RF)

    card = (await client.get(f"{VERSIONS}/{version.id}")).json()

    accounts = {member["id"]: member["osv_accounts"] for member in card["members"]}
    assert accounts == {str(company.id): ["51", "58.03", "60"], str(person.id): []}


@pytest.mark.integration
async def test_card_member_osv_accounts_q1_version_ignores_later_quarters(
    auth_client: AuthClientFactory, seeded: AsyncSession
) -> None:
    """Review Focus: версия за Q1 — документы Q2 того же года не входят."""
    version, company, _ = await _card_world(seeded, PeriodQuarter.Q1)
    await _osv(seeded, company, "60", 2024, PeriodQuarter.Q1)
    await _osv(seeded, company, "62", 2024, PeriodQuarter.Q2)
    client = await auth_client(KA_RF)

    card = (await client.get(f"{VERSIONS}/{version.id}")).json()

    member = next(member for member in card["members"] if member["id"] == str(company.id))
    assert member["osv_accounts"] == ["60"]
```

Импорт `make_consolidation` в тестовом модуле уже есть. Если `make_stored_file` с `status=FileStatus.ERROR` требует
другой `job_status` — передать `job_status=RecognitionStatus.error` (значение enum проверить в `api/src/models/enums.py`,
класс `RecognitionStatus`).

`api/tests/test_openapi_routes.py` — в конец:

```python
def test_version_member_declares_type_and_osv_accounts(schema: dict[str, Any]) -> None:
    """front-api-gaps D-3: участник периметра — тип ЮЛ и счета ОСВ к периоду версии."""
    member = schema["components"]["schemas"]["MemberOut"]
    assert {"entity_type", "osv_accounts", "checklist"} <= set(member["required"])
```

- [ ] **Step 2: Запустить — падают**

Run: `cd api && .venv/bin/pytest tests/test_openapi_routes.py -v; .venv/bin/pytest -m integration tests/test_api_consolidations.py -k "card_member" -v`
Expected: FAIL — `KeyError: 'entity_type'` / `'osv_accounts'`.

- [ ] **Step 3: Репозиторий**

`api/src/repositories/consolidations.py`: импорт `from src.domain.osv_mapping import account_sort_key`; в импорт enums
добавить `PeriodQuarter` (если нет — он уже есть в списке; `DocumentStatus`, `DocumentType`, `FileStatus` — есть).
После `unconfirmed_documents`:

```python
async def osv_accounts(
    session: AsyncSession, entity_ids: Collection[uuid.UUID], year: int, quarters: Collection[PeriodQuarter]
) -> dict[uuid.UUID, list[str]]:
    """Счета ОСВ, загруженные к периоду версии (колонка «ОСВ» панели [34]; front-api-gaps D-3): уникальные
    `osv_account_code` документов `OSV` ЮЛ за год `year` и кварталы `quarters`; документ не `ERROR`, файл не
    `SUPERSEDED`/`ERROR`, квартал и код счёта заданы; статус подтверждения и привязка к версии не важны. Порядок —
    натуральный (`account_sort_key`); ЮЛ без документов в словаре нет."""
    if not entity_ids:
        return {}
    stmt = (
        select(Document.legal_entity_id, Document.osv_account_code)
        .join(StoredFile, StoredFile.id == Document.stored_file_id)
        .where(
            Document.legal_entity_id.in_(list(entity_ids)),
            Document.document_type == DocumentType.OSV,
            Document.period_year == year,
            Document.period_quarter.in_(list(quarters)),
            Document.status != DocumentStatus.ERROR,
            StoredFile.status.not_in([FileStatus.SUPERSEDED, FileStatus.ERROR]),
            Document.osv_account_code.is_not(None),
            Document.osv_account_code != "",
        )
        .distinct()
    )
    accounts: dict[uuid.UUID, list[str]] = defaultdict(list)
    for entity_id, code in await session.execute(stmt):
        accounts[entity_id].append(code)
    return {entity_id: sorted(codes, key=account_sort_key) for entity_id, codes in accounts.items()}
```

(`period_quarter IN (...)` отбрасывает `NULL` сам — документы без квартала не попадают.)

- [ ] **Step 4: Схема участника**

`api/src/schemas/consolidations.py`: в импорт enums добавить `EntityType`. Класс:

```python
class MemberOut(BaseModel):
    """ЮЛ периметра версии (front-api-gaps D-2, D-3): тип ЮЛ, самоописывающие ячейки чек-листа в порядке правил подхода
    и счета ОСВ, загруженные к периоду версии (`osv_accounts` — «что загружено», готовность — в ячейках)."""

    id: uuid.UUID
    name: str
    inn: str
    entity_type: EntityType
    is_head_entity: bool
    checklist: list[ChecklistCellOut]
    osv_accounts: list[str]
```

- [ ] **Step 5: Сервис**

`api/src/services/consolidations.py`: `from src.domain.consolidation_periods import quarters_through, reporting_date`.
В `_card` после получения `rules, cells`:

```python
        accounts = await repo.osv_accounts(
            self._session,
            [entity.id for _, entity in members],
            consolidation.year,
            quarters_through(consolidation.quarter),
        )
```

и в `MemberOut(...)` добавить `entity_type=entity.entity_type,` и `osv_accounts=accounts.get(entity.id, []),`. Docstring
`_card`: дописать «у членов — тип ЮЛ и счета ОСВ к периоду версии (D-3)».

- [ ] **Step 6: Запустить — проходят**

Run: `cd api && .venv/bin/pytest tests/test_openapi_routes.py tests/test_schemas_consolidations.py -v && .venv/bin/pytest -m integration tests/test_api_consolidations.py tests/test_api_consolidation_checklist.py tests/test_api_consolidation_members.py tests/test_consolidation_fixtures.py -v`
Expected: PASS.

- [ ] **Step 7: Линтеры и коммит**

Run: `make lint` → без ошибок.

```bash
git add api/src/repositories/consolidations.py api/src/schemas/consolidations.py api/src/services/consolidations.py api/tests/test_api_consolidations.py api/tests/test_openapi_routes.py
git commit -m "feat(consolidations): тип ЮЛ и счета ОСВ к периоду версии у участника периметра (#42)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
```

---

### Task 4: Документы workspace (bounded-PR в arm-ka-docs)

**Files (репозиторий docs, отдельный worktree):**
- Create: `dev/api-contract-files-directories.md`
- Modify: `dev/api-contract-slice-4.md`, `dev/api-contract-slice-3b.md` (ссылка), `context/07-open-questions.md` (OQ-43),
  `context/10-user-journey.md` (шаги 2.1, 2.2, 2.6, 2.5), `mockup/INDEX.md` ([42])

**Interfaces:**
- Consumes: итоговые схемы Tasks 1–3 (`ConsolidationCreate`, `ChecklistCellOut`, `MemberOut`); существующие схемы
  `api/src/schemas/files.py` (`FileOut`, `JobBrief`, `DocumentBrief`), `api/src/schemas/documents.py` (`DocumentOut`,
  `EntryOut` — имя модуля проверить), `api/src/schemas/directories.py` (`CompanyGroupOut`, `LegalEntityOut`,
  `RelatedGroupOut`, `RelatedGroupDetail`, `RegionalOfficeOut`, фильтры `CompanyGroupFilter`, фильтр списка ЮЛ),
  `api/src/schemas/common.py` (`Page`, лимиты), `api/src/api/endpoints/files/*.py` (коды ошибок), `README.md` arm-core
  («Ошибки API»).
- Produces: PR в RSHB/arm-ka-docs (номер — в описание PR arm-core, Task 5).

- [ ] **Step 1: Worktree и issue docs**

```bash
cd /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps
rm docs                                  # это симлинк на основной checkout docs
git -C /Users/andrey.epifancev/projects/awp-ca/docs fetch -q
git -C /Users/andrey.epifancev/projects/awp-ca/docs worktree add -b tmp/front-gaps-docs /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs origin/main
touch /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs/.bounded
tea issues create --login home --repo RSHB/arm-ka-docs --title "Документы к arm-core#42: контракт файлов и справочников, OQ-43, модалка [42]" --description "Bounded: контракт для фронта (файлы/документы, справочники, новые поля консолидаций), OQ-43 (решение владельца 07.10.2026, П-3), баннер «Осталось: N» = все несопоставленные (П-1), шаг 2.1 пути и [42] в mockup/INDEX.md (блок «ЮЛ консолидации»), устаревшее «CSV в Срезе 4 нет». Код — RSHB/arm-core#42."
git -C /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs branch -m tmp/front-gaps-docs feat/<N>-front-api-gaps-docs
```

`<N>` — номер созданной issue (из вывода `tea`). `.bounded` в `.gitignore` docs — проверить `git -C … status`: файла в
списке быть не должно; если он виден — не добавлять его в коммит.

- [ ] **Step 2: Новый контракт `dev/api-contract-files-directories.md`**

Структура — как у `dev/api-contract-slice-3b.md` (шапка: назначение, общие правила со ссылкой на
`api-contract-slice-4.md` «Общее»; таблица маршрутов; схемы; нюансы). Содержание — **по коду**, не по памяти:

1. Файлы и документы (Срез 2c, используются панелью [39]/[40] и экраном [41]):
   - `GET /legal-entities/{legal_entity_id}/files` — параметры (`include_superseded`, `limit` (по умолчанию / максимум —
     из `schemas/common.py`), `offset`), порядок (по убыванию `uploaded_at` — проверить в репозитории), ответ `Page[FileOut]`;
     опрос во время распознавания — этим же списком или `GET /files/{id}`.
   - `GET /files/{file_id}` — `FileOut`; `DELETE /files/{file_id}` — 204, 409 `FILE_HAS_CONFIRMED_DOCUMENTS` /
     `FILE_SUPERSEDES_OTHERS` (коды и тексты — из `endpoints/files/read.py` и README «Ошибки API»).
   - `POST /legal-entities/{id}/files` — коды `rejected[].code` (`UNSUPPORTED_FILE`, `FILE_TOO_LARGE`, `DUPLICATE_FILE`,
     `STORAGE_UNAVAILABLE` — сверить с `services/primary_files.py`), 201 vs 422 `{accepted, rejected}` и **второе** тело
     422 — доменная ошибка `ENTITY_NOT_IN_PERIMETER` (`{"detail": {"code", "message"}}`): клиент различает по форме.
   - `GET /documents/{document_id}` (`DocumentOut`), `GET /documents/{document_id}/entries` (`EntryOut`, пагинация).
   - Схемы `FileOut`, `JobBrief`, `DocumentBrief` — все поля с типами и nullable (из `schemas/files.py`); как показать
     «Период» в [39] (`period_year` + `period_quarter` + `is_cumulative`: Q3 нарастающий — «2024 · 9 мес.»), «Проверка»
     (`counterparty_check`; `period_check` всегда `UNKNOWN` — показывать «—», OQ-120), статус строки (файл `UPLOADED`/
     `PROCESSING` — «Обработка», `ERROR` — «Ошибка»; документ `RECOGNIZED`/`CONFIRMED` — «Загружен», `NEEDS_CHECK` —
     «Требуется проверка»; подписи — `10-user-journey.md` «Словарь UI»).
   - Фильтра по версии консолидации нет: drawer показывает все документы ЮЛ (решение владельца 07.10.2026).
2. Справочники для экранов [03], [36], [42], [60]: `GET /directories/company-groups` (`CompanyGroupOut`, `q` ищет по
   name/crm_id/code, `legal_entities_count`; имя РФ — через `GET /directories/regional-offices`),
   `GET /directories/company-groups/{id}/related-groups` (ГСК/ГСЗ ГК, `kind`), `GET /directories/related-groups/{id}`
   (`RelatedGroupDetail.members`), `GET /directories/legal-entities` (фильтры `company_group_id`, `outside_group`, `q`;
   `entity_type`, `documents_count`); как собрать модалку [42]: ЮЛ ГК — `legal-entities?company_group_id=`, отметки —
   члены выбранной ГСК из `related-groups/{id}`; права — `DIRECTORY_VIEW`.

- [ ] **Step 3: `dev/api-contract-slice-4.md`**

- Таблица маршрутов, `POST /consolidations`: тело `{company_group_id, related_group_id, year, quarter, legal_entity_ids?}`;
  ошибки + 422 `ENTITY_NOT_IN_GROUP` (`legal_entity_ids`), `PERIMETER_TOO_SMALL` по выбранным; нюанс: без поля / `null` —
  периметр из ГСК, `[]` — 422; ГСК обязательна, в версии не хранится (П-2), колонка «ГСК» [34] до верификации пустая.
- Схемы: `members[]` — `{id, name, inn, entity_type ("ЮЛ"|"ИП"), is_head_entity, checklist[], osv_accounts[]}`;
  `ChecklistCellOut` — `{document_type, account (string|null), status, missing_quarters[], document_ids[]}`: ячейка
  самоописывающая, искать по `document_type`/`account`, а не по индексу; `osv_accounts` — счета действующих ОСВ за год
  версии до её квартала в любом статусе, кроме ошибки; готовность — по ячейкам.
- «Ответственный» на [34]: `lock.locked_by_name`, если есть активная блокировка, иначе `initiator.name`.
- П-1: «Осталось: N» и «Показать ЮЛ без ИНН» — `summary.unmapped_total` и `GET …/osv?unmapped=true`: все строки свода без
  сопоставленного ЮЛ, в том числе с ИНН, которого нет в справочнике (решение владельца 07.10.2026).
- П-3: «К отчетности» доступна во всех статусах (OQ-43 пересмотрен).
- Строка `| [37] Чек-лист | … (CSV в Срезе 4 нет) |` → «… `?format=csv` — CSV (Срез 3b)».
- Nullable-поля `ConsolidatedRowOut` (`account_code`, `account_root`, `row_number`, `counterparty_*`, `match_kind`) и
  `VersionBrief.created_at` — пометить `?`/`| null` (сверить с `schemas/consolidations.py`).
- В «Общее» уточнить: лимиты страниц у разных списков разные (сводная ОСВ — 500/2000, файлы и справочники — из
  `schemas/common.py`); ссылка на новый `api-contract-files-directories.md`.

- [ ] **Step 4: OQ-43, путь пользователя, INDEX**

- `context/07-open-questions.md`, строка OQ-43: в колонку статуса — «**решено владельцем 07.10.2026 (arm-core#42, П-3):**
  «К отчетности» доступна во всех статусах начиная с `INITIATED` для ролей с `CONSOLIDATION_VIEW`; правка свода
  (сопоставление) — только «в работе» со своей блокировкой». Прежнее допущение не удалять — зачеркнуть или оставить
  с пометкой «было».
- `context/10-user-journey.md`:
  - 2.1: после «ГК → ГСК → Год → Квартал» — «после выбора ГСК — блок **«ЮЛ консолидации»**: все неархивные ЮЛ ГК,
    отмечены члены выбранной ГСК, отметки меняются; «Выбрано ЮЛ: N. Минимум для консолидации: 2»»; API —
    `POST /consolidations` с `legal_entity_ids`; периметр — отмеченные ЮЛ.
  - 2.2: «Ответственный» — правило из Step 3; колонки ОФР / Бух. баланс / ОСВ — `members[].checklist` и `osv_accounts`,
    «Тип» — `entity_type`.
  - 2.3: «К отчетности» — во всех статусах (OQ-43).
  - 2.6: «CSV в Срезе 4 нет» → «CSV — `?format=csv` (Срез 3b)».
  - 3.1: «Показать ЮЛ без ИНН» = все несопоставленные (П-1).
- `mockup/INDEX.md`, строка `42`: в описание добавить «после ГК и ГСК — блок «ЮЛ консолидации» (все неархивные ЮЛ ГК,
  отмечены члены ГСК, минимум 2; снимок снят до выбора ГК — блока на нём нет)».

- [ ] **Step 5: Проверка и коммит docs**

Run: `git -C /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs diff --stat` — изменены только перечисленные
файлы; `docs/source/**` не тронут.

```bash
git -C /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs add dev/api-contract-files-directories.md dev/api-contract-slice-4.md dev/api-contract-slice-3b.md context/07-open-questions.md context/10-user-journey.md mockup/INDEX.md
git -C /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs commit -m "docs: контракт файлов и справочников, поля консолидаций #42, OQ-43, модалка [42]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
git -C /Users/andrey.epifancev/projects/awp-ca/.wt/front-gaps/docs push -u origin feat/<N>-front-api-gaps-docs
tea pulls create --login home --repo RSHB/arm-ka-docs --head feat/<N>-front-api-gaps-docs --base main --title "Документы к arm-core#42: контракт файлов и справочников, OQ-43, модалка [42]" --description "Closes #<N>. Код — RSHB/arm-core#42 (PR ссылается сюда).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
```

---

### Task 5: Завершение — README, CLAUDE.md, проверки, ревью, PR arm-core

**Files:**
- Modify: `README.md` (раздел «Консолидация (Срез 4)», таблица эндпоинтов ~стр. 636–645; «Ошибки API» ~стр. 843–845)
- Modify: `CLAUDE.md` (абзац «Консолидации (Срез 4)»)
- Modify: `openspec/changes/front-api-gaps/tasks.md`

**Interfaces:**
- Consumes: Tasks 1–4 (номер docs-PR из Task 4).
- Produces: PR в RSHB/arm-core (`Closes #42`).

- [ ] **Step 1: README и CLAUDE.md**

README, таблица эндпоинтов:
- `POST /consolidations` → «создать консолидацию ГК за период и версию №1 (`INITIATED`); периметр — текущие члены ГСК
  (≥ 2) или выбранные ЮЛ ГК `legal_entity_ids` (≥ 2, front-api-gaps)».
- `GET /consolidations/versions/{id}` → «карточка версии: периметр (тип ЮЛ, счета ОСВ к периоду версии), чек-лист по ЮЛ
  (самоописывающие ячейки), история статусов, блокировка».
«Ошибки API»: `PERIMETER_TOO_SMALL` — «в ГСК (при создании без списка), в выбранных ЮЛ (`legal_entity_ids`) или в новом
периметре (`PUT …/members`) меньше двух ЮЛ …»; `ENTITY_NOT_IN_GROUP` — «`POST /consolidations` с `legal_entity_ids` и
`PUT …/members`: …».
После таблицы эндпоинтов абзац: «Доработка #42 (`openspec/changes/front-api-gaps/`): создание с выбранным периметром,
ячейки чек-листа с `document_type`/`account`, `members[].entity_type`/`osv_accounts`; контракт —
`../docs/dev/api-contract-slice-4.md`, файлы и справочники — `../docs/dev/api-contract-files-directories.md`».

CLAUDE.md, абзац «Консолидации (Срез 4)», после перечня сервисов: «Создание и `PUT …/members` проверяют периметр одной
функцией `_validate_perimeter` (#42); ячейки чек-листа самоописывающие (`document_type`, `account`); `members[].osv_accounts`
— `repositories/consolidations.osv_accounts` (не подходящесть §3, а «что загружено к периоду»)».

`openspec/changes/front-api-gaps/tasks.md` — отметить `[x]` выполненные пункты 1–5 (пункт 4 этого tasks.md — README/
CLAUDE.md/OpenAPI — выполнен Tasks 1–3 и этим шагом; пункт 5 — Task 4 с номером docs-PR).

- [ ] **Step 2: Слить main и прогнать всё**

```bash
git fetch -q origin && git merge --no-edit origin/main
make check-full 2>&1 | tail -40
openspec validate front-api-gaps --strict
```

Expected: `check-full` EXIT 0 (unit, integration, `dbml-check`, docker-build, web-check; e2e — skip без профиля
`services`); `Change 'front-api-gaps' is valid`. Итоговые числа passed — в описание PR.

- [ ] **Step 3: Коммит описания**

```bash
git add README.md CLAUDE.md openspec/changes/front-api-gaps/tasks.md
git commit -m "docs: README и CLAUDE.md — периметр при создании, ячейки и участник периметра (#42)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2"
```

- [ ] **Step 4: Финальное ревью ветки**

Ревью всей ветки (`git diff origin/main...HEAD`) на модели opus против спеки `openspec/changes/front-api-gaps/` и раздела
Review Focus. Находки — маркеры `C-n`/`I-n`/`M-n` со статусом `fixed <commit>` / `deferred` / `rejected <причина>`;
исправления — отдельными коммитами, повтор `make check-full`. Решения, принятые без владельца, — дописать в
`openspec/changes/front-api-gaps/design.md` «Decisions made without discussion» (с № 9).

- [ ] **Step 5: Push и PR**

```bash
git push -u origin feat/42-front-api-gaps
tea pulls create --login home --repo RSHB/arm-core --head feat/42-front-api-gaps --base main \
  --title "API до сводной ОСВ: периметр при создании, ячейки чек-листа, участник периметра (#42)" \
  --description "<описание>"
```

Описание PR: «Closes #42»; что сделано (3 пункта); docs-PR `RSHB/arm-ka-docs#<M>` (мержить вместе); вывод
`make check-full` (числа); таблица находок ревью с маркерами и статусами; «Rulings I made» (решения №1–8 design.md + новые);
deferred — отдельным списком; в конце:

```
🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
```

Merge — только по команде владельца.