# AI 服务数据库初始化设计

> **日期**：2026-02-03  
> **类型**：数据库设计  
> **影响范围**：AI 服务模块  
> **符合规范**：jointo-tech-stack v1.0

---

## 变更概述

完成 AI 服务数据库初始化设计文档，包括技术栈符合性检查、表结构设计、关联关系梳理、初始化顺序和迁移建议。

---

## 变更内容

### 1. 技术栈符合性检查

✅ **完全符合 jointo-tech-stack 规范**：
- UUID v7 主键（应用层生成）
- TIMESTAMPTZ 时间字段
- SMALLINT 枚举类型（Python IntEnum）
- 无物理外键约束
- 应用层保证引用完整性
- JSONB 元数据 + GIN 索引
- 完整的字段注释

### 2. 数据库表结构

设计了 7 张核心表：

1. **ai_jobs**（AI 任务表）
   - 记录所有 AI 生成任务
   - 支持 9 种任务类型（图片、视频、音效、配音、字幕、文本处理、资源、分镜脚本、剧本生成）
   - 5 种任务状态（等待、处理中、完成、失败、取消）

2. **ai_models**（AI 模型配置表）
   - 管理可用的 AI 模型
   - 支持 10+ 种 AI 提供商
   - 动态定价配置

3. **ai_usage_logs**（AI 使用日志表）
   - 记录每次 AI 调用
   - 支持成本分析和账单生成

4. **ai_quotas**（AI 配额表）
   - 管理用户配额
   - 支持每日/每月/总配额

5. **ai_conversations**（AI 对话会话表）
   - 多态关联 + 标签系统
   - 支持 7 种目标类型
   - 支持 5 种媒体类型

6. **ai_conversation_messages**（AI 对话消息表）
   - 记录对话消息
   - 支持提及功能（@ 引用资源）

7. **ai_prompts_system**（AI 提示词系统表）
   - 系统级提示词管理
   - 版本控制
   - Skills 配置

### 3. 表关联关系

- **ai_jobs** ← users, ai_models, projects, storyboards, credit_consumption_logs
- **ai_usage_logs** ← ai_jobs, ai_models, users
- **ai_quotas** ← users
- **ai_conversations** ← users, projects, target_objects (多态)
- **ai_conversation_messages** ← ai_conversations, ai_jobs

### 4. 初始化顺序

```sql
-- 1. 基础表
CREATE TABLE ai_models;
CREATE TABLE ai_prompts_system;

-- 2. 用户相关表
CREATE TABLE ai_quotas;

-- 3. 任务相关表
CREATE TABLE ai_jobs;
CREATE TABLE ai_usage_logs;

-- 4. 对话相关表
CREATE TABLE ai_conversations;
CREATE TABLE ai_conversation_messages;
```

### 5. 应用层引用完整性保证

- Service 层验证所有关联 ID
- Repository 层提供 `exists()` 方法
- 使用数据库事务确保原子性
- 定期检查孤儿记录并告警

---

## 技术亮点

1. **多态关联设计**：ai_conversations 表使用 target_type + target_id + tag_id 实现灵活的多态关联
2. **标签系统集成**：支持同一对象的不同变体（如角色装扮、分镜角度）
3. **唯一性约束**：使用 NULLS NOT DISTINCT 确保唯一性约束正确处理 NULL 值
4. **自动触发器**：自动更新 updated_at 和会话统计信息
5. **GIN 索引优化**：为 JSONB 字段和全文搜索创建 GIN 索引
6. **部分索引**：使用 WHERE 子句创建部分索引，减少索引大小

---

## 性能优化

1. **索引策略**：
   - 复合索引优化常用查询
   - 部分索引减少索引大小
   - GIN 索引提升 JSON 查询性能

2. **分区建议**：
   - ai_usage_logs 按月分区
   - ai_conversation_messages 按对话分区

3. **连接池配置**：
   - pool_size=20
   - max_overflow=10
   - pool_recycle=3600

---

## 迁移步骤

### 首次部署

```bash
# 1. 创建迁移文件
docker exec jointo-server-app alembic revision --autogenerate -m "create_ai_service_tables"

# 2. 检查迁移文件
# 确认表结构、索引、约束、触发器

# 3. 执行迁移
docker exec jointo-server-app alembic upgrade head

# 4. 验证表结构
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d ai_jobs"
```

### 后续演进

- 添加新的任务类型：修改枚举 + 更新 CHECK 约束
- 添加新的 AI 提供商：修改枚举 + 添加模型配置
- 优化索引：根据实际查询模式调整
- 分区策略：按月分区历史数据

---

## 相关文档

- [AI 服务文档](../../../requirements/backend/04-services/ai/ai-service.md)
- [AI 对话服务文档](../../../requirements/backend/04-services/ai/ai-conversation-service.md)
- [AI 对话提及系统文档](../../../requirements/backend/04-services/ai/ai-conversation-mention-system.md)
- [AI 提示词系统文档](../../../requirements/backend/04-services/ai/ai-prompt-system-service.md)
- [数据库初始化设计](../../../requirements/backend/04-services/ai/database-init.md)

---

## 检查清单

- [x] 技术栈符合性检查完成
- [x] 7 张表结构设计完成
- [x] 表关联关系梳理完成
- [x] 初始化顺序确定
- [x] 迁移建议提供
- [x] 应用层验证逻辑设计
- [x] 性能优化建议提供
- [x] 文档创建完成

---

**变更人**：资深后端架构师  
**审核人**：待审核  
**状态**：已完成