akg-factor-bridge/CLAUDE.md

63 lines
5.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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. 提交信息用中文短句说清楚做了什么。
## 测试(改完必跑)
纯逻辑单测六个,都不连库。开发机系统 Python(3.9,无 pandas)能直接跑五个:test_plan_verdict.py、
test_card.py、test_regime.py、test_market_context.py、test_pool_logic.py(后两个只给缺席的依赖装最小桩,
依赖存在时不覆盖);test_xxl_trigger.py 需要 fastapi 实体,在有 Docker 的机器用一次性容器跑全套:
# 开发机(零依赖,秒出)
for t in test_plan_verdict.py test_card.py test_regime.py test_market_context.py test_pool_logic.py; do echo == $t ==; python3 $t || break; done
# 基座机 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_card.py test_regime.py test_market_context.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 实测三个全过;2026-09-03 开发机五个全过(容器全套待跑)。
## 代码地图
- 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 截断、成员抽样无排序、行情快照日错位)与传导覆盖偏低的主因(板块级异动源缺失),桥侧只告警、修不了。