# AI 提示词系统表创建

> **日期**：2026-02-03  
> **类型**：数据库迁移  
> **影响范围**：AI 提示词管理  
> **迁移文件**：
> - `20260203_1500_create_ai_prompts_system_table.py`
> - `20260203_1510_add_ai_prompt_to_storyboard_images.py`

---

## 变更概述

创建 AI 提示词系统表 (`ai_prompts_system`)，用于系统级的 AI 提示词管理，支持版本控制、Skills 配置和默认提示词机制。

---

## 数据库变更

### 1. 新建表：ai_prompts_system

**用途**：系统级 AI 提示词管理

**字段列表**（11 个字段）：

| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|--------|------|------|--------|------|
| prompt_id | UUID | PRIMARY KEY | - | 提示词唯一标识符（UUID v7） |
| name | TEXT | NOT NULL | - | 提示词名称 |
| prompt_type | SMALLINT | NOT NULL | - | 提示词类型（1-7） |
| prompt_content | TEXT | NOT NULL | - | 提示词内容 |
| skills_data | JSONB | NOT NULL | `{"skills": []}` | Skills 配置 |
| version | TEXT | NOT NULL | - | 版本号（如 1.0.0） |
| description | TEXT | NULL | - | 提示词说明 |
| is_active | BOOLEAN | NOT NULL | true | 是否启用 |
| is_default | BOOLEAN | NOT NULL | false | 是否为默认提示词 |
| created_at | TIMESTAMPTZ | NOT NULL | now() | 创建时间 |
| updated_at | TIMESTAMPTZ | NOT NULL | now() | 最后更新时间 |

**枚举值映射（prompt_type）**：

| 枚举值 | 说明 |
|--------|------|
| 1 | 剧本解析 (SCREENPLAY) |
| 2 | 分镜生成 (STORYBOARD) |
| 3 | 角色生成 (CHARACTER) |
| 4 | 场景生成 (SCENE) |
| 5 | 道具生成 (PROP) |
| 6 | 资源生成 (RESOURCE) |
| 7 | 通用 (GENERAL) |

**约束**：

1. **唯一约束**：
   - `ai_prompts_system_name_version_unique`：同一名称的不同版本唯一
   - `ai_prompts_system_default_unique`：每种类型只能有一个激活的默认提示词

2. **检查约束**：
   - `ai_prompts_system_prompt_type_check`：prompt_type 必须在 1-7 之间

**索引**（9 个）：

| 索引名 | 类型 | 字段 | 条件 | 说明 |
|--------|------|------|------|------|
| ai_prompts_system_pkey | BTREE | prompt_id | - | 主键索引 |
| ai_prompts_system_default_unique | BTREE | prompt_type, is_default | is_default=true AND is_active=true | 默认提示词唯一索引 |
| idx_ai_prompts_system_type | BTREE | prompt_type | - | 类型查询索引 |
| idx_ai_prompts_system_is_active | BTREE | is_active | is_active=true | 激活状态索引 |
| idx_ai_prompts_system_is_default | BTREE | is_default | is_default=true | 默认状态索引 |
| idx_ai_prompts_system_name | BTREE | name | - | 名称查询索引 |
| idx_ai_prompts_system_type_active | BTREE | prompt_type, is_active | is_active=true | 组合查询索引 |
| idx_ai_prompts_system_skills_data_gin | GIN | skills_data | - | JSONB 查询索引 |
| idx_ai_prompts_system_name_trgm | GIN | name (gin_trgm_ops) | - | 全文搜索索引 |

**触发器**：

- `update_ai_prompts_system_updated_at`：自动更新 updated_at 字段

**skills_data 结构示例**：

```json
{
  "skills": [
    {
      "skill_name": "jointo-tech-stack",
      "file_path": ".claude/skills/jointo-tech-stack/references/database.md",
      "url": "https://example.com/skills/jointo-tech-stack",
      "version": "1.0",
      "enabled": true,
      "priority": 1,
      "description": "项目技术栈规范"
    }
  ]
}
```

### 2. 修改表：storyboard_images

**新增字段**：

| 字段名 | 类型 | 约束 | 默认值 | 说明 |
|--------|------|------|--------|------|
| ai_prompt_id | UUID | NULL | - | AI 提示词 ID（应用层验证，可选） |

**新增索引**：

- `idx_storyboard_images_ai_prompt_id`：ai_prompt_id 索引（WHERE ai_prompt_id IS NOT NULL）

---

## 技术规范

### 符合 jointo-tech-stack 规范

✅ **UUID v7 主键**：应用层生成，时间有序  
✅ **SMALLINT 枚举**：prompt_type 使用 SMALLINT 存储（1-7）  
✅ **TIMESTAMPTZ 时间**：created_at、updated_at 使用 TIMESTAMPTZ  
✅ **无物理外键**：应用层保证引用完整性  
✅ **完整注释**：表和所有列都有中文注释  
✅ **索引优化**：包括 BTREE、GIN、部分索引  
✅ **触发器**：自动更新 updated_at  

### 设计特点

1. **版本管理**：
   - name + version 唯一约束
   - 支持多版本共存
   - 版本激活和回滚

2. **默认提示词机制**：
   - 每种类型只能有一个激活的默认提示词
   - 部分唯一索引保证约束

