docs(constitution): 新增数据库设计原则(v2.4.0)

在项目宪章中新增第九条原则"数据库设计原则"，明确禁止使用数据库外键约束和ORM关联标签。

主要变更：
- 新增原则IX：数据库设计原则（Database Design Principles）
- 强制要求：数据库表不得使用外键约束
- 强制要求：GORM模型不得使用ORM关联标签（foreignKey、hasMany等）
- 强制要求：表关系必须通过ID字段手动维护
- 强制要求：关联数据查询必须显式编写，避免ORM魔法
- 强制要求：时间字段由GORM处理，不使用数据库触发器

设计理念：
- 提升业务逻辑灵活性（无数据库约束限制）
- 优化高并发性能（无外键检查开销）
- 增强代码可读性（显式查询，无隐式预加载）
- 简化数据库架构和迁移流程
- 支持分布式和微服务场景

版本升级：2.3.0 → 2.4.0（MINOR）

pkg/queue/client.go

@@ -0,0 +1,88 @@
+package queue
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/break/junhong_cmp_fiber/pkg/config"
+	"github.com/bytedance/sonic"
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// Client Asynq 任务提交客户端
+type Client struct {
+	client *asynq.Client
+	logger *zap.Logger
+}
+
+// NewClient 创建新的 Asynq 客户端
+func NewClient(redisClient *redis.Client, logger *zap.Logger) *Client {
+	// 从 Redis 客户端获取配置
+	opts := redisClient.Options()
+
+	asynqClient := asynq.NewClient(asynq.RedisClientOpt{
+		Addr:     opts.Addr,
+		Password: opts.Password,
+		DB:       opts.DB,
+	})
+
+	return &Client{
+		client: asynqClient,
+		logger: logger,
+	}
+}
+
+// EnqueueTask 提交任务到队列
+func (c *Client) EnqueueTask(ctx context.Context, taskType string, payload interface{}, opts ...asynq.Option) error {
+	// 序列化载荷
+	payloadBytes, err := sonic.Marshal(payload)
+	if err != nil {
+		c.logger.Error("任务载荷序列化失败",
+			zap.String("task_type", taskType),
+			zap.Error(err))
+		return fmt.Errorf("failed to marshal task payload: %w", err)
+	}
+
+	// 创建任务
+	task := asynq.NewTask(taskType, payloadBytes, opts...)
+
+	// 提交任务
+	info, err := c.client.EnqueueContext(ctx, task)
+	if err != nil {
+		c.logger.Error("任务提交失败",
+			zap.String("task_type", taskType),
+			zap.Error(err))
+		return fmt.Errorf("failed to enqueue task: %w", err)
+	}
+
+	c.logger.Info("任务已提交",
+		zap.String("task_id", info.ID),
+		zap.String("task_type", taskType),
+		zap.String("queue", info.Queue),
+		zap.Int("max_retry", info.MaxRetry))
+
+	return nil
+}
+
+// Close 关闭客户端
+func (c *Client) Close() error {
+	if c.client != nil {
+		return c.client.Close()
+	}
+	return nil
+}
+
+// ParseQueueConfig 解析队列配置为 Asynq 格式
+func ParseQueueConfig(cfg *config.QueueConfig) map[string]int {
+	if cfg.Queues != nil && len(cfg.Queues) > 0 {
+		return cfg.Queues
+	}
+	// 默认队列优先级
+	return map[string]int{
+		"critical": 6,
+		"default":  3,
+		"low":      1,
+	}
+}

pkg/queue/handler.go

