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

Proposal: Метрики качества первички (AURORA-1759)

Срез: вне docs/context/09-delivery-plan.md (спринт AWPCA_Sprint_3_Corrections, эпик AURORA-1353). Репозиторий: arm-ka-docs (сквозная часть — модель данных). Issue: RSHB/arm-ka-docs#202. Дочерние change'и: arm-core/openspec/changes/quality-metrics (arm-core#190) — запись фактов, атрибуция, API, экран. tabular-parser и scan-gateway не меняются.

Полное обоснование и все решения владельца — ../../arm-core/openspec/changes/quality-metrics/design.md (брейнсторминг 27.10.2026, подтверждено владельцем 05.11.2026). Этот change переносит из него в модель данных только то, что становится структурой: таблицы, перечисления, столбцы, контракт payload, правила подсчёта.

Why

Заказчику нужно подтверждать эффект АРМ КА цифрами (доля ББ/ОФР, дошедшая без правок), владельцу — доказательная база о качестве сервиса разбора PDF с разделением «ошибка сервиса / наша нормализация / документ клиента». Ядро сейчас не хранит ничего для этого: document/financial_statement_* переписываются при правке и перестройке, подтверждённый результат недоступен после следующей правки, сырой ответ ИС Сканирование не регистрируется в БД (решение v5.13, отменяется этим change).

What Changes

• Три новые таблицы фактов (плоские, append-only, без FK на рабочие таблицы, отдельная схема PostgreSQL dkb_metrics — имя настройка): quality_intake_fact (документ «как распознано», пишется в момент маппинга), quality_outcome_fact (исход: автоподтверждён / подтверждён / удалён / заменён — в т. ч. после подтверждения — с атрибуцией правок и причиной попадания в ячейку матрицы), quality_failure_fact (технический отказ задания распознавания). Точные столбцы — design.md §1.
• s3_bucket_role: новое значение raw — сырой ответ ИС Сканирование (raw/{job_id}.json) регистрируется в s3_object, не удаляется вместе с файлом (вход для будущего эталонного прогона, ASSUMPTION(OQ-179) — срок хранения решает платформа).
• recognition_job.raw_s3_object_id — ссылка на зарегистрированный сырой ответ (image pipeline).
• stored_file.is_scan — признак скан/цифровой PDF, определяется при загрузке по текстовому слою.
• permission_object: новое значение QUALITY_METRICS — объект права для экрана (действие VIEW, право QUALITY_METRICS_VIEW; seed — в arm-core).
• docs/contracts/metrics/quality-facts.schema.json — JSON Schema payload (jsonb) трёх фактов.
• docs/context/05-domain-rules.md §14 — счёт документов/матрица причин, правило атрибуции правки (сервис/наш разбор), правило «документ клиента» (акцепт жёстких нарушений), признак скана.

Capabilities

New Capabilities

• quality-metrics-model: модель данных и контракт фактов качества распознавания первички — какие факты пишутся, в каком формате, как считается матрица причин.

Modified Capabilities

Impact

• Пишет факты только arm-core (единственный писатель в БД, см. ../CLAUDE.md). Читает — Superset платформы отдельной read-only ролью к схеме dkb_metrics (создаёт платформа, описание в 03-architecture.md).
• Таблицы DBML v5.24, которые это затрагивает: recognition_job, s3_object, s3_bucket_role, stored_file, document, financial_statement_meta/column/line/value, osv_entry, document_issue, permission_object. Новых FK на них из таблиц фактов нет (факты самодостаточны).
• Миграция Alembic — в arm-core (общая цепочка, не в этом репозитории).

Non-goals

• Метрики по документам до выкладки фичи (ретро-подсчёт) — не считаем.
• Время работы аналитика (визиты документа) — будущий раунд; факты уже ключуются document_id для последующего присоединения.
• Отдельный счётчик «документ есть, но сервис его не разбирает» — не отделить от технических отказов (решение владельца 27.10.2026).
• Сам эталонный прогон перенормализации сохранённых сырых ответов — этот change только обеспечивает вход (хранение raw/{job_id}.json, отказ от ретеншна).
• Ограничение видимости метрик по филиалу/ГК — пока все роли видят всё.