yuqei/ai-contract-platform

Fork 0

Files

T

yuqei a1f04c7d7a chore: align V2 into final four-project layout

2026-06-22 19:51:30 +08:00

40 KiB

Raw Blame History

AI 合同平台 V2 重构版开发方案

日期：2026-06-22

适用前提：当前系统尚未正式上线，可以不受线上兼容包袱限制，允许替换现有技术栈、模块边界、仓库结构和实现方案。目标不是继续修补 V1，而是启动一套面向正式商业交付的 V2 重构版。

1. 总结论

V2 不建议继续沿用现在的 shared-ai-platform、shared-ai-platform-java、shared-ai-python-sdk、ai-contract-platform/backend/vendor/shared-ai-platform-sdk 这套历史拆分方式。

新的重构原则是：

保留“共享 AI 能力中台”的思想，废弃旧 shared 仓库结构，重新规划为“合同产品平台 + 统一 AI 中台 + 正式 SDK + 统一基础设施”的新架构。

最终系统应该是：

合同系统负责企业合同业务体验。
AI 中台负责模型、知识库、RAG、Prompt、法条依据、AI 审计。
SDK 负责稳定调用边界。
基础设施负责部署、监控、日志、备份、安全和发布。

不再新增功能到旧 shared-ai-platform-java 和旧 Python 原型中。旧仓库只作为历史参考、行为对照、迁移资料和必要的数据导出来源。

2. V2 产品定位

V2 不再定位为“AI 合同审查工具”，而是：

面向企业法务、业务、采购、行政团队的 AI 合同工作平台。

核心目标：

30 秒内让用户知道自己该处理什么。
3 步内完成合同起草或上传审查。
合同详情页永远只突出“下一步操作”。
AI 回答和审查结论必须带明确法规、条文、制度或合同依据。
审批、审计、版本、履约、归档完整保留，但默认不压迫普通用户。
管理员能力集中到管理区，普通用户不看到模型、Prompt、规则、知识库等复杂配置。

V2 的产品主心智：

工作台：今天我该处理什么？
合同房间：这份合同下一步做什么？
AI 助手：结论依据是什么？
合同仓库：文件在哪里，和哪些合同相关？
管理区：规则、模型、知识库、权限怎么配置？

3. 旧模块处置策略

3.1 `ai-contract-platform`

当前仓库是 V1 合同业务系统。

V2 启动后建议：

作为 V1 参考实现和临时可演示版本保留。
不再继续承接大规模新功能。
可提取有价值的业务规则、数据结构、测试用例、文档。
不直接在 V1 上继续堆 V2 架构。

3.2 `shared-ai-platform`

当前定位是 Python 原型 + 文档仓。

V2 中执行：

保留为历史原型和迁移资料。
不作为生产 AI 中台主线。
可迁移其中的知识库、接口设计、联调文档、测试样例。
不继续承接新生产功能。

3.3 `shared-ai-platform-java`

当前定位是 Java 版共享 AI 平台主线。

但在 V2 “一次到位、可替换技术栈”的前提下，建议：

不作为 V2 生产主线。
冻结为历史对照实现。
若其中有已经跑通的 legal-review、knowledge、conversation 逻辑，只迁移业务语义和测试样例，不迁移 Java 技术栈。
V2 统一改为 Python/TypeScript 体系，降低长期维护复杂度。

3.4 `shared-ai-python-sdk`

当前 SDK 有保留价值，但建议重写为 V2 正式 SDK。

V2 中执行：

正式工程名为 yuqei-ai-sdk-python。
SDK 由 OpenAPI 契约生成基础客户端，再手写业务友好封装。
合同系统只能通过 SDK 或 OpenAPI client 调用 AI 中台。
删除 V1 中 vendored SDK 副本。

3.5 `shared-java-libs`

如果 V2 不继续使用 Java：

归档。
不再作为新系统基础库。
可保留文档和历史代码用于对照。

4. 新仓库与模块划分

4.1 推荐方案：四个最终工程一次到位

本次重构不采用临时混放路线。V2 从第一天开始就按四个最终工程边界开发。当前 main 分支只是一条统一开发线，根目录直接体现最终架构边界：

