8.9 KiB

Raw Blame History

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)

约束：

唯一约束：
- ai_prompts_system_name_version_unique：同一名称的不同版本唯一
- ai_prompts_system_default_unique：每种类型只能有一个激活的默认提示词
检查约束：
- 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 结构示例：

{
  "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

设计特点

版本管理：
- name + version 唯一约束
- 支持多版本共存
- 版本激活和回滚
默认提示词机制：
- 每种类型只能有一个激活的默认提示词
- 部分唯一索引保证约束
Skills 配置：
- JSONB 存储灵活配置
- GIN 索引支持高效查询
- 支持多个 skill 组合
软禁用：
- 使用 is_active 字段
- 不物理删除数据
- 部分索引排除禁用记录
全文搜索：
- pg_trgm 扩展支持
- 提示词名称模糊搜索

使用场景

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

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 调用提示词

# 获取默认提示词
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. 版本管理

# 创建新版本
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("剧本解析提示词")

迁移执行

执行命令

# 在容器内执行迁移
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

验证查询

-- 查看表结构
\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';

后续工作

代码实现

Model 层：
- 创建 app/models/ai_prompt_system.py
- 定义 PromptType 枚举
- 定义 AIPromptSystem 模型
Repository 层：
- 创建 app/repositories/ai_prompt_system_repository.py
- 实现 CRUD 操作
- 实现版本管理方法
Service 层：
- 创建 app/services/ai_prompt_system_service.py
- 实现业务逻辑
- 实现 Skills 配置验证
Schema 层：
- 创建 app/schemas/ai_prompt_system.py
- 定义请求/响应 Schema
API 层：
- 创建 app/api/v1/admin/ai_prompts.py
- 实现管理员接口
- 创建 app/api/v1/ai_prompts.py
- 实现公开接口（获取默认提示词）

集成工作

AI Service 集成：
- 修改 AI Service 调用提示词系统
- 实现 Skills 加载逻辑
- 实现提示词构建逻辑
剧本解析集成：
- 剧本解析使用提示词系统
- 记录使用的提示词 ID
分镜生成集成：
- 分镜图片生成使用提示词系统
- 记录 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

8.9 KiB Raw Blame History