ai-contract-platform/project-docs/V2-database-code-refactor-decision-2026-06-28.md

# AI 合同平台 V2 数据库与代码重构决策

日期：2026-06-28

## 结论

当前 V2 的总体方向是正确的：代码已经拆成合同平台、AI 中台、基础设施三块，文档和 compose 也已经把数据库目标收口为 `yuqei_contract`、`yuqei_ai`、`yuqei_ops` 三库。

但当前落地状态还没有达到“最佳长期方案”的要求，主要问题不是功能是否能跑，而是环境权威性、数据库边界、代码模块边界和模型长期可维护性还不够清晰。继续新增业务功能前，应该先做一轮非破坏性的治理和重构准备。

本轮不建议删除任何数据库，也不建议继续临时新建数据库。下一步应该先确定唯一权威 V2 环境，再迁移、验证、归档临时库。

## 已核验的当前状态

### 文档目标状态

V2 数据库最终边界：

| 数据库 | 归属 | 主要内容 | 连接变量 |
| --- | --- | --- | --- |
| `yuqei_contract` | `yuqei-contract-platform` | 合同、审批、附件元数据、审查任务业务结果、合同事件、模板/条款/规则管理 | `CONTRACT_API_DATABASE_URL` |
| `yuqei_ai` | `yuqei-ai-platform` | 模型配置、Prompt、知识库、RAG、向量、AI Trace、质量评测、配置执行 | `AI_PLATFORM_DATABASE_URL`、`YUQEI_WORKER_DATABASE_URL` |
| `yuqei_ops` | `yuqei-infra` | 发布记录、备份记录、运行审计、监控扩展预留 | 后续运维服务独立配置 |

这比 V1 的单库模型更合理。V1 中合同业务、AI、知识库、商业化、治理、发票、审批等全部堆在 `ai_contract_platform` 这类单体库里，不适合作为 V2 长期生产模型。

### 远端 192.168.3.90 当前状态

只读检查结果显示：

| 位置 | 数据库/环境 | 状态判断 |
| --- | --- | --- |
| 宿主机 PostgreSQL `5432` | `ai_contract_platform` | 旧版/历史单体库，47 张表，迁移头为 `20260619_0045`，有 `generated_contracts`，没有 V2 `contracts` |
| 宿主机 PostgreSQL `5432` | `yuqei_contract` | 临时 V2 合同测试库，12 张表，迁移头为 `20260628_0017`，有 `contracts` 和 `legal_change_impact_scans` |
| 宿主机 PostgreSQL `5432` | `yuqei_ai` | 不存在 |
| 宿主机 PostgreSQL `5432` | `yuqei_ops` | 不存在 |
| Docker smoke | `yuqei-contract-v2-smoke-*` | 容器和卷存在，但当前停止；Postgres 映射端口为 `15432`，卷为 `yuqei-contract-v2-smoke_postgres-data` |

因此不能把宿主机 `5432/yuqei_contract` 直接认定为完整 V2 数据库。它只是合同平台部分测试库，缺少 V2 目标中的 `yuqei_ai` 和 `yuqei_ops`。

## 当前设计问题

### 1. 数据库环境权威性不清

现在同时存在：

- V1/旧单体库：`ai_contract_platform`
- 临时 V2 合同测试库：`yuqei_contract`
- 停止状态的 V2 Docker smoke 环境

风险是开发者不知道本地/测试/准生产应该连哪一个库，后续迁移可能打到错误环境。最危险的不是“多了一个库”，而是没有一个明确登记表说明每个库的身份、用途、负责人、迁移头和是否允许写入。

### 2. 三库目标没有在宿主机 5432 上完整落地

宿主机只看到 `yuqei_contract`，没有 `yuqei_ai`、`yuqei_ops`。这说明如果当前本地后端连的是宿主机 5432，它只验证了合同 API 的一部分，没有验证 AI 中台和 worker 的真实 PostgreSQL 数据边界。

### 3. 本地 Contract API 示例仍默认 SQLite

`yuqei-contract-platform/services/contract-api/.env.example` 和 README 仍把 SQLite 放在默认示例里。SQLite 可以保留用于轻量单测，但对 V2 当前阶段来说，开发联调和验收应该默认指向 PostgreSQL，否则很容易出现“本地能跑，PostgreSQL 才暴露问题”的情况。

### 4. 健康检查不足以证明数据库结构正确

当前健康接口更多检查配置和后端类型，不足以证明：

- 连接的是不是预期数据库名。
- Alembic version 是否等于当前 head。
- 核心表是否存在。
- PostgreSQL 扩展 `pg_trgm`、`vector` 是否就绪。

这也是之前容易误判“后端已启动但模板/法律资产数据为空”的原因。

### 5. 合同平台代码模块过大

当前核心文件规模：

- `yuqei_contract_api/contracts.py`：约 7300 行。
- `yuqei_contract_api/main.py`：约 1500 行。

