edit | blame | history | raw

案例存储体系

创建人员:management.admin
文件职责:记录 project-info 项目案例分析体系的数据、证据、研报资料、图片、结果包、MySQL 追溯和临时文件存储位置。
管理规范/模板:../../common/ana-doc/案例存储体系创建指南.md;../../common/ana-doc/案例分析环境创建指南.md。
引用文件:案例分析规范.md;行业与产业链研究模板.md;产业链地图通用模板与研究方法.md;案例审核规范.md;案例总纲.md;案例分析设计.md;案例执行日志.md;案例审计报告.md;研报体系/研报解析架构.md;研报体系/研报分析架构.md。
记录方式:存储体系入口;目录、表结构、结果包口径、研报归档口径或 MySQL 追溯规则变化时维护更新。

1. 基本原则

本文件是 project-info 的统一案例存储母版。研报存储规则已经融入本文件,不另建平行的正式 研报存储体系.md

核心原则:

  1. 文件系统保存原文、转换产物、证据包、结果包和 manifest。
  2. MySQL 保存可复用结构化事实、指标、公司映射、标签和索引。
  3. 所有正式文件型产物必须进入行业数据根目录、案例目录或父体系 result/img 目录,不能散落在私有工作区。
  4. 所有可复核结论必须能追溯到原始资料、转换结果、抽取事实、补充资料、证据索引或数据卡。
  5. 通用存储体系只定义跨行业底座,不预设具体行业专属表。
  6. 具体行业需要哪些表、字段和对象,由该行业的 <行业>研报解析方案.md 或具体 案例分析设计.md 定义。
  7. 暗线产物与普通行业事实分离存储、分离验收。
  8. 临时文件统一进入父体系 ana-data/tmp/<行业案例>/<case_id>/<run_id>/,只能保存可重建中间产物,不得作为正式证据入口。
  9. 所有行业的原始资料只进入行业统一 raw/ 池,不按 case、batch 或 run 分散存放。
  10. 凡是研报通用产物,例如转换文本、通用抽取结果、通用证据事实、通用补充资料和行业级 manifest,统一进入行业数据根目录;逐案例目录只保存该案例自己的输出、引用清单和结论证据映射。
  11. 数据抓取、MySQL 只读导出和市场反向补漏脚本统一放在 ana-data/tools/;脚本输出仍必须按行业和案例落到 cases/tmp/result/img/,不得留在工具目录。

2. 目录映射

路径 作用 状态
../ana-data/cases/ 逐行业统一 raw 池、行业级通用研报产物,以及逐案例正式输出、引用清单和证据映射 已创建
../ana-data/result/ 父体系结果入口、对外交付包、跨案例汇总结果包、审计辅助输出、父级汇总表 已创建
../ana-data/img/ 图片、图册、研报截图、OCR 图片、标注图和图片 manifest 已创建
../ana-data/tmp/ 临时数据和中间文件,按行业、case、run 分组,不得当正式结果 已创建
../ana-data/tools/ 数据抓取、外部来源归档、本地 MySQL 只读导出和市场反向补漏脚本;不是正式数据目录 已创建

项目内正式路径默认使用项目根目录相对路径,例如:

ana-data/cases/有色案例/manifest/artifact_manifest.csv

ana-data/tools/ 只保存可复用脚本和工具说明。脚本运行产生的网页快照、SQL、CSV、summary、manifest、市场反向补漏结果或错误记录,必须进入对应行业 supplement/evidence/manifest/ 或父体系 tmp/result/img,不得把工具目录当作结果包、证据包或临时文件池。

3. 研报类案例目录结构

每个正式研报行业必须有自己的行业数据根目录。原始研报、公告、网页快照和外部资料原件统一进入行业 raw 池,这是所有行业通用硬规则,不能按每个 case、batch 或 run 分散存放:

ana-data/cases/<行业案例>/raw/

例如:

ana-data/cases/有色案例/raw/
ana-data/cases/机器人案例/raw/

禁止创建或使用以下形式保存原始资料:

ana-data/cases/<行业案例>/<case_id>/raw/
ana-data/cases/<行业案例>/<case_id>/<batch_id>/raw/
ana-data/cases/<行业案例>/<case_id>/<run_id>/raw/

每个正式研报行业必须有自己的行业级通用产物目录。凡是与具体研究目标无关、可被同一行业内多个案例复用的研报处理产物,都进入行业根目录:

