# AI 合同平台 V2 数据库优化重构方案 日期：2026-06-24 ## 1. 结论 需要做数据库优化重构，而且应该在 V2 继续扩展业务功能前完成。 当前 V2 代码已经按 `yuqei-contract-platform`、`yuqei-ai-platform`、`yuqei-ai-sdk-python`、`yuqei-infra` 重新划分，但数据库层还处在 MVP 过渡状态： - Contract API 已有 Alembic 和 SQLAlchemy 仓储，但表结构主要服务“主流程跑通”，缺少企业级租户、权限、软删除、组合索引和最终状态建模。 - AI Platform 已有知识库、chunk、AI Trace、质量评测、pgvector 起点，但还没有形成生产级检索索引、租户隔离、分区、冷热归档和可审计配置发布模型。 - 当前 compose 为了本地联调，把 Contract API 和 AI Platform 放在同一个 PostgreSQL 数据库里，只用不同 Alembic version table 隔离迁移历史。这适合开发，不适合作为最终生产数据库边界。 因为项目尚未正式上线，建议不要继续背 V1 兼容包袱，也不要在现有 MVP 迁移上无限叠加。应该在 V2 进入更多业务功能前，执行一次“干净数据库基线”重构。 ## 2. 本方案范围 本方案覆盖： - V1 数据库问题归纳。 - 当前 V2 数据库现状判断。 - V2 最终数据库边界与核心表设计。 - 性能索引、全文检索、向量检索、分区策略。 - 安全、租户隔离、审计、备份恢复。 - 从当前 V2 MVP 到最终数据库基线的实施路径。 本方案不直接改代码，不直接迁移生产数据。下一轮开发可按本文拆分 DB 任务执行。 ## 3. V1 数据库主要问题 根据 `D:\yuqei-project\ai-contract-platform-v1` 的模型与迁移观察，V1 有以下典型问题。 ### 3.1 迁移数量多，功能演进痕迹重 V1 后端已有大量迁移，覆盖审查、合同生成、知识库、法条、治理、商业订单、AI 质量评测、模型参数、审批等领域。 问题不是“迁移多”本身，而是这些能力都堆在一个业务后端数据库里，导致： - 合同业务、AI 能力、知识库、治理、商业订单混在一起。 - 不同模块数据增长速度差异巨大，却共享同一套表空间、索引和备份策略。 - 后续性能问题难以定位：到底是合同列表慢、知识库检索慢，还是 AI Trace 膨胀拖慢。 V2 不能继续沿用这种“一个后端库不断追加功能表”的模式。 ### 3.2 租户字段存在但不统一 V1 多数核心表有 `tenant_id`，例如 users、review_tasks、files、knowledge_bases、legal_articles 等。 但问题是： - 并非所有业务表都有完整 `tenant_id`。 - 主要依赖应用层过滤，缺少数据库层最后防线。 - 多租户唯一约束不够标准，例如应该更多使用 `(tenant_id, code)`、`(tenant_id, username)` 这类唯一约束。 - 审批、审计、文件、知识库、AI Trace 在租户维度上的隔离策略不一致。 V2 必须从数据库层统一租户上下文。 ### 3.3 JSON 与大文本字段使用过重 V1 `review_results` 中大量结构化结果存为 Text JSON： - `basic_info_json` - `clauses_json` - `risk_items_json` - `risk_summary_json` - `confidence_summary` 这种做法短期开发快，但会带来： - 查询困难，无法稳定索引风险项、法条引用、风险等级等字段。 - 数据质量不可控，字段结构漂移后很难校验。 - 后续统计分析、质量评测、用户筛选都需要反复解析 JSON。 V2 可以保留 JSONB 作为扩展字段，但核心查询字段必须结构化。 ### 3.4 文件内容曾进入数据库 V1 `generated_contracts` 里存在 `file_content_base64`，这类设计不适合生产： - 数据库膨胀快。 - 备份和恢复变慢。 - 文件下载性能受数据库影响。 - 文件去重、对象存储生命周期、冷热归档难做。 V2 必须坚持：数据库只存文件元数据和对象存储指针，文件正文进入 MinIO/S3。 ### 3.5 AI 能力和合同业务耦合 V1 里模型设置、知识库、法条、AI 质量评测、Prompt 资产等都和合同后端存在较强耦合。 V2 已经拆出 `yuqei-ai-platform`，数据库也必须跟着拆清楚： - 合同业务库不直接保存模型 provider、Prompt、RAG 内部 chunk。 - AI 中台库不保存合同审批流、合同履约状态、合同房间业务 UI 状态。 - 两边通过 `ai_audit_run_id`、`contract_id`、`trace_id` 做弱关联，而不是跨库强耦合事务。 ## 4. 当前 V2 数据库现状 ### 4.1 Contract API 当前表 当前 `yuqei-contract-platform/services/contract-api` 已有： - `contracts` - `approval_timeline_items` - `contract_files` - `review_tasks` - `contract_audit_events` 优点： - 已从内存数据推进到 SQLAlchemy/Alembic。 - 文件、审查任务、合同审计已经独立成表。 - 附件内容已走文件存储路径，不再把文件内容直接塞入合同表。 不足： - 缺少 `tenant_id`、`organization_id`、`department_id`、`created_by`、`updated_by`、`deleted_at`。 - `status_label`、`status_tone`、`next_action`、`next_actions` 偏 UI 展示，不应作为核心持久化真相。 - `owner`、`requested_by`、`actor_name` 仍是字符串，不是正式用户外键或快照字段组合。 - 索引以单列索引为主，缺少工作台、合同列表、审批待办、文件仓库、审计时间线的组合索引。 - 审批流还只是 timeline 表，没有正式 `approval_instances`、`approval_steps`、`approval_actions`。 - 版本、履约、归档仍未形成正式数据库模型。 ### 4.2 AI Platform 当前表 当前 `yuqei-ai-platform/services/ai-platform-api` 已有： - `ai_provider_configs` - `prompt_templates` - `knowledge_documents` - `knowledge_import_batches` - `knowledge_chunks` - `ai_run_audits` - 质量规则、质量标签、改进项、配置变更、worker runtime 等后续表 优点： - AI 中台已经形成独立数据库迁移历史。 - 已有 `knowledge_chunks` 和 pgvector column 起点。 - AI Trace 已记录 provider、model、token、费用、检索命中、质量标签等方向。 不足： - 生产级向量索引还不完整，需要明确 HNSW/IVFFLAT 策略、维度、重建流程。 - 知识库、AI Trace、质量评测缺少统一 `tenant_id` 与访问边界。 - `knowledge_documents.content` 和 `knowledge_chunks.content` 均可能增长较快，需要全文索引、分区和冷热策略。 - `ai_run_audits` 会高频增长，应从一开始设计分区或归档。 - Prompt、模型配置应有“草稿、发布、回滚、审计、影响范围”完整版本模型。 ### 4.3 当前基础设施问题 当前本地 compose 使用一个 PostgreSQL 数据库 `yuqei_v2` 同时承载 Contract API 和 AI Platform，并通过： - `contract_api_alembic_version` - `ai_platform_alembic_version` 隔离迁移历史。 这适合本地开发，但最终生产建议改为： - `yuqei_contract`：合同业务数据库。 - `yuqei_ai`：AI 中台数据库。 - `yuqei_ops`：可选，任务、运行状态、监控、队列补偿等运行数据。 这样数据库边界和服务边界一致，避免 AI 数据膨胀拖慢合同主流程。 ## 5. V2 数据库最终目标 ### 5.1 总原则 1. PostgreSQL 16 作为唯一生产关系数据库。 2. 合同平台和 AI 中台逻辑拆库，避免数据增长互相拖累。 3. 所有核心业务表都有 `tenant_id`。 4. 所有核心表都有 `created_at`、`updated_at`、`created_by`、`updated_by`。 5. 用户可删除/撤回的数据使用 `deleted_at` 软删除。 6. 审计和 AI Trace 使用 append-only 模型，不允许物理更新业务含义。 7. 文件内容不进入数据库，只存对象存储元数据、hash、size、mime、object_key。 8. 高频时间序列表按月分区。 9. 搜索字段使用 PostgreSQL FTS，向量字段使用 pgvector。 10. 数据库迁移必须可以从空库一键执行。 ### 5.2 生产数据库边界 推荐生产结构： ```text PostgreSQL cluster yuqei_contract identity schema contract schema document schema audit schema yuqei_ai ai schema knowledge schema prompt schema audit schema yuqei_ops jobs schema runtime schema notification schema ``` 本地开发可以继续用一个数据库，但 schema 和环境变量要与生产边界保持一致。不要让本地便利破坏最终模型。 ## 6. Contract Platform 目标模型 ### 6.1 identity schema 用于企业、部门、用户、角色。 核心表： - `tenants` - `organizations` - `departments` - `users` - `tenant_memberships` - `roles` - `role_bindings` - `permission_policies` 关键字段： ```text tenant_id organization_id department_id user_id role_code status created_at updated_at deleted_at ``` 关键约束： - `users`: `(tenant_id, email)` unique - `departments`: `(tenant_id, parent_department_id, name)` index - `role_bindings`: `(tenant_id, user_id, role_code, scope_type, scope_id)` unique ### 6.2 contract schema 用于合同主数据和合同房间。 核心表： - `contracts` - `contract_parties` - `contract_versions` - `contract_sections` - `contract_comments` - `contract_status_events` - `contract_obligations` - `contract_reminders` `contracts` 不应保存 UI 展示字段。目标字段： ```text id tenant_id contract_no title contract_type counterparty_name amount_cents currency lifecycle_status review_status approval_status signing_status archive_status owner_user_id department_id current_version_id effective_at expires_at created_by updated_by created_at updated_at deleted_at ``` 说明： - `status_label`、`status_tone` 在前端或 API serializer 层生成。 - `next_action` 由后端根据状态、角色、任务计算，不作为长期真相字段。 - 合同正文进入 `contract_versions`，不要直接塞在 `contracts` 主表。 `contract_versions` 目标字段： ```text id tenant_id contract_id version_no source_type body_text body_hash created_by created_at change_summary ai_generated_run_id ``` ### 6.3 approval schema 审批流独立建模，不再只靠 timeline。 核心表： - `approval_instances` - `approval_steps` - `approval_actions` - `approval_delegations` 关键查询： - 待我审批 - 退回后重提 - 审批时间线 - 审批人处理统计 关键索引： ```sql CREATE INDEX idx_approval_steps_tenant_assignee_status_created ON approval_steps (tenant_id, assignee_user_id, status, created_at DESC); CREATE INDEX idx_approval_instances_tenant_contract_status ON approval_instances (tenant_id, contract_id, status); ``` ### 6.4 document schema 文件仓库只存元数据，不存文件正文。 核心表： - `files` - `file_links` - `file_versions` - `file_text_extractions` - `file_processing_jobs` `files` 目标字段： ```text id tenant_id bucket object_key file_name mime_type file_size sha256 file_type storage_status encryption_status uploaded_by uploaded_at deleted_at ``` 关键索引： ```sql CREATE INDEX idx_files_tenant_type_uploaded ON files (tenant_id, file_type, uploaded_at DESC) WHERE deleted_at IS NULL; CREATE INDEX idx_files_tenant_sha256 ON files (tenant_id, sha256) WHERE deleted_at IS NULL; CREATE INDEX idx_file_links_tenant_resource ON file_links (tenant_id, resource_type, resource_id, created_at DESC); ``` ### 6.5 audit schema 合同侧审计必须 append-only。 核心表： - `audit_events` - `audit_event_hash_chain` `audit_events` 目标字段： ```text id tenant_id actor_user_id actor_display_name event_type resource_type resource_id summary metadata_jsonb request_id trace_id ip_address user_agent created_at ``` 关键策略： - 禁止业务代码 update/delete 审计事件。 - 高频审计按月分区。 - 可选 hash chain：每条审计记录保存 previous_hash 与 event_hash。 ## 7. AI Platform 目标模型 ### 7.1 ai schema 核心表： - `ai_provider_configs` - `ai_provider_config_versions` - `ai_model_routes` - `ai_runs` - `ai_run_steps` - `ai_run_costs` - `ai_quality_labels` - `ai_quality_improvement_actions` `ai_runs` 目标字段： ```text id tenant_id operation caller_service caller_user_id request_id trace_id provider model prompt_template_id prompt_template_version retrieval_trace_id status latency_ms prompt_tokens completion_tokens total_tokens estimated_cost quality_status quality_score created_at ``` 关键索引： ```sql CREATE INDEX idx_ai_runs_tenant_operation_created ON ai_runs (tenant_id, operation, created_at DESC); CREATE INDEX idx_ai_runs_tenant_status_created ON ai_runs (tenant_id, status, created_at DESC); CREATE UNIQUE INDEX ux_ai_runs_request_id ON ai_runs (request_id) WHERE request_id IS NOT NULL; ``` ### 7.2 prompt schema 核心表： - `prompt_templates` - `prompt_template_versions` - `prompt_releases` - `prompt_change_audits` 原则： - Prompt 内容按版本不可变。 - 发布记录独立于草稿记录。 - AI Run 必须记录命中的 prompt name + version。 ### 7.3 knowledge schema 核心表： - `knowledge_bases` - `knowledge_documents` - `knowledge_document_versions` - `knowledge_import_batches` - `knowledge_chunks` - `knowledge_chunk_embeddings` - `retrieval_traces` - `retrieval_trace_hits` 推荐把 embedding 从 `knowledge_chunks` 中拆出： ```text knowledge_chunks id tenant_id knowledge_base_id document_id chunk_index locator content content_hash token_count index_status created_at knowledge_chunk_embeddings id tenant_id chunk_id provider model dimension embedding vector created_at ``` 这样同一个 chunk 可以支持多套 embedding 模型并行评测，避免未来换模型时覆盖历史向量。 关键索引： ```sql CREATE INDEX idx_knowledge_chunks_tenant_kb_status ON knowledge_chunks (tenant_id, knowledge_base_id, index_status, created_at DESC); CREATE INDEX idx_knowledge_chunks_fts ON knowledge_chunks USING GIN (to_tsvector('simple', content)); CREATE INDEX idx_chunk_embeddings_vector_hnsw ON knowledge_chunk_embeddings USING hnsw (embedding vector_cosine_ops); ``` 说明： - `simple` 分词只是基础方案；中文法规检索后续可评估 `zhparser`、外部搜索服务或应用层分词字段。 - pgvector 索引必须按实际维度和数据量压测后决定 HNSW 参数。 ## 8. 统一索引策略 ### 8.1 合同工作台 ```sql CREATE INDEX idx_contracts_tenant_owner_updated ON contracts (tenant_id, owner_user_id, updated_at DESC) WHERE deleted_at IS NULL; CREATE INDEX idx_contracts_tenant_lifecycle_updated ON contracts (tenant_id, lifecycle_status, updated_at DESC) WHERE deleted_at IS NULL; ``` ### 8.2 待办任务 建议独立 `work_items` 表，不要每个页面临时拼任务。 ```sql CREATE INDEX idx_work_items_tenant_assignee_status_due ON work_items (tenant_id, assignee_user_id, status, due_at ASC, updated_at DESC) WHERE deleted_at IS NULL; ``` ### 8.3 统一搜索 合同、文件、审查任务先用 PostgreSQL FTS： ```sql CREATE INDEX idx_contract_search_fts ON contract_search_documents USING GIN (search_vector); CREATE INDEX idx_contract_search_tenant_type_updated ON contract_search_documents (tenant_id, resource_type, updated_at DESC); ``` 建议建立 `contract_search_documents` 物化表或同步表，而不是每次跨 contracts/files/review_tasks 临时 OR 查询。 ### 8.4 审计时间线 ```sql CREATE INDEX idx_audit_tenant_resource_created ON audit_events (tenant_id, resource_type, resource_id, created_at DESC); CREATE INDEX idx_audit_tenant_actor_created ON audit_events (tenant_id, actor_user_id, created_at DESC); ``` 按月分区后，每个分区保留同类本地索引。 ## 9. 分区与归档策略 从 V2 正式基线开始，以下表建议设计分区能力： - `audit_events`：按月分区。 - `ai_runs`：按月分区。 - `ai_run_steps`：按月分区。 - `retrieval_traces`：按月分区。 - `file_processing_jobs`：按月分区。 - `worker_job_executions`：按月分区。 归档策略： - 热数据：最近 3 到 6 个月，在线查询。 - 温数据：6 到 24 个月，保留数据库分区但降频查询。 - 冷数据：超过 24 个月，导出到对象存储归档，保留索引摘要。 ## 10. 安全策略 ### 10.1 租户隔离 所有核心业务表必须有 `tenant_id NOT NULL`。 应用层： - 所有 repository 方法必须显式接收 tenant context。 - 禁止无 tenant context 的业务查询。 数据库层： - PostgreSQL 生产环境建议启用 RLS。 - 每个请求连接事务内设置 `app.current_tenant_id`。 示例： ```sql ALTER TABLE contracts ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation_contracts ON contracts USING (tenant_id = current_setting('app.current_tenant_id')::text); ``` ### 10.2 权限与最小账号 推荐数据库账号： - `contract_app_rw`：合同服务读写合同库。 - `contract_app_ro`：合同服务只读报表。 - `ai_app_rw`：AI 中台读写 AI 库。 - `migration_owner`：只用于 Alembic migration。 - `backup_user`：只用于备份。 应用运行账号不应拥有 DDL 权限。 ### 10.3 敏感数据 敏感字段： - 用户手机号、邮箱。 - 合同正文。 - 文件名和对象 key。 - AI prompt 输入和回答。 - 模型 API key。 要求： - API key 只保存密文或引用 secret manager key。 - AI Trace 对管理员展示时支持脱敏。 - 合同正文导出和下载进入审计。 - 数据库备份加密。 ## 11. 备份与恢复 生产基线： - 每日全量备份。 - WAL 连续归档。 - MinIO/S3 对象存储独立备份。 - 每周恢复演练。 - 备份加密和异地保存。 验收目标： - RPO：不超过 15 分钟。 - RTO：核心合同查询 2 小时内恢复。 - 单租户误删：可按 tenant + 时间点恢复。 ## 12. 当前 V2 到最终数据库的实施路径 因为当前项目未正式上线，推荐采用干净基线，而不是从当前 MVP 迁移一直叠加。 ### DB-0：数据库现状冻结 产出： - 当前 V2 migration 清单。 - 当前 V1 有价值数据清单。 - 最终需要迁移的数据类型。 建议迁移的数据： - 法规、法条、制度、模板、标准条款。 - 有价值的 Prompt、审查规则、知识库文档。 - demo 用户和 demo 合同可重建，不建议从 V1 迁移历史业务数据。 ### DB-1：建立最终数据库工程 动作： - `yuqei_contract` 和 `yuqei_ai` 使用独立 DATABASE_URL。 - Contract API 和 AI Platform 使用独立 Alembic 目录和迁移。 - compose 改为两个数据库或两个 Postgres database。 - 生产禁用 auto create，只能 Alembic migration。 ### DB-2：Contract Platform 干净基线 动作： - 重建合同侧 `0001_v2_contract_baseline`。 - 引入 `tenants/users/roles` 基础模型。 - 重构 `contracts`，移除 UI 展示字段。 - 增加 `contract_versions`、`work_items`、`approval_instances/steps/actions`。 - 增加 `files/file_links/file_text_extractions`。 - 增加 `audit_events` append-only。 ### DB-3：AI Platform 干净基线 动作： - 重建 AI 侧 `0001_v2_ai_baseline`。 - 增加 provider config version/release。 - 增加 prompt version/release。 - 拆分 knowledge chunk 和 embedding。 - 增加 retrieval trace/hits。 - 增加 ai_runs/ai_run_steps/quality_labels。 - 明确 pgvector extension 和 HNSW 索引。 ### DB-4：Repository 全面 tenant 化 动作： - 所有 repository 方法增加 tenant context。 - 所有 API 入口解析 current tenant。 - 所有测试补 tenant 隔离场景。 - 禁止直接用字符串 actor_name 作为业务主体，保留 actor_display_name 作为快照字段。 ### DB-5：搜索与性能基线 动作： - 建立 `contract_search_documents`。 - 建立 FTS 索引。 - 建立核心组合索引。 - 为工作台、合同列表、审批待办、文件仓库、统一搜索写 EXPLAIN 验证。 ### DB-6：安全与备份基线 动作： - RLS 策略。 - 只读/读写/migration 数据库账号。 - 备份脚本。 - 恢复演练脚本。 - 审计表 append-only 限制。 ## 13. 性能验收指标 开发阶段建议使用以下目标压测： | 场景 | 数据量 | 目标 | |---|---:|---:| | 工作台待办 | 100 万 work_items | P95 < 150ms | | 合同列表 | 100 万 contracts | P95 < 200ms | | 合同详情 | 10 万 contracts + versions | P95 < 250ms | | 审批待办 | 100 万 approval_steps | P95 < 150ms | | 文件仓库 | 100 万 files | P95 < 200ms | | 审计时间线 | 1000 万 audit_events | P95 < 300ms | | 统一搜索 FTS | 100 万 search docs | P95 < 500ms | | 知识库向量检索 | 100 万 chunks | P95 < 800ms | | AI Trace 列表 | 1000 万 ai_runs | P95 < 300ms | ## 14. 当前最优下一步 下一轮建议直接进入 DB-0 / DB-1： 1. 新增 `yuqei-infra/compose` 中的双数据库配置： - `yuqei_contract` - `yuqei_ai` 2. 新增 Contract API 最终 baseline migration 草案。 3. 新增 AI Platform 最终 baseline migration 草案。 4. 把当前 MVP migration 标记为重构前临时迁移，不继续作为最终生产基线。 5. 写 Postgres 集成测试策略，减少对 SQLite 的关键路径依赖。 这一步完成后，V2 后面的合同主流程、AI 中台、知识库、审计和权限都会建立在干净数据库地基上，不会把 V1 的历史包袱带进新版本。