yuqei
1d85329a6a
9.9 KiB
P1-04.5 冲突账本、SLA、治理通知、异步影响分析与大规模关系图交付报告
日期：2026-08-23
状态：已实现、已迁移、已通过自动化验证与 Chrome 登录态 UAT
1. 阶段目标与结论
本阶段完成以下五项能力：
- 将候选预警、组合冲突和候选采用冲突统一写入租户隔离的冲突事件账本；
- 为冲突增加负责人、处理状态、到期时间、SLA 逾期升级和完整操作历史；
- 为指派、逾期、规则审批结果等治理事件提供按用户定向的站内通知和可执行深链接；
- 将规则变更影响分析升级为可租约恢复、可重试、可查询结果的数据库异步任务；
- 将规则关系图升级为服务端分页、搜索、筛选、焦点邻域和大图裁剪。
结论：P1-04.5 已形成“冲突产生 → 自动入账 → 指派与 SLA → 定向通知 → 处理结论 → 历史追溯”的运营闭环，并解决同步影响分析和一次性全图加载在大租户下的扩展性问题。所有治理数据均按 tenant_id 隔离；冲突处理不会静默修改合同正文或规则正文。
2. 产品与业务流程
2.1 冲突事件账本
账本统一记录候选运行时预警、组合规则 blocker 和候选采用冲突。每个事件包含来源、合同/审查/快照上下文、问题代码、严重程度、涉及规则、负责人、状态、SLA 到期时间、处理结论和时间线。
系统以租户和事件语义生成稳定 fingerprint，重复读取旧候选或重复上报同一问题不会生成重复事件。历史候选中的既有预警会在首次查询时幂等回填，不批量制造通知噪音。
支持的事件状态为：
- open：新建、尚未开始处理；
- in_progress：已指派并进入处理；
- resolved：问题已处理并保留结论；
- dismissed：经复核无需处理并保留原因。
2.2 负责人和 SLA
可指派对象只包含当前租户内启用的管理员、法务和审批角色，避免跨租户或无权限用户被错误指派。默认 SLA 按严重程度设置：blocker 4 小时、warning 24 小时、info 72 小时；指派时可按事项重置小时数。
治理 Worker 周期扫描逾期事件。首次逾期时写入 sla_breached 历史并向负责人发送定向通知；同一事件不会重复发送逾期通知。运营台提供待处理、已逾期、即将到期、未指派等指标和筛选条件。
2.3 治理通知
通知模型增加 recipient_user_id、action_url、resource_type 和 resource_id。用户只能看到当前租户的全局通知以及发给自己的定向通知，标记已读同样受租户和收件人约束。
本阶段覆盖：
- 冲突事项指派给负责人；
- 冲突事项 SLA 逾期；
- 规则变更等待独立审批；
- 规则变更审批通过或拒绝。
冲突通知可直接进入 Playbook 冲突运营台并高亮对应事件，减少“收到通知但找不到处理入口”的断点。
2.4 异步影响分析
前端提交影响分析任务后轮询任务状态。任务持久化请求摘要、执行状态、尝试次数、租约、结果、错误和完成时间。专用 Worker 使用数据库抢占和租约执行，进程异常后任务可重新领取，最多尝试 3 次。
同步影响分析接口暂时保留兼容但已标记 deprecated；新流程统一使用异步任务接口。当前数据库队列适合本阶段规模，且无需引入新的基础设施依赖。
2.5 大规模关系图
关系图不再强制一次返回租户全部规则，支持：
- page/page_size 服务端分页，单次上限 500 个节点；
- 按规则名称或标识搜索；
- 按依赖、互斥关系和启用状态筛选；
- 以指定规则为焦点加载 1～3 层邻域；
- 只返回可见节点之间的边，避免前端悬空边；
- 返回全局节点、边、删除保护数量和当前裁剪信息。
前端为焦点邻域提供径向布局，并显示入站/出站关系数量。搜索、筛选和焦点查询均在服务端执行，避免仅过滤当前页造成误导。
3. 技术实现
3.1 数据与迁移
Alembic 版本：20260823_0056。
新增表：
- playbook_impact_analysis_jobs：持久化异步任务、租约、重试和结果；
- playbook_conflict_events：冲突主账本、负责人、SLA 和结论；
- playbook_conflict_event_history：创建、指派、逾期和结案时间线。
notifications 表新增定向收件人、动作链接和资源定位字段。运行时 schema-check 已将全部 Playbook 治理表及 P1-04.5 关键字段纳入部署自检，漏跑迁移时会明确报错。
3.2 后端与 Worker
新增 manage_playbook_conflict 权限，管理员、法务和审批人可处理冲突；普通成员无权访问治理账本。冲突记录在候选生成、组合校验和候选采用路径自动触发，HTTP 409 的 blocker 也会在业务事务回滚后单独持久化。
新增独立 playbook_governance_worker，负责：
- 领取和执行异步影响分析；
- 对失败任务释放租约并按上限重试；
- 扫描 SLA 逾期并生成时间线和定向通知。
Compose 已增加对应 Worker 服务和运行参数示例。
新增接口：
- POST /api/v1/enterprise-playbook/rules/impact-analysis/jobs；
- GET /api/v1/enterprise-playbook/rules/impact-analysis/jobs/{job_id}；
- GET /api/v1/enterprise-playbook/conflict-events；
- GET /api/v1/enterprise-playbook/conflict-events/assignees；
- POST /api/v1/enterprise-playbook/conflict-events/{event_id}/assign；
- POST /api/v1/enterprise-playbook/conflict-events/{event_id}/resolve；
- GET /api/v1/enterprise-playbook/conflict-events/{event_id}/history。
关系图和冲突看板接口同步扩展分页、焦点和 SLA 指标。
3.3 前端
企业 Playbook 管理页升级冲突运营视图：
- 状态、严重程度、负责人、SLA 和关键词筛选；
- 事件卡片、负责人选择、SLA 重置、处理/忽略结论；
- 操作历史时间线和通知深链接高亮；
- 待处理、逾期、即将到期、未指派指标；
- 异步影响分析提交、轮询和失败提示；
- 大图分页、搜索、关系筛选和焦点邻域。
通知中心新增 Playbook 指派、逾期和规则审批通知样式，并提供“前往处理”动作。
4. Chrome 登录态 UAT 证据
工作空间：uat-playbook-20260823
账号：uat.legal.20260823@example.test
角色：管理员/法务治理账号
4.1 冲突生命周期与通知
首次进入冲突运营台后，系统从既有候选 playbook-candidate-c73bbb2b4322 幂等回填 4 个待处理事件。初始看板为：待处理 4、逾期 0、即将到期 0、未指派 4。
对事件 playbook-conflict-73bfa8408f3a 完成真实页面操作：
- 指派给“UAT 法务”，SLA 重置为 1 小时；
- 状态由 open 变为 in_progress，并进入即将到期；
- 通知中心出现“Playbook 冲突治理事项已指派”；
- 点击“前往处理”回到冲突运营台并高亮原事件；
- 填写复核结论后结案，状态变为 resolved；
- 历史完整展示 created → assigned → resolved。
结案后看板更新为待处理 3、未指派 3。整个流程未修改任何合同正文。
4.2 异步影响分析
创建但未提交发布的规则草案“UAT P1045 异步影响任务验证”，完成 dry-run 并确认上下文边界和连续标点预警。页面异步分析成功：
- dry-run 证据：playbook-dry-run-82ccdc5c2ff1；
- 任务：playbook-impact-job-ce5b07f05ab5；
- 状态：succeeded；
- 执行次数：1；
- 执行耗时：28ms；
- 风险等级：medium；
- 字段变化：11；
- 受影响审查、合同和候选：均为 0。
UAT 未点击提交变更，因此生效规则仍为 6 条、待审批申请仍为 0，证明影响分析不会隐式发布规则。
4.3 关系图
真实租户图包含 6 个节点、3 条关系。搜索“UAT P1044”时服务端仅返回匹配规则和直接邻居，共 2/6 个节点；焦点规则能够查看邻域和入站/出站数量，全局删除保护数量保持为 2。
自动化大图场景另以 13 个节点、12 条边、每页 5 个节点验证分页、truncated 元数据和焦点邻域，确认后端不会把全量图强制下发给浏览器。
5. 验证结果
- P1-04.5 专项、既有治理、授权、租户隔离、合同工作流及运行时结构检查后端测试：112/112 通过；
- 前端完整测试：41/41 通过；
- Python 编译：通过；
- TypeScript 类型检查：通过；
- Next.js 生产构建：通过，共 123 个页面/路由；
- OpenAPI YAML：79 个路径、123 个 schema，解析通过；
- FastAPI 运行时 OpenAPI：159 个路径、248 个 schema；
- Alembic 当前版本：20260823_0056 (head)；
- 运行时 schema-check：核心表、P1-04.5 字段与 Alembic 版本均通过；
- 本地 schema-check 总状态仅因开发环境关闭 anti-abuse 为 warning，不涉及本阶段结构或迁移失败；
- Contract API、Contract Web、AI API 与 Playbook Governance Worker 均正常运行；
- git diff --check：通过，仅有仓库既有的 LF/CRLF 转换提示。
6. 已知边界与下一阶段建议
- 当前治理通知为站内通知，尚未提供邮件、企业微信、钉钉、Slack 或 webhook 适配器。
- SLA 采用严重程度默认值并支持单事项覆盖，尚未提供租户级 SLA 策略、工作日历和节假日顺延。
- 当前数据库任务队列具备持久化、租约和重试；超高吞吐租户可在保持任务契约不变的前提下迁移至 Redis Streams、RabbitMQ 或 Kafka，并增加死信队列和队列可观测性。
- 关系图已具备服务端分页和焦点邻域，但数千节点场景仍可增加社区聚类、关系折叠和 WebGL 渲染。
- 既有候选回填事件的创建人只能使用原候选中保存的展示值；后续新事件和所有处理动作均记录真实用户标识。
- 下一阶段建议进入 P1-04.6：租户级 SLA 策略与工作日历、外部通知适配器、冲突根因与规则优化建议、任务队列可观测/死信处理、超大关系图聚类。