ana-data/cases/<行业案例>/
  raw/            # 行业统一原始资料池
  converted/      # 行业通用 PDF 转文本、表格抽取、OCR、格式标准化结果
  extracted/      # 行业通用事实抽取、观点拆解、指标候选、公司映射、资料缺口
  supplement/     # 行业通用公开资料补充、市场反向补漏、缺口补证
  evidence/       # 行业通用证据事实、来源定位、raw-to-converted trace、数据卡底座
  manifest/       # 行业级文件清单、来源清单、转换状态、迁移清单、处理批次索引

每个正式研报案例必须有自己的案例级目录。案例级目录只保存与该案例研究目标、输出和审核相关的自定义产物:

ana-data/cases/<行业案例>/<case_id>/
  outputs/        # 该案例的人读输出、行业/市场/公司视图、readout、对外版本
  manifest/       # 该案例引用了哪些行业级资料、batch/run、审核清单和结果包索引
  evidence/       # 该案例专属证据选择、结论到证据映射、审计抽样证据

研报案例还必须兼容父体系默认目录。临时、结果索引和图片不放入逐案例资料目录,而是按以下路径分流:

ana-data/tmp/<行业案例>/<case_id>/<run_id>/      # 临时文件和可重建中间产物
ana-data/result/<行业案例>/<case_id>/           # 结果入口、对外交付包、跨案例汇总索引
ana-data/img/<行业案例>/<case_id>/              # 图片、图册、截图、OCR 图片和图片 manifest

目录职责:

  1. 行业统一 raw/:只存原始资料。所有研报、公告、网页保存件、外部报告、PDF、Word、PPT、Excel、压缩包原件都必须先进入 ana-data/cases/<行业案例>/raw/,并保持不可覆盖、不可改写。不同案例、batch 或 run 对 raw 的使用关系通过 manifest 绑定,不通过复制 raw 文件或创建逐案例 raw 目录实现。
  2. 行业级 converted/:存转换后的文本、表格、OCR、页面切分结果和格式标准化结果,不存人工结论。转换产物可被同一行业多个案例复用,通过 case_idbatch_idrun_id 和 doc_id 在 manifest 中绑定使用关系。
  3. 行业级 extracted/:存从资料中抽出的通用事实、指标候选、观点、公司映射、产业链节点、资料缺口和初步分类结果。
  4. 行业级 supplement/:存公开资料补充、公告补证、网页来源、市场反向补漏、补充数据和来源快照。
  5. 行业级 evidence/:存通用证据事实、证据索引、raw-to-converted trace、来源定位、数据卡底座。案例结论专属证据映射放入 <case_id>/evidence/
  6. 行业级 manifest/:存行业级文件清单、来源清单、hash、生成时间、工具参数、处理批次、版本索引和迁移清单。
  7. 案例级 outputs/:存该案例正式输出文档和结果表,包括行业视图、市场视图、公司视图、细分行业文档、公司文档、投资读法、对外可读版本。
  8. 案例级 manifest/:存该案例引用了哪些行业级资料、哪些 batch/run、哪些输出和审核清单;不得复制替代行业级通用 manifest。
  9. 案例级 evidence/:只存该案例结论到证据的选择、引用、裁剪和审计抽样,不替代行业级通用证据事实。
  10. 父体系 tmp/:存该案例该 run 的临时文件、转换缓存、调试中间件和可重建草稿;不得作为正式证据、正式结果或审核入口。
  11. 父体系 result/:存该案例的结果入口、对外交付包、父级汇总索引和跨案例汇总表;可以引用 cases/<行业案例>/<case_id>/outputs/,但不能替代证据链。
  12. 父体系 img/:存该案例产生或引用的图片、截图、OCR 图片、标注图和图片 manifest;图片被结论引用时必须在 manifest 或证据映射中登记。

4. Manifest 和文件登记

所有原始文件和正式产物都必须进入 manifest 或等价数据库记录。

最低字段:

artifact_id
case_id
batch_id
run_id
artifact_type
industry_case
industry_id
subindustry_id
company_id
logical_path
relative_path
absolute_path
file_name
file_ext
file_size
sha256
source_doc_id
source_url
source_collected_at
raw_pool_path
artifact_status
created_at

artifact_type 建议枚举:

RAW_DOCUMENT
CONVERTED_TEXT
CONVERTED_MARKDOWN
CONVERTED_TABLE
EXTRACTED_FACT
EXTRACTED_METRIC
SUPPLEMENT_SOURCE
EVIDENCE_INDEX
DATA_CARD
REPORT_MARKDOWN
OUTPUT_TABLE
PACKAGE
MANIFEST

