ai-contract-platform/project-docs/V2-database-engineering-baseline-2026-06-24.md

AI 合同平台 V2 数据库工程基线

日期：2026-06-24

本文对应 DB-1：最终数据库工程基线。目标是在继续开发业务功能前，把 V2 的数据库边界、环境变量、迁移责任、启动顺序、性能和安全原则固定下来。

总体原则

V2 不再沿用 V1 的“一个后端库承载所有领域”的方式。

最终结构一次规划到位：

• 合同产品平台使用独立合同业务库。
• AI 中台使用独立 AI 能力库。
• 基础设施和运维数据预留独立运维库。
• 跨平台只通过 API、SDK、事件引用和审计 ID 关联，不直接跨库 join。

数据库清单

数据库	归属平台	主要内容	连接变量
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	发布记录、备份记录、运行审计、监控扩展预留	后续按运维服务单独配置

Compose 基线

本地 compose 仍使用一个 PostgreSQL 实例，降低部署复杂度；但实例内必须创建三个数据库：

• yuqei_contract
• yuqei_ai
• yuqei_ops

postgres 服务只作为数据库实例。postgres-init-databases 服务负责在每次启动时幂等检查并创建缺失数据库。

迁移顺序：

1. postgres 启动并健康。
2. postgres-init-databases 创建数据库。
3. ai-platform-api-migrate 升级 yuqei_ai。
4. contract-api-migrate 升级 yuqei_contract。
5. AI 平台、合同 API、worker、前端启动。

迁移责任

合同平台：

• Alembic 目录：yuqei-contract-platform/services/contract-api/migrations
• 只允许修改 yuqei_contract
• Alembic version table：contract_api_alembic_version

AI 平台：

• Alembic 目录：yuqei-ai-platform/services/ai-platform-api/migrations
• 只允许修改 yuqei_ai
• Alembic version table：ai_platform_alembic_version

运维平台：

• 当前只预留 yuqei_ops
• 后续如增加运维服务，必须独立迁移目录，不复用合同或 AI 的迁移链。

表设计原则

所有核心业务表默认遵循：

• 主键使用稳定字符串 ID 或 UUID，不使用有业务含义的自然键。
• 需要企业隔离的表必须有 tenant_id。
• 需要审计的表必须有 created_at、updated_at，重要业务表补 created_by、updated_by。
• 用户可删除的业务数据优先软删除，使用 deleted_at。
• 状态字段保存事实状态，不保存前端展示文案。
• 大文件、原始上传文件、导出文件不进数据库，只保存对象存储 key、hash、大小、MIME、版本和来源。
• JSON 字段只能用于扩展元数据，不能长期承载核心查询字段。
• 需要统计、筛选、排序、权限判断的字段必须结构化。

索引原则

合同库优先索引：

• (tenant_id, status, updated_at)
• (tenant_id, owner_id, updated_at)
• (tenant_id, approval_status, updated_at)
• (tenant_id, lifecycle_state, next_due_at)
• contract_files(contract_id, created_at)
• review_tasks(contract_id, status, updated_at)
• contract_audit_events(contract_id, created_at)

AI 库优先索引：

• ai_run_audits(created_at)
• ai_run_audits(trace_id) 或等价 trace 主键。
• (tenant_id, capability, created_at)
• knowledge_chunks(document_id, chunk_index)
• knowledge_chunks(embedding) 使用 pgvector 索引。
• quality_labels(status, code, created_at)
• provider_config_changes(provider_id, created_at)
• worker_run_executions(worker_name, started_at)

安全原则

• 生产必须禁用自动建表：*_DATABASE_AUTO_CREATE=false。
• 生产必须禁用 demo seed：CONTRACT_API_SEED_DEMO_DATA=false。
• 生产数据库密码不得使用默认值。
• Provider API Key、对象存储密钥、数据库密码不入库明文；需要入库时必须加密或交给密钥服务。
• 合同库与 AI 库使用不同数据库名称，生产环境优先使用不同账号授权。
• AI Trace 中的 Prompt、输入、输出需要保留脱敏策略和保留周期。
• 所有下载、上传、审批、配置发布、模型回滚、知识库重建索引都必须留审计事件。

