# 企业智能助手 API

> API 接口文档 - 定义企业智能助手的完整 API 接口规范
>
> **版本**: v1.4  
> **模块标识**: `platform_ai`  
> **基础路径**: `/api/v1/ai-assistant`  
> **创建日期**: 2025-12-11  
> **更新日期**: 2025-12-11  
> **审查日期**: 2025-12-11

---

## 📋 概述

### 认证要求

所有接口都需要 JWT 认证，通过 `Authorization: Bearer <token>` 请求头传递。

### 响应格式

遵循项目统一响应格式（详见 [API_STANDARDS.md](/docs/standards/API_STANDARDS.md)）：

**成功响应**:
```json
{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "timestamp": "2025-12-11T10:00:00.000Z",
  "path": "/api/v1/ai-assistant/conversations"
}
```

**分页响应**:
```json
{
  "success": true,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**错误响应**:
```json
{
  "success": false,
  "error": {
    "code": "CONVERSATION_NOT_FOUND",
    "message": "对话不存在",
    "details": { ... }
  },
  "timestamp": "2025-12-11T10:00:00.000Z",
  "path": "/api/v1/ai-assistant/conversations/xxx",
  "method": "GET",
  "statusCode": 404
}
```

### 流式响应

AI 回复使用 Server-Sent Events (SSE) 流式返回：
```http
Accept: text/event-stream
```

---

## 🔐 认证与权限

### 权限矩阵

| 接口 | 权限标识 | 普通用户 | IT 支持 | HR 支持 | 管理员 |
|------|----------|:--------:|:-------:|:-------:|:------:|
| 创建对话 | `ai:conversation:create` | ✅ | ✅ | ✅ | ✅ |
| 发送消息 | `ai:conversation:create` | ✅ | ✅ | ✅ | ✅ |
| 查看自己的对话 | `ai:conversation:read` | ✅ | ✅ | ✅ | ✅ |
| 删除自己的对话 | `ai:conversation:delete` | ✅ | ✅ | ✅ | ✅ |
| 创建工单 | `ai:ticket:create` | ✅ | ✅ | ✅ | ✅ |
| 查看分配给自己的工单 | `ai:ticket:read` | - | ✅ | ✅ | ✅ |
| 处理工单 | `ai:ticket:update` | - | ✅ | ✅ | ✅ |
| 查看所有工单 | `ai:ticket:admin` | - | - | - | ✅ |
| 提交知识纠正 | `ai:knowledge:create` | - | ✅ | ✅ | ✅ |
| 审核知识纠正 | `ai:knowledge:review` | - | - | - | ✅ |
| Prompt 模板管理 | `ai:prompt:manage` | - | - | - | ✅ |
| 配置管理 | `ai:config:manage` | - | - | - | ✅ |
| 查看统计/仪表盘 | `ai:stats:read` | - | - | - | ✅ |

### 用户上下文要求 🆕

**用户身份来源**:
- `userId` - 从 JWT Token 自动获取，无需手动传递
- 扩展上下文信息通过请求头传递（用于统计分析）

```http
X-User-Context: {"departmentId": "xxx", "departmentName": "IT部", "region": "CN"}
```

```typescript
interface UserContext {
  departmentId: string;    // 部门 ID
  departmentName: string;  // 部门名称
  region?: string;         // 区域（可选）
  jobLevel?: string;       // 职级（可选）
}
```

> **注意**: 当前用户上下文仅用于统计分析，不影响 AI 回答内容。未来版本可能增加权限差异化响应。

---

## 📡 接口列表

### 对话管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/conversations` | 创建新对话 |
| `GET` | `/conversations` | 获取对话列表 |
| `GET` | `/conversations/:id` | 获取对话详情 |
| `DELETE` | `/conversations/:id` | 删除对话 |
| `POST` | `/conversations/:id/messages` | 发送消息 |
| `GET` | `/conversations/:id/messages/stream` | 流式获取 AI 回复 |

### 反馈管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/messages/:id/feedback` | 提交消息反馈 |
| `PUT` | `/messages/:id/feedback` | 更新消息反馈 |

### 工单管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/tickets` | 创建工单 |
| `GET` | `/tickets` | 获取工单列表 |
| `GET` | `/tickets/:id` | 获取工单详情 |
| `PUT` | `/tickets/:id` | 更新工单 |
| `POST` | `/tickets/:id/assign` | 分配工单 |
| `POST` | `/tickets/:id/resolve` | 解决工单 |

### 知识补充 🆕

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/knowledge-fixes` | 提交知识纠正 |
| `GET` | `/knowledge-fixes` | 获取知识纠正列表 |
| `PUT` | `/knowledge-fixes/:id/review` | 审核知识纠正 |

### Prompt 模板管理 🆕

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/prompts` | 获取 Prompt 模板列表 |
| `GET` | `/prompts/:id` | 获取 Prompt 模板详情 |
| `POST` | `/prompts` | 创建 Prompt 模板 |
| `PUT` | `/prompts/:id` | 更新 Prompt 模板 |
| `POST` | `/prompts/:id/activate` | 激活 Prompt 模板 |

