# 提示词模板管理 API 文档

> 供前端对接使用 | 更新时间：2025-11-27

## 概述

提示词模板管理模块提供对 `prompt_templates` 表的完整 CRUD 操作，用于管理 LLM/VLM 抽取、评查、摘要等场景的提示词模板。

**基础路径**: `/api/v3/prompt-templates`

**认证方式**: Bearer Token (JWT)

---

## 快速开始

### 典型前端页面流程

```
1. 页面加载 → 调用 GET /types 获取类型列表（用于筛选下拉框）
2. 列表展示 → 调用 GET / 获取模板列表（支持分页、筛选、搜索）
3. 查看详情 → 调用 GET /{id} 获取完整模板内容
4. 编辑保存 → 调用 PUT /{id} 更新模板
5. 创建模板 → 调用 POST / 或 POST /{id}/duplicate 复制
6. 删除模板 → 调用 DELETE /{id}
```

---

## 字段说明

### template_type（模板类型）

用于标识模板的业务用途类别，支持按类型筛选。

| 值 | 显示名称 | 说明 |
|---|---|---|
| `LLM_Extraction` | LLM抽取 | LLM文档内容抽取 |
| `VLM_Extraction` | VLM抽取 | VLM图像识别抽取 |
| `Summary` | 摘要生成 | 文档摘要生成 |
| `Evaluation` | 评查 | 评查规则判断 |
| `Directory_Extraction` | 目录抽取 | 卷宗目录提取 |
| `CaseNum_Extraction` | 案号抽取 | 案件编号提取 |
| `Contract_Directory_Extraction` | 合同目录抽取 | 合同目录提取 |
| `Contract_Number` | 合同编号抽取 | 合同编号提取 |
| `Contract_Compare` | 合同比对 | 合同差异比对 |
| `Parties_Extraction` | 当事人抽取 | 当事人信息提取 |
| `Common` | 通用 | 通用模板 |

### template_code（模板代码）

模板的**唯一标识符**，用于在配置中引用模板。

- 格式要求：英文字母、数字、下划线，最大50字符
- 示例：`vlm_default_prompt`, `llm_general_extract`, `vlm_currency_prompt`

### status（状态）

| 值 | 说明 | 前端显示建议 |
|---|---|---|
| `0` | 停用 | 灰色标签 "停用" |
| `1` | 启用 | 绿色标签 "启用" |
| `2` | 系统预设 | 蓝色标签 "系统" + 禁用编辑/删除按钮 |

### variables（变量定义）

定义模板中可替换的变量，格式为 JSON 对象。

```json
{
    "doc_name": "文档名称",
    "json_template": "JSON输出模板",
    "field_list": "字段列表"
}
```

模板内容中使用 `{变量名}` 引用变量，如：`请分析{doc_name}中的内容...`

---

## API 接口详细

### 1. 获取模板列表

用于列表页展示，支持分页、筛选、搜索。

**请求**

```http
GET /api/v3/prompt-templates?page=1&page_size=20&template_type=VLM_Extraction&status=1&search=通用
Authorization: Bearer {token}
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | int | 否 | 1 | 页码，从1开始 |
| page_size | int | 否 | 20 | 每页数量，最大100 |
| template_type | string | 否 | - | 模板类型筛选 |
| status | int | 否 | - | 状态筛选（0/1/2） |
| search | string | 否 | - | 模糊搜索（匹配名称或代码） |

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "total": 25,
        "page": 1,
        "page_size": 20,
        "items": [
            {
                "id": 7,
                "template_name": "VLM通用卷宗抽取Prompt",
                "template_code": "vlm_default_prompt",
                "template_type": "VLM_Extraction",
                "description": "通用VLM图像抽取模板",
                "template_abbreviation": null,
                "status": 1,
                "created_by": 1,
                "created_at": "2025-01-15T10:30:00",
                "updated_at": "2025-01-20T14:20:00"
            }
        ]
    }
}
```

**前端表格列建议**

| 列名 | 字段 | 宽度 | 说明 |
|------|------|------|------|
| ID | id | 80px | 可排序 |
| 模板名称 | template_name | 200px | 可搜索 |
| 模板代码 | template_code | 180px | 可复制 |
| 类型 | template_type | 120px | 显示为标签 |
| 状态 | status | 80px | 显示为标签 |
| 更新时间 | updated_at | 160px | 格式化显示 |
| 操作 | - | 150px | 查看/编辑/复制/删除 |

**权限要求**: `prompt_template:list:read`

---

### 2. 获取模板类型列表

用于筛选下拉框，返回所有类型及其数量。

**请求**

