story/docs/release-evidence-bundle.md

# 发布候选证据包开发与使用说明

## 1. 目标与边界

`cmd/release-evidence`用于阶段8联调、试点和生产发布前，把同一候选版本的技术验收快照、外部验收状态、真机固件一致性报告、接口契约、数据库迁移、部署清单、关键交付文档和可用SBOM封装为一个带SHA-256清单的ZIP。`PILOT`包还必须携带同一客户组织、同一业务时区、上一完整自然周的7份日报和1份周报。它解决证据散落、候选身份不一致、真机场景缺口被模拟结果掩盖、试点周期证据缺失以及归档后无法判断文件是否被替换的问题。

证据包不是发布批准。生成器只在技术验收快照八项门禁全部通过时工作；其中生产快照必须额外证明生产部署模式、业务进程实际`prod`环境、身份服务非开发模式、已验证异地备份、外部告警配置和模拟服务退出。外部证据可以保持`PENDING`，此时包内状态固定为`EXTERNAL_VALIDATION_PENDING`。真实设备、供应商、KMS、告警接收器、Safari或业务签署不能用本地模拟结果替代。

## 2. 输入设计

### 2.1 必需参数

| 参数 | 说明 |
|---|---|
| `-candidate-version` | 与验收快照一致的候选版本，最长128字符 |
| `-build-digest` | 与验收快照一致的`sha256:`不可变构建摘要 |
| `-source-commit` | 源代码提交；`STAGING/PRODUCTION`必须是40或64位十六进制提交摘要，`LAB`可使用明确的本地标签 |
| `-acceptance-snapshot` | `POST /api/v1/ops/diagnostics/acceptance-snapshots`返回或下载的JSON |
| `-evidence-index` | `release-evidence-index-v2`外部证据索引 |
| `-pilot-daily-snapshot` | `PILOT`包重复传入恰好7次，分别对应周一至周日的`ops-pilot-daily-minimal-v1`日报 |
| `-pilot-weekly-snapshot` | `PILOT`包必需的`ops-pilot-weekly-minimal-v1`完整周报 |
| `-out` | 新ZIP文件路径；已有文件不会被覆盖 |

技术验收快照必须满足：候选版本和构建摘要完全匹配、`overall_gate_satisfied=true`、脱敏策略为`ops-acceptance-minimal-v1`，并包含有效环境、验收类型、编号和生成时间。

### 2.2 PILOT周期证据

验收类型为`PILOT`时，打包器执行以下强制校验：

- 验收快照、7份日报和周报的`tenant_id`、`candidate_version`和`build_digest`完全一致；
- 所有日/周报使用同一个有效IANA时区，周报起始日是周一；
- 周报`is_complete=true`，生成时间不早于自然周结束时间，UTC窗口与业务自然周一致；
- 7份日报日期无重复、无缺失且完整覆盖周一至周日，每份UTC窗口与其业务自然日一致；
- 日报和周报分别使用`ops-pilot-daily-minimal-v1`、`ops-pilot-weekly-minimal-v1`；
- 周报继续包含`complaints/REQUIRED`，防止打包时把未接入的客服/CRM投诉证据误报为已完成。

任一项不满足即拒绝生成ZIP。非`PILOT`包不要求周期证据；若主动提供，则同样必须满足完整的一周规则，不能只附零散文件。

### 2.3 外部证据索引

索引必须逐项包含以下十个代码，不能缺少、重复或自行改名：

| 代码 | 证据范围 |
|---|---|
| `REMOTE_CI_SUPPLY_CHAIN` | 固定提交的远程CI、14项构建/质量/安全检查、后端与Web镜像摘要及三份CycloneDX SBOM；首个文件须为`REMOTE_CI_SUPPLY_CHAIN`一致性报告 |
| `REAL_DEVICE_RTC` | 量产候选终端、真实RTC、三模式通话和异常恢复 |
| `REAL_DEVICE_FIRMWARE` | 至少3台量产候选终端的四场景`HARDWARE_CAPTURE`固件一致性报告 |
| `REAL_AGENT_MODELS` | 真实语音、内容、Embedding、内容安全与效果评测 |
| `PRODUCTION_INFRASTRUCTURE` | 生产域名、证书、OIDC、数据库、Redis、对象存储、网络和监控 |
| `PRODUCTION_RECOVERY` | 生产等价备份恢复、滚动重启、供应商停机和回滚演练 |
| `KMS_ROTATION` | 云KMS/HSM身份、挂载、轮换及旧凭据失效 |
| `REAL_ALERT_RECEIVER` | 真实通知网关、值班组映射、唯一送达及正式告警演练 |
| `SAFARI_COMPATIBILITY` | macOS最近两个Safari版本关键流程 |
| `BUSINESS_APPROVAL` | 产品、硬件、Agent、SRE、安全、法务和试点联合结论 |

