@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/websocket/hub.go

@@ -0,0 +1,269 @@
+package websocket
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	ws "github.com/gorilla/websocket"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// Hub WebSocket 连接中心
+// 管理所有活跃连接，按用户 ID 路由消息
+// 通过 channel 实现并发安全，避免锁竞争
+type Hub struct {
+	logger *zap.Logger
+	config HubConfig
+
+	// 注册/注销/鉴权通道（并发安全的核心机制）
+	register     chan *Client
+	unregister   chan *Client
+	authenticate chan *Client
+
+	// 用户 ID → 连接集合（一个用户可能有多个标签页）
+	mu      sync.RWMutex
+	users   map[int64]map[string]*Client // userID -> clientID -> Client
+	clients map[string]*Client           // clientID -> Client
+
+	// 连接认证器
+	authenticator Authenticator
+
+	// 关闭信号
+	done chan struct{}
+}
+
+// NewHub 创建 Hub
+func NewHub(logger *zap.Logger, authenticator Authenticator, cfg ...HubConfig) *Hub {
+	config := DefaultHubConfig()
+	if len(cfg) > 0 {
+		config = cfg[0]
+	}
+
+	return &Hub{
+		logger:        logger.Named("WebSocketHub"),
+		config:        config,
+		register:      make(chan *Client, 64),
+		unregister:    make(chan *Client, 64),
+		authenticate:  make(chan *Client, 64),
+		users:         make(map[int64]map[string]*Client),
+		clients:       make(map[string]*Client),
+		authenticator: authenticator,
+		done:          make(chan struct{}),
+	}
+}
+
+// Run 启动 Hub 事件循环（应在独立 goroutine 中运行）
+// ctx 取消时会优雅关闭所有连接
+func (h *Hub) Run(ctx context.Context) {
+	h.logger.Info("websocket hub started")
+	defer h.logger.Info("websocket hub stopped")
+
+	for {
+		select {
+		case client := <-h.register:
+			h.mu.Lock()
+			h.clients[client.id] = client
+			h.mu.Unlock()
+
+			h.logger.Debug("client registered",
+				zap.String("clientID", client.id),
+			)
+
+		case client := <-h.authenticate:
+			h.mu.Lock()
+			// 检查用户连接数上限
+			if conns, ok := h.users[client.userID]; ok {
+				if len(conns) >= h.config.MaxConnsPerUser {
+					// 关闭最旧的连接（map 遍历取第一个即可）
+					for _, oldest := range conns {
+						oldest.sendError("CONNECTION_REPLACED",
+							"New connection opened, closing this one")
+						delete(conns, oldest.id)
+						oldest.closeSend()
+						break
+					}
+				}
+			} else {
+				h.users[client.userID] = make(map[string]*Client)
+			}
+			h.users[client.userID][client.id] = client
+			h.mu.Unlock()
+
+			h.logger.Info("client authenticated",
+				zap.String("clientID", client.id),
+				zap.Int64("userID", client.userID),
+			)
+
+		case client := <-h.unregister:
+			h.mu.Lock()
+			if _, ok := h.clients[client.id]; ok {
+				delete(h.clients, client.id)
+				if conns, ok := h.users[client.userID]; ok {
+					delete(conns, client.id)
+					if len(conns) == 0 {
+						delete(h.users, client.userID)
+					}
+				}
+				client.closeSend()
+			}
+			h.mu.Unlock()
+
+			h.logger.Debug("client unregistered",
+				zap.String("clientID", client.id),
+				zap.Int64("userID", client.userID),
+			)
+
+		case <-ctx.Done():
+			h.shutdown()
+			return
+
+		case <-h.done:
+			return
+		}
+	}
+}
+
+// SendToUser 向指定用户的所有连接发送消息
+func (h *Hub) SendToUser(userID int64, envelope Envelope) {
+	h.mu.RLock()
+	conns, ok := h.users[userID]
+	if !ok {
+		h.mu.RUnlock()
+		return
+	}
+	// 复制连接列表，避免持锁期间执行 I/O
+	targets := make([]*Client, 0, len(conns))
+	for _, c := range conns {
+		targets = append(targets, c)
+	}
+	h.mu.RUnlock()
+
+	for _, client := range targets {
+		client.sendEnvelope(envelope)
+	}
+}
+
+// HandleUpgrade 处理 WebSocket 升级后的连接
+// 创建 Client 并启动读写 goroutine
+func (h *Hub) HandleUpgrade(conn *ws.Conn) {
+	clientID := fmt.Sprintf("ws_%d_%s", time.Now().UnixMilli(), uuid.New().String()[:8])
+
+	client := &Client{
+		id:     clientID,
+		conn:   conn,
+		send:   make(chan []byte, h.config.SendBufferSize),
+		hub:    h,
+		logger: h.logger,
+	}
+
+	h.register <- client
+
+	go client.writePump()
+	go client.readPump()
+}
+
+// StartRedisSubscriber 启动 Redis Pub/Sub 订阅
+// 使用模式订阅 ws:user:* 接收所有用户消息，同时订阅 ws:broadcast 广播频道
+func (h *Hub) StartRedisSubscriber(ctx context.Context, redisClient *redis.Client) {
+	go h.redisSubscribeLoop(ctx, redisClient)
+}
+
+// ActiveConnections 获取活跃连接数（用于 metrics）
+func (h *Hub) ActiveConnections() int {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return len(h.clients)
+}
+
+// ActiveUsers 获取活跃用户数（用于 metrics）
+func (h *Hub) ActiveUsers() int {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return len(h.users)
+}
+
+// authenticateToken 验证 JWT token
+func (h *Hub) authenticateToken(ctx context.Context, token string) (AuthContext, error) {
+	return h.authenticator.Authenticate(ctx, token)
+}
+
+func (h *Hub) revalidateAuthentication(ctx context.Context, auth AuthContext) error {
+	return h.authenticator.Revalidate(ctx, auth)
+}
+
+// shutdown 关闭所有连接
+func (h *Hub) shutdown() {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	for _, client := range h.clients {
+		client.closeSend()
+	}
+	h.clients = make(map[string]*Client)
+	h.users = make(map[int64]map[string]*Client)
+}
+
+// redisSubscribeLoop Redis 订阅主循环
+// 使用模式订阅 ws:user:* 接收所有用户消息
+func (h *Hub) redisSubscribeLoop(ctx context.Context, redisClient *redis.Client) {
+	pubsub := redisClient.PSubscribe(ctx, "ws:user:*", "ws:broadcast")
+	defer pubsub.Close()
+
+	h.logger.Info("redis pub/sub subscriber started")
+
+	ch := pubsub.Channel()
+	for {
+		select {
+		case msg, ok := <-ch:
+			if !ok {
+				h.logger.Warn("redis pub/sub channel closed")
+				return
+			}
+			h.handleRedisMessage(msg)
+
+		case <-ctx.Done():
+			h.logger.Info("redis pub/sub subscriber stopping")
+			return
+		}
+	}
+}
+
+// handleRedisMessage 处理 Redis 频道消息
+func (h *Hub) handleRedisMessage(msg *redis.Message) {
+	var envelope Envelope
+	if err := json.Unmarshal([]byte(msg.Payload), &envelope); err != nil {
+		h.logger.Warn("unmarshal redis message failed",
+			zap.String("channel", msg.Channel),
+			zap.Error(err),
+		)
+		return
+	}
+
+	if msg.Channel == "ws:broadcast" {
+		// 广播给所有在线用户
+		h.mu.RLock()
+		for _, conns := range h.users {
+			for _, client := range conns {
+				client.sendEnvelope(envelope)
+			}
+		}
+		h.mu.RUnlock()
+		return
+	}
+
+	// 解析 ws:user:{userID} 格式
+	var userID int64
+	if _, err := fmt.Sscanf(msg.Channel, "ws:user:%d", &userID); err != nil {
+		h.logger.Warn("invalid channel format",
+			zap.String("channel", msg.Channel),
+		)
+		return
+	}
+
+	h.SendToUser(userID, envelope)
+}