ai-contract-platform/
  yuqei-contract-platform/
    apps/
      contract-web/             # 合同平台 Web 前端
      admin-web/                # 可选，若管理区需要独立部署

    services/
      contract-api/             # 合同业务后端

    packages/
      design-system/            # V2 自研设计系统
      contract-openapi/         # 合同业务 OpenAPI 契约

  yuqei-ai-platform/
    services/
      ai-platform-api/          # 统一 AI 中台
      worker/                   # 文档解析、索引、AI 长任务、通知任务

    packages/
      ai-openapi/               # AI 中台 OpenAPI 契约

  yuqei-ai-sdk-python/          # 合同系统调用 AI 中台的正式 Python SDK

  yuqei-infra/
    docker/
    compose/
    nginx/
    observability/
    backup/
    deploy/

  docs/
    adr/
    product/
    architecture/
    qa/

说明：

四个顶层工程从现在开始就是最终边界，不再留下二次拆分的技术债。
统一 Git 分支只负责降低当前协作成本，不改变工程边界。
合同系统和 AI 中台通过 OpenAPI 和 SDK 固化边界，部署时仍然是独立服务。
如果未来因为组织治理必须变成多个物理 Git 仓库，也只是迁移仓库存放方式，不再改变代码结构和系统边界。

4.2 最终工程边界

V2 产品和工程边界必须按下面四块执行，避免重新出现旧 shared-* 大杂烩结构。

最终工程	当前代码位置	负责内容	不负责内容
`yuqei-contract-platform`	`yuqei-contract-platform/apps/contract-web`、`yuqei-contract-platform/services/contract-api`、`yuqei-contract-platform/packages/contract-openapi`、合同侧 worker 任务	企业合同系统：前端、后端、审批、台账、合同仓库、合同房间、权限、合同审计、业务通知	模型 provider、Prompt 拼装、RAG 检索、知识库内部表、AI 运行审计
`yuqei-ai-platform`	`yuqei-ai-platform/services/ai-platform-api`、`yuqei-ai-platform/packages/ai-openapi`、AI 侧 worker 任务	统一 AI 中台：模型网关、知识库、RAG、Prompt、法律审查、法条引用、文档智能、AI 审计、质量评测	合同审批流、合同台账、合同房间业务状态
`yuqei-ai-sdk-python`	`yuqei-ai-sdk-python`	合同系统调用 AI 中台的正式 Python SDK，由 OpenAPI 生成基础客户端，再手写业务友好封装	业务数据库访问、模型 provider 直连、旧 vendored SDK 兼容层
`yuqei-infra`	`yuqei-infra/*`	部署、环境变量、监控、日志、备份、发布脚本、安全基线	业务功能、AI 业务能力、前端产品体验

旧模块最终处理方式：

旧模块	V2 处理方式
`shared-ai-platform-java`	不作为未来主线；本项目未正式上线前不需要继续做线上兼容，只冻结为旧服务行为对照和接口参考；新 AI 能力不得再写入该模块。
`shared-ai-platform`	保留历史文档、原型和数据处理经验；不再承接生产功能。
`shared-ai-python-sdk`	保留 SDK 定位和测试思想；正式 SDK 在 `yuqei-ai-sdk-python` 重做，建议包名继续向 `yuqei-ai-sdk-python` 收敛。
`shared-java-libs`	如果 V2 不采用 Java 主线，归档为参考，不再扩展。
`ai-contract-platform/backend/vendor/shared-ai-platform-sdk`	最终删除；合同系统内不得再塞一份 SDK 副本。

合同系统只做业务。它只能通过 SDK/OpenAPI 向 AI 中台表达业务意图：

帮我审查这份合同。
帮我回答这个法律问题，并返回依据。
帮我生成这份合同。
帮我改写这个条款。
帮我提取履约义务。

AI 中台必须承接模型、Prompt、知识库、RAG、引用依据、运行审计和质量评测。合同系统不得因为开发方便而绕过 SDK 直接调用模型、拼 Prompt、查 AI 知识库内部表或写 AI 审计。

关键技术原则：

API 先行：yuqei-ai-platform/packages/ai-openapi 和 yuqei-contract-platform/packages/contract-openapi 是跨边界契约真相源。
长流程可靠：合同审查、文档解析、知识库索引、批量导入等长流程后续接入 durable workflow 方案，例如 Temporal 或同类能力。
全链路可观测：AI 调用、RAG 命中、Prompt 版本、模型耗时、错误和费用后续纳入 OpenTelemetry 体系。

防跑偏检查清单：

新 AI 能力先看是否属于 yuqei-ai-platform，不要直接写进 yuqei-contract-platform/services/contract-api。
yuqei-contract-platform/services/contract-api 调 AI 只能使用 yuqei_sdk 或 OpenAPI 生成客户端。
新 SDK 代码只能进入 yuqei-ai-sdk-python；如确需 TypeScript SDK，另建 yuqei-ai-sdk-typescript，不得恢复 backend/vendor/shared-ai-platform-sdk。
新部署、环境变量、监控、备份、发布脚本进入 yuqei-infra。
旧 shared-* 仓库只能只读参考，不新增功能、不新增依赖。