### 配置管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/config` | 获取配置列表 |
| `PUT` | `/config/:key` | 更新配置 |

### 统计分析 / 管理仪表盘 🆕

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/stats/overview` | 获取统计概览 |
| `GET` | `/stats/feedback` | 获取反馈统计 |
| `GET` | `/stats/dashboard` | 获取管理仪表盘数据 🆕 |
| `GET` | `/stats/hallucination` | 获取幻觉标记统计 🆕 |

---

## 📖 接口详情

### 对话管理

#### 创建新对话

**POST** `/api/v1/ai-assistant/conversations`

创建一个新的对话会话。

**权限**: `ai:conversation:create`

**请求体**:
```json
{
  "title": "VPN 连接问题",
  "category": "IT"
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `title` | string | ❌ | 对话标题 (2-200 字符)，不填则自动生成 |
| `category` | enum | ❌ | 问题类别: `IT`, `HR`, `ADMIN`, `GENERAL` (默认 `GENERAL`) |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user-uuid",
    "title": "VPN 连接问题",
    "category": "IT",
    "status": "ACTIVE",
    "tags": [],
    "createdAt": "2025-12-11T10:00:00.000Z",
    "updatedAt": "2025-12-11T10:00:00.000Z"
  },
  "message": "对话创建成功",
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `VALIDATION_ERROR` | 400 | 参数验证失败 |

---

#### 获取对话列表

**GET** `/api/v1/ai-assistant/conversations`

获取当前用户的对话列表。

**权限**: `ai:conversation:read`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `page` | number | ❌ | 1 | 页码 |
| `limit` | number | ❌ | 20 | 每页数量 (最大 50) |
| `status` | enum | ❌ | - | 过滤状态: `ACTIVE`, `CLOSED`, `ESCALATED` |
| `category` | enum | ❌ | - | 过滤类别: `IT`, `HR`, `ADMIN`, `GENERAL` |
| `keyword` | string | ❌ | - | 搜索关键词（标题/内容） |
| `startDate` | date | ❌ | - | 创建时间起始 |
| `endDate` | date | ❌ | - | 创建时间结束 |
| `sortBy` | string | ❌ | `updatedAt` | 排序字段: `createdAt`, `updatedAt` |
| `sortOrder` | string | ❌ | `desc` | 排序方向: `asc`, `desc` |