文件类型识别必须记录:

source_file_name
detected_type
archive_file_name
extension_added_by_archive_flag
extension_mismatch_flag

PDF、Office、网页、压缩包等资料不得只按扩展名判断。文件头为 %PDF 才按 PDF 处理;文件头为 PK 的 Office/zip 文件,即使扩展名写成 .pdf,也必须按 Office XML 或压缩包路径处理。

5. 状态口径

核心文件、资料、批次和结构化记录建议具备:

created_at
updated_at
source_snapshot_id
schema_version
data_status
processing_status

data_status 建议枚举:

READY
REVIEW
DATA_PARTIAL
MECHANISM_ONLY
HELD_BY_DATA_GAP
DEPRECATED
ERROR

processing_status 建议枚举:

RAW_REGISTERED
RAW_ARCHIVED
TEXT_CONVERTED
CLASSIFIED
EVIDENCE_EXTRACTED
METRIC_NORMALIZED
SUPPLEMENT_REQUIRED
SUPPLEMENT_ARCHIVED
HUMAN_DOC_INPUT_READY
HUMAN_DOC_READY
HELD_BY_DATA_GAP
ERROR

状态边界:

  1. EVIDENCE_EXTRACTED 不等于指标已标准化。
  2. METRIC_NORMALIZED 不等于投资结论成立。
  3. HUMAN_DOC_INPUT_READY 只表示可以进入人读文档输出。
  4. HUMAN_DOC_READY 只能由人读文档输出和验收流程写出。
  5. 缺核心数据时,必须使用 SUPPLEMENT_REQUIREDDATA_PARTIALMECHANISM_ONLYHELD_BY_DATA_GAP

6. 通用结构化数据底座

MySQL 或等价结构化存储可维护以下跨行业通用对象。表名可以按项目实际数据库规范调整,但字段含义和追溯关系不能丢。

6.1 来源文档

用途:记录每篇研报、文章、公告、网页和数据表。

最低字段:

doc_id
case_id
doc_type
title
source_org
author
publish_date
collected_at
source_url
raw_file_path
converted_text_path
converted_markdown_path
file_sha256
source_language
industry_id
subindustry_id
company_id
batch_id
run_id
doc_status
processing_status

6.2 证据事实中间层

用途:记录从资料中抽取的证据句、事实句、观点句和指标候选。它是原文和标准化指标之间的中间层。

最低字段:

evidence_fact_id
case_id
doc_id
industry_id
subindustry_id
company_id
source_text_path
source_page
source_table_id
source_sentence_index
evidence_text
evidence_type
business_dimension
numeric_value_raw
metric_candidate_name
metric_candidate_unit
metric_period
metric_date
chain_node_id
related_company_id
viewpoint_id
darkline_signal_flag
confidence_level
normalization_status
processing_status
data_status

evidence_type 建议枚举:

FACT_SENTENCE
METRIC_CANDIDATE
COMPANY_EVIDENCE
CHAIN_EVIDENCE
VIEWPOINT_EVIDENCE
DARKLINE_SIGNAL
DATA_GAP_EVIDENCE

6.3 通用指标、观点和读法

通用结构化数据至少应覆盖:

  1. 行业 / 子行业基础对象。
  2. 公司基础对象。
  3. 公司与行业关系。
  4. 产业链节点。
  5. 市场指标。
  6. 公司指标。
  7. 研报观点。
  8. 投资读法。
  9. 数据缺口。
  10. 转换状态。
  11. 来源缺口审计。
  12. 市场反向补漏审计。
  13. 人读文档验收回执。

这些结构化记录不得只保存结论。每条关键记录必须能追溯到 case_idsource_documentevidence_fact、文件路径和必要的 hash 或来源快照。

市场反向补漏产物按以下规则落点:

  1. 近 3 个月强显影股票清单、涨停/连续大涨/放量突破/逆行业上涨扫描结果、行情来源说明和外部数据快照,进入行业级 supplement/,并在行业级 manifest/ 登记来源、取得时间、口径和 hash 或等价摘要。
  2. 公司核心业务重归因、scope_type 范围闸门、缺失子行业/公司/关键变量判断和排除理由,进入行业级 evidence/ 或结构化表 industry_analysis_market_manifestation_gap_audit
  3. market_manifestation_gap_audit.csvmarket_manifestation_gap_priority.csvmarket_manifestation_gap_summary.json 或等价结构化记录,进入行业级 manifest/supplement/;如果某个正式案例引用这些补漏结果,再在案例级 <case_id>/manifest/<case_id>/evidence/ 记录引用关系。
  4. 市场反向补漏只保存缺口发现、补资料问题和审计结论,不保存未经证据验证的投资结论。

