akg-factor-bridge/README.md

265 lines
21 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.

# akg-factor-bridge
2026年11月5日:补齐数据迟到后的有限自动恢复及构建、冻结的沪深范围保护。保持日期时效与真实版本时间,说明与实际发布状态见[恢复接续](docs/选股输入迟到恢复与沪深边界_2026-11-05.md)。
astock-kg(知识图谱基座)↔ `quant_factor_service`(通用因子平台)之间的**因子导出桥**。
把基座的四路产出(分析师预期空间 / 热度 / 利好利空事件 / 板块传导)做成符合平台规范的
子因子;**复合因子 `akg_score` 在桥内用自洽的景气度漏斗算出**,平台只负责注册/存储/
调度/评价,不参与合成。
> 设计与决策依据见本工程 `docs/量化因子导出与合成设计.md`(v2.0,唯一事实源)。
> ⚠️ `astock-kg/docs/` 下的同名文档还是 v1,讲的是**已被推翻**的平台拟合合成方案,别读。
> 本工程**不 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:读视图+热度 → 四路日截面变换 → 【漏斗合成 akg_score】
→ 转前缀码 SH600000 → 写平台 t_factor_akg_* + 注册 factor_metadata
→ 每日冻结输入快照 data/frozen/(freeze.py)
▼
平台 quant_factor_service:当普通 single 因子 → 评价(RankIC/分层)=仪表盘 / 调度 / 下游消费
```
- **基座只暴露数据、不算因子**;桥承载全部因子建模(极性表、衰减、门槛、权重);
平台不感知 astock-kg。
- universe = KG 覆盖池(`v_factor_universe` = 全部 `industry_pools` 成员并集)。
⚠️ 它是**当前态**且每周一自动长大——子因子是否受它限制由 `SUBFACTOR_UNIVERSE` 控制。
## 四个子因子
| factor_code | 表 | 口径 | 缺失 |
|---|---|---|---|
| `akg_upside` | t_factor_akg_upside | 目标价中枢/现价−1(as-of backward) | NaN(无覆盖不出行) |
| `akg_heat` | t_factor_akg_heat | 热度分 0~1(最新批次,T+1 到达) | NaN |
| `akg_event` | t_factor_akg_event | Σ 事件极性×时间衰减(**仅公告来源、单文档封顶**) | 不出行 |
| `akg_transmission` | t_factor_akg_transmission | **distinct 源数**×(1−已动比例) | 不出行(合成侧填 0) |
## 选股计划入池(2026-08-03)
`python run.py push-pool` 把每日计划写进 Mongo 股票池分组(group_code=AKG_PLAN),
决策系统每晚认知扫描按分组并集覆盖 → 候选票自动获得夜间推理(支撑/压力/定性),
PMS 的参考位、择时执行区间、研判上下文由此可用。入池=当日计划(强传导前20)∪持仓;
掉榜未恶化留池观察;无持仓、不在计划且形态恶化 → 移入回收站 stock_recycle_bin;
持仓永不出池。规则、时间线、部署与判收见 `docs/选股计划入池_对接说明.md`。
## 日频行业观点快照(2026-09-03,只写不判)
`python run.py judgement-snapshot [--date D]` 把数据基座当前这一版产业研判与环节评析
(视图 `v_factor_judgement`)抄进选股系统自己的表 `t_akg_judgement_snapshot`,每个计划日
每个主题或环节一行。为什么要抄:那张评析表按主题唯一,重评时整行覆盖并把生成时间改成当前,
库里永远只有最新一版,查不到"这个观点上一次是什么样、什么时候变的";而逻辑状态四态里
"采信倾向从偏多变成偏空"这条判据依赖的正是这种变化,版本史只能由读的一方自己攒。
这一步只写不判:不产生判决、不改排序、不拦任何票。迁移与陈旧的口径写在行上——只有材料指纹
(`input_version`)变化才算一次迁移(`migrated=1`、`stale_days` 归零),指纹没变而日期变老
只累加陈旧天数(`migrated=0`);本表第一次见到的主题 `migrated` 留空。落点选平台因子库而不是
数据基座,因为桥对基座只有只读账号,且这是选股系统的派生记录不是基座事实;表名不带
`t_factor_` 前缀,免得平台的因子清单把它当因子表收进去。细节见 `judgement.py` 模块说明。
表由代码首次运行时自动建(`CREATE TABLE IF NOT EXISTS`)。若代理不允许自动建表,
在平台因子库(`FACTOR_MYSQL_*` 指向的那个库,即写 `t_factor_akg_*` 的同一个)手工执行
`judgement.py` 里 `_CREATE_TABLE` 的那段语句,两处逐字相同。
## 用法(全程 Docker,不在宿主机直跑)
```bash
# 0) 基座视图建一次/改一次。**按你在哪台机器上选一条**——桥是跨机部署的独立单元,
# 部署它的服务器上通常没有 astock-kg 的容器。
# (a) 在桥这边(推荐,无需 psql 客户端,用桥自己的 AKG_PG_* 连接):
docker compose exec -T akg-factor-bridge python run.py apply-views --dry-run # 先看要跑哪几条
docker compose exec -T akg-factor-bridge python run.py apply-views
# ⚠️ 需要 DDL 权限。日常只读账号会报 permission denied,用基座 owner 跑这一次:
# docker compose exec -T -e AKG_PG_USER=<owner> -e AKG_PG_PASSWORD=<pw> \
# akg-factor-bridge python run.py apply-views
# (必须用 -e 传进容器;写在 docker 前面只影响宿主机进程)
# (b) 在桥这边、想用原生 psql(一次性容器,不装客户端):
# set -a; . ./.env; set +a
# docker run --rm -i -e PGPASSWORD="$AKG_PG_PASSWORD" postgres:16-alpine \
# psql -h "$AKG_PG_HOST" -p "${AKG_PG_PORT:-5432}" -U "$AKG_PG_USER" -d "$AKG_PG_DB" \
# -v ON_ERROR_STOP=1 < sql/astock_kg_slot_views.sql
# (c) 在 astock-kg 那台机器上(把本文件带过去):
# 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
# 3.5) G1 体检(只读:池结构 / 行情年表 / upside 分布 / 三项相关矩阵与权重体检)
docker compose exec akg-factor-bridge python run.py probe
docker compose exec akg-factor-bridge python run.py probe --section corr # 单跑某节
# price 节全表聚合,可能 1~3 分钟;corr 节直接回答「0.5/0.3/0.2 是混合还是传导优先」
# 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
# 5) 输入冻结(daily 构建会自动跑一次;也可单独补)
docker compose exec akg-factor-bridge python run.py freeze --date 2026-07-24
```
生产触发:宿主 cron 或平台 XXL-JOB →
`docker exec akg_factor_bridge python run.py build all --mode daily`(跑完自动冻结)。
## ❄️ 输入冻结(freeze.py)——为什么每天都要跑
桥内写入幂等,但**上游不是**:传导的 quiet 集合依赖 Neo4j 返回序(基座 Cypher 无
`ORDER BY`)、`industry_pools` 只存最新态且每周一长大、`gp_day_data` 是前复权且
锚在最新日(每次除权历史 close 被整体重写)、`consensus_daily` 会被重跑覆盖。
所以「可复现」唯一诚实可达的定义是:**能从冻结的输入重算出同一个值**。
`data/frozen/<日期>/` 每天存一份 universe / 传导原始行 / 一致预期 / 当日收盘 / 热度
+ 当日算出的因子值 + `manifest.json`(行数、告警、git rev)。
它一次性满足:判收标准的「重跑不产生漂移」、「赛道成员快照可审计」、以及未来任何回溯
需求(含设计 §10 里 GRU 复活所需的「≥1 年 live 传导史」——**那个计时器只在开始存快照
的那天启动**)。`manifest.json` 才是可 diff 的审计线,建议 git 跟踪 manifest、忽略数据文件。
## 运行旋钮(`.env`,全部可留空取默认)
| 变量 | 默认 | 作用 |
|---|---|---|
| `SUBFACTOR_UNIVERSE` | `pool` | 子因子是否受覆盖池限制。`market` 可避免成员性前视与周一跳变(设计评审 §4 建议) |
| `EVENT_SOURCE_TYPES` | `announcement` | 事件只认哪些 `documents.source_type`。默认只认公告——年报会把**历史**诉讼记成披露日的当日负面事件 |
| `EVENT_MAX_PER_DOC` | `3` | 单文档最多贡献几条事件(一份年报能抽十几条) |
| `PRICE_CHUNK_DAYS` | `31` | 行情按月分块读取,防长区间回填 OOM |
| `WRITE_CHUNK_ROWS` | `50000` | 因子表分块提交,防单事务过大 |
| `FROZEN_ROOT` | `/app/data/frozen` | 冻结落点 |
| `UPSTREAM_MEMBER_CAP` / `UPSTREAM_QUIET_CAP` | `30` / `12` | 上游截断体检阈值,命中只告警不拦截 |
| `JUDGEMENT_SNAPSHOT_TABLE` | `t_akg_judgement_snapshot` | 日频行业观点快照落哪张表(平台因子库) |
| `JUDGEMENT_SCOPES` | `industry,segment` | 抄哪几类评析簇:产业研判与环节评析。个股与概念评析默认不抄 |
| `JUDGEMENT_PREV_LOOKBACK_DAYS` | `60` | 比对上一版时往前看几个自然日,超窗按第一次见到处理 |
## 网络(Docker)
桥要连三处,按「桥部署在哪」定地址:
- **跨机部署(默认,推荐)**:三处都用 LAN IP/域名(`.env` 里填)。默认 bridge 网络即可
出网到 LAN——前提是基座 PG、153、平台 MySQL 都对该服务器可达。
- **与基座同机同网**:让桥加入 astock-kg 的 compose 网络,用服务名 `postgres` 连基座 PG
(取消 `docker-compose.yml` 里 networks 段的注释,填 astock-kg 的网络名)。
## 已知的上游约束(桥修不了,但会显式告警)
跑 `build akg_transmission` 时若看到下列告警,是**基座侧**的问题,需在 astock-kg 修:
1. **`quiet` 存满 12 条** —— `transmission.py` 的 `quiet[:12]` 是给旁批/展示用的,
却把因子的结构上限锁在 `12 候选 × 12 成员 = 144 行/日`。改法:落库存全量,
旁批仍只喂前 12。
2. **`members_total >= 30`** —— 基座 `graph_store.topic_context` 的 Cypher 是
`LIMIT $cap`(默认 30)且**无 `ORDER BY`**,于是 `moved_ratio` 建立在一个任意顺序的
≤30 抽样上,同日重跑结果可能不同。改法:加 `ORDER BY`、cap 提到 200。
3. **`mkt_trade_date ≠ scan_date`** —— `hotspot._latest_mkt` 取的是
`max(trade_date) FROM mkt_daily` 而非 `scan_date` 当天的快照。17:30 `sync_market`
晚点时,18:15 的传导扫描会用 T−1 的 movers 写成今日戳。改法:`_latest_mkt` 加
`trade_date` 参数 + scan 开头加新鲜度断言。
(另:`gp_sector_daily` / `gp_market_sentiment` 当前空表、`t_signal_daily_results`
05-15 停更 → hotspot 的**板块级异动源整个缺失**,这才是传导每日只有几十行的主因。
要提传导覆盖,优先补 `gp_sector_daily`,比调任何参数都有用。)
## ⚠️ 待实机核实项
1. **三库连通性**:`python run.py views` 七项全 ✅ 才算通。
2. **视图版本**:`views` 会打印 `n_sources / mkt_trade_date / source_type` 是否就绪;
有 ⬜ 说明 `sql/astock_kg_slot_views.sql` 还没应用到基座(桥会自动退回旧口径并告警)。
3. **`factor_metadata` 列**:`register` 自适应实际列写入;若无 `factor_type` 列,平台
`/mining/factors/all` 可能查不到本因子(会打印告警),需与平台侧确认。
4. **事件极性/方向**:`factors.EVENT_POLARITY / EVENT_DIR` 是草案(设计 §9-5);
`增减持` 的增/减方向若 `qualifiers.direction` 里没有会落 0,需确认基座 EVENT 的方向
存在哪个 qualifier 键。半衰期 10 交易日 / 窗口 60 交易日可调。
5. **事件交易日龄近似**:v1 用自然日×(5/7) 折算交易日龄,非精确交易日历——够用,
后续可换真实交易日历向量化。
6. **`documents.source_type` 实际取值**:默认白名单是 `announcement`。若基座里公告的
`source_type` 不是这个字符串,事件因子会被过滤成空(会显式告警),按实际值改
`EVENT_SOURCE_TYPES`。
## HTTP 接口(桥常驻 API,端口 8300)
| 端点 | 作用 |
|---|---|
| `GET /health` | 存活探针;2026-09-03 起带 `pool_top`(POOL_TOP)与 `pool_max`(POOL_MAX),供 PMS 池深探针比对 |
| `GET /plan/dates?limit=30` | 有计划文件的日期清单 |
| `GET /plan?date=&format=json\|md&top=&obs_top=` | 当日选股计划(基座今日页 `/plan/today` 与 PMS 下单候选都读它)。顶层 `regime`(区制)与 `market`(两市成交额、广度、融资、恐贪四项)都只从当日快照读,快照缺失为空;每行的判决类字段 2026-09-03 起多 `basis`(判决依据)与 `logic`(因果论断带出处);2026-09-17 起名次改按质地带优先,每行多 `quality_band`(质地带:好 3 中 2 无评析 1 差 0)、`rank_axis`(quality/transmission)、`pointed`(是否被传导指向)、`rank_old`(旧序名次,供周报四周对照),开关 `PLAN_RANK_AXIS` 设 transmission 即逐字回旧 |
| `POST /plan/refresh?date=&key=` | 使用既有 XXL key 排入完整修订;晨版缺失不代造 |
| `GET /plan/user-candidates/search?q=` | 按名称或代码查找沪深 A 股 |
| `GET /plan/user-candidates` | 人工关注登记与实时评析状态;只读,不提交评析任务 |
| `POST /plan/user-candidates` | 经既有 `X-Job-Key` 鉴权登记人工关注;保存后由后台补齐评析并尝试计划修订 |
| `POST /plan/user-candidates/{id}/remove` | 经既有 `X-Job-Key` 鉴权移除关注,保留原登记记录 |
| `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` 则整组禁用 |
| `GET /review/latest` | 最新一份复盘周报的只读读数(2026-09-16 加,配合数据基座判收读数包):文件名、日期、大小、前二十行、三个标记行计数(`公司质地=`、`五日头`、`二十日头`)。没有周报回 404。纯文件读取,不连库 |
逐票对账的命令行形态(同一段判决代码):
`docker compose exec -T akg-factor-bridge python plan_reconcile.py 300750 [--date 2026-08-04]`
## 人工关注评析与吸筹参考规则(2026-11-04)
用户已明确选择沿用公司质地排序,吸筹作为参考,建仓由 PMS 的基本面、技术面、择时三源合议及后续规则判断。本次仅授权在 **155 模拟链路**配置 `CARD_ACCUM_CONFIRM_REQUIRED=0`。代码默认仍为 `1`,保留旧确认规则的回退能力;188 真实 PMS 不在本次切换范围。实际部署、参数生效与自然回执另记发布判收,不能用本地测试代替上线结论。
关闭确认要求后,潜在吸筹、其他非明确状态、缺评分或评分陈旧不再单独把股票降为“仅展示”或“关注”;原评分、状态与新鲜度仍保留为研究证据。不新增吸筹权重或综合分,质地排序与原始分数编码保持。券商覆盖、预期空间、证券资格、既有真实风险否决、高位派发和快照时点校验继续生效;人工来源只替代原发现入口。PMS 的三源合议、规则闸、研判、资金、组合及执行约束仍决定后续动作,研究完成或进入候选均不等于下单授权。
`plan-refresh` 只将本次获准的吸筹确认参数同步到新修订,其他冻结参数继续沿用原版本。即使研究输入未变,规则变化也必须追加带真实截止时刻、新参数指纹及明确原因的完整版本。`card_params.admission_rule` 区分确认规则与参考规则,`card_params.accum_confirm_required` 表明当前要求。旧日期、固定决策版本与晨版文件保持原样,不重写历史判决,也不倒填晨版。
人工关注走独立的真实买方评析链。登记后的后台任务与自然 `run.py plan-refresh` 周期先同步评析状态;GET 查询只批量读取真实报告。全部有效沪深人工关注加入原 `t_akg_review_targets` 目标名单,不受主榜前列、原分数或交易判决限制。缺少完整报告时,后台仅向配置的 `AKG_API_BASE` 提交原个股评析入口,要求买方评议和定性材料,使用 `force=false`,复用基座既有评析逻辑。
请求前先原子保存独立受理凭据,实际返回入队回执后才标记 `queued`。网络超时或受理结果不明时保持 `pending`,不立即重复提交;后续根据真实报告核验,并由原目标名单的自然批任务补齐。状态存于 `user_research.json`,不修改交易账本或历史计划。每轮默认最多提交 3 只、单次请求超时 3 秒;超过本轮额度的对象留待后续自然周期。移除或到期后停止新增提交与下游关注覆盖。
`GET /plan/user-candidates` 中,原 `status` 的 `pending/evaluated` 仅表示计划是否收录。独立的 `review_status` 为 `missing/pending/queued/completed/failed`,并附 `review_updated_at`、`review_error`、`review_data_date`、`company_review`、`company_review_text` 与 `review_ref`。任务标识不作为产品状态展示。
评析完成必须有真实固定版本引用、完整成功的买方评议、买方论点及不晚于当前时刻的报告生成时间。新鲜度按基座真实 `ran_at` 与 `checked_at` 中较新者检查,默认 7 天;轻量复核命中原指纹时可以更新核对时间,不能把它改写为新报告。`review_data_date` 始终取 `company_review.report_ran_at` 的北京时间日期。财报期是否落后仍由基座原有批任务判断;旧报告缺固定引用或评议未完成时明确等待补齐,不能伪造完成状态。
开发机验证:新增评析专项 19 项通过,包含吸筹参考规则的 35 个测试文件均经配置隔离、禁网护栏通过。候选镜像断网回归、真实评析受理与完成、自然日研究及盘中观察回执仍须在发布阶段分别核验。规则决定见[复盘决定台账 084](docs/复盘决定台账.md)。
## 里程碑状态(设计 §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` 参数」,动工前先与基座侧排期。
## 高股息阶段检测(独立研究)
`dividend_watch.py scan`读取上一交易日对应的`gp_stock_factor_pro_YYYYMM`。
先排除ST及退市名称,使用滚动股息不低于5%的研究入口。
每天接收已有新评析,财务分红事实每月更新,新入池立即补查。
季度复核需求单独列出;需求清单不等于已完成评析。
```bash
# 155桥机 · ~/project/akg-factor-bridge;部署后执行
docker exec akg_factor_bridge python dividend_watch.py scan
docker exec akg_factor_bridge python dividend_watch.py health
```
报告:`GET /research/dividend`。日检:`GET /research/dividend/health`。
独立XXL触发:`/api/v1/xxl/dividend-watch`,沿用既有鉴权及完成回调。
建议交易日北京时间08:05;使用独立锁,不占五分钟计划修订锁。
当前本地实现与真实只读试跑完成,线上日程尚未创建或启用。
输出在`data/dividend_watch/`,包含不可变输入、完整研究及可读报告。
没有分红公告和支付能力专项证据时,持续性保持待核验。
桥不调用模型,不改每日计划,不写交易股票池或PMS。
可选读取基座已发布的分红专项研究,冻结引用、结论与材料缺口。
基座缺失或复核失败时明确显示不可用,旧档案缺键继续兼容。
专项研究支持也不形成配置批准。新增接口当前尚未部署。
详见`docs/高股息阶段检测开发规格_2026-10-21.md`和同日交接。
```bash
# 开发机 · akg-factor-bridge;预期43项通过,完全离线
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest test_dividend_watch test_dividend_jobs test_dividend_research_feed
```