`contracts.py` 同时承载 Pydantic schema、SQLAlchemy model、内存仓储、SQLAlchemy 仓储、demo seed、模板生命周期、法律资产生命周期、文件、审批、审计、备份、权限、通知等多个领域。

这已经不适合继续叠功能。短期能跑，长期会让迁移、测试、审查和性能优化变慢。

### 6. AI 平台仓储也过于集中

当前核心文件规模：

- `yuqei_ai_platform_api/repository.py`：约 6100 行。
- `yuqei_ai_platform_api/main.py`：约 1200 行。

AI 平台已经有知识库、Prompt、Provider、AI Trace、质量闭环、worker runtime、pgvector 检索等能力，但仓储层仍集中在一个大文件里。继续扩展法规库、黄金样本、质量评测和运营后台时，应拆成独立领域模块。

### 7. 部分数据库模型仍偏 MVP

合同库仍有一些不适合长期作为事实字段的列：

- `status_label`
- `status_tone`
- `next_action`
- `next_actions`

这些更适合由 API serializer/BFF/前端根据状态和角色推导。数据库应保存事实状态，例如 `lifecycle_status`、`review_status`、`approval_status`、`signing_status`、`archive_status`。

`review_tasks.risk_items`、`citations`、`primary_sources`、法律影响扫描 payload 等 JSON 字段可以作为快照，但高频筛选、统计、排序和权限判断字段应逐步结构化。

### 8. 合同生命周期表还不完整

V2 已经补了模板、条款、规则、审查推荐、法律影响扫描等功能，但合同生命周期的长期模型还没有完全稳定：

- 缺少正式 `contract_versions` 表承载正文版本。
- 审批仍主要依赖 timeline，缺少 `approval_instances`、`approval_steps`、`approval_actions`。
- 合同正文仍在 `contracts.body_content`，后续应迁到版本表或对象存储快照。
- 软删除、创建人、更新人、部门、组织等字段还没有在全部核心表统一。

### 9. 安全与数据治理仍需硬化

需要继续补齐：

- PostgreSQL RLS 或至少数据库层租户隔离策略。
- 合同库与 AI 库使用不同账号和最小权限。
- Provider/OCR/API key 入库加密或改由密钥服务托管。
- 审计事件 append-only 约束和篡改检测。
- AI Trace 脱敏、保留周期、归档策略。

## 推荐的目标方案

### 数据库权威方案

推荐将 V2 数据库环境分成三类，避免混用：

| 环境 | 目的 | 推荐状态 |
| --- | --- | --- |
| 本地单测 | 快速单元测试 | 可继续 SQLite/fake repository，但只覆盖纯逻辑 |
| 本地/远端联调 | Codex 浏览器和开发调试 | 必须 PostgreSQL，连接明确登记的 V2 dev/smoke 三库 |
| 准生产 smoke | 发布前验收 | 使用 Docker smoke 环境或正式 staging PostgreSQL，必须同时存在 `yuqei_contract`、`yuqei_ai`、`yuqei_ops` |

当前最稳妥的选择：

1. 先把 `yuqei-contract-v2-smoke` Docker 环境启动并只读核验其三库状态。
2. 如果 smoke 卷中三库和迁移历史完整，将它登记为当前 V2 准生产 smoke 权威环境。
3. 宿主机 `5432/yuqei_contract` 标记为“临时合同测试库”，不要继续作为权威环境扩展。
4. `ai_contract_platform` 标记为“V1/旧单体历史库”，只读保留，用于资产映射和行为对照。
5. 若后续决定不用 Docker smoke，而改用宿主机 5432 作为正式 V2 dev/staging，则必须一次性补齐 `yuqei_contract`、`yuqei_ai`、`yuqei_ops` 三库和独立账号，再把 smoke 作为可重建环境。

### 代码重构目标结构

Contract API 建议拆分为：

```text
yuqei_contract_api/
  api/
    contracts.py
    files.py
    review_tasks.py
    templates.py
    legal_assets.py
    legal_fulltext.py
    approvals.py
    audit.py
    admin.py
  domain/
    contracts.py
    review.py
    templates.py
    legal_assets.py
    approvals.py
  persistence/
    models.py
    session.py
    repositories/
      contracts.py
      files.py
      review_tasks.py
      templates.py
      legal_assets.py
      audit.py
  services/
    contract_lifecycle.py
    template_lifecycle.py
    clause_recommendation.py
    legal_change_impact.py
    audit_integrity.py
  seed/
    demo_data.py
```

AI Platform 建议拆分为：

```text
yuqei_ai_platform_api/
  api/
    providers.py
    prompts.py
    knowledge.py
    ai_runs.py
    quality.py
    workers.py
  domain/
    providers.py
    prompts.py
    knowledge.py
    ai_runs.py
    quality.py
  persistence/
    models.py
    session.py
    repositories/
      providers.py
      prompts.py
      knowledge.py
      ai_runs.py
      quality.py
      workers.py
  services/
    retrieval.py
    trace.py
    quality_gate.py
    ingestion.py
```