7. 行业专属扩展表

通用存储体系不定义任何具体行业的专属表。

具体行业可以在自己的 <行业>研报解析方案.md 或具体 案例分析设计.md 中定义扩展表,例如:

关键资产
关键产能
技术路线
产品型号
项目管线
客户认证
渠道结构
政策资质
专利 / 工艺 / 算法
行业特有供给、需求、库存或价格结构

每个行业扩展表必须说明:

table_name
purpose
适用行业和子行业
对象定义
最低字段
唯一键
与 source_document / evidence_fact / artifact_manifest 的追溯关系
是否进入人读文档
验收标准

规则:

  1. 行业扩展表不能替代来源文档、manifest 和证据事实中间层。
  2. 扩展表中的每条关键记录必须能追溯到原始资料或证据句。
  3. 如果一个字段只对某个行业有效,不要写进通用表。
  4. 行业扩展表要先在行业方案或案例设计中定义,再进入正式执行和审核。

8. 暗线与外部信息存储

暗线产物必须和普通产业链、市场指标、公司事实分账。

外部信息补充和 darkline 相关产物落点:

  1. 外部原件、网页快照、公告原件:raw/supplement/,按是否原始输入区分。
  2. 外部资料补充摘要、来源清单、网页抓取结果:supplement/
  3. 事件链、证据链、市场显影和替代解释:evidence/
  4. 暗线假设、应有之线、市场输出和反证:单独文件或结构化表,并在 manifest/ 登记。
  5. 面向人的暗线文档:outputs/,不得混入普通行业事实文档。

暗线结构化记录至少能表达:

darkline_id
case_id
industry_id
subindustry_id
company_id
darkline_title
hypothesis_text
intention_actor
intention_goal
initial_signal_doc_ids_json
expected_line_summary
market_output_summary
confidence_level
alternative_explanation
darkline_status
report_path

9. 结果包和人读文档

逐案例正式输出优先进入:

ana-data/cases/<行业案例>/<case_id>/outputs/

逐案例结果包至少包含:

summary.md
readout.md
case_input_manifest.csv
case_evidence_map.csv
human_doc_validation_receipt.csv

阶段性批量研报分析还必须输出或更新:

batch_summary.md
input_manifest.csv
output_manifest.csv
conversion_status.csv
evidence_fact_table.csv
classification_summary.csv
unresolved_data_gap.csv
source_gap_audit.csv
next_action_list.csv

这些批量产物优先进入案例级 outputs/manifest/;其中 evidence、缺口、source gap 和结论证据映射如果被正式结论引用,还必须在案例级 evidence/ 或行业级 evidence/ 留下可追溯记录。不能只把批量产物放在 tmp/

研报批量读取时,行业级 manifest、source_document、conversion_status、artifact_manifest 和 evidence_index 必须保留:

case_id
batch_id
run_id
raw_pool_path
raw_file_sha256

同一案例多次读取资料时,使用 batch_id 区分输入批次,例如 BATCH-001BATCH-002;使用 run_id 区分实际执行轮次。是否属于同一个案例由研究目标决定,不由每次 30 份文件的数量决定。

无论同一案例被分几批读取,raw 文件的物理落点仍然是 ana-data/cases/<行业案例>/raw/batch_idrun_id 只能写在 manifest、source_document、conversion_status、evidence_index 或数据库记录中,不能通过拆 raw 目录表达。

同一案例分多批读取时,转换文本、通用抽取结果、通用证据事实和行业级 manifest 的物理落点仍然是行业级 converted/extracted/evidence/manifest/。案例级 <case_id>/manifest/ 只记录本案例引用了哪些行业级资料和批次,不复制一份通用资料库。

如涉及图片或图册,应包含:

image_manifest.csv

逐案例输出完成后,必须在父体系结果目录建立结果入口或交付包索引:

ana-data/result/<行业案例>/<case_id>/result_index.md

ana-data/result/ 承接父体系默认结果入口、跨案例汇总、父级汇总、审计辅助输出或项目级打包;它不替代逐案例 outputs/ 的详细输出和证据链,但审核员和外部读取者可以从这里进入结果包。

研报处理涉及图片、截图、图册、OCR 图片或标注图时,必须进入父体系图片目录:

ana-data/img/<行业案例>/<case_id>/

