yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
5.3 KiB
5.3 KiB
AI 合同平台 V2 数据库性能基线推进记录
日期：2026-06-24
本轮结论
对照《AI 合同平台 V2 数据库优化重构方案》，当前数据库重构没有跑偏。
已经完成：
- DB-0：数据库现状冻结，已形成当前状态记录。
- DB-1：最终数据库工程基线，已推进到合同库、AI 库、运维库三库边界，合同 API 与 AI Platform 分别维护 Alembic 链。
- DB-5 的一部分：补齐当前 MVP 查询路径的核心组合索引、PostgreSQL 模糊检索索引、知识库向量检索索引的可恢复基线。
仍未完成：
- DB-2：Contract Platform 清洁领域模型仍未完全落地，包括 tenant、用户、角色、审批实例、审批步骤、正式合同版本、履约义务、归档等最终表模型。
- DB-3：AI Platform 清洁领域模型仍未完全落地，包括 tenant 隔离、AI run step、retrieval trace/hit、结构化质量标签等最终表模型。
- DB-4：全表租户隔离与权限边界尚未完成。
- DB-5：还缺 EXPLAIN 级别的真实 PostgreSQL 查询计划验证、慢查询样本、数据量压测。
- DB-6：RLS、独立数据库账号、备份恢复演练、append-only 审计约束尚未完成。
本轮完成内容
合同库
新增迁移：
yuqei-contract-platform/services/contract-api/migrations/versions/20260624_0008_add_database_performance_indexes.py
覆盖当前主流程查询：
- 合同列表：
status + updated_at + id - 我的合同/负责人视角：
owner + updated_at + id - 审批时间线：
contract_id + created_at + id - 合同审计时间线：
contract_id + created_at + id - 审计类型筛选：
event_type + created_at + id - 合同附件列表：
related_contract_id + uploaded_at + id - 附件状态筛选：
status + uploaded_at + id - 审查任务列表：
contract_id + created_at + id - worker 领取队列：
status + created_at + id - 审查任务状态页：
status + updated_at + id
PostgreSQL 环境下额外启用 pg_trgm，为当前 ILIKE '%keyword%' 搜索补充 GIN trigram 索引：
- 合同标题、相对方、负责人、正文摘要、正文内容
- 附件名称、上传人
- 审查任务标题、摘要、发起人
AI 库
新增迁移：
yuqei-ai-platform/services/ai-platform-api/migrations/versions/20260624_0015_add_database_performance_indexes.py
覆盖当前 AI 中台高频查询：
- 模型参数发布记录：provider config + created_at
- Prompt 发布记录：template/version/name/operation + created_at
- 知识库文档：knowledge_base/status/import_batch + created_at
- 知识库 chunk：knowledge_base/document/import_batch/chunk_index
- 知识库重建索引记录：knowledge_base/import_batch/status + created_at
- 知识库导入 worker 队列：status/knowledge_base/import_batch + updated_at
- AI Trace：operation/status/quality/provider/model/prompt/provider_config + created_at
- 质量改进项：status/owner/action_type/dimension/key/prompt/knowledge_base/import_batch + updated_at
- worker 手动执行记录：worker/status + started_at
PostgreSQL 环境下额外启用：
pg_trgm：用于知识库标题、引用、正文，以及 AI 问题/回答的模糊检索。vector：用于知识库 chunk 的 pgvector 检索。ix_knowledge_chunks_embedding_hnsw：针对默认 64 维 embedding 的 HNSW 索引。该索引使用可恢复执行方式，如果目标 PostgreSQL/pgvector 版本不支持表达式 HNSW，不阻断迁移，后续可在 embedding 维度最终标准化后强制收口。
迁移工程修复
AI Platform Alembic 入口补齐 SQLite 父目录创建：
yuqei-ai-platform/services/ai-platform-api/migrations/env.pyyuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/repository.py
这样本地和 CI 可以直接用空 SQLite 文件验证完整 Alembic 链，不会因为 .runtime 目录不存在失败。
验证结果
已通过：
python -m py_compile新增迁移与 AI repository/Alembic env- 合同库空 SQLite 迁移到 head
- AI 库空 SQLite 迁移到 head
- 索引名长度检查：新增索引均不超过 PostgreSQL 63 字符限制
python -m pytest yuqei-contract-platform\services\contract-api\tests -q：24 passedpython -m pytest yuqei-ai-platform\services\ai-platform-api\tests -q：37 passedpython -m pytest yuqei-ai-platform\services\worker\tests -q：5 passed- V2 smoke Docker 从空库重建并通过：
project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-06-24T18-23-45 - 真实 PostgreSQL 检查：
- 合同库 Alembic 版本：
20260624_0008 - AI 库 Alembic 版本：
20260624_0015 - 合同库存在组合索引和
pg_trgm扩展 - AI 库存在组合索引、
pg_trgm、vector扩展和ix_knowledge_chunks_embedding_hnsw
- 合同库 Alembic 版本：
未在本轮执行：
- 大数据量 EXPLAIN ANALYZE。
- 慢查询采样和压测。
下一步建议
下一轮建议继续 DB-5 的真实 PostgreSQL 验证：
- 在 V2 smoke Docker 环境从空库执行合同库和 AI 库迁移。
- 检查
pg_trgm、vector、HNSW 索引创建状态。 - 插入或导入一批合同、文件、审查任务、知识库 chunk、AI Trace 样本。
- 对合同列表、统一搜索、AI Trace 看板、知识库检索、worker 队列领取执行
EXPLAIN ANALYZE。 - 形成
V2-database-postgresql-explain-baseline文档。
DB-5 真实验证完成后，再进入 DB-2/DB-3 的领域模型重构会更稳。