edit | blame | history | raw

股票估值端到端协调层 V2 编码方案 V002

创建人员：dev.developer.project.secondary / infodev-2
文件职责：在不修改、不复制 ana-dev V1 计算内核的前提下，冻结 project 级股票估值端到端协调层的接口、证据、缓存、失败、报告、性能和验收合同。
关联事项：DEV-ANA-STOCK-VALUATION-PIPELINE-V2-20260801-001。
上游依据：用户关于日常开发员接手 V2 的原生任务委派；dev-doc/ana-doc/开发方案/CODE-DESIGN-ANA-STOCK-VALUATION-PIPELINE-V2-V001.md；股票价格合理性评估操作手册；V1 流水线与铖昌科技既有结果。
管理规范/模板：../../../common/dev-doc/编码规范.md；../../编码规范.md；../../开发审计规范.md。
引用文件：../开发工作区说明.md；../../../dev/ana-dev/stock_valuation_pipeline/README.md；../../../outputs/20260730_stock_valuation_guide/股票价格合理性评估操作手册_v1.0.md。
记录方式：重型编码方案；dev.reviewer.project 在 dev-doc/开发审计报告.md 给出方案 PASS 前不得实施重型代码。

1. 接手、重分类与方案继承

  1. 原 V001 已冻结业务目标，但实现落点为 dev/ana-dev/stock_valuation_pipeline/，负责人和审核员分别是 dev.developer.ana.cai、dev.reviewer.ana.cai；后者会话失效，未产生独立 PASS。
  2. 本次由项目日常开发池明确将事项交给空闲的 dev.developer.project.secondary。合法实现落点改为 dev/project-dev/stock_valuation_pipeline_v2/，测试落点为 dev/project-dev/test/stock_valuation_pipeline_v2/，审核员改为共享 dev.reviewer.project。
  3. V001 的业务目标、状态、四类来源、性能指标和验收底线继续作为输入；V002 取代 V001 成为本次实现方案。V001 保留为历史证据，不改写、不冒充已审核方案。
  4. dev/ana-dev/stock_valuation_pipeline/ 及其测试、Schema、注册表和 README 在本事项中全部只读。V2 通过稳定 Python 入口调用 V1，不复制公式、校验或报告计算逻辑。
  5. 如后续发现必须修改 V1 公共合同，立即停止相关实现并向 project.admin 申请一事项范围调整；未获调整前不得写 ana-dev。

2. 问题、目标与非目标

2.1 问题

V1 只能在人工准备好 valuation_snapshot.json 后执行毫秒级计算。用户从提出 ticker/as-of 请求到收到完整报告的主要时间仍消耗在资料取得、来源校验、快照构建、报告扩写和人工终检，现有引擎耗时不能代表总墙钟。

2.2 目标

  1. 新增 ticker + as-of 端到端入口，同时保留 V1 --input 兼容入口。
  2. 并发取得公开行情、法定公告索引、结构化财务和机构预测，并在预算内结束或降级。
  3. 保存原始响应哈希、请求索引、来源元数据、A1 回链、公司基线和增量水位。
  4. 有判断覆盖层时构造合法 V1 快照并调用 V1 计算核心；无覆盖层时不伪造情景或方向性结论。
  5. 固定生成 16 节 Markdown、自动 QA、原子提交、运行 manifest 和从用户任务起点开始的总墙钟。

2.3 非目标

  1. 不连接付费数据库，不绕过登录、验证码、反爬或访问控制。
  2. 不修改 V1 计算公式、Schema、注册表、缓存或报告实现。
  3. 不复制 V1 核心到 project 目录，不建立第二套估值公式实现。
  4. 不自动推断未披露客户、订单、型号或敏感军工事实。
  5. 不输出交易指令、收益承诺或自动批准的投资结论。
  6. 不引入 GUI、常驻服务、数据库、定时任务或第三方 Python 依赖。

3. 代码、测试与文档落点

dev/project-dev/
  stock_valuation_pipeline_v2/
    __init__.py
    __main__.py
    cli.py
    telemetry.py
    http_client.py
    cache.py
    providers.py
    acquisition.py
    snapshot_builder.py
    judgment.py
    v1_bridge.py
    full_report.py
    report_qa.py
    workflow.py
    provider_registry.json
    judgment_overlay.schema.json
    README.md
  test/stock_valuation_pipeline_v2/
    test_*.py
    fixtures/chengchang_20260801/

dev-doc/project-doc/
  股票估值端到端协调层V2.md
  开发方案/CODE-DESIGN-PROJECT-INFO-STOCK-VALUATION-PIPELINE-V2-V002.md

