arm-core/openspec/changes/quality-metrics/specs/documents-api/spec.md

Spec Delta

Purpose

Дельта change quality-metrics (метрики качества первички).

MODIFIED Requirements

Requirement: Подтверждение документа

POST /api/v1/documents/{document_id}/confirm (DOCUMENT_EDIT, policy) SHALL переводить документ из RECOGNIZED или NEEDS_CHECK в CONFIRMED (confirmed_by, confirmed_at) с audit_event(DOCUMENT_CONFIRM, PRIMARY_DOCUMENTS); из CONFIRMED повторно — 409 ALREADY_CONFIRMED; документ файла SUPERSEDED — 409 FILE_SUPERSEDED; документ в любом другом статусе (например, ERROR) — 409 DOCUMENT_NOT_CONFIRMABLE. Для BALANCE/INCOME дополнительно: пустые period_year или period_quarter — 409 PERIOD_REQUIRED; строки unreadable / missing с непустой суммой или текстом значения — 409 LINES_UNRESOLVED (detail.lines[] {line_id, row_index, line_code_text}); вторая подтверждённая форма того же типа и периода в файле — 409 DUPLICATE_FORM (detail.document_id); записи document_issue вида relation без акцепта — 409 CHECKS_NOT_PASSED со списком нарушений в detail.failures; при подтверждении SHALL записываться financial_statement_meta.reviewed_by/at. Несовпадение контрагента и уверенность значений подтверждение MUST NOT блокировать. Если совпали несколько условий, порядок: FILE_SUPERSEDED, ALREADY_CONFIRMED, DOCUMENT_NOT_CONFIRMABLE, PERIOD_REQUIRED, LINES_UNRESOLVED, DUPLICATE_FORM, CHECKS_NOT_PASSED. Подтверждение берёт блокировки в порядке «файл → документ → (advisory-блокировка привязок ГК) → версии консолидации (по возрастанию id)»: файл — FOR UPDATE, документ — FOR NO KEY UPDATE (R-3; совместима со вставкой привязки FOR KEY SHARE), версии — FOR UPDATE; состояние перечитывается под этими блокировками; документ или файл, исчезнувшие за время ожидания блокировки, — 404 NOT_FOUND. В той же транзакции документ SHALL привязываться (consolidation_document) ко всем версиям «в работе» (INITIATED, DOCUMENTS_PROCESSING, DATA_CORRECTION), которым он подходит: ЮЛ документа ∈ consolidation_member версии, period_year = год версии, period_quarter не NULL и (is_cumulative true или NULL → period_quarter = квартал версии; false → period_quarter ≤ квартала версии). ОСВ за Q1 равнозначна нарастающей и квартальной (R-14): она подходит любой версии года при любом is_cumulative; ББ/ОФР за Q1 — отчёт на конец квартала и подходят только версии за Q1 (R-14a). Привязанный ранее документ того же ЮЛ с тем же ключом (document_type, osv_account_code, period_quarter, признак нарастающего: is_cumulative true или NULL; для ОСВ за Q1 признак не различается) в той же версии SHALL отвязываться (R-1). Каждая версия, получившая привязку, из INITIATED или DOCUMENTS_PROCESSING SHALL переходить в DATA_CORRECTION (changed_by = подтвердивший). Блокировка версии (consolidation_lock) для подтверждения MUST NOT требоваться. В той же транзакции ручное подтверждение документа BALANCE / INCOME / OSV SHALL записывать quality_outcome_fact (outcome = CONFIRMED) с отнесением правок по живым колонкам документа (is_modified, original_*, source_text), а не по payload приёма; checks_accepted — признак акцепта проверок шапкой (на ячейку матрицы не влияет: при правках приоритет у «сервиса» и «нашего разбора»). DISCLOSURE / OTHER факта не получают.

Scenario: Причина ошибки маппинга в карточке файла

• WHEN файл в ERROR после неудачного маппинга (задание done, error_code пуст)
• THEN job.mapping_error содержит причину, job.error_code пуст

Scenario: Документ не подтверждается

• WHEN подтверждается документ в статусе ERROR
• THEN 409 DOCUMENT_NOT_CONFIRMABLE, статус не изменился

Scenario: Подтверждение

• WHEN ka_rf подтверждает документ NEEDS_CHECK своего филиала
• THEN status = CONFIRMED, confirmed_by = пользователь, audit_event(DOCUMENT_CONFIRM) с before_value.status = NEEDS_CHECK

Scenario: Привязка к версии и переход статуса

• WHEN версия ГК 2024 Q3 в INITIATED с ЮЛ в периметре; подтверждается квартальная ОСВ 60 этого ЮЛ за 2024 Q2
• THEN consolidation_document(version, document) создан; версия в DATA_CORRECTION; запись истории INITIATED → DATA_CORRECTION с changed_by = пользователь

Scenario: Не подходит по периоду

• WHEN подтверждается нарастающая ОСВ 60 за 2024 Q2 при версии за 2024 Q3
• THEN привязки нет, статус версии не изменился

Scenario: Версия в CANCELLED

• WHEN подходящий документ подтверждается при версии CANCELLED
• THEN привязки нет

Scenario: Форма с нарушением проверок

• WHEN подтверждается BALANCE с непройденным жёстким соотношением без акцепта
• THEN 409 CHECKS_NOT_PASSED, в detail.failures — нарушение; после акцепта подтверждение проходит

Scenario: Форма без периода

• WHEN подтверждается форма из OCR, у которой нет ни даты отчёта, ни дат колонок
• THEN 409 PERIOD_REQUIRED; после правки даты отчёта подтверждение проходит

Scenario: Форма в чек-листе

• WHEN версия ГК 2025 Q3 INITIATED, ЮЛ в периметре; подтверждается его BALANCE за 2025 Q3
• THEN привязка создана, ячейка «Бух. баланс» чек-листа ЮЛ — CONFIRMED, reviewed_by шапки = пользователь

Scenario: Неразобранная строка с суммой

• WHEN у формы строка missing с суммой и одновременно жёсткое нарушение
• THEN 409 LINES_UNRESOLVED с этой строкой в detail.lines

Scenario: Неразобранная строка только с текстом

• WHEN у формы строка unreadable без сумм, но с мусором 211(1 | в ячейке значения (string_value)
• THEN 409 LINES_UNRESOLVED — потерянная сумма тоже требует разбора

Scenario: Вторая форма того же периода

• WHEN в файле два ББ на 30.09.2025, первый подтверждён, аналитик подтверждает второй
• THEN 409 DUPLICATE_FORM со ссылкой на первый

Scenario: Подтверждение с правкой суммы

• WHEN аналитик исправил сумму и подтвердил ББ
• THEN записан quality_outcome_fact CONFIRMED со счётчиком правки значения по источнику и payload.fixes