feat(ws): WebSocket 核心模块（Hub + Client + PubSub + Handler）

- pkg/ws/message.go: 统一消息协议（Message/Response/PushMessage）
- pkg/ws/hub.go: Hub 连接管理（注册/注销/按 userID 查找/在线计数）
- pkg/ws/client.go: 客户端连接封装（readPump/writePump/心跳 30s）
- pkg/ws/pubsub.go: Redis Pub/Sub 消息路由（按用户频道发布/订阅）
- app/ws/handler.go: WebSocket 升级处理（JWT 认证 + 消息分发）
- app/ws/router.go: GET /ws 路由注册
- app/ws/provider.go: Wire Provider Set
- 更新 provider/router 集成 WebSocket 模块

Made-with: Cursor

backend/go-service/app/provider/provider.go

@@ -6,8 +6,10 @@ import (
 	adminController "github.com/echochat/backend/app/admin/controller"
 	authController "github.com/echochat/backend/app/auth/controller"
 	"github.com/echochat/backend/app/auth/service"
+	wsApp "github.com/echochat/backend/app/ws"
 	"github.com/echochat/backend/config"
 	"github.com/echochat/backend/pkg/db"
+	"github.com/echochat/backend/pkg/ws"
 	"github.com/google/wire"
 	"github.com/redis/go-redis/v9"
 	"gorm.io/gorm"
@@ -22,6 +24,9 @@ type App struct {
 	AuthController        *authController.AuthController              // 前台认证控制器
 	AdminAuthController   *authController.AdminAuthController         // 后台认证控制器
 	UserManageController  *adminController.UserManageController       // 管理端用户管理控制器
+	WSHandler             *wsApp.Handler                              // WebSocket 连接处理器
+	Hub                   *ws.Hub                                     // WebSocket Hub 连接管理
+	PubSub                *ws.PubSub                                  // Redis Pub/Sub 消息路由
 }
 
 // NewApp 创建应用实例
@@ -33,6 +38,9 @@ func NewApp(
 	authCtrl *authController.AuthController,
 	adminAuthCtrl *authController.AdminAuthController,
 	userManageCtrl *adminController.UserManageController,
+	wsHandler *wsApp.Handler,
+	hub *ws.Hub,
+	pubsub *ws.PubSub,
 ) *App {
 	return &App{
 		Config:                cfg,
@@ -42,6 +50,9 @@ func NewApp(
 		AuthController:        authCtrl,
 		AdminAuthController:   adminAuthCtrl,
 		UserManageController:  userManageCtrl,
+		WSHandler:             wsHandler,
+		Hub:                   hub,
+		PubSub:                pubsub,
 	}
 }
 

backend/go-service/app/provider/wire.go

@@ -6,6 +6,7 @@ package provider
 import (
 	"github.com/echochat/backend/app/admin"
 	"github.com/echochat/backend/app/auth"
+	wsApp "github.com/echochat/backend/app/ws"
 	"github.com/echochat/backend/config"
 	"github.com/google/wire"
 )
@@ -16,6 +17,7 @@ func InitializeApp(cfg *config.Config) (*App, error) {
 		InfraSet,
 		auth.AuthSet,
 		admin.AdminSet,
+		wsApp.WSSet,
 	)
 	return nil, nil
 }

backend/go-service/app/provider/wire_gen.go

@@ -7,12 +7,13 @@
 package provider
 
 import (
-	adminController "github.com/echochat/backend/app/admin/controller"
-	adminDAO "github.com/echochat/backend/app/admin/dao"
-	adminService "github.com/echochat/backend/app/admin/service"
+	controller2 "github.com/echochat/backend/app/admin/controller"
+	dao2 "github.com/echochat/backend/app/admin/dao"
+	service2 "github.com/echochat/backend/app/admin/service"
 	"github.com/echochat/backend/app/auth/controller"
 	"github.com/echochat/backend/app/auth/dao"
 	"github.com/echochat/backend/app/auth/service"
+	"github.com/echochat/backend/app/ws"
 	"github.com/echochat/backend/config"
 	"github.com/echochat/backend/pkg/db"
 )
@@ -38,9 +39,12 @@ func InitializeApp(cfg *config.Config) (*App, error) {
 	authService := service.NewAuthService(userDAO, roleDAO, jwtConfig, tokenStore)
 	authController := controller.NewAuthController(authService)
 	adminAuthController := controller.NewAdminAuthController(authService)
-	userManageDAO := adminDAO.NewUserManageDAO(gormDB)
-	userManageService := adminService.NewUserManageService(userManageDAO, userDAO, roleDAO)
-	userManageController := adminController.NewUserManageController(userManageService)
-	app := NewApp(cfg, gormDB, client, authService, authController, adminAuthController, userManageController)
+	userManageDAO := dao2.NewUserManageDAO(gormDB)
+	userManageService := service2.NewUserManageService(userManageDAO, userDAO, roleDAO)
+	userManageController := controller2.NewUserManageController(userManageService)
+	hub := ws.ProvideHub()
+	pubSub := ws.ProvidePubSub(client, hub)
+	handler := ws.ProvideWSHandler(hub, pubSub, jwtConfig)
+	app := NewApp(cfg, gormDB, client, authService, authController, adminAuthController, userManageController, handler, hub, pubSub)
 	return app, nil
 }

backend/go-service/app/ws/handler.go

@@ -0,0 +1,106 @@
+// Package ws 提供 WebSocket 连接处理
+// 负责 HTTP → WebSocket 升级、JWT 认证、消息路由分发
+package ws
+
+import (
+	"net/http"
+
+	"github.com/echochat/backend/config"
+	"github.com/echochat/backend/pkg/logs"
+	"github.com/echochat/backend/pkg/utils"
+	"github.com/echochat/backend/pkg/ws"
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+	"go.uber.org/zap"
+)
+
+var upgrader = websocket.Upgrader{
+	ReadBufferSize:  1024,
+	WriteBufferSize: 1024,
+	CheckOrigin: func(r *http.Request) bool {
+		return true // 开发阶段允许所有来源，生产环境需限制
+	},
+}
+
+// Handler WebSocket 连接处理器
+type Handler struct {
+	hub    *ws.Hub
+	pubsub *ws.PubSub
+	jwtCfg *config.JWTConfig
+}
+
+// NewHandler 创建 WebSocket Handler 实例
+func NewHandler(hub *ws.Hub, pubsub *ws.PubSub, jwtCfg *config.JWTConfig) *Handler {
+	return &Handler{
+		hub:    hub,
+		pubsub: pubsub,
+		jwtCfg: jwtCfg,
+	}
+}
+
+// Upgrade 处理 WebSocket 升级请求
+// GET /ws?token=xxx → JWT 认证 → 升级连接 → 注册 Hub → 订阅 Redis 频道
+func (h *Handler) Upgrade(c *gin.Context) {
+	funcName := "ws.handler.Upgrade"
+
+	token := c.Query("token")
+	if token == "" {
+		utils.ResponseUnauthorized(c, "缺少认证 Token")
+		return
+	}
+
+	claims, err := utils.ParseToken(h.jwtCfg, token)
+	if err != nil {
+		logs.Warn(nil, funcName, "WebSocket Token 验证失败", zap.Error(err))
+		utils.ResponseUnauthorized(c, "Token 无效或已过期")
+		return
+	}
+
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		logs.Error(nil, funcName, "WebSocket 升级失败",
+			zap.Int64("user_id", claims.UserID), zap.Error(err))
+		return
+	}
+
+	client := ws.NewClient(h.hub, conn, claims.UserID)
+	h.hub.Register(client)
+	h.pubsub.Subscribe(claims.UserID)
+
+	logs.Info(nil, funcName, "WebSocket 连接建立",
+		zap.Int64("user_id", claims.UserID),
+		zap.String("ip", c.ClientIP()))
+
+	go client.WritePump()
+	go client.ReadPump(h.onMessage)
+}
+
+// onMessage 处理客户端发来的 WebSocket 消息
+// 根据 event 类型分发到不同的处理逻辑
+func (h *Handler) onMessage(client *ws.Client, msg *ws.Message) {
+	funcName := "ws.handler.onMessage"
+	logs.Debug(nil, funcName, "收到 WebSocket 消息",
+		zap.Int64("user_id", client.UserID),
+		zap.String("event", msg.Event),
+		zap.Int64("seq", msg.Seq))
+
+	// Phase 2a 阶段暂无需要客户端主动发送的事件
+	// Phase 2b 将在此处添加 im.message.send 等事件路由
+	resp := ws.NewResponse(msg.Event, msg.Seq, 0, "ok", nil)
+	data, err := ws.MarshalResponse(resp)
+	if err != nil {
+		logs.Error(nil, funcName, "序列化响应失败", zap.Error(err))
+		return
+	}
+	client.Send(data)
+}
+
+// GetHub 返回 Hub 实例（供在线状态等模块访问）
+func (h *Handler) GetHub() *ws.Hub {
+	return h.hub
+}
+
+// GetPubSub 返回 PubSub 实例（供业务模块发送推送）
+func (h *Handler) GetPubSub() *ws.PubSub {
+	return h.pubsub
+}

