WebSocket API 概览

即时通讯（IM）模块通过 WebSocket 与客户端双向通信。服务端主动推送消息更新，客户端可通过 WebSocket 命令发送群消息。

---

终结点

ws://ydzx.panretro.com/external/api/v1/im/imWebSocket/{accessToken}

accessToken 为 OAuth2 授权令牌，通过 /external/api/v1/account/login 获取。

获取令牌

POST /external/api/v1/account/login

参数	类型	必填	说明
account	string	是	账号 ID
password	string	是	密码或 MD5
loginType	string	是	account（明文密码）/ md5（MD5 安全登录）/ 其他（QQ 号 + 明文密码）

MD5 安全登录：用户首次通过网页用明文密码登录后，服务端自动存储 md5PasswordHash（sha256(md5(plain) + salt)）。之后外部 API 可传 loginType=md5 + password=<MD5(明文)> 登录，无需传输明文密码。

消息格式

所有 WebSocket 消息均为 JSON 文本帧，统一结构：

{
  "type": "MessageType",
  "code": 200,
  "identifier": "...",
  "data": ...,
  "msg": "..."
}

字段	说明
type	消息类型，见下方类型表
code	状态码，200 为成功
identifier	客户端传入的标识，服务端原样返回（仅请求-响应模式）
data	负载数据
msg	附加消息文本

消息类型 (ImTransferType)

类型	Code	方向	说明
LoginSuccess	200	服务端→客户端	连接认证成功
LoginFail	400	服务端→客户端	accessToken 无效或已过期
LackOfPermission	403	服务端→客户端	accessToken 缺少 chat scope
MessageUpdate	1	服务端→客户端	新消息推送（群内其他用户发言）
SendMessageResult	2	服务端→客户端	发送群消息的结果
FetchChatHistory	3	服务端→客户端	查询群聊历史记录的结果
OperationFailed	500	服务端→客户端	操作失败

API 列表

文档	说明
建立链接	连接建立与认证
发送群消息	客户端发送群消息
查询群聊历史	查询群聊历史记录
接收消息推送	接收服务端推送的消息
心跳机制	心跳机制

涉及文件

文件	说明
external/ws/ImWebSocketConnect.java	WebSocket 端点
messager/enums/ImTransferType.java	消息类型枚举
config/SpringContextHolder.java	Spring Bean 获取工具