yuqei
1d85329a6a
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 9m12s
Build and Test Quality Gate / Isolated Alibaba and Tencent KMS gateway (pull_request) Failing after 4m53s
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 24m55s
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 8m42s
95 lines
5.8 KiB
Markdown
95 lines
5.8 KiB
Markdown
# V2 P1-07.3 值班例外、错误预算、漏斗下钻与审计验证实施说明
|
||
|
||
> 实施日期：2026-08-25
|
||
> 状态：已实现，进入发布门禁与隔离 UAT
|
||
> 适用角色：平台超级管理员、试点运营、产品经理、法务运营、SRE、内外部审计人员
|
||
|
||
## 1. 交付结论
|
||
|
||
P1-07.3 将试点运营从“可观察”推进到“可治理、可追责、可外部核验”：值班轮换支持有时间边界的请假与换班例外；扫描和升级通知按照可配置目标计算错误预算与燃烧率，并保留预警、严重、预算耗尽和恢复事件；可靠决策漏斗可按租户与行业下钻；版本级起草证据具备有效期、提前提醒和过期阻断；严格可靠决策可导出不含合同正文的 JSON 证据包，由外部验证页核对包完整性、验证令牌和实时账本。
|
||
|
||
系统仍坚持两条底线：自动路由不计为人工首次响应；运营指标、提醒和外部验证均不暴露合同正文、通知密钥或签署凭据。
|
||
|
||
## 2. 产品与业务口径
|
||
|
||
### 2.1 换班与请假例外
|
||
|
||
- 例外必须绑定当前值班策略中的原成员，并设置开始和结束时间；
|
||
- `swap` 必须指定不同的替班账号，`leave` 未指定替班时转给兜底负责人；
|
||
- 可限制为失败任务、签署异常或人工复核队列；队列为空表示全部队列；
|
||
- 同一成员的生效时段不能重叠，避免出现互相矛盾的替班结论；
|
||
- 自动路由事件记录 `assignment_source` 和 `exception_id`，同时保持 `counts_as_first_response=false`；
|
||
- 撤销只改变例外状态，原始创建人、原因和时间窗不删除。
|
||
|
||
### 2.2 错误预算与多级告警
|
||
|
||
错误预算按观察周期的终态样本计算：
|
||
|
||
`允许失败数 = 样本数 × (1 - SLO 目标)`
|
||
`燃烧率 = 实际失败率 ÷ (1 - SLO 目标)`
|
||
|
||
- 扫描与外部升级通知分别配置目标，默认均为 99%；
|
||
- 未达到最小样本时不产生预算告警，避免单个试点样本引起误报；
|
||
- 达到预警/严重阈值或预算耗尽时写入生命周期事件并创建平台通知；
|
||
- 指标恢复时关闭当前告警并追加 `recovered` 事件，不静默覆盖历史；
|
||
- 只有已启用、握手通过且订阅 `pilot_operation_slo_alerted` 的既有通道才会接收外部 SLO 告警；默认关闭，不因升级自动发信。
|
||
|
||
### 2.3 租户与行业漏斗下钻
|
||
|
||
- 平台总漏斗改用 `(tenant_id, contract_id)` 复合键去重，修复跨租户误归因风险；
|
||
- 租户下钻展示版本、审查完成、起草证据、显式确认、下游动作与严格决策；
|
||
- 行业从租户 `settings.industry|industry_key|industry_name` 读取，缺失时明确归入“未标注行业”；
|
||
- 租户下钻可继续跳转到该租户的异常工单过滤结果；
|
||
- 下钻只返回计数和租户标识，不返回合同标题、正文、风险文本或参与人信息。
|
||
|
||
### 2.4 起草证据有效期
|
||
|
||
- 平台策略配置有效天数和提前提醒天数，默认 30 天有效、提前 3 天提醒；
|
||
- 合同证据接口返回 `expires_at`、`expires_soon` 和 `expired`；
|
||
- 未确认且即将过期/已过期时，定时扫描按原起草用户创建定向站内提醒；
|
||
- 同一生成事件和提醒类型只创建一次；已完成起草确认或可靠决策时不再提醒；
|
||
- 过期证据不能补做四项核对，后端返回 `draft_evidence_expired`，用户必须重新生成当前版本或改走合同审查路径。
|
||
|
||
### 2.5 决策证据导出与验证
|
||
|
||
- 只有具备合同下载权限且已经形成严格可靠决策时才能导出；
|
||
- 包含租户、合同、版本、决策动作、路径证据、摘要和时间，不包含合同正文、风险正文、通知目标或凭据；
|
||
- 每次导出生成随机验证令牌，数据库只保存令牌 SHA-256，不保存明文；
|
||
- 外部验证先重算规范化 JSON 包摘要，再核对令牌哈希、导出账本和当前可靠决策账本；
|
||
- 令牌正确的验证会追加验证事件；篡改包、过期或缺失账本均返回不通过；
|
||
- 验证页 `/evidence-verification` 支持 JSON 文件或粘贴，不要求登录，也不提供按合同 ID 查询能力。
|
||
|
||
## 3. 数据与接口
|
||
|
||
新增数据表：
|
||
|
||
- `pilot_operation_on_call_exceptions`
|
||
- `pilot_operation_slo_alert_events`
|
||
- `reliable_decision_evidence_exports`
|
||
- `reliable_decision_evidence_verifications`
|
||
|
||
策略新增 SLO 目标、燃烧率阈值、最小样本、证据有效期和提醒开关。主要接口：
|
||
|
||
- `GET|POST /api/v1/admin/pilot-operations/on-call-exceptions`
|
||
- `POST /api/v1/admin/pilot-operations/on-call-exceptions/{id}/cancel`
|
||
- `GET /api/v1/admin/pilot-operations/insights`
|
||
- `POST /api/v1/contracts/{contract_id}/reliable-decision/export`
|
||
- `POST /api/v1/public/reliable-decision/verify`
|
||
|
||
## 4. 发布门禁
|
||
|
||
- Alembic 达到 `20260825_0068`，通过空库升级、`0068 -> 0067 -> 0068` 往返；
|
||
- 换班测试证明受影响队列使用替班账号、撤销后恢复轮换，事件仍不计人工首响；
|
||
- 错误预算测试同时覆盖最小样本、预算耗尽和告警账本；
|
||
- 起草证据测试覆盖提前状态、过期阻断、提醒幂等；
|
||
- 导出验证测试覆盖正常包、篡改包、权限与正文排除；
|
||
- 人工 OpenAPI 无悬空引用，运行时 OpenAPI 包含全部新接口；
|
||
- Contract API 全量测试、Web 测试、类型检查、生产构建、PostgreSQL 迁移及 Chrome UAT 全部通过。
|
||
|
||
## 5. 已知边界与后续建议
|
||
|
||
- 行业维度依赖租户资料质量，未标注租户应纳入试点运营的数据治理任务；
|
||
- 当前错误预算使用单观察窗和终态失败率，下一阶段可增加 1 小时/6 小时/30 天多窗口燃烧率和抑制规则；
|
||
- 外部验证是在线账本验证，不是离线公钥签名。对监管归档或跨系统长期验真，应进入 P1-07.4：KMS 托管的非对称签名、证书轮换、撤销清单与审计机构 API 配额。
|
||
|