4.3 为什么不继续多个 shared 仓库

旧 shared 结构的问题：

Python 原型、Java 主线、Python SDK、vendored SDK 并存，边界不清。
同一能力可能在多个地方有实现。
合同系统开发者很难判断该改哪个仓库。
Prompt、知识库、模型配置、法条检索分散。
长期维护会越来越重。

V2 的目标是：

一个 AI 中台主线。
一个正式 SDK。
一个合同业务后端。
一套设计系统。
一套部署和可观测体系。

5. V2 总体架构

┌──────────────────────────────────────────────┐
│                contract-web                  │
│ 工作台 / 合同起草 / 合同房间 / 搜索 / 仓库 / 管理区 │
└──────────────────────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────┐
│                contract-api                  │
│ 合同业务 / 审批 / 台账 / 文件 / 权限 / 审计 / 通知 │
└──────────────────────────────────────────────┘
                      │
             Python SDK / OpenAPI
                      │
                      ▼
┌──────────────────────────────────────────────┐
│              ai-platform-api                 │
│ 模型网关 / Prompt / RAG / 法条依据 / AI 审计 / 评测 │
└──────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
  Model Providers   Knowledge DB   Object Storage
 OpenAI/通义/私有   pgvector/FTS   MinIO/S3

6. 核心服务职责

6.1 `contract-web`

负责所有用户可见体验。

核心页面：

工作台
合同起草
发起审查
合同房间
审批工作台
合同仓库
统一搜索
法律问答
管理区

体验原则：

首屏只突出待办和快速发起。
合同详情只突出下一步动作。
审批按条件出现。
审计、版本、履约、归档默认折叠。
管理员入口集中在管理区。
不在普通业务界面展示模型参数、Prompt 配置、技术字段。

6.2 `contract-api`

负责合同业务，不负责模型调用细节。

核心领域：

租户、用户、角色、权限
合同模板
合同起草
合同版本
合同审查任务
合同房间
审批流
批注与处理意见
文件仓库
合同台账
履约提醒
签署证据与归档证据
站内通知
业务审计
数据导出

contract-api 调用 AI 能力时只能使用：

yuqei-ai-sdk-python
或 AI 中台 OpenAPI 生成客户端

不得直接拼模型 provider 请求。

6.3 `ai-platform-api`

负责所有通用 AI 能力。

核心领域：

模型供应商管理
模型路由
超时、重试、fallback
Prompt 模板与版本
知识库管理
文档切分和索引
法规/法条检索
RAG 混合召回
法律问答
合同审查 domain pack
合同生成 domain pack
条款改写
履约义务提取
AI 调用审计
质量评测
用量和成本统计

AI 中台必须返回结构化结果，而不是只返回一段自然语言。

例如法律问答结果：

{
  "answer": "...",
  "citations": [
    {
      "source_type": "law",
      "source_title": "中华人民共和国民法典",
      "article_no": "第五百七十七条",
      "quote": "...",
      "reason": "该条用于判断违约责任承担方式"
    }
  ],
  "confidence": "medium",
  "missing_context": [],
  "trace_id": "ai_trace_xxx"
}

6.4 `worker`

负责所有长任务。

包括：

文件解析
OCR
合同生成
合同审查
报告生成
知识库索引
法规库导入
批量导出
通知同步
定时提醒

长任务需要支持：

任务状态查询
重试
失败原因
幂等键
运行日志
trace_id 串联

7. 推荐技术栈

7.1 前端

建议：

Next.js + React + TypeScript
自研 V2 Design System
CSS Variables + tokens
TanStack Table
Playwright E2E
关键页面走服务端渲染/流式加载/缓存策略

不建议：

继续用大量通用后台模板式卡片堆叠。
继续让 Ant Design 外观决定产品气质。

Ant Design 可以短期借用底层组件，但 V2 视觉语言应该自研。

7.2 后端

建议：

Python 3.12+
FastAPI
Pydantic v2
SQLAlchemy 2.x
Alembic
PostgreSQL
Redis
MinIO/S3
Temporal 或等价 durable workflow 方案
OpenTelemetry

理由：

合同、法律、AI、RAG、文档处理都更适合 Python 生态。
团队不用同时维护 Java + Python 两条后端主线。
长流程不靠简单后台线程硬撑。

7.3 数据与检索