**示例请求**:
```
GET /api/v1/ai-assistant/conversations?status=ACTIVE&category=IT&sortBy=updatedAt&sortOrder=desc
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "VPN 连接问题",
        "category": "IT",
        "status": "ACTIVE",
        "tags": ["vpn", "network"],
        "lastMessage": "好的，我来帮您解决这个问题...",
        "messageCount": 5,
        "createdAt": "2025-12-11T10:00:00.000Z",
        "updatedAt": "2025-12-11T10:30:00.000Z"
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取对话详情

**GET** `/api/v1/ai-assistant/conversations/:id`

获取对话详情，包含消息列表。

**权限**: `ai:conversation:read`（仅对话所有者）

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 对话 ID |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user-uuid",
    "title": "VPN 连接问题",
    "category": "IT",
    "status": "ACTIVE",
    "tags": ["vpn", "network"],
    "messages": [
      {
        "id": "msg-1",
        "role": "USER",
        "source": "USER",
        "content": "我的 VPN 连接不上",
        "createdAt": "2025-12-11T10:00:00.000Z"
      },
      {
        "id": "msg-2",
        "role": "ASSISTANT",
        "source": "AI",
        "content": "您好，请问是显示什么错误信息？",
        "feedback": {
          "type": "LIKE"
        },
        "createdAt": "2025-12-11T10:00:05.000Z"
      }
    ],
    "createdAt": "2025-12-11T10:00:00.000Z",
    "updatedAt": "2025-12-11T10:30:00.000Z"
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `CONVERSATION_NOT_FOUND` | 404 | 对话不存在 |
| `FORBIDDEN` | 403 | 无权访问该对话 |

---

#### 删除对话

**DELETE** `/api/v1/ai-assistant/conversations/:id`

删除对话（软删除）。

**权限**: `ai:conversation:delete`（仅对话所有者）

**成功响应** (200):
```json
{
  "success": true,
  "data": null,
  "message": "对话删除成功",
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 发送消息

**POST** `/api/v1/ai-assistant/conversations/:id/messages`

向对话发送用户消息，触发 AI 回复。

**权限**: `ai:conversation:create`（仅对话所有者）

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 对话 ID |

**请求体**:
```json
{
  "content": "我的 VPN 连接不上，显示认证失败"
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `content` | string | ✅ | 消息内容 (1-4000 字符) |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "userMessage": {
      "id": "msg-user-uuid",
      "role": "USER",
      "source": "USER",
      "content": "我的 VPN 连接不上，显示认证失败",
      "createdAt": "2025-12-11T10:01:00.000Z"
    },
    "streamUrl": "/api/v1/ai-assistant/conversations/xxx/messages/stream?messageId=msg-ai-uuid"
  },
  "timestamp": "2025-12-11T10:01:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `CONVERSATION_NOT_FOUND` | 404 | 对话不存在 |
| `CONVERSATION_CLOSED` | 400 | 对话已关闭，无法发送消息 |
| `MESSAGE_TOO_LONG` | 400 | 消息内容超过限制 |
| `PII_DETECTED` | 200 | 检测到敏感信息，已自动脱敏（警告，非错误）|
| `PROMPT_INJECTION_DETECTED` | 400 | 检测到 Prompt 注入攻击 |

---

#### 流式获取 AI 回复

**GET** `/api/v1/ai-assistant/conversations/:id/messages/stream`

使用 SSE 流式获取 AI 回复内容。

**权限**: `ai:conversation:read`（仅对话所有者）

**请求头**:
```http
Accept: text/event-stream
Authorization: Bearer <token>
```

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `messageId` | UUID | ✅ | AI 消息 ID |

**SSE 事件格式**:
```
event: token
data: {"content": "您好"}

event: token
data: {"content": "，"}

event: token
data: {"content": "VPN"}

event: done
data: {"messageId": "msg-ai-uuid", "totalTokens": 150}

event: error
data: {"code": "LLM_SERVICE_ERROR", "message": "模型服务暂时不可用"}
```

**事件类型**:

| 事件 | 说明 |
|------|------|
| `token` | AI 输出的 token 片段 |
| `done` | 响应完成 |
| `error` | 发生错误（服务降级时返回 fallback 消息） |

**降级处理**:

当 LLM 服务不可用时，返回预设的 fallback 消息：
```
event: fallback
data: {"content": "抱歉，智能助手服务暂时不可用，请稍后重试。如问题紧急，请通过以下方式联系支持..."}
```

---

### 反馈管理

#### 提交消息反馈

**POST** `/api/v1/ai-assistant/messages/:id/feedback`

对 AI 回复进行点赞或点踩。

**权限**: `ai:conversation:create`（仅对话所有者）

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 消息 ID |

**请求体**:
```json
{
  "type": "LIKE",
  "comment": "回答很有帮助"
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `type` | enum | ✅ | `LIKE` 或 `DISLIKE` |
| `comment` | string | ❌ | 反馈评论 (最大 500 字符) |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "id": "feedback-uuid",
    "messageId": "msg-uuid",
    "type": "LIKE",
    "comment": "回答很有帮助",
    "createdAt": "2025-12-11T10:05:00.000Z"
  },
  "message": "反馈提交成功",
  "timestamp": "2025-12-11T10:05:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `NOT_FOUND` | 404 | 消息不存在 |
| `FEEDBACK_EXISTS` | 400 | 已对该消息提交过反馈 |

---

#### 更新消息反馈

**PUT** `/api/v1/ai-assistant/messages/:id/feedback`

更新已提交的消息反馈。

**权限**: `ai:conversation:create`（仅反馈提交者）

**请求体**:
```json
{
  "type": "DISLIKE",
  "comment": "回答不准确"
}
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "feedback-uuid",
    "messageId": "msg-uuid",
    "type": "DISLIKE",
    "comment": "回答不准确",
    "updatedAt": "2025-12-11T10:10:00.000Z"
  },
  "message": "反馈更新成功",
  "timestamp": "2025-12-11T10:10:00.000Z"
}
```

---

### 工单管理

#### 创建工单（升级问题）

**POST** `/api/v1/ai-assistant/tickets`

将未解决的问题升级为工单。系统会自动调用工单系统并传递对话上下文。

**权限**: `ai:ticket:create`

**请求体**:
```json
{
  "conversationId": "conv-uuid",
  "category": "IT",
  "priority": "MEDIUM",
  "description": "VPN 连接问题，尝试了重置密码但仍无法连接",
  "confirmed": true
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `conversationId` | UUID | ✅ | 关联的对话 ID |
| `category` | enum | ✅ | 分类: `IT`, `HR`, `ADMIN`, `FINANCE`, `OTHER` |
| `priority` | enum | ❌ | 优先级: `LOW`, `MEDIUM`, `HIGH`, `URGENT` (默认 `MEDIUM`) |
| `description` | string | ✅ | 问题描述 (10-2000 字符) |
| `confirmed` | boolean | ✅ | 二次确认标识，必须为 `true` |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "id": "ticket-uuid",
    "conversationId": "conv-uuid",
    "source": "AI_ASSISTANT",
    "category": "IT",
    "priority": "MEDIUM",
    "status": "OPEN",
    "description": "VPN 连接问题，尝试了重置密码但仍无法连接",
    "assigneeId": "it-support-uuid",
    "assigneeTeam": "IT",
    "assignedAt": "2025-12-11T10:10:00.000Z",
    "createdAt": "2025-12-11T10:10:00.000Z",
    "conversationSummary": {
      "messageCount": 5,
      "includedInTicket": true
    }
  },
  "message": "工单已创建并分配给 IT 支持团队",
  "timestamp": "2025-12-11T10:10:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `CONVERSATION_NOT_FOUND` | 404 | 对话不存在 |
| `TICKET_NOT_CONFIRMED` | 400 | 工单升级未确认 |
| `VALIDATION_ERROR` | 400 | 参数验证失败 |

**工单系统接收的数据**:

创建工单时，系统会向工单系统发送以下数据（详见 [PRD 与工单系统的数据约定](./PRD.md#-与工单系统的数据约定)）：

```typescript
{
  source: 'AI_ASSISTANT',
  conversationId: 'conv-uuid',
  userContext: {
    userId: 'user-uuid',
    departmentId: 'dept-uuid',
    departmentName: 'IT部',
    region: 'CN'
  },
  category: 'IT',
  priority: 'MEDIUM',
  title: '自动生成的标题',
  description: '用户填写的描述',
  conversationSummary: {
    messageCount: 5,
    recentMessages: [...], // 最近 10 条消息
    aiSuggestedCategory: 'IT'
  }
}
```

---

#### 获取工单列表

**GET** `/api/v1/ai-assistant/tickets`

获取工单列表。普通用户只能看到自己创建的，处理人可看到分配给自己的。

**权限**: `ai:ticket:read` 或 `ai:ticket:admin`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `page` | number | ❌ | 1 | 页码 |
| `limit` | number | ❌ | 20 | 每页数量 (最大 50) |
| `status` | enum | ❌ | - | 过滤状态: `OPEN`, `IN_PROGRESS`, `RESOLVED`, `CLOSED` |
| `category` | enum | ❌ | - | 过滤类别: `IT`, `HR`, `ADMIN`, `FINANCE`, `OTHER` |
| `priority` | enum | ❌ | - | 过滤优先级: `LOW`, `MEDIUM`, `HIGH`, `URGENT` |
| `assigneeTeam` | enum | ❌ | - | 过滤分配团队 |
| `view` | string | ❌ | - | 预设视图: `my_created`, `my_assigned`, `all` |
| `sortBy` | string | ❌ | `createdAt` | 排序字段 |
| `sortOrder` | string | ❌ | `desc` | 排序方向: `asc`, `desc` |

**示例请求**:
```
GET /api/v1/ai-assistant/tickets?status=OPEN&view=my_assigned&sortBy=createdAt&sortOrder=desc
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "ticket-uuid",
        "category": "IT",
        "priority": "MEDIUM",
        "status": "OPEN",
        "description": "VPN 连接问题",
        "assignee": {
          "id": "user-uuid",
          "name": "IT Support"
        },
        "assigneeTeam": "IT",
        "creator": {
          "id": "user-uuid",
          "name": "张三"
        },
        "conversationId": "conv-uuid",
        "createdAt": "2025-12-11T10:10:00.000Z",
        "updatedAt": "2025-12-11T10:10:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取工单详情

**GET** `/api/v1/ai-assistant/tickets/:id`

获取工单详情，包括关联的对话历史。

**权限**: `ai:ticket:read`（创建人/处理人/管理员）

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 工单 ID |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "ticket-uuid",
    "category": "IT",
    "priority": "MEDIUM",
    "status": "OPEN",
    "description": "VPN 连接问题，尝试了重置密码但仍无法连接",
    "assignee": {
      "id": "user-uuid",
      "name": "IT Support",
      "email": "it@company.com"
    },
    "assigneeTeam": "IT",
    "creator": {
      "id": "user-uuid",
      "name": "张三"
    },
    "conversation": {
      "id": "conv-uuid",
      "title": "VPN 连接问题",
      "messages": [
        {
          "id": "msg-1",
          "role": "USER",
          "source": "USER",
          "content": "我的 VPN 连接不上",
          "createdAt": "2025-12-11T10:00:00.000Z"
        },
        {
          "id": "msg-2",
          "role": "ASSISTANT",
          "source": "AI",
          "content": "您好，请问是显示什么错误信息？",
          "createdAt": "2025-12-11T10:00:05.000Z"
        }
      ]
    },
    "resolution": null,
    "resolvedAt": null,
    "createdAt": "2025-12-11T10:10:00.000Z",
    "updatedAt": "2025-12-11T10:10:00.000Z"
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `TICKET_NOT_FOUND` | 404 | 工单不存在 |
| `FORBIDDEN` | 403 | 无权访问该工单 |

---

#### 更新工单

**PUT** `/api/v1/ai-assistant/tickets/:id`

更新工单信息。

**权限**: `ai:ticket:update`（处理人/管理员）

**请求体**:
```json
{
  "priority": "HIGH",
  "assigneeId": "new-assignee-uuid"
}
```

**可更新字段**:

| 字段 | 类型 | 说明 |
|------|------|------|
| `priority` | enum | 优先级 |
| `assigneeId` | UUID | 处理人 ID |
| `assigneeTeam` | enum | 分配团队 |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "ticket-uuid",
    "priority": "HIGH",
    "assigneeId": "new-assignee-uuid",
    "updatedAt": "2025-12-11T10:30:00.000Z"
  },
  "message": "工单更新成功",
  "timestamp": "2025-12-11T10:30:00.000Z"
}
```

---

#### 分配工单

**POST** `/api/v1/ai-assistant/tickets/:id/assign`

将工单分配给处理人或团队。

**权限**: `ai:ticket:update`（管理员）

**请求体**:
```json
{
  "assigneeId": "assignee-uuid",
  "assigneeTeam": "IT"
}
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "ticket-uuid",
    "assigneeId": "assignee-uuid",
    "assigneeTeam": "IT",
    "assignedAt": "2025-12-11T10:30:00.000Z"
  },
  "message": "工单分配成功",
  "timestamp": "2025-12-11T10:30:00.000Z"
}
```

---

#### 解决工单

**POST** `/api/v1/ai-assistant/tickets/:id/resolve`

将工单标记为已解决。

**权限**: `ai:ticket:update`（处理人/管理员）

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 工单 ID |

**请求体**:
```json
{
  "resolution": "已帮助用户重置 VPN 证书，问题解决"
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `resolution` | string | ✅ | 解决方案说明 (10-2000 字符) |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "ticket-uuid",
    "status": "RESOLVED",
    "resolution": "已帮助用户重置 VPN 证书，问题解决",
    "resolvedAt": "2025-12-11T11:00:00.000Z"
  },
  "message": "工单已解决",
  "timestamp": "2025-12-11T11:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `TICKET_NOT_FOUND` | 404 | 工单不存在 |
