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

Why

Панель «Первичные документы» ЮЛ, открытая из версии консолидации, показывает все файлы ЮЛ: stored_file не знает, в какую консолидацию загружен, GET /legal-entities/{id}/files не фильтруется, а consolidation_version_id при загрузке служит только переходу статуса версии. Решения владельца 09.10.2026 (RSHB/arm-ka-docs#90, сквозной change ../docs/openspec/changes/console-files/, DBML v5.18): файл загружается в консолидацию (ГК + период) и образует её «рабочий стол», общий для всех версий периода; что использует конкретная версия, по-прежнему определяет consolidation_document; загрузка и список в контексте консоли — маршрутами от консолидации.

Срез: доработка Срезов 2c/4 вне плана 09-delivery-plan.md (запись в разделе «Срез 2d»). Репозиторий — только arm-core; фронт — RSHB/arm-web (свой change), документы — RSHB/arm-ka-docs#90. Issue — RSHB/arm-core#96.

Правила домена: 05-domain-rules.md §9.1 (переход при загрузке), §9.5 п. 1, 3, 8 и 11 (редакция v5.18 из docs #90). Таблицы DBML v5.18: stored_file (новая колонка consolidation_id, индекс (legal_entity_id, consolidation_id)), читаются consolidation, consolidation_version, consolidation_member, consolidation_document, document.

What Changes

• Модель и миграция. StoredFile.consolidation_id (nullable FK → consolidation, последняя колонка), индекс ix_stored_file_legal_entity_id_consolidation_id; DBML_VERSION = "5.18", make dbml-check по ../docs/model/data-model-v5.18.dbml; миграция 0006_dbml_v5_18: колонка, FK, индекс, backfill по consolidation_document (при привязках к версиям разных периодов — самый ранний), откат — удаление.
• Загрузка в консолидацию. POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files (DOCUMENT_EDIT): консолидация и ЮЛ видимы (404), есть версия «в работе» (409 CONSOLIDATION_NOT_EDITABLE), ЮЛ в периметре хотя бы одной из них (422 ENTITY_NOT_IN_PERIMETER); файл получает consolidation_id, FILE_UPLOAD.after_value.consolidation_id; после приёма ≥ 1 файла каждая версия консолидации «в работе» с ЮЛ в периметре и статусом INITIATED переходит в DOCUMENTS_PROCESSING отдельной транзакцией.
• Загрузка без контекста. POST /legal-entities/{id}/files: query consolidation_version_id удалён, коды VERSION_NOT_FOUND/VERSION_NOT_EDITABLE у загрузки больше не возникают; consolidation_id = NULL.
• Рабочий стол. GET /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files (DOCUMENT_VIEW): файлы ЮЛ с этим consolidation_id ∪ файлы ЮЛ с документом, привязанным к любой версии консолидации; limit, offset, include_superseded; та же карточка FileOut.
• Карточка файла. FileOut.consolidation_id: uuid | null в списках и GET /files/{id}.
• Автозамена. Новый файл без контекста наследует consolidation_id первого (по id) заменённого файла, у которого он задан.
• Спеки primary-files, documents-api, data-model; README («Ошибки API», таблицы маршрутов, §9.1), CLAUDE.md.

Non-goals

• Несколько рабочих версий одного периода и «новая версия после VERIFIED» не реализуются (OQ-160, отдельный срез); переход статуса после загрузки написан для N версий, но создаётся по-прежнему одна.
• Замороженный список первички верифицированной версии (ЕХ, Срез 7) не строится; стол показывается для версии любого статуса, загрузка проверяет только наличие версии «в работе».
• Признак «документ привязан / подходит версии» в FileOut не вводится (чек-лист, OQ-120).
• consolidation_document, fits, подхват, удаление файла — без изменений.
• Перенос файла между консолидациями, правка consolidation_id через API — нет.
• Контракт NATS и S3 не меняется.

Capabilities

New Capabilities

Modified Capabilities

• primary-files: загрузка в консолидацию (новый маршрут, коды ошибок, переход N версий), удаление query у загрузки ЮЛ, наследование consolidation_id при автозамене.
• documents-api: рабочий стол консоли, consolidation_id в карточке файла.
• data-model: DBML v5.18, миграция 0006 с backfill.

Impact

• api/src/models/files.py, api/src/models/__init__.py, api/alembic/versions/0006_dbml_v5_18.py, Makefile (DBML), api/scripts/dbml_parity.py (путь по умолчанию), api/tests/dbml_helpers.py.
• api/src/repositories/files.py (стол), api/src/repositories/consolidations.py (консолидация по id, версии консолидации под FOR UPDATE), api/src/services/primary_files.py (загрузка в консолидацию, стол), api/src/services/result_mapping.py (наследование), api/src/services/documents.py (file_out), api/src/schemas/files.py, api/src/api/endpoints/files/upload.py, новый consolidation_files.py, api/src/api/endpoints/files/__init__.py.
• Тесты: test_api_files_upload.py (раздел «в контексте версии» переписывается под консолидацию), test_api_files_read.py/новый test_api_consolidation_files.py, test_migrations.py, test_models_part_04_06.py, тесты автозамены.
• Клиент arm-web меняется одновременно (query удалён); стенд обновляется после слияния обоих PR.