arm-core/openspec/specs/primary-files-ui/spec.md

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 стоять его консолидация: «<год> К» по списку консолидаций ГК, «вне консолидации» при 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 в поповере «Комментарий отсутствует», экран документа не открывается

Requirement: Открытая панель в адресе экрана консолидации

Открытая панель «Первичные документы» SHALL храниться в адресе экрана консолидации /groups/:group_id параметром ?entity=<legal_entity_id> рядом с ?version=. Клик по организации в панели «Организации» SHALL добавлять параметр, закрытие панели — убирать его; оба перехода SHALL заменять текущую запись истории браузера, без новой записи. Адрес с ?entity= SHALL открывать панель этой организации. Режим «Все документы организации» в адрес не входит: панель, открытая по адресу, показывает стол консолидации.

Scenario: Возврат из документа

• WHEN аналитик открыл панель организации, перешёл по ссылке документа и вернулся «Назад»
• THEN открыт экран консолидации с той же версией и панелью «Первичные документы» той же организации

Scenario: Закрытая панель не возвращается

• WHEN аналитик открыл панель организации, закрыл её и нажал «Назад» браузера
• THEN открыт экран, с которого пришли на экран консолидации, панель не открывается снова