# 聊天消息持久化功能使用指南

## 功能概述

本功能提供了完整的聊天消息持久化解决方案，包括：
- 聊天消息实体定义
- 标准CRUD操作接口
- 历史消息查询功能
- 用户操作追踪
- 类型安全的API调用

## API端点

### 1. 标准CRUD接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/chat-messages` | 获取聊天消息列表（支持分页、搜索、筛选） |
| POST | `/api/v1/chat-messages` | 创建新的聊天消息 |
| GET | `/api/v1/chat-messages/{id}` | 获取单个聊天消息详情 |
| PUT | `/api/v1/chat-messages/{id}` | 更新聊天消息 |
| DELETE | `/api/v1/chat-messages/{id}` | 删除聊天消息 |

### 2. 历史消息查询接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/chat-messages/history` | 按课堂ID查询历史消息 |

## 数据结构

### 聊天消息实体 (ChatMessage)

```typescript
interface ChatMessage {
  id: number;                    // 消息ID
  classId: string;              // 课堂ID
  type: 'text' | 'image' | 'system'; // 消息类型
  content: string;              // 消息内容
  senderId: string | null;      // 发送者ID
  senderName: string | null;    // 发送者名称
  timestamp: number;            // 消息时间戳（毫秒）
  createdBy: number | null;     // 创建用户ID
  updatedBy: number | null;     // 更新用户ID
  createdAt: Date;              // 创建时间
  updatedAt: Date;              // 更新时间
}
```

## 使用示例

### 1. 创建聊天消息

```typescript
import { chatMessageClient } from '@/client/api';

// 创建文本消息
const response = await chatMessageClient.$post({
  json: {
    classId: 'class_123456',
    type: 'text',
    content: '大家好，这是一条测试消息',
    senderId: 'user_123',
    senderName: '张三',
    timestamp: Date.now()
  }
});

if (response.status === 201) {
  const message = await response.json();
  console.log('消息创建成功:', message);
}
```

### 2. 查询历史消息

```typescript
// 查询特定课堂的历史消息
const response = await chatMessageClient.history.$get({
  query: {
    classId: 'class_123456',
    page: 1,
    pageSize: 50
  }
});

if (response.status === 200) {
  const result = await response.json();
  console.log('历史消息:', result.data);
  console.log('分页信息:', result.pagination);
}
```

### 3. 获取消息列表

```typescript
// 获取所有消息（支持搜索和筛选）
const response = await chatMessageClient.$get({
  query: {
    page: 1,
    pageSize: 10,
    keyword: '测试',
    filters: JSON.stringify({
      type: 'text',
      timestamp: { gte: 1704067200000 }
    })
  }
});

if (response.status === 200) {
  const result = await response.json();
  console.log('消息列表:', result.data);
}
```

## 服务类方法

### ChatMessageService

```typescript
// 根据课堂ID获取历史记录
const [messages, total] = await chatMessageService.getHistoryByClassId(
  'class_123456', 
  1, // page
  50 // pageSize
);

// 获取最新消息
const latestMessages = await chatMessageService.getLatestMessages(
  'class_123456', 
  20 // limit
);

// 创建单条消息
const message = await chatMessageService.createMessage(messageData, userId);

// 批量创建消息
const messages = await chatMessageService.createMessages(
  messageArray, 
  userId
);
```

## 类型定义

### 客户端类型

```typescript
import type { InferResponseType, InferRequestType } from 'hono/client';

// 响应类型
type ChatMessageResponse = InferResponseType<typeof chatMessageClient.$get, 200>;
type ChatMessageDetail = InferResponseType<typeof chatMessageClient[':id']['$get'], 200>;

// 请求类型
type CreateChatMessageRequest = InferRequestType<typeof chatMessageClient.$post>['json'];
type UpdateChatMessageRequest = InferRequestType<typeof chatMessageClient[':id']['$put']>['json'];
```

## 筛选功能

支持多种筛选操作：

```typescript
// 精确匹配
filters: JSON.stringify({ type: 'text' })

// 模糊搜索
filters: JSON.stringify({ content: '%关键词%' })

// 范围查询
filters: JSON.stringify({ 
  timestamp: { 
    gte: 1704067200000, // 开始时间
    lte: 1704153600000  // 结束时间
  }
})

// IN查询
filters: JSON.stringify({ 
  type: ['text', 'system'] 
})
```

## 注意事项

1. **认证要求**: 所有API都需要有效的JWT token
2. **用户追踪**: 创建和更新操作会自动记录操作人ID
3. **时间戳**: 使用毫秒时间戳，便于前端显示和处理
4. **消息类型**: 支持 text、image、system 三种类型
5. **分页**: 所有列表接口都支持分页，默认pageSize为10

## 错误处理

所有API都返回统一的错误格式：

```json
{
  "code": 错误代码,
  "message": "错误描述",
  "errors": "详细错误信息（可选）"
}
```

常见错误代码：
- 400: 参数验证失败
- 401: 未授权访问
- 404: 资源不存在
- 500: 服务器内部错误

## 性能优化

1. 为常用查询字段（classId、timestamp）添加数据库索引
2. 使用分页避免返回大量数据
3. 合理设置搜索字段，避免全表扫描
4. 使用缓存机制存储频繁访问的数据