arm-core/openspec/changes/archive/2026-11-07-quality-metrics/proposal.md

Метрики качества первички (AURORA-1759, arm-core #190)

Зачем

Заказчику нужно подтверждать эффект инициативы АРМ КА цифрами, а не прикидками: какая доля ББ/ОФР/ОСВ доходит до результата без ручного ввода, сколько правят, что ломается. Вторая цель — иметь доказательную базу о качестве сервиса разбора PDF (ИС Сканирование): если цифры неудовлетворительны, это аргумент за смену сервиса, и он должен отделять ошибки сервиса от ошибок нашей нормализации и от дефектов самого документа клиента.

Что меняется

• Ядро записывает неизменяемые факты качества по каждому документу: на приёме результата («как распознано») и на исходе (подтверждён / удалён / заменён), а также факты технических отказов заданий распознавания. Факты самодостаточны (без FK на рабочие таблицы), переживают удаление и перераспознавание файла и лежат плоскими таблицами в отдельной схеме БД — их читает Superset платформы и переносит отдельное решение без доработки ядра.
• Каждая правка аналитика относится к источнику ошибки сравнением подтверждённого значения с сырым текстом сервиса: сервис разбора / наш разбор / документ клиента.
• Сырой ответ ИС Сканирование (raw/{job_id}.json) регистрируется в реестре S3 и хранится, пока на него ссылаются факты, — для будущего эталонного прогона новой нормализации.
• Признак «скан / цифровой PDF» определяется при загрузке.
• Экран «Качество первички» в веб-интерфейсе: матрица «источник × причина» за период и динамика по месяцам, переход из ячейки в список документов и в документ; выгрузка фактов. Отдельное право на просмотр.

Затронутые репозитории

• arm-ka-docs (отдельный change): DBML v5.25 (таблицы фактов, роль бакета raw, признак скана, право), правила подсчёта — новый раздел 05-domain-rules.md §14, контракт фактов docs/contracts/metrics/quality-facts.schema.json.
• arm-core (этот change): запись фактов, атрибуция правок, расчёт метрик, API, экран, право в seed.
• scan-gateway и tabular-parser не меняются.

Вне срезов 09-delivery-plan.md: спринт 3, эпик AURORA-1353.

Затрагиваемые таблицы DBML v5.25

recognition_job (ключ сырого ответа), s3_object / s3_bucket_role (роль raw), stored_file (признак скана), document, financial_statement_meta|column|line|value, osv_entry, document_issue, audit_event (читаются при записи фактов), permission_object (новый объект). Новые таблицы фактов — в DBML v5.25 до кода.

Non-goals

• Метрики по документам, загруженным до выкладки: считаем только новые.
• Время работы аналитика (визиты документа, активное / полное время) и пользовательские метрики интерфейса — в будущий раунд; факты ключуются по document_id, чтобы визиты потом присоединились.
• Отдельный счётчик «документ есть, но сервис его не разбирает» (ОСВ в PDF, расшифровки) — не отделить от технических отказов ББ/ОФР (решение владельца).
• Ограничение видимости метрик по филиалу / ГК — пока все видят всё.
• Сам эталонный прогон (перенормализация сохранённых сырых ответов) — этот change только сохраняет для него данные.
• Свой BI: Superset платформы читает факты напрямую.

Подробности и решения — design.md.