建议：

PostgreSQL：业务主数据
pgvector：向量检索
PostgreSQL FTS 或 Meilisearch：关键词检索
混合召回：关键词 + 向量 + 规则 rerank
MinIO/S3：原始文件、导出文件、报告、证据附件

7.4 可观测与质量

必须内置：

OpenTelemetry trace
API latency p50/p95/p99
AI 调用耗时
模型错误率
文档解析失败率
知识库召回命中率
法条引用覆盖率
用户操作审计

8. 关键数据域

8.1 合同业务域

contracts
contract_versions
contract_rooms
contract_comments
contract_approvals
approval_steps
lifecycle_tasks
signoff_archive_evidence
contract_audit_events

8.2 文件域

files
file_versions
file_previews
file_contract_links
file_processing_jobs

8.3 AI 中台域

model_providers
model_profiles
prompt_templates
prompt_versions
ai_runs
ai_run_events
knowledge_bases
knowledge_documents
knowledge_chunks
legal_sources
legal_articles
retrieval_traces
evaluation_runs

8.4 权限和租户域

tenants
users
roles
permissions
role_bindings
access_policies
audit_logs

9. 数据库重构与安全性能方案

V2 如果要做到最高性能和最高安全，数据库不能沿用 V1 的“功能不断追加，字段不断扩展”的方式。数据库要从一开始按照企业级 SaaS、AI 知识检索、合同生命周期和审计合规来设计。

9.1 当前数据库主要问题

根据当前 V1 模型和工程结构，数据库层存在以下问题。

问题 1：业务主数据、全文内容、AI 结果混在一起

当前 generated_contracts 中同时包含：

合同元数据
合同正文 generated_content
导出文件内容 file_content_base64
生命周期字段
模板字段
AI 生成快照

这会导致：

合同列表查询也可能扫到大字段。
表膨胀快。
热数据和冷数据无法分层。
备份和恢复成本变高。
下载文件不应该依赖数据库大文本字段。

V2 应把合同元数据、正文版本、导出文件、生命周期状态拆开。

问题 2：JSON/Text 承载过多结构化结果

当前 review_results 用 Text 存 basic_info_json、clauses_json、risk_items_json、risk_summary_json。部分模型用 JSON 字段保存较多业务结构。

这会导致：

风险项无法高效筛选和统计。
无法稳定按风险等级、条款类型、依据来源建立索引。
数据质量约束弱。
后续做 BI、审计、法条引用准确率统计会困难。

V2 应把高频查询字段结构化，把低频详情放 JSONB。

问题 3：文件内容和对象存储边界不干净

V1 已有 files 表和 MinIO 对象存储，但合同表仍保留 file_content_base64。

V2 应坚持：

数据库只存文件元数据。
原始文件、导出文件、报告、证据附件全部进对象存储。
数据库保存 bucket、object_key、hash、size、mime、加密状态、归属关系。

问题 4：多租户隔离只停留在应用层字段

当前很多表有 tenant_id，但主要依赖应用代码过滤。

风险：

某个接口漏加 tenant 条件就可能越权。
后台任务、导出任务、搜索任务更容易漏边界。
缺少数据库层的最后防线。

V2 应考虑 PostgreSQL Row Level Security，至少在核心租户表上启用数据库层隔离策略。

问题 5：索引按单字段较多，缺少面向页面查询的复合索引

当前模型中有不少 index=True，但 V2 需要按真实页面和 API 设计索引。

例如：

工作台：tenant_id + assignee_id + status + due_at
合同列表：tenant_id + lifecycle_status + updated_at
审批待办：tenant_id + assignee_id + status + created_at
合同仓库：tenant_id + file_type + created_at
审计时间线：tenant_id + resource_type + resource_id + created_at

V2 不能只依赖单字段索引。

问题 6：法条向量以 JSON 保存，不适合高性能检索

当前 legal_articles.semantic_vector_json 是 JSON。

这不适合高性能向量相似度搜索。V2 应使用：

pgvector 存 embedding
GIN/FTS 做关键词检索
混合检索表记录召回 trace

问题 7：审计日志只是普通业务表

当前 audit_logs 能记录动作，但还不够企业级。

缺口：

缺少不可篡改链。
缺少请求 trace_id。
缺少 before/after 摘要。
缺少审计归档策略。
缺少关键安全事件分类。

V2 审计应单独设计为 append-only 事件表，并支持冷热归档。

问题 8：数据库连接和运行参数偏基础

当前 create_engine(settings.database_url, future=True) 没有体现：

