2676dfd731
OQ-179 (срок хранения raw/{job_id}.json), роль raw и dkb_metrics в 03-architecture.md,
openspec proposal/design/specs, план реализации (AURORA-1759).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
66 lines
6.2 KiB
Markdown
66 lines
6.2 KiB
Markdown
# 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`, отказ от ретеншна).
|
||
- Ограничение видимости метрик по филиалу/ГК — пока все роли видят всё.
|