人读核心输出应至少围绕三类视图展开:

  1. 行业视图。
  2. 市场视图。
  3. 公司视图。

细分行业文档、公司文档、投资读法、暗线文档、数据表和对外版本是上述三类视图的展开,不替代三类顶层视图。

10. 追溯链路

正式结论必须能走通:

人读结论
-> investment_readout / report_viewpoint / market_metric / company_metric / 行业扩展表
-> evidence_fact
-> source_document
-> artifact_manifest
-> raw_file_path + sha256

反向也要能走通:

raw 文件
-> source_document
-> converted 产物
-> evidence_fact
-> metric / viewpoint / darkline / 行业扩展表
-> 人读文档

MySQL 记录不得只保存结论,必须能反查到行业统一 raw/、行业级 converted/extracted/evidence/manifest/,以及对应案例目录中的 outputs/manifest/ 或案例级 evidence/ 路径。

如果任意一环缺失,该结论只能标记为 REVIEWDATA_PARTIALMECHANISM_ONLYHELD_BY_DATA_GAP,不能作为正式强结论。

11. 最低验收标准

完成一批行业资料或研报解析后,至少验收:

  1. 原始文档已归档到行业统一 raw/
  2. 转换文档已归档到 converted/,或明确无需转换。
  3. 文档来源、hash、路径已写入 manifest 或数据库。
  4. 总行业、子行业、公司归类明确。
  5. 关键事实、关键指标和关键观点已拆分记录。
  6. 标准化指标能追溯到证据事实。
  7. 投资读法有证据来源、触发条件、失效条件和风险边界。
  8. 人读文档能追溯到结构化数据。
  9. 结构化数据能追溯到原始文档。
  10. 批次处理状态明确,不把 EVIDENCE_EXTRACTED 误读成 HUMAN_DOC_READY
  11. 缺口清单明确记录缺什么、影响哪条结论、下一步从哪里补。
  12. 暗线内容单独分流,未混进普通事实表。
  13. 行业专属表只在具体行业方案或案例设计中定义,并能追溯到证据层。
  14. 不存在 ana-data/cases/<行业案例>/<case_id>/raw/ 或其他逐案例、逐批次、逐 run 的 raw 原始资料目录。
  15. 通用转换、抽取、补充、证据事实和行业级 manifest 没有落到 <case_id>/converted/<case_id>/extracted/<case_id>/supplement/<case_id>/manifest/ 中。
  16. 临时文件进入 ana-data/tmp/<行业案例>/<case_id>/<run_id>/,且未被正式证据或正式结果引用为主入口。
  17. 结果入口或交付包索引进入 ana-data/result/<行业案例>/<case_id>/
  18. 图片、截图、OCR 图片或图册进入 ana-data/img/<行业案例>/<case_id>/,涉及结论引用时有 image_manifest.csv 或等价记录。

12. 禁止事项

  1. 不另建与本文件平行的正式 研报存储体系.md
  2. 不在通用底座里写具体行业专属表。
  3. 不只保存 Markdown 摘要而不保存原始来源。
  4. 不只存 PDF 文件而不抽取结构化信息。
  5. 不把研报观点直接写成事实。
  6. 不把公司投资读法写在文档里但不留证据或结构化入口。
  7. 不让总行业、子行业、公司关系只存在自然语言里。
  8. 不把临时转换文件当正式产物。
  9. 不重复转换同一个 PDF;应复用 converted/ 缓存并记录转换状态。
  10. 不让报告文档和数据库各说各话。
  11. 不把数据库密码、授权 token 或私有凭据写入结果包。
  12. 不把任何行业的 raw 原始资料按 case、batch 或 run 分散存放。
  13. 不把研报通用处理产物按 case、batch 或 run 重复分散存放;案例目录只保存案例自定义输出、引用清单和结论证据映射。
  14. 不把临时文件放入 ana-data/cases/<行业案例>/<case_id>/;临时文件统一进入父体系 ana-data/tmp/<行业案例>/<case_id>/<run_id>/
  15. 不把 ana-data/tools/ 当作正式结果目录、证据目录、临时目录或凭据存放目录。

13. 行业整体成果稳定入口与原子发布合同(2026-08-07)

本节是行业整体长期成果的 canonical 存储例外和发布母合同;它只 supersede 本文件中“行业整体成果必须以 <case_id>/outputs/result/<case_id>/ 作为用户入口”的旧默认解释。普通专题案例、案例专属证据映射、行业共享 raw/converted/extracted/supplement/evidence 及历史 case/result 包的既有职责保持不变。

