# 试点运营自动化与 SLA 升级运行手册

## 1. 启动与健康检查

先升级数据库，再分别启动 Contract API、Web、审查 worker 和治理 worker：

```powershell
cd D:\yuqei-project\ai-contract-platform\yuqei-contract-platform\services\contract-api
python -m alembic -c alembic.ini upgrade head
python -m yuqei_contract_api.playbook_governance_worker --health
python -m yuqei_contract_api.playbook_governance_worker --run-once
python -m yuqei_contract_api.playbook_governance_worker
```

治理 worker 的 `--run-once` 输出应包含 `pilot_scan_claimed`、`pilot_scan_succeeded`、`pilot_escalations_enqueued` 和 `reliable_decisions_created`。长期进程轮询周期由 `CONTRACT_API_PLAYBOOK_GOVERNANCE_WORKER_POLL_INTERVAL_SECONDS` 控制；真正的扫描节奏由数据库策略的 `scan_interval_minutes` 控制。

## 2. 首次配置

1. 使用平台超级管理员打开 `/admin/pilot-operations`；
2. 核对时区、工作日、工作时间和节假日；
3. 先保持外部升级关闭并保存策略；
4. 在企业 Playbook 通知配置中创建邮件或 Webhook 通道，订阅 `pilot_operation_sla_escalated`，完成握手测试；
5. 回到试点运营后台选择合格通道，再启用外部升级；
6. 点击“立即执行完整扫描”，核对最新扫描证据。

禁止直接在数据库填入未握手通道，也不要把 Google/Microsoft 日历 OAuth 凭据当作平台运营日历配置。

## 3. 日常值守

1. 查看最近扫描是否持续成功，若超过两个预期扫描周期没有新证据，先检查治理 worker；
2. 使用“超时、未分派、严重级别”筛选处理队列；
3. 在当前页勾选工单并批量分派，每批不超过 100 条；
4. 业务恢复必须在审查、签署或合同模块完成，运营工单只记录协调和结论；
5. 工单说明不得粘贴合同正文、签署账号、临时链接、供应商原始响应或密钥；
6. 处理后运行一次完整扫描，确认来源恢复和自动关闭结果。

## 4. 扫描故障

| 现象 | 检查 | 处置 |
| --- | --- | --- |
| `claimed=false` | 是否已有 worker 持有租约 | 等待租约到期；不要并发强制清锁 |
| 最新运行 `failed` | `error_code`、Contract API 日志、数据库健康 | 修复依赖后再次执行；错误码只记录异常类型，不写原始敏感正文 |
| 运行长期停在 `running` | worker 是否崩溃、租约是否到期 | 先确认旧进程已停止；租约到期后由下一进程领取 |
| 扫描成功但无新工单 | 筛选条件、观察周期、源状态 | 对比源任务；扫描幂等不会重复创建同一来源工单 |

## 5. SLA 与通知故障

- 工单超时但未入队：确认未有 `first_response_at`、策略已启用通知、通道握手通过且订阅正确事件；
- 已入队但未送达：在 Playbook 通知死信和投递运行中检查，不要手工清除工单升级标识后盲目重发；
- Webhook 轮换期间失败：验证当前/旧密钥灰度窗口与对端配置；
- 大面积通知失败：先关闭策略中的外部升级，保留站内工单和投递证据，避免告警风暴；
- 恢复后：通过既有死信重放流程处理，不能重新构造包含敏感信息的自定义请求。

## 6. 可靠决策对账

合同详情“可靠合同决策证据”面板逐项显示四个条件。若用户已经确认风险但后台仍未计数：

1. 核对确认之后是否发生审批通过、合同下载或归档；确认之前的旧动作不会被接受；
2. 核对审查风险集合是否在确认后变化；变化后必须针对新集合重新确认；
3. 执行完整扫描，查看 `reliable_decisions_created`；
4. 按合同版本检查 `reliable_contract_decisions`，同一版本只能形成一条严格证据；
5. 不得通过手工改合同状态或补数据库行来提高指标。

## 7. 回滚与数据保护

迁移版本为 `20260825_0066`。代码回滚前可先关闭策略扫描和外部升级，但保留治理 worker 对既有 Playbook 队列的处理能力。

数据库 downgrade 会删除扫描运行、策略、风险确认和可靠决策证据，并移除工单升级字段。正式环境只有在导出证据、停止写入并取得变更批准后才允许执行；不能把 downgrade 当作普通故障恢复手段。