yuqei
1d85329a6a
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 9m12s
Build and Test Quality Gate / Isolated Alibaba and Tencent KMS gateway (pull_request) Failing after 4m53s
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 24m55s
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 8m42s
6.6 KiB
6.6 KiB
P1-04.3 企业 Playbook 发布前试运行、规则关系与组合冲突交付报告
日期：2026-08-23
状态：已实现、已迁移、已通过自动化验证与 Chrome 隔离 UAT
1. 本阶段目标与结论
本阶段完成以下五项能力：
- 规则发布前样本文本 dry-run，并返回可核验的发布令牌；
- 标点碰撞、上下文边界、样本未命中、兜底文本重复引入禁用表述等预警或阻断；
- 租户规则的依赖与互斥关系配置、持久化、版本化和快照固化；
- 组合候选生成前的依赖、互斥、文本命中重叠与替换链式触发分析，并返回结构化冲突解释；
- 合同候选差异从整行着色升级为中英文语义分段后的词级/局部增删高亮。
结论：P1-04.3 已达到可进入下一阶段的验收标准。发布和组合生成均由服务端重复校验，前端不是唯一防线；发生阻断时不会生成候选版本，也不会修改合同正文。
2. 产品与流程设计
2.1 发布前检查门禁
管理员在发布规则前必须填写脱敏样本文本并运行检查。结果同时展示：
- 样本原文与执行后预览；
- 禁用表述命中次数；
- blocker、warning、info 分级问题；
- 每个问题的原因和修复建议；
- 警告逐项确认状态。
含兜底文本的启用规则只有在以下条件全部满足时才能发布：
- dry-run 无 blocker；
- dry-run 令牌与当前规则、关系和样本文本完全一致；
- 所有 warning 已明确确认。
规则匹配值、兜底文本或依赖/互斥关系发生修改时，同一门禁也适用于新版本 PATCH 发布，避免 API 客户端绕过页面。
2.2 规则关系
每条规则支持：
depends_on_rule_ids：依赖规则；mutually_exclusive_rule_ids：互斥规则。
发布阶段阻断未知引用、自引用、依赖/互斥语义矛盾、反向矛盾和依赖环。审查完成后，这些关系随规则版本写入 Playbook 快照，后续规则修改不会改变历史决策证据。
2.3 组合冲突解释
组合候选生成前会分析：
- 依赖规则未命中；
- 可执行依赖规则被跳过；
- 互斥规则被同时采用；
- 两条禁用规则命中范围相同或包含重叠；
- 一条兜底文本引入另一条已选规则的命中表述；
- 运行时上下文边界和连续标点风险。
blocker 返回 HTTP 409 与结构化 issues，不创建候选版本；warning 写入候选、版本元数据和审计事件，在差异审阅中持续展示。
2.4 词级差异
差异算法先按句号、分号、换行等语义边界对长合同分段，再对变更段执行中英文分词 LCS。这样既保留远距离未改正文，也能将替换范围收敛到具体词语和标点；极端大段文本仍有复杂度上限和安全回退。
3. 技术实现
3.1 后端与数据模型
- 新增
POST /api/v1/enterprise-playbook/rules/dry-run； - 规则创建和实质性更新使用 SHA-256 dry-run 令牌作为发布证据；
approval_rules新增依赖和互斥 JSON 字段；- 迁移版本：
20260823_0054； - 规则命中快照新增依赖和互斥关系；
- 组合冲突使用结构化错误返回并在候选元数据中保留非阻断预警；
- OpenAPI 手工契约和运行时 schema 已同步。
3.2 前端
- 企业 Playbook 管理页新增关系选择器、样本输入、dry-run 结果、警告确认和发布门禁；
- 规则清单展示依赖/互斥关系；
- 组合候选面板展示 blocker/warning 的原因与处理建议；
- 差异对话框新增“原正文 / 组合候选”双栏局部词级高亮；
- 新增长合同远距离变更回归测试，防止退化为整段着色。
4. Chrome 隔离 UAT 证据
工作空间：uat-playbook-20260823
账号：uat.legal.20260823@example.test
合同：contract-13b67d8e4ea8（UAT P1-04.3 规则组合冲突合同）
4.1 规则与关系
approval-rule-73410de1f68f：UAT P1043 禁止自动续约；依赖approval-rule-711b817a3ac4；approval-rule-6d731bd4f871：UAT P1043 禁止强制续约；互斥approval-rule-73410de1f68f。
Chrome 页面真实识别并展示：
- 上下文边界警告；
- 标点碰撞警告；
- 发生警告时发布按钮禁用；
- 逐项确认后发布成功；
- 发布后的规则清单正确显示依赖和互斥关系。
4.2 快照与冲突
- 审查任务：
review-949afaccde84； - 快照：
playbook-snapshot-949afaccde84； - 快照摘要：
f284e78edcd2862a16eb3d147d966e69a256a61b19edb140243abef9e8a6863e； - 命中 4 条企业规则，可用兜底 4 条。
验证结果：
- 同时采用两条互斥续约规则：HTTP 409，页面解释“不能同时写入一个候选版本”，无候选生成；
- 跳过依赖规则但采用被依赖规则：HTTP 409，页面解释“依赖的可执行规则被跳过”，无候选生成；
- 恢复依赖规则并跳过互斥规则：成功生成组合候选。
4.3 候选与差异
- 候选：
playbook-candidate-c73bbb2b4322； - 候选版本：
version-4986d773cecb； - 状态：
candidate，未采用； - 决策：采用 3 条、跳过 1 条；
- 页面持续展示 4 条运行时上下文/标点预警；
- 长合同差异产生 6 个局部新增高亮和 6 个局部删除高亮；
- 单个新增/删除高亮最大长度为 9/7 字，不再整段着色；
- 当前合同正文未被覆盖，候选保留供后续人工审阅。
5. 验证结果
- Python 编译：通过；
- P1-04.3 后端单元测试：3/3 通过；
- 租户隔离、版本更新与 dry-run 发布门禁集成测试：通过；
- 组合候选创建、撤销、安全采用回归测试：通过；
- 审查工作器与规则快照回归测试：通过；
- 前端完整测试：41/41 通过；
- 词级差异专项测试：4/4 通过；
- TypeScript 类型检查：通过；
- Next.js 生产构建：通过，共 115 个路由；
- 运行时 OpenAPI 与 YAML 解析：通过；
- Alembic 当前版本：
20260823_0054 (head)； - Contract API、Review Worker 与 Contract Web 已保持运行。
6. 已知边界与后续建议
- 当前 warning 允许管理员在理解风险后确认发布，这是治理告警而非绝对禁止；企业可在下一阶段增加“特定 warning 必须双人复核”的租户策略。
- 当前依赖/互斥关系通过规则 ID 建模；下一阶段可增加关系图、影响范围查询和删除前引用检查。
- 对超长且缺少标点/换行的单段文本，差异算法会触发复杂度安全回退；可继续引入 Myers diff 或后台异步差异服务。
- 建议下一阶段进入 P1-04.4：规则变更影响分析、关系图与删除保护、双人发布审批、历史 dry-run 证据查询，以及冲突处理运营看板。