# 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/quality-facts.schema.json`** — JSON Schema payload (jsonb) трёх фактов.
- **`docs/context/05-domain-rules.md` §14** — счёт документов/матрица причин, правило атрибуции правки
  (сервис/наш разбор), правило «документ клиента» (акцепт жёстких нарушений), признак скана.

## Capabilities

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

### Modified Capabilities
<!-- openspec/specs пуст для этой области — изменяемых capability нет -->

## 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`, отказ от ретеншна).
- Ограничение видимости метрик по филиалу/ГК — пока все роли видят всё.