ai-contract-platform/project-docs/V2-P1-04-enterprise-playbook-implementation-2026-08-23.md

# V2 P1-04 企业 Playbook 实施与验收报告

> 日期：2026-08-23  
> 范围：租户级禁用条款、金额阈值、兜底文本、审批规则、企业规则命中解释  
> 状态：已实现、已迁移、已通过自动化与真实浏览器验收

## 1. 交付结论

P1-04 已形成从“管理员配置”到“合同审查命中”再到“审批留痕”的可运行闭环：

1. 管理员或法务可在企业 Playbook 中配置禁用条款、金额阈值、合同类型和风险等级规则。
2. 每条规则支持企业兜底文本、命中风险级别、执行优先级、启停状态和递增版本。
3. 规则按当前工作空间（tenant）隔离，跨租户不可见、不可修改。
4. AI 审查完成时固化命中规则快照，包含规则 ID、规则名称、版本、原因、命中原文、页码、兜底文本和是否要求审批。
5. 合同详情与管理端审查结果均展示企业规则命中解释。
6. 提交审批时重新基于合同当前正文和金额判断规则，并把触发规则写入审批时间线。
7. 历史审查保存规则快照；后续停用、修改或删除规则不会改写历史命中证据。

## 2. 产品与业务设计

### 2.1 单一规则模型

本阶段复用了已有租户级 `approval_rules`，将其扩展为企业 Playbook 规则，而没有新增第二套审批规则引擎。这样可以避免管理员在两个入口维护互相冲突的金额阈值与审批条件。

规则类型：

- `prohibited_clause`：正文包含租户禁用表述。
- `amount`：合同金额命中 `gt/gte/lt/lte` 阈值。
- `contract_type`：合同类型等于或包含规则值。
- `risk_level`：合同或审查风险等级命中规则值。

所有当前规则动作统一为 `require_approval`。规则命中不会替代法务判断，而是把企业政策、兜底文本和审批要求显式呈现给业务、法务和审批人。

### 2.2 历史可解释性

审查结果不只保存规则 ID，而是保存当次运行的完整命中快照。管理员以后修改规则时，旧审查仍可回答：

- 当时命中了哪条规则；
- 使用的是哪个版本；
- 命中正文和页码是什么；
- 为什么命中；
- 当时给出的兜底文本是什么；
- 是否要求审批。

### 2.3 审批衔接

用户提交或重新提交审批时，系统根据合同当前内容重新匹配启用规则，并把规则名称写入审批时间线。该设计保留用户主动提交的主流程，同时补齐“为什么需要审批”的解释。

## 3. 技术实现

### 3.1 数据库迁移

Alembic 迁移 `20260823_0050`：

- `approval_rules.fallback_text`
- `approval_rules.risk_level`
- `approval_rules.priority`
- `approval_rules.version`
- `(tenant_id, priority)` 索引
- `review_tasks.playbook_matches` JSON 快照

PostgreSQL 当前版本已升级为 `20260823_0050 (head)`；另使用全新 SQLite 数据库从首个迁移完整升级至 0050，验证迁移链可重建。

### 3.2 后端

- 扩展企业规则领域模型、创建和更新请求。
- 修正金额操作符边界：`gt` 与 `gte`、`lt` 与 `lte` 分别按严格/包含边界执行。
- 新增统一企业规则匹配与解释函数。
- 审查 worker 在租户上下文中读取启用规则并生成命中快照。
- 审查结果持久化 `playbook_matches`。
- 规则更新自动递增版本。
- 保留旧 `/approval-rules` API，同时新增语义化 `/enterprise-playbook/rules` API，保证兼容。
- 提交审批和重新提交审批自动附加企业规则触发原因。

### 3.3 前端

新增 `/admin/playbook`：

- 规则总览指标；
- 新建禁用条款、金额、合同类型、风险等级规则；
- 配置兜底文本、风险等级、优先级；
- 启用、停用、删除规则；
- 展示规则版本与“要求审批”动作；
- 管理员和法务角色可访问。

合同详情和管理端审查结果新增企业 Playbook 命中解释区域，突出规则版本、原因、原文、页码、兜底文本和审批要求。

## 4. 验收证据

### 4.1 真实浏览器旅程

使用已登录 Chrome 超级管理员会话完成：

1. 打开 `/admin/playbook`，确认默认金额和高风险规则正常读取。
2. 通过页面发布规则“禁止无上限赔偿责任” v1：
   - 禁用表述：`承担全部且无限责任`
   - 风险：高
   - 优先级：10
   - 配置了企业标准责任上限兜底文本
3. 创建验收合同并发起真实 AI 审查。
4. 合同详情显示 3 条命中：禁用条款、金额大于等于 500000、高风险。
5. 禁用条款显示第 1 页命中原文、规则 v1 和兜底文本。
6. 点击提交审批，合同进入待审批；审批时间线显示禁用条款与金额规则的触发原因。

验收数据：

- 合同：`contract-b3e11a3ddb59`
- 审查任务：`review-2ef6ad438571`
- AI Trace：`run-24db2a559682`
- 审查结果：`succeeded / high / 3 条企业规则命中`

### 4.2 自动化与构建

- 后端合同工作流、服务端授权、租户隔离：89 个用例通过。
- P1-04 针对性用例：规则字段与版本、租户隔离、worker 命中快照、审批时间线解释通过。
- 前端：11 组、37 个检查通过。
- TypeScript：`tsc --noEmit` 通过。
- Next.js 生产构建：114/114 页面生成通过。
- Python 源码编译检查通过。
- PostgreSQL 迁移：0050 head。
- 空 SQLite 完整迁移链：0050 head。
- OpenAPI 已包含企业 Playbook 列表/创建与单规则更新/删除路径。
- 健康检查：Web 3000、Contract API 8100、AI API 8101 均为 HTTP 200。

## 5. 当前边界与后续建议

本阶段的兜底文本已完成配置、版本固化和审查展示，但未直接替换合同原文。这样避免自动改写法律文本；当前用户仍可使用既有“应用条款”能力或手工确认后编辑正文。

建议下一迭代按以下顺序推进：

1. P1-04.1：兜底文本一键生成修订草案，必须创建合同新版本并记录操作者，禁止静默覆盖正文。
2. P1-04.2：为规则增加生效时间、发布审批、冲突检测和模拟命中预览。
3. P1-04.3：将命中率、误报反馈、被采纳兜底文本和审批耗时接入产品分析。
4. P1-04.4：为合同类型、金额币种和组织层级增加更精细的适用范围。
5. 产品层面优先把现有英文默认规则名称改为企业可理解的中文名称，降低管理员首次配置成本。

## 6. 关键文件

- 后端领域模型：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/domain.py`
- 规则匹配与解释：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/workflow_helpers.py`
- 规则持久化：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/persistence/support.py`
- 审查快照持久化：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/persistence/review_tasks.py`
- 审查 worker：`yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/review_worker.py`
- 数据库迁移：`yuqei-contract-platform/services/contract-api/migrations/versions/20260823_0050_add_enterprise_playbook.py`
- OpenAPI 合同：`yuqei-contract-platform/packages/contract-openapi/openapi.yaml`
- 管理页面：`yuqei-contract-platform/apps/contract-web/src/app/admin/playbook/page.tsx`
- 合同命中解释：`yuqei-contract-platform/apps/contract-web/src/app/contracts/[id]/page.tsx`
- 管理端审查结果：`yuqei-contract-platform/apps/contract-web/src/app/admin/review-results/page.tsx`