131 lines
3.0 KiB
Markdown
131 lines
3.0 KiB
Markdown
# AI Investigator API contract
|
||
|
||
AI Investigator не должен ходить напрямую в файловую 1С.
|
||
|
||
Его правильный слой:
|
||
|
||
- ClickHouse (`analytics_1c.*`)
|
||
- DLP/forensics case API
|
||
- bounded search/timeline endpoints
|
||
|
||
## Базовые use-cases
|
||
|
||
- почему выросли ошибки по базе;
|
||
- какие пользователи дали риск за сутки;
|
||
- что произошло по case `X`;
|
||
- собрать summary по entity timeline;
|
||
- предложить next steps без write-действий.
|
||
- какие компании выпали из активности;
|
||
- где ожидается спад или рост объёма по компаниям;
|
||
- какие компании требуют проверки из-за резкого падения документооборота.
|
||
|
||
## Рекомендуемые API endpoints
|
||
|
||
### `GET /api/1/analytics-1c/summary`
|
||
|
||
Параметры:
|
||
|
||
- `infobase`
|
||
- `from`
|
||
- `to`
|
||
|
||
Возвращает:
|
||
|
||
- sales
|
||
- returns
|
||
- overdue_receivables
|
||
- detections_by_severity
|
||
- open_cases
|
||
|
||
### `GET /api/1/analytics-1c/detections`
|
||
|
||
Фильтры:
|
||
|
||
- `infobase`
|
||
- `severity`
|
||
- `rule_id`
|
||
- `entity_type`
|
||
- `entity_id`
|
||
|
||
### `GET /api/1/analytics-1c/timeline`
|
||
|
||
Фильтры:
|
||
|
||
- `entity_type`
|
||
- `entity_id`
|
||
- `from`
|
||
- `to`
|
||
|
||
### `GET /api/1/analytics-1c/cases/{case_id}`
|
||
|
||
Возвращает:
|
||
|
||
- case card
|
||
- related detections
|
||
- related timeline rows
|
||
|
||
### `GET /api/1/analytics-1c/companies/overview`
|
||
|
||
Фильтры:
|
||
|
||
- `infobase`
|
||
- `min_signal_score`
|
||
- `limit`
|
||
|
||
Возвращает:
|
||
|
||
- компании с активностью за 30 дней
|
||
- последние сигналы риска
|
||
- прогноз `amount/docs` на `7/30` дней
|
||
|
||
### `GET /api/1/analytics-1c/companies/{counterparty}/summary`
|
||
|
||
Возвращает:
|
||
|
||
- текущую карточку компании
|
||
- AI-ready short summary
|
||
- последние документы
|
||
- forecasts
|
||
- signals
|
||
|
||
### `GET /api/1/analytics-1c/companies/{counterparty}/forecast`
|
||
|
||
Возвращает:
|
||
|
||
- `metric`
|
||
- `horizon_days`
|
||
- `baseline_daily`
|
||
- `trend_slope`
|
||
- `predicted_daily`
|
||
- `predicted_total`
|
||
- `confidence`
|
||
|
||
### `GET /api/1/analytics-1c/companies/{counterparty}/timeline`
|
||
|
||
Возвращает:
|
||
|
||
- последние документы по компании
|
||
- базу
|
||
- автора
|
||
- тип операции
|
||
- статус
|
||
|
||
## Guardrails
|
||
|
||
- read-only SQL;
|
||
- whitelist queries;
|
||
- no direct write-back into 1С;
|
||
- no direct execution of arbitrary SQL from prompt;
|
||
- all investigator requests are logged.
|
||
- если live-данные не содержат `counterparty`, company endpoints должны честно возвращать пустой результат, а не симулировать прогноз.
|
||
|
||
## Output style
|
||
|
||
AI Investigator должен выдавать:
|
||
|
||
1. краткую суть;
|
||
2. что именно найдено;
|
||
3. почему это важно;
|
||
4. что проверить дальше;
|
||
5. ссылки на case/timeline.
|