package/dist/resources/templates/go-backend/internal/core/websocket/message.go

@@ -0,0 +1,273 @@
+package websocket
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// MessageType WebSocket 消息类型
+type MessageType string
+
+const (
+	// MsgTypeConnected 连接确认
+	MsgTypeConnected MessageType = "connected"
+	// MsgTypeUploadProgress 分片上传进度
+	MsgTypeUploadProgress MessageType = "upload.progress"
+	// MsgTypeUploadCompleted 上传完成
+	MsgTypeUploadCompleted MessageType = "upload.completed"
+	// MsgTypeUploadFailed 上传失败
+	MsgTypeUploadFailed MessageType = "upload.failed"
+	// MsgTypeProcessingStarted 媒体处理开始
+	MsgTypeProcessingStarted MessageType = "processing.started"
+	// MsgTypeProcessingProgress 处理进度
+	MsgTypeProcessingProgress MessageType = "processing.progress"
+	// MsgTypeProcessingCompleted 处理完成
+	MsgTypeProcessingCompleted MessageType = "processing.completed"
+	// MsgTypeProcessingFailed 处理失败
+	MsgTypeProcessingFailed MessageType = "processing.failed"
+	// MsgTypeScanCompleted 病毒扫描完成
+	MsgTypeScanCompleted MessageType = "scan.completed"
+	// MsgTypeBatchProgress 批量操作进度
+	MsgTypeBatchProgress MessageType = "batch.progress"
+	// MsgTypeBatchCompleted 批量操作完成
+	MsgTypeBatchCompleted MessageType = "batch.completed"
+	// MsgTypeExportProgress 导出进度
+	MsgTypeExportProgress MessageType = "export.progress"
+	// MsgTypeExportCompleted 导出完成
+	MsgTypeExportCompleted MessageType = "export.completed"
+	// MsgTypeExportFailed 导出失败
+	MsgTypeExportFailed MessageType = "export.failed"
+	// MsgTypeNotification 通用通知
+	MsgTypeNotification MessageType = "notification"
+	// MsgTypeError 系统错误
+	MsgTypeError MessageType = "error"
+)
+
+// Envelope WebSocket 消息信封
+// 所有通过 WebSocket 传输的消息均使用此统一格式
+type Envelope struct {
+	// 事件类型
+	Type MessageType `json:"type"`
+	// 关联的请求 ID（用于前端去重）
+	RequestID string `json:"request_id,omitempty"`
+	// ISO 8601 格式时间戳
+	Timestamp time.Time `json:"timestamp"`
+	// 事件具体载荷（使用 any 是因为不同事件类型有不同的载荷结构）
+	Payload any `json:"payload"`
+}
+
+// ClientMessage 客户端发送的消息
+type ClientMessage struct {
+	// 消息类型（auth / pong 等）
+	Type string `json:"type"`
+	// 原始载荷，延迟解析
+	Payload json.RawMessage `json:"payload"`
+}
+
+// AuthPayload 鉴权消息载荷
+type AuthPayload struct {
+	// JWT 访问令牌
+	Token string `json:"token"`
+}
+
+// ConnectedPayload 连接确认载荷
+type ConnectedPayload struct {
+	// 连接唯一标识
+	ConnectionID string `json:"connection_id"`
+	// 用户 ID
+	UserID int64 `json:"user_id"`
+	// 服务器当前时间
+	ServerTime time.Time `json:"server_time"`
+}
+
+// UploadProgressPayload 上传进度载荷
+type UploadProgressPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 分片上传 ID
+	UploadID string `json:"upload_id,omitempty"`
+	// 已完成分片数
+	CompletedParts int `json:"completed_parts"`
+	// 总分片数
+	TotalParts int `json:"total_parts"`
+	// 进度百分比
+	ProgressPercent int `json:"progress_percent"`
+	// 文件名
+	Filename string `json:"filename"`
+}
+
+// ProcessingStartedPayload 处理开始载荷
+type ProcessingStartedPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 处理任务 ID
+	JobID int64 `json:"job_id"`
+	// 任务类型
+	JobType string `json:"job_type"`
+	// 文件名
+	Filename string `json:"filename"`
+}
+
+// ProcessingProgressPayload 处理进度载荷
+type ProcessingProgressPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 处理任务 ID
+	JobID int64 `json:"job_id"`
+	// 当前步骤
+	CurrentStep int `json:"current_step"`
+	// 总步骤数
+	TotalSteps int `json:"total_steps"`
+	// 进度百分比
+	ProgressPercent int `json:"progress_percent"`
+	// 步骤描述
+	StepDescription string `json:"step_description"`
+}
+
+// ProcessingCompletedPayload 处理完成载荷
+type ProcessingCompletedPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 处理任务 ID
+	JobID int64 `json:"job_id"`
+	// 已生成的变体数量
+	VariantCount int `json:"variant_count"`
+	// 内容分类
+	ContentClass string `json:"content_class"`
+	// 原始宽度
+	OriginalWidth int `json:"original_width"`
+	// 原始高度
+	OriginalHeight int `json:"original_height"`
+	// 变体摘要列表
+	Variants []VariantSummary `json:"variants"`
+}
+
+// VariantSummary 变体摘要（WebSocket 通知专用，非数据库模型）
+type VariantSummary struct {
+	// 变体类型（thumbnail / small / medium 等）
+	Type string `json:"type"`
+	// 输出格式
+	Format string `json:"format"`
+	// 宽度
+	Width int `json:"width"`
+	// 高度
+	Height int `json:"height"`
+	// 文件大小（字节）
+	Size int64 `json:"size"`
+	// CDN 访问 URL
+	CDNURL string `json:"cdn_url,omitempty"`
+}
+
+// ProcessingFailedPayload 处理失败载荷
+type ProcessingFailedPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 处理任务 ID
+	JobID int64 `json:"job_id"`
+	// 错误码
+	ErrorCode string `json:"error_code"`
+	// 错误消息
+	ErrorMessage string `json:"error_message"`
+	// 是否可重试
+	Retryable bool `json:"retryable"`
+}
+
+// ScanCompletedPayload 扫描完成载荷
+type ScanCompletedPayload struct {
+	// 资产 ID
+	AssetID int64 `json:"asset_id"`
+	// 扫描任务 ID
+	JobID int64 `json:"job_id"`
+	// 是否安全
+	Safe bool `json:"safe"`
+	// 威胁名称（仅在发现威胁时非空）
+	Threat string `json:"threat,omitempty"`
+	// 文件名
+	Filename string `json:"filename"`
+}
+
+// BatchProgressPayload 批量进度载荷
+type BatchProgressPayload struct {
+	// 批次 ID
+	BatchID string `json:"batch_id"`
+	// 总项目数
+	TotalItems int `json:"total_items"`
+	// 已完成项目数
+	CompletedItems int `json:"completed_items"`
+	// 失败项目数
+	FailedItems int `json:"failed_items"`
+	// 进度百分比
+	ProgressPercent int `json:"progress_percent"`
+}
+
+// BatchCompletedPayload 批量完成载荷
+type BatchCompletedPayload struct {
+	// 批次 ID
+	BatchID string `json:"batch_id"`
+	// 总项目数
+	TotalItems int `json:"total_items"`
+	// 成功项目数
+	SucceededItems int `json:"succeeded_items"`
+	// 失败项目数
+	FailedItems int `json:"failed_items"`
+	// 失败的资产 ID 列表
+	FailedAssetIDs []int64 `json:"failed_asset_ids,omitempty"`
+	// 总耗时（毫秒）
+	DurationMs int64 `json:"duration_ms"`
+}
+
+// ExportProgressPayload 导出进度载荷
+type ExportProgressPayload struct {
+	// 导出任务公共引用
+	ExportNo string `json:"export_no"`
+	// 资源类型
+	ResourceType string `json:"resource_type"`
+	// 任务状态
+	Status string `json:"status"`
+	// 已处理记录数
+	ProcessedCount int64 `json:"processed_count"`
+	// 总记录数
+	TotalCount int64 `json:"total_count"`
+	// 进度百分比
+	ProgressPercent int `json:"progress_percent"`
+}
+
+// ExportCompletedPayload 导出完成载荷
+type ExportCompletedPayload struct {
+	// 导出任务公共引用
+	ExportNo string `json:"export_no"`
+	// 资源类型
+	ResourceType string `json:"resource_type"`
+	// 任务状态
+	Status string `json:"status"`
+	// 已处理记录数
+	ProcessedCount int64 `json:"processed_count"`
+	// 总记录数
+	TotalCount int64 `json:"total_count"`
+	// 下载地址
+	DownloadURL string `json:"download_url"`
+}
+
+// ExportFailedPayload 导出失败载荷
+type ExportFailedPayload struct {
+	// 导出任务公共引用
+	ExportNo string `json:"export_no"`
+	// 资源类型
+	ResourceType string `json:"resource_type"`
+	// 任务状态
+	Status string `json:"status"`
+	// 已处理记录数
+	ProcessedCount int64 `json:"processed_count"`
+	// 总记录数
+	TotalCount int64 `json:"total_count"`
+	// 错误消息
+	ErrorMessage string `json:"error_message"`
+}
+
+// ErrorPayload 错误载荷
+type ErrorPayload struct {
+	// 错误码
+	Code string `json:"code"`
+	// 错误消息
+	Message string `json:"message"`
+}