性能原则

• 合同列表、待办、搜索、台账必须走索引字段，不依赖 JSON 全表扫描。
• 合同正文、审查全文、AI 输出全文可以保存为文本，但列表页只读取摘要字段。
• 文件预览读取对象存储，不从数据库拉大对象。
• AI 知识库检索使用关键词 + 向量 + 混合排序，向量检索在生产使用 pgvector。
• 长流程如合同审查、文档解析、OCR、知识库索引进入 worker，不阻塞 API 请求。
• 批量导入、批量下载、批量导出必须有任务状态，不做长时间同步请求。

环境变量基线

本地默认：

POSTGRES_DB=postgres
CONTRACT_POSTGRES_DB=yuqei_contract
AI_PLATFORM_POSTGRES_DB=yuqei_ai
OPS_POSTGRES_DB=yuqei_ops
CONTRACT_API_DATABASE_URL=postgresql+psycopg://yuqei:yuqei-local@postgres:5432/yuqei_contract
AI_PLATFORM_DATABASE_URL=postgresql+psycopg://yuqei:yuqei-local@postgres:5432/yuqei_ai
YUQEI_WORKER_DATABASE_URL=postgresql+psycopg://yuqei:yuqei-local@postgres:5432/yuqei_ai

生产默认：

POSTGRES_DB=postgres
CONTRACT_POSTGRES_DB=yuqei_contract
AI_PLATFORM_POSTGRES_DB=yuqei_ai
OPS_POSTGRES_DB=yuqei_ops
CONTRACT_API_DATABASE_URL=postgresql+psycopg://CHANGE_ME:CHANGE_ME@postgres:5432/yuqei_contract
AI_PLATFORM_DATABASE_URL=postgresql+psycopg://CHANGE_ME:CHANGE_ME@postgres:5432/yuqei_ai
YUQEI_WORKER_DATABASE_URL=postgresql+psycopg://CHANGE_ME:CHANGE_ME@postgres:5432/yuqei_ai

DB-1 完成标准

• compose 不再默认使用 yuqei_v2 单库。
• 本地环境样例明确合同库、AI 库、运维库。
• 生产环境样例明确合同库、AI 库、运维库。
• 基础设施 README 说明数据库拓扑和迁移顺序。
• 运行验证至少覆盖 YAML 解析和已有 API 测试；如本机没有 Docker，应在结果中明确说明无法执行 compose 启动验证。

本轮落地记录

已完成：

• yuqei-infra/compose/docker-compose.yml 增加 postgres-init-databases，启动时幂等创建 yuqei_contract、yuqei_ai、yuqei_ops。
• PostgreSQL 默认镜像改为 pgvector/pgvector:pg16，保证 yuqei_ai 可以执行 CREATE EXTENSION vector。
• 合同 API、合同审查 worker 默认连接 yuqei_contract。
• AI Platform API、AI worker 默认连接 yuqei_ai。
• yuqei-infra/compose/.env.example 增加三库本地配置。
• yuqei-infra/compose/.env.production.example 增加三库生产配置。
• yuqei-infra/README.md 更新数据库拓扑、迁移顺序和跨平台引用原则。

验证结果：

• YAML 解析通过，服务清单和数据库连接默认值符合三库基线。
• rg 检查 yuqei-infra、合同 API、AI API、worker 范围内不再出现 yuqei_v2。
• python -m pytest yuqei-contract-platform\services\contract-api\tests -q 通过。
• python -m pytest yuqei-ai-platform\services\ai-platform-api\tests -q 通过。
• python -m pytest yuqei-ai-platform\services\worker\tests -q 通过。
• python -m pytest yuqei-ai-sdk-python\tests -q 通过。

未执行：

• 本机未安装 Docker，docker --version 不可用，因此没有在本机执行 docker compose up --build 级别的容器启动验证。后续在装有 Docker 的开发机或服务器上需要执行 compose 启动与迁移验证。