ai-contract-platform/project-docs/V2-database-current-state-freeze-2026-06-24.md

AI 合同平台 V2 数据库现状冻结

日期：2026-06-24

本文对应 DB-0：数据库现状冻结。冻结目标不是备份生产数据，而是把 V1 遗留数据库结构、当前 V2 数据库结构、当前运行拓扑和后续重构边界写清楚，避免 V2 开发继续沿用 V1 的单库混杂惯性。

结论

当前必须做数据库重构基线收束。

V1 数据库把合同、审查、用户、租户、知识库、AI Prompt、AI 质量、商业订单、发票、治理、履约、审批等领域放在同一套后端库中，迁移已经累计 45 个。V2 虽然已经拆成 yuqei-contract-platform 和 yuqei-ai-platform 两个代码平台，但当前 compose 仍默认使用 yuqei_v2 单库，合同平台和 AI 平台只是使用不同 Alembic version table，并没有形成最终的数据边界。

DB-1 应立即把运行基线改为：

• yuqei_contract：企业合同业务库。
• yuqei_ai：统一 AI 中台库。
• yuqei_ops：运维、发布、任务运行和审计扩展预留库。

V1 数据库冻结摘要

V1 目录：D:\yuqei-project\ai-contract-platform-v1

V1 后端迁移目录：backend/migrations/versions

迁移数量：45

首个迁移：20260415_0001_create_review_tasks.py

最新迁移：20260619_0045_create_generated_contract_version_comments.py

主要领域：

• 身份与租户：users、tenants。
• 合同审查：review_tasks、review_results、review_rules、review_risk_actions。
• 合同生成与生命周期：generated_contracts、generated_contract_versions、contract_lifecycle_tasks、contract_approval_steps、版本批注。
• 文件：files。
• 知识库与法规：knowledge_bases、knowledge_base_documents、legal_articles、法条向量字段。
• 模板与文书：contract_templates、模板版本、法律文书类型、元素 schema、草稿。
• AI 与 Prompt：prompt_assets、prompt_evaluation_runs、model_settings、AI 质量评测域。
• 商业化：订单、发票、支付证据、商机跟进。
• 审计与治理：audit_logs、治理表、法律变更影响。

V1 主要数据库问题

1. 单库承载过多领域，合同业务和 AI 能力边界不清。
2. 多个表用 Text/JSON 承载核心业务结构，例如审查结果、风险项、变量值、摘要等，后期查询、统计、索引和权限控制困难。
3. generated_contracts 存在 file_content_base64 这类大对象字段，容易让数据库膨胀，文件应进入对象存储或文件仓库，只在数据库保存元数据。
4. 租户字段不是所有核心表都一致具备，后续企业隔离、权限、审计、导出会变复杂。
5. AI 模型参数、Prompt、知识库、向量、质量评测与合同业务混在一起，导致合同系统需要理解 AI 内部实现。
6. 迁移历史横跨多个产品阶段，缺少清晰的领域边界和最终读写归属。
7. 审计有基础表，但合同事件、AI 调用、配置发布、知识库导入、worker 执行之间缺少统一可追溯链。

当前 V2 合同平台数据库状态

目录：yuqei-contract-platform/services/contract-api

当前迁移数量：7

迁移清单：

• 20260623_0001_create_contract_workflow_tables.py
• 20260624_0002_add_contract_body_content.py
• 20260624_0003_add_contract_files_and_review_tasks.py
• 20260624_0004_add_review_task_results.py
• 20260624_0005_add_review_task_worker_state.py
• 20260624_0006_add_contract_audit_events.py
• 20260624_0007_add_review_task_ai_source_fields.py

当前核心表：

• contracts
• approval_timeline_items
• contract_audit_events
• contract_files
• review_tasks

当前问题：

• 合同业务已经开始持久化，但表结构仍偏 MVP，企业级字段如 tenant_id、created_by、updated_by、deleted_at、权限边界字段还没有全面固化。
• contracts 表仍保留部分前端展示型字段，例如 status_label、status_tone、next_action、next_actions。后续应逐步把展示文案收回前端或 BFF，将数据库保留为状态事实。
• 版本、履约、归档、下载审计已经有入口，但最终表结构还需要继续向“事件 + 快照 + 附件元数据”靠拢。

当前 V2 AI 平台数据库状态

目录：yuqei-ai-platform/services/ai-platform-api

当前迁移数量：13

迁移清单：

• 20260622_0001_create_ai_platform_tables.py
• 20260622_0002_add_knowledge_batches_and_chunks.py
• 20260622_0003_add_hybrid_retrieval_audit.py
• 20260622_0004_add_embedding_provider_and_pgvector.py
• 20260622_0005_add_ai_run_trace_fields.py
• 20260623_0006_add_ai_run_prompt_preview.py
• 20260623_0007_add_ai_run_quality_fields.py
• 20260623_0008_add_ai_quality_rule_configs.py
• 20260623_0009_add_provider_config_changes.py
• 20260623_0010_add_prompt_and_reindex_execution_records.py
• 20260623_0011_add_knowledge_ingestion_jobs.py
• 20260623_0012_add_runtime_config_and_worker_health.py
• 20260623_0013_add_worker_run_executions.py

当前核心能力：

• Provider 配置与模型运行参数。
• Prompt 模板、草稿、发布记录。
• 知识库文档、导入批次、chunk、索引状态。
• hybrid retrieval、pgvector 入口、命中分数和 explain。
• AI Run Trace、token、费用、耗时、错误、来源。
• 质量标签、质量规则、质量改进项、配置执行记录。
• worker 健康、手动执行、知识库导入任务、对象存储和 OCR 配置入口。

当前问题：

• 能力方向符合 V2 方案，但当前 compose 仍与合同平台共用 yuqei_v2 单库。
• AI 平台已经具备独立演进价值，应立刻固定为 yuqei_ai 独立数据库。
• 后续应继续补充多租户、数据保留周期、敏感字段加密、向量索引和审计保留策略。

当前运行拓扑问题

当前 yuqei-infra/compose/docker-compose.yml 使用一个 PostgreSQL 服务和一个默认数据库：

• POSTGRES_DB=yuqei_v2
• 合同平台 CONTRACT_API_DATABASE_URL 指向 yuqei_v2
• AI 平台 AI_PLATFORM_DATABASE_URL 指向 yuqei_v2
• worker YUQEI_WORKER_DATABASE_URL 指向 yuqei_v2

虽然 Alembic version table 是分开的，但这只是迁移历史隔离，不是数据库边界隔离。最终 V2 不应继续这种模式。

数据迁移处理原则

V2 当前是重构开发，不建议把 V1 表结构原样迁移进来。处理方式：

• V1 作为历史基线保留在 V1 分支和本地 worktree，用于行为对照和必要数据映射。
• V2 以新 schema 为准，不把 V1 的表名、JSON 字段、大对象字段继续带入。
• 后续如需导入 V1 数据，只写一次性迁移脚本，按 V2 领域模型清洗后导入。
• 合同文件正文、附件、知识库原始文件全部进入对象存储或文件仓库，数据库只保存元数据、解析结果、chunk 和索引状态。
• AI 调用、Prompt、模型参数、知识库检索只进入 yuqei_ai，合同系统只保存业务引用，例如 ai_trace_id、审查任务结果摘要、来源快照。

DB-0 冻结完成标准

• V1 数据库迁移数量、范围、主要问题已记录。
• V2 合同平台当前迁移和表边界已记录。
• V2 AI 平台当前迁移和表边界已记录。
• 当前 compose 单库问题已记录。
• DB-1 的目标数据库边界已明确。