akg-factor-bridge/CLAUDE.md

CLAUDE.md — akg-factor-bridge 项目指引

本文件写给之后在这个仓库工作的 Claude 会话。先读完再动手。

一句话定位

数据底座 astock-kg 与通用因子平台 quant_factor_service 之间的因子导出桥：基座只暴露只读视图，桥算全部子因子并在桥内合成复合因子 akg_score，写平台因子表并注册元数据；平台管存储、调度、评价。桥不 import 两边任何代码，靠 .env 三处数据库连接独立工作。

文档地图（先读哪份）

• 唯一事实源：docs/量化因子导出与合成设计.md（v2.0）。注意：astock-kg 仓库 docs/ 下的同名文档是 v1、方案已被推翻，别读。
• README.md：架构、六因子口径、HTTP 接口表、用法、上游约束、里程碑状态。
• docs/选股说明_下游对接.md：选股计划的业务逻辑与下游对接。
• docs/选股计划入池_对接说明.md：与决策系统夜间推理的对接（含池深与 PMS 下单候选深度的关系，第 7 节）。

部署与联动（2026-09-01 现状）

• 桥部署在 192.168.16.155 的 8300 端口，常驻容器跑 uvicorn，无热加载：代码更新要在桥机拉代码并重启桥容器（重启前须经用户同意，避开每早 07:10 因子构建窗口）。
• 上游：astock-kg 基座（PG 视图 sql/astock_kg_slot_views.sql），基座机 tlai4090 即 192.168.16.178（SSH 端口 2280，用户 tlai）。
• 下游甲：决策系统 bionic_trader（192.168.16.188:38000），每晚认知扫描读 Mongo 股票池分组 AKG_PLAN（pool.py push 写入）。
• 下游乙：PMS（tradingSystem 仓库）建仓不读 Mongo 池，直接调本桥 GET /plan 取主榜前 PMS_PLAN_TOP_N 名做下单候选。
• 基座前端今日页的交易计划、个股页的计划判决，都代理本桥接口（基座 .env 的 AKG_BRIDGE_BASE）。
• 时区：容器与各服务器为国际时间，调度排程按北京时间，谈时间先说清是哪一路。

纪律（历次用户令，逐条必守）

1. 全程 Docker：不在宿主机直跑 pip、python、psql。开发机没有 Python 依赖环境是常态，需要真实依赖的测试用一次性容器跑（见下）。
2. 只读优先：分析、对账、体检工具全是纯查询；写路径只有因子表写入（common.write_factor）、计划文件生成与 Mongo 入池（pool.py push）。动写路径前想清楚。
3. 口径变更先看数据：改 UPSIDE_NEG_TOLERANCE、POOL_THEME_CAP 这类口径旋钮之前，先跑 score_lab.py 对比器拿读数，改口径属拍板事项。
4. 代码里"勿回退"注释都是实测教训（例：观察档下界、锚强度排序），改动碰到就先读注释里的案例。
5. 交易系统或因子平台仓库有哨兵断言测试，其登记清单已丢失：往平台侧加表、加调度前，必须先在那边仓库重建登记清单再动手。
6. 提交信息用中文短句说清楚做了什么。

测试（改完必跑）

纯逻辑单测三个，不连库。test_plan_verdict.py 全离线，开发机系统 Python 直接跑；另两个需要 pandas 与 fastapi 实体，在有 Docker 的机器用一次性容器跑全套：

# 开发机（零依赖，秒出）
python3 test_plan_verdict.py

# 基座机 tlai4090（全套三个，一次性容器，跑完即弃）
rm -rf ~/akg_tmp_bridge_test && git clone -q git@192.168.18.24:zlt/akg-factor-bridge.git ~/akg_tmp_bridge_test && docker run --rm -v ~/akg_tmp_bridge_test:/w -w /w python:3.12-slim bash -c "pip install -q -r requirements.txt; for t in test_plan_verdict.py test_pool_logic.py test_xxl_trigger.py; do echo == \$t ==; python \$t || exit 1; done"; docker run --rm -v ~/akg_tmp_bridge_test:/w python:3.12-slim rm -rf /w/data /w/__pycache__; rm -rf ~/akg_tmp_bridge_test

预期：三个测试分别打出 ALL OK 与 ALL PASS。2026-09-01 实测全过。

代码地图

• run.py：命令行入口（views 自检、register 注册、build 构建、freeze 冻结、apply-views 建视图、probe 体检、push-pool 入池）。
• factors.py：六因子构建器（upside、heat、event、transmission、gate、score）与事件极性表。
• plan.py：当日计划装配与渲染（collect、generate）。
• pool.py：计划写 Mongo 股票池 + 触发决策系统增量补扫（decide 是入池决策纯函数，有单测）。
• plan_reconcile.py：逐票对账（explain 命令行）与结构化判决（verdict，供 API），同一段判决代码两种出口。
• api.py：常驻 HTTP（/plan、/plan/verdict 等，端口 8300）。
• xxl.py：XXL-JOB 调度触发入口（子进程执行保证每次重读 .env）。
• freeze.py：每日输入冻结（可复现性的落地件，manifest.json 是审计线）。
• tracks.py：赛道三路映射解析。score_lab.py：口径对比器。probe.py、chain_diag.py：体检工具。

已知上游约束

README"已知的上游约束"一节列了三条要在 astock-kg 侧修的（quiet 截断、成员抽样无排序、行情快照日错位）与传导覆盖偏低的主因（板块级异动源缺失），桥侧只告警、修不了。