```http
GET /api/v3/prompt-templates/types
Authorization: Bearer {token}
```

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "items": [
            {"value": "VLM_Extraction", "label": "VLM抽取", "count": 8},
            {"value": "LLM_Extraction", "label": "LLM抽取", "count": 5},
            {"value": "Summary", "label": "摘要生成", "count": 2},
            {"value": "Evaluation", "label": "评查", "count": 2}
        ]
    }
}
```

**前端下拉框渲染**

```jsx
// 示例：Ant Design Select
<Select placeholder="选择模板类型">
    {types.map(item => (
        <Option key={item.value} value={item.value}>
            {item.label} ({item.count})
        </Option>
    ))}
</Select>
```

**权限要求**: `prompt_template:list:read`

---

### 3. 获取模板详情

用于查看/编辑页面，返回完整模板内容。

**请求**

```http
GET /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}
```

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 7,
        "template_name": "VLM通用卷宗抽取Prompt",
        "template_code": "vlm_default_prompt",
        "template_type": "VLM_Extraction",
        "template_content": "请分析以下图片内容，按照指定的JSON格式提取{doc_name}的信息...",
        "description": "通用VLM图像抽取模板",
        "template_abbreviation": null,
        "variables": {
            "doc_name": "文档名称",
            "json_template": "JSON模板"
        },
        "status": 1,
        "is_active": true,
        "created_by": 1,
        "created_at": "2025-01-15T10:30:00",
        "updated_at": "2025-01-20T14:20:00"
    }
}
```

**权限要求**: `prompt_template:detail:read`

---

### 4. 通过代码获取模板

用于通过 `template_code` 获取模板（配置引用时使用）。

**请求**

```http
GET /api/v3/prompt-templates/code/{template_code}
Authorization: Bearer {token}
```

**示例**

```http
GET /api/v3/prompt-templates/code/vlm_default_prompt
```

**响应**

同"获取模板详情"

**权限要求**: `prompt_template:detail:read`

---

### 5. 创建模板

**请求**

```http
POST /api/v3/prompt-templates
Authorization: Bearer {token}
Content-Type: application/json
```

**请求体**

```json
{
    "template_name": "自定义VLM抽取模板",
    "template_code": "custom_vlm_extract",
    "template_type": "VLM_Extraction",
    "template_content": "请分析图片中的{doc_name}，提取以下信息：\n{json_template}",
    "description": "针对特定场景优化的VLM抽取模板",
    "template_abbreviation": "自定义VLM",
    "variables": {
        "doc_name": "文档名称",
        "json_template": "JSON模板结构"
    },
    "status": 1
}
```

**字段说明**

| 字段 | 类型 | 必填 | 最大长度 | 说明 |
|------|------|------|----------|------|
| template_name | string | ✅ | 255 | 模板名称 |
| template_code | string | ✅ | 50 | 模板代码（唯一） |
| template_type | string | ✅ | 50 | 模板类型 |
| template_content | string | ✅ | - | 模板内容（prompt文本） |
| description | string | ❌ | - | 模板描述 |
| template_abbreviation | string | ❌ | 100 | 模板简称 |
| variables | object | ❌ | - | 变量定义 |
| status | int | ❌ | - | 状态，默认1（启用） |

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 73,
        "template_name": "自定义VLM抽取模板",
        "template_code": "custom_vlm_extract",
        "template_type": "VLM_Extraction",
        "status": 1,
        "created_at": "2025-11-26T10:00:00"
    }
}
```

**错误情况**

| 错误 | HTTP状态码 | message |
|------|------------|---------|
| 模板代码已存在 | 400 | 模板代码已存在: xxx |
| 缺少必填字段 | 422 | field required |

**权限要求**: `prompt_template:create:write`

---

### 6. 更新模板

**请求**

```http
PUT /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}
Content-Type: application/json
```

**请求体**（所有字段可选，只传需要更新的字段）

```json
{
    "template_name": "更新后的模板名称",
    "template_content": "更新后的模板内容...",
    "description": "更新后的描述",
    "status": 0
}
```

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 73,
        "template_name": "更新后的模板名称",
        "template_code": "custom_vlm_extract",
        "status": 0,
        "updated_at": "2025-11-26T11:00:00"
    }
}
```

**注意事项**

- ⚠️ 系统预设模板（status=2）**不可修改**，会返回403错误
- 修改 `template_code` 时会检查唯一性
- 不能将普通模板的 status 改为 2（系统预设）

**权限要求**: `prompt_template:update:write`

---

### 7. 删除模板

**请求**

```http
DELETE /api/v3/prompt-templates/{template_id}
Authorization: Bearer {token}
```

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "message": "提示词模板删除成功: 自定义VLM抽取模板"
    }
}
```

**注意事项**

- ⚠️ 系统预设模板（status=2）**不可删除**，会返回403错误
- 建议删除前显示确认对话框

**权限要求**: `prompt_template:delete:delete`

---

### 8. 复制模板

快速基于现有模板创建副本。

**请求**

```http
POST /api/v3/prompt-templates/{template_id}/duplicate?new_code=my_custom_code
Authorization: Bearer {token}
```

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| new_code | string | 否 | 新模板代码，不填则自动生成 `{原代码}_copy` |

**响应**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 74,
        "template_name": "VLM通用卷宗抽取Prompt (副本)",
        "template_code": "vlm_default_prompt_copy",
        "template_type": "VLM_Extraction",
        "status": 1,
        "created_at": "2025-11-26T10:30:00"
    }
}
```

