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

primary-files Specification

Purpose

Загрузка файлов первичной отчётности в ядро: физический файл в S3 и stored_file, задание распознавания в outbox, дедуп, жизненный цикл статуса файла (§9.2), автозамена прежних версий и удаление.

Requirements

Requirement: Загрузка файлов организации

POST /api/v1/legal-entities/{legal_entity_id}/files (multipart, одно или несколько полей files; право DOCUMENT_EDIT; ЮЛ в области видимости пользователя, иначе 404) SHALL для каждого файла в отдельной транзакции: определить тип по расширению и сверить с сигнатурой содержимого (xls — BIFF8, xlsx/xlsb — zip, pdf, png, jpg); отвергнуть файл больше UPLOAD_MAX_BYTES (50 МиБ) или неподдерживаемого типа; вычислить sha256; создать s3_object (bucket_role = uploads, ключ uploads/{file_id}/{job_id}/{безопасное имя}, sha256, size_bytes, content_type, created_by = user:{id}), положить объект в S3, создать stored_file (status = UPLOADED, version_no = 1, uploaded_by, uploaded_at, content_hash, original_name) и recognition_job (status = queued, pipeline по типу: xls/xlsx/xlsb → tabular, pdf/png/jpg → image; max_attempts 3 / 1), установить stored_file.current_recognition_job_id, записать audit_event(FILE_UPLOAD, PRIMARY_DOCUMENTS). Ответ SHALL перечислять принятые файлы (accepted[] с file_id, job_id, name) и отклонённые (rejected[] с name, code, message); код ответа 201, если принят хотя бы один, иначе 422. Тип документа и период при загрузке MUST NOT запрашиваться (макет 40). Без доступного S3 — 503 STORAGE_UNAVAILABLE. Необязательный query-параметр consolidation_version_id SHALL проверяться до приёма файлов: версия видима (иначе 404 NOT_FOUND с сообщением VERSION_NOT_FOUND), статус «в работе» (иначе 409 VERSION_NOT_EDITABLE), ЮЛ ∈ периметру (иначе 422 ENTITY_NOT_IN_PERIMETER); если принят хотя бы один файл и версия в INITIATED, она SHALL перейти в DOCUMENTS_PROCESSING (changed_by = загрузивший) в отдельной транзакции после приёма файлов. Блокировка версии для загрузки MUST NOT требоваться.

Scenario: Реальная ОСВ принята и ушла в outbox

• WHEN ka_rf загружает rb/2024-FY/ОСВ_66 за 2024.xls для ЮЛ своего филиала
• THEN 201, accepted[0].file_id существует; stored_file.status = UPLOADED, file_type = XLS, content_hash = sha256 файла; recognition_job.status = queued, pipeline = tabular; объект в S3 по ключу uploads/{file_id}/{job_id}/ОСВ_66 за 2024.xls; публикатор outbox публикует запрос с этим ключом

Scenario: Смесь принятых и отклонённых

• WHEN в одном запросе xlsx, файл .docx и файл 51 МиБ
• THEN 201, accepted — один, rejected — два с кодами UNSUPPORTED_FILE и FILE_TOO_LARGE

Scenario: Расширение не совпадает с содержимым

• WHEN загружается файл osv.xlsx, байты которого — BIFF8
• THEN файл отклонён с кодом UNSUPPORTED_FILE

Scenario: Чужое ЮЛ

• WHEN ka_rf загружает файл для ЮЛ другого филиала
• THEN 404, объектов и записей нет

Scenario: Загрузка в контексте версии

• WHEN версия в INITIATED, ЮЛ в периметре, загружен один принятый файл с ?consolidation_version_id=
• THEN 201; версия в DOCUMENTS_PROCESSING, запись истории с changed_by = пользователь

Scenario: ЮЛ вне периметра

• WHEN consolidation_version_id указан, ЮЛ не в периметре версии
• THEN 422 ENTITY_NOT_IN_PERIMETER, файлы не приняты

Requirement: Дедуп по содержимому

Файл с тем же sha256, что у существующего stored_file того же ЮЛ со статусом не SUPERSEDED, SHALL отклоняться с кодом DUPLICATE_FILE и file_id существующего. Тот же файл у другого ЮЛ SHALL приниматься.

Scenario: Повторная загрузка того же файла

• WHEN тот же xls загружается во второй раз для того же ЮЛ
• THEN rejected[0].code = DUPLICATE_FILE, rejected[0].file_id — прежний файл; новых записей нет

Requirement: Жизненный цикл статуса файла

stored_file.status SHALL меняться только по заданию current_recognition_job_id: UPLOADED при загрузке; PROCESSING при ack сервиса; ERROR при финальной ошибке задания (error, timeout, dlq) и при невозможности маппинга; PROCESSED после успешного маппинга; SUPERSEDED при автозамене. Карточка файла SHALL показывать причину ERROR (error_code/error_message задания или ошибку маппинга).

Scenario: Парсер вернул ошибку

• WHEN конверт error UNSUPPORTED_FORMAT для задания файла
• THEN stored_file.status = ERROR, в карточке файла error_code = UNSUPPORTED_FORMAT

Scenario: Сервис не ответил

• WHEN задание переведено вахтёром в timeout
• THEN файл — ERROR с error_code = TIMEOUT

Requirement: Автозамена прежних версий

