# primary-files-ui Specification

## Purpose
Аналитик загружает первичные файлы ЮЛ в контексте версии и видит в панели «Первичные документы» [39]/[40] файлы и их документы со статусами распознавания; список обновляется сам, пока идёт распознавание.

## Requirements

### Requirement: Загрузка файлов ЮЛ в контексте версии
Панель «Файлы ЮЛ» [39]/[40], открытая из строки ЮЛ карточки версии, SHALL загружать выбранные файлы одним запросом
`POST /consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files` (multipart, поле `files` повторяется),
где `consolidation_id` — консолидация открытой версии (из списка консолидаций ГК в сторе по `current_version_id`),
без других полей формы и без query `consolidation_version_id`. Тип и период документа не спрашиваются. Кнопка
«Загрузить документы» SHALL быть недоступна с подсказкой «Загрузка доступна только в версии в работе», если статус
открытой версии не `INITIATED`, `DOCUMENTS_PROCESSING` или `DATA_CORRECTION`. После ответа панель SHALL показать итог:
принятые файлы (`accepted[].name`) и отклонённые с причиной (`rejected[].name` + `message`). Ответ 422 с телом
`UploadResult` SHALL трактоваться как «ни один файл не принят» с тем же показом `rejected[]`; ответ 422 с `detail`
(`ENTITY_NOT_IN_PERIMETER`), 409 (`CONSOLIDATION_NOT_EDITABLE`) и прочие ошибки — показом `message`.

#### Scenario: Часть файлов отклонена
- **WHEN** аналитик загружает ОСВ-файл и файл, уже загруженный ранее у этого ЮЛ
- **THEN** первый показан принятым, второй — отклонённым с текстом причины `DUPLICATE_FILE` от сервера

#### Scenario: Все файлы отклонены
- **WHEN** сервер отвечает 422 с телом `UploadResult`
- **THEN** панель показывает каждый отклонённый файл с причиной, а не общую ошибку

#### Scenario: Загрузка идёт в консолидацию
- **WHEN** панель открыта из версии консолидации 2024 Q3 и аналитик загружает файл
- **THEN** запрос уходит на `/consolidations/{id консолидации 2024 Q3}/legal-entities/{id ЮЛ}/files` без query; после
  приёма файл появляется в столе панели

#### Scenario: Версия не в работе
- **WHEN** панель открыта из версии в статусе `CANCELLED`
- **THEN** кнопка «Загрузить документы» недоступна, при наведении — подсказка

### Requirement: Список файлов и документов ЮЛ
Панель SHALL по умолчанию показывать рабочий стол консолидации открытой версии —
`GET /consolidations/{consolidation_id}/legal-entities/{id}/files` (новые первыми): имя, статус файла по-русски
(«Обработка» для `UPLOADED`/`PROCESSING`, «Ошибка» с причиной из `job` для `ERROR`) и вложенные `documents[]` — тип
(«ОСВ <счёт>», «Бух. баланс», «ОФР», «Расшифровка», «Прочее»), период («2024 К1», «2024 · 9 мес.», «период не
определён»), статус документа («Требуется проверка», «Загружен» для `CONFIRMED`, «Ошибка»). Документы `OSV`, `BALANCE`,
`INCOME` SHALL быть ссылками на `/documents/:document_id`. Переключатель «Все документы организации» SHALL переключать
панель на `GET /legal-entities/{id}/files`; в этом режиме у файла не из текущей консолидации в подписи SHALL стоять его
консолидация: «<год> К<n>» по списку консолидаций ГК, «вне консолидации» при `consolidation_id = null`, «другая
консолидация», если id нет в списке. Если консолидация открытой версии не определена (версии нет в списке ГК), панель
SHALL работать в режиме «все» без переключателя.

#### Scenario: PDF с двумя формами
- **WHEN** файл `aep_6.pdf` распознан
- **THEN** под файлом видны два документа — «Бух. баланс» и «ОФР» со статусом «Требуется проверка», каждый открывает
  экран проверки

#### Scenario: Стол и все документы
- **WHEN** у ЮЛ есть файлы, загруженные в консолидации 2024 Q3 и 2024 Q4, и файл, загруженный без контекста; панель
  открыта из версии 2024 Q3
- **THEN** по умолчанию виден только файл 2024 Q3; после переключателя «Все документы организации» видны все три, у
  файла 2024 Q4 подпись «2024 К4», у файла без контекста — «вне консолидации», у файла 2024 Q3 подписи нет

### Requirement: Опрос до окончания распознавания
Пока панель открыта и среди файлов активного списка (стол или все документы) есть `UPLOADED` или `PROCESSING`, панель
SHALL перечитывать этот список раз в 5 секунд и SHALL прекратить опрос, когда таких файлов нет или панель закрыта.
Переключение режима или смена ЮЛ SHALL сбрасывать список и перечитывать его. При закрытии панели карточка версии SHALL
перечитываться (обновить ячейки чек-листа).

#### Scenario: Опрос останавливается
- **WHEN** все файлы активного списка перешли в `PROCESSED` или `ERROR`
- **THEN** запросы списка файлов прекращаются

### Requirement: Предупреждения файла и документа в карточке файла
Карточка файла (панель файлов) SHALL читать `job.warnings` как список структур `{code, severity, message, locator}`
(после выкладки ядра v5.19 это не строки; у старых заданий ядро отдаёт строки, обёрнутые в `LEGACY_WARNING`), показывать
`message` и `locator`, отличая `error` от `info`; предупреждения листа ОСВ и документа — из `DocumentOut.issues[]`.
`job.mapping_warnings` остаётся списком строк.

#### Scenario: Потерянный ОФР в карточке
- **WHEN** у задания `job.warnings = [{code: "JSON_FAILED", severity: "error", message: "…", locator: "file:x_ofr.json"}]`
- **THEN** карточка показывает предупреждение уровня «ошибка» с текстом и местом; экран не падает на объекте вместо строки

### Requirement: Комментарии документа в панели
В строке документа панели «Первичные документы» [39-01] SHALL быть кнопка с иконкой комментария и числом комментариев
документа (`documents[].comments_count`; при нуле — только иконка). Клик по кнопке SHALL открывать поповер «Комментарии
к документу <имя файла>» со списком `GET /documents/{id}/comments` (запрос при открытии; автор, дата и время по Москве,
текст) только для чтения; без комментариев — «Комментарий отсутствует»; кнопка «Закрыть» закрывает поповер. Клик по
кнопке и внутри поповера SHALL NOT открывать документ. У строки файла без документов кнопки нет.

#### Scenario: Счётчик совпадает с числом комментариев
- **WHEN** к документу добавлены два комментария и панель перечитана
- **THEN** в строке документа у иконки число 2, в поповере — оба комментария по возрастанию времени

#### Scenario: Документ без комментариев
- **WHEN** аналитик нажимает иконку комментария у документа без комментариев
- **THEN** в поповере «Комментарий отсутствует», экран документа не открывается