**权限要求**: `prompt_template:create:write`

---

## 错误码汇总

| HTTP状态码 | 说明 | 处理建议 |
|------------|------|----------|
| 400 | 请求参数错误 | 检查请求参数格式 |
| 401 | 未认证或Token无效 | 重新登录获取Token |
| 403 | 权限不足或操作系统预设模板 | 检查用户权限/提示不可操作 |
| 404 | 模板不存在 | 刷新列表 |
| 422 | 参数验证失败 | 检查必填字段 |
| 500 | 服务器内部错误 | 联系管理员 |

---

## 权限配置

在 RBAC 系统中为角色分配以下权限：

| 权限键 | 说明 | 建议角色 |
|--------|------|----------|
| `prompt_template:list:read` | 查看模板列表 | 所有用户 |
| `prompt_template:detail:read` | 查看模板详情 | 所有用户 |
| `prompt_template:create:write` | 创建模板 | 管理员 |
| `prompt_template:update:write` | 更新模板 | 管理员 |
| `prompt_template:delete:delete` | 删除模板 | 超级管理员 |

---

## 前端实现建议

### 1. 列表页面

```jsx
// 功能点
- 顶部筛选栏：类型下拉框 + 状态下拉框 + 搜索框
- 表格展示：支持分页
- 操作列：查看、编辑、复制、删除按钮
- 系统预设模板(status=2)：禁用编辑和删除按钮
```

### 2. 编辑/创建弹窗

```jsx
// 表单字段
- 模板名称：文本输入框（必填）
- 模板代码：文本输入框（必填，创建后不建议修改）
- 模板类型：下拉选择框（必填）
- 模板简称：文本输入框（可选）
- 状态：开关/单选框
- 模板描述：多行文本框
- 变量定义：JSON编辑器或Key-Value编辑器
- 模板内容：代码编辑器（支持语法高亮更佳）
```

### 3. 模板内容编辑器

建议使用代码编辑器组件（如 Monaco Editor、CodeMirror），支持：
- 语法高亮
- 变量 `{xxx}` 高亮显示
- 行号显示
- 自动换行

### 4. 状态标签样式

```jsx
const statusConfig = {
    0: { color: 'default', text: '停用' },
    1: { color: 'success', text: '启用' },
    2: { color: 'processing', text: '系统预设' }
};
```

---

## TypeScript 类型定义

```typescript
// 模板类型
type TemplateType =
    | 'LLM_Extraction'
    | 'VLM_Extraction'
    | 'Summary'
    | 'Evaluation'
    | 'Directory_Extraction'
    | 'CaseNum_Extraction'
    | 'Contract_Directory_Extraction'
    | 'Contract_Number'
    | 'Contract_Compare'
    | 'Parties_Extraction'
    | 'Common';

// 模板状态
type TemplateStatus = 0 | 1 | 2;

// 列表项
interface PromptTemplateListItem {
    id: number;
    template_name: string;
    template_code: string | null;
    template_type: TemplateType;
    description: string | null;
    template_abbreviation: string | null;
    status: TemplateStatus;
    created_by: number | null;
    created_at: string;
    updated_at: string;
}

// 详情
interface PromptTemplateDetail extends PromptTemplateListItem {
    template_content: string;
    variables: Record<string, string> | null;
    is_active: boolean;
}

// 创建请求
interface PromptTemplateCreate {
    template_name: string;
    template_code: string;
    template_type: TemplateType;
    template_content: string;
    description?: string;
    template_abbreviation?: string;
    variables?: Record<string, string>;
    status?: TemplateStatus;
}

// 更新请求
interface PromptTemplateUpdate {
    template_name?: string;
    template_code?: string;
    template_type?: TemplateType;
    template_content?: string;
    description?: string;
    template_abbreviation?: string;
    variables?: Record<string, string>;
    status?: TemplateStatus;
}

// 列表响应
interface PromptTemplateListResponse {
    total: number;
    page: number;
    page_size: number;
    items: PromptTemplateListItem[];
}

// 类型列表项
interface TemplateTypeItem {
    value: TemplateType;
    label: string;
    count: number;
}
```

---

## 相关文件

| 文件 | 说明 |
|------|------|
| `app/routes/v3/prompt_templates.py` | API路由定义 |
| `app/services/prompt_template_service.py` | 业务服务层 |
| `app/schemas/prompt_template.py` | Pydantic数据模型 |
| `prompt_templates` 表 | 数据库表 |