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
113 lines
7.1 KiB
Markdown
113 lines
7.1 KiB
Markdown
# 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. 已知限制与下一步
|
||
|
||
1. 当前禁用条款采用精确片段替换；规则管理员若填写整句而命中项只是句中片段，替换后可能出现语法不顺。配置页已增加提示，下一步建议增加“替换前后 diff 预览 + 人工确认”。
|
||
2. 单次执行目前按快照整体处理。建议增加逐条勾选、跳过原因和每条命中的执行结果，便于复杂合同分批修复。
|
||
3. 回退后需重新发起审查验证风险是否消除；后续可增加“执行成功后自动创建待确认审查任务”，但不应在无人确认时自动提交审批。
|
||
4. 若需求确为水务行业的“水价规则”，下一阶段应先建立独立计价领域模型和金样测试，再复用本轮快照、幂等、冲突与审计框架。
|
||
|
||
## 8. 发布判断
|
||
|
||
本轮功能满足受控 UAT 和小范围企业试点所需的证据留存、租户隔离、权限隔离、幂等执行与冲突保护。正式开放自动改写前，建议把“diff 预览 + 人工确认”设为发布门槛，并持续保留文件合同只读、人工接管的安全边界。
|