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
7.1 KiB
7.1 KiB
V2 P1-04 企业 Playbook 聚合快照、回退执行器与隔离 UAT 验收记录
日期：2026-08-23
结论：通过，可继续进入受控试运行。
1. 范围与术语说明
本轮按 P1-04 企业 Playbook 的既定范围推进：租户级禁用条款、金额阈值、兜底文本、审批规则及命中解释。
需求中的“水价规则”在现有代码、数据模型和既有审查报告中没有对应业务对象，因此本轮按“企业 Playbook 规则”理解，落地为通用的规则聚合快照和安全回退执行器。若“水价规则”确指水务行业的阶梯水价、区域价格或结算公式，仍需另行补充价格区间、计量单位、生效日期、地区和计算方式等领域模型，不能直接用文本替换代替计价引擎。
2. 本轮交付
2.1 不可变聚合快照
- 审查完成时固化命中的规则版本、规则类型、风险等级、命中原因、兜底文本、审批要求和优先级。
- 生成快照 ID、快照摘要和合同正文哈希，后续规则配置变更不影响已完成审查的证据。
- 聚合结果包含命中数、最高风险、可用兜底数、是否需要审批和是否满足自动执行前置条件。
- 合同详情页与管理端审查结果页均展示快照摘要、聚合指标和命中解释。
2.2 安全回退执行器
- 执行前校验租户、合同状态、审查状态、快照摘要、正文哈希和编辑权限。
- 禁用条款规则仅精确替换快照中记录的命中表述；其他规则使用追加式企业标准文本。
- 成功后生成合同新版本、审计事件和独立执行台账，并把下一步引导改为“重新发起审查验证企业兜底文本”。
- 使用幂等键防止重复写入；相同请求安全重放时返回原执行结果。
- 正文、快照或状态不一致时不修改合同，记录冲突证据并转入人工接管。
- 文件审查暂不允许自动改写原始附件，避免把解析文本错误写回不可逆文件。
2.3 权限与界面
- 只有具备合同编辑权限的人员可看到和执行“应用企业兜底文本”。
- 只读审批人仍可查看快照、命中解释和历史执行证据，但不能编辑、重提或执行兜底。
- Playbook 管理页已提示：禁用条款的兜底文本必须是可直接替换并嵌入原文的片段。
- 历史人工
action_hint只在待提交、审查中和已退回状态生效，不再覆盖已批准或已归档的终态提示。
3. 隔离 UAT 证据
3.1 环境与账号
- 隔离租户：
uat-playbook-20260823（Playbook 隔离 UAT） - 法务/租户管理员：
uat.legal.20260823@example.test - 独立审批人：
uat.approver.20260823@example.test - 两个账号为独立用户，未共享浏览器身份；报告不记录密码。
3.2 完整合同状态流
合同 contract-d8ba1d8af7a3 已由两个账号依次完成：
draft -> reviewing -> approval_pending -> rejected -> modified/version 2 -> approval_pending -> approved -> archived
验证结果：
- 法务账号可编辑、发起审查、提交审批、按退回意见修改并重新提交。
- 审批账号可拒绝或批准，但不能编辑合同、重新提交或代替法务执行兜底。
- 已归档合同最终显示“归档完成”，历史人工提示不会覆盖终态。
3.3 聚合快照与回退执行
- 规则：
UAT 禁止无限责任，版本 1，高风险，优先级 1。 - 新合同：
contract-fc04e78469a9。 - 审查任务：
review-494e560732aa。 - AI 运行：
run-93da6ac49cbd。 - 快照：
playbook-snapshot-494e560732aa，摘要前缀55b200bb5c86。 - 聚合结果：1 条命中、最高风险 high、1 条可用兜底、满足执行前置条件。
- 成功执行：
playbook-fallback-ee1a6d94a00e。 - 执行后合同正文已替换，生成版本 2，并显示“兜底已应用”和重新审查提示。
- 重放同一执行请求返回原执行记录，没有重复创建版本。
- 审批账号可见快照和执行证据，但不可见执行、应用条款或编辑按钮。
4. 技术实现位置
- 聚合快照与领域模型：
yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/enterprise_playbook.py - SQL 安全执行与台账：
yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/sqlalchemy_playbook_fallback_orchestration.py - 审查完成时固化快照：
yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/persistence/review_tasks.py - 状态提示与人工提示优先级：
yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/contract_display.py - 数据库迁移：
yuqei-contract-platform/services/contract-api/migrations/versions/20260823_0051_add_playbook_snapshots_and_fallbacks.py - API 契约：
yuqei-contract-platform/packages/contract-openapi/openapi.yaml - 合同详情与执行按钮：
yuqei-contract-platform/apps/contract-web/src/app/contracts/[id]/page.tsx、apply-playbook-fallback-button.tsx - 管理端规则配置：
yuqei-contract-platform/apps/contract-web/src/app/admin/playbook/page.tsx
5. 自动化与构建结果
- 后端核心回归：98 项通过，覆盖合同状态机、租户隔离和代理权限。
- 前端测试：全部通过。
- TypeScript 类型检查：通过。
- Python
compileall：通过。 - OpenAPI YAML 解析：通过。
- Next.js 生产构建：通过，114 个页面路由完成构建。
- PostgreSQL 迁移：
20260823_0051 (head)。 - 迁移已在全新 SQLite 数据库从 0 升级到 head 验证，并对本地
create_all先建表场景做了可重入保护。
非阻断告警：测试环境仍有 Starlette TestClient 的上游弃用提示，以及 Windows 下 .pytest_cache 已存在导致的缓存写入提示，均不影响测试结果或运行功能。
6. 当前运行状态
- Web：
http://127.0.0.1:3000，监听中。 - Contract API：
http://127.0.0.1:8100，启用 Web 代理鉴权，监听中。 - AI API：
http://127.0.0.1:8101，监听中。 - Review Worker：运行中，已成功调用 AI 合同审查接口。
- Chrome 保留在合同
contract-fc04e78469a9的 UAT 验收页。
7. 已知限制与下一步
- 当前禁用条款采用精确片段替换；规则管理员若填写整句而命中项只是句中片段，替换后可能出现语法不顺。配置页已增加提示，下一步建议增加“替换前后 diff 预览 + 人工确认”。
- 单次执行目前按快照整体处理。建议增加逐条勾选、跳过原因和每条命中的执行结果，便于复杂合同分批修复。
- 回退后需重新发起审查验证风险是否消除；后续可增加“执行成功后自动创建待确认审查任务”，但不应在无人确认时自动提交审批。
- 若需求确为水务行业的“水价规则”，下一阶段应先建立独立计价领域模型和金样测试，再复用本轮快照、幂等、冲突与审计框架。
8. 发布判断
本轮功能满足受控 UAT 和小范围企业试点所需的证据留存、租户隔离、权限隔离、幂等执行与冲突保护。正式开放自动改写前，建议把“diff 预览 + 人工确认”设为发布门槛，并持续保留文件合同只读、人工接管的安全边界。