| `TICKET_ALREADY_RESOLVED` | 400 | 工单已解决 |

---

### 知识补充

#### 提交知识纠正

**POST** `/api/v1/ai-assistant/knowledge-fixes`

IT/HR 专员对 AI 错误回答提交纠正。

**权限**: `ai:knowledge:create`

**请求体**:
```json
{
  "messageId": "msg-uuid",
  "correctAnswer": "正确答案内容..."
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `messageId` | UUID | ✅ | 需要纠正的 AI 消息 ID |
| `correctAnswer` | string | ✅ | 正确答案内容 (10-5000 字符) |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "id": "fix-uuid",
    "messageId": "msg-uuid",
    "correctAnswer": "正确答案内容...",
    "contributorId": "user-uuid",
    "status": "PENDING",
    "createdAt": "2025-12-11T10:00:00.000Z"
  },
  "message": "知识纠正已提交，等待审核",
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `NOT_FOUND` | 404 | 消息不存在 |
| `KNOWLEDGE_FIX_EXISTS` | 400 | 已对该消息提交过纠正 |

---

#### 获取知识纠正列表

**GET** `/api/v1/ai-assistant/knowledge-fixes`

获取知识纠正列表。

**权限**: `ai:knowledge:create`（查看自己的）或 `ai:knowledge:review`（查看全部）

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `page` | number | ❌ | 1 | 页码 |
| `limit` | number | ❌ | 20 | 每页数量 |
| `status` | enum | ❌ | - | 过滤状态: `PENDING`, `APPROVED`, `REJECTED` |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "fix-uuid",
        "messageId": "msg-uuid",
        "originalAnswer": "AI 的原始回答...",
        "correctAnswer": "正确答案内容...",
        "contributor": {
          "id": "user-uuid",
          "name": "IT 专员"
        },
        "status": "PENDING",
        "createdAt": "2025-12-11T10:00:00.000Z"
      }
    ],
    "total": 10,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 审核知识纠正

**PUT** `/api/v1/ai-assistant/knowledge-fixes/:id/review`

管理员审核知识纠正内容。

**权限**: `ai:knowledge:review`

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 知识纠正 ID |

**请求体**:
```json
{
  "status": "APPROVED",
  "reviewNote": "审核通过，内容准确"
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `status` | enum | ✅ | `APPROVED` 或 `REJECTED` |
| `reviewNote` | string | ❌ | 审核备注 (最大 500 字符) |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "fix-uuid",
    "status": "APPROVED",
    "reviewerId": "admin-uuid",
    "reviewNote": "审核通过，内容准确",
    "reviewedAt": "2025-12-11T11:00:00.000Z"
  },
  "message": "知识纠正审核完成",
  "timestamp": "2025-12-11T11:00:00.000Z"
}
```

**错误响应**:

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `NOT_FOUND` | 404 | 知识纠正不存在 |
| `VALIDATION_ERROR` | 400 | 参数验证失败 |

---

### Prompt 模板管理

#### 获取 Prompt 模板列表

**GET** `/api/v1/ai-assistant/prompts`

获取 Prompt 模板列表。

**权限**: `ai:prompt:manage`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `category` | enum | ❌ | - | 过滤类别: `IT`, `HR`, `ADMIN`, `GENERAL` |
| `isActive` | boolean | ❌ | - | 是否激活 |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prompt-uuid",
        "name": "IT 支持 Prompt v2",
        "category": "IT",
        "version": 2,
        "isActive": true,
        "createdBy": {
          "id": "admin-uuid",
          "name": "管理员"
        },
        "createdAt": "2025-12-11T10:00:00.000Z",
        "updatedAt": "2025-12-11T10:00:00.000Z"
      }
    ],
    "total": 5
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取 Prompt 模板详情

**GET** `/api/v1/ai-assistant/prompts/:id`

获取 Prompt 模板详情，包含完整内容。

**权限**: `ai:prompt:manage`

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | Prompt 模板 ID |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "prompt-uuid",
    "name": "IT 支持 Prompt v2",
    "category": "IT",
    "content": "你是一个专业的企业 IT 支持助手...",
    "version": 2,
    "isActive": true,
    "createdBy": {
      "id": "admin-uuid",
      "name": "管理员"
    },
    "createdAt": "2025-12-11T10:00:00.000Z",
    "updatedAt": "2025-12-11T10:00:00.000Z"
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 创建 Prompt 模板

**POST** `/api/v1/ai-assistant/prompts`

创建新的 Prompt 模板。

**权限**: `ai:prompt:manage`

**请求体**:
```json
{
  "name": "IT 支持 Prompt v3",
  "category": "IT",
  "content": "你是一个专业的企业 IT 支持助手，专注于帮助员工解决 IT 相关问题..."
}
```

**请求体字段说明**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `name` | string | ✅ | 模板名称 (2-100 字符) |
| `category` | enum | ✅ | 类别: `IT`, `HR`, `ADMIN`, `GENERAL` |
| `content` | string | ✅ | Prompt 内容 (10-10000 字符) |

**成功响应** (201):
```json
{
  "success": true,
  "data": {
    "id": "prompt-uuid",
    "name": "IT 支持 Prompt v3",
    "category": "IT",
    "version": 3,
    "isActive": false,
    "createdAt": "2025-12-11T10:00:00.000Z"
  },
  "message": "Prompt 模板创建成功",
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 更新 Prompt 模板

**PUT** `/api/v1/ai-assistant/prompts/:id`

更新 Prompt 模板。更新后版本号自动递增。

**权限**: `ai:prompt:manage`

**请求体**:
```json
{
  "name": "IT 支持 Prompt v3 - 优化版",
  "content": "更新后的 Prompt 内容..."
}
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "prompt-uuid",
    "name": "IT 支持 Prompt v3 - 优化版",
    "version": 4,
    "updatedAt": "2025-12-11T11:00:00.000Z"
  },
  "message": "Prompt 模板更新成功",
  "timestamp": "2025-12-11T11:00:00.000Z"
}
```

---

#### 激活 Prompt 模板

**POST** `/api/v1/ai-assistant/prompts/:id/activate`

将指定版本的 Prompt 设为当前激活版本。同一类别下只能有一个激活的模板。

**权限**: `ai:prompt:manage`

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | Prompt 模板 ID |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "id": "prompt-uuid",
    "category": "IT",
    "version": 2,
    "isActive": true,
    "activatedAt": "2025-12-11T10:00:00.000Z"
  },
  "message": "Prompt 模板已激活",
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**说明**: 激活新模板时，同类别的其他模板会自动设为非激活状态。

