# CODE-D-HEAVY-001 manifest 结果包校验 helper 编码方案

创建人员：Codex  
文件职责：记录 DEV-D-HEAVY-001 的重型编码方案、接口、测试、风险和验收方式。  
管理规范/模板：../../../common/dev-doc/编码规范.md；../../../common/dev-doc/编码方案范本.md。  
引用文件：../开发工作区说明.md；../目录导读.md；../../开发事项总纲.md；../../开发事项计划.md；../../开发审计报告.md；../../../exp-doc/实验设计.md。  
记录方式：重型开发方案；方案变化时追加修订记录。

## 1. 背景和目标

实验 EXP-D-HEAVY-001 需要一个脚本校验结果包 manifest 是否完整、文件是否存在、sha256 是否匹配，并输出可审计结果包。

## 2. 模块接口

代码路径：`dev/exp-dev/manifest_pack_validator.py`。

CLI：

```text
python dev/exp-dev/manifest_pack_validator.py --input-root exp-data/raw/EXP-D-HEAVY-001 --output-dir exp-data/result/RUN-D-HEAVY-001
```

输入目录下每个 case 目录包含 `manifest.json`。

manifest schema：

| 字段 | 类型 | 说明 |
|---|---|---|
| package_id | string | 包 ID |
| files | array | 文件清单 |
| files[].path | string | 相对 case 目录的文件路径 |
| files[].sha256 | string | 文件 sha256 |

输出：

1. `summary.json`
2. `case_results.csv`
3. `readout.md`

## 3. 公共逻辑

实现公共函数：

1. `sha256_file(path)`
2. `load_manifest(case_dir)`
3. `validate_case(case_dir)`
4. `write_outputs(results, output_dir)`

## 4. 测试方案

测试覆盖：

1. valid_pack：文件存在且 hash 正确，应 PASS。
2. invalid_pack_missing_file：manifest 指向缺失文件，应 FAIL。
3. invalid_pack_hash：文件存在但 hash 错，应 FAIL。

## 5. 风险和处理

1. 路径风险：manifest 只能使用相对路径，不允许绝对路径。
2. 审计风险：readout 必须包含创建人员、文件职责、管理规范/模板、引用文件、记录方式。
3. 结果风险：任何 case 失败不影响脚本运行完成，但 summary 要统计失败数。

## 6. 验收标准

1. py_compile 通过。
2. unittest 通过。
3. 实验结果包 3 个文件存在。
4. summary 中 total_cases=3、pass_count=1、fail_count=2、quality_pass=true。
5. 开发审计和实验审计能追到代码、测试、结果包和修复记录。