# P1-04.9.1 实施与验收报告：KMS/Vault、SLO 升级、回放死信接管与错误手册

日期：2026-08-24  
状态：实现、迁移、全量自动化与超级管理员 Chrome UAT 均完成。

## 1. 本阶段目标

1. 将企业日历 OAuth token、国内企业应用 secret、短期 token 与增量游标从单一本地主密钥扩展为可插拔 Vault Transit / 企业 KMS 托管。
2. 建立持久化恢复探针和不可变演练证据，确认“能加密”之外也“能恢复历史密文”。
3. 把日历 SLO 从只读仪表盘升级为打开、提醒、升级、恢复的通知生命周期。
4. 为回放死信增加负责人、人工重入、人工解决和不可变事件账本。
5. 将确定性错误分类发布为管理端可查的版本化运营手册。

## 2. 已实现范围

### 2.1 密钥托管

- 后端：`local_fernet`、`vault_transit`、`kms_gateway`。
- 新密文使用带后端版本的 envelope，错误后端不会静默尝试解密。
- Vault Transit 使用实际 encrypt/decrypt HTTP 契约；KMS 网关使用实际 HTTPS/Bearer 最小契约，可在网关侧适配阿里云、腾讯云或 HSM。
- 外部托管凭据只从文件读取，HTTP 不跟随重定向，生产强制 HTTPS。
- production 使用 `local_fernet` 时运行时检查返回 error。
- 旧 Fernet 密文通过独立、临时、只读 legacy recovery key file 双读，不允许与新密文后端混淆。

### 2.2 恢复演练

- 管理端展示脱敏托管状态、生产门禁、key reference 和旧密文恢复状态。
- `round_trip` 用于即时加解密验证；`recovery_canary` 会优先解密此前持久化的同一探针。
- 数据库不保存探针明文，只保存密文、期望摘要、恢复摘要、匹配结果、耗时和脱敏错误。
- 成功和失败都形成租户隔离的不可变证据。

### 2.3 SLO 告警升级

- 租户策略新增：告警开关、冷却分钟、升级等待分钟、恢复通知开关。
- Worker 生成 `opened`、`reminded`、`escalated`、`resolved` 事件。
- L1/L2 与首次观察时间一并保存；外部通知失败不影响 SLO 事件证据。
- 现有通知通道迁移时自动订阅 SLO 打开、升级、恢复和回放死信事件。

### 2.4 回放死信人工接管

- 回放任务新增负责人、接管原因、接管时间、人工重入累计、人工结论。
- 新增动作：`take_over`、`requeue`、`resolve`、`cancel`。
- 仅死信可接管、重入或人工解决；运行中任务禁止人工取消。
- 人工重入重置本轮 attempt count，但保留 `manual_requeue_count`、原失败运行和完整事件账本。
- 回放进入死信时自动发出站内及已订阅外部通知。

### 2.5 提供方错误手册

- 九类错误均定义默认重试性、首响/升级分钟、负责人角色和操作步骤。
- API 返回版本与 SHA-256 摘要，管理页展示同一目录，便于确认前后端手册一致。
- 本地详细手册：`project-docs/playbook-calendar-provider-error-operations-runbook-2026-08-24.md`。

## 3. 数据与接口

迁移：`20260824_0062`。

新增表：

- `playbook_secret_recovery_drills`
- `playbook_calendar_slo_alert_events`
- `playbook_calendar_replay_events`

新增接口：

- `GET /governance/secret-custody/status`
- `GET|POST /governance/secret-custody/recovery-drills`
- `GET /governance/calendar-slo-alert-events`
- `GET /governance/calendar-provider-error-catalog`
- `GET /governance/calendar-replay-jobs/{job_id}/events`
- `POST /governance/calendar-replay-jobs/{job_id}/intervention`

OpenAPI 当前为 117 paths / 174 schemas；最终验收会再次验证 YAML 可解析。

## 4. 明确边界

- 本地/UAT 没有伪造真实 Vault、阿里云 KMS 或腾讯云 KMS 账号；外部适配器通过隔离 MockTransport 验证请求、响应、密文 envelope 和 legacy 双读。
- 真正发布前仍需客户提供 Vault/KMS endpoint、key、文件凭据、CA 链和网络白名单，在隔离预发布环境执行恢复演练。
- KMS 网关负责云厂商认证、密钥轮换与 AAD 元数据；合同 API 不持有云厂商 AccessKey。

## 5. 验收证据

最终结果：

- [x] 后端：355 collected，351 passed，4 skipped；无失败。新增用例覆盖 Vault Transit、KMS 网关、legacy 双读、production 门禁、持久化恢复探针、SLO 打开/升级/恢复、回放死信接管/重入。
- [x] PostgreSQL：升级到 `20260824_0062 (head)`；全新 SQLite 从零升级到 head 也通过。
- [x] 前端：typecheck 通过；45/45 测试通过；生产 build 通过，143 个页面/路由。
- [x] OpenAPI：YAML 可解析，117 paths / 174 schemas，所有 schema `$ref` 均可解析。
- [x] 服务：Contract API `8100` health=ok，Web `3000` HTTP 200，AI API `8101` 保持运行；治理 Worker 重启且 stderr 无错误。
- [x] 超级管理员 Chrome UAT：账号 `uat.legal.20260823@example.test`、工作区“Playbook 隔离 UAT”；P1-04.9.1、托管状态、恢复探针、SLO 升级、错误手册、回放人工接管均可见，治理数据加载错误为 false。

UAT 未点击“解密持久化恢复探针”，避免在用户租户写入额外演练证据；该写操作已由隔离 API 自动化覆盖。