arm-core/openspec/changes/slice-4-consolidation/proposal.md

Proposal: Срез 4 — консолидация: версии, периметр, блокировка, привязка документов, сводная ОСВ, экспорт xlsx

Срез: 4 (../docs/context/09-delivery-plan.md). Репозиторий: arm-core. Issue: RSHB/arm-core#18. Родительский change: ../docs/openspec/changes/slice-4-consolidation (DBML v5.16, правила §2/§3/§9 по факту, OQ; RSHB/arm-ka-docs#19). Объём по решению владельца 06.10.2026: бэкенд, API, экспорт xlsx; UI (список, карточка, состав, вкладка ОСВ) делает другой разработчик по этим спекам.

Why

После Среза 2c строки ОСВ лежат в osv_entry по документам, но объекта «консолидация» в ядре нет: модели шести таблиц есть, сервисов, репозиториев и эндпоинтов нет; права CONSOLIDATION_* ни на одном маршруте не используются; period_check = UNKNOWN. Без Среза 4 нет периметра версии, нет сводной ОСВ, на которой стоят шахматка и ВГО (Срез 5), нет чек-листа комплекта и некуда показывать результат ручного сопоставления контрагентов.

What Changes

• DBML v5.16: enum counterparty_match_kind (INN, NAME, ALIAS, MANUAL, PROPAGATED) и колонка osv_entry.counterparty_match_kind — как появился counterparty_id (решение владельца 06.10.2026: строки, сопоставленные автоматически по имени или алиасу, должны выделяться в API). Миграция 0004_dbml_v5_16 с backfill по уже смапленным строкам. Таблиц 43, enum'ов 28.
• Маппинг (2c) пишет counterparty_match_kind по шагу резолва (CounterpartyIndex.resolve возвращает шаг).
• Консолидации (consolidations-api): POST /consolidations (ГК + ГСК + год + квартал → consolidation, consolidation_version №1 INITIATED, consolidation_member из текущего состава ГСК, минимум 2 ЮЛ); список по ГК с деревом версий; карточка версии с периметром, ответственным и ячейками чек-листа; PUT …/members; блокировка POST/DELETE …/lock с перехватом по причине; POST …/status (в Срезе 4 — только CANCELLED и возврат в INITIATED); чек-лист GET …/checklist (перенесён из Среза 3: без него негде показать пробелы кварталов).
• Привязка документов (documents-api, primary-files): подтверждение документа привязывает его (consolidation_document) ко всем версиям в работе, которым он подходит по периметру и периоду, и двигает статус INITIATED/DOCUMENTS_PROCESSING → DATA_CORRECTION; создание версии и добавление ЮЛ подхватывают уже подтверждённые документы; автозамена файла и удаление ЮЛ из периметра снимают привязку. Загрузка файла принимает необязательный consolidation_version_id (INITIATED → DOCUMENTS_PROCESSING); маппинг документа NEEDS_CHECK для ЮЛ периметра — DOCUMENTS_PROCESSING → DATA_CORRECTION.
• Сводная ОСВ (consolidated-osv): чистая функция domain/consolidated_osv.py от версии, периметра и привязанных ОСВ: приведение квартальных ОСВ к нарастающим (§2: ключ (счёт, контрагент), пропуск квартала → пробел, строки не строятся), признак контрагента ГСК/ГК/Внешний, дорезолв незаполненного counterparty_id на чтение (не сохраняется), match_kind/match_stored. GET …/osv (страница, фильтры), GET …/osv/summary (счётчики, пробелы), GET …/counterparty-candidates, POST …/osv/entries/{id}/counterparty (алиас, перенос алиаса, автоприменение, OSV_COUNTERPARTY_MAP), GET …/osv/export (xlsx, openpyxl, два листа, аудит EXPORT).
• Политика (directory-policy): видимость консолидации = видимость её ГК; правки версии — только в статусе «в работе» и при своей активной блокировке.
• Аудит (audit-trail): CONSOLIDATION_CREATE, MEMBERSHIP_CHANGE, CONSOLIDATION_LOCK, CONSOLIDATION_LOCK_TAKEOVER, CONSOLIDATION_STATUS_CHANGE, OSV_COUNTERPARTY_MAP, EXPORT — все с consolidation_version_id.
• Тесты: домен без БД (приведение периодов, пробелы, признак), API на PostgreSQL, гонки блокировок, сквозной fixtures-тест: консолидация группы «Русский бисквит» за Q3 2024, одно ручное сопоставление → ГСК у всех строк «Пекарня Счастливочная».
• Документы: README среза, CLAUDE.md, спеки.

Capabilities

New Capabilities

• consolidations-api: создание, список, карточка, периметр, блокировка, статусы, чек-лист.
• consolidated-osv: расчёт сводной ОСВ, кандидаты и ручное сопоставление контрагента, экспорт xlsx.

Modified Capabilities

• data-model: схема равна DBML v5.16, миграции 0001 → 0004.
• documents-api: подтверждение документа привязывает его к версиям и меняет их статус.
• primary-files: загрузка с consolidation_version_id; автозамена снимает привязку заменённых документов.
• osv-result-mapping: counterparty_match_kind при резолве; переход версии в DATA_CORRECTION по NEEDS_CHECK.
• directory-policy: видимость консолидаций и правило редактируемости версии.
• audit-trail: события консолидации.

Impact

• Таблицы DBML v5.16: consolidation, consolidation_version, consolidation_status_history, consolidation_lock, consolidation_member, consolidation_document, osv_entry (новая колонка), legal_entity_alias, required_document_rule, audit_event.
• Правила: §2 (приведение периодов), §3 (сводная ОСВ, ручное сопоставление), §9.1 (статусы Среза 4), §9.3 (period_check остаётся UNKNOWN, см. design D-12), §9.5 (отвязка при автозамене), §10 (права), 04-data-model-guide («что не хранится»).
• Код: новые api/endpoints/consolidations/, services/consolidations.py, services/consolidation_locks.py, services/consolidation_documents.py, services/consolidated_osv.py, services/osv_export.py, repositories/consolidations.py, domain/consolidated_osv.py, domain/consolidation_periods.py, schemas/consolidations.py; правки services/documents.py, services/result_mapping.py, services/primary_files.py, repositories/counterparties.py, domain/policy.py, api/endpoints/files/upload.py, миграция 0004.
• Потребители: фронт (2d/4-UI) — по этим спекам; tabular-parser и контракт v1.1 не меняются.

Non-goals

• Маршрут согласования после DATA_CORRECTION (CONSOLIDATION_RF и далее), УОБ, ex_snapshot, «Добавить версию», сценарий CONFIRM, подход EXTENDED — Срезы 6–7. Переходы в эти статусы отвечают 409 TRANSITION_NOT_ALLOWED.
• Запрет загрузки/подтверждения документов в статусах после DATA_CORRECTION (ТЗ 03_9 A1) — Срез 7, OQ-118.
• period_check документа по версии (OQ-120): остаётся UNKNOWN; подходящесть документа версии считается на лету.
• Шахматка, пары ВГО, корректировки (Срез 5), ББ/ОФР из Excel (2b), PDF (Срез 3), UI (другой разработчик).
• CSV чек-листа (макет 37) — фронт строит из JSON.
• Отвязка контрагента от строки (обратное действие): перевязка покрывает исправление ошибки.
• Зоны ответственности в политике (OQ-86), истечение блокировки по времени (OQ-119).