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，不在宿主机直跑）

# 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/日），再决定是否放量。