backend/go-service/app/ws/provider.go

@@ -0,0 +1,32 @@
+package ws
+
+import (
+	"github.com/echochat/backend/config"
+	"github.com/echochat/backend/pkg/ws"
+	"github.com/google/wire"
+	"github.com/redis/go-redis/v9"
+)
+
+// ProvideHub 创建并启动 Hub 实例
+func ProvideHub() *ws.Hub {
+	hub := ws.NewHub()
+	go hub.Run()
+	return hub
+}
+
+// ProvidePubSub 创建 PubSub 实例
+func ProvidePubSub(rdb *redis.Client, hub *ws.Hub) *ws.PubSub {
+	return ws.NewPubSub(rdb, hub)
+}
+
+// ProvideWSHandler 创建 WebSocket Handler
+func ProvideWSHandler(hub *ws.Hub, pubsub *ws.PubSub, cfg *config.JWTConfig) *Handler {
+	return NewHandler(hub, pubsub, cfg)
+}
+
+// WSSet WebSocket 模块 Wire Provider Set
+var WSSet = wire.NewSet(
+	ProvideHub,
+	ProvidePubSub,
+	ProvideWSHandler,
+)

backend/go-service/app/ws/router.go

@@ -0,0 +1,8 @@
+package ws
+
+import "github.com/gin-gonic/gin"
+
+// RegisterRoutes 注册 WebSocket 相关路由
+func RegisterRoutes(engine *gin.Engine, handler *Handler) {
+	engine.GET("/ws", handler.Upgrade)
+}