---

### 配置管理

#### 获取配置列表

**GET** `/api/v1/ai-assistant/config`

获取 AI 助手配置列表。

**权限**: `ai:config:manage`

**成功响应** (200):
```json
{
  "success": true,
  "data": [
    {
      "id": "config-uuid",
      "key": "model",
      "value": "gpt-4-turbo",
      "category": "GENERAL",
      "isActive": true,
      "updatedAt": "2025-12-11T10:00:00.000Z"
    },
    {
      "id": "config-uuid-2",
      "key": "temperature",
      "value": "0.7",
      "category": "GENERAL",
      "isActive": true,
      "updatedAt": "2025-12-11T10:00:00.000Z"
    }
  ],
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 更新配置

**PUT** `/api/v1/ai-assistant/config/:key`

更新 AI 助手配置。

**权限**: `ai:config:manage`

**请求体**:
```json
{
  "value": "gpt-3.5-turbo",
  "category": "GENERAL"
}
```

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "key": "model",
    "value": "gpt-3.5-turbo",
    "category": "GENERAL",
    "updatedAt": "2025-12-11T11:00:00.000Z"
  },
  "message": "配置更新成功",
  "timestamp": "2025-12-11T11:00:00.000Z"
}
```

---

### 统计分析 / 管理仪表盘