连接池大小
pool recycle
statement timeout
lock timeout
application_name
慢查询日志
只读副本策略

V2 应从工程层统一配置数据库连接与超时策略。

问题 9：迁移和测试环境不够贴近生产

当前测试大量使用 SQLite in-memory。SQLite 很方便，但和 PostgreSQL 在 JSON、事务、锁、索引、RLS、全文检索、向量能力上差异很大。

V2 应保留轻量单测，但关键数据库测试必须跑 PostgreSQL Testcontainer 或独立测试库。

9.2 V2 数据库总体原则

V2 数据库设计遵循以下原则：

交易数据和检索数据分离。
元数据和大文本分离。
数据库和对象存储边界清晰。
租户隔离同时在应用层和数据库层实现。
高频查询优先设计复合索引。
AI 结果结构化保存，不能只存一段自然语言。
审计日志 append-only，关键事件可追溯、可校验。
所有长任务状态可查询、可重试、可恢复。
数据库迁移必须可回滚、可灰度、可验证。

9.3 V2 数据库分层

推荐采用一套 PostgreSQL 主库承载多个 schema，而不是一开始拆成多个数据库。

PostgreSQL
  identity          # 租户、用户、角色、权限
  contract          # 合同业务主数据
  document          # 文件元数据、解析结果、预览
  ai                # AI run、Prompt、模型配置、质量评测
  knowledge         # 知识库、法条、chunk、embedding
  audit             # 审计事件、安全事件、操作日志
  billing           # 用量、额度、成本

说明：

初期一个 PostgreSQL 实例即可。
schema 分层让边界清晰。
后期 AI 知识库或审计数据膨胀后，可以单独拆库或分区。

9.4 核心数据模型重构

9.4.1 合同主表

contract.contracts

只保存列表和详情首屏必须字段：

id
tenant_id
title
contract_type
counterparty_name
owner_user_id
owner_department_id
lifecycle_status
approval_status
risk_level
latest_version_id
latest_file_id
created_by
created_at
updated_at
archived_at

不保存大正文，不保存 base64 文件。

9.4.2 合同版本表

contract.contract_versions

保存每次生成、编辑、导入、审批退回后的版本：

id
tenant_id
contract_id
version_no
version_label
source_type
content_text
content_html
content_hash
created_by
created_at
ai_run_id

大正文是否直接入库要按大小控制：

短文本可入库，便于版本比对。
大文件原文进入对象存储，数据库保存 text extraction 和 object_key。

9.4.3 合同文件关系表

contract.contract_files

管理合同与文件关系：

contract_id
file_id
relation_type：source / generated / report / evidence / archive
version_id
created_at

9.4.4 审查任务表

contract.review_tasks

保存任务状态：

id
tenant_id
contract_id
source_file_id
status
risk_level
current_stage
ai_run_id
created_by
created_at
completed_at

9.4.5 审查风险项表

contract.review_risk_items

每个风险项结构化保存：

id
tenant_id
review_id
contract_id
severity
category
clause_title
original_text
risk_reason
suggestion
legal_basis_summary
status
sort_order

9.4.6 风险依据表

contract.review_risk_citations

风险项引用的法律、制度、知识库来源：

id
tenant_id
risk_item_id
source_type
source_id
source_title
article_no
quote_text
relevance_reason
confidence

这样可以统计：

哪些风险有依据
哪些依据最常被引用
哪类合同最常出现哪些风险

9.4.7 AI run 表

ai.ai_runs

保存每次 AI 调用：

id
tenant_id
run_type
model_provider
model_name
prompt_key
prompt_version
input_hash
output_hash
status
latency_ms
token_input
token_output
cost_amount
trace_id
created_at

输入全文不建议全量入库，可存：

hash
摘要
对象存储引用
脱敏后的 debug payload

9.4.8 知识库 chunk 表

knowledge.knowledge_chunks

id
tenant_id
knowledge_base_id
document_id
chunk_no
title
content
content_tsvector
embedding vector
metadata_jsonb
created_at

索引：

GIN(content_tsvector)
HNSW/IVFFLAT vector index
tenant_id + knowledge_base_id

9.4.9 法条表

knowledge.legal_articles

V2 法条表应结构化：

id
jurisdiction
source_type
source_title
authority
article_no
article_text
validity_status
effective_date
region
content_tsvector
embedding vector
source_url
checksum
updated_at

常用查询索引：

source_title + article_no
validity_status + effective_date
region + source_type
GIN(content_tsvector)
vector index

9.4.10 审计事件表

audit.audit_events

append-only：

