arm-core/openspec/specs/quality-metrics/spec.md

quality-metrics Specification

Purpose

Факты качества первички (приём «как распознано», исход, технический отказ), отнесение правок аналитика к источнику ошибки, матрица причин и API /quality-metrics с отдельным правом. Правила подсчёта — 05-domain-rules.md §14, модель — DBML v5.25, дизайн — design.md этого change.

Requirements

Requirement: Факты качества — отдельная схема, только добавление

Ядро SHALL хранить факты качества тремя плоскими таблицами quality_intake_fact, quality_outcome_fact, quality_failure_fact в отдельной схеме PostgreSQL (QUALITY_METRICS_SCHEMA, по умолчанию dkb_metrics; значение MUST отличаться от DB_SCHEMA). Таблицы MUST NOT иметь внешних ключей на рабочие таблицы: идентификаторы документов, файлов, заданий, ЮЛ и ГК — просто uuid, имена ЮЛ и ГК копируются на момент факта. Записи SHALL только добавляться (UPDATE и DELETE по фактам MUST NOT выполняться); payload — jsonb с payload_schema_version, форма по контракту quality-facts.schema.json. Факты пишутся только для документов, принятых после выкладки.

Scenario: Факт переживает удаление файла

• WHEN файл с документом, у которого есть факт приёма, удаляется
• THEN строки документа и файла удалены, а quality_intake_fact остаётся нетронутым

Scenario: Схема метрик совпала со схемой модели

• WHEN DB_SCHEMA и QUALITY_METRICS_SCHEMA заданы одним значением
• THEN приложение не стартует с ошибкой конфигурации

Requirement: Факт приёма «как распознано»

В транзакции маппинга результата, после map_file и до автоподтверждения, ядро SHALL записать по одному quality_intake_fact на каждый созданный документ BALANCE, INCOME, OSV (DISCLOSURE и OTHER факта не получают): измерения (ЮЛ и ГК с именами, тип документа, source_kind pdf/excel, is_scan для PDF, сервис и версии, intake_at, intake_status), счётчики строк, значений, нарушений и предупреждений, ключи S3, и payload со снимком «как распознано». Запись факта MUST NOT менять документы, статусы и результат маппинга.

Scenario: Приём ББ

• WHEN маппинг создал документ BALANCE из PDF
• THEN есть ровно один quality_intake_fact с document_id, source_kind = pdf, intake_status как у документа после маппинга и снимком строк и значений в payload

Scenario: Расшифровка не учитывается

• WHEN маппинг создал документ DISCLOSURE
• THEN факта приёма по нему нет

Requirement: Факт исхода документа

Ядро SHALL записать quality_outcome_fact в транзакции события, которое завершает документ: ручное подтверждение (CONFIRMED), автоподтверждение (AUTO_CONFIRMED), удаление файла (DELETED), автозамена файла (SUPERSEDED). Если документ на момент удаления или замены уже CONFIRMED, исход SHALL быть DELETED_AFTER_CONFIRM / SUPERSEDED_AFTER_CONFIRM. Факт содержит primary_cause, счётчики правок по источнику (service / ours / client), checks_accepted, число нарушений на момент исхода, подтверждённую отчётную дату. Повторное подтверждение ОСВ после правки SHALL писать новый факт; метрики берут последний факт документа.

Scenario: Автоподтверждение

• WHEN документ без замечаний автоподтверждён
• THEN факт с outcome = AUTO_CONFIRMED, primary_cause = WITHOUT_PARTICIPATION, confirmed_by пуст

Scenario: Удаление после подтверждения

• WHEN удаляется файл с автоподтверждённым документом
• THEN новый факт DELETED_AFTER_CONFIRM; прежний факт AUTO_CONFIRMED не изменён

Requirement: Факт технического отказа

Ядро SHALL записывать quality_failure_fact при переходе задания распознавания в error, timeout, dlq и при неповторяемой ошибке маппинга (файл → ERROR). failure_kind — SERVICE_ERROR / TIMEOUT / NO_ACK / MAPPING; error_code отказа маппинга — константа MAPPING_FAILED. Повторная обработка создаёт новое задание: отказ первой попытки остаётся фактом.