#### 获取统计概览

**GET** `/api/v1/ai-assistant/stats/overview`

获取 AI 助手使用统计概览。

**权限**: `ai:stats:read`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `startDate` | date | ❌ | 7天前 | 统计起始日期 |
| `endDate` | date | ❌ | 今天 | 统计结束日期 |
| `category` | enum | ❌ | - | 过滤类别 |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "totalConversations": 1250,
    "totalMessages": 5680,
    "totalTickets": 125,
    "resolutionRate": 0.65,
    "averageSatisfaction": 4.2,
    "categoryBreakdown": {
      "IT": 450,
      "HR": 380,
      "ADMIN": 220,
      "GENERAL": 200
    },
    "dailyTrend": [
      { "date": "2025-12-10", "conversations": 120, "tickets": 12 },
      { "date": "2025-12-11", "conversations": 135, "tickets": 15 }
    ]
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取反馈统计

**GET** `/api/v1/ai-assistant/stats/feedback`

获取用户反馈统计数据。

**权限**: `ai:stats:read`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `startDate` | date | ❌ | 7天前 | 统计起始日期 |
| `endDate` | date | ❌ | 今天 | 统计结束日期 |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "total": 500,
    "likes": 350,
    "dislikes": 150,
    "likeRate": 0.70,
    "byCategory": {
      "IT": { "likes": 150, "dislikes": 50 },
      "HR": { "likes": 120, "dislikes": 60 },
      "ADMIN": { "likes": 50, "dislikes": 30 },
      "GENERAL": { "likes": 30, "dislikes": 10 }
    }
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取管理仪表盘数据