13.1 目录合同

ana-data/cases/<行业>案例/
├─ 当前成果索引.md
├─ 核心文档/
│  └─ .releases/<release_id>/
├─ raw/
├─ converted/
├─ extracted/
├─ supplement/
├─ evidence/
├─ manifest/
│  ├─ current_output_manifest.csv
│  ├─ promotion_ledger.csv
│  └─ legacy_case_path_map.csv
└─ 审计包/
   └─ <case_id>/<batch_id>/<run_id>/

ana-data/result/<行业>案例/
└─ 当前成果索引.md
  1. cases 当前成果索引.md 是唯一可变、默认用户入口;它必须记录当前 release_id、accepted audit、内容截止、覆盖边界、未解决缺口和审计包入口,并只链接一个完整不可变 release。
  2. 核心文档/.releases/<release_id>/ 保存该 release 的完整普通非 reparse 人读文件集合。.releases/ 是事务内不可变代,不是第二套用户入口;用户从当前索引进入。
  3. result 当前成果索引.md 是固定薄跳转,固定指向 cases 当前索引;它不随 release 改写。cases 索引不存在或 exact-set 未闭合时,薄入口只表达“无正式当前成果”。
  4. 审计包/<case_id>/<batch_id>/<run_id>/ 保存 prior/candidate 快照、release receipt、验收、回滚入口、迁移映射和过程证据,不作为普通阅读入口。

13.2 release 身份与哈希域

  1. release_id=SHA256(canonical_utf8(industry,task_id,case_id,batch_id,run_id,accepted_audit_id)),不得包含会被 release_id 反向影响的 candidate 文件 hash。
  2. candidate release set 逐项冻结相对路径、类型、bytes、SHA-256,且覆盖 cases 当前索引、当前 core release 全部普通非 reparse 文件、固定 result 薄索引和 current_output_manifest.csv
  3. current_output_manifest.csv 枚举两份索引和 core release,但不枚举自身;审计包 release_receipt.json 冻结 current manifest 自身 bytes/SHA-256,并对“manifest 枚举域 + manifest 自身”计算 candidate_release_set_sha256,避免自引用环。
  4. promotion_ledger.csv 排除在 candidate hash 域之外。它以 append-only 事件行记录 release_id/event_seq/state/prior_release_id/prior_release_set_sha256/candidate_release_set_sha256/task/case/batch/run/audit/operator/event_time/recovery_or_rollback_receipt;不得改写既有行。

13.3 状态机、独占锁与 commit point

  1. 正常状态唯一为 PREPARED -> VERIFIED -> COMMITTING -> COMMITTED;失败/恢复状态只允许 ABORTED / RECOVERY_REQUIRED / ROLLING_BACK / ROLLED_BACK
  2. 同一行业同时只能有一个 CreateNew manifest/.promotion.lock,记录 release、operator、process identity、acquired time 和 lease deadline。接管必须同时证明原进程不存在、lease 过期及现场状态/hash 一致;不得直接删锁继续。
  3. candidate 先写 核心文档/.releases/<release_id>.staging/,全量验证后同卷原子 rename 为不可变 release。首次发布把 prior 明确冻结为 ABSENT_GENESIS;result 薄入口可按固定空态合同 CreateNew,但不得冒充已发布成果。
  4. cases 当前成果索引.md 的同卷 atomic ReplaceFile(首次为同目录 CreateNew + atomic rename)是唯一 commit point,也是最后一个可变用户入口动作。其前依次完成 prior 审计快照、candidate release 固化、result 薄入口复验、candidate current manifest atomic ReplaceFile;其后立即复算 candidate 全集,匹配才 append COMMITTED
  5. 在 commit point 之前,旧 cases 索引继续链接完整旧 release;之后,新 cases 索引链接完整新 release。PREPARED/VERIFIED/COMMITTING 不能被任何索引或工具解释为正式 current。

13.4 crash/reopen 与回滚

现场 恢复动作 允许终态
PREPARED/VERIFIED,cases 索引仍为 prior 复验 prior,隔离任务 staging,append 补偿事件 ABORTED,旧集正式
COMMITTING,manifest 已换而 cases 索引仍为 prior 从审计包 atomic 恢复 prior manifest并复算 prior exact-set ROLLED_BACK,旧集正式
cases 索引已为 candidate,ledger 无 COMMITTED candidate 两索引/core/manifest 全匹配时只补 append COMMITTED COMMITTED,新集正式
cases 索引已切换但 candidate 不匹配 atomic 恢复 prior manifest 和 prior cases 索引,再复算 prior ROLLED_BACK,候选不正式
prior/candidate、snapshot 或锁无法判真 保留现场,不猜测、不删除、不继续发布 RECOVERY_REQUIRED
同 release 已 COMMITTED 且现场匹配 返回既有 receipt,不追加第二次 commit COMMITTED 幂等

