# CHECK Validation Run Accounting Analytics — Result (2026-03-23)

## Scope

Выполнен ремонт ontology/mapping слоя по чек-листу `IN/CHEK_Validation_Run_Accounting_Analytics.md`:

1. Расширены canonical entity classes под недостающие доменные роли.
2. Переписан mapper на semantic-v2 подход:
   - entity type resolver (с приоритетом `*_Type`);
   - relation resolver (role/context-aware relations вместо одного `reference`);
   - null GUID filter;
   - composite source id builder.
3. Проведён re-map июньского snapshot 2020 и повторный validation-run.

## Implemented changes

### 1) Canonical model expansion

Добавлены классы:

- `ResponsiblePerson`
- `Currency`
- `Warehouse`
- `CashflowArticle`
- `Department`
- `Individual`
- `Item`
- `BankAccount`
- `InvoiceDocument`
- `RegisterRecord`

Файл: `canonical_layer/models.py`

### 2) Mapper architecture refactor

Файл: `canonical_layer/mappers.py`

Ключевые изменения:

- `map_record` больше не оставляет пустые/unknown `source_id`:
  - сначала пробует `Ref_Key/Ref/ID/...`,
  - затем строит `cmp:<sha1>` составной id по стабильному payload.
- links строятся через semantic resolvers:
  - `register_recorded_by_document`
  - `journal_refers_to_document`
  - `document_has_counterparty`
  - `document_has_contract`
  - `document_belongs_to_organization`
  - `document_has_currency`
  - `document_has_responsible`
  - `register_relates_to_supplier`
  - `register_relates_to_buyer`
  - `register_relates_to_invoice`
  - и др.
- `*_Type` используется как приоритетный target type hint.
- `00000000-0000-0000-0000-000000000000` фильтруется из canonical links.
- Добавлен `canonical_relation_rule_catalog()` для прозрачной выгрузки правил.

### 3) Regression tests

Файл: `tests/test_mappers.py` (переписан)

Проверки включают:

- document counterparty relation;
- register composite source id;
- journal `Ref` -> document relation;
- supplier/buyer role typing;
- `СчетФактура` -> `InvoiceDocument` (без ложного `Account`);
- zero-GUID filtering.

Статус тестов:

- `python -m pytest -q` -> `17 passed`

## Re-map and validation results

### Re-map command

`python scripts/remap_snapshot_semantic_v2.py`

Артефакты:

- `logs/pre_report_snapshot_2020_2020-06_semantic_v2.json`
- `logs/pre_report_snapshot_2020_2020-06_semantic_v2_metrics.json`

### Before vs after (snapshot-level metrics)

- `source_id_unknown`: `358 -> 0`
- `unknown_links`: `1016 -> 102`
- `semantic_coverage_pct`: `61.1917 -> 94.9279`
- `relation_types_total`: `1 -> 25`

### Validation run on semantic-v2 snapshot

Команда:

`python scripts/run_validation_accounting_analytics.py --snapshot-path logs/pre_report_snapshot_2020_2020-06_semantic_v2.json --output-dir docs/ARCH/validation_run_2026-03-23_semantic_v2 --strict`

Папка результатов:

- `docs/ARCH/validation_run_2026-03-23_semantic_v2/`

Ключевые ontology-аудит метрики:

- `covered_entity_classes`: `33 -> 42`
- `uncovered_entity_classes`: `9 -> 0`
- `unknown_relations`: `1016 -> 102`
- `semantic_coverage_pct`: `61.1917 -> 94.9279`
- `relation_types_total`: `1 -> 25`

## Export package refresh

Обновлён пакет `docs/ARCH/2020экспорт` на базе semantic-v2 snapshot:

- `01_ontology_mapping_layer.md` (обновлённые классы/метрики)
- `02_canonical_relation_rules.md` (каталог semantic relations из маппера)
- все sample/json файлы перегенерированы

Команда:

`python scripts/export_arch_2020_package.py`

## Remaining gap (post-fix)

Топ остаточных unknown-полей после semantic-v2:

- `ВидОперации`
- `Информация`
- `СубконтоДт1`
- `Руководитель_Key`
- `ГлавныйБухгалтер_Key`

Следующий шаг:

- добавить точечные semantic rules для перечисленных полей;
- отдельно закрыть `Subconto*` mapping в детальный typed-slot слой;
- после этого повторить remap + validation и зафиксировать delta.