Scenario: Таймаут задания

• WHEN вахтёр переводит задание в timeout
• THEN есть факт failure_kind = TIMEOUT с job_id, file_id, failed_at

Requirement: Отнесение правки к источнику ошибки

Правка аналитика (отличие подтверждённого результата от снимка приёма) SHALL относиться к источнику чистой функцией без БД по правилу «верный ответ есть в сыром тексте сервиса — ошибка наша, иначе сервиса»: сумма, код строки, добавленная строка, поля шапки (отчётная дата сравнивается как дата после разбора parse_date), период и счёт ОСВ. Для Excel любая ошибка — «наш разбор». Спорные случаи и случаи без сырого текста SHALL относиться к «нашему разбору». Правки колонок дат и набор кодов сырого ответа для добавленных строк PDF в этом change не учитываются (отложено).

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

• WHEN аналитик исправил сумму, цифры которой совпадают с цифрами сырого текста
• THEN правка относится к «нашему разбору»

Scenario: Сервис ошибся

• WHEN подтверждённый код строки не извлекается из сырого текста кода
• THEN правка относится к «ошибке сервиса»

Requirement: Причина документа и матрица

Каждый документ с исходом SHALL попадать ровно в одну ячейку по первому сработавшему правилу: удалён/заменён до подтверждения; удалён/заменён после подтверждения; есть правки «сервис» → ошибка сервиса; есть правки «наш разбор» → наш разбор; ручное подтверждение с акцептом жёстких нарушений → документ клиента; AUTO_CONFIRMED → без участия; иначе → как есть. Документы без исхода — «в работе». Доли считаются от документов с исходом AUTO_CONFIRMED / CONFIRMED; удалённые, заменённые и «в работе» в знаменатель не входят. Технические отказы считаются по файлам своей долей. Расчёт — чистая функция от фактов, в БД не хранится; последний факт документа выбирается по времени исхода, при равенстве — детерминированно.

Scenario: Документ с правкой сервиса и клиента

• WHEN у подтверждённого документа есть правка «сервис» и акцепт нарушений
• THEN документ в ячейке «ошибка сервиса», счётчики обеих сторон сохранены в факте

Scenario: Нулевой знаменатель

• WHEN за период нет документов с исходом
• THEN доли равны 0, denominator = 0

Requirement: API метрик качества

Система SHALL предоставлять под правом QUALITY_METRICS_VIEW маршруты /api/v1/quality-metrics: GET /matrix (матрица за период с фильтрами период по дате приёма, ГК, ЮЛ, тип, источник, скан/цифровой, отказы по файлам, счётчик уникальных отчётов), GET /series (ряд по месяцам даты приёма для причины, пропущенные месяцы — нули), GET /cells/{cell}/documents (постраничный список документов ячейки со счётчиками правок, ссылкой на документ, если он существует, и confirmed_by), GET /export (факты за период, CSV с BOM и JSON; значения, начинающиеся с символов формулы, экранируются). Выгрузка SHALL писать audit_event(EXPORT) с object_type = quality_metrics и фильтрами. Агрегаты MUST NOT содержать фамилий пользователей.

Scenario: Матрица без права

• WHEN пользователь без QUALITY_METRICS_VIEW запрашивает /quality-metrics/matrix
• THEN 403

Scenario: Выгрузка оставляет след

• WHEN пользователь выгружает факты за период
• THEN записан audit_event(EXPORT) с форматом, фильтрами и числом строк

Requirement: Право QUALITY_METRICS_VIEW

Объект QUALITY_METRICS в permission_object и право QUALITY_METRICS_VIEW SHALL быть в seed и выдаваться всем ролям; позже права сужаются данными (role_permission) без изменения кода. Видимость по филиалу и ГК не применяется.

Scenario: Право у всех ролей

• WHEN выполнен make seed на чистой БД
• THEN GET /me любой роли содержит QUALITY_METRICS_VIEW