股票估值端到端协调层 V2

创建人员：dev.developer.project.secondary / infodev-2
文件职责：说明 project 级股票估值 V2 协调层的入口、终态、产物、复算和边界。
管理规范/方案：开发方案/CODE-DESIGN-PROJECT-INFO-STOCK-VALUATION-PIPELINE-V2-V003.md 至 V007.md。
代码入口：dev/project-dev/stock_valuation_pipeline_v2/
测试入口：dev/project-dev/test/stock_valuation_pipeline_v2/test_pipeline_v2.py

1. 用途和边界

V2 接受 ticker + as-of，并发取得公告身份、行情、法定财务和机构预测，执行 as-of 检查、内容寻址缓存、公司增量基线、字段级来源回链、自动 QA 和固定 16 节 Markdown 报告。估值计算只桥接只读的 V1 dev/ana-dev/stock_valuation_pipeline 公共接口，不复制公式、校验或 V1 报告实现。

工具输出用于研究、复算和数据准备，不构成交易指令、收益承诺或自动投资决策。禁止把 as-of 之后发布或形成的数据带入本次计算。

2. 运行环境

• Python 3；协调层只使用 Python 标准库。
• 从项目根目录运行，并把 dev/project-dev 加入 PYTHONPATH。
• 公开网络 provider 当前限于 registry 中登记的巨潮资讯和东方财富 HTTPS 端点；未知 host 在 transport 前拒绝。

$env:PYTHONPATH="dev/project-dev"
python -m stock_valuation_pipeline_v2 --help

3. ticker + as-of 入口

$env:PYTHONPATH="dev/project-dev"
python -m stock_valuation_pipeline_v2 `
  --ticker 001270.SZ `
  --as-of 2026-08-01 `
  --cache-dir dev/tmp/valuation-v2/cache `
  --output-dir dev/tmp/valuation-v2/out

--task-start 接受带时区且不晚于进程启动时刻的实际用户任务起点，用来区分：

• process_wall_seconds：本次进程从启动到原子提交完成；
• task_wall_seconds：用户任务起点到原子提交完成。

若不传 --task-start，任务起点采用本次进程起点。已有正式输出目录会在任何缓存或网络动作前拒绝；只有显式 --force 才允许走可回滚替换状态机。

4. 最小人工判断覆盖层

没有 --judgment 时，机械阶段成功终态固定为 DATA_READY_NEEDS_JUDGMENT，不会生成 valuation_snapshot.json、valuation_results.json，也不会在报告中伪造估值方向、价格区间或结论。

