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
148 lines
6.6 KiB
Markdown
148 lines
6.6 KiB
Markdown
# P1-04.3 企业 Playbook 发布前试运行、规则关系与组合冲突交付报告
|
||
|
||
日期：2026-08-23
|
||
状态：已实现、已迁移、已通过自动化验证与 Chrome 隔离 UAT
|
||
|
||
## 1. 本阶段目标与结论
|
||
|
||
本阶段完成以下五项能力：
|
||
|
||
1. 规则发布前样本文本 dry-run，并返回可核验的发布令牌；
|
||
2. 标点碰撞、上下文边界、样本未命中、兜底文本重复引入禁用表述等预警或阻断；
|
||
3. 租户规则的依赖与互斥关系配置、持久化、版本化和快照固化；
|
||
4. 组合候选生成前的依赖、互斥、文本命中重叠与替换链式触发分析，并返回结构化冲突解释；
|
||
5. 合同候选差异从整行着色升级为中英文语义分段后的词级/局部增删高亮。
|
||
|
||
结论：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 条。
|
||
|
||
验证结果：
|
||
|
||
1. 同时采用两条互斥续约规则：HTTP 409，页面解释“不能同时写入一个候选版本”，无候选生成；
|
||
2. 跳过依赖规则但采用被依赖规则：HTTP 409，页面解释“依赖的可执行规则被跳过”，无候选生成；
|
||
3. 恢复依赖规则并跳过互斥规则：成功生成组合候选。
|
||
|
||
### 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. 已知边界与后续建议
|
||
|
||
1. 当前 warning 允许管理员在理解风险后确认发布，这是治理告警而非绝对禁止；企业可在下一阶段增加“特定 warning 必须双人复核”的租户策略。
|
||
2. 当前依赖/互斥关系通过规则 ID 建模；下一阶段可增加关系图、影响范围查询和删除前引用检查。
|
||
3. 对超长且缺少标点/换行的单段文本，差异算法会触发复杂度安全回退；可继续引入 Myers diff 或后台异步差异服务。
|
||
4. 建议下一阶段进入 P1-04.4：规则变更影响分析、关系图与删除保护、双人发布审批、历史 dry-run 证据查询，以及冲突处理运营看板。
|