每项状态只能为：

- `VERIFIED`：至少关联一个实际证据文件；
- `PENDING`：明确保留待外部验证，不会阻止生成包，但包状态不能进入发布评审就绪；
- `WAIVED`：必须填写豁免说明，最终状态为`RELEASE_REVIEW_WITH_WAIVERS`，仍需有权人员复核。

`REAL_DEVICE_FIRMWARE`是不可豁免门禁。它只能保持`PENDING`或标记为`VERIFIED`，其中每个文件都必须是官方校验器生成、候选版本和构建摘要一致、全部检查通过且范围为`HARDWARE_CAPTURE`的`firmware-conformance-report-v1`。打包器要求至少3台不同真机中的每一台均完成`AB_SUCCESS`、`AB_ROLLBACK`、`POWER_LOSS_AFTER_STAGE`和`POWER_LOSS_DURING_BOOT`四个场景，共至少12份不重复报告。缺少设备或任一场景时，索引必须保持`PENDING`；模拟器的`PROTOCOL_SIMULATION`报告即使全部通过也会被拒绝作为真机证据。

`REAL_ALERT_RECEIVER`同样不可豁免。第一个证据文件必须是`PASS/REAL_RECEIVER`的`alert-receiver-conformance-report-v1`，并与候选版本和构建摘要一致。报告必须覆盖全部活动路由、每条路由的唯一验签联通回执、主/升级接收组映射以及一条已确认并解决的受控正式告警演练。只完成本地或测试网关时报告范围为`MOCK_RECEIVER`，不能进入真实接收器证据项；缺报告或缺正式演练时必须保持`PENDING`。

`KMS_ROTATION`也不可豁免。第一个文件必须是`PASS/REAL_KMS_HSM`的`kms-rotation-conformance-report-v1`，环境必须为预生产或生产，并同时覆盖逐请求动态读取和受控滚动重启两类凭据。新版本接受、旧版本拒绝、业务连续性、工作负载身份和云提供器审计缺一不可。本地`LOCAL_SECRET`报告只能证明演练工具可用，不能进入真实轮换证据项。

`PRODUCTION_RECOVERY`不可豁免。第一个文件必须是`PASS/PRODUCTION_EQUIVALENT`的`production-recovery-conformance-report-v1`，同一预生产或生产候选必须完成PostgreSQL隔离恢复、Redis权威状态重建、API/Callbacks/Worker滚动重启和供应商停机恢复。每项都必须证明权威数据一致、业务连续、没有重复效果并完成清理。本地`LOCAL_RECOVERY`报告不能放行。

`PRODUCTION_INFRASTRUCTURE`不可豁免。第一个文件必须是`PASS/PRODUCTION_INFRASTRUCTURE`的`production-infrastructure-conformance-report-v1`，并完整覆盖域名TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控。每类组件必须具备规定控制项和探针、配置、审计引用。本地`LOCAL_INFRASTRUCTURE`报告只能验证采集工具链，不能放行。

`SAFARI_COMPATIBILITY`不可豁免。第一个文件必须是`PASS/REAL_SAFARI`的`safari-compatibility-conformance-report-v1`，覆盖发布依据中的`CURRENT/PREVIOUS`两个不同真实Safari版本、两种视口和六条关键流程，共24项结果。本地浏览器或Playwright WebKit只能形成`NON_SAFARI_TOOLCHAIN`报告，不能放行。

`REAL_DEVICE_RTC`不可豁免。第一个文件必须是`PASS/REAL_DEVICE_RTC_PROVIDER`的`real-device-rtc-conformance-report-v1`，至少3台量产候选终端以6通精简矩阵覆盖三种语音方式正常闭环，以及凭证续签、网络切换恢复和受控停止。每通都必须证明双向媒体、供应商启停、最终字幕、用量、质量结论、任务去重和资源回收。本地`PROTOCOL_SIMULATION`报告不能放行。

`REAL_AGENT_MODELS`不可豁免。第一个文件必须是`PASS/REAL_AGENT_MODELS`的`real-agent-models-conformance-report-v1`，内容生成必须使用`real`观测重新计算已有10类固定评测，Embedding和内容安全各覆盖6类精简数据集，并附数据条款和额度证据。本地生成器、哈希向量或本地规则只能形成`LOCAL_AGENT_TOOLCHAIN`报告，不能放行。

