# AI Prompt System 版本管理功能实现

> **变更日期**：2026-02-04  
> **变更类型**：功能增强  
> **影响范围**：AI Prompt System 服务  
> **符合规范**：jointo-tech-stack v1.0

---

## 变更概述

实现 AI Prompt System 服务的版本管理功能，包括创建新版本和获取版本历史。

---

## 变更详情

### 1. Service 层新增方法

**文件**：`server/app/services/ai_prompt_system_service.py`

#### 1.1 `create_version()` 方法

```python
async def create_version(
    self,
    base_prompt_id: UUID,
    new_version: str,
    prompt_content: Optional[str] = None,
    skills_data: Optional[Dict[str, Any]] = None,
    description: Optional[str] = None
) -> Dict[str, Any]:
    """基于现有提示词创建新版本"""
```

**功能**：
- 基于现有提示词创建新版本
- 支持继承或覆盖提示词内容
- 支持继承或覆盖 skills 配置
- 新版本默认不是默认提示词
- 自动生成描述（如未提供）

**验证**：
- 检查基础提示词是否存在
- 检查新版本号是否已存在
- 验证 skills_data 格式（如果提供）

#### 1.2 `get_versions()` 方法

```python
async def get_versions(
    self,
    name: str
) -> List[Dict[str, Any]]:
    """获取提示词的所有版本"""
```

**功能**：
- 根据提示词名称获取所有版本
- 按创建时间倒序排列
- 返回格式化的列表项

### 2. API 层新增接口

**文件**：`server/app/api/v1/ai_prompts.py`

#### 2.1 创建新版本接口

```
POST /api/v1/admin/ai-prompts/{prompt_id}/versions
```

**权限**：系统管理员

**请求体**：
```json
{
  "new_version": "1.1.0",
  "prompt_content": "新版本内容（可选）",
  "skills_data": {"skills": []},  // 可选
  "description": "版本说明（可选）"
}
```

**响应**：
```json
{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    "prompt_id": "019d...",
    "name": "剧本提示词",
    "version": "1.1.0",
    "prompt_content": "新版本内容",
    ...
  }
}
```

#### 2.2 获取版本历史接口

```
GET /api/v1/admin/ai-prompts/versions?name=剧本提示词
```

**权限**：系统管理员

**查询参数**：
- `name`：提示词名称（必需）

**响应**：
```json
{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": [
    {
      "prompt_id": "019d...",
      "name": "剧本提示词",
      "version": "1.2.0",
      "is_active": true,
      "is_default": true,
      "created_at": "2026-02-04T10:00:00Z"
    },
    {
      "prompt_id": "019d...",
      "name": "剧本提示词",
      "version": "1.1.0",
      "is_active": true,
      "is_default": false,
      "created_at": "2026-02-03T10:00:00Z"
    }
  ]
}
```

---

## 使用示例

### 1. 创建新版本

```python
# 基于现有提示词创建新版本
service = AIPromptSystemService(db)

new_version = await service.create_version(
    base_prompt_id=base_prompt_id,
    new_version="1.1.0",
    prompt_content="优化后的提示词内容",
    description="版本 1.1.0：优化了角色识别逻辑"
)
```

### 2. 获取版本历史

```python
# 获取提示词的所有版本
versions = await service.get_versions("剧本解析提示词")

for version in versions:
    print(f"版本 {version['version']}: {version['description']}")
```

### 3. API 调用示例

```bash
# 创建新版本
curl -X POST "http://localhost:6170/api/v1/admin/ai-prompts/{prompt_id}/versions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_version": "1.1.0",
    "prompt_content": "优化后的内容",
    "description": "版本 1.1.0 更新"
  }'

# 获取版本历史
curl -X GET "http://localhost:6170/api/v1/admin/ai-prompts/versions?name=剧本提示词" \
  -H "Authorization: Bearer {token}"
```

---

## 技术规范合规性

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

- ✅ 异步操作（async/await）
- ✅ %-formatting 日志格式
- ✅ exc_info=True 错误日志
- ✅ 完整的类型注解
- ✅ 完整的异常处理
- ✅ 事务管理（commit/rollback）
- ✅ 统一响应格式
- ✅ UUID v7 主键生成
- ✅ TIMESTAMPTZ 时间戳

---

## 测试覆盖

### Service 层测试

- ✅ 创建新版本成功
- ✅ 基础提示词不存在
- ✅ 创建重复版本失败
- ✅ 继承内容和配置
- ✅ 获取版本历史成功
- ✅ 获取空版本历史

### API 层测试

- ✅ 创建新版本成功
- ✅ 创建重复版本失败
- ✅ 获取版本历史成功
- ✅ 未认证访问失败

---

## 影响范围

### 新增功能

- ✅ Service: `create_version()` 方法
- ✅ Service: `get_versions()` 方法
- ✅ API: `POST /admin/ai-prompts/{prompt_id}/versions`
- ✅ API: `GET /admin/ai-prompts/versions`

### 无破坏性变更

- 现有 API 接口保持不变
- 现有数据库结构无需修改
- 向后兼容

---

## 后续优化建议

1. **版本对比功能**
   - 实现版本内容对比
   - 显示版本差异

2. **版本回滚**
   - 支持回滚到指定版本
   - 自动创建回滚版本

3. **版本标签**
   - 支持为版本添加标签（如 stable、beta）
   - 支持按标签查询版本

---

**变更日期**：2026-02-04  
**变更类型**：功能增强  
**符合规范**：jointo-tech-stack v1.0