blank/CHAT_MESSAGE_GUIDE.md

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

功能概述

本功能提供了完整的聊天消息持久化解决方案，包括：

• 聊天消息实体定义
• 标准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)

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. 创建聊天消息

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. 查询历史消息

// 查询特定课堂的历史消息
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. 获取消息列表

// 获取所有消息（支持搜索和筛选）
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

// 根据课堂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
);

类型定义

客户端类型

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'];

筛选功能

支持多种筛选操作：

// 精确匹配
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都返回统一的错误格式：

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

常见错误代码：

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

性能优化

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