# 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 |

## 用法

```bash
# 0) 先把基座视图建好（在 astock-kg 的 PG 上执行一次）
psql "postgresql://<akg_user>@<akg_host>:5432/akg" -f sql/astock_kg_slot_views.sql

# 1) 配置连接
cp .env.example .env && vim .env      # 填三处连接 + gp_day_data 代码列

# 2) 连通性自检（四视图 / 热度 / gp_day_data / factor_metadata 行数）
pip install -r requirements.txt
python run.py views

# 3) 注册四子因子
python run.py register

# 4) 历史回填 / 每日增量（幂等，可重跑）
python run.py build all --mode history --start 2024-01-01 --end 2026-07-24
python run.py build all --mode daily  --date 2026-07-24
```

容器化：`docker compose up -d`（常驻），宿主 cron/平台 XXL-JOB 以
`docker exec akg_factor_bridge python run.py build all --mode daily` 触发。

## ⚠️ 待实机核实项（本工程 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/日），再决定是否放量。