相对证据路径以索引文件所在目录为基准。每个文件必须是普通文件且不超过100 MiB。打包时本机绝对路径会被替换为包内路径，避免泄露工作站目录；不得把密钥、令牌、录音、字幕正文或未脱敏个人信息作为证据文件。

样例见[`testdata/release-evidence-index.example.v2.json`](../testdata/release-evidence-index.example.v2.json)。使用前必须替换候选版本、构建摘要、责任人、状态和证据文件。

## 3. 包结构与完整性

```text
candidate-evidence.zip
├── release-manifest.json
├── evidence-index.json
├── acceptance/technical-acceptance-snapshot.json
├── pilot/daily/YYYY-MM-DD.json       # PILOT包恰好7份
├── pilot/weekly/YYYY-MM-DD.json      # PILOT包1份完整周报
├── baseline/openapi/openapi.yaml
├── baseline/migrations/*.sql
├── baseline/deploy/kubernetes/**
├── baseline/docs/**
├── baseline/artifacts/*.cdx.json       # 当前工作区存在时加入
└── evidence/<CODE>/<序号>-<文件名>
```

`release-manifest.json`使用`release-candidate-evidence-bundle-v3`，保存候选版本、构建摘要、源提交、OpenAPI版本、环境、验收类型、技术快照编号、外部证据状态计数、SBOM数量和每个归档文件的大小与SHA-256。`remote_ci_supply_chain_validation`给出远程运行、14项检查、双镜像摘要和三份SBOM覆盖，`firmware_validation`同步给出真机与四场景覆盖，`real_device_rtc_validation`给出真机、三种方式和四类RTC场景覆盖，`real_agent_models_validation`给出真实生成、Embedding和内容安全质量覆盖，`alert_receiver_validation`给出活动路由、映射、唯一回执和正式演练，`kms_rotation_validation`给出真实提供器和两种轮换模式，`production_recovery_validation`给出基础设施、四类演练和实际恢复用时，`production_infrastructure_validation`给出目标环境和七类组件控制项覆盖，`safari_compatibility_validation`给出两个Safari版本和24项关键流程矩阵。没有报告时这些门禁都会明确列出`PENDING`原因。PILOT包额外保存`pilot_evidence_included=true`、`pilot_week_start`、`pilot_timezone`和`pilot_daily_count=7`。清单不把自身摘要写入自身；命令完成后另行输出整个ZIP的`sha256:`摘要，用于制品库登记。

如果当前工作区没有CI生成的CycloneDX文件，包仍可用于外部验收准备，但清单写入`SBOM_NOT_PRESENT_IN_WORKTREE`警告，且`REMOTE_CI_SUPPLY_CHAIN`不应标记为已验证。

## 4. 使用流程

1. 固定候选提交、构建镜像并取得不可变摘要。
2. 使用相同候选标识生成技术验收快照；任一技术门禁失败先处理问题，不允许打包。
3. 复制外部证据索引样例，逐项登记责任人、状态和文件；真机固件报告未达到3台×4场景时保持`PENDING`。
4. 执行：

```powershell
go run ./cmd/release-evidence `
  -root . `
  -candidate-version 0.55.0-rc.1 `
  -build-digest sha256:<64位摘要> `
  -source-commit <固定提交摘要> `
  -acceptance-snapshot E:\evidence\acceptance.json `
  -evidence-index E:\evidence\evidence-index.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-17.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-18.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-19.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-20.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-21.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-22.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-23.json `
  -pilot-weekly-snapshot E:\evidence\weekly\2026-08-17.json `
  -out E:\evidence\data-terminal-cloud-0.55.0-rc.1.zip
```

5. 保存命令输出的ZIP摘要，解包抽查清单，再上传只读制品库。
6. 任何候选版本、构建摘要或源提交变化都重新生成快照和证据包；不修改旧包伪装成同一候选。

## 5. 验证

受影响模块测试：

```powershell
go test ./internal/releaseevidence ./cmd/release-evidence
```

真实本地纵向烟测：

```powershell
.\scripts\smoke-release-evidence.ps1
```

烟测使用真实OIDC生成绑定同一候选版本和API镜像摘要的`PILOT`技术验收快照、上一完整自然周的7份日报和1份周报，构造十项全部`PENDING`的外部索引，生成并解包临时ZIP，核对OpenAPI 0.68.0、v3清单、候选一致性、周期证据、摘要、待验计数和真机固件四场景缺口，随后清理临时文件、审计和幂等记录。技术验收快照还要求主机健康上报在15分钟内且没有warning/critical；生产类型另要求生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警和Mock退出全部通过。该结果只证明打包链路可用，不证明十项外部验收、真机固件或投诉证据已经完成。