ai-contract-platform/project-docs/V2-P1-04.6-sla-calendar-external-notifications-root-cause-dead-letter-graph-clustering-2026-08-23.md

P1-04.6 租户 SLA、外部通知、根因建议、任务死信与关系图聚类交付报告

日期：2026-08-23
状态：已实现、已迁移、已完成 Chrome 登录态 UAT，自动化与生产构建验证通过

1. 阶段目标与结论

本阶段完成以下五项能力：

1. 将固定自然小时 SLA 升级为租户级策略，支持时区、工作日、工作时段、节假日、分级时限和即将到期窗口；
2. 在站内治理通知之外增加可靠外部派发队列，并提供 Webhook、邮件适配器、签名、重试和死信；
3. 对冲突账本提供可解释的根因分类、复发证据、置信度和规则优化建议；
4. 为影响分析任务增加指数退避、逐次执行证据、终态死信、人工重排审计和队列指标；
5. 为大规模规则关系图增加连通分量、规则类型聚类和服务端单簇裁剪。

结论：P1-04.6 将 P1-04.5 的“可处理治理事项”升级为“可配置、可派发、可解释、可恢复、可扩展”的企业治理运营能力。策略、适配器、任务、派发、根因和图数据均按 tenant_id 隔离；外部通道默认停用，人工重排必须填写原因，不会静默覆盖合同正文、规则正文或历史证据。

2. 产品与业务流程

2.1 租户级 SLA 与工作日历

治理管理员可以配置：

• IANA 时区，例如 Asia/Shanghai；
• 是否启用工作日历；
• 周一至周日的工作日集合；
• 每日开始和结束时间；
• blocker、warning、info 的 SLA 小时数；
• 即将到期提醒窗口；
• YYYY-MM-DD 格式的租户节假日；
• 是否将新策略一次性重排到所有开放事项。

工作日历启用后，SLA 只在有效工作时段内消耗。例如周五 17:00 创建的 4 个工作小时事项，会顺延到下一个有效工作日。策略版本、来源、目标小时数和 due_soon_at 固化到每个冲突事件，历史事件能够解释“为什么是这个截止时间”。单事项手动 SLA 仍可覆盖租户策略，并明确标记 manual_override。

保存策略与开放事项重排在同一租户事务内执行。关闭事项保留原截止时间；开放事项按创建时间、严重程度和新日历重新计算，不通过定时补丁产生短暂不一致。

2.2 外部通知适配器

外部派发采用“站内通知事实 → 租户启用通道 → 可靠 outbox → Worker 派发”的链路。创建适配器默认停用，避免配置完成即产生意外外发。

支持：

• Webhook：仅允许 HTTPS、禁止 URL 内嵌账号密码、阻止 localhost 和非公共 IP，使用系统密钥按通道派生 HMAC-SHA256 签名；
• 邮件：复用身份邮件 SMTP 配置；开发模式只模拟接受，不发送真实邮件；
• 每个通道独立订阅事件类型；
• 指数退避、租约、尝试次数、响应码、错误信息、成功时间和终态死信；
• 有派发历史的通道禁止删除，只允许停用，保证审计链不被截断。

Webhook 密钥支持环境变量或只读文件，两者同时设置会使运行时配置失败。生产 Compose 使用 opt-in 覆盖文件挂载 webhook 密钥，并为治理 Worker 复用 SMTP secret。

2.3 冲突根因建议

根因分析基于冲突事实、问题代码、规则关系和租户内同类历史事件生成确定性、可解释结论，当前分类包括：

• text_boundary：替换文本与原句标点或词边界重叠；
• context_scope：规则命中范围超出安全上下文；
• rule_relationship：依赖或互斥关系不完整；
• candidate_staleness：候选基于过期规则或版本；
• concurrency：版本竞争或并发采用；
• configuration_gap：配置与样本覆盖不足。

返回标题、解释、low/medium/high 置信度、租户内同类事件数量、疑似规则、证据和可执行建议。当前算法刻意不调用生成式模型，优先保证相同事实得到稳定结论，适合审计和运营归因。

2.4 任务死信与可观测性

影响分析任务状态扩展为 queued、running、retry_scheduled、succeeded、failed、dead_letter 和 cancelled。每次领取都会追加不可变 attempt 记录，包含 worker、序号、开始/结束时间、耗时和错误。