package/dist/resources/templates/go-backend/internal/core/websocket/notifier.go

@@ -0,0 +1,92 @@
+package websocket
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// Notifier 实时通知发布接口
+// 由 Worker 或 Service 层调用，将消息发布到 Redis Pub/Sub
+// Hub 订阅 Redis 频道后转发到对应用户的 WebSocket 连接
+type Notifier interface {
+	// NotifyUser 向指定用户发送通知
+	NotifyUser(ctx context.Context, userID int64, msgType MessageType, payload any) error
+	// Broadcast 向所有在线用户广播（谨慎使用）
+	Broadcast(ctx context.Context, msgType MessageType, payload any) error
+}
+
+// redisNotifier Redis Pub/Sub 实现
+type redisNotifier struct {
+	client *redis.Client
+	logger *zap.Logger
+}
+
+// NewNotifier 创建 Redis Notifier
+func NewNotifier(client *redis.Client, logger *zap.Logger) *redisNotifier {
+	return &redisNotifier{
+		client: client,
+		logger: logger.Named("WSNotifier"),
+	}
+}
+
+// NotifyUser 向指定用户发送通知
+// 通过 Redis PUBLISH 将消息发布到 ws:user:{userID} 频道
+func (n *redisNotifier) NotifyUser(ctx context.Context, userID int64, msgType MessageType, payload any) error {
+	envelope := Envelope{
+		Type:      msgType,
+		Timestamp: time.Now(),
+		// Payload 使用 any 是因为不同事件类型有不同的载荷结构
+		Payload: payload,
+	}
+
+	data, err := json.Marshal(envelope)
+	if err != nil {
+		return fmt.Errorf("marshal notification: %w", err)
+	}
+
+	channel := fmt.Sprintf("ws:user:%d", userID)
+	if err := n.client.Publish(ctx, channel, data).Err(); err != nil {
+		n.logger.Error("publish notification failed",
+			zap.Int64("userID", userID),
+			zap.String("msgType", string(msgType)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("publish to %s: %w", channel, err)
+	}
+
+	n.logger.Debug("notification published",
+		zap.Int64("userID", userID),
+		zap.String("msgType", string(msgType)),
+	)
+	return nil
+}
+
+// Broadcast 向所有在线用户广播
+// 通过 Redis PUBLISH 将消息发布到 ws:broadcast 频道
+func (n *redisNotifier) Broadcast(ctx context.Context, msgType MessageType, payload any) error {
+	envelope := Envelope{
+		Type:      msgType,
+		Timestamp: time.Now(),
+		Payload:   payload,
+	}
+
+	data, err := json.Marshal(envelope)
+	if err != nil {
+		return fmt.Errorf("marshal broadcast: %w", err)
+	}
+
+	if err := n.client.Publish(ctx, "ws:broadcast", data).Err(); err != nil {
+		n.logger.Error("broadcast failed",
+			zap.String("msgType", string(msgType)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("publish broadcast: %w", err)
+	}
+
+	return nil
+}

package/dist/resources/templates/go-backend/internal/core/websocket/provider.go

@@ -0,0 +1,33 @@
+package websocket
+
+import "github.com/google/wire"
+
+// ProviderSet WebSocket 基础设施 Wire 依赖集
+//
+// 提供以下依赖：
+//   - *Hub — WebSocket 连接中心
+//   - Notifier — 实时通知发布接口（Redis Pub/Sub 实现）
+//
+// 前置依赖：
+//   - *redis.Client — Redis 客户端（来自 core.InfraProviderSet）
+//   - *zap.Logger — 结构化日志
+//   - Authenticator — 持续认证适配器（由装配层提供）
+//
+// Hub 需要调用方在独立 goroutine 中启动 Run() 和 StartRedisSubscriber()
+var ProviderSet = wire.NewSet(
+	NewHub,
+	NewNotifier,
+	wire.Bind(new(Notifier), new(*redisNotifier)),
+)
+
+// NotifierProviderSet 仅提供 Notifier 的轻量级依赖集
+//
+// 适用于不需要 Hub（无 WebSocket 服务端）但需要通过 Redis Pub/Sub 推送实时通知的进程（如 Worker）
+//
+// 前置依赖：
+//   - *redis.Client — Redis 客户端
+//   - *zap.Logger — 结构化日志
+var NotifierProviderSet = wire.NewSet(
+	NewNotifier,
+	wire.Bind(new(Notifier), new(*redisNotifier)),
+)