RSHB/arm-ka-docs
9
0
Fork 0
Code Issues 17 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

DBML v5.25: факты качества первички (AURORA-1759) #203

Closed
aep wants to merge 0 commits from feat/202-quality-metrics-dbml into main
pull from: feat/202-quality-metrics-dbml
merge into: RSHB:main
Conversation 2 Commits - Files Changed -
aep commented 2026-11-05 14:04:22 +03:00
Owner
Copy Link

Closes #202. Jira: AURORA-1759 (arm-core #190 реализует код по этой модели).

Что сделано

  • Три новые append-only таблицы фактов без FK на рабочие таблицы: quality_intake_fact, quality_outcome_fact, quality_failure_fact (отдельная схема dkb_metrics).
  • s3_bucket_role.raw, recognition_job.raw_s3_object_id (сырой ответ ИС Сканирование теперь регистрируется — отменяет решение v5.13), stored_file.is_scan, permission_object.QUALITY_METRICS.
  • entities-v5.25.md, context/05-domain-rules.md §14 (счёт документов, атрибуция правки сервис/наш разбор, причина ячейки матрицы, технические отказы, признак скана), contracts/quality-facts.schema.json.
  • OQ-179 (срок хранения raw/{job_id}.json), правки 03-architecture.md, openspec change quality-metrics (proposal/design/specs), план реализации.
  • Полный WHY и решения владельца — arm-core/openspec/changes/quality-metrics/design.md §1-3, §10 (брейнсторминг 27.10, подтверждено 05.11).

Проверки

openspec validate quality-metrics --strict, make check, make diagrams DBML=model/data-model-v5.25.dbml — зелёные.

Ревью ветки (opus, фоновый агент)

Assessment: With fixes. 1 critical + 5 important исправлены одним проходом (коммит 8abbf50):

  • stored_file.is_scan был описан наоборот (true=цифровой вместо true=скан) — противоречил §14.6 и имени столбца.
  • §14 не говорил явно, что ОСВ не получает lines/values в payload — добавили и текст, и dependentSchemas в контракте.
  • §14.3 не говорил, что quality_outcome_fact.document_id не unique и метрики берут последний факт по outcome_at.
  • values[].amount был number вместо decimal-строки (как money в recognition-result.schema.json) — деньги не float.
  • Правка «дата колонки» не имела счётчика — явно отнесена к fixes_header_*.
  • Правило ретеншна S3 при удалении файла было несогласовано между domain-rules/architecture/spec.md (экспирится ли uploads, на который ссылается факт) — согласовано на «не экспирится ни raw, ни такой uploads» (OQ-179).

Rulings I made

  • R-1: quality_cause — отдельный enum-столбец (денормализация §6 вместо вычисления на лету). Цена ошибки: расхождение сохранённого значения с правилом §14, если правило изменится — старые факты не пересчитываются (ожидаемо для append-only).
  • R-2: Атрибуция правок — 2 источника (service/ours), не 3; «документ клиента» — свойство исхода, не правки. Цена ошибки: лишний enum-источник, если окажется нужен позже.
  • R-3: quality-facts.schema.json не подключается к scripts/validate_contracts.py (он жёстко завязан на NATS-контракт). Цена ошибки: изменение payload не поймает make check здесь — ловит тест arm-core.
  • R-4: legal_entity_name/group_name добавлены и в quality_failure_fact, хотя design arm-core §4.3 их не перечис��ял (общее правило §4 — копировать имена во все факты). Цена ошибки: 2 лишних столбца, если экран всё же джойнит live-справочник для отказов.
  • R-5 (отклонено ревьюером, решение не моё): является ли исключение *_AFTER_CONFIRM из матрицы правильным — решение владельца в arm-core design §4.2/§10, не пересматривалось здесь.

Deferred minors (из финального ревью)

issues[].level смешивает kind/severity; payload-схемы без required; фрагменты #intake-payload/#outcome-payload без $anchor; противоречивая фраза в Note quality_outcome_fact; 3 новых enum не в таблице изменений entities; допущение о скрытом OCR-слое без своего OQ; Note s3_object не упоминает raw; design.md §2 обещает 3 $id, реализовано 2 без $id; payload_schema_version nullable при payload not null.

