75 lines
7.9 KiB
Markdown
75 lines
7.9 KiB
Markdown
## 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). Файлы, загруженные до миграции без привязок,
|
||
остаются «вне консолидации» и видны только по переключателю «Все документы организации».
|