# 案例存储体系

创建人员：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 只读导出和市场反向补漏脚本；不是正式数据目录 | 已创建 |

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

```text
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 分散存放：

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

例如：

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

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

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

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

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

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

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

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

```text
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_id`、`batch_id`、`run_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 或等价数据库记录。

最低字段：

```text
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` 建议枚举：

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

文件类型识别必须记录：

```text
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. 状态口径

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

```text
created_at
updated_at
source_snapshot_id
schema_version
data_status
processing_status
```

`data_status` 建议枚举：

```text
READY
REVIEW
DATA_PARTIAL
MECHANISM_ONLY
HELD_BY_DATA_GAP
DEPRECATED
ERROR
```

`processing_status` 建议枚举：

```text
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_REQUIRED`、`DATA_PARTIAL`、`MECHANISM_ONLY` 或 `HELD_BY_DATA_GAP`。

## 6. 通用结构化数据底座

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

### 6.1 来源文档

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

最低字段：

```text
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 证据事实中间层

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

最低字段：

```text
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` 建议枚举：

```text
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_id`、`source_document`、`evidence_fact`、文件路径和必要的 hash 或来源快照。

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

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

## 7. 行业专属扩展表

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

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

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

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

```text
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/`，不得混入普通行业事实文档。

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

```text
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. 结果包和人读文档

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

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

逐案例结果包至少包含：

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

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

```text
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 必须保留：

```text
case_id
batch_id
run_id
raw_pool_path
raw_file_sha256
```

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

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

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

如涉及图片或图册，应包含：

```text
image_manifest.csv
```

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

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

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

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

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

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

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

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

## 10. 追溯链路

正式结论必须能走通：

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

反向也要能走通：

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

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

如果任意一环缺失，该结论只能标记为 `REVIEW`、`DATA_PARTIAL`、`MECHANISM_ONLY` 或 `HELD_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 目录合同

```text
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”有关的目录和发布口径。原条款及既有发布历史继续作为审计事实保留。

正式目录合同改为：

```text
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_RESULT`、`RECOVERY_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`、释放锁 |

7. **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 过期不自动选择任一侧。
8. **行业设计义务。** 每个采用本节的设计必须冻结 entry/state 精确内容和 hash、状态机成员与拒绝谓词、prior/candidate identity、卷标与目标缺失检查、维护窗口/lease、reader 实现与验证入口、direct-path 语义、每一状态的 crash/reopen/rollback 期望以及负向测试。仅写声明、只建 lock 或把逐文件原子性相加，均不满足本合同。
9. **治理边界。** 本节只建立项目级 fail-closed 后继，不授权任何行业执行。具体 sprint 仍由原行业 owner/reviewer 在同一设计与执行/输出审核链中一次合并确认，不增加逐文件、平行、管理或替代审核链。