go-ws-module-skill

Go Gin WebSocket Module Skill

为 Go Gin 项目叠加一套 WebSocket 即时通信能力，不是重新生成新项目。

定位

• 目标：在已有 go-gin-init-skill 骨架上，添加可运行的 WebSocket 通信模块。
• 不替代：不重复生成 go-gin-init-skill 已经提供的 JWT、统一响应、GORM 等基础设施。
• 不做腾讯 IM：自建轻量方案，适合小中规模，不依赖第三方 IM 服务。
• 输出：连接管理器、消息路由、消息存储、离线推送、会话管理、好友校验、接口契约。

骨架依赖（子模块）

本模块是 go-gin-init-skill 的子模块，必须在骨架基础上使用。

使用前必须满足以下条件：

1. ✅ 已安装 go-gin-init-skill（项目骨架）
2. ✅ 骨架包含：JWT、统一响应、GORM、分页、目录结构
3. ✅ 遵循骨架的表前缀、字段命名、软删除规范

检测逻辑：

1. 读取用户项目根目录，检查是否包含 go-gin-init-skill 的标志性文件（main.go、config/config.go、middleware/auth.go）
2. 检查是否已有 getCurrentUser 依赖
3. 如未检测到骨架，提示："本模块需要先安装 go-gin-init-skill 骨架"
4. 如用户拒绝安装骨架，则终止并提示无法使用

用户问题（最多 3 个）

1. 现有项目的包名是什么？（默认从 go-gin-init-skill 推断，如 main）
2. 表前缀是什么？（默认 wg）
3. 是否需要群聊？（默认不需要，先做单聊）

核心能力清单

#	能力	说明
1	WebSocket 长连接	WS /api/ws?token=<jwt>，query 参数鉴权，多端登录
2	单聊消息	文本/图片/语音实时投递，在线直推，离线入库
3	好友校验	仅允许已通过好友互发消息
4	消息幂等	客户端传 client_msg_id，网络抖动重发不重复入库
5	离线消息	用户上线时自动推送未送达消息（最多 100 条）
6	未读数	单聊未读计数，支持清零 + 实时通知对方
7	会话列表	最近会话排序，最后一条消息预览
8	聊天记录	基于 cursor 翻页的历史消息查询
9	消息状态	未读 → 已送达 → 已读 三态流转
10	接口契约	生成 api-contract-ws.md，与前端对齐

生成流程

1. 确认已存在 Go Gin 骨架（含 JWT、统一响应、GORM）。
2. 询问用户包名、表前缀（默认 wg）、是否需要群聊。
3. 按 references/skeleton.go 生成 ws/ 下全部源码：
   • 将所有 {prefix} 占位符替换为用户指定的表前缀（如 wg_）
   • 将 ws 替换为用户的包名
4. 生成 api-contract-ws.md 与 docs/ws-module-guide.md。
5. 在 main.go 注册 WebSocket 路由。
6. 提示用户：重启服务后可通过 WebSocket 客户端测试连接。

模块结构

{{PROJECT_NAME}}/
├── main.go                         # 注册 WebSocket 路由
├── config/
│   └── config.go                   # 配置
├── ws/
│   ├── manager.go                  # WebSocket 连接管理器（多端登录）
│   ├── handler.go                  # 消息路由与处理
│   ├── hub.go                      # 消息分发中心
│   ├── models/
│   │   ├── message.go              # 消息模型
│   │   ├── conversation.go         # 会话模型
│   │   └── friend.go               # 好友模型
│   ├── services/
│   │   ├── message_service.go      # 消息存储与查询
│   │   └── conversation_service.go # 会话管理
│   ├── routers/
│   │   ├── ws.go                   # WebSocket 端点
│   │   ├── chat.go                 # REST 接口
│   │   └── friend.go               # 好友接口
│   └── utils/
│       ├── validators.go           # 消息校验
│       └── helpers.go              # 工具函数
├── migrations/
│   └── ws_module.sql              # 数据库迁移
├── api-contract-ws.md              # 接口契约
└── docs/
    └── ws-module-guide.md          # 接入指南