ai-contract-platform/project-docs/playbook-calendar-provider-error-operations-runbook-2026-08-24.md

企业日历提供方错误运营手册

版本：2026-08-24.p1-04.9.1
适用范围：Google Calendar、Microsoft Graph、钉钉、企业微信、ICS 订阅，以及承载其凭据的 Vault Transit / 企业 KMS 网关。

1. 值班原则

1. 以同步运行 ID、回放任务 ID 和 SLO 告警事件 ID 为证据主键，不以聊天截图代替系统证据。
2. 不覆盖原失败运行；恢复动作必须创建回放任务或人工处置事件。
3. 不在日志、工单、通知或截图中粘贴 OAuth token、AppSecret、Vault token、KMS 明文或完整密文。
4. authentication、authorization、configuration、validation 默认禁止自动重试；rate_limited、cursor_invalid、network 和部分 provider_error 才可进入受限退避。
5. unknown 一律先分配事故负责人、暂停批量重入，并补充分类、测试和本手册后再恢复。

2. 错误分类与处置矩阵

分类	默认动作	首响 / 升级	负责人	核心处置
authentication	人工	30 / 60 分钟	租户管理员	校验令牌有效期、连接指纹和密钥托管；重新授权或轮换凭据
authorization	人工	30 / 60 分钟	租户管理员	核对最小只读权限与管理员同意证据，不通过扩大权限绕过
rate_limited	退避	15 / 120 分钟	平台运维	保存提供方错误码或 Retry-After，降低并发并指数退避
cursor_invalid	显式全量回放	30 / 120 分钟	平台运维	保留旧游标指纹，以新运行重建全量快照并验证新游标
network	退避后人工	15 / 60 分钟	平台运维	检查国内网络路径、DNS、TLS 和超时；持续失败转人工接管
configuration	人工	30 / 120 分钟	租户管理员	冻结回放，修复日历、调度或托管配置，先做恢复演练
provider_error	按 HTTP/提供方码	30 / 120 分钟	平台运维	记录脱敏状态码，判断重试性；未知代码补充回归测试
validation	人工	60 / 240 分钟	法务运营	核对全天事件、日期边界和返回结构，修复映射后回放
unknown	立即接管	15 / 30 分钟	事故负责人	暂停批量回放，收集脱敏证据，形成新分类后恢复

后端的同版本目录可通过 GET /api/v1/enterprise-playbook/governance/calendar-provider-error-catalog 查询；返回摘要用于核对管理页和手册版本。

3. SLO 告警生命周期

• opened / L1：某个受监控源首次进入 blocked 或 breached。
• reminded / L1：仍未恢复，且超过租户配置的告警冷却期。
• escalated / L2：从首次观察起超过升级等待时间。
• resolved：源恢复健康；无论是否发送恢复通知，系统都保留不可变关闭事件。

默认外部通知事件：

• playbook_calendar_slo_breached
• playbook_calendar_slo_escalated
• playbook_calendar_slo_recovered
• playbook_calendar_replay_dead_letter

通知投递失败不会抹掉 SLO 事件；通知派发有独立任务、重试和死信记录。

4. 回放死信人工接管

1. 在管理端确认原失败运行、错误分类、尝试次数和最后错误。
2. 使用“接管”指定负责人，并填写外部工单、检查范围或处置理由。
3. 修复外部条件后选择“重新入队”。系统会重置本轮尝试次数、累计 manual_requeue_count，原失败运行和死信事件保留。
4. 若已通过提供方后台或线下流程完成处置，使用“人工解决”填写结论；不得把未修复任务直接标记成功。
5. 运行中任务不能取消；须等待完成或租约到期，避免 Worker 与人工同时改写状态。

事件账本动作依次可能为：created → dead_lettered → taken_over → requeued → dead_lettered/resolved/succeeded。

5. Vault Transit 托管

应用使用 Vault Transit 的 encrypt/<key> 和 decrypt/<key> HTTP 接口；明文以 Base64 传输，数据库只保存带后端标记的 Vault 密文。建议：

1. 为合同平台创建独立 Transit key，禁止应用 token 创建新 key。
2. 应用策略只授予指定 key 的 encrypt/decrypt 权限；轮换和策略修改属于运维权限。
3. Vault token 只通过只读文件注入，不写入环境示例、数据库或管理页。
4. 在轮换、恢复、集群切换后先执行 recovery_canary，摘要匹配后再恢复日历同步。
5. 使用 rewrap 或供应商认可的轮换流程更新旧密文时，先在隔离环境验证并保留变更证据。

配置项：

CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_BACKEND=vault_transit
CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_ENDPOINT=https://vault.example.cn
CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_KEY_REFERENCE=playbook-calendar-credentials
CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_CREDENTIAL_FILE=/run/secrets/vault_token
CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_VAULT_MOUNT=transit

6. 企业 KMS 网关契约

为避免在业务服务中绑定多个云厂商 SDK，本阶段使用部署在企业内网的 HTTPS KMS 网关。网关可适配阿里云 KMS、腾讯云 KMS 或企业 HSM，但必须保持以下最小契约：

POST /v1/encrypt
Authorization: Bearer <file-injected credential>
Content-Type: application/json

{"key_id":"playbook-calendar-credentials","plaintext":"<base64>"}

返回：{"ciphertext":"<provider wrapped ciphertext>"}。

POST /v1/decrypt
Authorization: Bearer <file-injected credential>
Content-Type: application/json

{"key_id":"playbook-calendar-credentials","ciphertext":"<provider wrapped ciphertext>"}

返回：{"plaintext":"<base64>"}。

要求：生产只允许 HTTPS、禁止重定向、网关不得记录请求体、凭据必须来自文件、错误只返回脱敏状态，不得把云厂商密钥或明文写入响应日志。阿里云启用自动轮转时，网关实现应选用支持轮转语义的 AdvanceEncrypt / AdvanceDecrypt 或等价信封加密流程，并保存解密所需的 KeyId、密文与 AAD 元数据。

7. 旧密文迁移与恢复

• 新密文带有 yuqei-custody:v1:<backend>: 前缀，防止错误后端静默解密。
• 切换到外部托管后，可临时设置 CONTRACT_API_PLAYBOOK_SECRET_CUSTODY_LEGACY_RECOVERY_KEY_FILE 只读解密旧 Fernet 密文；禁止继续使用旧 key 加密新数据。
• 旧恢复 key 文件只能存在于迁移窗口，完成凭据重连或重包裹并验证后撤除。
• recovery_canary 首次创建随机探针，后续重复解密同一持久化密文；系统只返回密文指纹、耗时和摘要匹配，不返回探针明文。
• production 若选择 local_fernet，运行时配置检查为 error，不得发布。

8. 交接证据清单

• 租户、日历源、提供方、原同步运行 ID。
• 错误分类、脱敏提供方错误码、首次/最近发生时间。
• SLO 事件 ID、生命周期和升级级别。
• 回放任务 ID、负责人、人工重入次数和事件账本。
• 密钥托管后端、key reference、最近成功恢复演练 ID。
• 外部工单、变更单或提供方公告链接；不得包含任何秘密值。

9. 官方依据

• HashiCorp Vault Transit API：https://developer.hashicorp.com/vault/api-docs/secret/transit
• HashiCorp Vault Transit 概念与轮换密文格式：https://developer.hashicorp.com/vault/docs/secrets/transit
• 阿里云 KMS 实例 API 概览：https://help.aliyun.com/zh/kms/key-management-service/developer-reference/api-overview