id
tenant_id
actor_user_id
actor_role
action
resource_type
resource_id
request_id
trace_id
ip_address
user_agent
before_hash
after_hash
event_hash
previous_event_hash
metadata_jsonb
created_at

关键点：

禁止业务代码更新或删除审计事件。
通过 hash chain 提供防篡改校验。
高频审计可按月分区。

9.5 索引策略

V2 索引按页面/API 反推。

工作台

CREATE INDEX idx_tasks_tenant_assignee_status_due
ON contract.tasks (tenant_id, assignee_id, status, due_at);

合同列表

CREATE INDEX idx_contracts_tenant_status_updated
ON contract.contracts (tenant_id, lifecycle_status, updated_at DESC);

CREATE INDEX idx_contracts_tenant_owner_updated
ON contract.contracts (tenant_id, owner_user_id, updated_at DESC);

审批工作台

CREATE INDEX idx_approval_steps_tenant_assignee_status_created
ON contract.approval_steps (tenant_id, assignee_user_id, status, created_at DESC);

合同详情时间线

CREATE INDEX idx_audit_events_resource_time
ON audit.audit_events (tenant_id, resource_type, resource_id, created_at DESC);

文件仓库

CREATE INDEX idx_files_tenant_type_created
ON document.files (tenant_id, file_type, created_at DESC);

CREATE INDEX idx_files_tenant_hash
ON document.files (tenant_id, file_hash);

法条检索

CREATE INDEX idx_legal_articles_title_article
ON knowledge.legal_articles (source_title, article_no);

全文和向量索引根据 PostgreSQL/pgvector 版本选择 GIN + HNSW。

9.6 分区策略

以下表建议从 V2 初期就设计分区能力：

audit.audit_events：按月分区
ai.ai_runs：按月分区
ai.ai_run_events：按月分区
document.file_processing_jobs：按月分区
knowledge.retrieval_traces：按月分区

好处：

查询近期数据更快。
归档和清理更安全。
备份可以分冷热。
审计留存周期可按法规和客户要求管理。

9.7 租户隔离与权限安全

V2 安全目标：

应用层漏写 tenant 条件时，数据库层仍然尽量阻止越权读取。

建议：

核心表必须有 tenant_id NOT NULL。
所有业务查询默认带 tenant context。
PostgreSQL 启用 Row Level Security。
每个请求进入事务后设置：

SET LOCAL app.current_tenant_id = 'tenant_xxx';
SET LOCAL app.current_user_id = 'user_xxx';

示例策略：

CREATE POLICY tenant_isolation_contracts
ON contract.contracts
USING (tenant_id = current_setting('app.current_tenant_id')::text);

高权限后台操作必须：

单独 DB role
单独审计
明确 break-glass 机制

9.8 敏感数据安全

敏感字段包括：

模型 API Key
用户密码 hash
合同正文
企业制度
法律咨询内容
身份信息
商业合同金额

V2 要求：

API Key 不明文存储。
密钥使用 envelope encryption。
密码使用 Argon2id 或 bcrypt。
对象存储启用服务端加密。
合同正文和导出文件支持按租户加密策略。
日志和 AI trace 默认脱敏。
数据导出必须记录审计。
管理员不能直接查看密钥明文，只能重置。

9.9 备份、恢复与灾备

V2 必须在上线前验证：

每日全量备份
高频 WAL 归档
对象存储备份
备份加密
恢复演练
租户级数据导出
删除保护

目标指标：

RPO：不超过 15 分钟
RTO：不超过 2 小时

对于尚未正式上线的早期版本，也要至少做到：

每日数据库备份
每日 MinIO 备份
发布前手动快照
恢复脚本可执行

9.10 数据库连接与运行参数

V2 后端数据库连接必须配置：

pool_size
max_overflow
pool_timeout
pool_recycle
statement_timeout
lock_timeout
idle_in_transaction_session_timeout
application_name

建议：

API 服务：短连接事务，statement_timeout 5-15s
Worker：长任务拆小事务，statement_timeout 30-120s
报表/导出：独立只读连接或后台任务

禁止：

Web 请求里执行长时间批处理。
长事务包住 AI 调用。
长事务包住文件上传。
后台任务无边界地扫全表。

9.11 查询性能目标

V2 数据库性能验收指标：

工作台 API p95 < 300ms，不含 AI 长任务。
合同列表 API p95 < 300ms。
合同详情元数据 p95 < 300ms。
合同审计时间线 p95 < 500ms。
统一搜索 p95 < 800ms。
法条关键词检索 p95 < 500ms。
法条混合检索 p95 < 1200ms。
单租户 10 万合同元数据列表仍可分页稳定。
单租户 100 万审计事件按合同详情查询稳定。

