README 补 HTTP 接口表与里程碑真实状态，设计文档路径纠正；新增 CLAUDE.md 项目指引

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,60 @@
+# 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 截断、成员抽样无排序、行情快照日错位）与传导覆盖偏低的主因（板块级异动源缺失），桥侧只告警、修不了。

README.md

@@ -5,7 +5,7 @@ astock-kg（知识图谱基座）↔ `quant_factor_service`（通用因子平台
 子因子；**复合因子 `akg_score` 在桥内用自洽的景气度漏斗算出**，平台只负责注册/存储/
 调度/评价，不参与合成。
 
-> 设计与决策依据见本工程根目录 `量化因子导出与合成设计.md`（v2.0，唯一事实源）。
+> 设计与决策依据见本工程 `docs/量化因子导出与合成设计.md`（v2.0，唯一事实源）。
 > ⚠️ `astock-kg/docs/` 下的同名文档还是 v1，讲的是**已被推翻**的平台拟合合成方案，别读。
 > 本工程**不 import** 基座或平台任何代码，只靠 `.env` 里三处数据库连接工作，
 > 可单独部署于任意能连通三库的服务器。
@@ -162,10 +162,25 @@ docker compose exec akg-factor-bridge python run.py freeze --date 2026-07-24
    `source_type` 不是这个字符串，事件因子会被过滤成空（会显式告警），按实际值改
    `EVENT_SOURCE_TYPES`。
 
-## 未完成（设计 §8 里程碑）
+## HTTP 接口（桥常驻 API，端口 8300，全部只读除 refresh）
 
-- **G2**：`config/frontier_tracks.yml` + `tracks.py` + `data/track_members.csv`
+| 端点 | 作用 |
-  （赛道门槛 C；需要基座先出第五/六个插槽视图 `v_factor_segment_members` /
+|---|---|
-  `v_factor_segment_edges`——`industry_pools` 成员级没有 segment/layer，图谱在 Neo4j）。
+| `GET /health` | 存活探针 |
-- **G3**：漏斗合成 `akg_score` + `akg_gate`（0/1 全池出行，让平台分层能读出门槛的价值）。
+| `GET /plan/dates?limit=30` | 有计划文件的日期清单 |
-- **G4**：回填与仪表盘（upside 历史重建走「给基座 `sync_consensus` 加 `asof` 参数」）。
+| `GET /plan?date=&format=json\|md&top=&obs_top=` | 当日选股计划（基座今日页 `/plan/today` 与 PMS 下单候选都读它） |
+| `POST /plan/refresh?date=` | 重生成当日计划文件 |
+| `GET /plan/verdict?codes=300750,SH600438&date=` | 逐票『计划判决』（2026-08-18 PMS 对接加）：decision（main/observe/reject/absent）+ 与命令行 `plan_reconcile` 逐字同口径的 verdict_text + score/rank/tier/赛道/图谱证据。单票数据异常或代码形态认不出只报该票 error，不崩整批 |
+| `GET\|POST /api/v1/xxl/daily-build?key=&steps=&date=` | XXL-JOB 平台触发盘前链（build→plan→push-pool，白名单步骤、单实例互斥、回调结案）；`.env` 不配 `XXL_TRIGGER_KEY` 则整组禁用 |
+
+逐票对账的命令行形态（同一段判决代码）：
+`docker compose exec -T akg-factor-bridge python plan_reconcile.py 300750 [--date 2026-08-04]`
+
+## 里程碑状态（设计 §8）
+
+- **G2 赛道门槛 ✅**：`config/frontier_tracks.yml` + `tracks.py`，三路映射
+  （环节锚 > 链锚 > 主题弱锚），基座插槽视图 `v_factor_segment_members` 已就位。
+- **G3 漏斗合成 ✅**（07-30 拍板）：`akg_gate` + `akg_score` 进 `FACTORS`，
+  `build all` 一并日更；两锚三档 + 两段式组内分。
+- **G4 回填与仪表盘（未完成）**：upside 历史重建走「给基座 `sync_consensus` 加
+  `asof` 参数」，动工前先与基座侧排期。