现有操作手册位于角色常规写入范围之外。实现和审核期间先在 project 文档中维护 V2 使用说明；正式修改原操作手册前需由 project.admin 明确授予该单文件写入范围，或由其根据本事项证据代为同步。不得用“用户委派”静默扩大目录权限。

4. CLI 与兼容合同

4.1 V1 兼容入口

python -m stock_valuation_pipeline_v2 `
  --input <valuation_snapshot.json> `
  --output-dir <output-dir> `
  [--force]

该模式只做参数校验和 V1 桥接，调用 V1 run_pipeline，保留 GENERATED/REUSED、退出码和三件套产物语义。不得改变传入快照或追加 V2 结论。

4.2 ticker/as-of 入口

python -m stock_valuation_pipeline_v2 `
  --ticker 001270.SZ `
  --as-of 2026-08-01 `
  --output-dir <output-dir> `
  --cache-dir <cache-dir> `
  [--judgment <judgment_overlay.json>] `
  [--fixture-dir <fixture-dir>] `
  [--task-start <ISO-8601>] `
  [--force]

硬合同：

  1. --input 与 --ticker 互斥；ticker 模式必须给 as-of、output-dir、cache-dir。
  2. ticker 规范化为 NNNNNN.SZ/SH/BJ；无法确定市场时在网络前失败。
  3. as-of 不得晚于当前本地日期；所有来源按发布日期和数据日期双重过滤。
  4. fixture 模式禁止打开网络；夹具缺失是显式合同错误。
  5. stdout 只输出结构化终态摘要，进度写 stderr 和 runtime.log。

5. 两阶段数据与判断合同

V1 的 valuation.scenarios 必须非空且必须包含唯一基准情景。因此 V2 不得在无 judgment 时捏造机械场景来强行调用 V1。

5.1 无 judgment

  1. 采集、证据、字段级来源、公司基线和数据快照照常完成。
  2. 生成 data_snapshot.json、snapshot_build_report.json、16 节数据就绪报告、QA、gap、遥测和 manifest。
  3. 情景、结论、触发器等判断章节明确写 GAP：需要人工判断覆盖层，不得出现方向性价格结论。
  4. 终态固定为 DATA_READY_NEEDS_JUDGMENT；不生成伪 V1 valuation_snapshot.json 或 valuation_results.json。

5.2 有 judgment

  1. judgment_overlay.schema.json 仅允许业务摘要、归一化调整、三情景、主模型、交叉验证、风险、上下调触发器、持有期和结论边界。
  2. 覆盖层不得写价格、股本、法定利润、财务期间、来源日期或 A1 文档身份；出现禁写字段立即 E_JUDGMENT_CONFLICT。
  3. 覆盖层与数据快照合并后生成合法 V1 valuation_snapshot.json，通过 v1_bridge.py 调用 V1 load_snapshot 和 compute_valuation。
  4. V1 计算结果是所有数值章节的唯一来源；V2 报告模板不得重新计算 PE、PB、PS、情景、反向 PE 或持有期结果。

6. 统一提供者合同

四类适配器统一返回：

{
  "provider_id": "market",
  "adapter_version": "1.0.0",
  "status": "OK|GAP|BLOCKED",
  "fetched_at": "ISO-8601",
  "as_of_date": "YYYY-MM-DD",
  "records": [],
  "sources": [],
  "gaps": [],
  "warnings": [],
  "raw_artifact_hashes": []
}

6.1 法定公告索引

取得交易所或巨潮公开公告索引，登记证券代码、标题、公告日期、报告期、公告 ID、原文 URL、修订状态和支持字段。财务核心字段必须能回链至 A1 原文；公告索引不负责凭叙事直接填利润。

6.2 行情

取得不晚于 as-of 的最近交易日收盘价、价格时间、总股本和平台市值。自动检查 价格×股本 与平台市值差异；当前股本晚于历史 as-of 时不得回填历史快照。

6.3 结构化财务

取得最近完整年度、本期累计、上年同期累计、资产负债和现金流字段；每个记录带报告期、公告日期、单位、币种和 A1 公告 ID。结构化字段无法回链 A1 时为 gap；与 A1 明示数值超容差时阻断受影响字段。

6.4 机构预测

保存汇总机构数和可见明细两套记录。汇总 4 家、明细 3 家只形成一个 W_FORECAST_COVERAGE gap；最多查询两个登记来源，不为未知第四家无限搜索。明细日期晚于 as-of 的记录排除。

7. HTTP、并发与网络预算

  1. 仅允许 provider_registry.json 登记的 HTTPS 域名；巨潮如需 HTTP 回退必须在注册表明确标识并只用于公开公告查询。
  2. 连接超时 8 秒、单请求总读取超时 20 秒、单响应上限 20 MiB。
  3. 仅对超时、连接重置和 5xx 最多重试 2 次；4xx、解析错误和字段变化不盲重试。
  4. ThreadPoolExecutor(max_workers=4) 并发运行四类适配器。单个失败不取消其他来源，异常统一转 gap 或 blocked。
  5. 机械网络阶段总预算默认 90 秒；到达预算后取消未开始任务，等待中的请求依自身超时结束，不再发起新搜索。
  6. 进度日志记录 provider、开始、缓存命中、请求次数、完成、失败和耗时。

8. 可信信源停止规则与 as-of 安全

同一数字满足以下全部条件即停止搜索：

  1. 已取得 A1 原文或与 A1 公告 ID 可核对的结构化记录；
  2. 公司、报告期、币种、单位和口径明确；
  3. as-of 之前没有后续修正或替代版本；
  4. 报表勾稽或 价格×股本、EPS×股本 等数量关系无异常；
  5. 数量级合理且足以支持估值用途。

任何 publish_date > as_of、data_date > as_of、历史 as-of 使用当前不可历史化字段的行为均为 E_ASOF_VIOLATION，不得仅警告后继续。

9. 内容寻址缓存与公司增量基线

<cache-dir>/
  blobs/<sha256>.bin
  requests/<provider>/<request_fingerprint>.json
  companies/<market-code>/baseline.json
  companies/<market-code>/source_index.json

请求索引至少包含规范化请求、provider、ticker、as-of、请求/响应时间、状态、内容类型、字节数、SHA-256、适配器版本、来源发布日期和 complete=true。

复用必须同时通过请求指纹、blob 哈希、适配器版本、as-of 安全和完成标记；任一失败只废弃逻辑索引并重取，不删除其他 blob。fixture 响应也走同一缓存路径，以便机械验证缓存合同。

公司基线只在核心采集完成且基线自身哈希正确后原子提交。新 as-of 只刷新价格、最新公告状态、机构预测、股本、现金债务和公司行动；未重述历史报告按内容哈希复用。

10. 快照构建、字段来源与缺口

  1. snapshot_builder.py 从统一提供者结果建立唯一数据主记录，不直接读取网页模板字段。
  2. 金额统一为元、股本为股、价格为元/股；原始值和原始单位保留在证据包。
  3. TTM 输入固定为最近完整年度、本期累计、上年同期累计；由 V1 负责正式计算。
  4. snapshot_build_report.json 对每个 V1 字段记录来源 provider、source_id、raw_hash、转换、as-of 判断和状态。
  5. 核心行情、股本、TTM 三期利润或资产负债核心字段缺失时 BLOCKED_CORE_INPUT；机构、辅助说明或单一非核心来源缺失允许 COMPLETE_WITH_GAPS。
  6. gap 必须包含 gap_id、provider、字段、原因、影响、是否阻断、已用预算和建议人工补充，不得用 0、空字符串或测试值掩盖。

11. 16 节 Markdown 报告

固定章节顺序：

  1. 结论摘要；2. 市场和资本结构；3. 信源优先级；4. 业务及利润来源；5. 历史盈利；6. TTM 与归一化；7. 机构预期；8. 利润质量与现金流；9. 模型选择；10. 三情景；11. 反向隐含条件；12. 交叉验证；13. 持有期测试；14. 风险与触发器；15. 复评清单；16. 数据局限和复算摘要。

所有数值表格读取数据主记录或 V1 结果对象。无 judgment 的判断章节写明确 GAP 和需要的覆盖层字段，不得出现 TODO、TBD、待计算、默认倍数、默认方向性评级或伪价格区间。

12. 自动 QA

硬 gate：

  1. 16 个标题齐全、顺序唯一；Markdown 围栏成对；表格列数一致。
  2. 无 TODO/TBD/待计算/NaN/Infinity；本地产物链接存在。
  3. 报告关键数字与统一数据或 valuation_results.json 一致。
  4. 所有核心字段有来源，A1 回链存在，来源和数据日期不晚于 as-of。
  5. judgment 不得改写受保护字段；无 judgment 不得出现方向性估值结论。
  6. 不包含“买入、卖出、加仓、减仓”等交易指令或收益承诺。
  7. manifest 声明的每个正式产物哈希和字节数可复算。

外部 URL 在线可达性是警告，不因临时网络抖动改写已经生成的正式结果。

13. 状态、错误与降级

终态/错误 处理
COMPLETE judgment、V1 计算、报告和 QA 全部完成
COMPLETE_WITH_GAPS 非核心数据缺口已披露，硬 gate 通过
DATA_READY_NEEDS_JUDGMENT 数据和证据就绪，无方向性结论
BLOCKED_CORE_INPUT 价格、股本、核心财务或 A1 回链不足
E_INPUT_CONTRACT 网络前 fail-fast
E_ASOF_VIOLATION 阻断并保留失败证据
E_SOURCE_CONFLICT 阻断受影响核心字段
E_JUDGMENT_CONFLICT 覆盖层越权，阻断
FAILED 内部异常或提交失败

非核心提供者失败转换为一个有预算记录的 gap；不得 silent fallback，不得无限换站搜索。

14. 暂存、原子提交与失败证据

  1. 所有本次正式产物先写输出目录同级的唯一暂存目录。
  2. 每个 JSON 先写同目录临时文件、flush 后原子 replace；manifest 最后生成并含 complete=true。
  3. QA 全部通过后，暂存目录以一次 rename 提交到尚不存在的正式输出目录。
  4. 输出已存在时默认拒绝；--force 先形成完整新目录，再以备份交换，失败时恢复旧目录。
  5. 失败时暂存目录改名为 <output>.failed-<run_id>，只含 failure.json、runtime.log 和已形成的诊断产物；不得存在 COMPLETE manifest。
  6. 网络原始缓存可保留，但只有哈希、版本和完成标记都正确的索引才能复用。

15. 遥测与性能

runtime_metrics.json 必须包含：run_id、task_start、process_start、commit_ready_at、每阶段 started_at/finished_at/elapsed_seconds/status、provider 请求/缓存命中计数、task_wall_seconds 和 process_wall_seconds。

性能验收：

  1. 铖昌 fixture 冷运行 <5 s；相同缓存复跑 <2 s。
  2. 真实网络机械阶段目标 <90 s；外站异常也必须在预算内结束并形成 gap。
  3. V1 原 10 项测试全部通过；V1 --input 桥接输出关键结果与直接调用一致。
  4. 性能只比较同机、同夹具、同输出模式；不得用 V1 毫秒级计算时间冒充完整任务耗时。

16. 验收分层

16.1 L0

全包 py_compile/import、JSON Schema/注册表解析、V1 10/10 回归。

16.2 L1

覆盖 HTTP 超时/4xx/5xx/超大响应、fixture 禁网、缓存哈希篡改/版本变化/未完成标记/as-of 不安全、判断层禁写字段、报告结构和原子写。

16.3 L2 铖昌 fixture

  1. ticker/as-of 单命令生成全部适用产物；网络访问为 0。
  2. 有 judgment 时，市值、TTM 收入、TTM 归母、TTM 扣非、PB、PS、情景、反向 PE 和持有期关键数值与既有 fixture 一致。
  3. 无 judgment 时为 DATA_READY_NEEDS_JUDGMENT，不生成方向性价格区间。
  4. 汇总 4 家、明细 3 家只出现一个 forecast coverage gap。
  5. 冷运行 <5 s、缓存 <2 s。

16.4 L3 失败与回归

未来来源阻断；A1 与结构化财务冲突阻断；缓存篡改重取；无预测允许 gap；输出冲突、强制替换失败和中断不留下伪 COMPLETE；V1 --input 直接与桥接结果一致。

16.5 L4 真实网络 smoke

使用 001270.SZ 或另一只深市股票受控运行一次，核对请求索引、官方公告链接、价格日期、股本、市值、财务期间、机构日期、A1 回链和 90 秒预算。第二次运行证明历史 blob/公司基线复用；真实网络缺口如实记录，不把临时站点故障升级成伪成功。

17. 高风险点与控制

  1. V1 双实现：只允许 v1_bridge.py 解析并调用既有公共函数，测试比较直接与桥接结果。
  2. 无判断伪结论：无覆盖层不构造 V1 valuation 分组，不生成方向性结论。
  3. 未来信息：provider、builder、QA 三层检查 publish/data/as-of。
  4. 接口缩放变化：注册表版本化、原始响应归档、数量级和市值勾稽。
  5. 缓存误复用：请求、哈希、版本、as-of、完成标记联合门禁。
  6. 汇总/明细差异无限搜索：两个来源上限和单 gap 合同。
  7. 半成品冒充完成：暂存目录、manifest-last、目录级原子提交。
  8. 角色越权：实现和正式文档只写 project target；V1 与原操作手册分别保持只读，直到项目管理员明确调整单事项范围。

18. 审核门禁

本方案状态为 PENDING_DEV_REVIEWER_PROJECT_DESIGN_REVIEW。只有 dev.reviewer.project 在 dev-doc/开发审计报告.md 给出明确 PASS 后，才能创建 V2 代码、测试和 fixture。开发者不自审。