拆分原则：

- API 层只负责路由、鉴权、参数和响应。
- service 层负责业务编排。
- repository 层只负责数据库读写。
- domain/schema 层不依赖 FastAPI。
- migration 只从 persistence models 或明确 migration 脚本演进，不从大杂烩文件隐式生成。

## 重构执行顺序

### Phase A：数据库环境治理

目标：先消除“连错库”的风险。

任务：

1. 新增 V2 数据库环境登记表，记录每个库的用途、连接入口、迁移头、是否权威、是否允许写入。
2. 新增只读检查脚本，能输出远端 DB 清单、表数量、Alembic head、核心表存在性。
3. 启动并核验 Docker smoke 环境，确认 `15432` 下是否存在 `yuqei_contract`、`yuqei_ai`、`yuqei_ops`。
4. 决定权威开发/准生产库。
5. 本地后端只连接权威 V2 PostgreSQL，不再用临时 SQLite 作为功能验收依据。

验收标准：

- 文档中明确唯一 V2 dev/smoke 权威库。
- `ai_contract_platform` 标记为旧库，不再作为 V2 写入目标。
- 临时 `5432/yuqei_contract` 有归属说明，未确认前不继续扩展。
- 健康/检查脚本能显示当前连接数据库名和迁移头。

### Phase B：运行时安全检查

目标：应用启动和健康检查能发现错误数据库。

任务：

1. Contract API 增加 `/api/v1/runtime/schema-check`。
2. AI Platform API 增加 `/api/v1/runtime/schema-check`。
3. 检查项包括数据库名、Alembic version、核心表、PostgreSQL 扩展。
4. staging/production 环境禁止 SQLite，禁止 auto create，禁止 demo seed。

验收标准：

- 连接旧 `ai_contract_platform` 时 schema check 必须报错。
- 连接缺表或迁移头落后的库时 schema check 必须报错。
- Docker smoke 健康检查从“服务 alive”升级为“服务 alive + schema ready”。

### Phase C：代码模块化拆分

目标：先拆结构，不改接口行为。

任务：

1. 将 `contracts.py` 中 SQLAlchemy model 移到 `persistence/models.py`。
2. 将 Contract API repository 按合同、文件、审查、模板、法律资产、审计拆分。
3. 将路由从 `main.py` 拆到 `api/*`，由 `create_app` 注册。
4. 将 AI Platform repository 按 Provider、Prompt、Knowledge、AI Run、Quality、Worker 拆分。
5. 保持现有 API path、响应结构和测试不变。

验收标准：

- 拆分后功能测试全通过。
- 单文件不再继续承载多个领域。
- 新增功能只能落到对应领域模块，不再向大文件继续堆。

### Phase D：数据库模型硬化

目标：把 MVP 表逐步收敛到生产模型。

任务：

1. 新增 `contract_versions`，合同正文版本化。
2. 新增正式审批模型：`approval_instances`、`approval_steps`、`approval_actions`。
3. 将 UI 展示字段从长期事实表中逐步迁出或转为派生字段。
4. 为核心表补齐 `tenant_id`、`created_by`、`updated_by`、`deleted_at`。
5. 将高频 JSON 查询字段结构化，JSON 只保留快照和扩展。
6. AI 库补齐 `tenant_id`、保留周期、归档策略和敏感字段加密策略。

验收标准：

- 合同列表、审批待办、统一搜索、AI Trace、知识库检索不依赖 JSON 全表扫描。
- 合同正文修改有版本历史。
- 审批动作可追溯到步骤、人员、时间、结果。
- 数据库字段表达事实，不表达 UI 文案。

### Phase E：V1 资产迁移策略

目标：吸收 V1 优秀资产，但不复制 V1 单体结构。

任务：

1. 模板、条款、规则、黄金样本、精选法律全文通过导入脚本迁入 V2 新模型。
2. 每类资产都保留 V1 source id、导入批次、版本、hash。
3. V1 表结构不直接搬入 V2。
4. V1 数据库只读保留，作为迁移源和行为对照。

验收标准：

- V2 可独立从空库迁移到 head，再导入 V1 精选资产。
- 导入可重复执行，具备幂等性和差异报告。
- V1 与 V2 数据边界清楚，不出现一半沿用旧表、一半新表的混合状态。

## 立即不做的事

- 不删除 `ai_contract_platform`。
- 不删除或覆盖 `5432/yuqei_contract`。
- 不继续新建第三个、第四个 V2 候选库。
- 不把 V1 的单体 schema 复制到 V2。
- 不在未确认权威库前继续向数据库写入新业务数据。

## 下一步建议

优先执行 Phase A：

1. 写数据库环境登记表。
2. 写只读 DB 检查脚本。
3. 启动并检查 Docker smoke 数据库三库状态。
4. 决定权威 V2 dev/smoke 库。

这个阶段完成后，再开始代码模块化和 schema 硬化。这样重构不是边跑边猜，而是有清晰的数据库落点和验收门槛。