**GET** `/api/v1/ai-assistant/stats/dashboard`

获取实时监控仪表盘数据。

**权限**: `ai:stats:read`

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "realtime": {
      "callsLast24h": 1250,
      "callsLast7d": 8750,
      "successRate": 0.98,
      "errorRate": 0.02,
      "avgResponseTime": 850
    },
    "satisfaction": {
      "likeRate": 0.78,
      "dislikeRate": 0.12,
      "noFeedbackRate": 0.10
    },
    "categoryDistribution": {
      "IT": 0.36,
      "HR": 0.30,
      "ADMIN": 0.18,
      "GENERAL": 0.16
    },
    "hallucination": {
      "markedCount": 15,
      "pendingReviewCount": 3
    },
    "topIssues": [
      { "keyword": "VPN", "count": 120 },
      { "keyword": "密码重置", "count": 85 },
      { "keyword": "请假", "count": 60 }
    ],
    "updatedAt": "2025-12-11T10:00:00.000Z"
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

---

#### 获取幻觉标记统计

**GET** `/api/v1/ai-assistant/stats/hallucination`

获取 AI 幻觉标记统计数据。

**权限**: `ai:stats:read`

**查询参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `startDate` | date | ❌ | 30天前 | 统计起始日期 |
| `endDate` | date | ❌ | 今天 | 统计结束日期 |

**成功响应** (200):
```json
{
  "success": true,
  "data": {
    "totalMarked": 45,
    "fromDislike": 30,
    "fromKnowledgeFix": 15,
    "pendingReview": 5,
    "approved": 35,
    "rejected": 5,
    "hallucinationRate": 0.036,
    "byCategory": {
      "IT": 20,
      "HR": 15,
      "ADMIN": 5,
      "GENERAL": 5
    },
    "trend": [
      { "date": "2025-12-01", "count": 3 },
      { "date": "2025-12-02", "count": 2 },
      { "date": "2025-12-03", "count": 5 }
    ]
  },
  "timestamp": "2025-12-11T10:00:00.000Z"
}
```