执行失败后使用 30 秒、60 秒指数退避；第三次失败进入 dead_letter，并生成站内治理通知。管理员只能从死信状态重排，且必须填写 3～2000 字原因；重排动作写入独立审计表，旧 attempts 不会被覆盖。

治理配置页展示：

• 各状态影响任务数；
• 外部派发各状态数量；
• 最老排队时长；
• 24 小时成功率与平均耗时；
• 影响任务死信列表和人工重排入口；
• 近期外部派发状态与错误。

Worker 同一轮处理影响分析、外部派发和 SLA 升级，保持部署简单；三类工作使用独立计数，不会把外部派发失败误记为影响分析失败。

2.5 超大关系图聚类

关系图支持三种模式：none、connected_component、rule_type。服务端先在租户完整关系集上计算簇摘要，再按 cluster_id 裁剪节点和边，避免前端仅在当前分页上伪聚类。

簇摘要包含节点数、边数、启用节点数和删除保护数。连通簇算法使用稳定排序生成确定性标识；按规则类型聚类适合运营盘点。聚类可与搜索、关系类型、启用状态、焦点邻域和分页组合使用。

3. 技术实现

3.1 数据与迁移

Alembic 版本：20260823_0057。

新增表：

• playbook_governance_policies：租户 SLA、时区、工作日历和策略版本；
• playbook_notification_channels：Webhook/邮件通道、订阅范围和最后派发状态；
• playbook_notification_deliveries：可靠派发 outbox、租约、重试、响应和死信；
• playbook_impact_job_attempts：影响任务每次执行证据；
• playbook_impact_job_audit：人工重排原因和操作者审计。

扩展 playbook_impact_analysis_jobs 的 next_attempt_at、last_heartbeat_at、dead_lettered_at；扩展 playbook_conflict_events 的 due_soon_at、sla_policy_version、sla_source、sla_target_hours。

0056/0057 的 downgrade 已显式先删除关联索引再删除 SQLite 列，升级—降级—再升级链路可重复执行。运行时 schema-check 已覆盖新增表和关键列。

3.2 后端与接口

新增或扩展接口：

• GET /api/v1/enterprise-playbook/rules/impact-analysis/jobs；
• GET /api/v1/enterprise-playbook/rules/impact-analysis/jobs/{job_id}/attempts；
• POST /api/v1/enterprise-playbook/rules/impact-analysis/jobs/{job_id}/requeue；
• GET/PUT /api/v1/enterprise-playbook/governance/policy；
• GET/POST /api/v1/enterprise-playbook/governance/notification-channels；
• PUT/DELETE /api/v1/enterprise-playbook/governance/notification-channels/{channel_id}；
• GET /api/v1/enterprise-playbook/governance/queue-metrics；
• GET /api/v1/enterprise-playbook/conflict-events/{event_id}/root-cause；
• GET /api/v1/enterprise-playbook/relationship-graph 增加 cluster_mode 和 cluster_id。

策略更新、适配器写操作和死信重排要求租户管理员角色；治理查看权限只能读取当前租户。Pydantic 对工作时段、星期、节假日、邮件地址、Webhook 协议和事件订阅进行边界校验。

3.3 前端与通知中心

企业 Playbook 页面新增“治理配置”标签，包含租户 SLA 表单、工作日复选、节假日录入、适配器管理、队列指标、死信重排和近期派发。冲突卡片显示 SLA 来源/目标，并可展开根因建议。关系图增加聚类模式、簇摘要和单簇筛选。

前端轮询识别 retry_scheduled 和 dead_letter，避免把等待重试误报为未知状态。通知中心新增影响分析死信类型和高风险视觉提示，可深链到治理配置页。

OpenAPI 手工契约与 FastAPI 运行时契约同步增加上述路径、状态和 schema。

4. Chrome 登录态 UAT 证据

工作空间：uat-playbook-20260823
账号：uat.legal.20260823@example.test
角色：管理员/法务治理账号

4.1 SLA 策略与开放事项重排

在真实管理页面将策略配置为：Asia/Shanghai、周一至周五、09:00～18:00、blocker 4 小时、warning 16 小时、info 40 小时、即将到期 2 小时、节假日 2026-10-01，并启用工作日历和开放事项重排。