Closes #202. Jira: AURORA-1759 (arm-core #190 реализует код по этой модели). ## Что сделано - Три новые append-only таблицы фактов без FK на рабочие таблицы: `quality_intake_fact`, `quality_outcome_fact`, `quality_failure_fact` (отдельная схема `dkb_metrics`). - `s3_bucket_role.raw`, `recognition_job.raw_s3_object_id` (сырой ответ ИС Сканирование теперь регистрируется — отменяет решение v5.13), `stored_file.is_scan`, `permission_object.QUALITY_METRICS`. - `entities-v5.25.md`, `context/05-domain-rules.md` §14 (счёт документов, атрибуция правки сервис/наш разбор, причина ячейки матрицы, технические отказы, признак скана), `contracts/quality-facts.schema.json`. - OQ-179 (срок хранения `raw/{job_id}.json`), правки `03-architecture.md`, openspec change `quality-metrics` (proposal/design/specs), план реализации. - Полный WHY и решения владельца — `arm-core/openspec/changes/quality-metrics/design.md` §1-3, §10 (брейнсторминг 27.10, подтверждено 05.11). ## Проверки `openspec validate quality-metrics --strict`, `make check`, `make diagrams DBML=model/data-model-v5.25.dbml` — зелёные. ## Ревью ветки (opus, фоновый агент) Assessment: With fixes. 1 critical + 5 important исправлены одним проходом (коммит 8abbf50): - `stored_file.is_scan` был описан наоборот (true=цифровой вместо true=скан) — противоречил §14.6 и имени столбца. - §14 не говорил явно, что ОСВ не получает `lines`/`values` в payload — добавили и текст, и `dependentSchemas` в контракте. - §14.3 не говорил, что `quality_outcome_fact.document_id` не unique и метрики берут последний факт по `outcome_at`. - `values[].amount` был `number` вместо decimal-строки (как `money` в `recognition-result.schema.json`) — деньги не float. - Правка «дата колонки» не имела счётчика — явно отнесена к `fixes_header_*`. - Правило ретеншна S3 при удалении файла было несогласовано между domain-rules/architecture/spec.md (экспирится ли `uploads`, на который ссылается факт) — согласовано на «не экспирится ни `raw`, ни такой `uploads`» (OQ-179). ## Rulings I made - R-1: `quality_cause` — отдельный enum-столбец (денормализация §6 вместо вычисления на лету). Цена ошибки: расхождение сохранённого значения с правилом §14, если правило изменится — старые факты не пересчитываются (ожидаемо для append-only). - R-2: Атрибуция правок — 2 источника (service/ours), не 3; «документ клиента» — свойство исхода, не правки. Цена ошибки: лишний enum-источник, если окажется нужен позже. - R-3: `quality-facts.schema.json` не подключается к `scripts/validate_contracts.py` (он жёстко завязан на NATS-контракт). Цена ошибки: изменение payload не поймает `make check` здесь — ловит тест arm-core. - R-4: `legal_entity_name`/`group_name` добавлены и в `quality_failure_fact`, хотя design arm-core §4.3 их не перечис��ял (общее правило §4 — копировать имена во все факты). Цена ошибки: 2 лишних столбца, если экран всё же джойнит live-справочник для отказов. - R-5 (отклонено ревьюером, решение не моё): является ли исключение `*_AFTER_CONFIRM` из матрицы правильным — решение владельца в arm-core design §4.2/§10, не пересматривалось здесь. ## Deferred minors (из финального ревью) `issues[].level` смешивает kind/severity; payload-схемы без `required`; фрагменты `#intake-payload`/`#outcome-payload` без `$anchor`; противоречивая фраза в Note `quality_outcome_fact`; 3 новых enum не в таблице изменений entities; допущение о скрытом OCR-слое без своего OQ; Note `s3_object` не упоминает `raw`; design.md §2 обещает 3 $id, реализовано 2 без $id; `payload_schema_version` nullable при `payload` not null.
aep added 6 commits 2026-11-05 14:04:25 +03:00 
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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>
Критично: stored_file.is_scan был описан наоборот (true = цифровой вместо true = скан),
противоречил §14.6 и собственному имени столбца.

Важно: §14 не говорил явно, что ОСВ не получает lines/values в payload (теперь
dependentSchemas в контракте это ещё и проверяет); §14.3 не говорил, что
quality_outcome_fact.document_id не unique и метрики берут последний факт; амount в
контракте был float вместо decimal-строки (как money в recognition-result.schema.json);
правка "дата колонки" не имела счётчика — явно отнесена к fixes_header_*; правило
хранения S3 при удалении файла (OQ-179) не было согласовано между domain-rules,
architecture и spec.md (spec.md ошибочно утверждал, что uploads экспирится в отличие
от raw — не экспирится ни то, ни другое, если на них ссылается факт).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
aep added 6 commits 2026-11-07 03:32:50 +03:00 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
aep commented 2026-11-07 03:33:19 +03:00
Author
Owner
Copy Link

Обновление после ревью arm-core (feat/190-ocr-metrics):

  • контракт перенесён в contracts/metrics/quality-facts.schema.json (чтобы не требовать копии в tabular-parser и scan-gateway); is_recognized теперь ["boolean","null"];
  • DBML v5.25: stored_file.is_scan и recognition_job.raw_s3_object_id — последние колонки таблиц (версия не менялась);
  • 05-domain-rules.md §10: добавлен объект/право QUALITY_METRICS_VIEW (17 прав);
  • влит origin/main (конфликтов нет).
    Порядок merge: этот PR раньше arm-core.
Обновление после ревью arm-core (feat/190-ocr-metrics): - контракт перенесён в `contracts/metrics/quality-facts.schema.json` (чтобы не требовать копии в tabular-parser и scan-gateway); `is_recognized` теперь `["boolean","null"]`; - DBML v5.25: `stored_file.is_scan` и `recognition_job.raw_s3_object_id` — последние колонки таблиц (версия не менялась); - `05-domain-rules.md` §10: добавлен объект/право `QUALITY_METRICS_VIEW` (17 прав); - влит origin/main (конфликтов нет). Порядок merge: этот PR раньше arm-core.
aep commented 2026-11-07 07:52:49 +03:00
Author
Owner
Copy Link

Слито в main merge-коммитом d3386b7: Gitea оборвала ответ на merge, PR остался открытым. Закрываю вручную. Архив change — #212.

Слито в main merge-коммитом d3386b7: Gitea оборвала ответ на merge, PR остался открытым. Закрываю вручную. Архив change — #212.
aep closed this pull request 2026-11-07 07:52:50 +03:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
PotapovaA Raykov-MS SalminMP Veronika Yashin1994 aep grog maxim tsygankoviva
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: RSHB/arm-ka-docs#203
No description provided.
Delete Branch "feat/202-quality-metrics-dbml"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?