После успешного маппинга файла ядро SHALL найти другие файлы того же ЮЛ со статусом не SUPERSEDED, у которых есть документ с теми же document_type, osv_account_code, period_year, period_quarter, и перевести их в SUPERSEDED (superseded_by_file_id = новый файл, updated_at); новый файл получает version_no = максимум среди заменённых + 1. Документы и строки заменённых файлов SHALL сохраняться (история), но по умолчанию не показываться. Привязки consolidation_document документов заменённых файлов к версиям «в работе» SHALL удаляться в той же транзакции (версии блокируются FOR UPDATE по возрастанию id после старых файлов); привязки к версиям в других статусах не трогаются; статус версии не меняется. Аудит FILE_REPLACE (object_id заменённого, after_value с новым файлом и unbound_version_ids, в description — перечень заменённых документов и признак confirmed, если заменён документ CONFIRMED). Решение владельца 05.10.2026: замена происходит и для CONFIRMED. Замена остаётся на уровне файла (OQ-115), но если у заменённого файла есть документ, ключа которого (document_type, osv_account_code, period_year, period_quarter) нет среди документов нового файла (в т. ч. документ без года или квартала), ядро SHALL добавить в metrics.mapping_warnings задания нового файла (карточка файла, JobBrief.mapping_warnings) по одному предупреждению на заменённый файл (OQ-154): имя и версия заменённого файла, выпавшие документы (тип, счёт, период, статус — в т. ч. CONFIRMED) и версии консолидации «в работе», с которых сняты привязки этих документов. Поведение замены и статусы документов нового файла от предупреждения не меняются.

Scenario: Новая ОСВ 60 за 1 кв. 2025

• WHEN у ЮЛ есть PROCESSED файл с документом OSV 60 / 2025 / Q1 (CONFIRMED), загружен и смапплен новый файл с таким же документом
• THEN прежний файл — SUPERSEDED, superseded_by_file_id = новый, у нового version_no = 2; audit_event(FILE_REPLACE) с description, содержащим confirmed=true; список файлов ЮЛ по умолчанию показывает только новый

Scenario: Заменённый документ был в версии

• WHEN заменённый CONFIRMED документ ОСВ 60 за 2024 Q2 был привязан к версии 2024 Q3 в DATA_CORRECTION
• THEN привязка удалена; в чек-листе ячейка ОСВ 60 показывает missing_quarters = ["Q2"] (или NEEDS_CHECK по новому документу), пока новый документ не подтверждён; статус версии прежний

Scenario: Отдельный ОФР заменил книгу «ББ + ОФР»

• WHEN у ЮЛ есть файл с CONFIRMED ББ и ОФР за Q3 2025, ББ привязан к версии 2025 Q3 в DATA_CORRECTION; смаплен новый файл только с ОФР за Q3 2025
• THEN прежний файл — SUPERSEDED, привязка ББ снята; в metrics.mapping_warnings нового задания одно предупреждение: имя прежнего файла, BALANCE 2025 Q3 (CONFIRMED) и версия «ГК» 2025 Q3, версия 1; ОФР в предупреждении нет

Requirement: Удаление файла

DELETE /api/v1/files/{file_id} (DOCUMENT_EDIT, policy) SHALL удалить строки ОСВ, документы, задания и stored_file, проставить s3_object.expires_at = now() (объект физически не удаляется, OQ-22) и записать audit_event(FILE_DELETE, before_value = карточка файла, after_value = {unbound_version_ids}). Удаление MUST быть отклонено 409 FILE_HAS_CONFIRMED_DOCUMENTS, если у файла есть документ CONFIRMED, подтверждённый пользователем (confirmed_by не NULL), или если автоподтверждённый документ файла (confirmed_by NULL) привязан к версии в статусе, отличном от INITIATED, DOCUMENTS_PROCESSING, DATA_CORRECTION (OQ-157, уточняет OQ-110); и 409 FILE_SUPERSEDES_OTHERS, если на файл ссылаются superseded_by_file_id. При удалении файла с автоподтверждёнными документами их привязки consolidation_document SHALL сниматься, статус версий MUST NOT меняться, after_value.unbound_version_ids — id версий, где привязки сняты (по возрастанию; пустой список, если привязок не было). Блокировки: задания → файл → документы → advisory-блокировка привязок ГК → версии по id. Файл SUPERSEDED удалить можно.

Scenario: Удаление ошибочного файла

• WHEN файл в ERROR удаляется владельцем
• THEN 204; stored_file, recognition_job отсутствуют; s3_object.expires_at заполнен; audit_event(FILE_DELETE) с after_value.unbound_version_ids = []

Scenario: Подтверждённый документ

• WHEN удаляется файл с документом CONFIRMED, у которого confirmed_by = пользователь
• THEN 409 FILE_HAS_CONFIRMED_DOCUMENTS, ничего не изменилось

Scenario: Автоподтверждённый документ в корректировке

• WHEN версия 2025 Q1 в DATA_CORRECTION, к ней привязан автоподтверждённый документ ОСВ 60 РБ; файл удаляется
• THEN 204; привязка снята, версия осталась в DATA_CORRECTION; FILE_DELETE.after_value.unbound_version_ids = [id версии]

Scenario: Версия ушла на согласование

• WHEN автоподтверждённый документ файла привязан к версии в CONSOLIDATION_RF
• THEN 409 FILE_HAS_CONFIRMED_DOCUMENTS, привязка и файл на месте

Scenario: Автоподтверждённый без привязок

• WHEN удаляется файл, все документы которого автоподтверждены и ни к одной версии не привязаны
• THEN 204; after_value.unbound_version_ids = []