**说明**: `hallucinationRate` 计算方式：幻觉标记数 / 总消息数（详见 [PRD 幻觉率定义](./PRD.md#成功指标)）

---

## ⚠️ 错误码

### 通用错误

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `UNAUTHORIZED` | 401 | 未登录或 Token 过期 |
| `FORBIDDEN` | 403 | 无权限访问 |
| `NOT_FOUND` | 404 | 资源不存在 |
| `VALIDATION_ERROR` | 400 | 参数验证失败 |
| `INTERNAL_SERVER_ERROR` | 500 | 服务器内部错误 |

### 对话相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `CONVERSATION_NOT_FOUND` | 404 | 对话不存在 |
| `CONVERSATION_CLOSED` | 400 | 对话已关闭，无法发送消息 |
| `CONVERSATION_ACCESS_DENIED` | 403 | 无权访问该对话 |
| `MESSAGE_TOO_LONG` | 400 | 消息内容超过限制 |

### 工单相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `TICKET_NOT_FOUND` | 404 | 工单不存在 |
| `TICKET_ALREADY_RESOLVED` | 400 | 工单已解决 |
| `TICKET_NOT_CONFIRMED` | 400 | 工单升级未确认 |
| `TICKET_ACCESS_DENIED` | 403 | 无权访问该工单 |

### 反馈相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `FEEDBACK_EXISTS` | 400 | 已对该消息提交过反馈 |
| `FEEDBACK_NOT_FOUND` | 404 | 反馈不存在 |

### 知识补充相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `KNOWLEDGE_FIX_EXISTS` | 400 | 已对该消息提交过纠正 |
| `KNOWLEDGE_FIX_NOT_FOUND` | 404 | 知识纠正不存在 |

### AI 服务相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `LLM_SERVICE_ERROR` | 503 | 大模型服务不可用 |
| `LLM_RATE_LIMIT` | 429 | 请求频率超限 |
| `PROMPT_INJECTION_DETECTED` | 400 | 检测到 Prompt 注入攻击 |

### 安全相关

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| `PII_DETECTED` | 200 | 检测到敏感信息，已自动脱敏（警告，非错误）|

**说明**: `PII_DETECTED` 返回 200 状态码，但会在响应中包含警告信息，提示用户敏感信息已被脱敏处理。

---

## 📊 数据模型

### ConversationStatus

```typescript
enum ConversationStatus {
  ACTIVE = 'ACTIVE',       // 进行中
  CLOSED = 'CLOSED',       // 已关闭
  ESCALATED = 'ESCALATED'  // 已升级
}
```

### ConversationCategory

```typescript
enum ConversationCategory {
  IT = 'IT',           // IT 支持
  HR = 'HR',           // 人力资源
  ADMIN = 'ADMIN',     // 行政事务
  GENERAL = 'GENERAL'  // 通用问题
}
```

### MessageRole

```typescript
enum MessageRole {
  USER = 'USER',           // 用户消息
  ASSISTANT = 'ASSISTANT', // AI 回复
  SYSTEM = 'SYSTEM'        // 系统消息
}
```

### FeedbackType

```typescript
enum FeedbackType {
  LIKE = 'LIKE',       // 点赞
  DISLIKE = 'DISLIKE'  // 点踩
}
```

### TicketStatus

```typescript
enum TicketStatus {
  OPEN = 'OPEN',             // 待处理
  IN_PROGRESS = 'IN_PROGRESS', // 处理中
  RESOLVED = 'RESOLVED',     // 已解决
  CLOSED = 'CLOSED'          // 已关闭
}
```

### TicketPriority

```typescript
enum TicketPriority {
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH',
  URGENT = 'URGENT'
}
```

### TicketCategory

```typescript
enum TicketCategory {
  IT = 'IT',           // IT 支持
  HR = 'HR',           // 人力资源
  ADMIN = 'ADMIN',     // 行政事务
  FINANCE = 'FINANCE', // 财务问题
  OTHER = 'OTHER'      // 其他
}
```

### AssigneeTeam

```typescript
enum AssigneeTeam {
  IT = 'IT',           // IT 团队
  HR = 'HR',           // HR 团队
  ADMIN = 'ADMIN',     // 行政团队
  FINANCE = 'FINANCE'  // 财务团队
}
```

### MessageSource 🆕

```typescript
enum MessageSource {
  USER = 'USER',           // 用户输入
  AI = 'AI',               // AI 回复
  SYSTEM = 'SYSTEM',       // 系统消息
  ESCALATION = 'ESCALATION' // 升级通知
}
```

### KnowledgeFixStatus 🆕

```typescript
enum KnowledgeFixStatus {
  PENDING = 'PENDING',     // 待审核
  APPROVED = 'APPROVED',   // 已通过
  REJECTED = 'REJECTED'    // 已拒绝
}
```

---

## 🔗 相关文档

- [PRD 产品需求](./PRD.md)
- [架构设计](./ARCHITECTURE.md)
- [开发待办](./TODO.md)

---

**创建日期**: 2025-12-11  
**最后更新**: 2025-12-11  
**版本**: v1.4

### 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2025-12-11 | 初始版本 |
| v1.2 | 2025-12-11 | 增加知识补充 API、Prompt 模板 API、管理仪表盘 API、用户上下文要求、工单升级二次确认、新增枚举类型 |
| v1.3 | 2025-12-11 | 按项目 API 规范重构：增加权限标识、规范响应格式（分页 hasNext/hasPrev）、增加错误响应示例、补充接口详情（路径参数、错误码）、增加配置管理 API、增加获取幻觉统计 API 详情、增加 TicketCategory 枚举定义（含 OTHER）|
| v1.4 | 2025-12-11 | 规范审查：分页参数从 `pageSize` 改为 `limit` 与 API_STANDARDS 一致、用户上下文说明改进（明确 userId 从 JWT 获取）|