页面确认“租户 SLA 策略已更新至 v1，并重排 3 个开放事项”。冲突账本的 3 个开放 warning 事项均显示 SLA 16h/tenant_policy，截止时间顺延到 2026-08-25 16:00；已解决事项继续保留 SLA 24h/default 和原截止时间，证明历史结果未被静默改写。

4.2 外部适配器

创建邮件适配器“UAT P1046 治理邮件适配器”，收件人为合成 UAT 地址 governance-uat@example.test，并保持停用。页面显示 1 个适配器、email、停用、订阅 2 类事件；未产生外部派发记录，也未发送真实邮件。

4.3 根因建议

对已解决事件 playbook-conflict-73bfa8408f3a 展开根因分析，页面给出：

• 标题：替换文本与原句标点边界重叠；
• 分类：text_boundary；
• 置信度：high；
• 同类事件：3 个；
• 建议：统一兜底文本标点策略、重新 dry-run 复核词级差异、增加边界样本。

该结论与账本中的 runtime_punctuation_collision 证据一致，并且没有修改原处理结论。

4.4 关系图聚类

真实租户关系图包含 6 个节点、3 条边。选择“关系连通簇”后识别 3 个簇：主簇 4 节点/3 边/2 个受保护节点，另有两个单节点簇。点击主簇后服务端返回 4/6 个节点和 3 条边，证明聚类摘要基于全图、可按簇裁剪。

Chrome 页面无控制台 error/warn，最终保留在主关系簇视图供继续验收。

5. 验证结果

• Contract API 全量测试：340 通过、4 个环境条件测试跳过；
• P1-04.6 专项测试：7/7 通过；
• 迁移升级—降级定点测试：4/4 通过；
• 前端完整测试：41/41 通过；
• Python compileall：通过；
• TypeScript 类型检查：通过；
• Next.js 生产构建：通过；
• OpenAPI YAML：86 个路径、134 个 schema，解析通过；
• FastAPI 运行时 OpenAPI：166 个路径、259 个 schema；
• Alembic 当前版本：20260823_0057 (head)；
• 运行时 schema-check：数据库、迁移、核心表及 Playbook operations 全部通过；
• 本地 schema-check 总状态仅因开发环境关闭 anti-abuse 为 warning，不涉及本阶段结构或迁移失败；
• git diff --check：通过，仅有仓库既有的 LF/CRLF 转换提示；
• Contract API、Contract Web、AI API 与 Playbook Governance Worker 正常运行。

6. 市场与架构评估

本阶段显著提升企业客户可接受度：SLA 可以匹配企业工作制度，外部通知能进入现有运营链路，根因建议降低规则运营门槛，死信处理避免任务“消失”，聚类使大规则库仍可管理。这五项能力共同解决了企业采购中常见的“可配置、可追责、可恢复、可扩展”要求。

当前采用 PostgreSQL 数据库队列而非新增消息中间件是合理的：现阶段吞吐有限，事务一致性和部署简单性优先。任务与派发契约已经独立，未来迁移 Redis Streams、RabbitMQ 或 Kafka 时不需要改变前端和业务 API。

确定性根因建议比直接接入大模型更适合作为第一版治理证据。后续可以在保留规则化解释的前提下，用人工结论训练排序或推荐模型，但模型输出不应替代审计事实。

7. 已知边界与下一阶段建议

1. 节假日目前由租户手工维护，尚未接入法定节假日、调休模板或企业 HR 日历；
2. 外部通道首版为 Webhook 和邮件，尚未提供企业微信、钉钉、飞书、Slack 等专用卡片适配器，也未提供“测试连接”握手；
3. Webhook 已阻止解析到私网的目标，但 DNS 校验与实际连接之间仍存在理论上的 DNS 重绑定窗口；生产建议使用固定出口代理、域名/IP allowlist 和网络层 egress policy；
4. 根因建议是确定性启发式算法，尚未利用负责人结论形成反馈闭环；
5. 死信目前逐条重排，尚未提供批量选择、批量归因和告警阈值；
6. 关系图已具备服务端聚类和裁剪，数千节点的交互渲染仍应升级 WebGL、关系折叠或离线物化社区；
7. 数据库队列适合当前规模；当排队深度、租约竞争或外部派发吞吐达到阈值时，再迁移专用消息基础设施。

下一阶段建议进入 P1-04.7：企业日历模板与节假日同步、外部通道测试握手和密钥轮换、根因反馈学习、死信批量运营与告警、WebGL/物化关系社区。