已 COMMITTED release 的业务回滚必须以 prior accepted release 作为新 candidate,形成新的 release_id 和补偿 ledger 事件;不得改写旧 COMMITTED 行。每个 commit 边界必须有断点/重启故障注入,证明只收敛到完整旧集或完整新集。

13.5 legacy 与活跃链保护

  1. legacy_case_path_map.csv 必须逐路径记录旧位置、目标或聚合位置、bytes/hash、审计血缘和状态;历史文本不追溯改写。
  2. 旧 case/result 目录只有在新 release COMMITTED、prior exact-set 可恢复、两份索引/current manifest 复验、锁释放和行业执行/输出审核接受后才可移动或收敛;任何条件失败时 move/delete=0
  3. 活跃、PENDING、HOLD 或仍有原链修复权的 batch 不得进入 candidate,也不得被稳定入口迁移冻结。当前新能源 BATCH-002 与军工 BATCH-034 持续排除,直到各自原审核链独立 PASS 后再建立新的 promotion run。

13.6 单一稳定正文树后继合同(2026-08-08)

本小节落实 TASK-DEFENSE-SINGLE-CORE-DOCUMENT-REMEDIATION-20260808-001,并 append-only supersede 13.1—13.5 中与“核心文档/.releases/<release_id>/ 保存用户正文”“candidate 在核心文档下 staging”有关的目录和发布口径。原条款及既有发布历史继续作为审计事实保留。

正式目录合同改为:

ana-data/cases/<行业>案例/
├─ 当前成果索引.md
├─ 核心文档/                       # 唯一当前正文树;稳定路径、稳定文件名
├─ manifest/
│  ├─ current_output_manifest.csv
│  ├─ promotion_ledger.csv
│  └─ legacy_case_path_map.csv
└─ 审计包/<case_id>/<batch_id>/<run_id>/

ana-data/result/<行业>案例/
└─ 当前成果索引.md                 # 固定轻量跳转
  1. 核心文档/ 只枚举当前正式正文 exact-set。其下禁止 .releases/.staging/、hash/release 目录、日期/批次/版本后缀文件,以及任何第二套完整正文树;同一逻辑成果在所有后续批次中复用同一相对路径和文件名。
  2. candidate 只能写入 ana-data/tmp/<行业案例>/<task_id>/<run_id>/。通过一次合并执行/输出确认后,promotion 才可按 stable-path exact-set 晋升;current_output_manifest.csv 记录稳定相对路径、bytes、SHA-256 和当前状态,promotion_ledger.csv append-only 记录 task/case/batch/run/revision、接受审计、前后集合与恢复回执。
  3. 晋升前必须把上一正式状态的可恢复快照、差异、路径映射和回滚材料写入 审计包/ 并复验;正式用户树不得承担历史保存或回滚职责。任何 prior/candidate、锁、hash、映射或恢复状态不可判真时,保持原正式状态并 fail closed。
  4. cases 当前成果索引.md核心文档/ 共同表达唯一当前成果;result 当前索引仅固定跳转到 cases 当前索引,不复制正文、manifest、revision 或 release 内容。
  5. release_id、batch、run、revision 和历史正文哈希只作为 manifest/ledger/审计元数据;不得用于生成核心文档下的目录名、文件名或另一用户入口。
  6. 历史已发布 release 必须保留。迁移时可在完整 bytes/SHA-256、原接受审计和恢复测试闭合后,将旧 release 可恢复地归档到 审计包/,并在 legacy_case_path_map.csv 建立一对一映射;不得直接删除、覆盖或失去原路径血缘。
  7. 一个 CONTENT_SPRINT 的存储变更并入一次合并设计确认和一次合并执行/输出确认;不得按文件、公司、字段、manifest 行或机械校验项拆出额外审核链。
  8. 本后继合同只更新母规范,不执行任何行业文件迁移、发布、删除或状态提升。

13.7 非空 direct stable core 的撤回、目录级切换与恢复状态机(2026-08-13)