@@ -0,0 +1,57 @@
+package queue
+
+import (
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/task"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// Handler 任务处理器注册
+type Handler struct {
+	mux    *asynq.ServeMux
+	logger *zap.Logger
+	db     *gorm.DB
+	redis  *redis.Client
+}
+
+// NewHandler 创建任务处理器
+func NewHandler(db *gorm.DB, redis *redis.Client, logger *zap.Logger) *Handler {
+	return &Handler{
+		mux:    asynq.NewServeMux(),
+		logger: logger,
+		db:     db,
+		redis:  redis,
+	}
+}
+
+// RegisterHandlers 注册所有任务处理器
+func (h *Handler) RegisterHandlers() *asynq.ServeMux {
+	// 创建任务处理器实例
+	emailHandler := task.NewEmailHandler(h.redis, h.logger)
+	syncHandler := task.NewSyncHandler(h.db, h.logger)
+	simHandler := task.NewSIMHandler(h.db, h.redis, h.logger)
+
+	// 注册邮件发送任务
+	h.mux.HandleFunc(constants.TaskTypeEmailSend, emailHandler.HandleEmailSend)
+	h.logger.Info("注册邮件发送任务处理器", zap.String("task_type", constants.TaskTypeEmailSend))
+
+	// 注册数据同步任务
+	h.mux.HandleFunc(constants.TaskTypeDataSync, syncHandler.HandleDataSync)
+	h.logger.Info("注册数据同步任务处理器", zap.String("task_type", constants.TaskTypeDataSync))
+
+	// 注册 SIM 卡状态同步任务
+	h.mux.HandleFunc(constants.TaskTypeSIMStatusSync, simHandler.HandleSIMStatusSync)
+	h.logger.Info("注册 SIM 状态同步任务处理器", zap.String("task_type", constants.TaskTypeSIMStatusSync))
+
+	h.logger.Info("所有任务处理器注册完成")
+	return h.mux
+}
+
+// GetMux 获取 ServeMux（用于启动 Worker 服务器）
+func (h *Handler) GetMux() *asynq.ServeMux {
+	return h.mux
+}

pkg/queue/server.go

@@ -0,0 +1,86 @@
+package queue
+
+import (
+	"github.com/break/junhong_cmp_fiber/pkg/config"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+)
+
+// Server Asynq Worker 服务器
+type Server struct {
+	server *asynq.Server
+	logger *zap.Logger
+}
+
+// NewServer 创建新的 Asynq 服务器
+func NewServer(redisClient *redis.Client, queueCfg *config.QueueConfig, logger *zap.Logger) *Server {
+	// 从 Redis 客户端获取配置
+	opts := redisClient.Options()
+
+	// 解析队列优先级配置
+	queues := ParseQueueConfig(queueCfg)
+
+	// 设置并发数
+	concurrency := queueCfg.Concurrency
+	if concurrency <= 0 {
+		concurrency = constants.DefaultConcurrency
+	}
+
+	// 创建 Asynq 服务器配置
+	asynqServer := asynq.NewServer(
+		asynq.RedisClientOpt{
+			Addr:     opts.Addr,
+			Password: opts.Password,
+			DB:       opts.DB,
+		},
+		asynq.Config{
+			// 并发数
+			Concurrency: concurrency,
+			// 队列优先级配置
+			Queues: queues,
+			// 重试延迟函数（指数退避）
+			RetryDelayFunc: asynq.DefaultRetryDelayFunc,
+			// 是否记录详细日志
+			LogLevel: asynq.WarnLevel,
+		},
+	)
+
+	return &Server{
+		server: asynqServer,
+		logger: logger,
+	}
+}
+
+// Start 启动 Worker 服务器
+func (s *Server) Start(mux *asynq.ServeMux) error {
+	s.logger.Info("Worker 服务器启动中...")
+
+	if err := s.server.Start(mux); err != nil {
+		s.logger.Error("Worker 服务器启动失败", zap.Error(err))
+		return err
+	}
+
+	s.logger.Info("Worker 服务器启动成功")
+	return nil
+}
+
+// Shutdown 优雅关闭服务器
+func (s *Server) Shutdown() {
+	s.logger.Info("Worker 服务器关闭中...")
+	s.server.Shutdown()
+	s.logger.Info("Worker 服务器已关闭")
+}
+
+// Run 启动并阻塞运行（用于主函数）
+func (s *Server) Run(mux *asynq.ServeMux) error {
+	s.logger.Info("Worker 服务器启动中...")
+
+	if err := s.server.Run(mux); err != nil {
+		s.logger.Error("Worker 服务器运行失败", zap.Error(err))
+		return err
+	}
+
+	return nil
+}