diff --git a/docs/下一阶段开发方案与规格书_2026-09-15.md b/docs/下一阶段开发方案与规格书_2026-09-15.md new file mode 100644 index 0000000..43835f3 --- /dev/null +++ b/docs/下一阶段开发方案与规格书_2026-09-15.md @@ -0,0 +1,671 @@ +# 数据基座下一阶段开发方案与规格书(2026-09-15) + +> 供拍板与实施。开发者可以是人,也可以是大模型。 +> 写法遵守 `.claude/output-styles/readable-chinese.md`。 +> 第一到第十节是正文,读完就知道做什么、为什么、怎么验证、怎么评审。 +> 附录是实现细节,标了「可不读」。但开发者动手前必须读自己那个工作包的附录。 +> 基线:本地主检出 `7aaada0`,基座机 `3f45294`(两者只差一条只改文档的提交)。 +> 本文件在数据基座与选股系统两个仓库的 docs 下各有一份逐字副本,改一份要同步另一份。 + +--- + +## 一、这件事为最终目标买什么 + +最终目标不变:系统模拟主观选股基金经理的六步工作流。四层定位不变:数据基座用大模型分析并保存结论,选股系统基于结论选股,持仓管理系统定建仓方案,择时决策系统定时点。判收标准不变:只看系统逻辑、实现、设计目标三者是否一致,不看收益。 + +数据基座这一层今天的位置是这样的。个股深度评析已经全天跑、每天铺满一百二十家目标名单。但它用的财报期落后一季,因为上游供应商指标表的半年报只同步了一百六十五家。评析方案里排好的第二批(年报文本定性视角)和第三批(预期与合议)还没做。评析接入方案的判收四条与量价研判链的判收四条,都没有一条命令能出读数,人读评议连落点都没有。周五复盘周报从没自动跑过。灌入链路里有五百八十一份七月的公告没有运行记录,日检却报着一个退役口径算出的一千零八十六。需求单表挂着五千零四十八张"缺年报"的假单。 + +所以这一阶段不是再开新方向。这一阶段做四件事。一,把评析用的数据变新鲜,把丢单堵住,让系统自己列材料缺口。二,把两条判收的读数做出来。三,把评析方案里已经排好的第二批和第三批做完。四,让选股系统配合两处小改。 + +这一阶段买四样东西。 + +1. 评析证据线的新鲜度。半年报数据上游到了就用,上游没到就有读数说明是谁没到。 +2. 研究深度。年报的管理层讨论、核心竞争力、风险因素进评析;预期差与周期位置进评析;买方论点引用到具体视角与材料编号。 +3. 判收的依据。评析判收四条、量价研判链判收四条,一条命令出读数;人读评议有落点;周报每周五自动跑。 +4. 保运。登记了没入队的文档自动补投;抽取任务改成晚确认;材料需求单按评析目标开单并能核销。 + +--- + +## 二、原则 + +沿用五条:加不改;代码算数、模型写字;每个视角都能说"算不了";基座做描述性估值不做规范性估值;融合层永远不接大模型。本阶段再加五条。 + +1. 先有读数后判收。任何"判收"必须由一条可重跑的命令给出读数,人核的条目明写"人核"。 +2. 每一处改动都守"开关关掉逐字回旧",并先写这条单测再改。 +3. 判收只认基座机实测。本地单测绿只是进门票。 +4. 上游的表本仓库只读只报数。财务表由谁同步、多久同步,登记成"上游同步待办",不在本仓库写表。 +5. 一次只升一个版本号。第二批与第三批各升一次评析版本号,每升一次就是一次全量重跑,要在升版当天预判费用与时长。 + +--- + +## 三、做哪几件事 + +四个工作包,按建议的动工顺序排。前三个全在本仓库。第四个在本仓库但要与第一个包共用一个纯函数。第五项在选股系统仓库,单独审批。 + +每个工作包的名字就是它做的事,不另起代号。 + +### 保运包(最先做) + +**做什么。** 三件保运的活:财报期落后一季的处理,登记了没入队的自动补投,材料需求单按评析目标开单。 + +**为什么先做。** 评析的后两批都建立在"数据新鲜、材料齐"之上。今天近三天一百一十一次评析里九十六次用的是一季报。今天目标名单里一百一十一家有一百零九家已经有二零二五年年报正文,材料本来是够的,缺的是系统没有列出谁缺什么。 + +**做哪几件。** + +甲、财报期。 +1. 数据集拆成两个期键。供应商指标表与重构报表各按自己的最新期算指标。只依赖重构报表的指标(最近四季与结构类)用重构报表的最新期,必须要供应商指标表的指标(比率类最新期)用供应商指标表的最新期。年度类判据不受影响。 +2. 报告头部、侧车、摘要、索引表都写清两个期。索引表的报告期列取两者中更新的那个,作为报告期标签。索引表加三列:两个期与最近一次核对时刻。 +3. 指纹在两个期相同时逐字节复现旧公式,两表本就同期的公司不会因此重跑;两个期不同的公司会重跑一次,这正是要修的对象。 +4. 一个纯函数 `expected_period(asof)` 给出按日历应已披露的最新期:五月到八月是当年一季报,九月到十月是半年报,十一月到十二月是三季报,一月到四月是上年三季报。再一个 `due_period(asof, 30)` 给判收用,表示"截止日后三十天"。 +5. 批任务的跳过判据改成"七天内跑过、已用期不落后应披露期、版本相同",只看索引表不连上游库。落后的公司单独按名额轮转复核,复核只做两条最大值查询,上游没来就只更新核对时刻。 +6. 日检加四行:两张表对应应披露期的覆盖只数(一百五十三库两条单表计数)、目标名单里落后的家数、其中上游已到而报告未更新的家数(这一条才告警)、判收读数。零条分支的文案从"零点四十五任务"改成"每小时批任务"。 +7. 交接文档固定一节"上游同步待办",登记表名、期、读数、影响、写表方、复核日。写表方在因子仓库里全文没有命中,要在一百五十三库侧向写表方确认。 + +乙、登记了没入队。 +1. 两个灌入入口共用一个入队函数:同一套队列判定(研报与年报走靶向队列,其余走默认队列),入队失败不吞异常,登记成功但没入队时接口响应写明"已登记未入队"而不是谎报"已入队"。投递目录轮询里一份入队失败不再中断整轮。 +2. 一张调度台账表 `extraction_dispatch`,记每份文档的入队次数、补投次数、最近队列、来源、失败次数与最近失败原因。从此"登记了没入队""入队了没跑""跑了失败"三种情况可区分。运行记录表的语义不动:成功才写行,无行即回炉名单。 +3. 抽取任务改成晚确认,并把预取数改成一,未确认超时放到六小时。工作进程重建时预取了还没跑的消息回到队列,"蒸发"这一类根因消失。任务本身幂等,重复执行只浪费一次模型调用。 +4. 一个定时补投任务,从凌晨一点二十起每两小时一次。只投登记超过三十分钟且无运行记录的,只投见底的队列,同一文档最多补三次,每轮每队列最多二百份。原文对象为空的文档不补投,日检单独计数交人。 +5. 日检把"待抽取一千零八十六"的退役口径换成运行记录口径,去掉那条与队列长度错误对账的假警告。 +6. 上线后先干跑补投任务出花名册,再经同意投第一批。今天的五百八十一份公告就是首批。 + +丙、材料需求单。 +1. 年报判定改成并集口径:登记类型是年报,或者标题含"年度报告"且不含"半年度"与"摘要"。三处巡检函数与评析开年报单的那一处都改到同一个常量上。今天五千零四十八张在办的"缺年报"单里五千零四十一张就是这个口径错开的。 +2. 一次性核销存量假单:脚本先干跑出清单(每张单对应的年报文档号),经你同意后写库,状态改为已满足并标上文档号。真缺的七张留着。 +3. 按公司列研报缺口:对评析目标名单逐家看近一百八十天有没有研报(文档锚为主、论断反查为辅),没有的开单。主榜前三十名优先级一,其余二。理由写清来自评析目标与名次。已经被巡检开过的低优先级单,抬高优先级并追加来源。 +4. 每天十二点二十跑一次,评析批次上午铺满之后、下午上传材料之前。走即时队列,不调模型。 +5. 研报入库时按文档锚核销公司级研报单;公告入库时标题命中年报口径的核销年报单。 +6. 日检加"采集需求"一行:在办总数按类分布、来源为评析的张数、本周新开与核销、最老一条天数;另一条只在"在办单但其实已有材料"时告警。 + +细节见附录甲。 + +### 判收读数包 + +**做什么。** 一条命令出两条判收的读数;人读评议有落点;周五周报由基座定时触发选股系统去跑。 + +**为什么做。** 没有读数就没有判收。评析判收第一条要等半年报数据,第三条要周报,第四条要人读记录,都没有落点。量价研判链的判收原定今天,第三条能从择时决策系统结论表读出来(近五个交易日两个头的覆盖率已到九成五以上),第四条要周报里择时那一行下面两行,而周报从没自动跑过,且那两行在选股系统里还没实现。 + +**做哪几件。** + +1. 一条命令 `backend/scripts/acceptance_readings.py`,四节输出:评析判收(目标名单里有报告的比例、不落后应披露期的比例、评议成功率、未核数字比例、人读记录);量价链判收(近十个交易日每日总条数、带两个头的条数、带技术面的条数,连续五日覆盖率不低于九成是否成立,信号分布);周报(最近一份的日期与标记行计数);结论行(八条,各标成立、不成立或人核)。阈值集中在一个纯函数模块里。 +2. 人读记录:一张小表 `company_review_feedback`,一个接口 `POST /company/{代码}/review/feedback`,前端评析块两枚按钮"比代码汇总多说了东西"与"没有",重复点覆盖。只在评议成功的报告上显示。判收第四条按最近十份有记录的评议算。 +3. 周报自动触发:基座定时表加一条周五二十点十分的任务,打选股系统的外部触发接口跑复盘周报,钥匙走请求头不走查询串,触发与轮询结果记进一张小台账表 `bridge_job_runs`。日检周一报"上周五周报有或无"。二十点十分而不是十五点四十,是因为源侧十九点五十才发当日行情,早跑会少一个计划日的五日期限。 +4. 量价链判收第二节从一百五十三代理库读择时结论表,只做聚合查询,永远不把原始结论列整列拉回。动工前先探一次代理认不认 JSON 函数,不认就走字符串定位的退路并在输出里标明。 + +细节见附录乙。 + +### 评析第二批 + +**做什么。** 年报三类章节进材料层;五个定性视角(费雪十五问、段永平、林奇归类、波特五力、巴菲特文本部分);定性判据由本地模型读材料判定,代码校验编号、拒收没有依据的判定。 + +**为什么做。** 评析方案第二批。第一批十个视角全是数字,"管理层诚信""商业模式""竞争格局"这些主观选股最看重的东西还没进报告。 + +**做哪几件。** + +1. 分段器加一份新的章节类别表副本 `annual_report_review`,三类:核心竞争力、风险因素、经营与行业。原来的类别表一个字不动。风险因素多数年报是三级小节,命中展望段后从第一个风险词根处截起。 +2. 新材料层 `materials.py`:按标题口径取最近一份年报,只读解析缓存不解析 PDF,按章节类别切段并编号(章节 S、研报论断 R、图谱关系 G、环节评析 K、可比公司 P),编号稳定,材料集合有指纹。研报论断不进指纹,免得每来一篇研报就重跑整份报告。 +3. 新定性判定层 `qualitative.py`:把判据按三组(经营、治理、市场)各打包一次调用,材料喂入不超过一万四千字,模型只回 JSON,每条判据带通过与否和材料编号。代码做十条校验:编号不在本次材料里的丢弃,判定了却没有编号的拒收,引文不在材料里的记警告,数字逐个回查。拒收的判据保留在表里让人看见模型哪里没依据。 +4. 模型档位与时段。盘后用本地大模型档;盘中直接用云端溢出档(与本地质量相近的小模型),不等端点池的槽位,因为盘中等待上限一小时会卡死评析队列。云端溢出档没配置时盘中批次跳过定性并记原因。云端评议跟着定性同批跑,避免同一家一天评两次。 +5. 视角接口不改第一批十个文件:新视角在自己的声明里写需要材料与定性判定,调度函数只对声明了的视角传这两个参数。 +6. 报告六段标题不变。第三段的文本判据与数字判据在同一张表,读数列写"文本",备注列带材料编号。第三段末尾加材料编号对照表。第一段加材料与定性阶段两行。 +7. 索引表加三列(定性是否跑、定性状态、材料指纹)。评析版本号升到 `2026.09-3`。 + +细节见附录丙。 + +### 评析第三批 + +**做什么。** 四个数字视角(莫布森预期差、达摩达兰三情景对照、邱国鹭品质与估值、马克斯周期位置);买方论点合议扩展到引用视角编号与材料编号,并列出视角分歧。 + +**为什么做。** 评析方案第三批。前两批回答"公司好不好",第三批回答"市场预期与价格已经反映了多少"。 + +**做哪几件。** + +1. 指标层加约十个指标:市盈率与市净率十年中位、十年最高回报率与毛利率、市盈率对增速、自由现金流收益率、一致预期隐含的每股收益增速、预期差、隐含市盈率对一致预期、主营第一大项占比及三年变动。全部代码算。 +2. 四个视角全部代码判据。达摩达兰只做"叙事对应必须成立的数字"对照表,每个情景反推所需的增速、净资产收益率、市盈率,与历史对照,不产内在价值、不设折现率。邱国鹭的"时机"一条固定写"归择时决策系统"。 +3. 合议不另起本地模型,扩展现有云端评议:喂入视角索引与被引用的材料摘录,论点与反方每条带视角编号,新增视角分歧清单最多三条。评议版本号升到 `2026.09-2`,评析版本号升到 `2026.09-4`。 +4. 摘要只加键:预期差、周期位置、林奇归类、定性状态、论点引用的视角。原有"十视角好中差计数"的语义不变,另加一组第二三批的计数,选股系统卡上那句话继续为真。 + +细节见附录丁。 + +### 选股系统小改(另一仓库,单独审批) + +1. 一个只读接口 `GET /review/latest`,返回最新一份周报的文件名、日期、大小、前二十行与标记行计数。判收读数包第三节读它。 +2. 周报第七节"三套对照"在择时决策系统那一行下面加"五日头""二十日头"两行。这是量价研判链判收第四条的前提,方案写了但没实现。动工前先在一百五十五只读探一次两个头的判分种类名。 +3. 台账两条:质地证据线的报告期口径改为两表各自最新期;判收读数包与周报触发。 + +细节见附录戊。 + +--- + +## 四、顺序与时间 + +按交易日排。部署一律收盘后,先经审批。工作进程与定时器重建要一起做,漏了定时器新定时表不会生效。避开六点十分。 + +| 交易日 | 做什么 | +|---|---| +| 09-16 到 09-18 | 保运包开发与本地单测。四个只读探针(材料可得性、供应边占比属性名、代理库认不认 JSON 函数、两个头的判分种类名)在基座机与选股系统机器上跑完,读数记进交接。假需求单核销脚本干跑出清单 | +| 09-18 收盘后 | 部署保运包:重建四个工作进程与定时器。经同意后跑假需求单核销与补投首批。次日早上核日检新增的行 | +| 09-19 周五 | 周报先手工跑一次(选股系统机器上只读命令)。判收读数包开发 | +| 09-22 收盘后 | 部署判收读数包:接口侧存盘即生效,前端重建镜像,工作进程与定时器重建。跑一次判收读数命令留基线 | +| 09-22 到 09-24 | 评析第二批开发。分段器新类别表用真实年报正文抽查十家 | +| 09-24 收盘后 | 部署第二批。当晚看盘后批次的定性状态分布与单家耗时 | +| 09-25 | 第二批首日读数。选股系统两处小改提交,等审批重启接口容器(避开七点到七点半、八点半到九点零五) | +| 09-25 到 09-29 | 评析第三批开发 | +| 09-29 收盘后 | 部署第三批。当晚看评议的视角引用与分歧清单 | +| 09-26 周五 20:10 | 第一次自动周报。周一日检看那一行 | +| 09-30 | 评析判收第一条到期日(半年报截止日后三十天)。用判收读数命令出读数。上游没到就按"上游同步待办"处理,不算本仓库不达 | +| 十月长假后第一周 | 全部工作包的评审。人读记录攒到十份后判收第四条 | + +--- + +## 五、开关与参数 + +全部是环境变量,各模块直接读,与本仓库现有惯例一致。改了要重建工作进程才生效。每个键都要有真实读取处。 + +| 键 | 默认 | 属于 | 说明 | +|---|---|---|---| +| `AKG_COMPANY_REVIEW_FRESH_DAYS` | 7 | 保运甲 | 批任务"近期跑过"的窗口 | +| `AKG_COMPANY_REVIEW_RECHECK_MAX` | 60 | 保运甲 | 每批复核落后公司的名额 | +| `AKG_COMPANY_REVIEW_PROBE` | 1 | 保运甲 | 单家任务先做两条最大值查询再决定全量取数。零退回原流程 | +| `AKG_EXTRACT_ACKS_LATE` | 1 | 保运乙 | 抽取任务晚确认。导入期读,改后须重建工作进程 | +| `AKG_REQUEUE_ENABLED` | 1 | 保运乙 | 零时补投任务只干跑记日志 | +| `AKG_REQUEUE_BATCH_CAP` | 200 | 保运乙 | 每轮每队列上限 | +| `AKG_REQUEUE_MIN_AGE_MIN` | 30 | 保运乙 | 登记超过多久才补 | +| `AKG_REQUEUE_STALE_DAYS` | 2 | 保运乙 | 入队过的多久算蒸发 | +| `AKG_REQUEUE_MAX` | 3 | 保运乙 | 同一文档最多补几次 | +| `AKG_REQUEUE_LOW_WATER_CELERY` | 50 | 保运乙 | 默认队列见底阈值 | +| `AKG_REQUEUE_LOW_WATER_TARGETED` | 5 | 保运乙 | 靶向队列见底阈值 | +| `AKG_MATERIAL_DEMANDS_ENABLED` | 1 | 保运丙 | 零时只干跑 | +| `AKG_RESEARCH_FRESH_DAYS` | 180 | 保运丙 | 研报"新鲜"窗口 | +| `AKG_MATERIAL_TOP_RANK` | 30 | 保运丙 | 主榜前几名优先级一 | +| `AKG_BRIDGE_XXL_KEY` | 空 | 读数包 | 与选股系统触发钥匙相同。空即不触发,只记一行跳过 | +| `AKG_BRIDGE_POLL_EVERY` | 20 | 读数包 | 轮询间隔秒 | +| `AKG_BRIDGE_POLL_MAX_SEC` | 1200 | 读数包 | 轮询上限秒 | +| `AKG_COMPANY_REVIEW_QUAL` | 0 | 第二批 | 定性阶段总开关。上线后置一 | +| `AKG_COMPANY_REVIEW_QUAL_MAX` | 10 | 第二批 | 每批前几家带定性 | +| `AKG_COMPANY_REVIEW_QUAL_DAILY` | 200 | 第二批 | 当日定性家数上限 | +| `AKG_COMPANY_REVIEW_QUAL_TIER` | worker_large | 第二批 | 盘后档位 | +| `AKG_COMPANY_REVIEW_QUAL_INTRADAY_TIER` | worker_large_cloud | 第二批 | 盘中档位。空即盘中跳过定性 | +| `AKG_COMPANY_REVIEW_QUAL_MAX_TOKENS` | 8192 | 第二批 | 单次输出上限 | +| `AKG_COMPANY_REVIEW_QUAL_BUDGET` | 40960 | 第二批 | 单家定性输出总额 | +| `AKG_COMPANY_REVIEW_QUAL_INPUT_CHARS` | 14000 | 第二批 | 单次喂入材料字数上限,三万二千窗口 | +| `AKG_COMPANY_REVIEW_BRAIN_REQUIRES_QUAL` | 1 | 第二批 | 定性开着时评议只跟定性同批跑 | +| `AKG_COMPANY_REVIEW_ANNUAL_YEARS` | 1 | 第二批 | 取最近几份年报 | +| `AKG_COMPANY_REVIEW_PARSE_ON_MISS` | 0 | 第二批 | 解析缓存缺失时是否现场解析 | +| `AKG_COMPANY_REVIEW_PEERS_PX` | 1 | 第三批 | 同环节市盈率是否取数 | +| `AKG_COMPANY_REVIEW_MASK_NAME` | 1 | 第二批 | 章节文本脱敏 | +| `AKG_COMPANY_REVIEW_MATERIALS` | 1 | 第二批 | 材料层总开关 | + +--- + +## 六、验证方式 + +每条命令标明在哪台机器上运行。一个命令块只放一台机器的命令。基座机指 `ssh -p 2280 tlai@192.168.16.178`,仓库在 `~/project/astock-kg`;选股系统机器指 `ssh -p 2280 factor@192.168.16.155`。 + +### 动工前的四个只读探针 + +**基座机。** 预期第一条打出一行三元组,第二个元素是 OBJECT。报 SQL 语法错就走字符串定位的退路。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python -c " +from app.store.market_snapshot import _proxy_conn +c=_proxy_conn(); cur=c.cursor() +cur.execute(\"SELECT trade_date, JSON_TYPE(JSON_EXTRACT(raw_logic_json,'$.pv_heads')), JSON_KEYS(raw_logic_json) FROM strategy_daily_results ORDER BY trade_date DESC LIMIT 1\") +print(cur.fetchone())" +``` + +**基座机。** 预期带占比的供应边条数大于零。为零时改读边上的属性名。 + +```bash +cd ~/project/astock-kg && docker compose exec -T neo4j cypher-shell -u neo4j -p "$NEO4J_PASSWORD" "MATCH ()-[r:SUPPLIES_TO {status:'active'}]->() RETURN count(r) AS n, count(r.ratio) AS with_ratio, count(r.amount) AS with_amount" +``` + +**选股系统机器。** 预期除 strategy 外还有两个新种类名,期限五与二十各有行数。没有就说明两个头没有判分,选股系统第二处小改要先等择时决策系统那边。 + +```bash +docker exec akg_factor_bridge python3 -c "import db; print(db.read_mysql('pms','SELECT ref_type, horizon, COUNT(*) n FROM decision_outcome GROUP BY 1,2').to_string())" 2>&1 | grep -v Warning +``` + +**基座机(部署保运包之后跑,第二批的材料探针)。** 预期二十家里至少十四家有年报且解析缓存命中,其中至少十二家三类章节各有一段。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/company_review_materials_probe.py --top 20 +``` + +### 保运包 + +**本地。** 预期最后两行是 `Ran 4x tests` 与 `OK`,比改前的二十五多出新增用例数。 + +```bash +cd /Users/baobao/Documents/work/project/astock-kg && PYTHONPATH=backend python3 -m unittest discover -s backend/tests -t backend +``` + +**基座机。** 甲:单家报告头部出现两个期。预期出现"财务指标表最新期 2026Q1"与"重构报表最新期 2026Q2"两句。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/company_review_run.py --code 600519.SH --print --no-save | head -20 +``` + +**基座机。** 甲:批任务干跑。预期 `expected` 是 2026Q2,`counts` 里落后类约九十家,逐家带原因。 + +```bash +curl -s -X POST 'http://192.168.16.178:8000/admin/company_review_batch?dry_run=true' | python3 -m json.tool | head -60 +``` + +**基座机。** 乙:补投干跑。预期花名册五百八十一份左右,按队列分派,队列未见底的部分记在 `withheld`。 + +```bash +curl -s -X POST 'http://192.168.16.178:8000/admin/requeue_no_run?dry_run=true' | python3 -m json.tool +``` + +**基座机。** 乙:晚确认生效。预期 `worker_prefetch_multiplier` 为一,`visibility_timeout` 为 21600。 + +```bash +cd ~/project/astock-kg && docker compose exec -T worker celery -A workers.tasks inspect conf 2>/dev/null | grep -i "prefetch_multiplier\|visibility" +``` + +**基座机。** 丙:假需求单核销干跑。预期打印约五千零四十一张单与各自匹配的年报文档号,不写库。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/fulfill_annual_demands.py +``` + +**基座机。** 丙:材料需求单干跑。预期目标约一百二十家,研报缺口几十家,样例理由含"主榜第 n 名"。 + +```bash +curl -s -X POST 'http://192.168.16.178:8000/admin/review_material_demands?dry_run=true' | python3 -m json.tool +``` + +**基座机。** 日检。预期新增的行都出现:财报期覆盖、目标落后家数、调度台账、采集需求;不再出现"待抽取台账与队列对不上"。 + +```bash +cd ~/project/astock-kg && bash daily_check.sh +``` + +### 判收读数包 + +**基座机。** 预期四节都出,第四节八行,每行标成立、不成立或人核。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/acceptance_readings.py +``` + +**基座机。** 周报触发干跑。预期返回 `state` 为 `dry_run`,台账表多一行。 + +```bash +curl -s -X POST 'http://192.168.16.178:8000/admin/trigger_plan_review?dry_run=true&sync=true' +``` + +**基座机。** 人读记录。预期返回保存后的整行,再点一次相反的值同一行被覆盖。 + +```bash +curl -s -X POST http://192.168.16.178:8000/company/601126.SH/review/feedback -H 'Content-Type: application/json' -d '{"useful":true,"note":"评审试点"}' +``` + +**页面判收。** 打开任一家评议成功的个股页,评析块多两枚按钮。点一枚后按钮旁显示"已记"与时刻。 + +### 评析第二批 + +**基座机。** 单家定性试跑,盘后,不落库。预期 `qual_status` 为 ok、三次调用、耗时低于六分钟;费雪那张表里判定为通过或不通过的行备注都带材料编号;日志里三次 `finish=stop`。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/company_review_run.py --code <当天主榜第一只> --with-qual --no-save --print +``` + +**基座机。** 批任务干跑,盘中与盘后各一次。预期盘中前十家的定性档位是云端溢出档,盘后是本地档。 + +```bash +curl -s -X POST 'http://192.168.16.178:8000/admin/company_review_batch?dry_run=true&max_n=30&with_qual=true' | python3 -m json.tool | head -60 +``` + +**基座机。** 上线次日看分布。预期一天里定性状态 ok 不少于一百家。 + +```bash +cd ~/project/astock-kg && docker compose exec -T postgres psql -U akg -d akg -c "SELECT qual_status, count(*) FROM company_review_runs WHERE ran_at >= now() - interval '1 day' GROUP BY 1;" +``` + +**人工判收。** 十份报告的定性判据逐条点回材料编号对照表核章节。 + +### 评析第三批 + +**基座机。** 单家带评议,落库并忽略指纹。预期第五段有"引用视角"行,反方每条带视角编号,视角分歧非空或写"无";去掉 `--force` 再跑返回 `skipped_fresh`。 + +```bash +cd ~/project/astock-kg && docker compose exec -T -e PYTHONPATH=/app backend python /app/scripts/company_review_run.py --code <同上> --force --with-qual --with-brain --print +``` + +**基座机。** 预期差分布与反方非空占比。预期第二条反方与无法判断非空占比不低于七成。 + +```bash +cd ~/project/astock-kg && docker compose exec -T postgres psql -U akg -d akg -c "SELECT percentile_cont(ARRAY[0.1,0.5,0.9]) WITHIN GROUP (ORDER BY (summary->'expectation'->>'gap_pts')::float) FROM company_review_runs WHERE status='ok' AND summary->'expectation'->>'gap_pts' IS NOT NULL;" -c "SELECT count(*) FILTER (WHERE summary->>'antithesis' IS NOT NULL) AS anti, count(*) FROM company_review_runs WHERE brain_used AND ran_at >= now() - interval '7 days';" +``` + +### 选股系统小改 + +**选股系统机器。** 预期末行 ALL OK。 + +```bash +docker exec akg_factor_bridge python3 test_review_latest.py +``` + +**选股系统机器。** 重启接口容器后。预期返回文件名、日期、前二十行与三个标记计数;周报没跑过则 404。 + +```bash +curl -s 'http://192.168.16.155:8300/review/latest' | python3 -m json.tool | head -30 +``` + +--- + +## 七、回退 + +每个工作包独立回退,互不牵连。 + +| 工作包 | 回退方式 | 要不要重建 | +|---|---|---| +| 保运甲 | `AKG_COMPANY_REVIEW_PROBE=0` 退回全量取数;三列纯加法留着无害;指纹在两期相同时与旧公式一致 | 改参数要重建工作进程 | +| 保运乙 | `AKG_EXTRACT_ACKS_LATE=0` 退回早确认;`AKG_REQUEUE_ENABLED=0` 停补投;台账表可整张删;接口响应值域回退改一行 | 要重建工作进程 | +| 保运丙 | `AKG_MATERIAL_DEMANDS_ENABLED=0`;年报口径常量改回一处;已开的单可关闭 | 不用 | +| 读数包 | `AKG_BRIDGE_XXL_KEY` 置空即不触发;摘要多出的键对下游是"缺键就是空";前端回滚重建 | 触发那条要重建即时队列工作进程 | +| 第二批 | `AKG_COMPANY_REVIEW_QUAL=0` 文本判据全部"算不了",报告六段齐;整体回退用 `git revert` 一个提交并重建工作进程 | 要重建 | +| 第三批 | 评议对没有材料与视角索引的侧车自动退化为旧形状;整体回退 `git revert` 一个提交 | 要重建 | +| 选股系统小改 | `git revert` 一个提交,重启接口容器 | 要重启,先经审批 | + +--- + +## 八、拍板点 + +已定三条(2026-09-15)。 + +1. 定性判据的模型:本地为主,盘中用云端溢出档。落法是盘后本地大模型档、盘中直接走云端溢出档不等槽位。 +2. 抽取任务改晚确认,预取数一,未确认超时六小时。 +3. 五千零四十一张假年报需求单一次性按匹配到的年报核销,先干跑出清单再经同意写库。 + +代定的项,写明依据,动工前不再问。要改就在这里改。 + +4. 周报触发时刻二十点十分。源侧十九点五十才发当日行情,十五点四十跑会少一个计划日的五日期限。 +5. 合议不另起本地模型,扩展现有云端评议。本地档三万二千窗口装不下十九个视角加材料摘录;本地产能留给必须本地跑的三次定性调用;护栏、额度、下游键都在云端评议上。方案里"本地合议"那句记台账为被接入方案取代。 +6. 视角接口不改第一批文件,新视角自己声明需要什么,调度函数只对声明了的传参。 +7. 定性判据三层级联:代码圈材料编号,模型只回 JSON,代码校验并拒收无编号判定。拒收的保留在表里。 +8. 巴菲特文本部分独立模块,不碰参与质地合成的数字模块。第二三批视角不参与质地合成。 +9. 事件断言不进材料。九十天滚动窗口天天老化,指纹会跟着漂。 +10. 研报论断进材料但不进指纹。 +11. 解析缓存缺失默认不现场解析,只记账。探针读数低于线再开。 +12. 摘要里"十视角好中差计数"语义不变,另加第二三批的计数。 +13. 索引表报告期列取两表中更新的期。指纹在两期相同时复现旧公式。 +14. 失败不写运行记录表,写调度台账。运行记录表仍是"成功表、无行即回炉"。 +15. 补投只投见底的队列。补投是修复不是插队。 +16. 版本号:第二批评析版本 `2026.09-3`,第三批 `2026.09-4`,评议版本第三批升 `2026.09-2`。第二批与第三批分两个提交,第二批观察一夜再上第三批。 +17. 周报第七节加两行放在选股系统小改里做,前提是两个头的判分种类名探针有读数。没有就量价判收第四条固定写"不成立(未实现)"。 +18. 判收"落后一个月"的实现是截止日后三十天,不按各公司实际披露日。 + +--- + +## 九、交付要求 + +给开发者的硬要求,人和大模型一样。 + +1. 每个工作包一个提交。提交信息全中文、无前缀,格式是"主题:改了什么",末尾带台账号。第二批与第三批各一个提交。 +2. 先写"开关关掉逐字回旧"的单测,再改代码。开关关掉时输出的字典要 JSON 序列化后逐字节相等。 +3. 本地单测只用标准库 unittest,跑法写进测试文件首行。不在容器里跑单测。 +4. 加表加任务五处一起登记:存储模块的表定义与读写、任务定义与定时表并写清为什么是这个时刻、手工触发入口、日检一行读数、交接文档一段与台账一条。 +5. 手工投任务显式指定队列。定时表按北京时间。判盘中盘后看容器内时间折成北京时间,容器是世界协调时。 +6. 一百五十三代理库一条 SQL 只碰一张表。择时结论表只做聚合查询,永远不把原始结论列整列拉回。 +7. 给现有表加列必须写 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`,并放在非六点十分的窗口部署。 +8. 推理型模型输出上限给足,截断不重试,非截断空答案只重试一次,单家有总额上限。 +9. 部署先经审批。工作进程与定时器一起重建。前端改动要重建镜像。服务器上只做 `git pull`,不跑 `git stash`。 +10. 每个工作包交付时附第十节的证据清单。 + +--- + +## 十、评审方式 + +开发完成后由评审者逐条核,评审者可以是大模型。评审不看开发者的自述,只看证据。 + +### 每个工作包要交的证据 + +| 证据项 | 要交什么 | 怎么核 | +|---|---|---| +| 提交号 | 每仓库一个或多个短哈希 | `git show --stat` 对照附录己的文件清单,多一个少一个都记 | +| 离线单测输出 | 本地全量单测的最后两行;选股系统各测试文件的末行 | 评审者自己再跑一遍,数字对不上退回 | +| 只读读数 | 第六节每条命令的原文输出,标机器与北京时间 | 评审者在同一台机器重跑,读数量级一致即可 | +| 五处登记 | 逐处给文件路径与行号;不适用的写"不适用"及理由 | 逐处打开看,缺一处退回 | +| 逐字回旧 | 每个开关关掉后的输出与改前一致的证明 | 评审者至少亲手核一条 | +| 上线读数 | 部署后次日日检新增行的原文、批任务干跑输出 | 与第六节预期逐条对 | + +### 评审者的核对步骤 + +1. 读 diff 对照附录己的文件清单。出现清单外的文件,或改了既有函数签名、既有表列、既有键语义,记不符项。 +2. 本地跑全部离线单测,基座与选股系统各一次。 +3. 在基座机跑第六节标"基座机"的每一条命令,逐条对预期读数。 +4. 核五处登记。跑一次日检,新加的行必须出现且分级正确:没跑用信息级,该有而没有才警告级。 +5. 核回退可行。至少实测一条开关回退。 +6. 核时区与队列:定时表在北京时区之下;手工投任务用了 `apply_async(queue=...)`;新任务在路由表里。 +7. 写评审记录到 `docs/评审记录_<日期>.md`。骨架:评审对象与提交号;证据核对表;只读读数原文;不符项与条件;判定;评审者与时刻。 + +### 判定三档 + +| 档 | 条件 | +|---|---| +| 通过 | 单测全绿;第六节命令全部按预期;五处登记齐;回退实测通过;diff 无清单外改动 | +| 有条件通过 | 只差运行样本类的读数,例如人读记录不足十份、上游半年报未到、周报还没到周五自动跑过一次。列出条件与复核日期 | +| 退回 | 任一:单测红;改了既有签名或既有键语义;手工投任务没指定队列;定时表没写时刻理由;日检分级用错;代理查询联了表或把原始结论列整列拉回;钥匙走了查询串;模型调用没有截断不重试 | + +--- + +## 附录甲(可不读):保运包实现 + +### 甲、财报期 + +**`periods.py` 新增纯函数。** + +```python +def expected_period(asof: date) -> str # 01-01到04-30 上年Q3;05-01到08-31 当年Q1;09-01到10-31 Q2;11-01到12-31 Q3 +def due_period(asof: date, grace_days: int = 30) -> str # expected_period(asof - grace_days) +def key_end_date(key: str) -> date # "2026Q2" -> 2026-06-30 +def key_lt(a, b) -> bool # a 落后于 b;a 为空视为落后,b 为空视为不落后 +def newer_key(a, b) -> str | None +``` + +**`dataset.py` 第 125 到 129 行。** `latest_key` 改为 `newer_key(latest_key_fi, latest_key_rf)`。`latest_key_fi` 与 `latest_key_rf` 已经算了,只是没人用。新增 `latest_notice` 记两表最新期的披露日。 + +**`metrics.py` 的 `compute`。** 第 149 到 152 行取最新行的地方拆成 `lr = rf.get(key_rf)` 与 `lf = fi.get(key_fi)`。只依赖重构报表的指标的 `period` 写 `key_rf`,最近四季用 `ttm(rf_single, key_rf)`;必须要供应商指标表的指标写 `key_fi`。年度类不动。第 344 行的说明改为按两个键分别判,两键相同时文案一字不差,不同时追加一句"两张表最新期不一致:财务指标表 X、重构报表 Y"。返回加 `latest_key_fi` 与 `latest_key_rf`。 + +**`runner.py`。** 指纹改为 `fingerprint(key_fi, key_rf, *, with_brain)`,两键相等时原串逐字节等于旧公式 `"{key}|{REVIEW_VERSION}|{lenses}|{brain}"`。新增探针:保存模式且非强制时先调 `fin_statements.latest_period_keys(code, asof)`(两条单表最大值查询)算指纹,与索引表相等就 `touch_checked` 并返回 `skipped_fresh`。两期进侧车、摘要、索引表与返回值。 + +**`company_review_store.py`。** 建表语句追加三条 `ALTER TABLE company_review_runs ADD COLUMN IF NOT EXISTS`:`period_fi TEXT`、`period_rf TEXT`、`checked_at TIMESTAMPTZ`。列表加三列。`save_run` 加两参。新增 `touch_checked(ts_code, period, version)`。 + +**`freshness.py`(新,纯函数)。** + +```python +def row_periods(row) -> tuple # 旧行兼容:coalesce(period_fi, period) +def classify(row, *, expected, version, with_brain, now, fresh_days) -> str + # never_run / stale_run / recent_no_data / version_changed / brain_pending / behind / fresh +def pick_batch(targets, latest, *, expected, version, with_brain, max_n, max_recheck, now, fresh_days=7) -> dict + # 前四类按名次取 max_n;behind 类按 checked_at 升序(空在前)取 max_recheck;返回 picked 带 reason 与 counts +def lag_readout(targets, latest, *, expected, due, version, fi_codes, rf_codes) -> dict + # 日检与判收:落后家数、仅哪张表落后、上游已到而报告未更新的家数与代码 +``` + +**`fin_statements.py`。** 新增 `latest_period_keys(code, asof)`:供应商指标表按公告日不晚于 asof 取最大期末,重构报表按公告日不晚于 asof 且校验状态非 FAIL 取最大报告期。新增 `period_coverage(key)`:两张表对应该期的覆盖只数与按校验状态分布,含代码集合。 + +**`tasks.py` 批任务。** `latest = store.latest_many(...)`,`plan = freshness.pick_batch(...)`,`expected = periods.expected_period(北京日期)`。强制模式时 latest 传空。返回值加 `expected`、`counts`,逐家带 `reason`。定时表注释补一句判据改法。 + +**日检落点。** "个股深度评析"块内追加:财报期覆盖(信息级)、目标落后家数(信息级)、上游已到而报告未更新的家数(大于零才警告)、判收读数(宽限三十天)。上市公司分母取 `company_master` 里在市的。 + +**上游同步待办写法。** 交接文档固定一节,表头:提出日、表、期、读数、对本仓库的影响、写表方、复核日。首条:2026-09-15,`gp_fina_indicator`,2026Q2,165/5202 家,比率类最新期指标停在一季报,写表方待核实,复核 2026-09-22。 + +### 乙、登记了没入队 + +**`dispatch_policy.py`(新,纯函数,不导入 celery)。** + +```python +TARGETED_SOURCE_TYPES = frozenset({"research_report", "annual_report"}) +def queue_for_source(source_type) -> str # targeted / celery +def plan_requeue(rows, *, queue_len, low_water, inflight, cap, max_requeues) -> dict + # 从未入队与入队过但陈旧的都只投向见底队列;inflight 里的不投;inflight 为 None 时陈旧类整批不投 + # 每队列最多 cap;先从未入队后陈旧;组内按披露日升序;返回 dispatch 与 withheld +``` + +**`extraction_dispatch.py`(新,存储模块)。** 建表语句内嵌,`db/postgres/init.sql` 末尾同源追加一份。 + +```sql +CREATE TABLE IF NOT EXISTS extraction_dispatch ( + doc_id UUID PRIMARY KEY REFERENCES documents(doc_id), + first_enqueued_at TIMESTAMPTZ, last_enqueued_at TIMESTAMPTZ, + n_enqueued INT NOT NULL DEFAULT 0, n_requeued INT NOT NULL DEFAULT 0, + last_queue TEXT, last_task_id TEXT, last_source TEXT, last_reason TEXT, + n_failed INT NOT NULL DEFAULT 0, last_failed_at TIMESTAMPTZ, last_error TEXT); +CREATE INDEX IF NOT EXISTS idx_extdisp_last_enq ON extraction_dispatch (last_enqueued_at); +``` + +函数:`record_enqueue(doc_id, *, queue, task_id, source, reason=None, requeue=False)`,`record_failure(doc_id, error)`,`roster(*, min_age_minutes, stale_days, max_requeues, limit)`,`summary()`。花名册查询:原文对象非空、无运行记录、登记超过 min_age、补投次数低于上限、从未入队或最近入队早于 stale_days,先从未入队后陈旧,组内按披露日与文档号排序。 + +**`tasks.py`。** 新增唯一入队口 `enqueue_extract(*, doc_id, object_key, disclosure_date, source_type, ingest_mode="stream", source, reason=None, requeue=False) -> str`:按来源选队列,`apply_async(kwargs=..., queue=...)`,成功后写台账,台账写失败只记警告,入队失败原样抛出。投递目录轮询里每份入队包在 try 里,失败计数并继续。抽取任务装饰器加 `acks_late=_ACKS_LATE`,函数体整体包一层异常记录后重新抛出。全局配置加 `worker_prefetch_multiplier=1` 与 `broker_transport_options={"visibility_timeout": 21600}`。新任务 `akg.requeue_no_run(limit=None, dry_run=False)`,路由即时队列,定时 `crontab(minute=20, hour="1-23/2")`,注释写清避开盘前链与整点评析批、只投见底队列等于自然限流、两小时是研报快线的时效需求。 + +**`routes_ingest.py`。** 响应模型加 `error`,`status` 取值 `queued` 或 `registered_not_queued`。`_enqueue` 改调唯一入队口,返回 `(task_id, error)`。HTTP 状态保持 200,登记确实成功了。`batch_ingest.py` 识别 `registered_not_queued`,打印警告并计数,仍写本地台账以免重跑重复登记。`requeue_no_run_docs.py` 改用花名册函数与唯一入队口,花名册多打补投次数与最近失败原因两列。 + +**`main.py`。** `POST /admin/requeue_no_run?limit=&dry_run=`,干跑就地跑,否则 `apply_async(queue="interactive")`,队列不可用则同步跑。 + +**日检第四节。** 换成:无运行记录 N 份按来源、其中原文对象为空 U 份;调度台账的从未入队、已入队未跑、曾失败、补投达上限各几份与最近一次补投时刻;补投任务超过四十八小时没跑才警告;已入队未跑远多于两条队列长度之和才警告。去掉原"待抽取台账与队列对不上"那条。 + +### 丙、材料需求单 + +**年报口径常量。** 放在 `company_review/materials.py` 与 `claim_store.py` 共用一处:`ANNUAL_TITLE_SQL = "(title LIKE '%%年度报告%%' AND title NOT LIKE '%%半年度%%' AND title NOT LIKE '%%摘要%%')"`,并集口径 `_ANNUAL_DOC_SQL = "(source_type='annual_report' OR " + ANNUAL_TITLE_SQL + ")"`;Python 侧同规则 `is_annual_title(title) -> bool`,单测钉住两者一致。`claim_store` 里 `patrol_coverage_sets`、`companies_missing_annual`、`company_coverage` 三处与 `runner._open_annual_demand` 都改到这个常量上。 + +**`claim_store.py` 新增。** `annual_docs_by_company(codes)` 回每家份数与标题里最大的报告年份;`has_annual_report(ts_code)`;`research_coverage(codes, *, since)` 回每家文档锚篇数、论断反查篇数、最近披露日;`escalate_demand(need, target_type, target_id, *, priority, note)` 只抬优先级并追加理由;`demands_health(*, fresh_days=180)` 给日检。 + +**`company_review/materials.py` 需求单部分。** `label_for(source, rank)`、`priority_for(source, rank, *, top_rank=30)`、`research_gaps(targets, coverage, *, fresh_days, today)`、`annual_gaps(targets, annual, *, fy)`、`apply(gaps, *, source="company_review", dry_run)`。理由写法:"个股深度评析目标(主榜第 3 名,计划日 2026-09-16):近 180 天无研报覆盖(文档锚 0 篇、论断反查 0 篇)"。 + +**`tasks.py`。** 新任务 `akg.review_material_demands(dry_run=False, fresh_days=None)`,路由即时队列,定时 `crontab(hour=12, minute=20)`,注释写清为什么是评析批次铺满之后。`_demand_scan` 研报分支加文档锚核销路径;公告分支标题命中年报口径时核销年报单。`main.py` 加 `POST /admin/review_material_demands`。 + +**一次性核销脚本 `backend/scripts/fulfill_annual_demands.py`。** 无参数干跑:列出在办年报单里按并集口径能匹配到年报的,每张单打公司、匹配到的文档号与标题;`--apply` 才写库,逐张 `fulfill_demands("annual_report", "Company", code, doc_id)`。写库前再打印一遍计数。 + +**前端。** `DemandsView.jsx` 来源标签加"个股深度评析"。要重建前端镜像。 + +**日检。** 放在评析块之后:采集需求一行(信息级);核销遗漏一行(在办单但其实已有材料时警告)。 + +--- + +## 附录乙(可不读):判收读数包实现 + +**`backend/app/analysis/acceptance.py`(新,纯函数)。** 阈值常量集中在顶部:宽限 30 天、报告不落后比例 0.90、评议不落后比例 0.80、连续 5 个交易日、每日覆盖率 0.90、人读 10 份里 7 份。函数:`period_ge(a, b)`、`review_readings(targets, latest, floor)`、`pv_day_rule(days, *, need, bar)`、`signal_shift(days)`、`feedback_readings(recent_rows, last_rows)`、`verdict_lines(readings)`。地板期用 `periods.due_period(asof, 30)`。 + +**`backend/scripts/acceptance_readings.py`(新)。** 参数 `--asof`、`--days`、`--json`。四节各自 try,失败本身是读数,退出码恒零。第二节的主路 SQL 用 `JSON_TYPE(JSON_EXTRACT(raw_logic_json, '$.pv_heads'))='OBJECT'` 而不是 `IS NOT NULL`,因为 JSON 空值经抽取后不是 SQL 空值。两个头都有值按 `$.pv_heads.h5.score` 与 `$.pv_heads.h20.score` 的类型是数值判。退路用 `LOCATE('"pv_heads"', raw_logic_json) > 0`,输出标 `heuristic`。日期先取 `SELECT DISTINCT trade_date ... ORDER BY trade_date DESC LIMIT 10`。信号分布用 `GROUP BY trade_date, signal_type`。 + +**`company_review_feedback_store.py`(新)。** + +```sql +CREATE TABLE IF NOT EXISTS company_review_feedback ( + ts_code TEXT NOT NULL, period TEXT NOT NULL, review_version TEXT NOT NULL, + reader TEXT NOT NULL DEFAULT 'web', useful BOOLEAN NOT NULL, note TEXT, + at TIMESTAMPTZ NOT NULL DEFAULT now(), + PRIMARY KEY (ts_code, period, review_version, reader)); +``` + +函数:`save(...)` 用 `ON CONFLICT ... DO UPDATE` 覆盖;`get`、`last_reviews(n=10)`(每份评议一行,`DISTINCT ON` 三键)、`recent(days)`、`summary(days)`;纯函数 `normalize(payload)` 截备注三百字、读者三十二字、`useful` 强制布尔。 + +**接口。** `POST /company/{ts_code}/review/feedback`,请求体 `useful`、`note`、`reader`、`period`、`review_version`,后两者缺省取索引表最新行;索引表没有这家回 404。`GET /company/{ts_code}/review/summary` 只加一个键 `feedback`。 + +**前端。** `client.js` 加 `companyReviewFeedback(ts, payload)`;`StockView.jsx` 的评析块在"十视角"行后加两枚按钮,只在评议状态是 ok 或 half 时显示,点击后写入并清该票摘要的缓存,已有记录时显示"已记"与时刻并高亮当前选项。 + +**`bridge_job_store.py`(新)。** 表 `bridge_job_runs`:`id`、`job`、`steps`、`task_id`、`state`(accepted、running、success、failed、rejected、auth_error、unreachable、timeout、lost、skipped_no_key、dry_run)、`http_status`、`note`、`artifact`、`tail JSONB`、`triggered_at`、`ended_at`。函数 `open_run`、`close_run`、`latest(job)`、`on_day(job, day)`、`summary(job)`。 + +**`bridge_jobs.py`(新,http 可注入)。** `trigger(base, key, steps, *, http=None)` 打 `GET {base}/api/v1/xxl/daily-build?steps=plan-review`,钥匙走头 `X-Job-Key`;`poll(base, key, task_id, *, every, max_wait, http, sleep)` 轮询 `/api/v1/xxl/status/{task_id}`,404 记 `lost`(选股系统接口容器重启会清掉内存里的状态);`artifact_from_tail(tail)` 从"已写入 ... .md"抽路径;`run_plan_review(*, dry_run)` 读 `AKG_BRIDGE_BASE` 与 `AKG_BRIDGE_XXL_KEY`,钥匙空只记一行跳过。 + +**`tasks.py`。** 路由 `"akg.trigger_plan_review": {"queue": "interactive"}`;定时 `crontab(hour=20, minute=10, day_of_week=5)`,注释写清为什么二十点十分。任务只转调 `bridge_jobs.run_plan_review`。`main.py` 加 `POST /admin/trigger_plan_review?dry_run=&sync=`。 + +**日检。** 人读记录一行恒信息级;周报触发一行周一按上周五那条判 ok 或警告,平日信息级。 + +--- + +## 附录丙(可不读):评析第二批实现 + +**分段器。** `sectionizer.py` 只加不改:`SECTION_PROFILE_VERSION = "1"`;`PROFILES["annual_report_review"]` 三类,字典顺序即优先级,核心竞争力先于经营与行业;`subcut` 规定风险因素从展望段里第一个风险词根处截起;新函数 `sections_by_category(text, profile_name) -> dict[str, list[Section]]`。原 `annual_report` 类别表冻结快照进单测。 + +**材料层 `materials.py`。** 常量 `MATERIALS_VERSION`、每类最多四段、每段最多六千字、论断最多二十条、可比公司最多十家。数据类 `Material(ref, kind, key, title, heading, category, text, date, meta)`。函数:`annual_report_docs(code, *, years=1)`(标题口径,同一年度多版取披露日最新)、`load_parsed_text(raw_uri)`(只读 `parsed/v2/{raw_uri}.txt`)、`mask(text, names)`、`collect(code, *, asof, fetch=None, years=1, want=...)`(八路各自 try,返回 refs、by_kind、fingerprint、stats、errors)、`number(items)`(编号稳定)、`fingerprint(mat)`(章节按文档号、类别、序号、正文哈希、解析器版本、类别表版本;图谱关系按谓词、对象、占比、披露日;环节评析按环节名与倾向;可比按代码;论断不进)、`excerpt(mat, ref, n=400)`、`allowed_numbers(mat, refs)`。 + +**公共调用件 `llm_json.py`。** 从 `synthesis.py` 抽出 `safe_json` 与 `call_json(client, system, user, *, max_tokens, budget, spent=0)`,三条纪律不变,评议模块改为引用。 + +**定性层 `qualitative.py`。** `QUAL_VERSION = "2026.09-1"`;三组 `business`、`governance`、`market`,一条判据只进一组;系统提示词只告诉模型"材料里有没有足以回答它的依据",不知道公司是谁,不用表外知识,每条判定必须给编号,不得出现材料里没有的数字。函数:`client_for(intraday: bool)`(盘后 `worker_large`,盘中 `worker_large_cloud`,档位不可用回 None)、`build_calls(questions, mat, *, input_chars)`、`validate(raw, call, mat, *, allowed_extra)`、`run(mat, *, client, questions, max_tokens, budget, allowed_extra)`。校验十条:问题编号不在集合丢弃;`passed` 非三态记坏值;编号逐个清洗只认本次材料里的;判定了却没编号拒收;漏答记未答;引文不在材料里记警告不改判定;理由里的数字逐个回查;理由截八十字引文截六十字;同一问题多次取第一条;表外措辞记警告。状态:全部应发的调用成功 ok,部分失败 half,无材料零调用 thin。 + +**判据公共件。** `scores.check_text(cid, name, question, j, *, reason="定性阶段未跑")`,与 `check()` 同形,多 `evidence_refs`、`why`、`quote` 三键,单位固定 `text`,备注带编号。 + +**视角。** 每个新视角模块的 `LENS` 加 `"needs": ("materials", "qual")`,有定性判据的加 `QUESTIONS` 列表(编号、名称、组、问题、类别)。`lenses/__init__.py` 的 `run_all(res, *, materials=None, qual=None)` 只对声明了的传关键字参数,新增 `qual_questions()`。五个视角: + +| 视角 | 判据 | 材料 | +|---|---|---| +| 费雪十五问 | 十三条文本加两条数字(净利率不低于 8%、总股本同比不超过 0.5%) | 章节 | +| 段永平 | 数字:主营第一大项占比三年变动不超过 15 个百分点、毛利率不低于 30%、现金转化不低于 0.9、净资产收益率十年平均不低于 15%、自由现金流收益率不低于 4%;文本:本分、长期主义、对用户承诺 | 章节 | +| 林奇归类 | 六类归类按周期、困境反转、隐蔽资产、快速、稳健、缓慢的顺序先命中先得;市盈率对增速不超过 1;冷门度按覆盖机构不超过五家;主营可解释性第一大项不低于 50%;存货应收增速判据标不在数据源 | 无 | +| 波特五力 | 数字:客户集中度(供应边出边最大占比不超过 30%、前五和不超过 60%)、供应商集中度(入边同上)、竞争者数量(主环节成员不超过十五家);文本:替代品、新进入者、同业竞争 | 图谱供应边、成员数、论断、章节 | +| 巴菲特文本部分 | 护城河四问、管理层坦承失误、资本配置理由、可核验目标 | 章节 | + +新增 `graph_store.supply_edges(ts_code, cap=40)` 取两向供应边带占比;`claim_store.opinion_claims_for` 补 `claim_id` 第二排序键;新增 `claim_store.drives_claims_for(subjects, limit=40)` 替代全表回读。 + +**报告与摘要。** 第一段加材料与定性阶段两行;第三段文本判据同表,末尾加"3.末 材料编号对照";第六段措辞改为"缺年报正文的公司已按材料需求单登记;缺章节的写明类别"。摘要加 `qual`、`n_materials`、`grade_counts_b23`、`lynch_category`。 + +**编排。** `runner.run(..., with_qual=False, qual_client=None, materials_fetch=None)`;指纹加 `qual:{QUAL_VERSION}` 与 `mat:{材料指纹}`;`_qual_gate` 三道闸:当日上限、材料层报错、档位不可用。索引表加三列 `qual_used`、`qual_status`、`materials_fp`。批任务加 `with_qual`、`max_qual`,盘中批的定性档位取盘中档位,评议随定性。 + +**费用与耗时。** 本地每家三次调用约三到五分钟,零费用;盘中云端溢出档每家约几分钱。一批最坏三十家数字加十家定性加十家评议,并发二,约四十分钟,不撑爆一小时。 + +--- + +## 附录丁(可不读):评析第三批实现 + +**指标层新增。** `pe_ttm_median_10y`、`pb_median_10y`、`roe_max_10y`、`gm_max_10y`、`peg`(增速不为正时空)、`fcf_yield`、`cons_eps_growth`、`expectation_gap_eps`、`implied_pe_vs_cons`、`pe_vs_hist_median`、`bz_top1_share`、`bz_top1_share_chg_3y`。全部进指标列表,自动进侧车与数字回查允许集合。 + +**四个视角。** + +| 视角 | 判据 | +|---|---| +| 莫布森 | 预期差不超过正 10 个百分点;隐含市盈率对一致预期不超过 1.2;市盈率对十年中位不超过 1.3;价格在两百五十日区间位置不超过 70%;投入资本回报率不低于十年平均净资产收益率。结论句写"一致预期要求下一年每股收益增长 x%,历史复合 y%,差 z 个点" | +| 达摩达兰 | 三情景对照表:每情景价等于每股收益乘市盈率(已有三情景);反推所需增速、所需净资产收益率、所需市盈率。判据:中性所需增速不超过历史复合增速加 10 个百分点;中性所需净资产收益率不超过十年最高;中性市盈率不超过 1.5 倍十年中位;乐观所需净资产收益率不超过 1.2 倍十年最高;悲观价不低于现价七成。无一致预期全部算不了 | +| 邱国鹭 | 品质:十年里净资产收益率不低于 15% 的年份占七成以上、毛利率十年标准差不超过 5 个百分点、主环节成员不超过十五家;估值:市盈率与市净率十年分位不超过 50%、市盈率不超过同环节中位、市盈率对增速不超过 1.5。附注固定"时机不在本报告,归择时决策系统" | +| 马克斯 | 环节评析倾向不为偏空;市盈率与市净率十年分位不超过 70%;杠杆与资产负债率不高;价格区间位置不超过 70%;毛利率不在十年高点。多环节取成员最少的为主环节 | + +**评议扩展。** `build_input` 加视角索引段(`[L1] 薛云奎四维分析法 评价 好`)、材料摘录段(只放被文本判据引用过的编号,每条不超过四百字);判据行的能判计数改为按 `passed` 非空计;系统提示词加论点与反方各带 `lens_refs`、预期字段须引用一致预期或预期视角的判据编号、第六项视角分歧最多三条各引两个视角编号;正则 `^[MCSRGKL]\d+$`;后处理校验 `lens_refs`,论点无视角引用记 `thesis_without_lens_ref` 并降为 half;渲染加"引用视角"行与 5.6 视角分歧。摘要加 `expectation`、`cycle`、`thesis_lens_refs`。 + +--- + +## 附录戊(可不读):选股系统小改 + +**`GET /review/latest`。** `config.py` 加 `REVIEW_DIR = os.environ.get("REVIEW_DIR", "data/review")`。新 `review_latest.py`:`latest_report(dir, *, start="next_close")` 只认 `复盘_YYYY-MM-DD_{start}.md`,按日期倒序取第一;`head_lines(path, n=20)`;`marker_counts(path, markers)` 默认标记 `("公司质地=", "五日头", "二十日头")`;`payload(...)`。`api.py` 末尾加路由,没有周报回 404。测试 `test_review_latest.py` 用临时目录三份文件,末行 ALL OK。README 接口表加一行。重启接口容器要审批、避开七点到七点半与八点半到九点零五、重启后预热计划接口。 + +**周报加两行。** `plan_review.compare_table` 在择时决策系统那一行下面加"择时决策系统·五日头"与"择时决策系统·二十日头",读数函数 `timing_head_eval(since, until, head)` 与现有择时自评同款,从 `decision_outcome` 按两个头的判分种类名与期限取。种类名以探针读数为准。 + +--- + +## 附录己(可不读):单测与文件清单汇总 + +**单测新增(标准库 unittest,全部离线)。** + +| 文件 | 例数 | 覆盖 | +|---|---|---| +| `tests/company_review/test_freshness.py` | 8 | 应披露期边界、期比较、旧行兼容、批任务挑选四类、落后读数分级 | +| `tests/company_review/test_company_review.py`(改增) | 5 | 指纹向后兼容、两键拆分、报告头部两个期、视角数改为清单长度、六段标题不变 | +| `tests/ingest/test_dispatch_policy.py` | 5 | 队列判定、只投见底队列、陈旧类要在飞信息、上限与顺序、补投次数上限 | +| `tests/company_review/test_materials.py` | 11 | 编号稳定、材料指纹变与不变、上限截断、按标题选年报、缓存缺失记账不解析、脱敏、允许数字;需求单优先级与理由、年报标题判定 | +| `tests/acceptance/test_acceptance.py` | 8 | 期比较、地板期、评析读数六情形、连续五日规则、信号分布、人读规则、结论行、应披露期契约 | +| `tests/company_review/test_feedback_store.py` | 1 | 归一 | +| `tests/bridge/test_bridge_jobs.py` | 4 | 触发四种结局、轮询三跳、产物路径抽取、无钥匙不发请求 | +| `tests/extraction/test_sectionizer_review.py` | 4 | 三类命中、展望无风险词根为空、原类别表冻结、表格行不当标题 | +| `tests/company_review/test_qualitative.py` | 12 | 分组与预算、有编号通过、无编号拒收、坏编号、空判定不拒收、未答、引文回查、数字回查、截断不重试、空答重试一次、预算、无材料 thin、等级计算 | +| `tests/company_review/test_lenses_batch2.py` | 8 | 林奇归类顺序与边界、波特集中度与成员数、定性未跑全空、带编号、段永平稳定性 | +| `tests/company_review/test_lenses_batch3.py` | 5 | 莫布森预期差、达摩达兰对照表、邱国鹭估值与可比、马克斯倾向、新指标 | +| `tests/company_review/test_synthesis.py`(改增) | 7 | 两键相等提示词不变、视角索引、只放被引用摘录、论点须引视角、分歧校验、渲染、能判计数 | +| `tests/company_review/test_quality.py`(增) | 1 | 第二三批视角不影响质地合成 | +| 选股系统 `test_review_latest.py` | 1 | 目录注入取最新 | + +预期总数:现有二十五加约八十,本地一条命令 `OK`。 + +**文件清单(本仓库,按工作包)。** + +保运包:`backend/app/analysis/company_review/{periods,dataset,metrics,report,summary,synthesis,runner}.py`、新 `freshness.py`、新 `materials.py`(需求单部分)、`backend/app/store/{company_review_store,fin_statements,claim_store}.py`、新 `backend/app/store/extraction_dispatch.py`、新 `backend/app/orchestration/dispatch_policy.py`、`backend/workers/tasks.py`、`backend/app/api/routes_ingest.py`、`backend/app/main.py`、`backend/scripts/{daily_check,requeue_no_run_docs,batch_ingest,annual_report_gap_list}.py`、新 `backend/scripts/fulfill_annual_demands.py`、`db/postgres/init.sql`、`frontend/src/views/DemandsView.jsx`。 + +判收读数包:新 `backend/app/analysis/acceptance.py`、新 `backend/scripts/acceptance_readings.py`、新 `backend/app/store/company_review_feedback_store.py`、新 `backend/app/store/bridge_job_store.py`、新 `backend/app/analysis/bridge_jobs.py`、`backend/app/main.py`、`backend/workers/tasks.py`、`backend/scripts/daily_check.py`、`frontend/src/api/client.js`、`frontend/src/views/StockView.jsx`、`.env.example`。 + +评析第二批:`backend/app/extraction/sectionizer.py`、新 `company_review/{materials,llm_json,qualitative}.py`、`company_review/{scores,report,runner,summary,synthesis,__init__}.py`、`company_review/lenses/__init__.py`、新 `lenses/{fisher,duan,lynch,porter,buffett_text}.py`、`backend/app/store/{company_review_store,claim_store,graph_store}.py`、`backend/workers/tasks.py`、`backend/app/main.py`、`backend/scripts/company_review_run.py`、新 `backend/scripts/company_review_materials_probe.py`、`backend/scripts/daily_check.py`。 + +评析第三批:`company_review/{metrics,synthesis,report,summary,__init__}.py`、新 `lenses/{mauboussin,damodaran,qiu,marks}.py`。 + +文档:`docs/下一阶段开发方案与规格书_2026-09-15.md`(本文)、下一份交接文档(保运三段、上游同步待办一节、每日节奏加周五二十点十分)、`docs/评审记录_<日期>.md`(评审时写)、选股系统仓库 `docs/复盘决定台账.md` 两条。