9.12 数据库测试要求

V2 测试分三层：

轻量单测：可使用 SQLite 或 fake repository。
数据库集成测试：必须使用 PostgreSQL。
性能测试：使用接近真实数据量的种子数据。

必须覆盖：

迁移升级
迁移回滚
RLS 租户隔离
复合索引命中
审计 append-only
文件元数据与对象存储一致性
AI run trace 查询
法条全文检索
向量检索

9.13 数据库重构分阶段任务

DB-0：数据架构冻结

确认 schema 划分。
确认核心表清单。
确认租户隔离策略。
确认对象存储边界。
确认审计防篡改策略。

DB-1：基础数据库工程

初始化 Alembic。
建立 PostgreSQL 本地开发库。
建立 Testcontainer 或测试库。
建立数据库连接配置。
建立 health check。

DB-2：身份与权限域

tenants
users
roles
permissions
role_bindings
access_policies
RLS 基础策略

DB-3：合同业务域

contracts
contract_versions
contract_files
review_tasks
review_risk_items
review_risk_citations
approval_steps
lifecycle_tasks

DB-4：文件与对象存储域

files
file_versions
file_previews
file_processing_jobs
object storage consistency checker

DB-5：AI 与知识库域

model_providers
prompt_templates
ai_runs
knowledge_bases
knowledge_documents
knowledge_chunks
legal_articles
retrieval_traces

DB-6：审计与归档域

audit_events
security_events
monthly partitions
hash chain
archive jobs

DB-7：性能压测与安全验证

租户越权测试
10 万合同种子数据
100 万审计事件种子数据
法条检索压测
备份恢复演练

10. V2 核心用户流程

10.1 工作台

目标：用户进入系统只看到两类事情。

待我处理
- 待审批
- 被退回待修改
- 高风险待确认
- 到期/逾期提醒
- 待补证据
快速发起
- 起草合同
- 上传审查

其他入口放到二级：

合同仓库
统一搜索
法律问答
审查记录
合同台账

10.2 合同房间

合同房间是 V2 最核心页面。

顶部固定展示：

合同名称
当前状态
下一步操作
主动作按钮

默认可见：

合同概览
正文预览
AI 风险摘要
下一步建议

默认折叠：

审批流
版本比对
履约任务
签署证据
归档证据
审计时间线
技术详情

审批区只在以下情况出现：

高风险合同
金额或合同类型触发审批规则
已提交审批
待当前用户审批
被退回待重提
管理员/法务主动查看

10.3 法律问答

回答前必须先检索：

法律法规
司法解释
地方法规
企业制度
合同上下文

回答必须包含：

结论
依据
适用关系
风险提示
需要补充的信息

没有依据时必须明确说：

当前知识库未检索到足够依据，以下仅为一般性分析，建议补充合同条款或人工复核。

10.4 合同审查

审查输出必须结构化：

总体风险
必改项
可协商项
证据/依据
修改建议
谈判建议
可生成报告

每条风险必须尽量关联：

合同原文位置
风险理由
法条或制度依据
建议改法

11. API 与 SDK 规范

11.1 契约先行

V2 必须先定义 OpenAPI：

contract-openapi
ai-openapi

前后端和 SDK 都围绕契约开发。

11.2 SDK 设计

Python SDK 必须包含：

类型定义
统一错误
超时配置
重试策略
幂等键
trace_id
streaming 支持
mock/stub 测试工具

核心方法：

client.chat_with_citations(...)
client.run_legal_review(...)
client.generate_contract(...)
client.rewrite_clause(...)
client.extract_obligations(...)
client.retrieve_legal_sources(...)
client.sync_knowledge_records(...)
client.get_run_trace(...)

11.3 合同系统调用原则

合同系统不得：

直接写 OpenAI/Anthropic/通义请求。
直接拼 Prompt。
直接操作 AI 中台知识库内部表。
直接假设某个模型 provider 的返回格式。

合同系统只表达业务意图：

审查这份合同
起草这份合同
回答这个法律问题
改写这个条款
提取履约义务

12. 开发阶段规划

Phase 0：V2 架构冻结与原型确认

目标：先把方向锁死，避免边做边推翻。

交付：

V2 信息架构
V2 仓库结构
V2 API 边界
V2 数据域草图
V2 设计系统方向
旧模块归档策略

验收：

明确不再往旧 shared 结构增加新能力。
明确新 AI 中台技术栈。
明确合同系统与 AI 中台边界。

