237 lines
8.6 KiB
Markdown
237 lines
8.6 KiB
Markdown
# 1C Business Event Layer
|
||
|
||
Это следующий production-шаг поверх уже работающего контура
|
||
`file 1C -> ClickHouse -> Grafana -> AI Investigator`.
|
||
|
||
Цель не в том, чтобы заменить текущий `company intelligence`, а в том, чтобы
|
||
добавить **read-only business-event слой**, пригодный для финансовых
|
||
расследований, explainability и rule-based detections по бухгалтерскому смыслу.
|
||
|
||
## Почему этот слой нужен
|
||
|
||
Текущий контур уже решает:
|
||
|
||
- operational telemetry;
|
||
- timeline по reglog/audit;
|
||
- detections/cases;
|
||
- company portfolio intelligence;
|
||
- manager/recovery briefs.
|
||
|
||
Но он ещё не даёт полноценного ответа на вопросы уровня:
|
||
|
||
- какие проводки дали вклад в аномалию;
|
||
- кто и когда перепровёл документ;
|
||
- какие изменения реквизитов повлияли на результат;
|
||
- почему вырос НДС, возвраты или нетипичные движения.
|
||
|
||
Для этого нужен отдельный канонический слой бизнес-событий.
|
||
|
||
## Слои данных
|
||
|
||
### 1. `documents`
|
||
|
||
Карточки документов и базовые агрегаты по документам.
|
||
|
||
### 2. `postings`
|
||
|
||
Лёгкий слой проводок/движений. Уже есть в контуре, но он недостаточен как
|
||
канонический event stream.
|
||
|
||
### 3. `business_events`
|
||
|
||
Новый целевой канонический слой. Один ряд = одно бизнес-событие, пригодное для:
|
||
|
||
- timeline;
|
||
- detections;
|
||
- explainability;
|
||
- AI investigations;
|
||
- correlation с reglog/audit/cases.
|
||
|
||
Текущая schema scaffold:
|
||
|
||
- `ts`
|
||
- `event_id`
|
||
- `infobase`
|
||
- `company_entity_key`
|
||
- `organization`
|
||
- `department`
|
||
- `document_id`
|
||
- `document_number`
|
||
- `document_type`
|
||
- `registrar`
|
||
- `operation_type`
|
||
- `event_kind`
|
||
- `user`
|
||
- `counterparty`
|
||
- `counterparty_inn`
|
||
- `debit_account`
|
||
- `credit_account`
|
||
- `amount`
|
||
- `currency`
|
||
- `line_no`
|
||
- `evidence_ref`
|
||
- `source_file`
|
||
|
||
### 4. `document_change_events`
|
||
|
||
Новый слой изменений документов и реквизитов.
|
||
|
||
Нужен для:
|
||
|
||
- расследования перепроведений;
|
||
- контроля изменений реквизитов;
|
||
- reconstruction narrative;
|
||
- объяснения, какие именно изменения дали бизнес-эффект.
|
||
|
||
Текущая schema scaffold:
|
||
|
||
- `ts`
|
||
- `change_id`
|
||
- `infobase`
|
||
- `company_entity_key`
|
||
- `organization`
|
||
- `document_id`
|
||
- `document_number`
|
||
- `document_type`
|
||
- `change_kind`
|
||
- `field_name`
|
||
- `user`
|
||
- `before_value`
|
||
- `after_value`
|
||
- `risk_tag`
|
||
- `evidence_ref`
|
||
- `source_file`
|
||
|
||
## Read-only extraction path
|
||
|
||
Правильный extraction path такой:
|
||
|
||
1. Внешний extractor читает только безопасные read-only источники.
|
||
2. Формирует `jsonl/csv` в landing-каталоги.
|
||
3. `etl/load_1c_exports.py` грузит данные в raw/core ClickHouse tables.
|
||
4. Detection/AI слой работает только с ClickHouse.
|
||
|
||
То есть LLM и manager pages не ходят в 1С напрямую.
|
||
|
||
## Безопасные источники для extractor
|
||
|
||
Подходящие:
|
||
|
||
- регламентированные выгрузки документов/движений;
|
||
- журнал регистрации 1С;
|
||
- внешние реестры и справочники;
|
||
- audit/export критичных изменений;
|
||
- отдельные read-only файлы, формируемые рядом с 1С.
|
||
- `1c-mcp-toolkit` REST API через `execute_query` и `get_event_log`.
|
||
|
||
Не подходящие по умолчанию:
|
||
|
||
- запись в файловую базу;
|
||
- опасные `COM`/`Configurator` сценарии;
|
||
- любой write-back path в production 1С.
|
||
|
||
## Почему здесь нужен `company_entity_key`
|
||
|
||
Этот слой не должен зависеть от того, как компания названа в текущий момент в
|
||
1С. Поэтому новые event tables уже сразу завязаны на `company_entity_key`.
|
||
|
||
Приоритет идентификации:
|
||
|
||
1. `baseid:<base_id>`
|
||
2. `basepath:<normalized path>`
|
||
3. только fallback на human name
|
||
|
||
Это делает timeline и расследования устойчивыми к rename.
|
||
|
||
## Что extractor должен уметь первым
|
||
|
||
Минимальный read-only extractor v1 должен уметь:
|
||
|
||
- выгружать документы;
|
||
- выгружать проводки;
|
||
- выгружать `business_events`;
|
||
- выгружать `document_change_events`;
|
||
- стабильно наполнять `company_entity_key`;
|
||
- писать `evidence_ref`, чтобы расследование не было бездоказательным.
|
||
|
||
## Первые детекты на этом слое
|
||
|
||
После появления business-event выгрузок стоит вводить:
|
||
|
||
- ночные проводки;
|
||
- дробление платежей;
|
||
- повторные перепроведения;
|
||
- изменение реквизитов перед/после движения;
|
||
- возвраты после закрытия периода;
|
||
- нехарактерные движения по пользователю;
|
||
- циклические движения по контрагенту/счётам.
|
||
|
||
## Что уже сделано в репо
|
||
|
||
Уже добавлены:
|
||
|
||
- raw tables:
|
||
- `raw_1c_business_events`
|
||
- `raw_1c_document_changes`
|
||
- core tables:
|
||
- `business_events`
|
||
- `document_change_events`
|
||
- ETL support:
|
||
- `landing/business_events`
|
||
- `landing/document_changes`
|
||
- dataset mapping в `etl/load_1c_exports.py`
|
||
- built-in normalizer:
|
||
- `etl/build_business_event_exports.py`
|
||
- собирает canonical events из существующих read-only выгрузок
|
||
`documents/postings/audit`
|
||
- read-only extractor scaffold:
|
||
- `etl/extract_1c_mcp_toolkit.py`
|
||
- забирает `companies/documents/postings/business_events/document_changes`
|
||
через `execute_query`
|
||
- забирает `reglog` через `get_event_log`
|
||
- пишет в те же `landing/*`, которые уже понимает loader
|
||
- ingest wiring:
|
||
- normalizer запускается перед `load_1c_exports.py`
|
||
- timeline/detection wiring:
|
||
- `business_events` и `document_change_events` уже входят в
|
||
`entity_timeline`
|
||
- на этом слое уже есть первые detections:
|
||
- крупная корректировка проводки
|
||
- рискованное изменение документа
|
||
|
||
Это уже рабочий v1 normalizer, но ещё не конечный extractor со всей
|
||
бухгалтерской глубиной.
|
||
|
||
## Контракт `1c-mcp-toolkit` extractor
|
||
|
||
На текущем шаге extractor сознательно ограничен:
|
||
|
||
- только read-only endpoint'ы;
|
||
- без `execute_code`;
|
||
- с локальным checkpoint state;
|
||
- с `channel` isolation для разделения `dev/prod`.
|
||
|
||
Практический контракт такой:
|
||
|
||
1. `execute_query` должен возвращать колонки, алиаснутые под landing-схему.
|
||
2. Если это неудобно, используется `field_map` в `etl/config.yml`.
|
||
3. Для query-datasets можно включать incremental-window через
|
||
`incremental.since_param` / `incremental.until_param`.
|
||
4. Для `reglog` extractor хранит курсор `last_date +
|
||
same_second_offset`.
|
||
5. `company_entity_key` достраивается extractor'ом по той же логике,
|
||
что уже используется в built-in normalizer.
|
||
6. Перед включением live-ingest query-pack должен проходить:
|
||
- `--validate-config`
|
||
- `--dry-run`
|
||
- targeted `--dataset <name>` probe
|
||
|
||
## Что делать дальше
|
||
|
||
1. Подключить production queries под конкретную конфигурацию 1С.
|
||
2. Стабильно наполнять `company_entity_key`.
|
||
3. Добавить первые SQL detections на `business_events`.
|
||
4. Обогащать `entity_timeline` уже не только telemetry/audit, но и
|
||
business-event evidence.
|
||
5. Включить AI Investigator narrative по реальным проводкам и изменениям.
|