dev: маршруты файлов консолидации в гайде фронта, контрактах и пути пользователя (#90)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

context/10-user-journey.md

@@ -76,7 +76,7 @@
 | 2.2 | Отчётность → Группы компаний [03] → **Консолидации →** [34] | [03]: таблица ГК (Группа компаний, CRM ID, Основной РФ, Организаций), поиск по ГК, CRM ID или РФ. [34]: таблица консолидаций ГК: Год, Квартал, Версия (дерево версий под периодом), Статус (бейдж), ГСК, Дата создания, Дата верификации, Организаций; кнопки в строке **Взять в работу**, **К отчетности** (по снимку неактивна у «Инициация» и «Верификация РФ»; решение владельца 07.10.2026 — доступна во всех статусах, OQ-43), меню «…»; чекбокс «Только в работе». Выбор строки открывает панель **Организации** (Ответственный / Утверждён в РФ / Верифицирован в ГО; таблица Наименование, Документы, ОФР, Бух. баланс, ОСВ — перечень счетов, ИНН, Тип). **API:** `GET /company-groups/{id}/consolidations?in_work_only=` (периоды и версии, блокировка), `GET /consolidations/versions/{id}` (карточка: члены — тип ЮЛ `entity_type`, самоописывающие ячейки чек-листа ББ/ОФР, счета загруженных ОСВ `osv_accounts`; история; «Ответственный» — `lock.locked_by_name` при активной блокировке, иначе `initiator.name`; «Утверждён в РФ» / «Верифицирован в ГО» и колонка «ГСК» — Срез 7) | `consolidation_version`, `consolidation_lock`, `consolidation_member`, `document` |
 | 2.3 | [34] → **Взять в работу** [35] | «Консолидация … будет закреплена за вами для редактирования». **API:** `POST …/versions/{id}/lock` (перехват — `takeover_reason`), `DELETE …/lock`; ручной статус — `POST …/status` | `consolidation_lock`, `audit_event(CONSOLIDATION_LOCK)` |
 | 2.4 | [34] панель Организации → **Редактировать состав** [36] | фильтр по ГСК, «Показать все ЮЛ в ГК», чекбоксы, Сохранить. **API:** `PUT …/versions/{id}/members` (`{legal_entity_ids}`), нужны статус «в работе» и своя блокировка | `consolidation_member` |
-| 2.5 | строка организации → **Документы** → drawer «Первичные документы» [39] | список: документ (имя, формат, дата; подпись типа у прочих — «Прочий документ», «Бухгалтерская отчетность»), Период («2024 К1», «2025 · 9 мес.»), Проверка (✓ / ✗ / — Период, Контрагент), Статус (Загружен / Обработка / Требуется проверка / Ошибка); иконки: комментарий (поповер «Комментарий к документу …», [39-01]) и удалить; **Редактировать документы** — в снимке неактивна; **Загрузить документы** [40]: модалка с зоной «Перетащите файлы сюда» / **Выбрать документы**, Загрузить; **тип документа и период в модалке не выбираются** — определяются при распознавании. **API:** загрузка — `POST /legal-entities/{id}/files?consolidation_version_id=`; документы и подтверждение — `/files`, `/documents` (Срез 2c); подтверждённый документ привязывается к версиям «в работе» автоматически | `stored_file(UPLOADED)`, `s3_object`, `recognition_job(queued)`, `document.period_check/counterparty_check` → `DOCUMENTS_PROCESSING` |
+| 2.5 | строка организации → **Документы** → drawer «Первичные документы» [39] | список: документ (имя, формат, дата; подпись типа у прочих — «Прочий документ», «Бухгалтерская отчетность»), Период («2024 К1», «2025 · 9 мес.»), Проверка (✓ / ✗ / — Период, Контрагент), Статус (Загружен / Обработка / Требуется проверка / Ошибка); иконки: комментарий (поповер «Комментарий к документу …», [39-01]) и удалить; **Редактировать документы** — в снимке неактивна; **Загрузить документы** [40]: модалка с зоной «Перетащите файлы сюда» / **Выбрать документы**, Загрузить; **тип документа и период в модалке не выбираются** — определяются при распознавании. **API:** список — `GET /consolidations/{cid}/legal-entities/{id}/files` (рабочий стол консоли: файлы, загруженные в эту консолидацию, и файлы с документами, привязанными к её версиям; переключатель «Все документы организации» — `GET /legal-entities/{id}/files`, у файла подпись консолидации); загрузка — `POST /consolidations/{cid}/legal-entities/{id}/files` (только в версии «в работе»); документы и подтверждение — `/files`, `/documents` (Срез 2c); подтверждённый документ привязывается к версиям «в работе» автоматически (v5.18, docs #90) | `stored_file(UPLOADED)`, `s3_object`, `recognition_job(queued)`, `document.period_check/counterparty_check` → `DOCUMENTS_PROCESSING` |
 | 2.6 | [34] → **Скачать чек-лист** [37] | матрица Организация × (Бух. баланс, ОФР, ОСВ 01 58 60 62 66 67 76 90, Прочие); легенда: Загружен / Обработка / Требуется проверка / Ошибка загрузки / Отсутствует; Скачать CSV. **API:** `GET …/versions/{id}/checklist` (`rules[]`, `rows[].cells[]`: `document_type`, `account`, `status`, `missing_quarters`, `document_ids`); «Скачать CSV» — `?format=csv` (Срез 3b) | `required_document_rule × consolidation_member − document(CONFIRMED)` |
 | 2.7 | drawer [39] → клик по **PDF**-документу → **Проверка распознавания** [41] | слева «Исходный документ» постранично с масштабом; справа «Результат распознавания»: шапка формы (организация, ИНН, ОКПО/ОКОПФ/ОКФС, адрес, аудит, ОКУД, отчётная дата, ОКЕИ, единица измерения) и таблица Пояснения / Наименование показателя / Код / колонки-даты (в таблице есть строки без кода «в том числе …» и строка «Гудвилл 1105» ФСБУ 4/2023 — OQ-36, OQ-37); выпадающий список **Документ** для перехода между документами ЮЛ; **Добавить комментарий**; **Редактировать** [41-02] → кнопки **Сохранить** / **Отменить** (значения таблицы редактируются на месте); **Подтвердить данные**. Блок логических ошибок — по ТЗ (в снимках не виден). Для ОСВ (xlsx) экран в макете не открывается — строки readonly, OQ-42 | `financial_statement_meta/column/line/value.is_modified`, `osv_entry.is_modified`, `document(CONFIRMED)`, `comment`, `audit_event(RECOGNIZED_DATA_EDIT, DOCUMENT_CONFIRM)` → `DATA_CORRECTION` |
 

dev/api-contract-files-directories.md

@@ -24,7 +24,9 @@
 | Метод и путь | Право | Запрос | Ответ | Ошибки | Экран |
 |---|---|---|---|---|---|
 | `GET /legal-entities/{legal_entity_id}/files` | VIEW | query `limit`, `offset`, `include_superseded` (bool, по умолчанию `false` — заменённые скрыты) | `Page[FileOut]`, новые первыми (по убыванию `uploaded_at`) | 404 | [39] drawer «Первичные документы» |
-| `POST /legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле `files` (повторяется для каждого файла, не `files[]`); query `consolidation_version_id?` | 201 `UploadResult` (принят хотя бы один файл) / 422 `UploadResult` (ни один) | 404 (ЮЛ; версия — `VERSION_NOT_FOUND`), 409 `VERSION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER`, 503 `STORAGE_UNAVAILABLE` | [40] |
+| `GET /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` | VIEW | query `limit`, `offset`, `include_superseded` (bool, по умолчанию `false`) | `Page[FileOut]` — рабочий стол консоли для ЮЛ (файлы с этим `consolidation_id` + файлы с документами, привязанными к версиям консолидации), новые первыми; `SUPERSEDED` — только при `include_superseded=true` | 404 | [39] drawer внутри версии (v5.18, docs #90) |
+| `POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле `files` (повторяется) — загрузка в консолидацию | 201 `UploadResult` (принят хотя бы один файл) / 422 `UploadResult` (ни один) | 404 (консолидация, ЮЛ), 409 `CONSOLIDATION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER`, 503 `STORAGE_UNAVAILABLE` | [40] |
+| `POST /legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле `files` (повторяется) — без контекста (`consolidation_id = null`); query `consolidation_version_id` удалён (v5.18) | 201 / 422 `UploadResult` | 404, 503 `STORAGE_UNAVAILABLE` | страница ЮЛ, монозаёмщики |
 | `GET /files/{file_id}` | VIEW | — | `FileOut` | 404 | опрос строки файла |
 | `DELETE /files/{file_id}` | EDIT | — | 204 | 404, 409 `FILE_HAS_CONFIRMED_DOCUMENTS`, 409 `FILE_SUPERSEDES_OTHERS` | [39] иконка «удалить» |
 | `GET /files/{file_id}/content` | VIEW | query `disposition` (`attachment` по умолчанию / `inline`) | поток исходного файла | 404 (`FILE_CONTENT_NOT_FOUND` — объекта нет в хранилище), 503 | [41] «Исходный документ» (см. контракт 3b) |
@@ -45,7 +47,7 @@ file_id?}`, где `code` — `UNSUPPORTED_FILE` (тип не из списка
 
 **`FileOut`** `{id, legal_entity_id, original_name?, file_type, status (FileStatus), version_no, size_bytes?, content_hash?,
 uploaded_at?, uploaded_by?, superseded_by_file_id?, job (JobBrief | null), documents[] (DocumentBrief)}` — поля с `?` могут быть
-`null`. **`JobBrief`** `{id, status (RecognitionStatus), error_code?, error_message?, mapping_error?, warnings[],
+`null`. `consolidation_id: uuid | null` — консолидация, в которую загружен файл (v5.18); `null` — загружен без контекста. **`JobBrief`** `{id, status (RecognitionStatus), error_code?, error_message?, mapping_error?, warnings[],
 mapping_warnings[], finished_at?}` — причина ошибки сервиса распознавания (`error_*`) или маппинга (`mapping_error`).
 **`DocumentBrief`** `{id, document_type, osv_account_code?, period_year?, period_quarter?, is_cumulative?, status (DocumentStatus),
 period_check?, counterparty_check?, locator?, comments_count}` — порядок: тип, счёт, `locator`.

dev/api-contract-slice-4.md

@@ -47,7 +47,7 @@
 | `GET /consolidations/versions/{version_id}/osv/export` | VIEW | те же фильтры, что у `…/osv`, без `limit`/`offset` | файл xlsx (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`) | 404 | «Экспорт» [30] |
 | `GET /consolidations/versions/{version_id}/counterparty-candidates` | VIEW | query: `q` (≤ 500), `scope` (`group` по умолчанию / `all`), `entry_id` | `CandidateOut[]` (до 100) | 404, 422 `QUERY_TOO_SHORT` (`scope=all` и `q` короче 3 символов после обрезки) | [32-osv-map-counterparty] |
 | `POST /consolidations/versions/{version_id}/osv/entries/{entry_id}/counterparty` | EDIT | `MapCounterpartyIn {legal_entity_id, move_alias?=false}` | 200 `MapCounterpartyOut` | 404, 409 `VERSION_NOT_EDITABLE` / `LOCK_REQUIRED` / `LOCKED_BY_OTHER`, 409 `ALIAS_TAKEN` (`owners[] {legal_entity_id, name}`) | [32-osv-map-counterparty] «Связать» |
-| `POST /legal-entities/{legal_entity_id}/files?consolidation_version_id=` | `DOCUMENT_EDIT` | multipart `files`; параметр версии необязателен | как в Срезе 2c: 201/422 `{accepted[], rejected[]}` | 404 (ЮЛ или версия), 409 `VERSION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER` | [39] / [40] |
+| `POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` | `DOCUMENT_EDIT` | multipart `files` (v5.18, docs #90; прежний query `consolidation_version_id` у `POST /legal-entities/{id}/files` удалён) | как в Срезе 2c: 201/422 `{accepted[], rejected[]}` | 404 (консолидация или ЮЛ), 409 `CONSOLIDATION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER` | [39] / [40] |
 
 Остальные маршруты, влияющие на версию: `POST /documents/{id}/confirm` (Срез 2c) привязывает подтверждённый документ ко всем
 версиям «в работе» своей ГК и может перевести версию в `DATA_CORRECTION`; `DELETE /files/{id}` и автозамена — снимают привязки
@@ -177,7 +177,7 @@ alias_moved_from (uuid | null)}`.
 | [42] Новая консолидация | справочники: ГК → её ГСК (`…/company-groups/{id}/related-groups`, `kind = gsk`) → ЮЛ ГК и члены ГСК (нюанс 19) → `POST /consolidations` с `legal_entity_ids` |
 | [34] Консолидации ГК | `GET /company-groups/{id}/consolidations` (+ `in_work_only`), клик по строке — `GET …/versions/{id}` (панель «Организации»: `members[]` — тип, ячейки ББ/ОФР, `osv_accounts`; «Ответственный» — нюанс 20); «Взять в работу» — `POST …/lock`; меню «…» → «Отмена КФО» — `POST …/status {CANCELLED, comment}` |
 | [36] Состав | `GET …/versions/{id}` (члены), все ЮЛ ГК — справочники, «Сохранить» — `PUT …/members` |
-| [39]/[40] Документы организации | `GET /legal-entities/{id}/files` (все файлы ЮЛ, опрос во время распознавания — им же или `GET /files/{id}`; схема — `dev/api-contract-files-directories.md`), `POST /legal-entities/{id}/files?consolidation_version_id=` |
+| [39]/[40] Документы организации | `GET /consolidations/{cid}/legal-entities/{id}/files` (рабочий стол консоли; «Все документы организации» — `GET /legal-entities/{id}/files`; опрос во время распознавания — им же или `GET /files/{id}`; схема — `dev/api-contract-files-directories.md`), `POST /consolidations/{cid}/legal-entities/{id}/files` |
 | [37] Чек-лист | `GET …/checklist`; «Скачать CSV» — `GET …/checklist?format=csv` (Срез 3b) |
 | [30] ОСВ | `GET …/osv` с фильтрами, `GET …/osv/summary`, «Экспорт» — `GET …/osv/export` |
 | [32-osv-no-inn], [32-osv-map-counterparty] | `GET …/osv?unmapped=true`, `GET …/counterparty-candidates`, «Связать» — `POST …/osv/entries/{entry_id}/counterparty` |

dev/frontend-api-guide.md

@@ -29,6 +29,7 @@
 
 | Когда, PR | Что изменилось в API | Что сделать в клиенте |
 |---|---|---|
+| 09.10, docs #90 (DBML v5.18; arm-core и arm-web — дочерние PR) | **Файлы в контексте консолидации.** Новые маршруты `POST /consolidations/{cid}/legal-entities/{le}/files` (загрузка в консоль: 404; 409 `CONSOLIDATION_NOT_EDITABLE` — нет версии «в работе»; 422 `ENTITY_NOT_IN_PERIMETER`) и `GET /consolidations/{cid}/legal-entities/{le}/files` (рабочий стол консоли для ЮЛ: файлы консоли + файлы с документами, привязанными к её версиям; `include_superseded`). Query `consolidation_version_id` у `POST /legal-entities/{id}/files` **удалён**; `FileOut.consolidation_id: uuid \| null`. Отменяет решение 07.10 «фильтра файлов ЮЛ в контексте версии нет» | панель [39] — стол консоли (`current_consolidation_id` из строки списка `con_id` / карточки версии `consolidation_id`), переключатель «Все документы организации» → `GET /legal-entities/{id}/files` с подписью консолидации у файла; загрузка [40] — новым маршрутом, кнопка недоступна, если версия не «в работе» |
 | 09.10, arm-core #85 (#84) | **Форма ЮЛ одним запросом** (макет [51-02], [79]): `POST` и `PATCH /directories/legal-entities` принимают `aliases: string[]` (1–500 символов, ≤ 100), `gsk_id`, `gsz_id` и применяют их в той же транзакции, что и поля ЮЛ (ошибка — откат всего). `POST`: алиасы и членства создаются вместе с ЮЛ. `PATCH`: не переданное поле не меняется; `aliases` — **итоговый набор** (сверка по `normalized_alias`: совпавшие не трогаются, лишние удаляются — нужно право `DIRECTORY_DELETE`, иначе 403 строкой; `aliases: null` — 422), `gsk_id`/`gsz_id` — итоговая группа (`null` — выйти, другая — сменить). Новый код 422 `WRONG_GROUP_KIND`; дубль в списке — 409 `ALIAS_EXISTS`. Ответ обоих — **`LegalEntityDetail`** (было `LegalEntityOut`; поля прежние + `memberships`, `aliases`) | «Добавить»/«Сохранить» в модалках ЮЛ — один запрос со всей формой; в `PATCH` слать `aliases` и группы целиком, как они на экране; после ответа брать карточку из него, без `GET`; удаление тега-алиаса без `DIRECTORY_DELETE` (`/me.permissions`) не предлагать — сервер ответит 403 |
 | 08.10, arm-core #75 (#74) | **Отмена П-1** (решение владельца 08.10.2026): «несопоставленная» строка свода — нет ЮЛ после резолва **и** нет ИНН из файла. `unmapped_total`, `GET …/osv?unmapped=true` и экспорт с этим фильтром больше не включают строки с ИНН, которого нет в справочнике (`unmapped=false` — все остальные строки). Новое поле `ConsolidatedRowOut.counterparty_entity_inn` — ИНН сопоставленного ЮЛ справочника (П-8; `counterparty_inn` — по-прежнему ИНН из файла) | «Указать» — только у строк без `counterparty_id` и без `counterparty_inn`; у строки, сопоставленной без ИНН в файле, показывать `counterparty_entity_inn` с возможностью пересопоставить (макет [32-osv-no-inn], `osv-inn-mapped-button`; повторный `POST …/counterparty` разрешён) |
 | 08.10, arm-core #60 (#58) | **Предупреждение автозамены** (OQ-154): если новый файл заменил прежний целиком, а части документов прежнего в нём нет (книга «ББ + ОФР» → отдельный ОФР), в `job.mapping_warnings` **нового** файла приходит одна строка на заменённый файл: «автозамена: файл «…» (версия N) заменён этим файлом целиком, но в новом файле нет документов прежнего: …; привязки сняты с версий консолидации: …» — с пометкой `CONFIRMED` у подтверждённых документов. Схемы ответов не менялись; поведение замены прежнее | показать предупреждение в карточке нового файла заметно (не только в общем списке подсказок): аналитик должен догрузить выпавшие документы; текст не разбирать |
@@ -41,7 +42,7 @@
 | 07.10, #46 | Ячейка чек-листа `ChecklistCellOut` стала **самоописывающей**: `document_type` и `account` своего правила | искать ячейку по `document_type`/`account`, а не по индексу |
 | 07.10, #46 | `VersionCard.members[]` (`MemberOut`): новые `entity_type` (`"ЮЛ"`/`"ИП"`/`null`) и `osv_accounts[]` — счета ОСВ, загруженные к периоду версии | колонки «Тип» и «ОСВ» панели «Организации» [34] |
 | 07.10, решения владельца П-1/П-2/П-3 | ~~«Осталось N» / «Показать ЮЛ без ИНН» = **все** несопоставленные строки (`unmapped_total`), а не только без ИНН~~ (П-1 отменён 08.10, см. arm-core #75); ГСК в версии **не хранится**; «К отчётности» доступна в любом статусе | баннер — по `unmapped_total`; колонку «ГСК» на [34] не заполнять; кнопку «К отчётности» не прятать по статусу |
-| 07.10, решение владельца | Фильтра «файлы ЮЛ в контексте версии» нет и не будет | drawer [39] показывает все файлы ЮЛ; подходящесть — по `document_ids` ячеек чек-листа |
+| 07.10, решение владельца | ~~Фильтра «файлы ЮЛ в контексте версии» нет и не будет~~ (пересмотрено 09.10, см. docs #90 выше) | ~~drawer [39] показывает все файлы ЮЛ~~; подходящесть документа версии — по-прежнему по `document_ids` ячеек чек-листа |
 | 07.10, arm-core #39 (Срез 3b) | Новые маршруты: `GET/PATCH /documents/{id}/statement`, `POST …/statement/checks/accept`, `GET/POST /documents/{id}/comments`, `GET /files/{id}/content`, `GET /users/brief`, `GET …/checklist?format=csv` | экран [41], комментарии, просмотр первички, имена пользователей, «Скачать чек-лист» |
 | 07.10, #39 | `POST /documents/{id}/confirm` для ББ/ОФР — новые 409 `PERIOD_REQUIRED` и `CHECKS_NOT_PASSED` (`detail.failures[]`) | обработать оба кода на «Подтвердить данные» |
 | 07.10, #39 | Новые поля: `comments_count` у документа (в `FileOut.documents[]` и `DocumentOut`), `documents_count` у ЮЛ | бейджи комментариев, колонка «Документы» |
@@ -321,8 +322,10 @@ UI прячет элементы по `GET /me → permissions` (объедин
 
 | Метод и путь | Право | Запрос | Ответ | Ошибки |
 |---|---|---|---|---|
-| `POST /legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле **`files`** повторяется на каждый файл (не `files[]`); query `consolidation_version_id?` | 201 `UploadResult {accepted[] {file_id, job_id, name}, rejected[] {name, code, message, file_id?}}`, если принят ≥ 1 файл; **422 тем же телом**, если ни одного | 404 (ЮЛ или версия), 409 `VERSION_NOT_EDITABLE`, 422 `ENTITY_NOT_IN_PERIMETER` (объектом `detail`), 503 `STORAGE_UNAVAILABLE` |
+| `POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` | EDIT | multipart, поле **`files`** повторяется на каждый файл (не `files[]`) — загрузка **в консолидацию** (панель [40] внутри версии) | 201 `UploadResult {accepted[] {file_id, job_id, name}, rejected[] {name, code, message, file_id?}}`, если принят ≥ 1 файл; **422 тем же телом**, если ни одного | 404 (консолидация или ЮЛ), 409 `CONSOLIDATION_NOT_EDITABLE` (нет версии «в работе»), 422 `ENTITY_NOT_IN_PERIMETER` (объектом `detail`), 503 `STORAGE_UNAVAILABLE` |
+| `POST /legal-entities/{legal_entity_id}/files` | EDIT | то же, **без контекста** (страница ЮЛ, монозаёмщики): `consolidation_id = null` | как выше | 404, 503 `STORAGE_UNAVAILABLE` |
 | `GET /legal-entities/{legal_entity_id}/files` | VIEW | `limit`, `offset`, `include_superseded` (по умолчанию `false`) | `Page[FileOut]`, новые первыми | — |
+| `GET /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` | VIEW | `limit`, `offset`, `include_superseded` | `Page[FileOut]` — **рабочий стол консоли** для ЮЛ: файлы с этим `consolidation_id` плюс файлы, чьи документы привязаны к любой версии консолидации; новые первыми; `SUPERSEDED` — только при `include_superseded=true` | 404 |
 | `GET /files/{file_id}` | VIEW | — | `FileOut` | — |
 | `DELETE /files/{file_id}` | EDIT | — | 204 (удаляет документы, строки ОСВ, формы ББ/ОФР, комментарии, задания) | 409 `FILE_HAS_CONFIRMED_DOCUMENTS`, 409 `FILE_SUPERSEDES_OTHERS` |
 | `GET /files/{file_id}/content` | VIEW | `disposition` = `attachment` (по умолчанию) / `inline` | поток байт; `Content-Type` по типу файла | 404 `FILE_CONTENT_NOT_FOUND` (в БД есть, в хранилище нет), 503 `STORAGE_UNAVAILABLE` |
@@ -340,8 +343,9 @@ UI прячет элементы по `GET /me → permissions` (объедин
   `FILE_TOO_LARGE`, `DUPLICATE_FILE` (тот же файл у ЮЛ уже есть — `file_id` указывает на него), `STORAGE_UNAVAILABLE`.
 - Два разных тела 422: все файлы отклонены — `UploadResult` (смотрите `rejected[]`); ЮЛ вне периметра версии —
   `{"detail": {"code": "ENTITY_NOT_IN_PERIMETER", …}}`. Различайте по наличию `detail`.
-- С `consolidation_version_id` версия должна быть видима, «в работе» и содержать ЮЛ; первый принятый файл переводит версию
-  `INITIATED` → `DOCUMENTS_PROCESSING`. Блокировка версии для загрузки **не нужна**.
+- Загрузка в консолидацию: консолидация видима, есть версия «в работе», ЮЛ в её периметре; первый принятый файл переводит
+  **каждую** версию консолидации «в работе» с этим ЮЛ из `INITIATED` в `DOCUMENTS_PROCESSING`. Блокировка версии для загрузки
+  **не нужна**. `FileOut.consolidation_id` — куда загружен файл (`null` — без контекста).
 - Общий размер запроса приложение не ограничивает (лимит ставит ingress), число файлов — только предел Starlette: больше 1000
   в одном запросе — 400 строкой; большие пачки лучше слать по
   нескольку файлов.
@@ -490,8 +494,8 @@ UI прячет элементы по `GET /me → permissions` (объедин
 | [33-01] «Изменить статус» / «Отмена КФО» | `POST …/versions/{id}/status {to_status, comment}` |
 | [36] Состав | `GET …/versions/{id}` (члены) + все ЮЛ ГК → «Сохранить» — `PUT …/members` |
 | [37] Чек-лист | `GET …/checklist`; «Скачать» — `GET …/checklist?format=csv` (blob, §7) |
-| [39] Первичные документы ЮЛ | `GET /legal-entities/{id}/files` (+ опрос при `UPLOADED`/`PROCESSING`); «Загрузил» — `GET /users/brief?ids=…`; удалить — `DELETE /files/{id}` |
-| [40] Загрузить документы | `POST /legal-entities/{id}/files?consolidation_version_id=…` → показать `accepted`/`rejected` → опрос списка |
+| [39] Первичные документы ЮЛ | `GET /consolidations/{cid}/legal-entities/{id}/files` (+ опрос при `UPLOADED`/`PROCESSING`); переключатель «Все документы организации» — `GET /legal-entities/{id}/files`, подпись консолидации у файла по `consolidation_id` (год и квартал — из списка консолидаций ГК, `null` — «вне консолидации»); «Загрузил» — `GET /users/brief?ids=…`; удалить — `DELETE /files/{id}` |
+| [40] Загрузить документы | `POST /consolidations/{cid}/legal-entities/{id}/files` → показать `accepted`/`rejected` → опрос списка; кнопка недоступна, если версия не «в работе» |
 | [41] Проверка распознавания ББ/ОФР | `GET /documents/{id}/statement`; исходник — `GET /files/{file_id}/content?disposition=inline` (blob); «Сохранить» [41-02] — `PATCH …/statement`; акцепт — `POST …/statement/checks/accept`; «Подтвердить данные» — `POST /documents/{id}/confirm`; комментарии — `GET/POST /documents/{id}/comments` |
 | Строки ОСВ документа | `GET /documents/{id}/entries` (только чтение) |
 | [30] Сводная ОСВ | `GET …/osv` с фильтрами, `GET …/osv/summary`; «Экспорт» — `GET …/osv/export` (blob) |

mockup/INDEX.md

@@ -38,7 +38,7 @@ GSK-002), консолидации 2024 К1 (v1 Верифицирован, v2
 | `36` | Модалка «Редактировать состав» | фильтры ГСК / Состав, чекбокс «Показать все ЮЛ в ГК», таблица Наименование/ИНН/Тип/ГСК с выбором, Сохранить | `consolidation_member`, `related_group_member` | 4 |
 | `37` | Модалка «Чек-лист загруженных документов» | фильтры Группа компаний / Документы; легенда статусов: Загружен, Обработка, Требуется проверка, Ошибка загрузки, Отсутствует; матрица: Организация × Бух. баланс, ОФР, ОСВ 01 58 60 62 66 67 76 90, Прочие документы (ОСВ №20, Прочий документ); **Скачать** (CSV) | `required_document_rule`, `document` | 3 |
 | `38` | Модалка «Импорт групп компаний из файла» | Файл (.xlsx, .csv), РФ, «Ожидаемые колонки: ИНН, Наименование, Тип, Базовый РФ ГК, ID ГК», «При дублировании: Пропустить существующие», Загрузить | `legal_entity`, `company_group`, `audit_event(DIRECTORY_IMPORT)` | 1 |
-| `39` | **Панель «Первичные документы»** организации (drawer) | ИНН, **Загрузить документы**, Редактировать документы; таблица: Документ (имя, формат, дата; у прочих — подпись «Прочий документ» / «Бухгалтерская отчетность»), Период («2024 К1», «2025 · 9 мес.»), Проверка (✓ / ✗ / — Период, Контрагент), Статус (Загружен / Обработка / Требуется проверка / Ошибка), иконки комментарий и удалить. Строки PDF — `doc-row--previewable` (клик → `41`), строки xlsx (ОСВ, расшифровки) — `doc-row--readonly` (клик ничего не открывает) | `stored_file`, `document.period_check/counterparty_check/status`, `comment` | 2–3 |
+| `39` | **Панель «Первичные документы»** организации (drawer) | ИНН, **Загрузить документы**, Редактировать документы; таблица: Документ (имя, формат, дата; у прочих — подпись «Прочий документ» / «Бухгалтерская отчетность»), Период («2024 К1», «2025 · 9 мес.»), Проверка (✓ / ✗ / — Период, Контрагент), Статус (Загружен / Обработка / Требуется проверка / Ошибка), иконки комментарий и удалить. Строки PDF — `doc-row--previewable` (клик → `41`), строки xlsx (ОСВ, расшифровки) — `doc-row--readonly` (клик ничего не открывает) | `stored_file` (+ `consolidation_id`, v5.18: панель внутри версии показывает рабочий стол консоли), `document.period_check/counterparty_check/status`, `comment` | 2–3 |
 | `39-01` | Панель документов → «Редактировать документы» | кнопка в снимке неактивна (режим не включается); иконка комментария в строке → поповер «Комментарий к документу <файл>» («Комментарий отсутствует», Закрыть) | `comment(object_type='document')` | 2–3 |
 | `40` | Модалка «Загрузка документов» | заголовок с организацией; зона «Перетащите файлы сюда» + **Выбрать документы**; Отмена, Загрузить (неактивна, пока нет файлов). Тип документа и период в модалке **не выбираются** — определяются при распознавании | `stored_file`, `recognition_job` | 2 |
 | `41` | **Проверка распознавания** (клик по PDF-документу в `39`) | крошки Отчётность › ГК › ЮЛ › Проверка документа; заголовок + имя файла, формат, дата; выпадающий список **Документ** (переход между документами организации) + бейдж статуса; **Добавить комментарий**. Слева «Исходный документ»: постраничные изображения, масштаб 100 % ±, сброс. Справа «Результат распознавания»: шапка формы (организация, ИНН, ОКПО/ОКОПФ/ОКФС, адрес, аудит), «Бухгалтерский баланс на 30 сентября 2025 г.», ОКУД, отчётная дата, ОКЕИ, единица измерения; таблица Пояснения / Наименование показателя / Код / колонки-даты, разделы и итоги; в таблице есть строки **без кода** («в том числе: Основные средства, пригодные к использованию…») и строка «Гудвилл 1105» (ФСБУ 4/2023); **Редактировать**, **Подтвердить данные**. В снимке — реальный скан ББ «Пекарни Счастливочной» из фикстур при имени файла «ОФР_2024_К1.pdf» (данные макета условны) | `document`, `financial_statement_meta/column/line/value`, `comment`, `audit_event(RECOGNIZED_DATA_EDIT, DOCUMENT_CONFIRM)` | 3 |