ai-contract-platform/project-docs/pilot-operations-automation-runbook-2026-08-25.md

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

1. 启动与健康检查

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

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 当作普通故障恢复手段。