3. **Skills 配置**：
   - JSONB 存储灵活配置
   - GIN 索引支持高效查询
   - 支持多个 skill 组合

4. **软禁用**：
   - 使用 is_active 字段
   - 不物理删除数据
   - 部分索引排除禁用记录

5. **全文搜索**：
   - pg_trgm 扩展支持
   - 提示词名称模糊搜索

---

## 使用场景

### 1. 系统管理员创建提示词

```python
from app.services.ai_prompt_system_service import AIPromptSystemService
from app.models.ai_prompt_system import PromptType

prompt_data = AIPromptSystemCreate(
    name="剧本解析提示词",
    prompt_type=PromptType.SCREENPLAY,
    prompt_content="你是一个专业的剧本解析助手...",
    skills_data={
        "skills": [
            {
                "skill_name": "jointo-tech-stack",
                "file_path": ".claude/skills/jointo-tech-stack/references/database.md",
                "version": "1.0",
                "enabled": True,
                "priority": 1
            }
        ]
    },
    version="1.0.0",
    is_default=True
)

prompt = await prompt_service.create_prompt(prompt_data)
```

### 2. AI Service 调用提示词

```python
# 获取默认提示词
prompt = await prompt_service.get_default_prompt(PromptType.SCREENPLAY)

# 构建完整提示词（包含 skills）
full_prompt = build_prompt_with_skills(
    prompt.prompt_content,
    prompt.skills_data
)

# 调用 AI 模型
result = await ai_model.generate(full_prompt, screenplay_content)
```

### 3. 版本管理

```python
# 创建新版本
new_prompt = await prompt_service.create_version(
    base_prompt_id=prompt.prompt_id,
    new_version="1.1.0",
    prompt_content="优化后的提示词内容..."
)

# 设置为默认
await prompt_service.set_default(new_prompt.prompt_id)

# 查看版本历史
versions = await prompt_service.get_versions("剧本解析提示词")
```

---

## 迁移执行

### 执行命令

```bash
# 在容器内执行迁移
docker exec jointo-server-app python scripts/db_migrate.py upgrade
```

### 执行结果

```
✓ 创建表 ai_prompts_system
✓ 创建 9 个索引
✓ 创建 2 个唯一约束
✓ 创建 1 个检查约束
✓ 创建 1 个触发器
✓ 添加 11 个列注释
✓ 添加表注释
✓ 为 storyboard_images 添加 ai_prompt_id 字段
✓ 创建 ai_prompt_id 索引

当前版本：20260203_1510
```

### 验证查询

```sql
-- 查看表结构
\d ai_prompts_system

-- 查看索引
SELECT indexname, indexdef 
FROM pg_indexes 
WHERE tablename = 'ai_prompts_system';

-- 查看约束
SELECT conname, contype, pg_get_constraintdef(oid) 
FROM pg_constraint 
WHERE conrelid = 'ai_prompts_system'::regclass;

-- 查看注释
SELECT column_name, col_description('ai_prompts_system'::regclass, ordinal_position) 
FROM information_schema.columns 
WHERE table_name = 'ai_prompts_system';
```

---

## 相关文档

- **服务文档**：`docs/requirements/backend/04-services/ai/ai-prompt-system-service.md` (v1.1)
- **技术规范**：jointo-tech-stack skill
- **ADR 参考**：
  - ADR 001：UUID v7 迁移
  - ADR 006：TIMESTAMPTZ 时间戳规范

---

## 后续工作

### 代码实现

1. **Model 层**：
   - [ ] 创建 `app/models/ai_prompt_system.py`
   - [ ] 定义 PromptType 枚举
   - [ ] 定义 AIPromptSystem 模型

2. **Repository 层**：
   - [ ] 创建 `app/repositories/ai_prompt_system_repository.py`
   - [ ] 实现 CRUD 操作
   - [ ] 实现版本管理方法

3. **Service 层**：
   - [ ] 创建 `app/services/ai_prompt_system_service.py`
   - [ ] 实现业务逻辑
   - [ ] 实现 Skills 配置验证

4. **Schema 层**：
   - [ ] 创建 `app/schemas/ai_prompt_system.py`
   - [ ] 定义请求/响应 Schema

5. **API 层**：
   - [ ] 创建 `app/api/v1/admin/ai_prompts.py`
   - [ ] 实现管理员接口
   - [ ] 创建 `app/api/v1/ai_prompts.py`
   - [ ] 实现公开接口（获取默认提示词）

### 集成工作

1. **AI Service 集成**：
   - [ ] 修改 AI Service 调用提示词系统
   - [ ] 实现 Skills 加载逻辑
   - [ ] 实现提示词构建逻辑

2. **剧本解析集成**：
   - [ ] 剧本解析使用提示词系统
   - [ ] 记录使用的提示词 ID

3. **分镜生成集成**：
   - [ ] 分镜图片生成使用提示词系统
   - [ ] 记录 ai_prompt_id 到 storyboard_images

---

## 变更历史

**2026-02-03**：
- ✅ 创建 ai_prompts_system 表
- ✅ 为 storyboard_images 添加 ai_prompt_id 字段
- ✅ 创建完整的索引和约束
- ✅ 添加表和列注释
- ✅ 符合 jointo-tech-stack 规范

---

**文档版本**：v1.0  
**最后更新**：2026-02-03  
**迁移版本**：20260203_1500, 20260203_1510