yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
176 lines
7.5 KiB
Markdown
176 lines
7.5 KiB
Markdown
# 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 请求。
|
||
- 批量导入、批量下载、批量导出必须有任务状态，不做长时间同步请求。
|
||
|
||
## 环境变量基线
|
||
|
||
本地默认：
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
生产默认：
|
||
|
||
```text
|
||
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 启动与迁移验证。
|