本小节落实 案例分析规范.md 12.6,并窄范围 supersede 13.3.4—13.3.5 中“candidate 激活前 cases 入口必须持续表达 prior current”的口径;cases candidate index 仍是唯一 candidate activation commit。既有首发、不可变历史 release 和审计文字均保持原事实,不由本小节追溯改写。

  1. 适用前提。 只适用于 核心文档/ 已存在完整 prior direct stable exact-set、同一 CONTENT_SPRINT 必须更新相同稳定路径集合且已取得原行业合并执行/输出审核 PASS 的后续晋升。prior/candidate exact-set、快照、回滚、锁、ledger、maintenance entry/state、同卷和目标缺失任一未闭合时,正式写入为 0
  2. 预备与撤回。 在 direct core 不变时,先以 CreateNew/同卷原子 rename 安装设计冻结的 transition state 包;随后以同卷 atomic ReplaceFile 将 cases 当前索引替换为冻结的 MAINTENANCE_NO_CURRENT_RESULT 入口。任一 transition member 缺失、额外、类型不符或 bytes/SHA-256 漂移均 fail closed;cases 入口一旦为维护态,即使 state 包不完整也只能解释为“无 current”。该撤回事件 append ledger,但不得记为 COMMITTED release。
  3. 读取规则。 result 当前成果索引.md 始终只跳转 cases 入口。canonical reader 必须按“cases 入口 -> transition state -> accepted audit/ledger -> matching current manifest -> core exact-set”顺序校验;遇到 MAINTENANCE_NO_CURRENT_RESULTRECOVERY_REQUIRED、未知状态或任何漂移立即 STOP_NO_CURRENT,不得继续解析 direct path。未通过这一入口链验证的 核心文档/ 文件只是不具 current 语义的现场字节。
  4. 目录级切换。 维护态激活后,先验证 prior 审计包目标不存在且与 stable core 同卷,再用 whole-directory atomic rename 把完整 prior core 移到该 run 审计包;再验证 stable core 目标不存在,并把 task tmp 的完整已审核 candidate core 整体 atomic rename 到该稳定位置。禁止逐文件替换、复制后删除、覆盖已有目标、跨卷模拟 rename 或在正式 prior 入口仍生效时改变 direct core。
  5. 唯一激活点。 candidate core、candidate current manifest、cases candidate index、固定 result 薄入口及 formal exact-set 必须先按冻结 bytes/SHA-256 全量匹配;随后 cases candidate index 的 atomic ReplaceFile 是唯一 activation commit,也是切回“完整 candidate current”的最后动作。transition state 清理和 COMMITTED ledger 只能在复算 candidate 全集成功后进行;维护撤回不是另一个 release。
  6. 三态判定。 只允许下表三种语义;任何第四种、窗口/lease 超限、未知 hash 或无法证明的现场均为 RECOVERY_REQUIRED
cases 入口与现场 current 语义 允许动作
accepted prior index + matching prior manifest + 完整 prior core PRIOR_CURRENT_COMPLETE 保持只读,或按本节重新取得门禁后进入维护
冻结 maintenance index,或 transition/现场存在未知、漂移、超时 MAINTENANCE_NO_CURRENT_RESULT / RECOVERY_REQUIRED STOP_NO_CURRENT;在维护入口保持时收敛完整 prior 或完整 candidate
accepted candidate index + matching candidate manifest + 完整 candidate core CANDIDATE_CURRENT_COMPLETE 复算、append COMMITTED、释放锁
  1. crash/reopen/rollback。 每次 reopen 都从 cases 入口和 transition state 重新判定,禁止根据锁、mtime、目录存在或上次进度猜测 current。恢复只能在维护入口保持时完成完整 prior 或完整 candidate;恢复 prior 时先还原 prior core/manifest 并全量复算,恢复 candidate 时先闭合 candidate core/manifest/两入口 exact-set,最后才 atomic ReplaceFile 对应 accepted cases index。窗口或 lease 过期不自动选择任一侧。
  2. 行业设计义务。 每个采用本节的设计必须冻结 entry/state 精确内容和 hash、状态机成员与拒绝谓词、prior/candidate identity、卷标与目标缺失检查、维护窗口/lease、reader 实现与验证入口、direct-path 语义、每一状态的 crash/reopen/rollback 期望以及负向测试。仅写声明、只建 lock 或把逐文件原子性相加,均不满足本合同。
  3. 治理边界。 本节只建立项目级 fail-closed 后继,不授权任何行业执行。具体 sprint 仍由原行业 owner/reviewer 在同一设计与执行/输出审核链中一次合并确认,不增加逐文件、平行、管理或替代审核链。