akg-factor-bridge/README.md

# akg-factor-bridge

astock-kg（知识图谱基座）↔ `quant_factor_service`（通用因子平台）之间的**因子导出桥**。
把基座的四路产出（分析师预期空间 / 热度 / 利好利空事件 / 板块传导）做成符合平台规范的
子因子，写进平台因子库，供平台合成为选股因子。

> 设计与决策依据见 astock-kg `docs/量化因子导出与合成设计.md`。本工程**不 import**
> 基座或平台任何代码，只靠 `.env` 里三处数据库连接工作，可单独部署于任意能连通三库的服务器。

## 架构（基座出视图，桥算变换，平台算合成）

```
astock-kg 基座 PG ── 只读视图（sql/astock_kg_slot_views.sql）
   v_factor_universe / v_factor_consensus / v_factor_events / v_factor_transmission
        │                          （热度不经基座：桥直连 153 读 stock_fund_heat_scores）
        ▼
akg-factor-bridge：读视图+热度 → 算四路日截面(极性/衰减/打分) → 转前缀码 SH600000
        → 写平台 t_factor_akg_* + 注册 factor_metadata
        ▼
平台 quant_factor_service：把四子因子当普通 single 因子 → 合成/回测/调度
```

- **基座只暴露数据、不算因子**；桥承载因子建模（极性表、衰减、打分——见 `factors.py`）；
  跨信号 alpha 组合在平台侧。
- universe = KG 覆盖池（`v_factor_universe` = 全部 `industry_pools` 成员并集），四路都限制其内。

## 四个子因子

| factor_code | 表 | 口径 | 缺失 |
|---|---|---|---|
| `akg_upside` | t_factor_akg_upside | 目标价中枢/现价−1（as-of） | NaN（无覆盖不出行） |
| `akg_heat` | t_factor_akg_heat | 热度分 0~1（最新批次） | NaN |
| `akg_event` | t_factor_akg_event | Σ 事件极性×时间衰减 | 0（无事件=中性） |
| `akg_transmission` | t_factor_akg_transmission | 路径数×(1−已动比例) | 0 |

## 用法（全程 Docker，不在宿主机直跑）

```bash
# 0) 基座视图建一次——经 astock-kg 的 postgres 容器（容器名 akg-postgres，库/用户均 akg）
docker exec -i akg-postgres psql -U akg -d akg < sql/astock_kg_slot_views.sql

# 1) 配连接（地址填「桥容器可达」的：跨机=LAN IP；与基座同机同网=服务名，见下「网络」）
cp .env.example .env && vim .env

# 2) 构建并起桥容器（常驻）
docker compose up -d --build

# 3) 连通性自检（六项行数全出 = 三库都通）
docker compose exec akg-factor-bridge python run.py views

# 4) 注册 + 跑因子（幂等，可重跑）
docker compose exec akg-factor-bridge python run.py register
docker compose exec akg-factor-bridge python run.py build akg_heat --mode daily --date 2026-07-24
docker compose exec akg-factor-bridge python run.py build all --mode history --start 2024-01-01 --end 2026-07-24
```

生产触发：宿主 cron 或平台 XXL-JOB →
`docker exec akg_factor_bridge python run.py build all --mode daily`。

## 网络（Docker）

桥要连三处，按「桥部署在哪」定地址：

- **跨机部署（默认，推荐——就是你要的「可部署到其他服务器」）**：三处都用 LAN IP/域名
  （`.env` 里填）。默认 bridge 网络即可出网到 LAN——前提是基座 PG、153、平台 MySQL 都对该
  服务器可达（基座 PG 需发布端口或处于可达网络；见设计文档 §8-1）。
- **与基座同机同网**：让桥加入 astock-kg 的 compose 网络，用服务名 `postgres` 连基座 PG
  （取消 `docker-compose.yml` 里 networks 段的注释，填 astock-kg 的网络名）。

## ⚠️ 待实机核实项（本工程 DB 细节以线上为准，跑不通按此排查）

1. **三库连通性**：`python run.py views` 六项全 ✅ 才算通。任一 ❌ 先解决网络/账号
   （尤其桥所在服务器到基座 PG、153、平台 MySQL 的可达性）。
2. **`gp_day_data` 代码列与形态**：`upside` 现价来自它。列名可能是 `ts_code` 或
   `symbol`（`.env` 的 `PRICE_CODE_COL`）；代码形态（`600000.SH` / `SH600000` / `600000`）
   两边已统一折前缀式再 join——若 `upside` 出行为 0，多半是形态没对上，在此调 join 口径。
3. **`factor_metadata` 列**：`register` 自适应实际列写入；若无 `factor_type` 列，平台
   `/mining/factors/all` 可能查不到本因子（会打印告警），需与平台侧确认。
4. **事件极性/方向（§8-3 开放问题）**：`factors.EVENT_POLARITY / EVENT_DIR` 是草案；
   `增减持` 的增/减方向若 `qualifiers.direction` 里没有（当前视图取 direction），会落 0，
   需确认基座 EVENT 的方向到底存在哪个 qualifier 键。半衰期 10 交易日 / 窗口 60 交易日可调。
5. **事件交易日龄近似**：v1 用自然日×(5/7) 折算交易日龄，非精确交易日历——够用，后续可
   换真实交易日历向量化。
6. **universe 覆盖面（F0 前置）**：先用 astock-kg 的 `factor_coverage_probe.py` 确认池内
   四信号日截面覆盖数（尤其热度 ≥30~50/日），再决定是否放量。