arm-core/openspec/changes/console-files/specs/documents-api/spec.md

MODIFIED Requirements

Requirement: Файлы организации и карточка файла

GET /api/v1/legal-entities/{id}/files (DOCUMENT_VIEW, policy; include_superseded=false по умолчанию) SHALL возвращать Page файлов ЮЛ по убыванию uploaded_at: поля stored_file (в том числе consolidation_id: uuid | null, v5.18 — консолидация, в контексте которой файл загружен), текущее задание (status, error_code, error_message, mapping_error (metrics.mapping_error: причина ERROR файла после неудачного маппинга, когда у задания error_code пуст), metrics.warnings, metrics.mapping_warnings, finished_at), документы файла (id, document_type, osv_account_code, period_year, period_quarter, is_cumulative, status, period_check, counterparty_check, comments_count). GET /api/v1/files/{file_id} SHALL отдавать ту же карточку; чужой или несуществующий файл — 404.

Scenario: Список после обработки

• WHEN у ЮЛ два файла: PROCESSED с документом и ERROR
• THEN оба в списке; у первого documents непустой, у второго job.error_code заполнен

Scenario: Счётчик комментариев

• WHEN к документу файла добавлены два комментария
• THEN в карточке файла у документа comments_count = 2

Scenario: Консолидация в карточке

• WHEN один файл ЮЛ загружен в консолидацию C, другой — без контекста
• THEN в списке ЮЛ и в GET /files/{id} у первого consolidation_id = C, у второго consolidation_id = null

ADDED Requirements

Requirement: Рабочий стол консолидации для ЮЛ

GET /api/v1/consolidations/{consolidation_id}/legal-entities/{legal_entity_id}/files (DOCUMENT_VIEW; limit, offset, include_superseded=false по умолчанию; §9.5 п. 11 v5.18) SHALL отвечать 404 NOT_FOUND на консолидацию вне видимости или несуществующую («консолидация не найдена») и на ЮЛ вне видимости, иначе возвращать Page[FileOut] — объединение файлов ЮЛ, у которых stored_file.consolidation_id = consolidation_id, и файлов ЮЛ, у которых есть документ с записью consolidation_document к любой версии этой консолидации; порядок и карточка — как у списка файлов ЮЛ; SUPERSEDED — только при include_superseded=true (в обоих множествах). Принадлежность ЮЛ к ГК консолидации не проверяется: чужому ЮЛ соответствует пустой список.

Scenario: Стол показывает только файлы консоли

• WHEN у ЮЛ три файла: загружен в консолидацию 2025 Q1, загружен в консолидацию 2025 Q2, без контекста
• THEN стол 2025 Q1 содержит только первый; стол 2025 Q2 — только второй; GET /legal-entities/{id}/files — все три

Scenario: Подхваченный файл виден через привязку

• WHEN файл с CONFIRMED ОСВ за 2025 Q1 загружен без контекста и его документ привязан к версии консолидации 2025 Q2 (подхват при создании версии)
• THEN файл есть в столе 2025 Q2, хотя consolidation_id IS NULL

Scenario: Заменённый файл скрыт по умолчанию

• WHEN файл консолидации заменён (SUPERSEDED) новым файлом той же консолидации
• THEN по умолчанию в столе только новый; с include_superseded=true — оба

Scenario: Чужая консолидация

• WHEN ka_rf запрашивает стол консолидации ГК другого филиала и несуществующий id
• THEN оба ответа 404 с одинаковым телом