python -m stock_valuation_pipeline_v2 `
  --ticker 001270.SZ `
  --as-of 2026-08-01 `
  --judgment dev/project-dev/test/stock_valuation_pipeline_v2/fixtures/chengchang_20260801/judgment_overlay.json `
  --cache-dir dev/tmp/valuation-v2/cache `
  --output-dir dev/tmp/valuation-v2/out-with-judgment

覆盖层只允许提供分析文字、归一化调整、估值情景和持有期假设。价格、股本、法定财务、日期、A1 身份和来源回链属于受保护字段，覆盖即输入错误。

5. V1 兼容入口

$env:PYTHONPATH="dev/project-dev"
python -m stock_valuation_pipeline_v2 `
  --input valuation_snapshot.json `
  --output-dir generated

此入口校验 V1 模块、registry 和函数签名指纹，再调用 V1 CLI 合同，保留 V1 的退出码 0/2/3、三件套产物和 GENERATED/REUSED 语义。合同漂移时 fail-fast，不退化为第二套计算实现。

6. 终态和退出码

标准输出始终是单个 JSON 对象。包括 argparse 参数错误在内，ticker 模式都不把非规范错误写到 stdout 之外；成功对象包含正式目录、manifest 和外部 commit receipt 的路径、bytes、SHA-256，以及两种墙钟；失败字段统一使用 JSON null，不使用空串冒充缺失值。

7. 正式产物

成功正式目录固定包含：

• data_snapshot.json
• provider_results.json
• snapshot_build_report.json
• source_evidence.json
• gaps.json
• report.md
• qa_report.json
• runtime_metrics.json
• runtime.log
• manifest.json（目录内最后写入）

有 judgment 时再包含 valuation_snapshot.json 和 valuation_results.json。同级外部 <output>.commit-receipt.json 使用 schema 2，只写一次并绑定 run、终态、正式目录、manifest 指纹、commit_ready_at 和 receipt_write_started_at；它有意不写自指的“最终写后墙钟”。receipt 原子写入、重新读取、复算 hash/bytes、校验并尝试清理备份之后，ticker stdout 的 terminal_at/task_wall_seconds/process_wall_seconds 才是最终墙钟权威。包内 runtime 仍冻结在 commit_ready，不会为补写墙钟而破坏 manifest。

report.md 的 16 节顺序固定为：结论摘要、市场和资本结构、信源优先级、业务及利润来源、历史盈利、TTM 与归一化、机构预期、利润质量与现金流、模型选择、三情景、反向隐含条件、交叉验证、持有期测试、风险与触发器、复评清单、数据局限和复算摘要。

snapshot_build_report.json 保存每个核心值的 field -> source_id -> A1 -> raw_hash 机器可读回链；法定财务必须绑定到相同期间的年度/季度 A1 公告。上年同期值必须来自本期 A1 同一响应中的明确比较列，并记录 same_response_comparative_row、本期/比较期和共享发布日期，不能把独立 2025 行挂到 2026 Q1 A1 名下。自动 QA 不只检查标题，还检查 16 节唯一顺序、Markdown 围栏/表格/本地链接、字段回链、raw field/hash、A1 支持范围与期间、比较关系、受保护字段、V1 数值、as-of 和确定性重渲染；任一失败都不能提交正式包。

8. 信源、停止和 as-of

• A1 公告身份：巨潮公告索引；截止时刻按 Asia/Shanghai 的 as-of 日末构造，核心财务必须能回链至不晚于 as-of 发布的法定年度/季度报告。
• 行情与股本：东方财富历史 K 线和行情接口；K 线查询窗口为 as-of - 14 个自然日至 as-of，过滤未来行后按 f51 取最大日期。实时行情的 f124 必须证明与该交易日一致，不能把当前股本/市值改标成历史日期；历史股本只有同 as-of 的 FRESH 语义基线或可验证实时日期才能使用，否则核心阻断。
• 结构化财务：东方财富利润表、资产负债表、现金流量表及主要指标；资产负债表完整键/alias 规则不满足即阻断。
• 机构预测：固定汇总和明细端点；只接受响应中的真实 REPORT_DATE/UPDATE_DATE，不以请求 as-of 伪造发布日期或期间。汇总 4 家、明细 3 家只形成一个 W_FORECAST_COVERAGE gap，不进行无界搜索。

所有请求共享唯一 90 秒单调 task deadline。请求、2xx 与 4xx/5xx 响应体读取、重试和退避均裁剪到剩余预算；错误体也使用分块、剩余 socket timeout 和可取消读取，不会在 HTTPError 分支绕过截止时间。四个 worker 截止后不创建新请求或写缓存/基线；协调层最多再等待 1 秒让受控传输协作返回。非核心缺口按 gap 降级，核心缺口阻断。

9. 缓存和公司基线

请求 fingerprint 对规范化后的 provider、method、精确 endpoint、保序重复 query、headers、form/JSON body、adapter 版本和 as-of 计算。registry 同时限制 host/path/method、精确 query/body 键和值、request/response content-type 与逐 provider 响应上限；重定向、路径/query/reportName 变体在 transport 前拒绝。HTTP 成功响应先以 PENDING_PARSE 写原始归档，只有 adapter 完成 schema/as-of 解析后才提升为可复用逻辑索引；4xx/5xx、空响应、字段漂移和未确认响应不会永久命中。

公司基线按 stock_identity/announcement_index/market_close/shares_market_cap/finance_main/finance_income/finance_balance/finance_cashflow/forecast_summary/forecast_detail 逐类保存 provider/fingerprint、schema/version、as-of、TTL、水位、语义状态、来源 raw hash 和 data hash。每类在固定进程起点判为 FRESH/STALE/MISSING：FRESH 直接从其内容寻址 blob 装载，只有目标 stale/missing 种类会运输；核心刷新失败则整次阻断且不推进 current.json，非核心按 gap 降级；STALE 不进入正式值。基线 envelope/data hash 与逐 data-kind blob 完整性分开校验：单个 blob 缺失或被篡改只把对应种类判为 STALE，其余健康种类保持 FRESH；相同 digest 路径若实物哈希错误，刷新时原子重写并写后复验。缓存层把 repair 写失败或写后复验失败显式标为完整性失败；任一 kind 出现该信号，或十类条目/实物不完整，workflow 都跳过 company baseline/current 提交。核心种类仍阻断，非核心 forecast 可保留带 gap 的正式输出，但不得新建、替换或归档活动基线，也不得提升目标 reusable。成功增量合并后，同一 as-of 的上一活动基线移入 history/，原始 blob 继续保留，baselines/ 只留下新活动世代，避免旧 stale 候选因 hash 排序再次胜出。活动候选选择仍严格按最大 baseline_as_of、最大规范化 watermark、ASCII 最大的小写 data_hash；较新的未来基线不能污染旧 as-of 回跑。current.json 在 ticker 级进程/系统锁内重新读取并原子更新，避免并发 TOCTOU。所有 blob、索引、基线和正式输出均使用临时文件加原子替换。

10. 离线 fixture 与复算

$env:PYTHONPATH="dev/project-dev"
python -m stock_valuation_pipeline_v2 `
  --ticker 001270.SZ `
  --as-of 2026-08-01 `
  --fixture-dir dev/project-dev/test/stock_valuation_pipeline_v2/fixtures/chengchang_20260801 `
  --cache-dir dev/tmp/valuation-v2-fixture/cache `
  --output-dir dev/tmp/valuation-v2-fixture/out

fixture 模式禁止真实 transport，只读取 fixture_manifest.json 登记的响应，可用于冷/热缓存、负响应、schema 漂移、未来信息、原子提交和 V1 数值一致性回归。

提交前以词法绝对路径逐级 lstat 检查文件、目录、符号链接和 Windows reparse point，不先跟随链接解析。--force 只有在新目录和外部 receipt 都耐久写入后才宣告成功；真实提交失败恢复旧目录/receipt并保留双异常证据，备份清理失败则保留新成功和备份、只发 warning，不把已成功的新真值回滚。

11. 已知限制

• 当前只实现首期 A 股公开 provider registry，未实现 GUI、API 服务、数据库或批处理。
• 未接入付费、登录态或绕过访问控制的数据源；provider 页面变更会通过 schema drift 阻断或 gap 暴露。
• 机构明细可能受公开页面结构变化影响；系统不会为补齐明细进行无界查找。
• 首期公开行情接口可能不给出可验证的历史股本时间戳（例如 f124=0）；此时真实历史 as-of 会诚实 BLOCKED/E_CORE_INPUT，不会用当前股本冒充历史股本。可在未来经独立方案审核后增加历史股本信源，但当前实现不会静默扩 provider。
• DATA_READY_NEEDS_JUDGMENT 只是数据准备完成，不应被解释为方向性估值结论。