arm-ka-docs/openspec/changes/archive/2026-10-10-console-files/proposal.md

Why

Панель «Первичные документы» ЮЛ [39], открытая из версии консолидации, показывает все файлы ЮЛ, в том числе загруженные в другие консолидации той же ГК. Причина в модели: файл принадлежит ЮЛ (stored_file.legal_entity_id), контекста консолидации у него нет, GET /legal-entities/{id}/files ничем не фильтруется. Связь с версией есть только у подтверждённых документов (consolidation_document), поэтому «что версия использует» и «что аналитик загрузил в эту консоль» сегодня разные множества, и второе нигде не хранится (consolidation_version_id при загрузке используется лишь для перехода статуса версии).

Решения владельца 09.10.2026 (RSHB/arm-ka-docs#90), целевая картина:

• файл загружается в консолидацию (ГК + год + квартал) и становится частью её «рабочего стола», общего для всех рабочих версий периода; рабочие версии одного периода различаются периметром;
• верифицированная версия заморожена: её первичка фиксируется в ЕХ (ex_snapshot_item.stored_file_id, Срез 7); новая версия после VERIFIED может менять документы при том же периметре;
• что использует конкретная версия, по-прежнему определяют consolidation_document и чек-лист версии;
• загрузка и список файлов в контексте консоли идут по маршрутам от консолидации, а не query-параметром у ЮЛ.

Срез: вне плана 09-delivery-plan.md — доработка Среза 2d/4 (UI первичных документов в карточке версии).

What Changes

• Модель, DBML v5.18: stored_file.consolidation_id uuid (nullable, FK → consolidation) — консолидация, в контексте которой загружен файл; NULL — загрузка без контекста (страница ЮЛ, монозаёмщики, API). Индекс (legal_entity_id, consolidation_id). Пишется один раз при загрузке; при автозамене наследуется заменённым файлом, если у нового файла контекста нет.
• API ядра: новые маршруты POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files (загрузка в консоль) и GET /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files (рабочий стол консоли для ЮЛ). У POST /legal-entities/{id}/files query consolidation_version_id убирается — маршрут остаётся для загрузки без контекста. FileOut.consolidation_id в списках и карточке файла. Переход INITIATED → DOCUMENTS_PROCESSING после загрузки — у всех версий консоли «в работе», где ЮЛ в периметре.
• Правила домена, §9.5: загрузка в консоль (проверки, коды ошибок, переход версий), состав рабочего стола, наследование при автозамене.
• Фронт arm-web: панель [39] и загрузка [40] ходят на маршруты консолидации; переключатель «Все документы организации» с подписью консолидации у файла; загрузка недоступна, если открытая версия не «в работе».
• Документы: model/data-model-v5.18.dbml, model/entities-v5.18.md, 04-data-model-guide.md, 05-domain-rules.md §9.5, 10-user-journey.md п. 2.5, dev/frontend-api-guide.md, dev/api-contract-files-directories.md, dev/api-contract-slice-4.md, dev/qa-guide.md, 07-open-questions.md.

Дочерние change'и console-files: RSHB/arm-core (миграция 0006_dbml_v5_18, сервис, маршруты, спеки primary-files и documents-api), RSHB/arm-web (спека primary-files-ui). Issue этого репозитория — RSHB/arm-ka-docs#90. Контракт обмена с сервисами распознавания не меняется, schema_version прежняя.

Non-goals

• Несколько рабочих версий одного периода с разным периметром и «новая версия после VERIFIED» ядро пока не создаёт (POST /consolidations создаёт только версию 1); эти правила — отдельный срез (OQ, design «Decisions» №6). Этот change лишь делает модель файлов совместимой с ними.
• Замороженный список первички верифицированной версии в панели не строится: заморозка — ex_snapshot (Срез 7). Панель из карточки версии не «в работе» показывает рабочий стол консоли как есть, без кнопки загрузки.
• Признак «документ подходит / привязан к версии» в списке файлов не вводится: это чек-лист версии (OQ-120).
• Привязка файла к версии (consolidation_file) не вводится: отвергнута на brainstorming 09.10.2026 (design, №1).
• consolidation_document, правило fits, подхват при создании версии и добавлении ЮЛ в периметр — без изменений.
• Горячие папки scan-gateway файлов в ядре не создают; их контекст не рассматривается.
• Backfill касается только файлов с документами в consolidation_document; прочие остаются NULL.

Capabilities

New Capabilities

Modified Capabilities

• Спецификации этого репозитория (dev-environment, quality-checks, recognition-contract) не меняются; требования к API и UI — в дочерних change'ах arm-core (primary-files, documents-api) и arm-web (primary-files-ui).

Impact

• arm-core: миграция с backfill; services/primary_files.py (загрузка, page_files, автозамена в services/result_mapping.py), repositories/files.py, api/endpoints/files/upload.py, read.py, новый роутер под /consolidations/{id}/legal-entities/{le}/files, schemas/files.py; тесты; README «Ошибки API».
• arm-web: services/api/files.ts, стор consolidations (current_consolidation_id), widgets/FilesDrawer/*, типы FileOut.
• Совместимость: query consolidation_version_id у POST /legal-entities/{id}/files исчезает — фронт меняется одновременно с ядром (стенд обновляется после слияния обоих PR). Файлы, загруженные до миграции без привязок, остаются «вне консолидации» и видны только по переключателю «Все документы организации».