yuqei
1d85329a6a
8.3 KiB
P1-04.4 企业 Playbook 影响分析、双人审批与运营治理交付报告
日期：2026-08-23
状态：已实现、已迁移、已通过自动化验证与 Chrome 双账号隔离 UAT
1. 本阶段目标与结论
本阶段完成以下五项能力：
- 规则新增、修改、启停和删除前的租户级影响分析；
- 依赖/互斥关系图、入站引用识别和删除保护；
- 发起人与审批人分离的双人发布审批，审批时重新校验影响与并发版本；
- 可按规则、是否可发布和问题代码查询的历史 dry-run 证据；
- 面向运营的候选冲突、预警、未解决事项和高频规则看板。
结论：P1-04.4 已形成“dry-run 证据 → 影响分析 → 变更申请 → 独立审批 → 原子发布 → 历史查询/运营复盘”的治理闭环。旧的直接写规则接口默认关闭，前端或普通 API 客户端无法绕过双人审批；审批失败、影响范围漂移或基础版本变化时均不会修改生效规则。
2. 产品与流程设计
2.1 变更影响分析
影响分析覆盖新增、修改、启用、停用和删除，并返回：
- 字段级变更数量；
- 直接依赖方与互斥引用方；
- 历史审查命中数和受影响合同数；
- 活跃候选版本数；
- 待处理变更数；
- 删除保护原因；
- low、medium、high、critical 风险等级；
- 用于审批阶段防漂移复核的影响摘要。
删除操作在存在入站依赖、互斥引用或相关待审批变更时失败关闭，不允许形成悬空关系。
2.2 双人发布审批
管理员先取得 dry-run 证据，确认全部 warning，再运行影响分析并提交变更申请。提交后生效规则保持不变。
审批人必须具备独立审批权限，且不得与发起人相同。审批事务会再次检查：
- dry-run 证据是否对应同一规则定义；
- warning 是否已逐项确认；
- 影响摘要是否发生变化；
- 被修改规则的基础版本是否仍一致；
- 依赖、互斥和删除保护是否仍满足。
检查全部通过后才在同一事务中创建、更新或删除规则，并写入审批决定。拒绝操作只关闭申请，不改变规则。
2.3 关系图与历史证据
管理端将生效规则展示为关系图：依赖使用实线，互斥使用红色虚线；节点显示版本、状态、入站引用数和删除保护状态。图和影响分析均由服务端根据当前租户数据计算，避免只依赖前端缓存。
dry-run 证据保存 SHA-256 摘要、脱敏截断片段、问题代码、可发布状态、规则定义摘要、操作者和时间。系统不保存完整样本文本，降低合同内容进入治理日志的隐私风险。
2.4 冲突运营看板
看板聚合当前租户的：
- 候选总量、冲突候选量、含预警候选量和未解决量；
- blocker、warning 与运行时问题代码分布；
- 高频命中规则排行；
- 最近候选及其状态、预警数和创建时间。
看板使用已持久化候选和组合冲突结果，帮助法务运营识别需要优化的高频规则和文本边界问题。
3. 技术实现
3.1 后端与数据模型
- 新增 playbook_dry_run_evidence 表，持久化隐私最小化的试运行证据；
- 新增 playbook_rule_change_requests 表，保存规则草案、影响摘要、基础版本、发起人、审批人和决定；
- Alembic 迁移版本：20260823_0055；
- 新增 approve_playbook_rule 能力，管理员和审批人可审批，但审批人不因此获得直接管理规则权限；
- 直接 POST/PATCH/DELETE 规则接口默认返回 four_eyes_workflow_required，仅测试夹具可显式开启；
- 生产/预发布配置检查会阻止误开启直接变更旁路；
- OpenAPI 手工契约与 FastAPI 运行时契约已同步。
新增治理接口：
- POST /api/v1/enterprise-playbook/rules/impact-analysis；
- GET /api/v1/enterprise-playbook/relationship-graph；
- GET/POST /api/v1/enterprise-playbook/rule-change-requests；
- POST /api/v1/enterprise-playbook/rule-change-requests/{request_id}/approve；
- POST /api/v1/enterprise-playbook/rule-change-requests/{request_id}/reject；
- GET /api/v1/enterprise-playbook/dry-run-evidence；
- GET /api/v1/enterprise-playbook/conflicts/dashboard。
3.2 前端
企业 Playbook 管理页升级为五个治理视图：
- 规则与影响：完成 dry-run、影响分析和变更申请三步流程；
- 双人发布：展示待审批队列、风险、证据和审批/拒绝操作；
- 关系图：展示依赖、互斥、入站引用和删除保护；
- Dry-run 证据：支持规则、可发布状态和问题代码筛选；
- 冲突看板：展示指标、问题分布、高频规则和最近候选。
同一发起人查看自己的申请时审批按钮明确禁用；独立审批账号仅能进入治理页面和处理审批，不显示发起规则变更表单。
4. Chrome 双账号隔离 UAT 证据
工作空间：uat-playbook-20260823
发起账号：uat.legal.20260823@example.test
审批账号：uat.approver.20260823@example.test
4.1 新规则双人发布
发起人创建“UAT P1044 禁止单方调价”草案，匹配“甲方有权单方调整价格”，兜底为“价格调整须经双方书面确认。”，并依赖“UAT P1043 禁止自动续约”。
- dry-run 证据：playbook-dry-run-cc47c34e92bd；
- 发现并确认：punctuation_collision；
- 影响等级：medium；
- 影响摘要前缀：378f7e161d98；
- 变更申请：playbook-change-91987c70a429；
- 审批后规则：approval-rule-08e4e1a5f74c，版本 1。
验证结果：发起后生效规则仍为 5 条，发起人无法自批；切换独立审批账号后审批成功，生效规则变为 6 条，待审批数量归零。申请记录保留不同的 requested_by 与 decided_by。
4.2 关系图与删除保护
审批后关系图包含 6 个节点、3 条关系边。“UAT P1043 禁止自动续约”存在 2 条入站引用并显示删除保护。
对规则 approval-rule-73410de1f68f 执行删除影响分析得到：
- deletion_protected = true；
- 风险等级 critical；
- 历史审查命中 1 次；
- 活跃候选 1 个；
- 阻断原因包含 rule_has_dependents 与 rule_has_mutual_references。
4.3 历史证据与冲突看板
历史证据页正确展示脱敏样本文本片段、完整 SHA-256、问题代码与发布时间，并可按 punctuation_collision 筛出本次证据。
冲突看板 UAT 快照：
- 候选总量：3；
- 冲突候选：0；
- 含预警候选：1；
- 未解决：0；
- runtime_punctuation_collision：3；
- runtime_context_boundary：1；
- 高频规则第一名：“UAT P1043 禁止自动续约”，命中 2 次。
上一阶段候选 playbook-candidate-c73bbb2b4322 仍为 candidate，候选版本 version-4986d773cecb 未被采用；本阶段发布规则未静默覆盖任何合同正文。
5. 验证结果
- P1-04.4 治理专项、合同工作流、授权和租户隔离后端测试：94/94 通过；
- 前端完整测试：41/41 通过；
- Python 编译：通过；
- TypeScript 类型检查：通过；
- Next.js 生产构建：通过，共 120 个页面/路由；
- OpenAPI YAML：72 个路径、116 个 schema，解析通过；
- FastAPI 运行时 OpenAPI：152 个路径、241 个 schema，新治理接口齐全；
- Alembic 当前版本：20260823_0055 (head)；
- 旧直接变更旁路探测：HTTP 409，默认关闭；
- Contract API、Contract Web、AI API 健康检查均为 HTTP 200；
- git diff --check：通过，仅显示仓库既有的 LF/CRLF 转换提示。
6. 已知边界与后续建议
- 当前冲突看板聚合已创建候选及其持久化问题；在候选创建前即被 blocker 拒绝的尝试尚未形成独立冲突事件。建议 P1-04.5 增加冲突事件账本、负责人、处理状态和 SLA。
- 当前影响分析同步扫描租户历史审查与候选。超大租户应增加物化统计、增量索引或异步深度扫描，页面先返回快速影响摘要。
- 审批时历史命中或候选数量发生变化会使影响摘要失效并要求重新提交，这是有意的失败关闭策略；后续可增加“一键刷新申请”以降低运营成本。
- 关系图当前采用轻量 SVG 布局。规则规模达到数百条后，建议升级为分层布局、搜索聚焦、关系折叠和异常子图筛选。
- 下一阶段建议进入 P1-04.5：冲突事件全生命周期、运营 SLA、治理通知、影响分析异步化及大规模关系图优化。