feat(1c): add company intelligence forecasting layer

2026-05-22 10:11:53 +03:00
parent da58d682c1
commit f7114bde03
17 changed files with 1539 additions and 3 deletions
@@ -0,0 +1,155 @@
+# 1C Company Intelligence для AW-rus
+
+Этот слой строится **поверх** `clickhouse-1c/` и не трогает саму 1С.
+
+Его задача:
+
+- анализировать работу с компаниями (`counterparty`);
+- показывать, где компании выпали из активности;
+- считать простой, объяснимый прогноз по документам и объёму;
+- давать read-only API для AI Investigator и внешних аналитических сервисов.
+
+## Что считается компанией
+
+В этом контуре компания = `documents.counterparty`.
+
+Если в live-выгрузках поле `counterparty` пустое, слой остаётся корректно пустым.
+Он не выдумывает данные и не пытается прогнозировать то, чего нет.
+
+## Что добавлено
+
+### ClickHouse
+
+Файл:
+
+- `clickhouse-1c/clickhouse/init/04_company_intelligence.sql`
+
+Создаёт:
+
+- `company_forecasts`
+- `company_health_signals`
+- `v_counterparty_daily`
+- `v_counterparty_latest_activity`
+- `v_company_forecasts_current`
+- `v_company_health_current`
+- `v_company_portfolio_overview`
+
+### Forecast refresh
+
+Файл:
+
+- `clickhouse-1c/ai/refresh_company_intelligence.py`
+
+Что делает:
+
+- строит daily series по `counterparty`;
+- считает базовую линию и линейный тренд;
+- материализует прогнозы на `7` и `30` дней;
+- создаёт health-signals:
+  - `inactive_company`
+  - `amount_drop`
+  - `docs_stopped`
+  - `open_cases`
+  - `open_detections`
+
+### Read-only API
+
+Файл:
+
+- `clickhouse-1c/ai/company_intelligence_api.py`
+
+Endpoints:
+
+- `GET /health`
+- `GET /api/1/analytics-1c/companies/overview`
+- `GET /api/1/analytics-1c/companies/{counterparty}/summary`
+- `GET /api/1/analytics-1c/companies/{counterparty}/forecast`
+- `GET /api/1/analytics-1c/companies/{counterparty}/timeline`
+
+### Ops
+
+Файлы:
+
+- `clickhouse-1c/ops/run_company_intelligence_refresh.sh`
+- `clickhouse-1c/ops/run_company_intelligence_api.sh`
+- `clickhouse-1c/ops/aw-1c-company-api.service`
+
+И `run_ingest_cycle.sh` теперь:
+
+1. грузит новые выгрузки;
+2. обновляет timeline/detections/cases;
+3. применяет `04_company_intelligence.sql`;
+4. пересчитывает company forecasts/signals.
+
+## Развёртывание
+
+### 1. Установить зависимости
+
+```bash
+cd clickhouse-1c
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r etl/requirements.txt
+pip install -r ai/requirements.txt
+```
+
+### 2. Применить schema
+
+```bash
+clickhouse-client --queries-file clickhouse/init/04_company_intelligence.sql
+```
+
+### 3. Пересчитать company intelligence
+
+```bash
+./ops/run_company_intelligence_refresh.sh
+```
+
+### 4. Запустить API
+
+```bash
+./ops/run_company_intelligence_api.sh
+```
+
+По умолчанию:
+
+- host: `127.0.0.1`
+- port: `8710`
+
+## Переменные окружения
+
+См.:
+
+- `clickhouse-1c/.env.example`
+
+Ключевые:
+
+- `AW_1C_COMPANY_API_HOST`
+- `AW_1C_COMPANY_API_PORT`
+- `AW_1C_COMPANY_LOOKBACK_DAYS`
+- `AW_1C_COMPANY_MIN_DAYS`
+- `AW_1C_COMPANY_HORIZONS`
+
+## Что прогноз реально означает
+
+Это не black-box ML и не «магический AI».
+
+Сейчас используется объяснимый MVP:
+
+- daily baseline;
+- linear trend;
+- confidence;
+- health signals на простых правилах.
+
+Этого достаточно для:
+
+- раннего обнаружения выпадения компаний из потока;
+- ранжирования портфеля;
+- AI summary поверх уже объяснимых чисел.
+
+## Ограничения
+
+- без `counterparty` в выгрузках слой пустой;
+- это прогноз тенденции, а не финансовое обещание;
+- API строго read-only;
+- никакой записи обратно в 1С нет.
@@ -0,0 +1,17 @@
+# 1C Company Intelligence
+
+Слой `1C Company Intelligence` расширяет `File 1C analytics` и добавляет:
+
+- mart по `counterparty`;
+- прогноз по документам и объёму на `7/30` дней;
+- health-signals по компаниям;
+- read-only API для AI Investigator;
+- source dashboard `1c-file-companies`.
+
+Основной документ:
+
+- [1C_COMPANY_INTELLIGENCE_RU.md](../1C_COMPANY_INTELLIGENCE_RU.md)
+
+Ключевая граница:
+
+- если `counterparty` в live-выгрузках пустой, слой остаётся пустым честно и ничего не симулирует.
@@ -16,6 +16,7 @@
 - [Hayabusa Security Analytics](Hayabusa-Security-Analytics) - текущий production-контур: auto-upload, auto-case, severity scoring и Telegram alerts
 - [Security analytics stack v1](../security-analytics-stack-v1.md) - целевая v1-модель без претензии на Splunk-class SIEM
 - [File 1C analytics](File-1C-Analytics) - ClickHouse/Grafana/AI Investigator контур для файловой 1С
+- [1C Company Intelligence](1C-Company-Intelligence) - AI-ready слой анализа и прогноза по компаниям поверх файловой 1С

 ### Компоненты
 - [DLP Endpoint Monitoring](DLP-Endpoint-Monitoring) - мониторинг clipboard, печати, USB