Phase 1：V2 基础工程

目标：搭好能长期开发的底座。

交付：

workspace 初始化
contract-web 初始化
contract-api 初始化
ai-platform-api 初始化
worker 初始化
PostgreSQL / Redis / MinIO / Temporal 本地环境
OpenTelemetry 基础接入
CI 脚本
lint / test / build / typecheck

验收：

一条命令启动本地开发环境。
一条命令跑基础测试。
每个服务有 health check。
trace_id 能跨服务串联。

Phase 2：设计系统与产品骨架

目标：先把 V2 产品气质定下来。

交付：

登录页
工作台
合同房间静态骨架
合同起草流程原型
发起审查流程原型
法律问答原型
管理区框架
组件库 tokens

验收：

页面不再像通用后台模板。
首屏不堆卡片。
普通用户看不到复杂配置。
合同房间顶部下一步动作清晰。

Phase 3：AI 中台 V2

目标：先建好 AI 能力边界。

交付：

模型 provider 管理
模型 profile
Prompt 模板与版本
AI run trace
知识库 CRUD
文档切分和索引
法条库导入
混合检索
法律问答 with citations
Python SDK v0.3

验收：

法律问答必须返回依据。
每次 AI 调用有 trace。
模型配置可热更新。
SDK 契约测试通过。

Phase 4：合同主链路 V2

目标：合同起草和审查闭环跑通。

交付：

合同模板
合同起草
生成预览
合同下载
上传审查
审查报告
合同房间
AI 风险摘要
法条依据展示

验收：

用户 3 步内完成起草或上传审查。
合同详情只突出下一步。
审查结论有依据。
报告可下载。

Phase 5：企业协作闭环

目标：补齐企业用户真正会用的协作流程。

交付：

RBAC 权限
条件审批规则
待我审批
退回后重提
审批时间线
版本比对
批注和处理意见
审计时间线
通知中心

验收：

普通合同不默认压审批。
触发条件时审批自动出现。
退回后能修改并重新提交。
所有关键操作有审计。

Phase 6：合同仓库与生命周期

目标：让系统从工具变成合同管理平台。

交付：

文件仓库
文件预览
关联合同
批量下载
合同台账
生命周期筛选
履约提醒
签署证据
归档证据
数据导出

验收：

文件能按合同、类型、状态检索。
台账状态和详情状态一致。
签署/归档证据有统一附件清单。
到期和履约提醒进入待我处理。

Phase 7：安全、性能与上线准备

目标：达到正式商业交付标准。

交付：

租户隔离
权限矩阵
审计完整性
数据备份和恢复
错误监控
性能压测
安全扫描
部署文档
运维手册

验收指标：

工作台首屏加载小于 1.5 秒。
常用 API p95 小于 500ms。
AI 长任务可恢复、可追踪、可重试。
租户数据不可越权访问。
关键操作 100% 留痕。

13. 质量门禁

V2 每个阶段必须满足：

单元测试
API 契约测试
关键流程 E2E
权限边界测试
数据库迁移回滚测试
AI 输出结构测试
法条引用质量抽检
Playwright 视觉回归
构建和部署验证

AI 能力额外门禁：

有依据率
引用准确率
无依据拒答率
审查漏项率
超时率
fallback 成功率
成本统计准确性

14. 旧数据与旧代码迁移策略

由于系统尚未正式上线，V2 不需要为了旧系统做复杂兼容。

但可以迁移以下资产：

合同模板
法条数据
测试合同样本
Prompt 资产
审查规则经验
UI 优化经验
现有 E2E 测试中的关键业务路径

不建议迁移：

V1 页面结构
V1 管理后台信息架构
vendored SDK
Java shared-ai 技术栈
多套 shared 仓库边界
无明确业务价值的历史测试数据

15. 第一批立即执行任务

T0：决策冻结

确认 V2 不继续沿用旧 shared 仓库结构。
确认 V2 统一 Python/TypeScript 技术主线。
确认 shared-ai-platform-java 归档为历史对照。
确认新 workspace 名称。

建议名称：

yuqei-platform-v2

T1：V2 信息架构稿

输出页面清单：

工作台
合同起草
发起审查
合同房间
审批工作台
合同仓库
统一搜索
法律问答
管理区

T2：AI 中台 API 草案

先定义：

/chat/with-citations
/legal-review/run
/contracts/generate
/clauses/rewrite
/obligations/extract
/knowledge-bases
/retrieval/legal-sources
/ai-runs/{id}

T3：合同业务 API 草案