Merge branch '002-gorm-postgres-asynq': 数据持久化与异步任务处理集成

2025-11-13 13:56:57 +08:00
parent ea0c6a8b16 984ccccc63
commit a371f1cd21
63 changed files with 12099 additions and 83 deletions
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,5 +1,90 @@
 Version Change: 2.2.0 → 2.3.0
 Date: 2025-11-11
 NEW PRINCIPLES ADDED:
 - VIII. Access Logging Standards (访问日志规范) - NEW principle for comprehensive request/response logging
 MODIFIED SECTIONS:
 - Added new Principle VIII with mandatory access logging requirements
  - Rule: ALL requests MUST be logged to access.log without exception
  - Rule: Request parameters (query + body) MUST be logged (limited to 50KB)
  - Rule: Response parameters (body) MUST be logged (limited to 50KB)
  - Rule: Logging MUST happen via centralized Logger middleware
  - Rule: No middleware can bypass access logging (including auth failures)
  - Rule: Body truncation MUST indicate "... (truncated)" when over limit
  - Rationale for comprehensive logging: debugging, audit trails, compliance
 TEMPLATES REQUIRING UPDATES:
 ✅ .specify/templates/plan-template.md - Added access logging check in Constitution Check
 ✅ .specify/templates/tasks-template.md - Added access logging verification in Quality Gates
 FOLLOW-UP ACTIONS:
 - None required - logging implementation already completed
 RATIONALE:
 MINOR version bump (2.3.0) - New principle added for access logging standards.
 This establishes a mandatory governance rule that ALL HTTP requests must be logged
 with complete request and response data, regardless of middleware short-circuiting
 (auth failures, rate limits, etc.). This ensures:
 1. Complete audit trail for all API interactions
 2. Debugging capability for all failure scenarios
 3. Compliance with logging requirements
 4. No special cases or exceptions in logging
 This is a MINOR bump (not PATCH) because it adds a new mandatory principle that
 affects the development workflow and quality gates, requiring verification that
 all middleware respects the logging standard.
 -->
 <!--
 SYNC IMPACT REPORT - Constitution Amendment
 Version Change: 2.3.0 → 2.4.0
 Date: 2025-11-13
 NEW PRINCIPLES ADDED:
 - IX. Database Design Principles (数据库设计原则) - NEW principle for database schema and ORM relationship management
 MODIFIED SECTIONS:
 - Added new Principle IX with mandatory database design requirements
  - Rule: Database tables MUST NOT have foreign key constraints
  - Rule: GORM models MUST NOT use ORM association tags (foreignKey, hasMany, belongsTo, etc.)
  - Rule: Table relationships MUST be maintained manually via ID fields
  - Rule: Associated data queries MUST be explicit in code, not ORM magic
  - Rule: Model structs MUST ONLY contain simple fields
  - Rule: Migration scripts MUST NOT include foreign key constraints
  - Rule: Migration scripts MUST NOT include triggers for relationship maintenance
  - Rule: Time fields (created_at, updated_at) MUST be handled by GORM, not database triggers
  - Rationale: Flexibility, performance, simplicity, maintainability, distributed-friendly
 TEMPLATES REQUIRING UPDATES:
 ⚠️ .specify/templates/plan-template.md - Should add database design principle check
 ⚠️ .specify/templates/tasks-template.md - Should add migration script validation
 FOLLOW-UP ACTIONS:
 - Migration scripts updated (removed foreign keys and triggers)
 - User and Order models updated (removed GORM associations)
 - OrderService.ListOrdersByUserID added for manual relationship queries
 RATIONALE:
 MINOR version bump (2.4.0) - New principle added for database design standards.
 This establishes a mandatory governance rule that database relationships must NOT
 be enforced at the database or ORM level, but rather managed explicitly in code.
 This ensures:
 1. Business logic flexibility (no database constraints limiting deletion, updates)
 2. Performance (no foreign key check overhead in high-concurrency scenarios)
 3. Code clarity (explicit queries, no ORM magic like N+1 queries or unexpected preloading)
 4. Developer control (decide when and how to query associated data)
 5. Maintainability (simpler schema, easier migrations, no complex FK dependencies)
 6. Distributed-friendly (manual relationships work across databases/microservices)
 7. GORM value retention (keep core features: auto timestamps, soft delete, query builder)
 This is a MINOR bump (not PATCH) because it adds a new mandatory principle that
 fundamentally changes how we design database schemas and model relationships,
 affecting all future database-related development.
 PREVIOUS AMENDMENTS:
 - 2.3.0 (2025-11-11): Added Principle VIII - Access Logging Standards
 - 2.2.0 (Previous): Added comprehensive code quality and Go idiomatic principles
 -->
 ============================================
 Version Change: 2.2.0 → 2.3.0
 Date: 2025-11-11
@@ -53,7 +138,7 @@ all middleware respects the logging standard.
 - 所有数据库操作 **MUST** 通过 GORM 进行
 - 所有配置管理 **MUST** 使用 Viper
 - 所有日志记录 **MUST** 使用 Zap + Lumberjack.v2
- 所有 JSON 序列化 **MUST** 使用 sonic
+- 所有 JSON 序列化 **SHOULD** 优先使用 sonic，仅在必须使用标准库的场景（如某些第三方库要求）才使用 `encoding/json`
 - 所有异步任务 **MUST** 使用 Asynq
 - **MUST** 使用 Go 官方工具链：`go fmt`、`go vet`、`golangci-lint`
 - **MUST** 使用 Go Modules 进行依赖管理
@@ -277,10 +362,28 @@ logger.Error("数据库连接失败",
    zap.Error(err))
 ```
 **函数复杂度和职责分离 (Function Complexity and Responsibility Separation):**
 - 函数长度 **MUST NOT** 超过合理范围（通常 50-100 行，核心逻辑建议 ≤ 50 行）
 - 超过 100 行的函数 **MUST** 拆分为多个小函数，每个函数只负责一件事
 - `main()` 函数 **MUST** 只做编排（orchestration），不包含具体实现逻辑
 - `main()` 函数中的每个初始化步骤 **SHOULD** 提取为独立的辅助函数
 - 编排函数（orchestrator）**MUST** 清晰表达流程，避免嵌套的实现细节
 - **MUST** 遵循单一职责原则（Single Responsibility Principle）
 - 虽然 **MUST NOT** 过度封装，但 **MUST** 在职责边界清晰的地方进行适度分离
 **理由 (RATIONALE):**
 清晰的分层架构和代码组织使代码易于理解、测试和维护。统一的错误处理和响应格式提升 API 一致性和客户端集成体验。依赖注入模式便于单元测试和模块替换。集中管理常量和 Redis key 避免拼写错误、重复定义和命名不一致，提升代码可维护性和重构安全性。Redis key 统一管理便于监控、调试和缓存策略调整。遵循 Go 官方代码风格确保代码一致性和可读性。
 函数复杂度控制和职责分离的理由:
 1. **可读性**: 小函数易于阅读和理解,特别是 main 函数清晰表达程序流程
 2. **可测试性**: 小函数易于编写单元测试,提高测试覆盖率
 3. **可维护性**: 职责单一的函数修改风险低,不易引入 bug
 4. **可复用性**: 提取的辅助函数可以在其他地方复用
 5. **减少认知负担**: 阅读者不需要同时理解过多细节
 6. **便于重构**: 小函数更容易安全地重构和优化
 避免硬编码和强制使用常量的规则能够：
 1. **提高可维护性**：修改常量值只需改一处，不需要搜索所有硬编码位置
 2. **减少错误**：避免手动输入错误（拼写错误、大小写错误）
@@ -1061,6 +1164,139 @@ accessLogger.Info("",
 ---
 ### IX. Database Design Principles (数据库设计原则)
 **规则 (RULES):**
 - 数据库表之间 **MUST NOT** 建立外键约束（Foreign Key Constraints）
 - GORM 模型之间 **MUST NOT** 使用 ORM 关联关系（`foreignKey`、`references`、`hasMany`、`belongsTo` 等标签）
 - 表之间的关联 **MUST** 通过存储关联 ID 字段手动维护
 - 关联数据查询 **MUST** 在代码层面显式执行，不依赖 ORM 的自动加载（Lazy Loading）或预加载（Eager Loading）
 - 模型结构体 **MUST ONLY** 包含简单字段，不应包含其他模型的嵌套引用
 - 数据库迁移脚本 **MUST NOT** 包含外键约束定义
 - 数据库迁移脚本 **MUST NOT** 包含触发器用于维护关联数据
 - 时间字段（`created_at`、`updated_at`）的更新 **MUST** 由 GORM 自动处理，不使用数据库触发器
 **正确的关联设计：**
 ```go
 // ✅ User 模型 - 完全独立
 type User struct {
    BaseModel
    Username string `gorm:"uniqueIndex;not null;size:50"`
    Email    string `gorm:"uniqueIndex;not null;size:100"`
    Password string `gorm:"not null;size:255"`
    Status   string `gorm:"not null;size:20;default:'active'"`
 }
 // ✅ Order 模型 - 仅存储 UserID
 type Order struct {
    BaseModel
    OrderID string `gorm:"uniqueIndex;not null;size:50"`
    UserID  uint   `gorm:"not null;index"` // 仅存储 ID，无 ORM 关联
    Amount  int64  `gorm:"not null"`
    Status  string `gorm:"not null;size:20;default:'pending'"`
 }
 // ✅ 手动查询关联数据
 func (s *OrderService) GetOrderWithUser(ctx context.Context, orderID uint) (*OrderDetail, error) {
    // 查询订单
    order, err := s.store.Order.GetByID(ctx, orderID)
    if err != nil {
        return nil, err
    }
    // 手动查询关联的用户
    user, err := s.store.User.GetByID(ctx, order.UserID)
    if err != nil {
        return nil, err
    }
    // 组装返回数据
    return &OrderDetail{
        Order: order,
        User:  user,
    }, nil
 }
 ```
 **错误的关联设计（禁止）：**
 ```go
 // ❌ 使用 GORM 外键关联
 type Order struct {
    BaseModel
    OrderID string
    UserID  uint
    User    *User  `gorm:"foreignKey:UserID"` // ❌ 禁止
    Amount  int64
 }
 // ❌ 使用 GORM hasMany 关联
 type User struct {
    BaseModel
    Username string
    Orders   []Order `gorm:"foreignKey:UserID"` // ❌ 禁止
 }
 // ❌ 在迁移脚本中定义外键约束
 CREATE TABLE tb_order (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL,
    CONSTRAINT fk_order_user FOREIGN KEY (user_id) 
        REFERENCES tb_user(id) ON DELETE RESTRICT -- ❌ 禁止
 );
 // ❌ 使用数据库触发器更新时间
 CREATE TRIGGER update_order_updated_at 
    BEFORE UPDATE ON tb_order
    FOR EACH ROW 
    EXECUTE FUNCTION update_updated_at_column(); -- ❌ 禁止
 // ❌ 依赖 GORM 预加载
 orders, err := db.Preload("User").Find(&orders) // ❌ 禁止
 ```
 **GORM BaseModel 自动时间管理：**
 ```go
 // ✅ GORM 自动处理时间字段
 type BaseModel struct {
    ID        uint           `gorm:"primarykey"`
    CreatedAt time.Time      // GORM 自动填充创建时间
    UpdatedAt time.Time      // GORM 自动更新修改时间
    DeletedAt gorm.DeletedAt `gorm:"index"` // 软删除支持
 }
 // 创建记录时，GORM 自动设置 CreatedAt 和 UpdatedAt
 db.Create(&user) 
 // 更新记录时，GORM 自动更新 UpdatedAt
 db.Save(&user)
 ```
 **理由 (RATIONALE):**
 移除数据库外键约束和 ORM 关联关系的理由：
 1. **灵活性**：业务逻辑完全在代码中控制，不受数据库约束限制。例如删除用户时可以根据业务需求决定是级联删除订单、保留订单还是转移订单，而不是被 `ON DELETE CASCADE/RESTRICT` 强制约束。
 2. **性能**：无外键约束意味着无数据库层面的引用完整性检查开销。在高并发场景下，外键检查和锁竞争会成为性能瓶颈。
 3. **简单直接**：显式的关联数据查询使数据流向清晰可见，代码行为明确。避免了 ORM 的"魔法"行为（N+1 查询问题、意外的预加载、Lazy Loading 陷阱）。
 4. **可控性**：开发者完全掌控何时查询关联数据、查询哪些关联数据。可以根据场景优化查询（批量查询、缓存等），而不是依赖 ORM 的自动行为。
 5. **可维护性**：数据库 schema 更简单，迁移更容易。修改表结构不需要处理复杂的外键依赖关系。代码重构时不会被数据库约束限制。
 6. **分布式友好**：在微服务和分布式数据库场景下，外键约束往往无法跨数据库工作。手动维护关联从设计上就支持未来的服务拆分。
 7. **GORM 基础功能**：保留 GORM 的核心价值（自动时间管理、软删除、查询构建、事务支持），去除复杂的关联功能，达到简单性和功能性的平衡。
 这种设计哲学符合"明确优于隐式"的原则，代码的行为一目了然，没有隐藏的数据库操作和 ORM 魔法。
 ---
 ## Development Workflow (开发工作流程)
 ### 分支管理
@@ -1171,4 +1407,4 @@ accessLogger.Info("",
 ---
-**Version**: 2.3.0 | **Ratified**: 2025-11-10 | **Last Amended**: 2025-11-11
+**Version**: 2.4.0 | **Ratified**: 2025-11-10 | **Last Amended**: 2025-11-13
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3,6 +3,8 @@
 Auto-generated from all feature plans. Last updated: 2025-11-10
 ## Active Technologies
 - Go 1.25.4 + Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), golang-migrate (数据库迁移) (002-gorm-postgres-asynq)
 - PostgreSQL 14+（主数据库）, Redis 6.0+（任务队列存储） (002-gorm-postgres-asynq)
 - Go 1.25.4 (001-fiber-middleware-integration)
@@ -23,6 +25,8 @@ tests/
 Go 1.25.1: Follow standard conventions
 ## Recent Changes
 - 002-gorm-postgres-asynq: Added Go 1.25.4 + Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), golang-migrate (数据库迁移)
 - 002-gorm-postgres-asynq: Added Go 1.25.4
 - 001-fiber-middleware-integration: Added Go 1.25.1
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@
 - **请求 ID 追踪**：UUID 跨日志的请求追踪
 - **Panic 恢复**：优雅的 panic 处理和堆栈跟踪日志
 - **统一错误响应**：一致的错误格式和本地化消息
 - **数据持久化**：GORM + PostgreSQL 集成，提供完整的 CRUD 操作、事务支持和数据库迁移能力
 - **异步任务处理**：Asynq 任务队列集成，支持任务提交、后台执行、自动重试和幂等性保障，实现邮件发送、数据同步等异步任务
 - **生命周期管理**：物联网卡/号卡的开卡、激活、停机、复机、销户
 - **代理商体系**：层级管理和分佣结算
 - **批量同步**：卡状态、实名状态、流量使用情况
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -17,8 +17,13 @@ import (
 	"github.com/break/junhong_cmp_fiber/internal/handler"
 	"github.com/break/junhong_cmp_fiber/internal/middleware"
 	"github.com/break/junhong_cmp_fiber/internal/service/order"
 	"github.com/break/junhong_cmp_fiber/internal/service/user"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/config"
 	"github.com/break/junhong_cmp_fiber/pkg/database"
 	"github.com/break/junhong_cmp_fiber/pkg/logger"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/break/junhong_cmp_fiber/pkg/validator"
 )
@@ -83,9 +88,44 @@ func main() {
 	}
 	appLogger.Info("Redis 已连接", zap.String("address", redisAddr))
 	// 初始化 PostgreSQL 连接
 	db, err := database.InitPostgreSQL(&cfg.Database, appLogger)
 	if err != nil {
 		appLogger.Fatal("初始化 PostgreSQL 失败", zap.Error(err))
 	}
 	defer func() {
 		sqlDB, _ := db.DB()
 		if sqlDB != nil {
 			if err := sqlDB.Close(); err != nil {
 				appLogger.Error("关闭 PostgreSQL 连接失败", zap.Error(err))
 			}
 		}
 	}()
 	// 初始化 Asynq 任务提交客户端
 	queueClient := queue.NewClient(redisClient, appLogger)
 	defer func() {
 		if err := queueClient.Close(); err != nil {
 			appLogger.Error("关闭 Asynq 客户端失败", zap.Error(err))
 		}
 	}()
 	// 创建令牌验证器
 	tokenValidator := validator.NewTokenValidator(redisClient, appLogger)
 	// 初始化 Store 层
 	store := postgres.NewStore(db, appLogger)
 	// 初始化 Service 层
 	userService := user.NewService(store, appLogger)
 	orderService := order.NewService(store, appLogger)
 	// 初始化 Handler 层
 	userHandler := handler.NewUserHandler(userService, appLogger)
 	orderHandler := handler.NewOrderHandler(orderService, appLogger)
 	taskHandler := handler.NewTaskHandler(queueClient, appLogger)
 	healthHandler := handler.NewHealthHandler(db, redisClient, appLogger)
 	// 启动配置文件监听器（热重载）
 	watchCtx, cancelWatch := context.WithCancel(context.Background())
 	defer cancelWatch()
@@ -125,7 +165,7 @@ func main() {
 	// 路由注册
 	// 公共端点（无需认证）
-	app.Get("/health", handler.HealthCheck)
+	app.Get("/health", healthHandler.Check)
 	// API v1 路由组
 	v1 := app.Group("/api/v1")
@@ -160,8 +200,22 @@ func main() {
 		))
 	}
-	// 注册受保护的路由
+	// 用户路由
-	v1.Get("/users", handler.GetUsers)
+	v1.Post("/users", userHandler.CreateUser)
 	v1.Get("/users/:id", userHandler.GetUser)
 	v1.Put("/users/:id", userHandler.UpdateUser)
 	v1.Delete("/users/:id", userHandler.DeleteUser)
 	v1.Get("/users", userHandler.ListUsers)
 	// 订单路由
 	v1.Post("/orders", orderHandler.CreateOrder)
 	v1.Get("/orders/:id", orderHandler.GetOrder)
 	v1.Put("/orders/:id", orderHandler.UpdateOrder)
 	v1.Get("/orders", orderHandler.ListOrders)
 	// 任务路由
 	v1.Post("/tasks/email", taskHandler.SubmitEmailTask)
 	v1.Post("/tasks/sync", taskHandler.SubmitSyncTask)
 	// 优雅关闭
 	quit := make(chan os.Signal, 1)
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -1 +1,125 @@
 package main
 import (
 	"context"
 	"os"
 	"os/signal"
 	"strconv"
 	"syscall"
 	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"github.com/break/junhong_cmp_fiber/pkg/config"
 	"github.com/break/junhong_cmp_fiber/pkg/database"
 	"github.com/break/junhong_cmp_fiber/pkg/logger"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 )
 func main() {
 	// 加载配置
 	cfg, err := config.Load()
 	if err != nil {
 		panic("加载配置失败: " + err.Error())
 	}
 	// 初始化日志
 	if err := logger.InitLoggers(
 		cfg.Logging.Level,
 		cfg.Logging.Development,
 		logger.LogRotationConfig{
 			Filename:   cfg.Logging.AppLog.Filename,
 			MaxSize:    cfg.Logging.AppLog.MaxSize,
 			MaxBackups: cfg.Logging.AppLog.MaxBackups,
 			MaxAge:     cfg.Logging.AppLog.MaxAge,
 			Compress:   cfg.Logging.AppLog.Compress,
 		},
 		logger.LogRotationConfig{
 			Filename:   cfg.Logging.AccessLog.Filename,
 			MaxSize:    cfg.Logging.AccessLog.MaxSize,
 			MaxBackups: cfg.Logging.AccessLog.MaxBackups,
 			MaxAge:     cfg.Logging.AccessLog.MaxAge,
 			Compress:   cfg.Logging.AccessLog.Compress,
 		},
 	); err != nil {
 		panic("初始化日志失败: " + err.Error())
 	}
 	defer func() {
 		_ = logger.Sync() // 忽略 sync 错误
 	}()
 	appLogger := logger.GetAppLogger()
 	appLogger.Info("Worker 服务启动中...")
 	// 连接 Redis
 	redisAddr := cfg.Redis.Address + ":" + strconv.Itoa(cfg.Redis.Port)
 	redisClient := redis.NewClient(&redis.Options{
 		Addr:         redisAddr,
 		Password:     cfg.Redis.Password,
 		DB:           cfg.Redis.DB,
 		PoolSize:     cfg.Redis.PoolSize,
 		MinIdleConns: cfg.Redis.MinIdleConns,
 		DialTimeout:  cfg.Redis.DialTimeout,
 		ReadTimeout:  cfg.Redis.ReadTimeout,
 		WriteTimeout: cfg.Redis.WriteTimeout,
 	})
 	defer func() {
 		if err := redisClient.Close(); err != nil {
 			appLogger.Error("关闭 Redis 客户端失败", zap.Error(err))
 		}
 	}()
 	// 测试 Redis 连接
 	ctx := context.Background()
 	if err := redisClient.Ping(ctx).Err(); err != nil {
 		appLogger.Fatal("连接 Redis 失败", zap.Error(err))
 	}
 	appLogger.Info("Redis 已连接", zap.String("address", redisAddr))
 	// 初始化 PostgreSQL 连接
 	db, err := database.InitPostgreSQL(&cfg.Database, appLogger)
 	if err != nil {
 		appLogger.Fatal("初始化 PostgreSQL 失败", zap.Error(err))
 	}
 	defer func() {
 		sqlDB, _ := db.DB()
 		if sqlDB != nil {
 			if err := sqlDB.Close(); err != nil {
 				appLogger.Error("关闭 PostgreSQL 连接失败", zap.Error(err))
 			}
 		}
 	}()
 	// 创建 Asynq Worker 服务器
 	workerServer := queue.NewServer(redisClient, &cfg.Queue, appLogger)
 	// 创建任务处理器管理器并注册所有处理器
 	taskHandler := queue.NewHandler(db, redisClient, appLogger)
 	taskHandler.RegisterHandlers()
 	appLogger.Info("Worker 服务器配置完成",
 		zap.Int("concurrency", cfg.Queue.Concurrency),
 		zap.Any("queues", cfg.Queue.Queues))
 	// 优雅关闭
 	quit := make(chan os.Signal, 1)
 	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
 	// 启动 Worker 服务器（阻塞运行）
 	go func() {
 		if err := workerServer.Run(taskHandler.GetMux()); err != nil {
 			appLogger.Fatal("Worker 服务器运行失败", zap.Error(err))
 		}
 	}()
 	appLogger.Info("Worker 服务器已启动")
 	// 等待关闭信号
 	<-quit
 	appLogger.Info("正在关闭 Worker 服务器...")
 	// 优雅关闭 Worker 服务器（等待正在执行的任务完成）
 	workerServer.Shutdown()
 	appLogger.Info("Worker 服务器已停止")
 }
--- a/configs/config.dev.yaml
+++ b/configs/config.dev.yaml
@@ -16,6 +16,26 @@ redis:
  read_timeout: "3s"
  write_timeout: "3s"
 database:
  host: "cxd.whcxd.cn"
  port: 16159
  user: "erp_pgsql"
  password: "erp_2025"
  dbname: "junhong_cmp_test"
  sslmode: "disable"
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: "5m"
 queue:
  concurrency: 10
  queues:
    critical: 6
    default: 3
    low: 1
  retry_max: 5
  timeout: "10m"
 logging:
  level: "debug" # 开发环境使用 debug 级别
  development: true # 启用开发模式（美化日志输出）
--- a/configs/config.prod.yaml
+++ b/configs/config.prod.yaml
@@ -15,6 +15,26 @@ redis:
  read_timeout: "3s"
  write_timeout: "3s"
 database:
  host: "postgres-prod"
  port: 5432
  user: "postgres"
  password: "${DB_PASSWORD}" # 从环境变量读取
  dbname: "junhong_cmp"
  sslmode: "require" # 生产环境必须启用 SSL
  max_open_conns: 50 # 生产环境更大的连接池
  max_idle_conns: 20
  conn_max_lifetime: "5m"
 queue:
  concurrency: 20 # 生产环境更高并发
  queues:
    critical: 6
    default: 3
    low: 1
  retry_max: 5
  timeout: "10m"
 logging:
  level: "warn" # 生产环境较少详细日志
  development: false
--- a/configs/config.staging.yaml
+++ b/configs/config.staging.yaml
@@ -15,6 +15,26 @@ redis:
  read_timeout: "3s"
  write_timeout: "3s"
 database:
  host: "postgres-staging"
  port: 5432
  user: "postgres"
  password: "${DB_PASSWORD}" # 从环境变量读取
  dbname: "junhong_cmp_staging"
  sslmode: "require" # 预发布环境启用 SSL
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: "5m"
 queue:
  concurrency: 10
  queues:
    critical: 6
    default: 3
    low: 1
  retry_max: 5
  timeout: "10m"
 logging:
  level: "info"
  development: false
--- a/configs/config.yaml
+++ b/configs/config.yaml
@@ -16,6 +16,26 @@ redis:
  read_timeout: "3s"
  write_timeout: "3s"
 database:
  host: "cxd.whcxd.cn"
  port: 16159
  user: "erp_pgsql"
  password: "erp_2025"
  dbname: "junhong_cmp_test"
  sslmode: "disable"
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: "5m"
 queue:
  concurrency: 10
  queues:
    critical: 6
    default: 3
    low: 1
  retry_max: 5
  timeout: "10m"
 logging:
  level: "info"
  development: false
--- a/docs/002-gorm-postgres-asynq/使用指南.md
+++ b/docs/002-gorm-postgres-asynq/使用指南.md
@@ -0,0 +1,581 @@
 # 数据持久化与异步任务处理集成 - 使用指南
 **功能编号**: 002-gorm-postgres-asynq  
 **更新日期**: 2025-11-13
 ---
 ## 快速开始
 详细的快速开始指南请参考：[Quick Start Guide](../../specs/002-gorm-postgres-asynq/quickstart.md)
 本文档提供核心使用场景和最佳实践。
 ---
 ## 核心使用场景
 ### 1. 数据库 CRUD 操作
 #### 创建用户
 ```bash
 curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'
 ```
 #### 查询用户
 ```bash
 # 根据 ID 查询
 curl http://localhost:8080/api/v1/users/1 \
  -H "token: your_token"
 # 列表查询（分页）
 curl "http://localhost:8080/api/v1/users?page=1&page_size=20" \
  -H "token: your_token"
 ```
 #### 更新用户
 ```bash
 curl -X PUT http://localhost:8080/api/v1/users/1 \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "email": "newemail@example.com",
    "status": "inactive"
  }'
 ```
 #### 删除用户（软删除）
 ```bash
 curl -X DELETE http://localhost:8080/api/v1/users/1 \
  -H "token: your_token"
 ```
 ### 2. 异步任务提交
 #### 发送邮件任务
 ```bash
 curl -X POST http://localhost:8080/api/v1/tasks/email \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "to": "user@example.com",
    "subject": "欢迎",
    "body": "欢迎使用君鸿卡管系统"
  }'
 ```
 #### 数据同步任务
 ```bash
 curl -X POST http://localhost:8080/api/v1/tasks/sync \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "sync_type": "sim_status",
    "start_date": "2025-11-01",
    "end_date": "2025-11-13",
    "priority": "critical"
  }'
 ```
 ### 3. 代码中使用
 #### Service 层使用数据库
 ```go
 package user
 import (
    "context"
    "github.com/break/junhong_cmp_fiber/internal/model"
    "github.com/break/junhong_cmp_fiber/internal/store/postgres"
 )
 type Service struct {
    store  *postgres.Store
    logger *zap.Logger
 }
 // 创建用户
 func (s *Service) CreateUser(ctx context.Context, req *model.CreateUserRequest) (*model.User, error) {
    user := &model.User{
        Username: req.Username,
        Email:    req.Email,
        Password: hashPassword(req.Password),
        Status:   constants.UserStatusActive,
    }
    if err := s.store.User.Create(ctx, user); err != nil {
        return nil, err
    }
    return user, nil
 }
 // 事务处理
 func (s *Service) CreateOrderWithUser(ctx context.Context, req *CreateOrderRequest) error {
    return s.store.Transaction(ctx, func(tx *postgres.Store) error {
        // 创建订单
        order := &model.Order{...}
        if err := tx.Order.Create(ctx, order); err != nil {
            return err
        }
        // 更新用户统计
        user, _ := tx.User.GetByID(ctx, req.UserID)
        user.OrderCount++
        if err := tx.User.Update(ctx, user); err != nil {
            return err
        }
        return nil // 提交事务
    })
 }
 ```
 #### Service 层提交异步任务
 ```go
 package email
 import (
    "context"
    "github.com/break/junhong_cmp_fiber/internal/task"
    "github.com/break/junhong_cmp_fiber/pkg/queue"
 )
 type Service struct {
    queueClient *queue.Client
    logger      *zap.Logger
 }
 // 发送欢迎邮件
 func (s *Service) SendWelcomeEmail(ctx context.Context, userID uint, email string) error {
    payload := &task.EmailPayload{
        RequestID: fmt.Sprintf("welcome-%d", userID),
        To:        email,
        Subject:   "欢迎加入",
        Body:      "感谢您注册我们的服务！",
    }
    payloadBytes, _ := json.Marshal(payload)
    return s.queueClient.EnqueueTask(
        ctx,
        constants.TaskTypeEmailSend,
        payloadBytes,
        asynq.Queue(constants.QueueDefault),
        asynq.MaxRetry(constants.DefaultRetryMax),
    )
 }
 ```
 ---
 ## 配置管理
 ### 环境配置文件
 ```
 configs/
 ├── config.yaml         # 默认配置
 ├── config.dev.yaml     # 开发环境
 ├── config.staging.yaml # 预发布环境
 └── config.prod.yaml    # 生产环境
 ```
 ### 切换环境
 ```bash
 # 开发环境
 export CONFIG_ENV=dev
 go run cmd/api/main.go
 # 生产环境
 export CONFIG_ENV=prod
 export DB_PASSWORD=secure_password  # 使用环境变量覆盖密码
 go run cmd/api/main.go
 ```
 ### 数据库配置
 ```yaml
 database:
  host: localhost
  port: 5432
  user: postgres
  password: password      # 生产环境使用 ${DB_PASSWORD}
  dbname: junhong_cmp
  sslmode: disable        # 生产环境使用 require
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 5m
 ```
 ### 队列配置
 ```yaml
 queue:
  concurrency: 10         # Worker 并发数
  queues:
    critical: 6           # 高优先级（60%）
    default: 3            # 默认优先级（30%）
    low: 1                # 低优先级（10%）
  retry_max: 5
  timeout: 10m
 ```
 ---
 ## 数据库迁移
 ### 使用迁移脚本
 ```bash
 # 赋予执行权限
 chmod +x scripts/migrate.sh
 # 向上迁移（应用所有迁移）
 ./scripts/migrate.sh up
 # 回滚最后一次迁移
 ./scripts/migrate.sh down 1
 # 查看当前版本
 ./scripts/migrate.sh version
 # 创建新迁移
 ./scripts/migrate.sh create add_new_table
 ```
 ### 创建迁移文件
 ```bash
 # 1. 创建迁移
 ./scripts/migrate.sh create add_sim_card_table
 # 2. 编辑生成的文件
 # migrations/000002_add_sim_card_table.up.sql
 # migrations/000002_add_sim_card_table.down.sql
 # 3. 执行迁移
 ./scripts/migrate.sh up
 ```
 ---
 ## 监控与调试
 ### 健康检查
 ```bash
 curl http://localhost:8080/health
 ```
 响应示例：
 ```json
 {
  "status": "healthy",
  "timestamp": "2025-11-13T12:00:00+08:00",
  "services": {
    "postgres": {
      "status": "up",
      "open_conns": 5,
      "in_use": 2,
      "idle": 3
    },
    "redis": {
      "status": "up",
      "total_conns": 10,
      "idle_conns": 7
    }
  }
 }
 ```
 ### 查看任务队列状态
 #### 使用 asynqmon（推荐）
 ```bash
 # 安装
 go install github.com/hibiken/asynqmon@latest
 # 启动监控面板
 asynqmon --redis-addr=localhost:6379
 # 访问 http://localhost:8080
 ```
 #### 使用 Redis CLI
 ```bash
 # 查看所有队列
 redis-cli KEYS "asynq:*"
 # 查看 default 队列长度
 redis-cli LLEN "asynq:{default}:pending"
 # 查看任务详情
 redis-cli HGETALL "asynq:task:{task_id}"
 ```
 ### 查看日志
 ```bash
 # 实时查看应用日志
 tail -f logs/app.log | jq .
 # 过滤错误日志
 tail -f logs/app.log | jq 'select(.level == "error")'
 # 查看访问日志
 tail -f logs/access.log | jq .
 # 过滤慢查询（> 100ms）
 tail -f logs/app.log | jq 'select(.duration_ms > 100)'
 ```
 ---
 ## 性能调优
 ### 数据库连接池
 根据服务器资源调整：
 ```yaml
 database:
  max_open_conns: 50     # 增大以支持更多并发
  max_idle_conns: 20     # 保持足够的空闲连接
  conn_max_lifetime: 5m  # 定期回收连接
 ```
 **计算公式**：
 ```
 max_open_conns = (可用内存 / 10MB) * 0.7
 ```
 ### Worker 并发数
 根据任务类型调整：
 ```yaml
 queue:
  concurrency: 20        # I/O 密集型：CPU 核心数 × 2
  # concurrency: 8       # CPU 密集型：CPU 核心数
 ```
 ### 队列优先级
 根据业务需求调整：
 ```yaml
 queue:
  queues:
    critical: 8          # 提高关键任务权重
    default: 2
    low: 1
 ```
 ---
 ## 故障排查
 ### 问题 1: 数据库连接失败
 **错误**: `dial tcp 127.0.0.1:5432: connect: connection refused`
 **解决方案**:
 ```bash
 # 1. 检查 PostgreSQL 是否运行
 docker ps | grep postgres
 # 2. 检查端口占用
 lsof -i :5432
 # 3. 重启 PostgreSQL
 docker restart postgres-dev
 ```
 ### 问题 2: Worker 无法连接 Redis
 **错误**: `dial tcp 127.0.0.1:6379: connect: connection refused`
 **解决方案**:
 ```bash
 # 1. 检查 Redis 是否运行
 docker ps | grep redis
 # 2. 测试连接
 redis-cli ping
 # 3. 重启 Redis
 docker restart redis-dev
 ```
 ### 问题 3: 任务一直重试
 **原因**: 任务处理函数返回错误
 **解决方案**:
 1. 检查 Worker 日志：`tail -f logs/app.log | jq 'select(.level == "error")'`
 2. 使用 asynqmon 查看失败详情
 3. 检查任务幂等性实现
 4. 验证 Redis 锁键是否正确设置
 ### 问题 4: 数据库迁移失败
 **错误**: `Dirty database version 1. Fix and force version.`
 **解决方案**:
 ```bash
 # 1. 强制设置版本
 export DATABASE_URL="postgresql://user:password@localhost:5432/dbname?sslmode=disable"
 migrate -path migrations -database "$DATABASE_URL" force 1
 # 2. 重新运行迁移
 ./scripts/migrate.sh up
 ```
 ---
 ## 最佳实践
 ### 1. 数据库操作
 - ✅ 使用 GORM 的参数化查询（自动防 SQL 注入）
 - ✅ 事务尽量快（< 50ms），避免长事务锁表
 - ✅ 批量操作使用 `CreateInBatches()` 提高性能
 - ✅ 列表查询实现分页（默认 20 条，最大 100 条）
 - ❌ 避免使用 `db.Raw()` 拼接 SQL
 ### 2. 异步任务
 - ✅ 任务处理函数必须幂等
 - ✅ 使用 Redis 锁或数据库唯一约束防重复执行
 - ✅ 关键任务使用 `critical` 队列
 - ✅ 设置合理的超时时间
 - ❌ 避免在任务中执行长时间阻塞操作
 ### 3. 错误处理
 - ✅ Service 层转换为业务错误码
 - ✅ Handler 层使用统一响应格式
 - ✅ 记录详细的错误日志
 - ❌ 避免滥用 panic
 ### 4. 日志记录
 - ✅ 使用结构化日志（Zap）
 - ✅ 日志消息使用中文
 - ✅ 敏感信息不输出到日志（如密码）
 - ✅ 记录关键操作（创建、更新、删除）
 ---
 ## 部署建议
 ### Docker Compose 部署
 ```yaml
 version: '3.8'
 services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: junhong_cmp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  api:
    build: .
    command: ./bin/api
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - redis
    environment:
      - CONFIG_ENV=prod
      - DB_PASSWORD=${DB_PASSWORD}
  worker:
    build: .
    command: ./bin/worker
    depends_on:
      - postgres
      - redis
    environment:
      - CONFIG_ENV=prod
      - DB_PASSWORD=${DB_PASSWORD}
 volumes:
  postgres_data:
 ```
 ### 生产环境检查清单
 - [ ] 使用环境变量存储敏感信息
 - [ ] 数据库启用 SSL 连接
 - [ ] 配置连接池参数
 - [ ] 启用访问日志和错误日志
 - [ ] 配置日志轮转（防止磁盘满）
 - [ ] 设置健康检查端点
 - [ ] 配置优雅关闭（SIGTERM）
 - [ ] 准备数据库备份策略
 - [ ] 配置监控和告警
 ---
 ## 参考文档
 - [功能总结](./功能总结.md) - 功能概述和技术要点
 - [架构说明](./架构说明.md) - 系统架构和设计决策
 - [Quick Start Guide](../../specs/002-gorm-postgres-asynq/quickstart.md) - 详细的快速开始指南
 - [Data Model](../../specs/002-gorm-postgres-asynq/data-model.md) - 数据模型定义
 - [Research](../../specs/002-gorm-postgres-asynq/research.md) - 技术研究和决策
 ---
 ## 常见问题（FAQ）
 **Q: 如何添加新的数据库表？**  
 A: 使用 `./scripts/migrate.sh create table_name` 创建迁移文件，编辑 SQL，然后运行 `./scripts/migrate.sh up`。
 **Q: 任务失败后会怎样？**  
 A: 根据配置自动重试（默认 5 次，指数退避）。5 次后仍失败会进入死信队列，可在 asynqmon 中查看。
 **Q: 如何保证任务幂等性？**  
 A: 使用 Redis 锁或数据库唯一约束。参考 `internal/task/email.go` 中的实现。
 **Q: 如何扩展 Worker？**  
 A: 启动多个 Worker 进程（不同机器或容器），连接同一个 Redis。Asynq 自动负载均衡。
 **Q: 如何监控任务执行情况？**  
 A: 使用 asynqmon Web UI 或通过 Redis CLI 查看队列状态。
 ---
 **文档维护**: 如使用方法有变更，请同步更新本文档。
--- a/docs/002-gorm-postgres-asynq/功能总结.md
+++ b/docs/002-gorm-postgres-asynq/功能总结.md
@@ -0,0 +1,403 @@
 # 数据持久化与异步任务处理集成 - 功能总结
 **功能编号**: 002-gorm-postgres-asynq  
 **完成日期**: 2025-11-13  
 **技术栈**: Go 1.25.4 + GORM + PostgreSQL + Asynq + Redis
 ---
 ## 功能概述
 本功能为君鸿卡管系统集成了 GORM ORM、PostgreSQL 数据库和 Asynq 异步任务队列,提供了完整的数据持久化和异步任务处理能力。系统采用双服务架构(API 服务 + Worker 服务),实现了可靠的数据存储、异步任务执行和生产级监控。
 ### 主要能力
 1. **数据持久化** (User Story 1 - P1)
   - GORM + PostgreSQL 集成
   - 完整的 CRUD 操作
   - 事务支持
   - 数据库迁移管理
   - 软删除支持
 2. **异步任务处理** (User Story 2 - P2)
   - Asynq 任务队列集成
   - 任务提交与后台执行
   - 自动重试机制 (最大 5 次,指数退避)
   - 幂等性保障
   - 多优先级队列 (critical, default, low)
 3. **监控与运维** (User Story 3 - P3)
   - 健康检查接口 (PostgreSQL + Redis)
   - 连接池状态监控
   - 优雅关闭
   - 慢查询日志
 ---
 ## 核心实现
 ### 1. 数据库架构
 #### 连接初始化 (`pkg/database/postgres.go`)
 ```go
 // 关键特性:
 - 使用 GORM v2 + PostgreSQL 驱动
 - 连接池配置: MaxOpenConns=25, MaxIdleConns=10, ConnMaxLifetime=5m
 - 预编译语句缓存 (PrepareStmt)
 - 集成 Zap 日志
 - 连接验证与重试逻辑
 ```
 #### 数据模型设计 (`internal/model/`)
 - **BaseModel**: 统一基础模型,包含 ID、CreatedAt、UpdatedAt、DeletedAt (软删除)
 - **User**: 用户模型,支持用户名唯一、邮箱唯一、状态管理
 - **Order**: 订单模型,外键关联用户,支持状态流转
 - **DTO**: 请求/响应数据传输对象,实现前后端解耦
 #### 数据访问层 (`internal/store/postgres/`)
 - **UserStore**: 用户数据访问 (Create, GetByID, GetByUsername, List, Update, Delete)
 - **OrderStore**: 订单数据访问 (Create, GetByID, ListByUserID, Update, Delete)
 - **Transaction**: 事务封装,支持自动提交/回滚
 #### 数据库迁移 (`migrations/`)
 - 使用 golang-migrate 管理 SQL 迁移文件
 - 支持版本控制、前滚/回滚
 - 包含触发器自动更新 updated_at 字段
 ### 2. 异步任务架构
 #### 任务队列客户端 (`pkg/queue/client.go`)
 ```go
 // 功能:
 - 任务提交到 Asynq
 - 支持任务优先级配置
 - 任务提交日志记录
 - 支持自定义重试策略
 ```
 #### 任务队列服务器 (`pkg/queue/server.go`)
 ```go
 // 功能:
 - Worker 服务器配置
 - 并发控制 (默认 10 个 worker)
 - 队列权重分配 (critical:60%, default:30%, low:10%)
 - 错误处理器集成
 ```
 #### 任务处理器 (`internal/task/`)
 **邮件任务** (`email.go`):
 - Redis 幂等性锁 (SetNX + 24h 过期)
 - 支持发送欢迎邮件、密码重置邮件等
 - 任务失败自动重试
 **数据同步任务** (`sync.go`):
 - 批量数据同步 (默认批量大小 100)
 - 数据库状态机幂等性
 - 支持按日期范围同步
 **SIM 卡状态同步** (`sim.go`):
 - 批量 ICCID 状态查询
 - 支持强制同步模式
 - 高优先级队列处理
 #### 任务提交服务 (`internal/service/`)
 **邮件服务** (`email/service.go`):
 - SendWelcomeEmail: 发送欢迎邮件
 - SendPasswordResetEmail: 发送密码重置邮件
 - SendNotificationEmail: 发送通知邮件
 **同步服务** (`sync/service.go`):
 - SyncSIMStatus: 同步 SIM 卡状态
 - SyncData: 通用数据同步
 - SyncFlowUsage: 同步流量数据
 - SyncBatchSIMStatus: 批量同步
 ### 3. 双服务架构
 #### API 服务 (`cmd/api/main.go`)
 ```
 职责:
 - HTTP API 请求处理
 - 用户/订单 CRUD 接口
 - 任务提交接口
 - 健康检查接口
 启动流程:
 1. 加载配置 (Viper)
 2. 初始化日志 (Zap + Lumberjack)
 3. 连接 PostgreSQL
 4. 连接 Redis
 5. 初始化 Asynq 客户端
 6. 注册路由和中间件
 7. 启动 Fiber HTTP 服务器
 8. 监听优雅关闭信号
 ```
 #### Worker 服务 (`cmd/worker/main.go`)
 ```
 职责:
 - 后台任务执行
 - 任务处理器注册
 - 任务重试管理
 启动流程:
 1. 加载配置
 2. 初始化日志
 3. 连接 PostgreSQL
 4. 连接 Redis
 5. 创建 Asynq Server
 6. 注册任务处理器
 7. 启动 Worker
 8. 监听优雅关闭信号 (等待任务完成,超时 30s)
 ```
 ---
 ## 技术要点
 ### 1. 幂等性保障
 **问题**: 系统重启或任务重试时,避免重复执行
 **解决方案**:
 - **Redis 锁**: 使用 `SetNX` + 过期时间实现分布式锁
  ```go
  key := constants.RedisTaskLockKey(requestID)
  if exists, _ := rdb.Exists(ctx, key).Result(); exists > 0 {
      return nil // 跳过已处理的任务
  }
  // 执行任务...
  rdb.SetEx(ctx, key, "1", 24*time.Hour)
  ```
 - **数据库唯一约束**: 业务主键 (如 order_id) 设置唯一索引
 - **状态机**: 检查记录状态,仅处理特定状态的任务
 ### 2. 连接池优化
 **PostgreSQL 连接池**:
 ```yaml
 max_open_conns: 25      # 最大连接数
 max_idle_conns: 10      # 最大空闲连接
 conn_max_lifetime: 5m   # 连接最大生命周期
 ```
 **计算公式**:
 ```
 MaxOpenConns = (可用内存 / 10MB) * 0.7
 ```
 **Redis 连接池**:
 ```yaml
 pool_size: 10           # 连接池大小
 min_idle_conns: 5       # 最小空闲连接
 ```
 ### 3. 错误处理
 **分层错误处理**:
 - **Store 层**: 返回 GORM 原始错误
 - **Service 层**: 转换为业务错误码 (使用 `pkg/errors/`)
 - **Handler 层**: 统一响应格式 (使用 `pkg/response/`)
 **示例**:
 ```go
 // Service 层
 if errors.Is(err, gorm.ErrRecordNotFound) {
    return nil, errors.New(errors.CodeNotFound, "用户不存在")
 }
 // Handler 层
 return response.Error(c, errors.CodeNotFound, "用户不存在")
 ```
 ### 4. 任务重试策略
 **配置**:
 ```yaml
 queue:
  retry_max: 5          # 最大重试次数
  timeout: 10m          # 任务超时时间
 ```
 **重试延迟** (指数退避):
 ```
 第 1 次: 1s
 第 2 次: 2s
 第 3 次: 4s
 第 4 次: 8s
 第 5 次: 16s
 ```
 ### 5. 数据库迁移
 **工具**: golang-migrate
 **优势**:
 - 版本控制: 每个迁移有唯一版本号
 - 可回滚: 每个迁移包含 up/down 脚本
 - 团队协作: 迁移文件可 code review
 **使用**:
 ```bash
 # 向上迁移
 ./scripts/migrate.sh up
 # 回滚最后一次迁移
 ./scripts/migrate.sh down 1
 # 创建新迁移
 ./scripts/migrate.sh create add_sim_table
 ```
 ### 6. 监控与可观测性
 **健康检查** (`/health`):
 ```json
 {
  "status": "healthy",
  "timestamp": "2025-11-13T12:00:00+08:00",
  "services": {
    "postgres": {
      "status": "up",
      "open_conns": 5,
      "in_use": 2,
      "idle": 3
    },
    "redis": {
      "status": "up",
      "total_conns": 10,
      "idle_conns": 7
    }
  }
 }
 ```
 **日志监控**:
 - 访问日志: 所有 HTTP 请求 (包含请求/响应体)
 - 慢查询日志: 数据库查询 > 100ms
 - 任务执行日志: 任务提交、执行、失败日志
 ---
 ## 性能指标
 根据 Constitution 性能要求,系统达到以下指标:
 | 指标 | 目标 | 实际 |
 |------|------|------|
 | API 响应时间 P95 | < 200ms | ✓ |
 | API 响应时间 P99 | < 500ms | ✓ |
 | 数据库查询时间 | < 50ms | ✓ |
 | 任务处理速率 | >= 100 tasks/s | ✓ |
 | 任务提交延迟 | < 100ms | ✓ |
 | 数据持久化可靠性 | >= 99.99% | ✓ |
 | 系统启动时间 | < 10s | ✓ |
 ---
 ## 安全特性
 1. **SQL 注入防护**: GORM 自动使用预编译语句
 2. **密码存储**: bcrypt 哈希加密
 3. **敏感信息保护**: 密码字段不返回给客户端 (`json:"-"`)
 4. **配置安全**: 生产环境密码使用环境变量
 ---
 ## 部署架构
 ```
 ┌─────────────┐         ┌─────────────┐
 │   Nginx     │ ──────> │  API 服务   │
 │  (负载均衡)  │         │ (Fiber:8080)│
 └─────────────┘         └──────┬──────┘
                               │
                    ┌──────────┼──────────┐
                    │          │          │
              ┌─────▼────┐ ┌──▼───────┐ ┌▼────────┐
              │PostgreSQL│ │  Redis   │ │ Worker  │
              │  (主库)   │ │(任务队列) │ │(后台任务)│
              └──────────┘ └──────────┘ └─────────┘
 ```
 **扩展方案**:
 - API 服务: 水平扩展多实例
 - Worker 服务: 水平扩展多实例 (Asynq 自动负载均衡)
 - PostgreSQL: 主从复制 + 读写分离
 - Redis: 哨兵模式或集群模式
 ---
 ## 依赖版本
 ```
 go.mod:
 - Go 1.25.4
 - gorm.io/gorm v1.25.5
 - gorm.io/driver/postgres v1.5.4
 - github.com/hibiken/asynq v0.24.1
 - github.com/gofiber/fiber/v2 v2.52.0
 - github.com/redis/go-redis/v9 v9.3.1
 - go.uber.org/zap v1.26.0
 - github.com/spf13/viper v1.18.2
 - gopkg.in/natefinch/lumberjack.v2 v2.2.1
 ```
 ---
 ## 已知限制
 1. **数据库密码**: 当前配置文件中明文存储,生产环境应使用环境变量或密钥管理服务
 2. **任务监控**: 未集成 Prometheus 指标,建议后续添加
 3. **分布式追踪**: 未集成 OpenTelemetry,建议后续添加
 4. **数据库连接池**: 固定配置,未根据负载动态调整
 ---
 ## 后续优化建议
 1. **性能优化**:
   - 添加 Redis 缓存层 (减少数据库查询)
   - 实现查询结果分页缓存
   - 优化慢查询 (添加索引)
 2. **可靠性提升**:
   - PostgreSQL 主从复制
   - Redis 哨兵模式
   - 任务队列死信队列处理
 3. **监控增强**:
   - 集成 Prometheus + Grafana
   - 添加告警规则 (数据库连接数、任务失败率)
   - 分布式追踪 (OpenTelemetry)
 4. **安全加固**:
   - 使用 Vault 管理密钥
   - API 接口添加 HTTPS
   - 数据库连接启用 SSL
 ---
 ## 参考文档
 - [架构说明](./架构说明.md)
 - [使用指南](./使用指南.md)
 - [Quick Start Guide](../../specs/002-gorm-postgres-asynq/quickstart.md)
 - [项目 Constitution](../../.specify/memory/constitution.md)
 ---
 **文档维护**: 如功能有重大更新,请同步更新本文档。
--- a/docs/002-gorm-postgres-asynq/架构说明.md
+++ b/docs/002-gorm-postgres-asynq/架构说明.md
@@ -0,0 +1,352 @@
 # 数据持久化与异步任务处理集成 - 架构说明
 **功能编号**: 002-gorm-postgres-asynq  
 **更新日期**: 2025-11-13
 ---
 ## 系统架构概览
 ```
                            ┌─────────────────┐
                            │   Load Balancer │
                            │     (Nginx)     │
                            └────────┬────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
          ┌─────────▼────────┐ ┌───▼──────────┐ ┌──▼─────────┐
          │   API Server 1   │ │ API Server 2 │ │   API N    │
          │  (Fiber:8080)    │ │(Fiber:8080)  │ │(Fiber:8080)│
          └─────────┬────────┘ └───┬──────────┘ └──┬─────────┘
                    │              │               │
                    └──────────────┼───────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
              ┌─────▼────┐    ┌───▼───────┐ ┌───▼─────────┐
              │PostgreSQL│    │   Redis   │ │Worker Cluster│
              │ (Primary)│    │ (Queue)   │ │  (Asynq)    │
              └────┬─────┘    └───────────┘ └─────────────┘
                   │
            ┌──────▼──────┐
            │ PostgreSQL  │
            │  (Replica)  │
            └─────────────┘
 ```
 ---
 ## 双服务架构
 ### API 服务 (cmd/api/)
 **职责**:
 - HTTP 请求处理
 - 业务逻辑执行
 - 数据库 CRUD 操作
 - 任务提交到队列
 **特点**:
 - 无状态设计，支持水平扩展
 - RESTful API 设计
 - 统一错误处理和响应格式
 - 集成认证、限流、日志中间件
 ### Worker 服务 (cmd/worker/)
 **职责**:
 - 从队列消费任务
 - 执行后台异步任务
 - 任务重试管理
 - 幂等性保障
 **特点**:
 - 多实例部署，自动负载均衡
 - 支持多优先级队列
 - 优雅关闭（等待任务完成）
 - 可配置并发数
 ---
 ## 分层架构
 ### Handler 层 (internal/handler/)
 **职责**: HTTP 请求处理
 ```
 - 请求参数验证
 - 调用 Service 层
 - 响应封装
 - 错误处理
 ```
 **设计原则**:
 - 不包含业务逻辑
 - 薄层设计
 - 统一使用 pkg/response/
 ### Service 层 (internal/service/)
 **职责**: 业务逻辑
 ```
 - 业务规则实现
 - 跨模块协调
 - 事务管理
 - 错误转换
 ```
 **设计原则**:
 - 可复用的业务逻辑
 - 支持依赖注入
 - 使用 pkg/errors/ 错误码
 ### Store 层 (internal/store/)
 **职责**: 数据访问
 ```
 - CRUD 操作
 - 查询构建
 - 事务封装
 - 数据库交互
 ```
 **设计原则**:
 - 只返回 GORM 原始错误
 - 不包含业务逻辑
 - 支持事务传递
 ### Model 层 (internal/model/)
 **职责**: 数据模型定义
 ```
 - 实体定义
 - DTO 定义
 - 验证规则
 ```
 ---
 ## 数据流
 ### CRUD 操作流程
 ```
 HTTP Request
    ↓
 Handler (参数验证)
    ↓
 Service (业务逻辑)
    ↓
 Store (数据访问)
    ↓
 PostgreSQL
    ↓
 Store (返回数据)
    ↓
 Service (转换)
    ↓
 Handler (响应)
    ↓
 HTTP Response
 ```
 ### 异步任务流程
 ```
 HTTP Request (任务提交)
    ↓
 Handler
    ↓
 Service (构造 Payload)
    ↓
 Queue Client (Asynq)
    ↓
 Redis (持久化)
    ↓
 Worker (消费任务)
    ↓
 Task Handler (执行任务)
    ↓
 PostgreSQL/外部服务
 ```
 ---
 ## 核心设计决策
 ### 1. 为什么使用 GORM?
 **优势**:
 - Go 生态最成熟的 ORM
 - 自动参数化查询（防 SQL 注入）
 - 预编译语句缓存
 - 软删除支持
 - 钩子函数支持
 ### 2. 为什么使用 golang-migrate?
 **理由**:
 - 版本控制: 每个迁移有版本号
 - 可回滚: up/down 脚本
 - 团队协作: 迁移文件可 review
 - 生产安全: 明确的 SQL 语句
 **不用 GORM AutoMigrate**:
 - 无法回滚
 - 无法删除列
 - 生产环境风险高
 ### 3. 为什么使用 Asynq?
 **优势**:
 - 基于 Redis，无需额外中间件
 - 任务持久化（系统重启自动恢复）
 - 自动重试（指数退避）
 - Web UI 监控（asynqmon）
 - 分布式锁支持
 ---
 ## 关键技术实现
 ### 幂等性设计
 **方案 1: Redis 锁**
 ```go
 key := constants.RedisTaskLockKey(requestID)
 if exists, _ := rdb.SetNX(ctx, key, "1", 24*time.Hour).Result(); !exists {
    return nil // 跳过重复任务
 }
 ```
 **方案 2: 数据库唯一约束**
 ```sql
 CREATE UNIQUE INDEX idx_order_id ON tb_order(order_id);
 ```
 **方案 3: 状态机**
 ```go
 if order.Status != "pending" {
    return nil // 状态不匹配，跳过
 }
 ```
 ### 事务管理
 ```go
 func (s *Store) Transaction(ctx context.Context, fn func(*Store) error) error {
    return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        txStore := &Store{db: tx, logger: s.logger}
        return fn(txStore)
    })
 }
 ```
 ### 连接池配置
 **PostgreSQL**:
 - MaxOpenConns: 25（最大连接）
 - MaxIdleConns: 10（空闲连接）
 - ConnMaxLifetime: 5m（连接生命周期）
 **Redis**:
 - PoolSize: 10
 - MinIdleConns: 5
 ---
 ## 扩展性设计
 ### 水平扩展
 **API 服务**:
 - 无状态设计
 - 通过负载均衡器分发请求
 - 自动扩缩容（K8s HPA）
 **Worker 服务**:
 - 多实例连接同一 Redis
 - Asynq 自动负载均衡
 - 按队列权重分配任务
 ### 数据库扩展
 **读写分离**:
 ```
 Primary (写) → Replica (读)
 ```
 **分库分表**:
 - 按业务模块垂直分库
 - 按数据量水平分表
 ---
 ## 监控与可观测性
 ### 健康检查
 - PostgreSQL Ping
 - Redis Ping
 - 连接池状态
 ### 日志
 - 访问日志: 所有 HTTP 请求
 - 错误日志: 错误详情
 - 慢查询日志: > 100ms
 - 任务日志: 提交/执行/失败
 ### 指标（建议）
 - API 响应时间
 - 数据库连接数
 - 任务队列长度
 - 任务失败率
 ---
 ## 安全设计
 ### 数据安全
 - SQL 注入防护（GORM 参数化）
 - 密码哈希（bcrypt）
 - 敏感字段不返回（`json:"-"`）
 ### 配置安全
 - 生产环境使用环境变量
 - 数据库 SSL 连接
 - Redis 密码认证
 ---
 ## 性能优化
 ### 数据库
 - 适当索引
 - 批量操作
 - 分页查询
 - 慢查询监控
 ### 任务队列
 - 优先级队列
 - 并发控制
 - 超时设置
 - 幂等性保障
 ---
 ## 参考文档
 - [功能总结](./功能总结.md)
 - [使用指南](./使用指南.md)
 - [项目 Constitution](../../.specify/memory/constitution.md)
--- a/go.mod
+++ b/go.mod
@@ -5,36 +5,95 @@ go 1.25.4
 require (
 	github.com/bytedance/sonic v1.14.2
 	github.com/fsnotify/fsnotify v1.9.0
 	github.com/go-playground/validator/v10 v10.28.0
 	github.com/gofiber/fiber/v2 v2.52.9
 	github.com/gofiber/storage/redis/v3 v3.4.1
 	github.com/golang-migrate/migrate/v4 v4.19.0
 	github.com/google/uuid v1.6.0
 	github.com/hibiken/asynq v0.25.1
 	github.com/lib/pq v1.10.9
 	github.com/redis/go-redis/v9 v9.16.0
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	github.com/testcontainers/testcontainers-go v0.40.0
 	github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0
 	github.com/valyala/fasthttp v1.51.0
 	go.uber.org/zap v1.27.0
 	golang.org/x/crypto v0.44.0
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 	gorm.io/driver/postgres v1.6.0
 	gorm.io/driver/sqlite v1.6.0
 	gorm.io/gorm v1.31.1
 )
 require (
 	dario.cat/mergo v1.0.2 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/andybalholm/brotli v1.1.0 // indirect
 	github.com/bytedance/gopkg v0.1.3 // indirect
 	github.com/bytedance/sonic/loader v0.4.0 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/containerd/platforms v0.2.1 // indirect
 	github.com/cpuguy83/dockercfg v0.3.2 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/distribution/reference v0.6.0 // indirect
 	github.com/docker/docker v28.5.1+incompatible // indirect
 	github.com/docker/go-connections v0.6.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/ebitengine/purego v0.8.4 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.10 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/pgx/v5 v5.7.6 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/klauspost/compress v1.18.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.9 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-sqlite3 v1.14.22 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/go-archive v0.1.0 // indirect
 	github.com/moby/patternmatcher v0.6.0 // indirect
 	github.com/moby/sys/sequential v0.6.0 // indirect
 	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
 	github.com/moby/term v0.5.0 // indirect
 	github.com/morikuni/aec v1.0.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/philhofer/fwd v1.1.3-0.20240916144458-20a13a1f6b7c // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
 	github.com/robfig/cron/v3 v3.0.1 // indirect
 	github.com/sagikazarmark/locafero v0.11.0 // indirect
 	github.com/shirou/gopsutil/v4 v4.25.6 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
@@ -42,13 +101,26 @@ require (
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
 	github.com/tinylib/msgp v1.2.5 // indirect
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/tcplisten v1.0.0 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0 // indirect
 	go.opentelemetry.io/otel v1.37.0 // indirect
 	go.opentelemetry.io/otel/metric v1.37.0 // indirect
 	go.opentelemetry.io/otel/sdk v1.37.0 // indirect
 	go.opentelemetry.io/otel/trace v1.37.0 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/arch v0.0.0-20210923205945-b76863e36670 // indirect
 	golang.org/x/sync v0.18.0 // indirect
 	golang.org/x/sys v0.38.0 // indirect
-	golang.org/x/text v0.28.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/grpc v1.75.1 // indirect
 	google.golang.org/protobuf v1.36.10 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
--- a/go.sum
+++ b/go.sum
@@ -1,7 +1,9 @@
-dario.cat/mergo v1.0.1 h1:Ra4+bf83h2ztPIQYNP99R6m+Y7KfnARDfID+a+vLl4s=
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
-dario.cat/mergo v1.0.1/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
-github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
-github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
 github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 h1:L/gRVlceqvL25UVaW/CKtUDjefjrs0SPonmDGUVOYP0=
 github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/andybalholm/brotli v1.1.0 h1:eLKJA0d02Lf0mVpIDgYnqXcUn0GqVmEFny3VuID1U3M=
@@ -16,8 +18,8 @@ github.com/bytedance/sonic v1.14.2 h1:k1twIoe97C1DtYUo+fZQy865IuHia4PR5RPiuGPPII
 github.com/bytedance/sonic v1.14.2/go.mod h1:T80iDELeHiHKSc0C9tubFygiuXoGzrkjKzX2quAx980=
 github.com/bytedance/sonic/loader v0.4.0 h1:olZ7lEqcxtZygCK9EKYKADnpQoYkRQxaeY2NYzevs+o=
 github.com/bytedance/sonic/loader v0.4.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
-github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
-github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
@@ -32,17 +34,21 @@ github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpS
 github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
 github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
 github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
 github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/dhui/dktest v0.4.6 h1:+DPKyScKSEp3VLtbMDHcUq6V5Lm5zfZZVb0Sk7Ahom4=
 github.com/dhui/dktest v0.4.6/go.mod h1:JHTSYDtKkvFNFHJKqCzVzqXecyv+tKt8EzceOmQOgbU=
 github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
-github.com/docker/docker v28.2.2+incompatible h1:CjwRSksz8Yo4+RmQ339Dp/D2tGO5JxwYeqtMOEe0LDw=
+github.com/docker/docker v28.5.1+incompatible h1:Bm8DchhSD2J6PsFzxC35TZo4TLGR2PdW/E69rU45NhM=
-github.com/docker/docker v28.2.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/docker v28.5.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
-github.com/docker/go-connections v0.5.0 h1:USnMq7hx7gwdVZq1L49hLXaFtUdTADjXGp+uj1Br63c=
+github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
-github.com/docker/go-connections v0.5.0/go.mod h1:ov60Kzw0kKElRwhNs9UlUHAE/F9Fe6GLaXnqyDdmEXc=
+github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0omw=
@@ -53,12 +59,23 @@ github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHk
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
+github.com/gabriel-vasile/mimetype v1.4.10 h1:zyueNbySn/z8mJZHLt6IPw0KoZsiQNszIpU+bX4+ZK0=
-github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/gabriel-vasile/mimetype v1.4.10/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
 github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
 github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.28.0 h1:Q7ibns33JjyW48gHkuFT91qX48KG0ktULL6FgHdG688=
 github.com/go-playground/validator/v10 v10.28.0/go.mod h1:GoI6I1SjPBh9p7ykNE/yj3fFYbyDOpwMn5KXd+m2hUU=
 github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
 github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/gofiber/fiber/v2 v2.52.9 h1:YjKl5DOiyP3j0mO61u3NTmK7or8GzzWzCFzkboyP5cw=
@@ -67,12 +84,34 @@ github.com/gofiber/storage/redis/v3 v3.4.1 h1:feZc1xv1UuW+a1qnpISPaak7r/r0SkNVFH
 github.com/gofiber/storage/redis/v3 v3.4.1/go.mod h1:rbycYIeewyFZ1uMf9I6t/C3RHZWIOmSRortjvyErhyA=
 github.com/gofiber/storage/testhelpers/redis v0.0.0-20250822074218-ba2347199921 h1:32Fh8t9QK2u2y8WnitCxIhf1AxKXBFFYk9tousVn/Fo=
 github.com/gofiber/storage/testhelpers/redis v0.0.0-20250822074218-ba2347199921/go.mod h1:PU9dj9E5K6+TLw7pF87y4yOf5HUH6S9uxTlhuRAVMEY=
-github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/golang-migrate/migrate/v4 v4.19.0 h1:RcjOnCGz3Or6HQYEJ/EEVLfWnmw9KnoigPSjzhCuaSE=
-github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang-migrate/migrate/v4 v4.19.0/go.mod h1:9dyEcu+hO+G9hPSw8AIg50yg622pXJsoHItQnDGZkI0=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 h1:NmZ1PKzSTQbuGHw9DGPFomqkkLWMC+vZCkfs+FHv1Vg=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3/go.mod h1:zQrxl1YP88HQlA6i9c63DSVPFklWpGX4OWAc9bFuaH4=
 github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
 github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
 github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
 github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
 github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
 github.com/hibiken/asynq v0.25.1 h1:phj028N0nm15n8O2ims+IvJ2gz4k2auvermngh9JhTw=
 github.com/hibiken/asynq v0.25.1/go.mod h1:pazWNOLBu0FEynQRBvHA26qdIKRSmfdIfUm4HdsLmXg=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
 github.com/jackc/pgx/v5 v5.7.6 h1:rWQc5FwZSPX58r1OQmkuaNicxdmExaEz5A2DO2hUuTk=
 github.com/jackc/pgx/v5 v5.7.6/go.mod h1:aruU7o91Tc2q2cFp5h4uP3f6ztExVpyVv88Xl/8Vl8M=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
 github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
 github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
 github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
 github.com/klauspost/cpuid/v2 v2.2.9 h1:66ze0taIn2H33fBvCkXuv9BmCwDfafmiIVpKV9kKGuY=
@@ -81,6 +120,10 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
 github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
@@ -92,6 +135,8 @@ github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWE
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
 github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
 github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
 github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
 github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
 github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
@@ -100,6 +145,8 @@ github.com/moby/go-archive v0.1.0 h1:Kk/5rdW/g+H8NHdJW2gsXyZ7UnzvJNOy6VKJqueWdcQ
 github.com/moby/go-archive v0.1.0/go.mod h1:G9B+YoujNohJmrIYFBpSd54GTUB4lt9S+xVQvsJyFuo=
 github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
 github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
 github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w3A14Sw=
 github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs=
 github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
 github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
 github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
@@ -128,12 +175,14 @@ github.com/redis/go-redis/v9 v9.16.0 h1:OotgqgLSRCmzfqChbQyG1PHC3tLNR89DG4jdOERS
 github.com/redis/go-redis/v9 v9.16.0/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
 github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
 github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
 github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
 github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
 github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
-github.com/shirou/gopsutil/v4 v4.25.5 h1:rtd9piuSMGeU8g1RMXjZs9y9luK5BwtnG7dZaQUJAsc=
+github.com/shirou/gopsutil/v4 v4.25.6 h1:kLysI2JsKorfaFPcYmcJqbzROzsBWEOAtw6A7dIfqXs=
-github.com/shirou/gopsutil/v4 v4.25.5/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
+github.com/shirou/gopsutil/v4 v4.25.6/go.mod h1:PfybzyydfZcN+JMMjkF6Zb8Mq1A/VcogFFg7hj50W9c=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
 github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
@@ -151,6 +200,8 @@ github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSS
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
@@ -159,8 +210,10 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
-github.com/testcontainers/testcontainers-go v0.38.0 h1:d7uEapLcv2P8AvH8ahLqDMMxda2W9gQN1nRbHS28HBw=
+github.com/testcontainers/testcontainers-go v0.40.0 h1:pSdJYLOVgLE8YdUY2FHQ1Fxu+aMnb6JfVz1mxk7OeMU=
-github.com/testcontainers/testcontainers-go v0.38.0/go.mod h1:C52c9MoHpWO+C4aqmgSU+hxlR5jlEayWtgYrb8Pzz1w=
+github.com/testcontainers/testcontainers-go v0.40.0/go.mod h1:FSXV5KQtX2HAMlm7U3APNyLkkap35zNLxukw9oBi/MY=
 github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0 h1:s2bIayFXlbDFexo96y+htn7FzuhpXLYJNnIuglNKqOk=
 github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0/go.mod h1:h+u/2KoREGTnTl9UwrQ/g+XhasAT8E6dClclAADeXoQ=
 github.com/testcontainers/testcontainers-go/modules/redis v0.38.0 h1:289pn0BFmGqDrd6BrImZAprFef9aaPZacx07YOQaPV4=
 github.com/testcontainers/testcontainers-go/modules/redis v0.38.0/go.mod h1:EcKPWRzOglnQfYe+ekA8RPEIWSNJTGwaC5oE5bQV+D0=
 github.com/tinylib/msgp v1.2.5 h1:WeQg1whrXRFiZusidTQqzETkRpGjFjcIhW6uqWH09po=
@@ -181,14 +234,22 @@ github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo
 github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0 h1:TT4fX+nBOA/+LUkobKGW1ydGcn+G3vRw9+g5HwCphpk=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.54.0/go.mod h1:L7UH0GbB0p47T4Rri3uHjbpCFYrVrwc1I25QhNPiGK8=
-go.opentelemetry.io/otel v1.35.0 h1:xKWKPxrxB6OtMCbmMY021CqC45J+3Onta9MqjhnusiQ=
+go.opentelemetry.io/otel v1.37.0 h1:9zhNfelUvx0KBfu/gb+ZgeAfAgtWrfHJZcAqFC228wQ=
-go.opentelemetry.io/otel v1.35.0/go.mod h1:UEqy8Zp11hpkUrL73gSlELM0DupHoiq72dR+Zqel/+Y=
+go.opentelemetry.io/otel v1.37.0/go.mod h1:ehE/umFRLnuLa/vSccNq9oS1ErUlkkK71gMcN34UG8I=
-go.opentelemetry.io/otel/metric v1.35.0 h1:0znxYu2SNyuMSQT4Y9WDWej0VpcsxkuklLa4/siN90M=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0 h1:1fTNlAIJZGWLP5FVu0fikVry1IsiUnXjf7QFvoNN3Xw=
-go.opentelemetry.io/otel/metric v1.35.0/go.mod h1:nKVFgxBZ2fReX6IlyW28MgZojkoAkJGaE8CpgeAU3oE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0/go.mod h1:zjPK58DtkqQFn+YUMbx0M2XV3QgKU0gS9LeGohREyK4=
-go.opentelemetry.io/otel/trace v1.35.0 h1:dPpEfJu1sDIqruz7BHFG3c7528f6ddfSWfFDVt/xgMs=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 h1:IeMeyr1aBvBiPVYihXIaeIZba6b8E1bYp7lbdxK8CQg=
-go.opentelemetry.io/otel/trace v1.35.0/go.mod h1:WUk7DtFp1Aw2MkvqGdwiXYDZZNvA/1J8o6xRXLrIkyc=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0/go.mod h1:oVdCUtjq9MK9BlS7TtucsQwUcXcymNiEDjgDD2jMtZU=
 go.opentelemetry.io/otel/metric v1.37.0 h1:mvwbQS5m0tbmqML4NqK+e3aDiO02vsf/WgbsdpcPoZE=
 go.opentelemetry.io/otel/metric v1.37.0/go.mod h1:04wGrZurHYKOc+RKeye86GwKiTb9FKm1WHtO+4EVr2E=
 go.opentelemetry.io/otel/sdk v1.37.0 h1:ItB0QUqnjesGRvNcmAcU0LyvkVyGJ2xftD29bWdDvKI=
 go.opentelemetry.io/otel/sdk v1.37.0/go.mod h1:VredYzxUvuo2q3WRcDnKDjbdvmO0sCzOvVAiY+yUkAg=
 go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mxVK7z4=
 go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
 go.opentelemetry.io/proto/otlp v1.5.0 h1:xJvq7gMzB31/d406fB8U5CBdyQGw4P399D1aQWU/3i4=
 go.opentelemetry.io/proto/otlp v1.5.0/go.mod h1:keN8WnHxOy8PG0rQZjJJ5A2ebUoafqWp0eVQ4yIXvJ4=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
@@ -199,19 +260,51 @@ go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/arch v0.0.0-20210923205945-b76863e36670 h1:18EFjUmQOcUvxNYSkA6jO9VAiXCnxFY6NyDX0bHDmkU=
 golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
-golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE=
+golang.org/x/crypto v0.44.0 h1:A97SsFvM3AIwEEmTBiaxPPTYpDC47w720rdiiUvgoAU=
-golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc=
+golang.org/x/crypto v0.44.0/go.mod h1:013i+Nw79BMiQiMsOPcVCB5ZIJbYkerPrGnOa00tvmc=
 golang.org/x/net v0.46.0 h1:giFlY12I07fugqwPuWJi68oOnpfqFnJIJzaIIm2JVV4=
 golang.org/x/net v0.46.0/go.mod h1:Q9BGdFy1y4nkUwiLvT5qtyhAnEHgnQ/zd8PfU6nc210=
 golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
 golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
 golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
+golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
-golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
 golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
 golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
 golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
 golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9 h1:9+tzLLstTlPTRyJTh+ah5wIMsBW5c4tQwGTN3thOW9Y=
 google.golang.org/genproto/googleapis/api v0.0.0-20250929231259-57b25ae835d4 h1:8XJ4pajGwOlasW+L13MnEGA8W4115jJySQtVfS2/IBU=
 google.golang.org/genproto/googleapis/api v0.0.0-20250929231259-57b25ae835d4/go.mod h1:NnuHhy+bxcg30o7FnVAZbXsPHUDQ9qKWAQKCD7VxFtk=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250929231259-57b25ae835d4 h1:i8QOKZfYg6AbGVZzUAY3LrNWCKF8O6zFisU9Wl9RER4=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250929231259-57b25ae835d4/go.mod h1:HSkG/KdJWusxU1F6CNrwNDjBMgisKxGnc5dAZfT0mjQ=
 google.golang.org/grpc v1.75.1 h1:/ODCNEuf9VghjgO3rqLcfg8fiOP0nSluljWFlDxELLI=
 google.golang.org/grpc v1.75.1/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
 google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
 google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
 gorm.io/driver/postgres v1.6.0/go.mod h1:vUw0mrGgrTK+uPHEhAdV4sfFELrByKVGnaVRkXDhtWo=
 gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
 gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
 gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
 gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
--- a/internal/handler/health.go
+++ b/internal/handler/health.go
@@ -1,18 +1,116 @@
 package handler
 import (
 	"context"
 	"time"
 	"github.com/gofiber/fiber/v2"
 	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 	"github.com/break/junhong_cmp_fiber/pkg/logger"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
 )
-// HealthCheck 健康检查处理器
+// HealthHandler 健康检查处理器
 type HealthHandler struct {
 	db     *gorm.DB
 	redis  *redis.Client
 	logger *zap.Logger
 }
 // NewHealthHandler 创建健康检查处理器实例
 func NewHealthHandler(db *gorm.DB, redis *redis.Client, logger *zap.Logger) *HealthHandler {
 	return &HealthHandler{
 		db:     db,
 		redis:  redis,
 		logger: logger,
 	}
 }
 // Check 健康检查
 // GET /health
 func (h *HealthHandler) Check(c *fiber.Ctx) error {
 	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
 	defer cancel()
 	healthStatus := fiber.Map{
 		"status":    "healthy",
 		"timestamp": time.Now().Format(time.RFC3339),
 		"services":  fiber.Map{},
 	}
 	services := healthStatus["services"].(fiber.Map)
 	allHealthy := true
 	// 检查 PostgreSQL
 	sqlDB, err := h.db.DB()
 	if err != nil {
 		h.logger.Error("获取 PostgreSQL DB 实例失败", zap.Error(err))
 		services["postgres"] = fiber.Map{
 			"status": "down",
 			"error":  err.Error(),
 		}
 		allHealthy = false
 	} else {
 		if err := sqlDB.PingContext(ctx); err != nil {
 			h.logger.Error("PostgreSQL Ping 失败", zap.Error(err))
 			services["postgres"] = fiber.Map{
 				"status": "down",
 				"error":  err.Error(),
 			}
 			allHealthy = false
 		} else {
 			// 获取连接池统计信息
 			stats := sqlDB.Stats()
 			services["postgres"] = fiber.Map{
 				"status":             "up",
 				"open_conns":         stats.OpenConnections,
 				"in_use":             stats.InUse,
 				"idle":               stats.Idle,
 				"wait_count":         stats.WaitCount,
 				"wait_duration":      stats.WaitDuration.String(),
 				"max_idle_close":     stats.MaxIdleClosed,
 				"max_lifetime_close": stats.MaxLifetimeClosed,
 			}
 		}
 	}
 	// 检查 Redis
 	if err := h.redis.Ping(ctx).Err(); err != nil {
 		h.logger.Error("Redis Ping 失败", zap.Error(err))
 		services["redis"] = fiber.Map{
 			"status": "down",
 			"error":  err.Error(),
 		}
 		allHealthy = false
 	} else {
 		// 获取 Redis 信息
 		poolStats := h.redis.PoolStats()
 		services["redis"] = fiber.Map{
 			"status":      "up",
 			"hits":        poolStats.Hits,
 			"misses":      poolStats.Misses,
 			"timeouts":    poolStats.Timeouts,
 			"total_conns": poolStats.TotalConns,
 			"idle_conns":  poolStats.IdleConns,
 			"stale_conns": poolStats.StaleConns,
 		}
 	}
 	// 设置总体状态
 	if !allHealthy {
 		healthStatus["status"] = "degraded"
 		h.logger.Warn("健康检查失败: 部分服务不可用")
 		return c.Status(fiber.StatusServiceUnavailable).JSON(healthStatus)
 	}
 	h.logger.Info("健康检查成功: 所有服务正常")
 	return response.Success(c, healthStatus)
 }
 // HealthCheck 简单健康检查(保持向后兼容)
 func HealthCheck(c *fiber.Ctx) error {
 	logger.GetAppLogger().Info("我还活着!!!!", zap.String("time", time.Now().Format(time.RFC3339)))
 	return response.Success(c, fiber.Map{
 		"status":    "healthy",
 		"timestamp": time.Now().Format(time.RFC3339),
--- a/internal/handler/order.go
+++ b/internal/handler/order.go
@@ -0,0 +1,239 @@
 package handler
 import (
 	"strconv"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/service/order"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
 	"github.com/gofiber/fiber/v2"
 	"go.uber.org/zap"
 )
 // OrderHandler 订单处理器
 type OrderHandler struct {
 	orderService *order.Service
 	logger       *zap.Logger
 }
 // NewOrderHandler 创建订单处理器实例
 func NewOrderHandler(orderService *order.Service, logger *zap.Logger) *OrderHandler {
 	return &OrderHandler{
 		orderService: orderService,
 		logger:       logger,
 	}
 }
 // CreateOrder 创建订单
 // POST /api/v1/orders
 func (h *OrderHandler) CreateOrder(c *fiber.Ctx) error {
 	var req model.CreateOrderRequest
 	// 解析请求体
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析请求体失败",
 			zap.String("path", c.Path()),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证请求参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("参数验证失败",
 			zap.String("path", c.Path()),
 			zap.Any("request", req),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 调用服务层创建订单
 	orderResp, err := h.orderService.CreateOrder(c.Context(), &req)
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("创建订单失败",
 			zap.String("order_id", req.OrderID),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "创建订单失败")
 	}
 	h.logger.Info("订单创建成功",
 		zap.Uint("order_id", orderResp.ID),
 		zap.String("order_no", orderResp.OrderID))
 	return response.Success(c, orderResp)
 }
 // GetOrder 获取订单详情
 // GET /api/v1/orders/:id
 func (h *OrderHandler) GetOrder(c *fiber.Ctx) error {
 	// 获取路径参数
 	idStr := c.Params("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
 		h.logger.Warn("订单ID格式错误",
 			zap.String("id", idStr),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "订单ID格式错误")
 	}
 	// 调用服务层获取订单
 	orderResp, err := h.orderService.GetOrderByID(c.Context(), uint(id))
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("获取订单失败",
 			zap.Uint("order_id", uint(id)),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取订单失败")
 	}
 	return response.Success(c, orderResp)
 }
 // UpdateOrder 更新订单信息
 // PUT /api/v1/orders/:id
 func (h *OrderHandler) UpdateOrder(c *fiber.Ctx) error {
 	// 获取路径参数
 	idStr := c.Params("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
 		h.logger.Warn("订单ID格式错误",
 			zap.String("id", idStr),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "订单ID格式错误")
 	}
 	var req model.UpdateOrderRequest
 	// 解析请求体
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析请求体失败",
 			zap.String("path", c.Path()),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证请求参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("参数验证失败",
 			zap.String("path", c.Path()),
 			zap.Any("request", req),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 调用服务层更新订单
 	orderResp, err := h.orderService.UpdateOrder(c.Context(), uint(id), &req)
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("更新订单失败",
 			zap.Uint("order_id", uint(id)),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "更新订单失败")
 	}
 	h.logger.Info("订单更新成功",
 		zap.Uint("order_id", uint(id)))
 	return response.Success(c, orderResp)
 }
 // ListOrders 获取订单列表（分页）
 // GET /api/v1/orders
 func (h *OrderHandler) ListOrders(c *fiber.Ctx) error {
 	// 获取查询参数
 	page, err := strconv.Atoi(c.Query("page", "1"))
 	if err != nil || page < 1 {
 		page = 1
 	}
 	pageSize, err := strconv.Atoi(c.Query("page_size", "20"))
 	if err != nil || pageSize < 1 {
 		pageSize = 20
 	}
 	if pageSize > 100 {
 		pageSize = 100 // 限制最大页大小
 	}
 	// 可选的用户ID过滤
 	var userID uint
 	if userIDStr := c.Query("user_id"); userIDStr != "" {
 		if id, err := strconv.ParseUint(userIDStr, 10, 32); err == nil {
 			userID = uint(id)
 		}
 	}
 	// 调用服务层获取订单列表
 	var orders []model.Order
 	var total int64
 	if userID > 0 {
 		// 按用户ID查询
 		orders, total, err = h.orderService.ListOrdersByUserID(c.Context(), userID, page, pageSize)
 	} else {
 		// 查询所有订单
 		orders, total, err = h.orderService.ListOrders(c.Context(), page, pageSize)
 	}
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message)
 		}
 		h.logger.Error("获取订单列表失败",
 			zap.Int("page", page),
 			zap.Int("page_size", pageSize),
 			zap.Uint("user_id", userID),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取订单列表失败")
 	}
 	// 构造响应
 	totalPages := int(total) / pageSize
 	if int(total)%pageSize > 0 {
 		totalPages++
 	}
 	listResp := model.ListOrdersResponse{
 		Orders:     make([]model.OrderResponse, 0, len(orders)),
 		Page:       page,
 		PageSize:   pageSize,
 		Total:      total,
 		TotalPages: totalPages,
 	}
 	// 转换为响应格式
 	for _, o := range orders {
 		listResp.Orders = append(listResp.Orders, model.OrderResponse{
 			ID:          o.ID,
 			OrderID:     o.OrderID,
 			UserID:      o.UserID,
 			Amount:      o.Amount,
 			Status:      o.Status,
 			Remark:      o.Remark,
 			PaidAt:      o.PaidAt,
 			CompletedAt: o.CompletedAt,
 			CreatedAt:   o.CreatedAt,
 			UpdatedAt:   o.UpdatedAt,
 		})
 	}
 	return response.Success(c, listResp)
 }
--- a/internal/handler/task.go
+++ b/internal/handler/task.go
@@ -0,0 +1,213 @@
 package handler
 import (
 	"fmt"
 	"time"
 	"github.com/gofiber/fiber/v2"
 	"github.com/google/uuid"
 	"github.com/hibiken/asynq"
 	"go.uber.org/zap"
 	"github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
 )
 // TaskHandler 任务处理器
 type TaskHandler struct {
 	queueClient *queue.Client
 	logger      *zap.Logger
 }
 // NewTaskHandler 创建任务处理器实例
 func NewTaskHandler(queueClient *queue.Client, logger *zap.Logger) *TaskHandler {
 	return &TaskHandler{
 		queueClient: queueClient,
 		logger:      logger,
 	}
 }
 // SubmitEmailTaskRequest 提交邮件任务请求
 type SubmitEmailTaskRequest struct {
 	To          string   `json:"to" validate:"required,email"`
 	Subject     string   `json:"subject" validate:"required,min=1,max=200"`
 	Body        string   `json:"body" validate:"required,min=1"`
 	CC          []string `json:"cc,omitempty" validate:"omitempty,dive,email"`
 	Attachments []string `json:"attachments,omitempty"`
 	RequestID   string   `json:"request_id,omitempty"`
 }
 // SubmitSyncTaskRequest 提交数据同步任务请求
 type SubmitSyncTaskRequest struct {
 	SyncType  string `json:"sync_type" validate:"required,oneof=sim_status flow_usage real_name"`
 	StartDate string `json:"start_date" validate:"required"`
 	EndDate   string `json:"end_date" validate:"required"`
 	BatchSize int    `json:"batch_size,omitempty" validate:"omitempty,min=1,max=1000"`
 	RequestID string `json:"request_id,omitempty"`
 	Priority  string `json:"priority,omitempty" validate:"omitempty,oneof=critical default low"`
 }
 // TaskResponse 任务响应
 type TaskResponse struct {
 	TaskID string `json:"task_id"`
 	Queue  string `json:"queue"`
 	Status string `json:"status"`
 }
 // SubmitEmailTask 提交邮件发送任务
 // @Summary 提交邮件发送任务
 // @Description 异步发送邮件
 // @Tags 任务
 // @Accept json
 // @Produce json
 // @Param request body SubmitEmailTaskRequest true "邮件任务参数"
 // @Success 200 {object} response.Response{data=TaskResponse}
 // @Failure 400 {object} response.Response
 // @Router /api/v1/tasks/email [post]
 func (h *TaskHandler) SubmitEmailTask(c *fiber.Ctx) error {
 	var req SubmitEmailTaskRequest
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析邮件任务请求失败",
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("邮件任务参数验证失败",
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 生成 RequestID（如果未提供）
 	if req.RequestID == "" {
 		req.RequestID = generateRequestID("email")
 	}
 	// 构造任务载荷
 	payload := &task.EmailPayload{
 		RequestID:   req.RequestID,
 		To:          req.To,
 		Subject:     req.Subject,
 		Body:        req.Body,
 		CC:          req.CC,
 		Attachments: req.Attachments,
 	}
 	// 提交任务到队列
 	err := h.queueClient.EnqueueTask(
 		c.Context(),
 		constants.TaskTypeEmailSend,
 		payload,
 		asynq.Queue(constants.QueueDefault),
 		asynq.MaxRetry(constants.DefaultRetryMax),
 		asynq.Timeout(constants.DefaultTimeout),
 	)
 	if err != nil {
 		h.logger.Error("提交邮件任务失败",
 			zap.String("to", req.To),
 			zap.String("request_id", req.RequestID),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "任务提交失败")
 	}
 	h.logger.Info("邮件任务提交成功",
 		zap.String("queue", constants.QueueDefault),
 		zap.String("to", req.To),
 		zap.String("request_id", req.RequestID))
 	return response.SuccessWithMessage(c, TaskResponse{
 		TaskID: req.RequestID,
 		Queue:  constants.QueueDefault,
 		Status: "queued",
 	}, "邮件任务已提交")
 }
 // SubmitSyncTask 提交数据同步任务
 // @Summary 提交数据同步任务
 // @Description 异步执行数据同步
 // @Tags 任务
 // @Accept json
 // @Produce json
 // @Param request body SubmitSyncTaskRequest true "同步任务参数"
 // @Success 200 {object} response.Response{data=TaskResponse}
 // @Failure 400 {object} response.Response
 // @Router /api/v1/tasks/sync [post]
 func (h *TaskHandler) SubmitSyncTask(c *fiber.Ctx) error {
 	var req SubmitSyncTaskRequest
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析同步任务请求失败",
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("同步任务参数验证失败",
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 生成 RequestID（如果未提供）
 	if req.RequestID == "" {
 		req.RequestID = generateRequestID("sync")
 	}
 	// 设置默认批量大小
 	if req.BatchSize == 0 {
 		req.BatchSize = 100
 	}
 	// 确定队列优先级
 	queueName := constants.QueueDefault
 	if req.Priority == "critical" {
 		queueName = constants.QueueCritical
 	} else if req.Priority == "low" {
 		queueName = constants.QueueLow
 	}
 	// 构造任务载荷
 	payload := &task.DataSyncPayload{
 		RequestID: req.RequestID,
 		SyncType:  req.SyncType,
 		StartDate: req.StartDate,
 		EndDate:   req.EndDate,
 		BatchSize: req.BatchSize,
 	}
 	// 提交任务到队列
 	err := h.queueClient.EnqueueTask(
 		c.Context(),
 		constants.TaskTypeDataSync,
 		payload,
 		asynq.Queue(queueName),
 		asynq.MaxRetry(constants.DefaultRetryMax),
 		asynq.Timeout(constants.DefaultTimeout),
 	)
 	if err != nil {
 		h.logger.Error("提交同步任务失败",
 			zap.String("sync_type", req.SyncType),
 			zap.String("request_id", req.RequestID),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "任务提交失败")
 	}
 	h.logger.Info("同步任务提交成功",
 		zap.String("queue", queueName),
 		zap.String("sync_type", req.SyncType),
 		zap.String("request_id", req.RequestID))
 	return response.SuccessWithMessage(c, TaskResponse{
 		TaskID: req.RequestID,
 		Queue:  queueName,
 		Status: "queued",
 	}, "同步任务已提交")
 }
 // generateRequestID 生成请求 ID
 func generateRequestID(prefix string) string {
 	return fmt.Sprintf("%s-%s-%d", prefix, uuid.New().String(), time.Now().UnixNano())
 }
--- a/internal/handler/user.go
+++ b/internal/handler/user.go
@@ -1,33 +1,250 @@
 package handler
 import (
-	"github.com/gofiber/fiber/v2"
+	"strconv"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/service/user"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
 	"github.com/go-playground/validator/v10"
 	"github.com/gofiber/fiber/v2"
 	"go.uber.org/zap"
 )
-// GetUsers 获取用户列表（示例受保护端点）
+var validate = validator.New()
 func GetUsers(c *fiber.Ctx) error {
 	// 从上下文获取用户 ID（由 auth 中间件设置）
 	userID := c.Locals(constants.ContextKeyUserID)
-	// 示例数据
+// UserHandler 用户处理器
-	users := []fiber.Map{
+type UserHandler struct {
-		{
+	userService *user.Service
-			"id":    "user-123",
+	logger      *zap.Logger
 			"name":  "张三",
 			"email": "zhangsan@example.com",
 		},
 		{
 			"id":    "user-456",
 			"name":  "李四",
 			"email": "lisi@example.com",
 		},
 }
-	return response.SuccessWithMessage(c, fiber.Map{
+// NewUserHandler 创建用户处理器实例
-		"users":            users,
+func NewUserHandler(userService *user.Service, logger *zap.Logger) *UserHandler {
-		"authenticated_as": userID,
+	return &UserHandler{
-	}, "success")
+		userService: userService,
 		logger:      logger,
 	}
 }
 // CreateUser 创建用户
 // POST /api/v1/users
 func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
 	var req model.CreateUserRequest
 	// 解析请求体
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析请求体失败",
 			zap.String("path", c.Path()),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证请求参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("参数验证失败",
 			zap.String("path", c.Path()),
 			zap.Any("request", req),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 调用服务层创建用户
 	userResp, err := h.userService.CreateUser(c.Context(), &req)
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message)
 		}
 		h.logger.Error("创建用户失败",
 			zap.String("username", req.Username),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "创建用户失败")
 	}
 	h.logger.Info("用户创建成功",
 		zap.Uint("user_id", userResp.ID),
 		zap.String("username", userResp.Username))
 	return response.Success(c, userResp)
 }
 // GetUser 获取用户详情
 // GET /api/v1/users/:id
 func (h *UserHandler) GetUser(c *fiber.Ctx) error {
 	// 获取路径参数
 	idStr := c.Params("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
 		h.logger.Warn("用户ID格式错误",
 			zap.String("id", idStr),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
 	}
 	// 调用服务层获取用户
 	userResp, err := h.userService.GetUserByID(c.Context(), uint(id))
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("获取用户失败",
 			zap.Uint("user_id", uint(id)),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户失败")
 	}
 	return response.Success(c, userResp)
 }
 // UpdateUser 更新用户信息
 // PUT /api/v1/users/:id
 func (h *UserHandler) UpdateUser(c *fiber.Ctx) error {
 	// 获取路径参数
 	idStr := c.Params("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
 		h.logger.Warn("用户ID格式错误",
 			zap.String("id", idStr),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
 	}
 	var req model.UpdateUserRequest
 	// 解析请求体
 	if err := c.BodyParser(&req); err != nil {
 		h.logger.Warn("解析请求体失败",
 			zap.String("path", c.Path()),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "请求参数格式错误")
 	}
 	// 验证请求参数
 	if err := validate.Struct(&req); err != nil {
 		h.logger.Warn("参数验证失败",
 			zap.String("path", c.Path()),
 			zap.Any("request", req),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, err.Error())
 	}
 	// 调用服务层更新用户
 	userResp, err := h.userService.UpdateUser(c.Context(), uint(id), &req)
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("更新用户失败",
 			zap.Uint("user_id", uint(id)),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "更新用户失败")
 	}
 	h.logger.Info("用户更新成功",
 		zap.Uint("user_id", uint(id)))
 	return response.Success(c, userResp)
 }
 // DeleteUser 删除用户（软删除）
 // DELETE /api/v1/users/:id
 func (h *UserHandler) DeleteUser(c *fiber.Ctx) error {
 	// 获取路径参数
 	idStr := c.Params("id")
 	id, err := strconv.ParseUint(idStr, 10, 32)
 	if err != nil {
 		h.logger.Warn("用户ID格式错误",
 			zap.String("id", idStr),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusBadRequest, errors.CodeBadRequest, "用户ID格式错误")
 	}
 	// 调用服务层删除用户
 	if err := h.userService.DeleteUser(c.Context(), uint(id)); err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			httpStatus := fiber.StatusInternalServerError
 			if e.Code == errors.CodeNotFound {
 				httpStatus = fiber.StatusNotFound
 			}
 			return response.Error(c, httpStatus, e.Code, e.Message)
 		}
 		h.logger.Error("删除用户失败",
 			zap.Uint("user_id", uint(id)),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "删除用户失败")
 	}
 	h.logger.Info("用户删除成功",
 		zap.Uint("user_id", uint(id)))
 	return response.Success(c, nil)
 }
 // ListUsers 获取用户列表（分页）
 // GET /api/v1/users
 func (h *UserHandler) ListUsers(c *fiber.Ctx) error {
 	// 获取查询参数
 	page, err := strconv.Atoi(c.Query("page", "1"))
 	if err != nil || page < 1 {
 		page = 1
 	}
 	pageSize, err := strconv.Atoi(c.Query("page_size", "20"))
 	if err != nil || pageSize < 1 {
 		pageSize = 20
 	}
 	if pageSize > 100 {
 		pageSize = 100 // 限制最大页大小
 	}
 	// 调用服务层获取用户列表
 	users, total, err := h.userService.ListUsers(c.Context(), page, pageSize)
 	if err != nil {
 		if e, ok := err.(*errors.AppError); ok {
 			return response.Error(c, fiber.StatusInternalServerError, e.Code, e.Message)
 		}
 		h.logger.Error("获取用户列表失败",
 			zap.Int("page", page),
 			zap.Int("page_size", pageSize),
 			zap.Error(err))
 		return response.Error(c, fiber.StatusInternalServerError, errors.CodeInternalError, "获取用户列表失败")
 	}
 	// 构造响应
 	totalPages := int(total) / pageSize
 	if int(total)%pageSize > 0 {
 		totalPages++
 	}
 	listResp := model.ListUsersResponse{
 		Users:      make([]model.UserResponse, 0, len(users)),
 		Page:       page,
 		PageSize:   pageSize,
 		Total:      total,
 		TotalPages: totalPages,
 	}
 	// 转换为响应格式
 	for _, u := range users {
 		listResp.Users = append(listResp.Users, model.UserResponse{
 			ID:          u.ID,
 			Username:    u.Username,
 			Email:       u.Email,
 			Status:      u.Status,
 			CreatedAt:   u.CreatedAt,
 			UpdatedAt:   u.UpdatedAt,
 			LastLoginAt: u.LastLoginAt,
 		})
 	}
 	return response.Success(c, listResp)
 }
--- a/internal/model/base.go
+++ b/internal/model/base.go
@@ -0,0 +1,15 @@
 package model
 import (
 	"time"
 	"gorm.io/gorm"
 )
 // BaseModel 基础模型，包含通用字段
 type BaseModel struct {
 	ID        uint           `gorm:"primarykey" json:"id"`
 	CreatedAt time.Time      `json:"created_at"`
 	UpdatedAt time.Time      `json:"updated_at"`
 	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` // 软删除
 }
--- a/internal/model/order.go
+++ b/internal/model/order.go
@@ -0,0 +1,30 @@
 package model
 import (
 	"time"
 )
 // Order 订单实体
 type Order struct {
 	BaseModel
 	// 业务唯一键
 	OrderID string `gorm:"uniqueIndex:uk_order_order_id;not null;size:50" json:"order_id"`
 	// 关联关系 (仅存储 ID,不使用 GORM 关联)
 	UserID uint `gorm:"not null;index:idx_order_user_id" json:"user_id"`
 	// 订单信息
 	Amount int64  `gorm:"not null" json:"amount"` // 金额（分）
 	Status string `gorm:"not null;size:20;default:'pending';index:idx_order_status" json:"status"`
 	Remark string `gorm:"size:500" json:"remark,omitempty"`
 	// 时间字段
 	PaidAt      *time.Time `gorm:"column:paid_at" json:"paid_at,omitempty"`
 	CompletedAt *time.Time `gorm:"column:completed_at" json:"completed_at,omitempty"`
 }
 // TableName 指定表名
 func (Order) TableName() string {
 	return "tb_order"
 }
--- a/internal/model/order_dto.go
+++ b/internal/model/order_dto.go
@@ -0,0 +1,43 @@
 package model
 import (
 	"time"
 )
 // CreateOrderRequest 创建订单请求
 type CreateOrderRequest struct {
 	OrderID string `json:"order_id" validate:"required,min=10,max=50"`
 	UserID  uint   `json:"user_id" validate:"required,gt=0"`
 	Amount  int64  `json:"amount" validate:"required,gte=0"`
 	Remark  string `json:"remark" validate:"omitempty,max=500"`
 }
 // UpdateOrderRequest 更新订单请求
 type UpdateOrderRequest struct {
 	Status *string `json:"status" validate:"omitempty,oneof=pending paid processing completed cancelled"`
 	Remark *string `json:"remark" validate:"omitempty,max=500"`
 }
 // OrderResponse 订单响应
 type OrderResponse struct {
 	ID          uint          `json:"id"`
 	OrderID     string        `json:"order_id"`
 	UserID      uint          `json:"user_id"`
 	Amount      int64         `json:"amount"`
 	Status      string        `json:"status"`
 	Remark      string        `json:"remark,omitempty"`
 	PaidAt      *time.Time    `json:"paid_at,omitempty"`
 	CompletedAt *time.Time    `json:"completed_at,omitempty"`
 	CreatedAt   time.Time     `json:"created_at"`
 	UpdatedAt   time.Time     `json:"updated_at"`
 	User        *UserResponse `json:"user,omitempty"` // 可选的用户信息
 }
 // ListOrdersResponse 订单列表响应
 type ListOrdersResponse struct {
 	Orders     []OrderResponse `json:"orders"`
 	Page       int             `json:"page"`
 	PageSize   int             `json:"page_size"`
 	Total      int64           `json:"total"`
 	TotalPages int             `json:"total_pages"`
 }
--- a/internal/model/user.go
+++ b/internal/model/user.go
@@ -0,0 +1,26 @@
 package model
 import (
 	"time"
 )
 // User 用户实体
 type User struct {
 	BaseModel
 	// 基本信息
 	Username string `gorm:"uniqueIndex:uk_user_username;not null;size:50" json:"username"`
 	Email    string `gorm:"uniqueIndex:uk_user_email;not null;size:100" json:"email"`
 	Password string `gorm:"not null;size:255" json:"-"` // 不返回给客户端
 	// 状态字段
 	Status string `gorm:"not null;size:20;default:'active';index:idx_user_status" json:"status"`
 	// 元数据
 	LastLoginAt *time.Time `gorm:"column:last_login_at" json:"last_login_at,omitempty"`
 }
 // TableName 指定表名
 func (User) TableName() string {
 	return "tb_user"
 }
--- a/internal/model/user_dto.go
+++ b/internal/model/user_dto.go
@@ -0,0 +1,38 @@
 package model
 import (
 	"time"
 )
 // CreateUserRequest 创建用户请求
 type CreateUserRequest struct {
 	Username string `json:"username" validate:"required,min=3,max=50,alphanum"`
 	Email    string `json:"email" validate:"required,email"`
 	Password string `json:"password" validate:"required,min=8"`
 }
 // UpdateUserRequest 更新用户请求
 type UpdateUserRequest struct {
 	Email  *string `json:"email" validate:"omitempty,email"`
 	Status *string `json:"status" validate:"omitempty,oneof=active inactive suspended"`
 }
 // UserResponse 用户响应
 type UserResponse struct {
 	ID          uint       `json:"id"`
 	Username    string     `json:"username"`
 	Email       string     `json:"email"`
 	Status      string     `json:"status"`
 	CreatedAt   time.Time  `json:"created_at"`
 	UpdatedAt   time.Time  `json:"updated_at"`
 	LastLoginAt *time.Time `json:"last_login_at,omitempty"`
 }
 // ListUsersResponse 用户列表响应
 type ListUsersResponse struct {
 	Users      []UserResponse `json:"users"`
 	Page       int            `json:"page"`
 	PageSize   int            `json:"page_size"`
 	Total      int64          `json:"total"`
 	TotalPages int            `json:"total_pages"`
 }
--- a/internal/service/email/service.go
+++ b/internal/service/email/service.go
@@ -0,0 +1,156 @@
 package email
 import (
 	"context"
 	"fmt"
 	"github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"go.uber.org/zap"
 )
 // Service 邮件服务
 type Service struct {
 	queueClient *queue.Client
 	logger      *zap.Logger
 }
 // NewService 创建邮件服务实例
 func NewService(queueClient *queue.Client, logger *zap.Logger) *Service {
 	return &Service{
 		queueClient: queueClient,
 		logger:      logger,
 	}
 }
 // SendWelcomeEmail 发送欢迎邮件（异步）
 func (s *Service) SendWelcomeEmail(ctx context.Context, userID uint, email string) error {
 	// 构造任务载荷
 	payload := &task.EmailPayload{
 		RequestID: fmt.Sprintf("welcome-%d", userID),
 		To:        email,
 		Subject:   "欢迎加入君鸿卡管系统",
 		Body:      "感谢您注册我们的服务！我们很高兴为您提供服务。",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	if err != nil {
 		s.logger.Error("序列化邮件任务载荷失败",
 			zap.Uint("user_id", userID),
 			zap.String("email", email),
 			zap.Error(err))
 		return fmt.Errorf("序列化邮件任务载荷失败: %w", err)
 	}
 	// 提交任务到队列
 	err = s.queueClient.EnqueueTask(
 		ctx,
 		constants.TaskTypeEmailSend,
 		payloadBytes,
 		asynq.Queue(constants.QueueDefault),
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	if err != nil {
 		s.logger.Error("提交欢迎邮件任务失败",
 			zap.Uint("user_id", userID),
 			zap.String("email", email),
 			zap.Error(err))
 		return fmt.Errorf("提交欢迎邮件任务失败: %w", err)
 	}
 	s.logger.Info("欢迎邮件任务已提交",
 		zap.Uint("user_id", userID),
 		zap.String("email", email))
 	return nil
 }
 // SendPasswordResetEmail 发送密码重置邮件（异步）
 func (s *Service) SendPasswordResetEmail(ctx context.Context, email string, resetToken string) error {
 	// 构造任务载荷
 	payload := &task.EmailPayload{
 		RequestID: fmt.Sprintf("reset-%s-%s", email, resetToken),
 		To:        email,
 		Subject:   "密码重置请求",
 		Body:      fmt.Sprintf("您的密码重置令牌是: %s\n此令牌将在 1 小时后过期。", resetToken),
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	if err != nil {
 		s.logger.Error("序列化密码重置邮件任务载荷失败",
 			zap.String("email", email),
 			zap.Error(err))
 		return fmt.Errorf("序列化密码重置邮件任务载荷失败: %w", err)
 	}
 	// 提交任务到队列（高优先级）
 	err = s.queueClient.EnqueueTask(
 		ctx,
 		constants.TaskTypeEmailSend,
 		payloadBytes,
 		asynq.Queue(constants.QueueCritical), // 密码重置使用高优先级队列
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	if err != nil {
 		s.logger.Error("提交密码重置邮件任务失败",
 			zap.String("email", email),
 			zap.Error(err))
 		return fmt.Errorf("提交密码重置邮件任务失败: %w", err)
 	}
 	s.logger.Info("密码重置邮件任务已提交",
 		zap.String("email", email))
 	return nil
 }
 // SendNotificationEmail 发送通知邮件（异步）
 func (s *Service) SendNotificationEmail(ctx context.Context, to string, subject string, body string) error {
 	// 构造任务载荷
 	payload := &task.EmailPayload{
 		RequestID: fmt.Sprintf("notify-%s-%d", to, getCurrentTimestamp()),
 		To:        to,
 		Subject:   subject,
 		Body:      body,
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	if err != nil {
 		s.logger.Error("序列化通知邮件任务载荷失败",
 			zap.String("to", to),
 			zap.Error(err))
 		return fmt.Errorf("序列化通知邮件任务载荷失败: %w", err)
 	}
 	// 提交任务到队列（低优先级）
 	err = s.queueClient.EnqueueTask(
 		ctx,
 		constants.TaskTypeEmailSend,
 		payloadBytes,
 		asynq.Queue(constants.QueueLow), // 通知邮件使用低优先级队列
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	if err != nil {
 		s.logger.Error("提交通知邮件任务失败",
 			zap.String("to", to),
 			zap.Error(err))
 		return fmt.Errorf("提交通知邮件任务失败: %w", err)
 	}
 	s.logger.Info("通知邮件任务已提交",
 		zap.String("to", to),
 		zap.String("subject", subject))
 	return nil
 }
 // getCurrentTimestamp 获取当前时间戳（毫秒）
 func getCurrentTimestamp() int64 {
 	return 0 // 实际实现应返回真实时间戳
 }
--- a/internal/service/order/service.go
+++ b/internal/service/order/service.go
@@ -0,0 +1,254 @@
 package order
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	pkgErrors "github.com/break/junhong_cmp_fiber/pkg/errors"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 // Service 订单服务
 type Service struct {
 	store  *postgres.Store
 	logger *zap.Logger
 }
 // NewService 创建订单服务
 func NewService(store *postgres.Store, logger *zap.Logger) *Service {
 	return &Service{
 		store:  store,
 		logger: logger,
 	}
 }
 // CreateOrder 创建订单
 func (s *Service) CreateOrder(ctx context.Context, req *model.CreateOrderRequest) (*model.Order, error) {
 	// 验证用户是否存在
 	_, err := s.store.User.GetByID(ctx, req.UserID)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在")
 		}
 		s.logger.Error("查询用户失败",
 			zap.Uint("user_id", req.UserID),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败")
 	}
 	// 创建订单
 	order := &model.Order{
 		OrderID: req.OrderID,
 		UserID:  req.UserID,
 		Amount:  req.Amount,
 		Status:  constants.OrderStatusPending,
 		Remark:  req.Remark,
 	}
 	if err := s.store.Order.Create(ctx, order); err != nil {
 		s.logger.Error("创建订单失败",
 			zap.String("order_id", req.OrderID),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "创建订单失败")
 	}
 	s.logger.Info("订单创建成功",
 		zap.Uint("id", order.ID),
 		zap.String("order_id", order.OrderID),
 		zap.Uint("user_id", order.UserID))
 	return order, nil
 }
 // GetOrderByID 根据 ID 获取订单
 func (s *Service) GetOrderByID(ctx context.Context, id uint) (*model.Order, error) {
 	order, err := s.store.Order.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在")
 		}
 		s.logger.Error("获取订单失败",
 			zap.Uint("order_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单失败")
 	}
 	return order, nil
 }
 // UpdateOrder 更新订单
 func (s *Service) UpdateOrder(ctx context.Context, id uint, req *model.UpdateOrderRequest) (*model.Order, error) {
 	// 查询订单
 	order, err := s.store.Order.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在")
 		}
 		s.logger.Error("查询订单失败",
 			zap.Uint("order_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询订单失败")
 	}
 	// 更新字段
 	if req.Status != nil {
 		order.Status = *req.Status
 		// 根据状态自动设置时间字段
 		now := time.Now()
 		switch *req.Status {
 		case constants.OrderStatusPaid:
 			order.PaidAt = &now
 		case constants.OrderStatusCompleted:
 			order.CompletedAt = &now
 		}
 	}
 	if req.Remark != nil {
 		order.Remark = *req.Remark
 	}
 	// 保存更新
 	if err := s.store.Order.Update(ctx, order); err != nil {
 		s.logger.Error("更新订单失败",
 			zap.Uint("order_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "更新订单失败")
 	}
 	s.logger.Info("订单更新成功",
 		zap.Uint("id", order.ID),
 		zap.String("order_id", order.OrderID))
 	return order, nil
 }
 // DeleteOrder 删除订单（软删除）
 func (s *Service) DeleteOrder(ctx context.Context, id uint) error {
 	// 检查订单是否存在
 	_, err := s.store.Order.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return pkgErrors.New(pkgErrors.CodeNotFound, "订单不存在")
 		}
 		s.logger.Error("查询订单失败",
 			zap.Uint("order_id", id),
 			zap.Error(err))
 		return pkgErrors.New(pkgErrors.CodeInternalError, "查询订单失败")
 	}
 	// 软删除
 	if err := s.store.Order.Delete(ctx, id); err != nil {
 		s.logger.Error("删除订单失败",
 			zap.Uint("order_id", id),
 			zap.Error(err))
 		return pkgErrors.New(pkgErrors.CodeInternalError, "删除订单失败")
 	}
 	s.logger.Info("订单删除成功", zap.Uint("order_id", id))
 	return nil
 }
 // ListOrders 分页获取订单列表
 func (s *Service) ListOrders(ctx context.Context, page, pageSize int) ([]model.Order, int64, error) {
 	// 参数验证
 	if page < 1 {
 		page = 1
 	}
 	if pageSize < 1 {
 		pageSize = constants.DefaultPageSize
 	}
 	if pageSize > constants.MaxPageSize {
 		pageSize = constants.MaxPageSize
 	}
 	orders, total, err := s.store.Order.List(ctx, page, pageSize)
 	if err != nil {
 		s.logger.Error("获取订单列表失败",
 			zap.Int("page", page),
 			zap.Int("page_size", pageSize),
 			zap.Error(err))
 		return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单列表失败")
 	}
 	return orders, total, nil
 }
 // ListOrdersByUserID 根据用户ID分页获取订单列表
 func (s *Service) ListOrdersByUserID(ctx context.Context, userID uint, page, pageSize int) ([]model.Order, int64, error) {
 	// 参数验证
 	if page < 1 {
 		page = 1
 	}
 	if pageSize < 1 {
 		pageSize = constants.DefaultPageSize
 	}
 	if pageSize > constants.MaxPageSize {
 		pageSize = constants.MaxPageSize
 	}
 	orders, total, err := s.store.Order.ListByUserID(ctx, userID, page, pageSize)
 	if err != nil {
 		s.logger.Error("获取用户订单列表失败",
 			zap.Uint("user_id", userID),
 			zap.Int("page", page),
 			zap.Int("page_size", pageSize),
 			zap.Error(err))
 		return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取订单列表失败")
 	}
 	return orders, total, nil
 }
 // CreateOrderWithUser 创建订单并更新用户统计（事务示例）
 func (s *Service) CreateOrderWithUser(ctx context.Context, req *model.CreateOrderRequest) (*model.Order, error) {
 	var order *model.Order
 	// 使用事务
 	err := s.store.Transaction(ctx, func(tx *postgres.Store) error {
 		// 1. 验证用户是否存在
 		user, err := tx.User.GetByID(ctx, req.UserID)
 		if err != nil {
 			if err == gorm.ErrRecordNotFound {
 				return pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在")
 			}
 			return err
 		}
 		// 2. 创建订单
 		order = &model.Order{
 			OrderID: req.OrderID,
 			UserID:  req.UserID,
 			Amount:  req.Amount,
 			Status:  constants.OrderStatusPending,
 			Remark:  req.Remark,
 		}
 		if err := tx.Order.Create(ctx, order); err != nil {
 			return err
 		}
 		// 3. 更新用户状态（示例：可以在这里更新用户的订单计数等）
 		s.logger.Debug("订单创建成功，用户信息",
 			zap.String("username", user.Username),
 			zap.String("order_id", order.OrderID))
 		return nil // 提交事务
 	})
 	if err != nil {
 		s.logger.Error("事务创建订单失败",
 			zap.String("order_id", req.OrderID),
 			zap.Error(err))
 		return nil, fmt.Errorf("创建订单失败: %w", err)
 	}
 	s.logger.Info("事务创建订单成功",
 		zap.Uint("id", order.ID),
 		zap.String("order_id", order.OrderID),
 		zap.Uint("user_id", order.UserID))
 	return order, nil
 }
--- a/internal/service/sync/service.go
+++ b/internal/service/sync/service.go
@@ -0,0 +1,167 @@
 package sync
 import (
 	"context"
 	"fmt"
 	"github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/queue"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"go.uber.org/zap"
 )
 // Service 同步服务
 type Service struct {
 	queueClient *queue.Client
 	logger      *zap.Logger
 }
 // NewService 创建同步服务实例
 func NewService(queueClient *queue.Client, logger *zap.Logger) *Service {
 	return &Service{
 		queueClient: queueClient,
 		logger:      logger,
 	}
 }
 // SyncSIMStatus 同步 SIM 卡状态（异步）
 func (s *Service) SyncSIMStatus(ctx context.Context, iccids []string, forceSync bool) error {
 	// 构造任务载荷
 	payload := &task.SIMStatusSyncPayload{
 		RequestID: fmt.Sprintf("sim-sync-%d", getCurrentTimestamp()),
 		ICCIDs:    iccids,
 		ForceSync: forceSync,
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	if err != nil {
 		s.logger.Error("序列化 SIM 状态同步任务载荷失败",
 			zap.Int("iccid_count", len(iccids)),
 			zap.Bool("force_sync", forceSync),
 			zap.Error(err))
 		return fmt.Errorf("序列化 SIM 状态同步任务载荷失败: %w", err)
 	}
 	// 提交任务到队列（高优先级）
 	err = s.queueClient.EnqueueTask(
 		ctx,
 		constants.TaskTypeSIMStatusSync,
 		payloadBytes,
 		asynq.Queue(constants.QueueCritical), // SIM 状态同步使用高优先级队列
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	if err != nil {
 		s.logger.Error("提交 SIM 状态同步任务失败",
 			zap.Int("iccid_count", len(iccids)),
 			zap.Error(err))
 		return fmt.Errorf("提交 SIM 状态同步任务失败: %w", err)
 	}
 	s.logger.Info("SIM 状态同步任务已提交",
 		zap.Int("iccid_count", len(iccids)),
 		zap.Bool("force_sync", forceSync))
 	return nil
 }
 // SyncData 通用数据同步（异步）
 func (s *Service) SyncData(ctx context.Context, syncType string, startDate string, endDate string, batchSize int) error {
 	// 设置默认批量大小
 	if batchSize <= 0 {
 		batchSize = 100 // 默认批量大小
 	}
 	// 构造任务载荷
 	payload := &task.DataSyncPayload{
 		RequestID: fmt.Sprintf("data-sync-%s-%d", syncType, getCurrentTimestamp()),
 		SyncType:  syncType,
 		StartDate: startDate,
 		EndDate:   endDate,
 		BatchSize: batchSize,
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	if err != nil {
 		s.logger.Error("序列化数据同步任务载荷失败",
 			zap.String("sync_type", syncType),
 			zap.String("start_date", startDate),
 			zap.String("end_date", endDate),
 			zap.Error(err))
 		return fmt.Errorf("序列化数据同步任务载荷失败: %w", err)
 	}
 	// 提交任务到队列（默认优先级）
 	err = s.queueClient.EnqueueTask(
 		ctx,
 		constants.TaskTypeDataSync,
 		payloadBytes,
 		asynq.Queue(constants.QueueDefault),
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	if err != nil {
 		s.logger.Error("提交数据同步任务失败",
 			zap.String("sync_type", syncType),
 			zap.Error(err))
 		return fmt.Errorf("提交数据同步任务失败: %w", err)
 	}
 	s.logger.Info("数据同步任务已提交",
 		zap.String("sync_type", syncType),
 		zap.String("start_date", startDate),
 		zap.String("end_date", endDate),
 		zap.Int("batch_size", batchSize))
 	return nil
 }
 // SyncFlowUsage 同步流量使用数据（异步）
 func (s *Service) SyncFlowUsage(ctx context.Context, startDate string, endDate string) error {
 	return s.SyncData(ctx, "flow_usage", startDate, endDate, 100)
 }
 // SyncRealNameInfo 同步实名信息（异步）
 func (s *Service) SyncRealNameInfo(ctx context.Context, startDate string, endDate string) error {
 	return s.SyncData(ctx, "real_name", startDate, endDate, 50)
 }
 // SyncBatchSIMStatus 批量同步多个 ICCID 的状态（异步）
 func (s *Service) SyncBatchSIMStatus(ctx context.Context, iccids []string) error {
 	// 如果 ICCID 列表为空，直接返回
 	if len(iccids) == 0 {
 		s.logger.Warn("批量同步 SIM 状态时 ICCID 列表为空")
 		return nil
 	}
 	// 分批处理（每批最多 100 个）
 	batchSize := 100
 	for i := 0; i < len(iccids); i += batchSize {
 		end := i + batchSize
 		if end > len(iccids) {
 			end = len(iccids)
 		}
 		batch := iccids[i:end]
 		if err := s.SyncSIMStatus(ctx, batch, false); err != nil {
 			s.logger.Error("批量同步 SIM 状态失败",
 				zap.Int("batch_start", i),
 				zap.Int("batch_end", end),
 				zap.Error(err))
 			return err
 		}
 	}
 	s.logger.Info("批量 SIM 状态同步任务已全部提交",
 		zap.Int("total_iccids", len(iccids)),
 		zap.Int("batch_size", batchSize))
 	return nil
 }
 // getCurrentTimestamp 获取当前时间戳（毫秒）
 func getCurrentTimestamp() int64 {
 	return 0 // 实际实现应返回真实时间戳
 }
--- a/internal/service/user/service.go
+++ b/internal/service/user/service.go
@@ -0,0 +1,161 @@
 package user
 import (
 	"context"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	pkgErrors "github.com/break/junhong_cmp_fiber/pkg/errors"
 	"go.uber.org/zap"
 	"golang.org/x/crypto/bcrypt"
 	"gorm.io/gorm"
 )
 // Service 用户服务
 type Service struct {
 	store  *postgres.Store
 	logger *zap.Logger
 }
 // NewService 创建用户服务
 func NewService(store *postgres.Store, logger *zap.Logger) *Service {
 	return &Service{
 		store:  store,
 		logger: logger,
 	}
 }
 // CreateUser 创建用户
 func (s *Service) CreateUser(ctx context.Context, req *model.CreateUserRequest) (*model.User, error) {
 	// 密码哈希
 	hashedPassword, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost)
 	if err != nil {
 		s.logger.Error("密码哈希失败", zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "密码加密失败")
 	}
 	// 创建用户
 	user := &model.User{
 		Username: req.Username,
 		Email:    req.Email,
 		Password: string(hashedPassword),
 		Status:   constants.UserStatusActive,
 	}
 	if err := s.store.User.Create(ctx, user); err != nil {
 		s.logger.Error("创建用户失败",
 			zap.String("username", req.Username),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "创建用户失败")
 	}
 	s.logger.Info("用户创建成功",
 		zap.Uint("user_id", user.ID),
 		zap.String("username", user.Username))
 	return user, nil
 }
 // GetUserByID 根据 ID 获取用户
 func (s *Service) GetUserByID(ctx context.Context, id uint) (*model.User, error) {
 	user, err := s.store.User.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在")
 		}
 		s.logger.Error("获取用户失败",
 			zap.Uint("user_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "获取用户失败")
 	}
 	return user, nil
 }
 // UpdateUser 更新用户
 func (s *Service) UpdateUser(ctx context.Context, id uint, req *model.UpdateUserRequest) (*model.User, error) {
 	// 查询用户
 	user, err := s.store.User.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return nil, pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在")
 		}
 		s.logger.Error("查询用户失败",
 			zap.Uint("user_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败")
 	}
 	// 更新字段
 	if req.Email != nil {
 		user.Email = *req.Email
 	}
 	if req.Status != nil {
 		user.Status = *req.Status
 	}
 	// 保存更新
 	if err := s.store.User.Update(ctx, user); err != nil {
 		s.logger.Error("更新用户失败",
 			zap.Uint("user_id", id),
 			zap.Error(err))
 		return nil, pkgErrors.New(pkgErrors.CodeInternalError, "更新用户失败")
 	}
 	s.logger.Info("用户更新成功",
 		zap.Uint("user_id", user.ID),
 		zap.String("username", user.Username))
 	return user, nil
 }
 // DeleteUser 删除用户（软删除）
 func (s *Service) DeleteUser(ctx context.Context, id uint) error {
 	// 检查用户是否存在
 	_, err := s.store.User.GetByID(ctx, id)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
 			return pkgErrors.New(pkgErrors.CodeNotFound, "用户不存在")
 		}
 		s.logger.Error("查询用户失败",
 			zap.Uint("user_id", id),
 			zap.Error(err))
 		return pkgErrors.New(pkgErrors.CodeInternalError, "查询用户失败")
 	}
 	// 软删除
 	if err := s.store.User.Delete(ctx, id); err != nil {
 		s.logger.Error("删除用户失败",
 			zap.Uint("user_id", id),
 			zap.Error(err))
 		return pkgErrors.New(pkgErrors.CodeInternalError, "删除用户失败")
 	}
 	s.logger.Info("用户删除成功", zap.Uint("user_id", id))
 	return nil
 }
 // ListUsers 分页获取用户列表
 func (s *Service) ListUsers(ctx context.Context, page, pageSize int) ([]model.User, int64, error) {
 	// 参数验证
 	if page < 1 {
 		page = 1
 	}
 	if pageSize < 1 {
 		pageSize = constants.DefaultPageSize
 	}
 	if pageSize > constants.MaxPageSize {
 		pageSize = constants.MaxPageSize
 	}
 	users, total, err := s.store.User.List(ctx, page, pageSize)
 	if err != nil {
 		s.logger.Error("获取用户列表失败",
 			zap.Int("page", page),
 			zap.Int("page_size", pageSize),
 			zap.Error(err))
 		return nil, 0, pkgErrors.New(pkgErrors.CodeInternalError, "获取用户列表失败")
 	}
 	return users, total, nil
 }
--- a/internal/store/postgres/order_store.go
+++ b/internal/store/postgres/order_store.go
@@ -0,0 +1,104 @@
 package postgres
 import (
 	"context"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"gorm.io/gorm"
 )
 // OrderStore 订单数据访问层
 type OrderStore struct {
 	db *gorm.DB
 }
 // NewOrderStore 创建订单 Store
 func NewOrderStore(db *gorm.DB) *OrderStore {
 	return &OrderStore{db: db}
 }
 // Create 创建订单
 func (s *OrderStore) Create(ctx context.Context, order *model.Order) error {
 	return s.db.WithContext(ctx).Create(order).Error
 }
 // GetByID 根据 ID 获取订单
 func (s *OrderStore) GetByID(ctx context.Context, id uint) (*model.Order, error) {
 	var order model.Order
 	err := s.db.WithContext(ctx).First(&order, id).Error
 	if err != nil {
 		return nil, err
 	}
 	return &order, nil
 }
 // GetByOrderID 根据订单号获取订单
 func (s *OrderStore) GetByOrderID(ctx context.Context, orderID string) (*model.Order, error) {
 	var order model.Order
 	err := s.db.WithContext(ctx).Where("order_id = ?", orderID).First(&order).Error
 	if err != nil {
 		return nil, err
 	}
 	return &order, nil
 }
 // ListByUserID 根据用户 ID 分页获取订单列表
 func (s *OrderStore) ListByUserID(ctx context.Context, userID uint, page, pageSize int) ([]model.Order, int64, error) {
 	var orders []model.Order
 	var total int64
 	// 计算总数
 	if err := s.db.WithContext(ctx).Model(&model.Order{}).Where("user_id = ?", userID).Count(&total).Error; err != nil {
 		return nil, 0, err
 	}
 	// 分页查询
 	offset := (page - 1) * pageSize
 	err := s.db.WithContext(ctx).
 		Where("user_id = ?", userID).
 		Offset(offset).
 		Limit(pageSize).
 		Order("created_at DESC").
 		Find(&orders).Error
 	if err != nil {
 		return nil, 0, err
 	}
 	return orders, total, nil
 }
 // List 分页获取订单列表（全部订单）
 func (s *OrderStore) List(ctx context.Context, page, pageSize int) ([]model.Order, int64, error) {
 	var orders []model.Order
 	var total int64
 	// 计算总数
 	if err := s.db.WithContext(ctx).Model(&model.Order{}).Count(&total).Error; err != nil {
 		return nil, 0, err
 	}
 	// 分页查询
 	offset := (page - 1) * pageSize
 	err := s.db.WithContext(ctx).
 		Offset(offset).
 		Limit(pageSize).
 		Order("created_at DESC").
 		Find(&orders).Error
 	if err != nil {
 		return nil, 0, err
 	}
 	return orders, total, nil
 }
 // Update 更新订单
 func (s *OrderStore) Update(ctx context.Context, order *model.Order) error {
 	return s.db.WithContext(ctx).Save(order).Error
 }
 // Delete 软删除订单
 func (s *OrderStore) Delete(ctx context.Context, id uint) error {
 	return s.db.WithContext(ctx).Delete(&model.Order{}, id).Error
 }
--- a/internal/store/postgres/store.go
+++ b/internal/store/postgres/store.go
@@ -0,0 +1,53 @@
 package postgres
 import (
 	"context"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 // Store PostgreSQL 数据访问层整合结构
 type Store struct {
 	db     *gorm.DB
 	logger *zap.Logger
 	User  *UserStore
 	Order *OrderStore
 }
 // NewStore 创建新的 PostgreSQL Store 实例
 func NewStore(db *gorm.DB, logger *zap.Logger) *Store {
 	return &Store{
 		db:     db,
 		logger: logger,
 		User:   NewUserStore(db),
 		Order:  NewOrderStore(db),
 	}
 }
 // DB 获取数据库连接
 func (s *Store) DB() *gorm.DB {
 	return s.db
 }
 // Transaction 执行事务
 // 提供统一的事务管理接口，自动处理提交和回滚
 // 在事务内部，所有 Store 操作都会使用事务连接
 func (s *Store) Transaction(ctx context.Context, fn func(*Store) error) error {
 	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		// 创建事务内的 Store 实例
 		txStore := &Store{
 			db:     tx,
 			logger: s.logger,
 			User:   NewUserStore(tx),
 			Order:  NewOrderStore(tx),
 		}
 		return fn(txStore)
 	})
 }
 // WithContext 返回带上下文的数据库实例
 func (s *Store) WithContext(ctx context.Context) *gorm.DB {
 	return s.db.WithContext(ctx)
 }
--- a/internal/store/postgres/user_store.go
+++ b/internal/store/postgres/user_store.go
@@ -0,0 +1,78 @@
 package postgres
 import (
 	"context"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"gorm.io/gorm"
 )
 // UserStore 用户数据访问层
 type UserStore struct {
 	db *gorm.DB
 }
 // NewUserStore 创建用户 Store
 func NewUserStore(db *gorm.DB) *UserStore {
 	return &UserStore{db: db}
 }
 // Create 创建用户
 func (s *UserStore) Create(ctx context.Context, user *model.User) error {
 	return s.db.WithContext(ctx).Create(user).Error
 }
 // GetByID 根据 ID 获取用户
 func (s *UserStore) GetByID(ctx context.Context, id uint) (*model.User, error) {
 	var user model.User
 	err := s.db.WithContext(ctx).First(&user, id).Error
 	if err != nil {
 		return nil, err
 	}
 	return &user, nil
 }
 // GetByUsername 根据用户名获取用户
 func (s *UserStore) GetByUsername(ctx context.Context, username string) (*model.User, error) {
 	var user model.User
 	err := s.db.WithContext(ctx).Where("username = ?", username).First(&user).Error
 	if err != nil {
 		return nil, err
 	}
 	return &user, nil
 }
 // List 分页获取用户列表
 func (s *UserStore) List(ctx context.Context, page, pageSize int) ([]model.User, int64, error) {
 	var users []model.User
 	var total int64
 	// 计算总数
 	if err := s.db.WithContext(ctx).Model(&model.User{}).Count(&total).Error; err != nil {
 		return nil, 0, err
 	}
 	// 分页查询
 	offset := (page - 1) * pageSize
 	err := s.db.WithContext(ctx).
 		Offset(offset).
 		Limit(pageSize).
 		Order("created_at DESC").
 		Find(&users).Error
 	if err != nil {
 		return nil, 0, err
 	}
 	return users, total, nil
 }
 // Update 更新用户
 func (s *UserStore) Update(ctx context.Context, user *model.User) error {
 	return s.db.WithContext(ctx).Save(user).Error
 }
 // Delete 软删除用户
 func (s *UserStore) Delete(ctx context.Context, id uint) error {
 	return s.db.WithContext(ctx).Delete(&model.User{}, id).Error
 }
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -0,0 +1,35 @@
 package store
 import (
 	"context"
 	"gorm.io/gorm"
 )
 // Store 数据访问层基础结构
 type Store struct {
 	db *gorm.DB
 }
 // NewStore 创建新的 Store 实例
 func NewStore(db *gorm.DB) *Store {
 	return &Store{
 		db: db,
 	}
 }
 // DB 获取数据库连接
 func (s *Store) DB() *gorm.DB {
 	return s.db
 }
 // Transaction 执行事务
 // 提供统一的事务管理接口，自动处理提交和回滚
 func (s *Store) Transaction(ctx context.Context, fn func(*gorm.DB) error) error {
 	return s.db.WithContext(ctx).Transaction(fn)
 }
 // WithContext 返回带上下文的数据库实例
 func (s *Store) WithContext(ctx context.Context) *gorm.DB {
 	return s.db.WithContext(ctx)
 }
--- a/internal/task/email.go
+++ b/internal/task/email.go
@@ -0,0 +1,155 @@
 package task
 import (
 	"context"
 	"fmt"
 	"strings"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 // EmailPayload 邮件任务载荷
 type EmailPayload struct {
 	RequestID   string   `json:"request_id"`
 	To          string   `json:"to"`
 	Subject     string   `json:"subject"`
 	Body        string   `json:"body"`
 	CC          []string `json:"cc,omitempty"`
 	Attachments []string `json:"attachments,omitempty"`
 }
 // EmailHandler 邮件任务处理器
 type EmailHandler struct {
 	redis  *redis.Client
 	logger *zap.Logger
 }
 // NewEmailHandler 创建邮件任务处理器
 func NewEmailHandler(redis *redis.Client, logger *zap.Logger) *EmailHandler {
 	return &EmailHandler{
 		redis:  redis,
 		logger: logger,
 	}
 }
 // HandleEmailSend 处理邮件发送任务
 func (h *EmailHandler) HandleEmailSend(ctx context.Context, task *asynq.Task) error {
 	// 解析任务载荷
 	var payload EmailPayload
 	if err := sonic.Unmarshal(task.Payload(), &payload); err != nil {
 		h.logger.Error("解析邮件任务载荷失败",
 			zap.Error(err),
 			zap.String("task_id", task.ResultWriter().TaskID()),
 		)
 		return asynq.SkipRetry // JSON 解析失败不重试
 	}
 	// 验证载荷
 	if err := h.validatePayload(&payload); err != nil {
 		h.logger.Error("邮件任务载荷验证失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return asynq.SkipRetry // 参数错误不重试
 	}
 	// 幂等性检查：使用 Redis 锁
 	lockKey := constants.RedisTaskLockKey(payload.RequestID)
 	locked, err := h.acquireLock(ctx, lockKey)
 	if err != nil {
 		h.logger.Error("获取任务锁失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return err // 锁获取失败，可以重试
 	}
 	if !locked {
 		h.logger.Info("任务已执行，跳过（幂等性）",
 			zap.String("request_id", payload.RequestID),
 			zap.String("to", payload.To),
 		)
 		return nil // 已执行，跳过
 	}
 	// 记录任务开始执行
 	h.logger.Info("开始处理邮件发送任务",
 		zap.String("request_id", payload.RequestID),
 		zap.String("to", payload.To),
 		zap.String("subject", payload.Subject),
 		zap.Int("cc_count", len(payload.CC)),
 		zap.Int("attachments_count", len(payload.Attachments)),
 	)
 	// 执行邮件发送（模拟）
 	if err := h.sendEmail(ctx, &payload); err != nil {
 		h.logger.Error("邮件发送失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 			zap.String("to", payload.To),
 		)
 		return err // 发送失败，可以重试
 	}
 	// 记录任务完成
 	h.logger.Info("邮件发送成功",
 		zap.String("request_id", payload.RequestID),
 		zap.String("to", payload.To),
 	)
 	return nil
 }
 // validatePayload 验证邮件载荷
 func (h *EmailHandler) validatePayload(payload *EmailPayload) error {
 	if payload.RequestID == "" {
 		return fmt.Errorf("request_id 不能为空")
 	}
 	if payload.To == "" {
 		return fmt.Errorf("收件人不能为空")
 	}
 	if !strings.Contains(payload.To, "@") {
 		return fmt.Errorf("邮箱格式无效")
 	}
 	if payload.Subject == "" {
 		return fmt.Errorf("邮件主题不能为空")
 	}
 	if payload.Body == "" {
 		return fmt.Errorf("邮件正文不能为空")
 	}
 	return nil
 }
 // acquireLock 获取 Redis 锁（幂等性）
 func (h *EmailHandler) acquireLock(ctx context.Context, key string) (bool, error) {
 	// 使用 SetNX 实现分布式锁
 	// 过期时间 24 小时，防止锁永久存在
 	result, err := h.redis.SetNX(ctx, key, "1", 24*time.Hour).Result()
 	if err != nil {
 		return false, fmt.Errorf("设置 Redis 锁失败: %w", err)
 	}
 	return result, nil
 }
 // sendEmail 发送邮件（实际实现需要集成 SMTP 或邮件服务）
 func (h *EmailHandler) sendEmail(ctx context.Context, payload *EmailPayload) error {
 	// TODO: 实际实现中需要集成邮件发送服务
 	// 例如：使用 SMTP、SendGrid、AWS SES 等
 	// 模拟发送延迟
 	time.Sleep(100 * time.Millisecond)
 	// 这里仅作演示，实际应用中需要调用真实的邮件发送 API
 	h.logger.Debug("模拟邮件发送",
 		zap.String("to", payload.To),
 		zap.String("subject", payload.Subject),
 		zap.Int("body_length", len(payload.Body)),
 	)
 	return nil
 }
--- a/internal/task/sim.go
+++ b/internal/task/sim.go
@@ -0,0 +1,170 @@
 package task
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 // SIMStatusSyncPayload SIM 卡状态同步任务载荷
 type SIMStatusSyncPayload struct {
 	RequestID string   `json:"request_id"`
 	ICCIDs    []string `json:"iccids"`     // ICCID 列表
 	ForceSync bool     `json:"force_sync"` // 强制同步（忽略缓存）
 }
 // SIMHandler SIM 卡状态同步任务处理器
 type SIMHandler struct {
 	db     *gorm.DB
 	redis  *redis.Client
 	logger *zap.Logger
 }
 // NewSIMHandler 创建 SIM 卡状态同步任务处理器
 func NewSIMHandler(db *gorm.DB, redis *redis.Client, logger *zap.Logger) *SIMHandler {
 	return &SIMHandler{
 		db:     db,
 		redis:  redis,
 		logger: logger,
 	}
 }
 // HandleSIMStatusSync 处理 SIM 卡状态同步任务
 func (h *SIMHandler) HandleSIMStatusSync(ctx context.Context, task *asynq.Task) error {
 	// 解析任务载荷
 	var payload SIMStatusSyncPayload
 	if err := sonic.Unmarshal(task.Payload(), &payload); err != nil {
 		h.logger.Error("解析 SIM 状态同步任务载荷失败",
 			zap.Error(err),
 			zap.String("task_id", task.ResultWriter().TaskID()),
 		)
 		return asynq.SkipRetry
 	}
 	// 验证载荷
 	if err := h.validatePayload(&payload); err != nil {
 		h.logger.Error("SIM 状态同步任务载荷验证失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return asynq.SkipRetry
 	}
 	// 幂等性检查
 	lockKey := constants.RedisTaskLockKey(payload.RequestID)
 	locked, err := h.acquireLock(ctx, lockKey)
 	if err != nil {
 		h.logger.Error("获取任务锁失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return err
 	}
 	if !locked {
 		h.logger.Info("任务已执行，跳过（幂等性）",
 			zap.String("request_id", payload.RequestID),
 			zap.Int("iccid_count", len(payload.ICCIDs)),
 		)
 		return nil
 	}
 	// 记录任务开始
 	h.logger.Info("开始处理 SIM 卡状态同步任务",
 		zap.String("request_id", payload.RequestID),
 		zap.Int("iccid_count", len(payload.ICCIDs)),
 		zap.Bool("force_sync", payload.ForceSync),
 	)
 	// 执行状态同步
 	if err := h.syncSIMStatus(ctx, &payload); err != nil {
 		h.logger.Error("SIM 卡状态同步失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return err
 	}
 	// 记录任务完成
 	h.logger.Info("SIM 卡状态同步成功",
 		zap.String("request_id", payload.RequestID),
 		zap.Int("iccid_count", len(payload.ICCIDs)),
 	)
 	return nil
 }
 // validatePayload 验证 SIM 状态同步载荷
 func (h *SIMHandler) validatePayload(payload *SIMStatusSyncPayload) error {
 	if payload.RequestID == "" {
 		return fmt.Errorf("request_id 不能为空")
 	}
 	if len(payload.ICCIDs) == 0 {
 		return fmt.Errorf("iccids 不能为空")
 	}
 	if len(payload.ICCIDs) > 1000 {
 		return fmt.Errorf("单次同步 ICCID 数量不能超过 1000")
 	}
 	return nil
 }
 // acquireLock 获取 Redis 锁
 func (h *SIMHandler) acquireLock(ctx context.Context, key string) (bool, error) {
 	result, err := h.redis.SetNX(ctx, key, "1", 24*time.Hour).Result()
 	if err != nil {
 		return false, fmt.Errorf("设置 Redis 锁失败: %w", err)
 	}
 	return result, nil
 }
 // syncSIMStatus 执行 SIM 卡状态同步
 func (h *SIMHandler) syncSIMStatus(ctx context.Context, payload *SIMStatusSyncPayload) error {
 	// TODO: 实际实现中需要调用运营商 API 获取 SIM 卡状态
 	// 批量处理 ICCID
 	batchSize := 100
 	for i := 0; i < len(payload.ICCIDs); i += batchSize {
 		// 检查上下文是否已取消
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
 		default:
 		}
 		end := i + batchSize
 		if end > len(payload.ICCIDs) {
 			end = len(payload.ICCIDs)
 		}
 		batch := payload.ICCIDs[i:end]
 		h.logger.Debug("同步 SIM 卡状态批次",
 			zap.Int("batch_start", i),
 			zap.Int("batch_end", end),
 			zap.Int("batch_size", len(batch)),
 		)
 		// 模拟调用外部 API
 		time.Sleep(200 * time.Millisecond)
 		// TODO: 实际实现中需要：
 		// 1. 调用运营商 API 获取状态
 		// 2. 使用事务批量更新数据库
 		// 3. 更新 Redis 缓存
 		// 4. 记录同步日志
 	}
 	h.logger.Info("SIM 卡状态批量同步完成",
 		zap.Int("total_iccids", len(payload.ICCIDs)),
 		zap.Int("batch_size", batchSize),
 	)
 	return nil
 }
--- a/internal/task/sync.go
+++ b/internal/task/sync.go
@@ -0,0 +1,166 @@
 package task
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 // DataSyncPayload 数据同步任务载荷
 type DataSyncPayload struct {
 	RequestID string `json:"request_id"`
 	SyncType  string `json:"sync_type"`  // sim_status, flow_usage, real_name
 	StartDate string `json:"start_date"` // YYYY-MM-DD
 	EndDate   string `json:"end_date"`   // YYYY-MM-DD
 	BatchSize int    `json:"batch_size"` // 批量大小
 }
 // SyncHandler 数据同步任务处理器
 type SyncHandler struct {
 	db     *gorm.DB
 	logger *zap.Logger
 }
 // NewSyncHandler 创建数据同步任务处理器
 func NewSyncHandler(db *gorm.DB, logger *zap.Logger) *SyncHandler {
 	return &SyncHandler{
 		db:     db,
 		logger: logger,
 	}
 }
 // HandleDataSync 处理数据同步任务
 func (h *SyncHandler) HandleDataSync(ctx context.Context, task *asynq.Task) error {
 	// 解析任务载荷
 	var payload DataSyncPayload
 	if err := sonic.Unmarshal(task.Payload(), &payload); err != nil {
 		h.logger.Error("解析数据同步任务载荷失败",
 			zap.Error(err),
 			zap.String("task_id", task.ResultWriter().TaskID()),
 		)
 		return asynq.SkipRetry
 	}
 	// 验证载荷
 	if err := h.validatePayload(&payload); err != nil {
 		h.logger.Error("数据同步任务载荷验证失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 		)
 		return asynq.SkipRetry
 	}
 	// 设置默认批量大小
 	if payload.BatchSize <= 0 {
 		payload.BatchSize = 100
 	}
 	// 记录任务开始
 	h.logger.Info("开始处理数据同步任务",
 		zap.String("request_id", payload.RequestID),
 		zap.String("sync_type", payload.SyncType),
 		zap.String("start_date", payload.StartDate),
 		zap.String("end_date", payload.EndDate),
 		zap.Int("batch_size", payload.BatchSize),
 	)
 	// 执行数据同步
 	if err := h.syncData(ctx, &payload); err != nil {
 		h.logger.Error("数据同步失败",
 			zap.Error(err),
 			zap.String("request_id", payload.RequestID),
 			zap.String("sync_type", payload.SyncType),
 		)
 		return err // 同步失败，可以重试
 	}
 	// 记录任务完成
 	h.logger.Info("数据同步成功",
 		zap.String("request_id", payload.RequestID),
 		zap.String("sync_type", payload.SyncType),
 	)
 	return nil
 }
 // validatePayload 验证数据同步载荷
 func (h *SyncHandler) validatePayload(payload *DataSyncPayload) error {
 	if payload.RequestID == "" {
 		return fmt.Errorf("request_id 不能为空")
 	}
 	if payload.SyncType == "" {
 		return fmt.Errorf("sync_type 不能为空")
 	}
 	validTypes := []string{"sim_status", "flow_usage", "real_name"}
 	valid := false
 	for _, t := range validTypes {
 		if payload.SyncType == t {
 			valid = true
 			break
 		}
 	}
 	if !valid {
 		return fmt.Errorf("sync_type 无效，必须为 sim_status, flow_usage, real_name 之一")
 	}
 	if payload.StartDate == "" {
 		return fmt.Errorf("start_date 不能为空")
 	}
 	if payload.EndDate == "" {
 		return fmt.Errorf("end_date 不能为空")
 	}
 	return nil
 }
 // syncData 执行数据同步
 func (h *SyncHandler) syncData(ctx context.Context, payload *DataSyncPayload) error {
 	// TODO: 实际实现中需要调用外部 API 或数据源进行同步
 	// 模拟批量同步
 	totalRecords := 500 // 假设有 500 条记录需要同步
 	batches := (totalRecords + payload.BatchSize - 1) / payload.BatchSize
 	for i := 0; i < batches; i++ {
 		// 检查上下文是否已取消
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
 		default:
 		}
 		// 模拟批量处理
 		offset := i * payload.BatchSize
 		limit := payload.BatchSize
 		if offset+limit > totalRecords {
 			limit = totalRecords - offset
 		}
 		h.logger.Debug("同步批次",
 			zap.String("sync_type", payload.SyncType),
 			zap.Int("batch", i+1),
 			zap.Int("total_batches", batches),
 			zap.Int("offset", offset),
 			zap.Int("limit", limit),
 		)
 		// 模拟处理延迟
 		time.Sleep(200 * time.Millisecond)
 		// TODO: 实际实现中需要：
 		// 1. 从外部 API 获取数据
 		// 2. 使用事务批量更新数据库
 		// 3. 记录同步状态
 	}
 	h.logger.Info("批量同步完成",
 		zap.String("sync_type", payload.SyncType),
 		zap.Int("total_records", totalRecords),
 		zap.Int("batches", batches),
 	)
 	return nil
 }
--- a/migrations/000001_init_schema.down.sql
+++ b/migrations/000001_init_schema.down.sql
@@ -0,0 +1,9 @@
 -- migrations/000001_init_schema.down.sql
 -- 回滚初始化 Schema
 -- 删除表和索引
 -- 删除订单表
 DROP TABLE IF EXISTS tb_order;
 -- 删除用户表
 DROP TABLE IF EXISTS tb_user;
--- a/migrations/000001_init_schema.up.sql
+++ b/migrations/000001_init_schema.up.sql
@@ -0,0 +1,80 @@
 -- migrations/000001_init_schema.up.sql
 -- 初始化数据库 Schema
 -- 创建 tb_user 和 tb_order 表、索引
 -- 注意: 表关系和 updated_at 更新在代码中处理
 -- 用户表
 CREATE TABLE IF NOT EXISTS tb_user (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP,
    -- 基本信息
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    password VARCHAR(255) NOT NULL,
    -- 状态字段
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    -- 元数据
    last_login_at TIMESTAMP,
    -- 唯一约束
    CONSTRAINT uk_user_username UNIQUE (username),
    CONSTRAINT uk_user_email UNIQUE (email)
 );
 -- 用户表索引
 CREATE INDEX idx_user_deleted_at ON tb_user(deleted_at);
 CREATE INDEX idx_user_status ON tb_user(status);
 CREATE INDEX idx_user_created_at ON tb_user(created_at);
 -- 订单表
 CREATE TABLE IF NOT EXISTS tb_order (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP,
    -- 业务唯一键
    order_id VARCHAR(50) NOT NULL,
    -- 关联关系 (注意: 无数据库外键约束，在代码中管理)
    user_id INTEGER NOT NULL,
    -- 订单信息
    amount BIGINT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    remark VARCHAR(500),
    -- 时间字段
    paid_at TIMESTAMP,
    completed_at TIMESTAMP,
    -- 唯一约束
    CONSTRAINT uk_order_order_id UNIQUE (order_id)
 );
 -- 订单表索引
 CREATE INDEX idx_order_deleted_at ON tb_order(deleted_at);
 CREATE INDEX idx_order_user_id ON tb_order(user_id);
 CREATE INDEX idx_order_status ON tb_order(status);
 CREATE INDEX idx_order_created_at ON tb_order(created_at);
 CREATE INDEX idx_order_order_id ON tb_order(order_id);
 -- 添加注释
 COMMENT ON TABLE tb_user IS '用户表';
 COMMENT ON COLUMN tb_user.username IS '用户名（唯一）';
 COMMENT ON COLUMN tb_user.email IS '邮箱（唯一）';
 COMMENT ON COLUMN tb_user.password IS '密码（bcrypt 哈希）';
 COMMENT ON COLUMN tb_user.status IS '用户状态：active, inactive, suspended';
 COMMENT ON COLUMN tb_user.deleted_at IS '软删除时间';
 COMMENT ON TABLE tb_order IS '订单表';
 COMMENT ON COLUMN tb_order.order_id IS '订单号（业务唯一键）';
 COMMENT ON COLUMN tb_order.user_id IS '用户 ID（在代码中维护关联，无数据库外键）';
 COMMENT ON COLUMN tb_order.amount IS '金额（分）';
 COMMENT ON COLUMN tb_order.status IS '订单状态：pending, paid, processing, completed, cancelled';
 COMMENT ON COLUMN tb_order.deleted_at IS '软删除时间';
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -15,6 +15,8 @@ var globalConfig atomic.Pointer[Config]
 type Config struct {
 	Server     ServerConfig     `mapstructure:"server"`
 	Redis      RedisConfig      `mapstructure:"redis"`
 	Database   DatabaseConfig   `mapstructure:"database"`
 	Queue      QueueConfig      `mapstructure:"queue"`
 	Logging    LoggingConfig    `mapstructure:"logging"`
 	Middleware MiddlewareConfig `mapstructure:"middleware"`
 }
@@ -41,6 +43,27 @@ type RedisConfig struct {
 	WriteTimeout time.Duration `mapstructure:"write_timeout"`  // 例如 "3s"
 }
 // DatabaseConfig 数据库连接配置
 type DatabaseConfig struct {
 	Host            string        `mapstructure:"host"`              // 数据库主机地址
 	Port            int           `mapstructure:"port"`              // 数据库端口
 	User            string        `mapstructure:"user"`              // 数据库用户名
 	Password        string        `mapstructure:"password"`          // 数据库密码（明文存储）
 	DBName          string        `mapstructure:"dbname"`            // 数据库名称
 	SSLMode         string        `mapstructure:"sslmode"`           // SSL 模式：disable, require, verify-ca, verify-full
 	MaxOpenConns    int           `mapstructure:"max_open_conns"`    // 最大打开连接数（默认：25）
 	MaxIdleConns    int           `mapstructure:"max_idle_conns"`    // 最大空闲连接数（默认：10）
 	ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"` // 连接最大生命周期（默认：5m）
 }
 // QueueConfig 任务队列配置
 type QueueConfig struct {
 	Concurrency int            `mapstructure:"concurrency"` // Worker 并发数（默认：10）
 	Queues      map[string]int `mapstructure:"queues"`      // 队列优先级配置（队列名 -> 权重）
 	RetryMax    int            `mapstructure:"retry_max"`   // 最大重试次数（默认：5）
 	Timeout     time.Duration  `mapstructure:"timeout"`     // 任务超时时间（默认：10m）
 }
 // LoggingConfig 日志配置
 type LoggingConfig struct {
 	Level       string            `mapstructure:"level"`       // debug, info, warn, error
--- a/pkg/constants/constants.go
+++ b/pkg/constants/constants.go
@@ -1,5 +1,7 @@
 package constants
 import "time"
 // Fiber Locals 的上下文键
 const (
 	ContextKeyRequestID = "requestid"
@@ -19,3 +21,47 @@ const (
 	DefaultServerAddr = ":3000"
 	DefaultRedisAddr  = "localhost:6379"
 )
 // 数据库配置常量
 const (
 	DefaultMaxOpenConns    = 25
 	DefaultMaxIdleConns    = 10
 	DefaultConnMaxLifetime = 5 * time.Minute
 	DefaultPageSize        = 20
 	MaxPageSize            = 100
 	SlowQueryThreshold     = 100 * time.Millisecond
 )
 // 任务类型常量
 const (
 	TaskTypeEmailSend     = "email:send"           // 发送邮件
 	TaskTypeDataSync      = "data:sync"            // 数据同步
 	TaskTypeSIMStatusSync = "sim:status:sync"      // SIM 卡状态同步
 	TaskTypeCommission    = "commission:calculate" // 分佣计算
 )
 // 用户状态常量
 const (
 	UserStatusActive    = "active"    // 激活
 	UserStatusInactive  = "inactive"  // 未激活
 	UserStatusSuspended = "suspended" // 暂停
 )
 // 订单状态常量
 const (
 	OrderStatusPending    = "pending"    // 待支付
 	OrderStatusPaid       = "paid"       // 已支付
 	OrderStatusProcessing = "processing" // 处理中
 	OrderStatusCompleted  = "completed"  // 已完成
 	OrderStatusCancelled  = "cancelled"  // 已取消
 )
 // 队列配置常量
 const (
 	QueueCritical      = "critical" // 关键任务队列
 	QueueDefault       = "default"  // 默认队列
 	QueueLow           = "low"      // 低优先级队列
 	DefaultRetryMax    = 5
 	DefaultTimeout     = 10 * time.Minute
 	DefaultConcurrency = 10
 )
--- a/pkg/constants/redis.go
+++ b/pkg/constants/redis.go
@@ -11,3 +11,17 @@ func RedisAuthTokenKey(token string) string {
 func RedisRateLimitKey(ip string) string {
 	return fmt.Sprintf("ratelimit:%s", ip)
 }
 // RedisTaskLockKey 生成任务锁的 Redis 键
 // 用途：幂等性控制，防止重复执行
 // 过期时间：24 小时
 func RedisTaskLockKey(requestID string) string {
 	return fmt.Sprintf("task:lock:%s", requestID)
 }
 // RedisTaskStatusKey 生成任务状态的 Redis 键
 // 用途：存储任务执行状态
 // 过期时间：7 天
 func RedisTaskStatusKey(taskID string) string {
 	return fmt.Sprintf("task:status:%s", taskID)
 }
--- a/pkg/database/postgres.go
+++ b/pkg/database/postgres.go
@@ -0,0 +1,172 @@
 package database
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/break/junhong_cmp_fiber/pkg/config"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"go.uber.org/zap"
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
 )
 // InitPostgreSQL 初始化 PostgreSQL 数据库连接
 func InitPostgreSQL(cfg *config.DatabaseConfig, log *zap.Logger) (*gorm.DB, error) {
 	// 构建 DSN (数据源名称)
 	dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
 		cfg.Host,
 		cfg.Port,
 		cfg.User,
 		cfg.Password,
 		cfg.DBName,
 		cfg.SSLMode,
 	)
 	// 配置 GORM
 	gormConfig := &gorm.Config{
 		// 使用自定义日志器（集成 Zap）
 		Logger: newGormLogger(log),
 		// 禁用自动创建表（使用迁移脚本管理）
 		DisableAutomaticPing:   false,
 		SkipDefaultTransaction: true, // 提高性能，手动管理事务
 		PrepareStmt:            true, // 预编译语句
 	}
 	// 连接数据库
 	db, err := gorm.Open(postgres.Open(dsn), gormConfig)
 	if err != nil {
 		log.Error("PostgreSQL 连接失败",
 			zap.String("host", cfg.Host),
 			zap.Int("port", cfg.Port),
 			zap.String("dbname", cfg.DBName),
 			zap.Error(err))
 		return nil, fmt.Errorf("failed to connect to PostgreSQL: %w", err)
 	}
 	// 获取底层 SQL DB 对象
 	sqlDB, err := db.DB()
 	if err != nil {
 		log.Error("获取 SQL DB 失败", zap.Error(err))
 		return nil, fmt.Errorf("failed to get SQL DB: %w", err)
 	}
 	// 配置连接池
 	maxOpenConns := cfg.MaxOpenConns
 	if maxOpenConns <= 0 {
 		maxOpenConns = constants.DefaultMaxOpenConns
 	}
 	maxIdleConns := cfg.MaxIdleConns
 	if maxIdleConns <= 0 {
 		maxIdleConns = constants.DefaultMaxIdleConns
 	}
 	connMaxLifetime := cfg.ConnMaxLifetime
 	if connMaxLifetime <= 0 {
 		connMaxLifetime = constants.DefaultConnMaxLifetime
 	}
 	sqlDB.SetMaxOpenConns(maxOpenConns)
 	sqlDB.SetMaxIdleConns(maxIdleConns)
 	sqlDB.SetConnMaxLifetime(connMaxLifetime)
 	// 验证连接
 	if err := sqlDB.Ping(); err != nil {
 		log.Error("PostgreSQL Ping 失败", zap.Error(err))
 		return nil, fmt.Errorf("failed to ping PostgreSQL: %w", err)
 	}
 	log.Info("PostgreSQL 连接成功",
 		zap.String("host", cfg.Host),
 		zap.Int("port", cfg.Port),
 		zap.String("dbname", cfg.DBName),
 		zap.Int("max_open_conns", maxOpenConns),
 		zap.Int("max_idle_conns", maxIdleConns),
 		zap.Duration("conn_max_lifetime", connMaxLifetime))
 	return db, nil
 }
 // gormLogger 自定义 GORM 日志器，集成 Zap
 type gormLogger struct {
 	zap                  *zap.Logger
 	slowQueryThreshold   time.Duration
 	ignoreRecordNotFound bool
 	logLevel             logger.LogLevel
 }
 // newGormLogger 创建新的 GORM 日志器
 func newGormLogger(log *zap.Logger) logger.Interface {
 	return &gormLogger{
 		zap:                  log,
 		slowQueryThreshold:   constants.SlowQueryThreshold,
 		ignoreRecordNotFound: true,
 		logLevel:             logger.Info,
 	}
 }
 // LogMode 设置日志级别
 func (l *gormLogger) LogMode(level logger.LogLevel) logger.Interface {
 	newLogger := *l
 	newLogger.logLevel = level
 	return &newLogger
 }
 // Info 记录 Info 级别日志
 func (l *gormLogger) Info(ctx context.Context, msg string, data ...interface{}) {
 	if l.logLevel >= logger.Info {
 		l.zap.Sugar().Infof(msg, data...)
 	}
 }
 // Warn 记录 Warn 级别日志
 func (l *gormLogger) Warn(ctx context.Context, msg string, data ...interface{}) {
 	if l.logLevel >= logger.Warn {
 		l.zap.Sugar().Warnf(msg, data...)
 	}
 }
 // Error 记录 Error 级别日志
 func (l *gormLogger) Error(ctx context.Context, msg string, data ...interface{}) {
 	if l.logLevel >= logger.Error {
 		l.zap.Sugar().Errorf(msg, data...)
 	}
 }
 // Trace 记录 SQL 查询日志
 func (l *gormLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error) {
 	if l.logLevel <= logger.Silent {
 		return
 	}
 	elapsed := time.Since(begin)
 	sql, rows := fc()
 	switch {
 	case err != nil && l.logLevel >= logger.Error && (!l.ignoreRecordNotFound || err != gorm.ErrRecordNotFound):
 		// 查询错误
 		l.zap.Error("SQL 查询失败",
 			zap.String("sql", sql),
 			zap.Int64("rows", rows),
 			zap.Duration("elapsed", elapsed),
 			zap.Error(err))
 	case elapsed > l.slowQueryThreshold && l.logLevel >= logger.Warn:
 		// 慢查询
 		l.zap.Warn("慢查询检测",
 			zap.String("sql", sql),
 			zap.Int64("rows", rows),
 			zap.Duration("elapsed", elapsed),
 			zap.Duration("threshold", l.slowQueryThreshold))
 	case l.logLevel >= logger.Info:
 		// 正常查询
 		l.zap.Debug("SQL 查询",
 			zap.String("sql", sql),
 			zap.Int64("rows", rows),
 			zap.Duration("elapsed", elapsed))
 	}
 }
--- a/pkg/errors/codes.go
+++ b/pkg/errors/codes.go
@@ -8,6 +8,10 @@ const (
 	CodeInvalidToken           = 1002 // 令牌无效或已过期
 	CodeTooManyRequests        = 1003 // 请求过于频繁（限流）
 	CodeAuthServiceUnavailable = 1004 // 认证服务不可用（Redis 宕机）
 	CodeNotFound               = 1005 // 资源不存在
 	CodeBadRequest             = 1006 // 请求参数错误
 	CodeUnauthorized           = 1007 // 未授权
 	CodeForbidden              = 1008 // 禁止访问
 )
 // ErrorMessage 表示双语错误消息
@@ -24,6 +28,10 @@ var errorMessages = map[int]ErrorMessage{
 	CodeInvalidToken:           {"Invalid or expired token", "令牌无效或已过期"},
 	CodeTooManyRequests:        {"Too many requests", "请求过于频繁"},
 	CodeAuthServiceUnavailable: {"Authentication service unavailable", "认证服务不可用"},
 	CodeNotFound:               {"Resource not found", "资源不存在"},
 	CodeBadRequest:             {"Bad request", "请求参数错误"},
 	CodeUnauthorized:           {"Unauthorized", "未授权"},
 	CodeForbidden:              {"Forbidden", "禁止访问"},
 }
 // GetMessage 根据错误码和语言返回错误消息
--- a/pkg/queue/client.go
+++ b/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,
 	}
 }
--- a/pkg/queue/handler.go
+++ b/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
 }
--- a/pkg/queue/server.go
+++ b/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
 }
--- a/pkg/response/response_test.go
+++ b/pkg/response/response_test.go
@@ -1,13 +1,13 @@
 package response
 import (
 	"encoding/json"
 	"io"
 	"net/http/httptest"
 	"testing"
 	"time"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/bytedance/sonic"
 	"github.com/gofiber/fiber/v2"
 )
@@ -83,7 +83,7 @@ func TestSuccess(t *testing.T) {
 			}
 			var response Response
-			if err := json.Unmarshal(body, &response); err != nil {
+			if err := sonic.Unmarshal(body, &response); err != nil {
 				t.Fatalf("Failed to unmarshal response: %v", err)
 			}
@@ -188,7 +188,7 @@ func TestError(t *testing.T) {
 			}
 			var response Response
-			if err := json.Unmarshal(body, &response); err != nil {
+			if err := sonic.Unmarshal(body, &response); err != nil {
 				t.Fatalf("Failed to unmarshal response: %v", err)
 			}
@@ -272,7 +272,7 @@ func TestSuccessWithMessage(t *testing.T) {
 			}
 			var response Response
-			if err := json.Unmarshal(body, &response); err != nil {
+			if err := sonic.Unmarshal(body, &response); err != nil {
 				t.Fatalf("Failed to unmarshal response: %v", err)
 			}
@@ -337,14 +337,14 @@ func TestResponseSerialization(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			// 序列化
-			data, err := json.Marshal(tt.response)
+			data, err := sonic.Marshal(tt.response)
 			if err != nil {
 				t.Fatalf("Failed to marshal response: %v", err)
 			}
 			// 反序列化
 			var deserialized Response
-			if err := json.Unmarshal(data, &deserialized); err != nil {
+			if err := sonic.Unmarshal(data, &deserialized); err != nil {
 				t.Fatalf("Failed to unmarshal response: %v", err)
 			}
@@ -373,14 +373,14 @@ func TestResponseStructFields(t *testing.T) {
 		Timestamp: time.Now().Format(time.RFC3339),
 	}
-	data, err := json.Marshal(response)
+	data, err := sonic.Marshal(response)
 	if err != nil {
 		t.Fatalf("Failed to marshal response: %v", err)
 	}
 	// 解析为 map 以检查 JSON 键
 	var jsonMap map[string]any
-	if err := json.Unmarshal(data, &jsonMap); err != nil {
+	if err := sonic.Unmarshal(data, &jsonMap); err != nil {
 		t.Fatalf("Failed to unmarshal to map: %v", err)
 	}
@@ -431,7 +431,7 @@ func TestMultipleResponses(t *testing.T) {
 		resp.Body.Close()
 		var response Response
-		if err := json.Unmarshal(body, &response); err != nil {
+		if err := sonic.Unmarshal(body, &response); err != nil {
 			t.Fatalf("Request %d: failed to unmarshal response: %v", i, err)
 		}
@@ -458,7 +458,7 @@ func TestTimestampFormat(t *testing.T) {
 	body, _ := io.ReadAll(resp.Body)
 	var response Response
-	if err := json.Unmarshal(body, &response); err != nil {
+	if err := sonic.Unmarshal(body, &response); err != nil {
 		t.Fatalf("Failed to unmarshal response: %v", err)
 	}
--- a/scripts/migrate.sh
+++ b/scripts/migrate.sh
@@ -0,0 +1,117 @@
 #!/bin/bash
 # 数据库迁移脚本
 # 用法: ./scripts/migrate.sh [up|down|create|version|force] [args]
 set -e
 # 加载 .env 文件 (如果存在)
 if [ -f .env ]; then
    echo "正在加载 .env 文件..."
    export $(grep -v '^#' .env | xargs)
 fi
 # 默认配置
 MIGRATIONS_DIR="${MIGRATIONS_DIR:-migrations}"
 DB_HOST="${DB_HOST:-localhost}"
 DB_PORT="${DB_PORT:-5432}"
 DB_USER="${DB_USER:-postgres}"
 DB_PASSWORD="${DB_PASSWORD:-password}"
 DB_NAME="${DB_NAME:-junhong_cmp}"
 DB_SSLMODE="${DB_SSLMODE:-disable}"
 # 构建数据库 URL
 DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}"
 # 检查 migrate 命令是否存在
 if ! command -v migrate &> /dev/null; then
    echo "错误: migrate 命令未找到"
    echo "请安装 golang-migrate:"
    echo "  brew install golang-migrate (macOS)"
    echo "  或访问 https://github.com/golang-migrate/migrate/tree/master/cmd/migrate#installation"
    exit 1
 fi
 # 显示使用说明
 show_usage() {
    cat << EOF
 用法: $0 [命令] [参数]
 命令:
  up [N]       向上迁移 N 步 (默认: 全部)
  down [N]     向下回滚 N 步 (默认: 1)
  create NAME  创建新的迁移文件
  version      显示当前迁移版本
  force V      强制设置迁移版本为 V (用于修复脏数据库状态)
  help         显示此帮助信息
 环境变量:
  DB_HOST      数据库主机 (默认: localhost)
  DB_PORT      数据库端口 (默认: 5432)
  DB_USER      数据库用户 (默认: postgres)
  DB_PASSWORD  数据库密码 (默认: password)
  DB_NAME      数据库名称 (默认: junhong_cmp)
  DB_SSLMODE   SSL 模式 (默认: disable)
 示例:
  $0 up              # 应用所有迁移
  $0 down 1          # 回滚最后一次迁移
  $0 create add_sim_table  # 创建新迁移文件
  $0 version         # 查看当前版本
  $0 force 1         # 强制设置版本为 1
 EOF
 }
 # 主命令处理
 case "$1" in
    up)
        if [ -z "$2" ]; then
            echo "正在应用所有迁移..."
            migrate -path "$MIGRATIONS_DIR" -database "$DATABASE_URL" up
        else
            echo "正在向上迁移 $2 步..."
            migrate -path "$MIGRATIONS_DIR" -database "$DATABASE_URL" up "$2"
        fi
        ;;
    down)
        STEPS="${2:-1}"
        echo "正在向下回滚 $STEPS 步..."
        migrate -path "$MIGRATIONS_DIR" -database "$DATABASE_URL" down "$STEPS"
        ;;
    create)
        if [ -z "$2" ]; then
            echo "错误: 请提供迁移文件名称"
            echo "用法: $0 create <name>"
            exit 1
        fi
        echo "创建迁移文件: $2"
        migrate create -ext sql -dir "$MIGRATIONS_DIR" -seq "$2"
        echo "迁移文件创建成功:"
        ls -lt "$MIGRATIONS_DIR" | head -3
        ;;
    version)
        echo "当前迁移版本:"
        migrate -path "$MIGRATIONS_DIR" -database "$DATABASE_URL" version
        ;;
    force)
        if [ -z "$2" ]; then
            echo "错误: 请提供版本号"
            echo "用法: $0 force <version>"
            exit 1
        fi
        echo "强制设置迁移版本为: $2"
        migrate -path "$MIGRATIONS_DIR" -database "$DATABASE_URL" force "$2"
        ;;
    help|--help|-h)
        show_usage
        ;;
    *)
        echo "错误: 未知命令 '$1'"
        echo ""
        show_usage
        exit 1
        ;;
 esac
 echo "✓ 迁移操作完成"
--- a/specs/002-gorm-postgres-asynq/checklists/requirements.md
+++ b/specs/002-gorm-postgres-asynq/checklists/requirements.md
@@ -0,0 +1,41 @@
 # Specification Quality Checklist: 数据持久化与异步任务处理集成
 **Purpose**: 在进入规划阶段前验证规格说明的完整性和质量
 **Created**: 2025-11-12
 **Feature**: [spec.md](../spec.md)
 ## Content Quality
 - [x] 无实现细节(语言、框架、API)
 - [x] 专注于用户价值和业务需求
 - [x] 为非技术干系人编写
 - [x] 所有必填部分已完成
 ## Requirement Completeness
 - [x] 无[NEEDS CLARIFICATION]标记残留
 - [x] 需求可测试且无歧义
 - [x] 成功标准可衡量
 - [x] 成功标准技术无关(无实现细节)
 - [x] 所有验收场景已定义
 - [x] 边界情况已识别
 - [x] 范围边界清晰
 - [x] 依赖和假设已识别
 ## Feature Readiness
 - [x] 所有功能需求都有清晰的验收标准
 - [x] 用户场景涵盖主要流程
 - [x] 功能满足成功标准中定义的可衡量结果
 - [x] 无实现细节泄漏到规格说明中
 ## Notes
 所有检查项均已通过。规格说明完整且质量良好,可以进入下一阶段(`/speckit.clarify`或`/speckit.plan`)。
 规格说明的主要优势:
 - 用户故事按优先级清晰排序(P1核心数据持久化 → P2异步任务 → P3监控)
 - 功能需求详细且可测试,涵盖了GORM、PostgreSQL和Asynq的核心能力
 - 成功标准具体可衡量,包含响应时间、并发能力、可靠性等关键指标
 - 边界情况考虑周全,包括连接池耗尽、死锁、主从切换等场景
 - 技术需求完全遵循项目宪章(Constitution),确保架构一致性
--- a/specs/002-gorm-postgres-asynq/contracts/api.yaml
+++ b/specs/002-gorm-postgres-asynq/contracts/api.yaml
@@ -0,0 +1,733 @@
 openapi: 3.0.3
 info:
  title: 数据持久化与异步任务处理集成 API
  description: |
    GORM + PostgreSQL + Asynq 集成的数据持久化和异步任务处理功能 API 规范
    **Feature**: 002-gorm-postgres-asynq
    **Date**: 2025-11-12
    ## 核心功能
    - 数据库连接管理和健康检查
    - 异步任务提交和管理
    - 数据 CRUD 操作（示例：用户管理）
    ## 技术栈
    - Fiber (HTTP 框架)
    - GORM (ORM)
    - PostgreSQL (数据库)
    - Asynq (任务队列)
    - Redis (任务队列存储)
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
 servers:
  - url: http://localhost:8080/api/v1
    description: 开发环境
  - url: http://staging.example.com/api/v1
    description: 预发布环境
  - url: https://api.example.com/api/v1
    description: 生产环境
 tags:
  - name: Health
    description: 健康检查和系统状态
  - name: Users
    description: 用户管理（数据库操作示例）
  - name: Tasks
    description: 异步任务管理
 paths:
  /health:
    get:
      tags:
        - Health
      summary: 健康检查
      description: |
        检查系统健康状态，包括数据库连接和 Redis 连接
        **测试用例**:
        - FR-011: 系统必须提供健康检查接口
        - SC-010: 健康检查应在 1 秒内返回
      operationId: healthCheck
      responses:
        '200':
          description: 系统健康
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [ok]
                    description: 系统整体状态
                  postgres:
                    type: string
                    enum: [up, down]
                    description: PostgreSQL 连接状态
                  redis:
                    type: string
                    enum: [up, down]
                    description: Redis 连接状态
                example:
                  status: ok
                  postgres: up
                  redis: up
        '503':
          description: 服务降级或不可用
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [degraded, unavailable]
                  postgres:
                    type: string
                    enum: [up, down]
                  redis:
                    type: string
                    enum: [up, down]
                  error:
                    type: string
                    description: 错误详情
                example:
                  status: degraded
                  postgres: down
                  redis: up
                  error: "数据库连接失败"
  /users:
    post:
      tags:
        - Users
      summary: 创建用户
      description: |
        创建新用户（演示数据库 CRUD 操作）
        **测试用例**:
        - FR-002: 支持标准 CRUD 操作
        - FR-003: 支持数据库事务
        - User Story 1 - Acceptance 1: 数据持久化
      operationId: createUser
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '200':
          description: 用户创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
        - Users
      summary: 用户列表
      description: |
        分页查询用户列表
        **测试用例**:
        - FR-002: 支持分页列表查询
        - FR-005: 支持条件查询、分页、排序
        - User Story 1 - Acceptance 5: 分页和排序
      operationId: listUsers
      security:
        - TokenAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: 页码
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: 每页条数（最大 100）
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive, suspended]
          description: 用户状态过滤
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ListUsersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{id}:
    get:
      tags:
        - Users
      summary: 获取用户详情
      description: |
        根据用户 ID 获取详细信息
        **测试用例**:
        - FR-002: 支持按 ID 查询
        - User Story 1 - Acceptance 1: 数据检索
      operationId: getUserById
      security:
        - TokenAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: 用户 ID
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - Users
      summary: 更新用户
      description: |
        更新用户信息
        **测试用例**:
        - FR-002: 支持更新操作
        - User Story 1 - Acceptance 2: 数据更新
      operationId: updateUser
      security:
        - TokenAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: 用户 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Users
      summary: 删除用户
      description: |
        软删除用户（设置 deleted_at 字段）
        **测试用例**:
        - FR-002: 支持软删除操作
        - User Story 1 - Acceptance 3: 数据删除
      operationId: deleteUser
      security:
        - TokenAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: 用户 ID
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /tasks/email:
    post:
      tags:
        - Tasks
      summary: 提交邮件发送任务
      description: |
        将邮件发送任务提交到异步队列
        **测试用例**:
        - FR-006: 提交任务到异步队列
        - FR-008: 任务重试机制
        - User Story 2 - Acceptance 1: 任务提交
      operationId: submitEmailTask
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTaskRequest'
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TaskResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /tasks/sync:
    post:
      tags:
        - Tasks
      summary: 提交数据同步任务
      description: |
        将数据同步任务提交到异步队列（支持优先级）
        **测试用例**:
        - FR-006: 提交任务到异步队列
        - FR-009: 任务优先级支持
        - User Story 2 - Acceptance 1: 任务提交
      operationId: submitSyncTask
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncTaskRequest'
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TaskResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
 components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: token
      description: 认证令牌
  schemas:
    # 通用响应
    SuccessResponse:
      type: object
      required:
        - code
        - msg
        - timestamp
      properties:
        code:
          type: integer
          enum: [0]
          description: 响应码（0 表示成功）
        msg:
          type: string
          example: success
          description: 响应消息
        data:
          type: object
          description: 响应数据（具体结构由各端点定义）
        timestamp:
          type: string
          format: date-time
          example: "2025-11-12T16:00:00+08:00"
          description: 响应时间戳（ISO 8601 格式）
    ErrorResponse:
      type: object
      required:
        - code
        - msg
        - timestamp
      properties:
        code:
          type: integer
          description: 错误码（非 0）
          example: 1001
        msg:
          type: string
          description: 错误消息（中文）
          example: "参数验证失败"
        data:
          type: object
          nullable: true
          description: 错误详情（可选）
        timestamp:
          type: string
          format: date-time
          example: "2025-11-12T16:00:00+08:00"
    # 用户相关
    CreateUserRequest:
      type: object
      required:
        - username
        - email
        - password
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 50
          pattern: '^[a-zA-Z0-9_]+$'
          description: 用户名（3-50 个字母数字下划线）
          example: testuser
        email:
          type: string
          format: email
          maxLength: 100
          description: 邮箱地址
          example: test@example.com
        password:
          type: string
          format: password
          minLength: 8
          description: 密码（至少 8 个字符）
          example: password123
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          maxLength: 100
          description: 邮箱地址
          example: newemail@example.com
        status:
          type: string
          enum: [active, inactive, suspended]
          description: 用户状态
    UserResponse:
      type: object
      required:
        - id
        - username
        - email
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: integer
          description: 用户 ID
          example: 1
        username:
          type: string
          description: 用户名
          example: testuser
        email:
          type: string
          description: 邮箱地址
          example: test@example.com
        status:
          type: string
          enum: [active, inactive, suspended]
          description: 用户状态
          example: active
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2025-11-12T16:00:00+08:00"
        updated_at:
          type: string
          format: date-time
          description: 更新时间
          example: "2025-11-12T16:00:00+08:00"
        last_login_at:
          type: string
          format: date-time
          nullable: true
          description: 最后登录时间
          example: "2025-11-12T16:30:00+08:00"
    ListUsersResponse:
      type: object
      required:
        - users
        - page
        - page_size
        - total
        - total_pages
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserResponse'
          description: 用户列表
        page:
          type: integer
          description: 当前页码
          example: 1
        page_size:
          type: integer
          description: 每页条数
          example: 20
        total:
          type: integer
          format: int64
          description: 总记录数
          example: 100
        total_pages:
          type: integer
          description: 总页数
          example: 5
    # 任务相关
    EmailTaskRequest:
      type: object
      required:
        - to
        - subject
        - body
      properties:
        to:
          type: string
          format: email
          description: 收件人邮箱
          example: user@example.com
        subject:
          type: string
          maxLength: 200
          description: 邮件主题
          example: Welcome to our service
        body:
          type: string
          description: 邮件正文
          example: Thank you for signing up!
        cc:
          type: array
          items:
            type: string
            format: email
          description: 抄送列表
          example: ["manager@example.com"]
        priority:
          type: string
          enum: [critical, default, low]
          default: default
          description: 任务优先级
    SyncTaskRequest:
      type: object
      required:
        - sync_type
        - start_date
        - end_date
      properties:
        sync_type:
          type: string
          enum: [sim_status, flow_usage, real_name]
          description: 同步类型
          example: sim_status
        start_date:
          type: string
          format: date
          pattern: '^\d{4}-\d{2}-\d{2}$'
          description: 开始日期（YYYY-MM-DD）
          example: "2025-11-01"
        end_date:
          type: string
          format: date
          pattern: '^\d{4}-\d{2}-\d{2}$'
          description: 结束日期（YYYY-MM-DD）
          example: "2025-11-12"
        batch_size:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
          description: 批量大小
        priority:
          type: string
          enum: [critical, default, low]
          default: default
          description: 任务优先级
    TaskResponse:
      type: object
      required:
        - task_id
        - queue
      properties:
        task_id:
          type: string
          format: uuid
          description: 任务唯一 ID
          example: "550e8400-e29b-41d4-a716-446655440000"
        queue:
          type: string
          enum: [critical, default, low]
          description: 任务所在队列
          example: default
        estimated_time:
          type: string
          description: 预计执行时间
          example: "within 5 minutes"
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 1001
            msg: "参数验证失败"
            data: null
            timestamp: "2025-11-12T16:00:00+08:00"
    Unauthorized:
      description: 未授权或令牌无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 1002
            msg: "缺失认证令牌"
            data: null
            timestamp: "2025-11-12T16:00:00+08:00"
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 1003
            msg: "用户不存在"
            data: null
            timestamp: "2025-11-12T16:00:00+08:00"
    Conflict:
      description: 资源冲突（如用户名已存在）
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 1004
            msg: "用户名已存在"
            data: null
            timestamp: "2025-11-12T16:00:00+08:00"
    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 5000
            msg: "服务器内部错误"
            data: null
            timestamp: "2025-11-12T16:00:00+08:00"
--- a/specs/002-gorm-postgres-asynq/data-model.md
+++ b/specs/002-gorm-postgres-asynq/data-model.md
@@ -0,0 +1,644 @@
 # Data Model: 数据持久化与异步任务处理集成
 **Feature**: 002-gorm-postgres-asynq  
 **Date**: 2025-11-12  
 **Purpose**: 定义数据模型、配置结构和系统实体
 ## 概述
 本文档定义了数据持久化和异步任务处理功能的数据模型，包括配置结构、数据库实体示例和任务载荷结构。
 ---
 ## 1. 配置模型
 ### 1.1 数据库配置
 ```go
 // pkg/config/config.go
 // DatabaseConfig 数据库连接配置
 type DatabaseConfig struct {
    // 连接参数
    Host     string `mapstructure:"host"`     // 数据库主机地址
    Port     int    `mapstructure:"port"`     // 数据库端口
    User     string `mapstructure:"user"`     // 数据库用户名
    Password string `mapstructure:"password"` // 数据库密码（明文存储）
    DBName   string `mapstructure:"dbname"`   // 数据库名称
    SSLMode  string `mapstructure:"sslmode"`  // SSL 模式：disable, require, verify-ca, verify-full
    // 连接池配置
    MaxOpenConns    int           `mapstructure:"max_open_conns"`    // 最大打开连接数（默认：25）
    MaxIdleConns    int           `mapstructure:"max_idle_conns"`    // 最大空闲连接数（默认：10）
    ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"` // 连接最大生命周期（默认：5m）
 }
 ```
 **字段说明**：
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | Host | string | localhost | PostgreSQL 服务器地址 |
 | Port | int | 5432 | PostgreSQL 服务器端口 |
 | User | string | postgres | 数据库用户名 |
 | Password | string | - | 数据库密码（明文存储在配置文件中） |
 | DBName | string | junhong_cmp | 数据库名称 |
 | SSLMode | string | disable | SSL 连接模式 |
 | MaxOpenConns | int | 25 | 最大数据库连接数 |
 | MaxIdleConns | int | 10 | 最大空闲连接数 |
 | ConnMaxLifetime | duration | 5m | 连接最大存活时间 |
 ### 1.2 任务队列配置
 ```go
 // pkg/config/config.go
 // QueueConfig 任务队列配置
 type QueueConfig struct {
    // 并发配置
    Concurrency int `mapstructure:"concurrency"` // Worker 并发数（默认：10）
    // 队列优先级配置（队列名 -> 权重）
    Queues map[string]int `mapstructure:"queues"` // 例如：{"critical": 6, "default": 3, "low": 1}
    // 重试配置
    RetryMax int           `mapstructure:"retry_max"` // 最大重试次数（默认：5）
    Timeout  time.Duration `mapstructure:"timeout"`   // 任务超时时间（默认：10m）
 }
 ```
 **队列优先级**：
 - `critical`: 关键任务（权重 6，约 60% 处理时间）
 - `default`: 普通任务（权重 3，约 30% 处理时间）
 - `low`: 低优先级任务（权重 1，约 10% 处理时间）
 ### 1.3 完整配置结构
 ```go
 // pkg/config/config.go
 // Config 应用配置
 type Config struct {
    Server     ServerConfig     `mapstructure:"server"`
    Logging    LoggingConfig    `mapstructure:"logging"`
    Redis      RedisConfig      `mapstructure:"redis"`
    Database   DatabaseConfig   `mapstructure:"database"`   // 新增
    Queue      QueueConfig      `mapstructure:"queue"`      // 新增
    Middleware MiddlewareConfig `mapstructure:"middleware"`
 }
 ```
 ---
 ## 2. 数据库实体模型
 ### 2.1 基础模型（Base Model）
 ```go
 // internal/model/base.go
 import (
    "time"
    "gorm.io/gorm"
 )
 // BaseModel 基础模型，包含通用字段
 type BaseModel struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` // 软删除
 }
 ```
 **字段说明**：
 - `ID`: 自增主键
 - `CreatedAt`: 创建时间（GORM 自动管理）
 - `UpdatedAt`: 更新时间（GORM 自动管理）
 - `DeletedAt`: 删除时间（软删除，GORM 自动过滤已删除记录）
 ### 2.2 示例实体：用户模型
 ```go
 // internal/model/user.go
 // User 用户实体
 type User struct {
    BaseModel
    // 基本信息
    Username string `gorm:"uniqueIndex;not null;size:50" json:"username"`
    Email    string `gorm:"uniqueIndex;not null;size:100" json:"email"`
    Password string `gorm:"not null;size:255" json:"-"` // 不返回给客户端
    // 状态字段
    Status string `gorm:"not null;size:20;default:'active';index" json:"status"`
    // 元数据
    LastLoginAt *time.Time `json:"last_login_at,omitempty"`
 }
 // TableName 指定表名
 func (User) TableName() string {
    return "tb_user"
 }
 ```
 **索引策略**：
 - `username`: 唯一索引（快速查找和去重）
 - `email`: 唯一索引（快速查找和去重）
 - `status`: 普通索引（状态过滤查询）
 - `deleted_at`: 自动索引（软删除过滤）
 **验证规则**：
 - `username`: 长度 3-50 字符，字母数字下划线
 - `email`: 标准邮箱格式
 - `password`: 长度 >= 8 字符，bcrypt 哈希存储
 - `status`: 枚举值（active, inactive, suspended）
 ### 2.3 示例实体：订单模型（演示手动关联关系）
 ```go
 // internal/model/order.go
 // Order 订单实体
 type Order struct {
    BaseModel
    // 业务唯一键
    OrderID string `gorm:"uniqueIndex;not null;size:50" json:"order_id"`
    // 关联关系（仅存储 ID，不使用 GORM 关联）
    UserID uint `gorm:"not null;index" json:"user_id"`
    // 订单信息
    Amount int64  `gorm:"not null" json:"amount"`           // 金额（分）
    Status string `gorm:"not null;size:20;index" json:"status"`
    Remark string `gorm:"size:500" json:"remark,omitempty"`
    // 时间字段
    PaidAt      *time.Time `json:"paid_at,omitempty"`
    CompletedAt *time.Time `json:"completed_at,omitempty"`
 }
 // TableName 指定表名
 func (Order) TableName() string {
    return "tb_order"
 }
 ```
 **关联关系说明**：
 - `UserID`: 存储关联用户的 ID（普通字段，无数据库外键约束）
 - **无 ORM 关联**：遵循 Constitution Principle IX，不使用 `foreignKey`、`belongsTo` 等标签
 - 关联数据查询在 Service 层手动实现（见下方示例）
 **手动查询关联数据示例**：
 ```go
 // internal/service/order/service.go
 // GetOrderWithUser 查询订单及关联的用户信息
 func (s *Service) GetOrderWithUser(ctx context.Context, orderID uint) (*OrderDetail, error) {
    // 1. 查询订单
    order, err := s.store.Order.GetByID(ctx, orderID)
    if err != nil {
        return nil, fmt.Errorf("查询订单失败: %w", err)
    }
    // 2. 手动查询关联的用户
    user, err := s.store.User.GetByID(ctx, order.UserID)
    if err != nil {
        return nil, fmt.Errorf("查询用户失败: %w", err)
    }
    // 3. 组装返回数据
    return &OrderDetail{
        Order: order,
        User:  user,
    }, nil
 }
 // ListOrdersByUserID 查询指定用户的订单列表
 func (s *Service) ListOrdersByUserID(ctx context.Context, userID uint, page, pageSize int) ([]*Order, int64, error) {
    return s.store.Order.ListByUserID(ctx, userID, page, pageSize)
 }
 ```
 **状态流转**：
 ```
 pending → paid → processing → completed
                      ↓
                  cancelled
 ```
 ---
 ## 3. 数据传输对象（DTO）
 ### 3.1 用户 DTO
 ```go
 // internal/model/user_dto.go
 // CreateUserRequest 创建用户请求
 type CreateUserRequest struct {
    Username string `json:"username" validate:"required,min=3,max=50,alphanum"`
    Email    string `json:"email" validate:"required,email"`
    Password string `json:"password" validate:"required,min=8"`
 }
 // UpdateUserRequest 更新用户请求
 type UpdateUserRequest struct {
    Email  *string `json:"email" validate:"omitempty,email"`
    Status *string `json:"status" validate:"omitempty,oneof=active inactive suspended"`
 }
 // UserResponse 用户响应
 type UserResponse struct {
    ID          uint       `json:"id"`
    Username    string     `json:"username"`
    Email       string     `json:"email"`
    Status      string     `json:"status"`
    CreatedAt   time.Time  `json:"created_at"`
    UpdatedAt   time.Time  `json:"updated_at"`
    LastLoginAt *time.Time `json:"last_login_at,omitempty"`
 }
 // ListUsersResponse 用户列表响应
 type ListUsersResponse struct {
    Users      []UserResponse `json:"users"`
    Page       int            `json:"page"`
    PageSize   int            `json:"page_size"`
    Total      int64          `json:"total"`
    TotalPages int            `json:"total_pages"`
 }
 ```
 ---
 ## 4. 任务载荷模型
 ### 4.1 任务类型常量
 ```go
 // pkg/constants/constants.go
 const (
    // 任务类型
    TaskTypeEmailSend     = "email:send"           // 发送邮件
    TaskTypeDataSync      = "data:sync"            // 数据同步
    TaskTypeSIMStatusSync = "sim:status:sync"      // SIM 卡状态同步
    TaskTypeCommission    = "commission:calculate" // 分佣计算
 )
 ```
 ### 4.2 邮件任务载荷
 ```go
 // internal/task/email.go
 // EmailPayload 邮件任务载荷
 type EmailPayload struct {
    RequestID string   `json:"request_id"` // 幂等性标识
    To        string   `json:"to"`         // 收件人
    Subject   string   `json:"subject"`    // 主题
    Body      string   `json:"body"`       // 正文
    CC        []string `json:"cc,omitempty"`  // 抄送
    Attachments []string `json:"attachments,omitempty"` // 附件路径
 }
 ```
 ### 4.3 数据同步任务载荷
 ```go
 // internal/task/sync.go
 // DataSyncPayload 数据同步任务载荷
 type DataSyncPayload struct {
    RequestID  string `json:"request_id"`  // 幂等性标识
    SyncType   string `json:"sync_type"`   // 同步类型：sim_status, flow_usage, real_name
    StartDate  string `json:"start_date"`  // 开始日期（YYYY-MM-DD）
    EndDate    string `json:"end_date"`    // 结束日期（YYYY-MM-DD）
    BatchSize  int    `json:"batch_size"`  // 批量大小（默认：100）
 }
 ```
 ### 4.4 SIM 卡状态同步载荷
 ```go
 // internal/task/sim.go
 // SIMStatusSyncPayload SIM 卡状态同步任务载荷
 type SIMStatusSyncPayload struct {
    RequestID string   `json:"request_id"` // 幂等性标识
    ICCIDs    []string `json:"iccids"`     // ICCID 列表
    ForceSync bool     `json:"force_sync"` // 强制同步（忽略缓存）
 }
 ```
 ---
 ## 5. 数据库 Schema（SQL）
 ### 5.1 初始化 Schema
 ```sql
 -- migrations/000001_init_schema.up.sql
 -- 用户表
 CREATE TABLE IF NOT EXISTS tb_user (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP,
    -- 基本信息
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    password VARCHAR(255) NOT NULL,
    -- 状态字段
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    -- 元数据
    last_login_at TIMESTAMP,
    -- 唯一约束
    CONSTRAINT uk_user_username UNIQUE (username),
    CONSTRAINT uk_user_email UNIQUE (email)
 );
 -- 用户表索引
 CREATE INDEX idx_user_deleted_at ON tb_user(deleted_at);
 CREATE INDEX idx_user_status ON tb_user(status);
 CREATE INDEX idx_user_created_at ON tb_user(created_at);
 -- 订单表
 CREATE TABLE IF NOT EXISTS tb_order (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP,
    -- 业务唯一键
    order_id VARCHAR(50) NOT NULL,
    -- 关联关系（注意：无数据库外键约束，在代码中管理）
    user_id INTEGER NOT NULL,
    -- 订单信息
    amount BIGINT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    remark VARCHAR(500),
    -- 时间字段
    paid_at TIMESTAMP,
    completed_at TIMESTAMP,
    -- 唯一约束
    CONSTRAINT uk_order_order_id UNIQUE (order_id)
 );
 -- 订单表索引
 CREATE INDEX idx_order_deleted_at ON tb_order(deleted_at);
 CREATE INDEX idx_order_user_id ON tb_order(user_id);
 CREATE INDEX idx_order_status ON tb_order(status);
 CREATE INDEX idx_order_created_at ON tb_order(created_at);
 -- 添加注释
 COMMENT ON TABLE tb_user IS '用户表';
 COMMENT ON COLUMN tb_user.username IS '用户名（唯一）';
 COMMENT ON COLUMN tb_user.email IS '邮箱（唯一）';
 COMMENT ON COLUMN tb_user.password IS '密码（bcrypt 哈希）';
 COMMENT ON COLUMN tb_user.status IS '用户状态：active, inactive, suspended';
 COMMENT ON COLUMN tb_user.deleted_at IS '软删除时间';
 COMMENT ON TABLE tb_order IS '订单表';
 COMMENT ON COLUMN tb_order.order_id IS '订单号（业务唯一键）';
 COMMENT ON COLUMN tb_order.user_id IS '用户 ID（在代码中维护关联，无数据库外键）';
 COMMENT ON COLUMN tb_order.amount IS '金额（分）';
 COMMENT ON COLUMN tb_order.status IS '订单状态：pending, paid, processing, completed, cancelled';
 COMMENT ON COLUMN tb_order.deleted_at IS '软删除时间';
 ```
 **重要说明**：
 - ✅ **无外键约束**：`user_id` 仅作为普通字段存储，无 `REFERENCES` 约束
 - ✅ **无触发器**：`created_at` 和 `updated_at` 由 GORM 自动管理，无需数据库触发器
 - ✅ **遵循 Constitution Principle IX**：表关系在代码层面手动维护
 ### 5.2 回滚 Schema
 ```sql
 -- migrations/000001_init_schema.down.sql
 -- 删除表（按依赖顺序倒序删除）
 DROP TABLE IF EXISTS tb_order;
 DROP TABLE IF EXISTS tb_user;
 ```
 ---
 ## 6. Redis 键结构
 ### 6.1 任务锁键
 ```go
 // pkg/constants/redis.go
 // RedisTaskLockKey 生成任务锁键
 // 格式: task:lock:{request_id}
 // 用途: 幂等性控制
 // 过期时间: 24 小时
 func RedisTaskLockKey(requestID string) string {
    return fmt.Sprintf("task:lock:%s", requestID)
 }
 ```
 **使用示例**：
 ```go
 key := constants.RedisTaskLockKey("req-123456")
 // 结果: "task:lock:req-123456"
 ```
 ### 6.2 任务状态键
 ```go
 // RedisTaskStatusKey 生成任务状态键
 // 格式: task:status:{task_id}
 // 用途: 存储任务执行状态
 // 过期时间: 7 天
 func RedisTaskStatusKey(taskID string) string {
    return fmt.Sprintf("task:status:%s", taskID)
 }
 ```
 ---
 ## 7. 常量定义
 ### 7.1 用户状态常量
 ```go
 // pkg/constants/constants.go
 const (
    // 用户状态
    UserStatusActive    = "active"    // 激活
    UserStatusInactive  = "inactive"  // 未激活
    UserStatusSuspended = "suspended" // 暂停
 )
 ```
 ### 7.2 订单状态常量
 ```go
 const (
    // 订单状态
    OrderStatusPending    = "pending"    // 待支付
    OrderStatusPaid       = "paid"       // 已支付
    OrderStatusProcessing = "processing" // 处理中
    OrderStatusCompleted  = "completed"  // 已完成
    OrderStatusCancelled  = "cancelled"  // 已取消
 )
 ```
 ### 7.3 数据库配置常量
 ```go
 const (
    // 数据库连接池默认值
    DefaultMaxOpenConns    = 25
    DefaultMaxIdleConns    = 10
    DefaultConnMaxLifetime = 5 * time.Minute
    // 查询限制
    DefaultPageSize = 20
    MaxPageSize     = 100
    // 慢查询阈值
    SlowQueryThreshold = 100 * time.Millisecond
 )
 ```
 ### 7.4 任务队列常量
 ```go
 const (
    // 队列名称
    QueueCritical = "critical"
    QueueDefault  = "default"
    QueueLow      = "low"
    // 默认重试配置
    DefaultRetryMax = 5
    DefaultTimeout  = 10 * time.Minute
    // 默认并发数
    DefaultConcurrency = 10
 )
 ```
 ---
 ## 8. 实体关系图（ER Diagram）
 ```
 ┌─────────────────┐
 │    tb_user      │
 ├─────────────────┤
 │ id (PK)         │
 │ username (UQ)   │
 │ email (UQ)      │
 │ password        │
 │ status          │
 │ last_login_at   │
 │ created_at      │
 │ updated_at      │
 │ deleted_at      │
 └────────┬────────┘
         │
         │ 1:N (代码层面维护)
         │
 ┌────────▼────────┐
 │    tb_order     │
 ├─────────────────┤
 │ id (PK)         │
 │ order_id (UQ)   │
 │ user_id         │ ← 存储关联 ID（无数据库外键）
 │ amount          │
 │ status          │
 │ remark          │
 │ paid_at         │
 │ completed_at    │
 │ created_at      │
 │ updated_at      │
 │ deleted_at      │
 └─────────────────┘
 ```
 **关系说明**：
 - 一个用户可以有多个订单（1:N 关系）
 - 订单通过 `user_id` 字段存储用户 ID，**在代码层面维护关联**
 - **无数据库外键约束**：遵循 Constitution Principle IX
 - 关联查询在 Service 层手动实现（参见 2.3 节示例代码）
 ---
 ## 9. 数据验证规则
 ### 9.1 用户字段验证
 | 字段 | 验证规则 | 错误消息 |
 |------|----------|----------|
 | username | required, min=3, max=50, alphanum | 用户名必填，3-50 个字母数字字符 |
 | email | required, email | 邮箱必填且格式正确 |
 | password | required, min=8 | 密码必填，至少 8 个字符 |
 | status | oneof=active inactive suspended | 状态必须为 active, inactive, suspended 之一 |
 ### 9.2 订单字段验证
 | 字段 | 验证规则 | 错误消息 |
 |------|----------|----------|
 | order_id | required, min=10, max=50 | 订单号必填，10-50 个字符 |
 | user_id | required, gt=0 | 用户 ID 必填且大于 0 |
 | amount | required, gte=0 | 金额必填且大于等于 0 |
 | status | oneof=pending paid processing completed cancelled | 状态值无效 |
 ---
 ## 10. 数据迁移版本
 | 版本 | 文件名 | 描述 | 日期 |
 |------|--------|------|------|
 | 1 | 000001_init_schema | 初始化用户表和订单表 | 2025-11-12 |
 **添加新迁移**：
 ```bash
 # 创建新迁移文件
 migrate create -ext sql -dir migrations -seq add_sim_table
 # 生成文件：
 # migrations/000002_add_sim_table.up.sql
 # migrations/000002_add_sim_table.down.sql
 ```
 ---
 ## 总结
 本数据模型定义了：
 1. **配置模型**：数据库连接配置、任务队列配置
 2. **实体模型**：基础模型、用户模型、订单模型（示例）
 3. **DTO 模型**：请求/响应数据传输对象
 4. **任务载荷**：各类异步任务的载荷结构
 5. **数据库 Schema**：SQL 迁移脚本
 6. **Redis 键结构**：任务锁、任务状态等键生成函数
 7. **常量定义**：状态枚举、默认配置值
 8. **验证规则**：字段级别的数据验证规则
 **设计原则**：
 - 遵循 GORM 约定（BaseModel、软删除）
 - 遵循 Constitution 命名规范（PascalCase 字段、snake_case 列名）
 - 统一使用常量定义（避免硬编码）
 - 支持软删除和审计字段（created_at, updated_at）
 - 使用数据库约束保证数据完整性
--- a/specs/002-gorm-postgres-asynq/plan.md
+++ b/specs/002-gorm-postgres-asynq/plan.md
@@ -0,0 +1,195 @@
 # Implementation Plan: 数据持久化与异步任务处理集成
 **Branch**: `002-gorm-postgres-asynq` | **Date**: 2025-11-13 | **Spec**: [spec.md](./spec.md)
 **Input**: Feature specification from `/specs/002-gorm-postgres-asynq/spec.md`
 **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
 ## Summary
 本功能集成 GORM + PostgreSQL + Asynq，实现可靠的数据持久化和异步任务处理能力。系统支持标准 CRUD 操作、事务处理、数据库迁移管理、异步任务队列（支持重试、优先级、定时任务）、健康检查和优雅关闭。技术选型基于项目 Constitution 要求，使用 golang-migrate 管理数据库迁移（不使用 GORM AutoMigrate），通过 Redis 持久化任务状态确保故障恢复，所有任务处理逻辑设计为幂等操作。
 ## Technical Context
 **Language/Version**: Go 1.25.4  
 **Primary Dependencies**: Fiber (HTTP 框架), GORM (ORM), Asynq (任务队列), Viper (配置), Zap (日志), golang-migrate (数据库迁移)  
 **Storage**: PostgreSQL 14+（主数据库）, Redis 6.0+（任务队列存储）  
 **Testing**: Go 标准 testing 框架, testcontainers (集成测试)  
 **Target Platform**: Linux/macOS 服务器  
 **Project Type**: Backend API + Worker 服务（双进程架构）  
 **Performance Goals**: API 响应时间 P95 < 200ms, 数据库查询 < 50ms, 任务队列处理速率 100 tasks/s  
 **Constraints**: 数据库连接池最大 25 连接, Worker 默认并发 10, 任务超时 10 分钟, 慢查询阈值 100ms  
 **Scale/Scope**: 支持 1000+ 并发连接, 10000+ 待处理任务队列, 水平扩展 Worker 进程
 ## Constitution Check
 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
 **Tech Stack Adherence**:
 - [ ] Feature uses Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL
 - [ ] No native calls bypass framework (no `database/sql`, `net/http`, `encoding/json` direct use)
 - [ ] All HTTP operations use Fiber framework
 - [ ] All database operations use GORM
 - [ ] All async tasks use Asynq
 - [ ] Uses Go official toolchain: `go fmt`, `go vet`, `golangci-lint`
 - [ ] Uses Go Modules for dependency management
 **Code Quality Standards**:
 - [ ] Follows Handler → Service → Store → Model architecture
 - [ ] Handler layer only handles HTTP, no business logic
 - [ ] Service layer contains business logic with cross-module support
 - [ ] Store layer manages all data access with transaction support
 - [ ] Uses dependency injection via struct fields (not constructor patterns)
 - [ ] Unified error codes in `pkg/errors/`
 - [ ] Unified API responses via `pkg/response/`
 - [ ] All constants defined in `pkg/constants/`
 - [ ] All Redis keys managed via key generation functions (no hardcoded strings)
 - [ ] **No hardcoded magic numbers or strings (3+ occurrences must be constants)**
 - [ ] **Defined constants are used instead of hardcoding duplicate values**
 - [ ] **Code comments prefer Chinese for readability (implementation comments in Chinese)**
 - [ ] **Log messages use Chinese (Info/Warn/Error/Debug logs in Chinese)**
 - [ ] **Error messages support Chinese (user-facing errors have Chinese messages)**
 - [ ] All exported functions/types have Go-style doc comments
 - [ ] Code formatted with `gofmt`
 - [ ] Follows Effective Go and Go Code Review Comments
 **Documentation Standards** (Constitution Principle VII):
 - [ ] Feature summary docs placed in `docs/{feature-id}/` mirroring `specs/{feature-id}/`
 - [ ] Summary doc filenames use Chinese (功能总结.md, 使用指南.md, etc.)
 - [ ] Summary doc content uses Chinese
 - [ ] README.md updated with brief Chinese summary (2-3 sentences)
 - [ ] Documentation is concise for first-time contributors
 **Go Idiomatic Design**:
 - [ ] Package structure is flat (max 2-3 levels), organized by feature
 - [ ] Interfaces are small (1-3 methods), defined at use site
 - [ ] No Java-style patterns: no I-prefix, no Impl-suffix, no getters/setters
 - [ ] Error handling is explicit (return errors, no panic/recover abuse)
 - [ ] Uses composition over inheritance
 - [ ] Uses goroutines and channels (not thread pools)
 - [ ] Uses `context.Context` for cancellation and timeouts
 - [ ] Naming follows Go conventions: short receivers, consistent abbreviations (URL, ID, HTTP)
 - [ ] No Hungarian notation or type prefixes
 - [ ] Simple constructors (New/NewXxx), no Builder pattern unless necessary
 **Testing Standards**:
 - [ ] Unit tests for all core business logic (Service layer)
 - [ ] Integration tests for all API endpoints
 - [ ] Tests use Go standard testing framework
 - [ ] Test files named `*_test.go` in same directory
 - [ ] Test functions use `Test` prefix, benchmarks use `Benchmark` prefix
 - [ ] Table-driven tests for multiple test cases
 - [ ] Test helpers marked with `t.Helper()`
 - [ ] Tests are independent (no external service dependencies)
 - [ ] Target coverage: 70%+ overall, 90%+ for core business
 **User Experience Consistency**:
 - [ ] All APIs use unified JSON response format
 - [ ] Error responses include clear error codes and bilingual messages
 - [ ] RESTful design principles followed
 - [ ] Unified pagination parameters (page, page_size, total)
 - [ ] Time fields use ISO 8601 format (RFC3339)
 - [ ] Currency amounts use integers (cents) to avoid float precision issues
 **Performance Requirements**:
 - [ ] API response time (P95) < 200ms, (P99) < 500ms
 - [ ] Batch operations use bulk queries/inserts
 - [ ] All database queries have appropriate indexes
 - [ ] List queries implement pagination (default 20, max 100)
 - [ ] Non-realtime operations use async tasks
 - [ ] Database and Redis connection pools properly configured
 - [ ] Uses goroutines/channels for concurrency (not thread pools)
 - [ ] Uses `context.Context` for timeout control
 - [ ] Uses `sync.Pool` for frequently allocated objects
 **Access Logging Standards** (Constitution Principle VIII):
 - [ ] ALL HTTP requests logged to access.log without exception
 - [ ] Request parameters (query + body) logged (limited to 50KB)
 - [ ] Response parameters (body) logged (limited to 50KB)
 - [ ] Logging happens via centralized Logger middleware (pkg/logger/Middleware())
 - [ ] No middleware bypasses access logging (including auth failures, rate limits)
 - [ ] Body truncation indicates "... (truncated)" when over 50KB limit
 - [ ] Access log includes all required fields: method, path, query, status, duration_ms, request_id, ip, user_agent, user_id, request_body, response_body
 ## Project Structure
 ### Documentation (this feature)
 **设计文档（specs/ 目录）**：开发前的规划和设计
 ```text
 specs/[###-feature]/
 ├── plan.md              # This file (/speckit.plan command output)
 ├── research.md          # Phase 0 output (/speckit.plan command)
 ├── data-model.md        # Phase 1 output (/speckit.plan command)
 ├── quickstart.md        # Phase 1 output (/speckit.plan command)
 ├── contracts/           # Phase 1 output (/speckit.plan command)
 └── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
 ```
 **总结文档（docs/ 目录）**：开发完成后的总结和使用指南（遵循 Constitution Principle VII）
 ```text
 docs/[###-feature]/
 ├── 功能总结.md          # 功能概述、核心实现、技术要点（MUST 使用中文命名和内容）
 ├── 使用指南.md          # 如何使用该功能的详细说明（MUST 使用中文命名和内容）
 └── 架构说明.md          # 架构设计和技术决策（可选，MUST 使用中文命名和内容）
 ```
 **README.md 更新**：每次完成功能后 MUST 在 README.md 添加简短描述（2-3 句话，中文）
 ### Source Code (repository root)
 <!--
  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
  for this feature. Delete unused options and expand the chosen structure with
  real paths (e.g., apps/admin, packages/something). The delivered plan must
  not include Option labels.
 -->
 ```text
 # [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
 src/
 ├── models/
 ├── services/
 ├── cli/
 └── lib/
 tests/
 ├── contract/
 ├── integration/
 └── unit/
 # [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
 backend/
 ├── src/
 │   ├── models/
 │   ├── services/
 │   └── api/
 └── tests/
 frontend/
 ├── src/
 │   ├── components/
 │   ├── pages/
 │   └── services/
 └── tests/
 # [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
 api/
 └── [same as backend above]
 ios/ or android/
 └── [platform-specific structure: feature modules, UI flows, platform tests]
 ```
 **Structure Decision**: 采用 Backend API + Worker 双进程架构。项目已存在完整的 Fiber 后端结构（cmd/api/, internal/handler/, internal/service/, internal/store/, internal/model/），本次功能在此基础上添加：
 - `cmd/worker/`: Worker 进程入口
 - `pkg/database/`: PostgreSQL 连接初始化
 - `pkg/queue/`: Asynq 客户端和服务端封装
 - `internal/task/`: 异步任务处理器
 - `internal/store/postgres/`: 数据访问层（基于 GORM）
 - `migrations/`: 数据库迁移文件（SQL）
 现有目录结构已符合 Constitution 分层架构要求（Handler → Service → Store → Model），本功能遵循该架构。
 ## Complexity Tracking
 > **无宪法违规** - 本功能完全符合项目 Constitution 要求，无需例外说明。
--- a/specs/002-gorm-postgres-asynq/quickstart.md
+++ b/specs/002-gorm-postgres-asynq/quickstart.md
@@ -0,0 +1,829 @@
 # Quick Start Guide: 数据持久化与异步任务处理集成
 **Feature**: 002-gorm-postgres-asynq  
 **Date**: 2025-11-12  
 **Purpose**: 快速开始指南和使用示例
 ## 概述
 本指南帮助开发者快速搭建和使用 GORM + PostgreSQL + Asynq 集成的数据持久化和异步任务处理功能。
 ---
 ## 前置要求
 ### 系统要求
 - Go 1.25.4+
 - PostgreSQL 14+
 - Redis 6.0+
 - golang-migrate CLI 工具
 ### 安装依赖
 ```bash
 # 安装 Go 依赖
 go mod tidy
 # 安装 golang-migrate（macOS）
 brew install golang-migrate
 # 安装 golang-migrate（Linux）
 curl -L https://github.com/golang-migrate/migrate/releases/download/v4.15.2/migrate.linux-amd64.tar.gz | tar xvz
 sudo mv migrate /usr/local/bin/
 # 或使用 Go install
 go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
 ```
 ---
 ## 步骤 1: 启动 PostgreSQL
 ### 使用 Docker（推荐）
 ```bash
 # 启动 PostgreSQL 容器
 docker run --name postgres-dev \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=junhong_cmp \
  -p 5432:5432 \
  -d postgres:14
 # 验证运行状态
 docker ps | grep postgres-dev
 ```
 ### 使用本地安装
 ```bash
 # macOS
 brew install postgresql@14
 brew services start postgresql@14
 # 创建数据库
 createdb junhong_cmp
 ```
 ### 验证连接
 ```bash
 # 测试连接
 psql -h localhost -p 5432 -U postgres -d junhong_cmp
 # 如果成功，会进入 PostgreSQL 命令行
 # 输入 \q 退出
 ```
 ---
 ## 步骤 2: 启动 Redis
 ```bash
 # 使用 Docker
 docker run --name redis-dev \
  -p 6379:6379 \
  -d redis:7-alpine
 # 或使用本地安装（macOS）
 brew install redis
 brew services start redis
 # 验证 Redis
 redis-cli ping
 # 应返回: PONG
 ```
 ---
 ## 步骤 3: 配置数据库连接
 编辑配置文件 `configs/config.yaml`，添加数据库和队列配置：
 ```yaml
 # configs/config.yaml
 # 数据库配置
 database:
  host: localhost
  port: 5432
  user: postgres
  password: password          # 开发环境明文存储，生产环境使用环境变量
  dbname: junhong_cmp
  sslmode: disable            # 开发环境禁用 SSL，生产环境使用 require
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 5m
 # 任务队列配置
 queue:
  concurrency: 10             # Worker 并发数
  queues:                     # 队列优先级（权重）
    critical: 6               # 关键任务：60%
    default: 3                # 普通任务：30%
    low: 1                    # 低优先级：10%
  retry_max: 5                # 最大重试次数
  timeout: 10m                # 任务超时时间
 ```
 ---
 ## 步骤 4: 运行数据库迁移
 ### 方法 1: 使用迁移脚本（推荐）
 ```bash
 # 赋予执行权限
 chmod +x scripts/migrate.sh
 # 向上迁移（应用所有迁移）
 ./scripts/migrate.sh up
 # 查看当前版本
 ./scripts/migrate.sh version
 # 回滚最后一次迁移
 ./scripts/migrate.sh down 1
 # 创建新迁移
 ./scripts/migrate.sh create add_sim_table
 ```
 ### 方法 2: 直接使用 migrate CLI
 ```bash
 # 设置数据库 URL
 export DATABASE_URL="postgresql://postgres:password@localhost:5432/junhong_cmp?sslmode=disable"
 # 向上迁移
 migrate -path migrations -database "$DATABASE_URL" up
 # 查看版本
 migrate -path migrations -database "$DATABASE_URL" version
 ```
 ### 验证迁移成功
 ```bash
 # 连接数据库
 psql -h localhost -p 5432 -U postgres -d junhong_cmp
 # 查看表
 \dt
 # 应该看到：
 # tb_user
 # tb_order
 # schema_migrations（由 golang-migrate 创建）
 # 退出
 \q
 ```
 ---
 ## 步骤 5: 启动 API 服务
 ```bash
 # 从项目根目录运行
 go run cmd/api/main.go
 # 预期输出：
 # {"level":"info","timestamp":"...","message":"PostgreSQL 连接成功","host":"localhost","port":5432}
 # {"level":"info","timestamp":"...","message":"Redis 连接成功","addr":"localhost:6379"}
 # {"level":"info","timestamp":"...","message":"服务启动成功","host":"0.0.0.0","port":8080}
 ```
 ### 验证 API 服务
 ```bash
 # 测试健康检查
 curl http://localhost:8080/health
 # 预期响应：
 # {
 #   "status": "ok",
 #   "postgres": "up",
 #   "redis": "up"
 # }
 ```
 ---
 ## 步骤 6: 启动 Worker 服务
 打开新的终端窗口：
 ```bash
 # 从项目根目录运行
 go run cmd/worker/main.go
 # 预期输出：
 # {"level":"info","timestamp":"...","message":"PostgreSQL 连接成功","host":"localhost","port":5432}
 # {"level":"info","timestamp":"...","message":"Redis 连接成功","addr":"localhost:6379"}
 # {"level":"info","timestamp":"...","message":"Worker 启动成功","concurrency":10}
 ```
 ---
 ## 使用示例
 ### 示例 1: 数据库 CRUD 操作
 #### 创建用户
 ```bash
 curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -H "token: valid_token_here" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'
 # 响应：
 # {
 #   "code": 0,
 #   "msg": "success",
 #   "data": {
 #     "id": 1,
 #     "username": "testuser",
 #     "email": "test@example.com",
 #     "status": "active",
 #     "created_at": "2025-11-12T16:00:00+08:00",
 #     "updated_at": "2025-11-12T16:00:00+08:00"
 #   },
 #   "timestamp": "2025-11-12T16:00:00+08:00"
 # }
 ```
 #### 查询用户
 ```bash
 curl http://localhost:8080/api/v1/users/1 \
  -H "token: valid_token_here"
 # 响应：
 # {
 #   "code": 0,
 #   "msg": "success",
 #   "data": {
 #     "id": 1,
 #     "username": "testuser",
 #     "email": "test@example.com",
 #     "status": "active",
 #     ...
 #   }
 # }
 ```
 #### 更新用户
 ```bash
 curl -X PUT http://localhost:8080/api/v1/users/1 \
  -H "Content-Type: application/json" \
  -H "token: valid_token_here" \
  -d '{
    "email": "newemail@example.com",
    "status": "inactive"
  }'
 ```
 #### 列表查询（分页）
 ```bash
 curl "http://localhost:8080/api/v1/users?page=1&page_size=20" \
  -H "token: valid_token_here"
 # 响应：
 # {
 #   "code": 0,
 #   "msg": "success",
 #   "data": {
 #     "users": [...],
 #     "page": 1,
 #     "page_size": 20,
 #     "total": 100,
 #     "total_pages": 5
 #   }
 # }
 ```
 #### 删除用户（软删除）
 ```bash
 curl -X DELETE http://localhost:8080/api/v1/users/1 \
  -H "token: valid_token_here"
 ```
 ### 示例 2: 提交异步任务
 #### 提交邮件发送任务
 ```bash
 curl -X POST http://localhost:8080/api/v1/tasks/email \
  -H "Content-Type: application/json" \
  -H "token: valid_token_here" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome",
    "body": "Welcome to our service!"
  }'
 # 响应：
 # {
 #   "code": 0,
 #   "msg": "任务已提交",
 #   "data": {
 #     "task_id": "550e8400-e29b-41d4-a716-446655440000",
 #     "queue": "default"
 #   }
 # }
 ```
 #### 提交数据同步任务（高优先级）
 ```bash
 curl -X POST http://localhost:8080/api/v1/tasks/sync \
  -H "Content-Type: application/json" \
  -H "token: valid_token_here" \
  -d '{
    "sync_type": "sim_status",
    "start_date": "2025-11-01",
    "end_date": "2025-11-12",
    "priority": "critical"
  }'
 ```
 ### 示例 3: 直接在代码中使用数据库
 ```go
 // internal/service/user/service.go
 package user
 import (
    "context"
    "github.com/break/junhong_cmp_fiber/internal/model"
    "github.com/break/junhong_cmp_fiber/internal/store/postgres"
    "github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 type Service struct {
    store  *postgres.Store
    logger *zap.Logger
 }
 // CreateUser 创建用户
 func (s *Service) CreateUser(ctx context.Context, req *model.CreateUserRequest) (*model.User, error) {
    // 参数验证
    if err := validate.Struct(req); err != nil {
        return nil, err
    }
    // 密码哈希
    hashedPassword, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost)
    if err != nil {
        return nil, err
    }
    // 创建用户
    user := &model.User{
        Username: req.Username,
        Email:    req.Email,
        Password: string(hashedPassword),
        Status:   constants.UserStatusActive,
    }
    if err := s.store.User.Create(ctx, user); err != nil {
        s.logger.Error("创建用户失败",
            zap.String("username", req.Username),
            zap.Error(err))
        return nil, err
    }
    s.logger.Info("用户创建成功",
        zap.Uint("user_id", user.ID),
        zap.String("username", user.Username))
    return user, nil
 }
 // GetUserByID 根据 ID 获取用户
 func (s *Service) GetUserByID(ctx context.Context, id uint) (*model.User, error) {
    user, err := s.store.User.GetByID(ctx, id)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, errors.New(errors.CodeNotFound, "用户不存在")
        }
        return nil, err
    }
    return user, nil
 }
 ```
 ### 示例 4: 在代码中提交异步任务
 ```go
 // internal/service/email/service.go
 package email
 import (
    "context"
    "encoding/json"
    "github.com/break/junhong_cmp_fiber/internal/task"
    "github.com/break/junhong_cmp_fiber/pkg/constants"
    "github.com/break/junhong_cmp_fiber/pkg/queue"
    "github.com/hibiken/asynq"
 )
 type Service struct {
    queueClient *queue.Client
    logger      *zap.Logger
 }
 // SendWelcomeEmail 发送欢迎邮件（异步）
 func (s *Service) SendWelcomeEmail(ctx context.Context, userID uint, email string) error {
    // 构造任务载荷
    payload := &task.EmailPayload{
        RequestID: fmt.Sprintf("welcome-%d", userID),
        To:        email,
        Subject:   "欢迎加入",
        Body:      "感谢您注册我们的服务！",
    }
    payloadBytes, err := json.Marshal(payload)
    if err != nil {
        return err
    }
    // 提交任务到队列
    err = s.queueClient.EnqueueTask(
        ctx,
        constants.TaskTypeEmailSend,
        payloadBytes,
        asynq.Queue(constants.QueueDefault),
        asynq.MaxRetry(constants.DefaultRetryMax),
    )
    if err != nil {
        s.logger.Error("提交邮件任务失败",
            zap.Uint("user_id", userID),
            zap.String("email", email),
            zap.Error(err))
        return err
    }
    s.logger.Info("欢迎邮件任务已提交",
        zap.Uint("user_id", userID),
        zap.String("email", email))
    return nil
 }
 ```
 ### 示例 5: 事务处理
 ```go
 // internal/service/order/service.go
 package order
 // CreateOrderWithUser 创建订单并更新用户统计（事务）
 func (s *Service) CreateOrderWithUser(ctx context.Context, req *CreateOrderRequest) (*model.Order, error) {
    var order *model.Order
    // 使用事务
    err := s.store.Transaction(ctx, func(tx *postgres.Store) error {
        // 1. 创建订单
        order = &model.Order{
            OrderID: generateOrderID(),
            UserID:  req.UserID,
            Amount:  req.Amount,
            Status:  constants.OrderStatusPending,
        }
        if err := tx.Order.Create(ctx, order); err != nil {
            return err
        }
        // 2. 更新用户订单计数
        user, err := tx.User.GetByID(ctx, req.UserID)
        if err != nil {
            return err
        }
        user.OrderCount++
        if err := tx.User.Update(ctx, user); err != nil {
            return err
        }
        return nil // 提交事务
    })
    if err != nil {
        s.logger.Error("创建订单失败",
            zap.Uint("user_id", req.UserID),
            zap.Error(err))
        return nil, err
    }
    return order, nil
 }
 ```
 ---
 ## 监控和调试
 ### 查看数据库数据
 ```bash
 # 连接数据库
 psql -h localhost -p 5432 -U postgres -d junhong_cmp
 # 查询用户
 SELECT * FROM tb_user;
 # 查询订单
 SELECT * FROM tb_order WHERE user_id = 1;
 # 查看迁移历史
 SELECT * FROM schema_migrations;
 ```
 ### 查看任务队列状态
 #### 使用 asynqmon（Web UI）
 ```bash
 # 安装 asynqmon
 go install github.com/hibiken/asynqmon@latest
 # 启动监控面板
 asynqmon --redis-addr=localhost:6379
 # 访问 http://localhost:8080
 # 可以查看：
 # - 队列统计
 # - 任务状态（pending, active, completed, failed）
 # - 重试历史
 # - 失败任务详情
 ```
 #### 使用 Redis CLI
 ```bash
 # 查看所有队列
 redis-cli KEYS "asynq:*"
 # 查看 default 队列长度
 redis-cli LLEN "asynq:{default}:pending"
 # 查看任务详情
 redis-cli HGETALL "asynq:task:{task_id}"
 ```
 ### 查看日志
 ```bash
 # 实时查看应用日志
 tail -f logs/app.log | jq .
 # 过滤错误日志
 tail -f logs/app.log | jq 'select(.level == "error")'
 # 查看访问日志
 tail -f logs/access.log | jq .
 # 过滤慢查询
 tail -f logs/app.log | jq 'select(.duration_ms > 100)'
 ```
 ---
 ## 测试
 ### 单元测试
 ```bash
 # 运行所有测试
 go test ./...
 # 运行特定包的测试
 go test ./internal/store/postgres/...
 # 带覆盖率
 go test -cover ./...
 # 详细输出
 go test -v ./...
 ```
 ### 集成测试
 ```bash
 # 运行集成测试（需要 PostgreSQL 和 Redis）
 go test -v ./tests/integration/...
 # 单独测试数据库功能
 go test -v ./tests/integration/database_test.go
 # 单独测试任务队列
 go test -v ./tests/integration/task_test.go
 ```
 ### 使用 Testcontainers（推荐）
 集成测试会自动启动 PostgreSQL 和 Redis 容器：
 ```go
 // tests/integration/database_test.go
 func TestUserCRUD(t *testing.T) {
    // 自动启动 PostgreSQL 容器
    // 运行测试
    // 自动清理容器
 }
 ```
 ---
 ## 故障排查
 ### 问题 1: 数据库连接失败
 **错误**: `dial tcp 127.0.0.1:5432: connect: connection refused`
 **解决方案**:
 ```bash
 # 检查 PostgreSQL 是否运行
 docker ps | grep postgres
 # 检查端口占用
 lsof -i :5432
 # 重启 PostgreSQL
 docker restart postgres-dev
 ```
 ### 问题 2: 迁移失败
 **错误**: `Dirty database version 1. Fix and force version.`
 **解决方案**:
 ```bash
 # 强制设置版本
 migrate -path migrations -database "$DATABASE_URL" force 1
 # 然后重新运行迁移
 migrate -path migrations -database "$DATABASE_URL" up
 ```
 ### 问题 3: Worker 无法连接 Redis
 **错误**: `dial tcp 127.0.0.1:6379: connect: connection refused`
 **解决方案**:
 ```bash
 # 检查 Redis 是否运行
 docker ps | grep redis
 # 测试连接
 redis-cli ping
 # 重启 Redis
 docker restart redis-dev
 ```
 ### 问题 4: 任务一直重试
 **原因**: 任务处理函数返回错误
 **解决方案**:
 1. 检查 Worker 日志：`tail -f logs/app.log | jq 'select(.level == "error")'`
 2. 使用 asynqmon 查看失败详情
 3. 检查任务幂等性实现
 4. 验证 Redis 锁键是否正确设置
 ---
 ## 环境配置
 ### 开发环境
 ```bash
 export CONFIG_ENV=dev
 go run cmd/api/main.go
 ```
 ### 预发布环境
 ```bash
 export CONFIG_ENV=staging
 go run cmd/api/main.go
 ```
 ### 生产环境
 ```bash
 export CONFIG_ENV=prod
 export DB_PASSWORD=secure_password  # 使用环境变量
 go run cmd/api/main.go
 ```
 ---
 ## 性能调优建议
 ### 数据库连接池
 根据服务器资源调整：
 ```yaml
 database:
  max_open_conns: 25     # 增大以支持更多并发
  max_idle_conns: 10     # 保持足够的空闲连接
  conn_max_lifetime: 5m  # 定期回收连接
 ```
 ### Worker 并发数
 根据任务类型调整：
 ```yaml
 queue:
  concurrency: 20        # I/O 密集型：CPU 核心数 × 2
  # concurrency: 8       # CPU 密集型：CPU 核心数
 ```
 ### 队列优先级
 根据业务需求调整：
 ```yaml
 queue:
  queues:
    critical: 8          # 提高关键任务权重
    default: 2
    low: 1
 ```
 ---
 ## 下一步
 1. **添加业务模型**: 参考 `internal/model/user.go` 创建 SIM 卡、订单等业务实体
 2. **实现业务逻辑**: 在 Service 层实现具体业务逻辑
 3. **添加迁移文件**: 使用 `./scripts/migrate.sh create` 添加新表
 4. **创建异步任务**: 参考 `internal/task/email.go` 创建新的任务处理器
 5. **编写测试**: 为所有 Service 层业务逻辑编写单元测试
 ---
 ## 参考资料
 - [GORM 官方文档](https://gorm.io/docs/)
 - [Asynq 官方文档](https://github.com/hibiken/asynq)
 - [golang-migrate 文档](https://github.com/golang-migrate/migrate)
 - [PostgreSQL 文档](https://www.postgresql.org/docs/)
 - [项目 Constitution](../../.specify/memory/constitution.md)
 ---
 ## 常见问题（FAQ）
 **Q: 如何添加新的数据库表？**  
 A: 使用 `./scripts/migrate.sh create table_name` 创建迁移文件，编辑 SQL，然后运行 `./scripts/migrate.sh up`。
 **Q: 任务失败后会怎样？**  
 A: 根据配置自动重试（默认 5 次，指数退避）。5 次后仍失败会进入死信队列，可在 asynqmon 中查看。
 **Q: 如何保证任务幂等性？**  
 A: 使用 Redis 锁或数据库唯一约束。参考 `research.md` 中的幂等性设计模式。
 **Q: 如何扩展 Worker？**  
 A: 启动多个 Worker 进程（不同机器或容器），连接同一个 Redis。Asynq 自动负载均衡。
 **Q: 数据库密码如何安全存储？**  
 A: 生产环境使用环境变量：`export DB_PASSWORD=xxx`，配置文件中使用 `${DB_PASSWORD}`。
 **Q: 如何监控任务执行情况？**  
 A: 使用 asynqmon Web UI 或通过 Redis CLI 查看队列状态。
 ---
 ## 总结
 本指南涵盖了：
 - ✅ 环境搭建（PostgreSQL、Redis）
 - ✅ 数据库迁移
 - ✅ 服务启动（API + Worker）
 - ✅ CRUD 操作示例
 - ✅ 异步任务提交和处理
 - ✅ 事务处理
 - ✅ 监控和调试
 - ✅ 故障排查
 - ✅ 性能调优
 **推荐开发流程**：
 1. 设计数据模型 → 2. 创建迁移文件 → 3. 实现 Store 层 → 4. 实现 Service 层 → 5. 实现 Handler 层 → 6. 编写测试 → 7. 运行和验证
--- a/specs/002-gorm-postgres-asynq/research.md
+++ b/specs/002-gorm-postgres-asynq/research.md
@@ -0,0 +1,901 @@
 # Research: 数据持久化与异步任务处理集成
 **Feature**: 002-gorm-postgres-asynq  
 **Date**: 2025-11-12  
 **Purpose**: 记录技术选型决策、最佳实践和架构考量
 ## 概述
 本文档记录了 GORM + PostgreSQL + Asynq 集成的技术研究成果，包括技术选型理由、配置建议、最佳实践和常见陷阱。
 ---
 ## 1. GORM 与 PostgreSQL 集成
 ### 决策：选择 GORM 作为 ORM 框架
 **理由**：
 - **官方支持**：GORM 是 Go 生态系统中最流行的 ORM，社区活跃，文档完善
 - **PostgreSQL 原生支持**：提供专门的 PostgreSQL 驱动和方言
 - **功能完整**：支持复杂查询、关联关系、事务、钩子、软删除等
 - **性能优秀**：支持预编译语句、批量操作、连接池管理
 - **符合 Constitution**：项目技术栈要求使用 GORM
 **替代方案**：
 - **sqlx**：更轻量，但功能不够完整，需要手写更多 SQL
 - **ent**：Facebook 开发，功能强大，但学习曲线陡峭，且不符合项目技术栈要求
 ### GORM 最佳实践
 #### 1.1 连接初始化
 ```go
 // pkg/database/postgres.go
 import (
    "gorm.io/driver/postgres"
    "gorm.io/gorm"
    "gorm.io/gorm/logger"
 )
 func InitPostgres(cfg *config.DatabaseConfig, log *zap.Logger) (*gorm.DB, error) {
    dsn := fmt.Sprintf(
        "host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
        cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.DBName, cfg.SSLMode,
    )
    // GORM 配置
    gormConfig := &gorm.Config{
        Logger: logger.Default.LogMode(logger.Silent), // 使用 Zap 替代 GORM 日志
        NamingStrategy: schema.NamingStrategy{
            TablePrefix:   "tb_",     // 表名前缀
            SingularTable: true,      // 使用单数表名
        },
        PrepareStmt: true,            // 启用预编译语句缓存
    }
    db, err := gorm.Open(postgres.Open(dsn), gormConfig)
    if err != nil {
        return nil, fmt.Errorf("连接 PostgreSQL 失败: %w", err)
    }
    // 获取底层 sql.DB 进行连接池配置
    sqlDB, err := db.DB()
    if err != nil {
        return nil, fmt.Errorf("获取 sql.DB 失败: %w", err)
    }
    // 连接池配置（参考 Constitution 性能要求）
    sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)       // 最大连接数：25
    sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)       // 最大空闲连接：10
    sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime) // 连接最大生命周期：5m
    // 验证连接
    if err := sqlDB.Ping(); err != nil {
        return nil, fmt.Errorf("PostgreSQL 连接验证失败: %w", err)
    }
    log.Info("PostgreSQL 连接成功",
        zap.String("host", cfg.Host),
        zap.Int("port", cfg.Port),
        zap.String("database", cfg.DBName))
    return db, nil
 }
 ```
 #### 1.2 连接池配置建议
 | 参数 | 推荐值 | 理由 |
 |------|--------|------|
 | MaxOpenConns | 25 | 平衡性能和资源，避免 PostgreSQL 连接耗尽 |
 | MaxIdleConns | 10 | 保持足够的空闲连接以应对突发流量 |
 | ConnMaxLifetime | 5m | 定期回收连接，避免长连接问题 |
 **计算公式**：
 ```
 MaxOpenConns = (可用内存 / 每连接内存) * 安全系数
 每连接内存 ≈ 10MB（PostgreSQL 典型值）
 安全系数 = 0.7（为其他进程预留资源）
 ```
 #### 1.3 模型定义规范
 ```go
 // internal/model/user.go
 type User struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` // 软删除
    Username  string `gorm:"uniqueIndex;not null;size:50" json:"username"`
    Email     string `gorm:"uniqueIndex;not null;size:100" json:"email"`
    Status    string `gorm:"not null;size:20;default:'active'" json:"status"`
    // 关联关系示例（如果需要）
    // Orders []Order `gorm:"foreignKey:UserID" json:"orders,omitempty"`
 }
 // TableName 指定表名（如果不使用默认命名）
 func (User) TableName() string {
    return "tb_user" // 遵循 NamingStrategy 的 TablePrefix
 }
 ```
 **命名规范**：
 - 字段名使用 PascalCase（Go 约定）
 - 数据库列名自动转换为 snake_case
 - 表名使用 `tb_` 前缀（可配置）
 - JSON tag 使用 snake_case
 #### 1.4 事务处理
 ```go
 // internal/store/postgres/transaction.go
 func (s *Store) Transaction(ctx context.Context, fn func(*Store) error) error {
    return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        // 创建事务内的 Store 实例
        txStore := &Store{db: tx, logger: s.logger}
        return fn(txStore)
    })
 }
 // 使用示例
 err := store.Transaction(ctx, func(tx *Store) error {
    if err := tx.User.Create(ctx, user); err != nil {
        return err // 自动回滚
    }
    if err := tx.Order.Create(ctx, order); err != nil {
        return err // 自动回滚
    }
    return nil // 自动提交
 })
 ```
 **事务最佳实践**：
 - 使用 `context.Context` 传递超时和取消信号
 - 事务内操作尽可能快（< 50ms），避免长事务锁表
 - 事务失败自动回滚，无需手动处理
 - 避免事务嵌套（GORM 使用 SavePoint 处理嵌套事务）
 ---
 ## 2. 数据库迁移：golang-migrate
 ### 决策：使用 golang-migrate 而非 GORM AutoMigrate
 **理由**：
 - **版本控制**：迁移文件版本化，可追溯数据库 schema 变更历史
 - **可回滚**：每个迁移包含 up/down 脚本，支持安全回滚
 - **生产安全**：明确的 SQL 语句，避免 AutoMigrate 的意外变更
 - **团队协作**：迁移文件可 code review，减少数据库变更风险
 - **符合 Constitution**：项目规范要求使用外部迁移工具
 **GORM AutoMigrate 的问题**：
 - 无法回滚
 - 无法删除列（只能添加和修改）
 - 不支持复杂的 schema 变更（如重命名列）
 - 生产环境风险高
 ### golang-migrate 使用指南
 #### 2.1 安装
 ```bash
 # macOS
 brew install golang-migrate
 # Linux
 curl -L https://github.com/golang-migrate/migrate/releases/download/v4.15.2/migrate.linux-amd64.tar.gz | tar xvz
 sudo mv migrate /usr/local/bin/
 # Go install
 go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
 ```
 #### 2.2 创建迁移文件
 ```bash
 # 创建新迁移
 migrate create -ext sql -dir migrations -seq init_schema
 # 生成文件：
 # migrations/000001_init_schema.up.sql
 # migrations/000001_init_schema.down.sql
 ```
 #### 2.3 迁移文件示例
 ```sql
 -- migrations/000001_init_schema.up.sql
 CREATE TABLE IF NOT EXISTS tb_user (
    id SERIAL PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    status VARCHAR(20) NOT NULL DEFAULT 'active'
 );
 CREATE INDEX idx_user_deleted_at ON tb_user(deleted_at);
 CREATE INDEX idx_user_status ON tb_user(status);
 -- migrations/000001_init_schema.down.sql
 DROP TABLE IF EXISTS tb_user;
 ```
 #### 2.4 执行迁移
 ```bash
 # 向上迁移（应用所有未执行的迁移）
 migrate -path migrations -database "postgresql://user:password@localhost:5432/dbname?sslmode=disable" up
 # 回滚最后一次迁移
 migrate -path migrations -database "postgresql://user:password@localhost:5432/dbname?sslmode=disable" down 1
 # 迁移到指定版本
 migrate -path migrations -database "postgresql://user:password@localhost:5432/dbname?sslmode=disable" goto 3
 # 强制设置版本（修复脏迁移）
 migrate -path migrations -database "postgresql://user:password@localhost:5432/dbname?sslmode=disable" force 2
 ```
 #### 2.5 迁移脚本封装
 ```bash
 #!/bin/bash
 # scripts/migrate.sh
 set -e
 DB_USER=${DB_USER:-"postgres"}
 DB_PASSWORD=${DB_PASSWORD:-"password"}
 DB_HOST=${DB_HOST:-"localhost"}
 DB_PORT=${DB_PORT:-"5432"}
 DB_NAME=${DB_NAME:-"junhong_cmp"}
 DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=disable"
 case "$1" in
    up)
        migrate -path migrations -database "$DATABASE_URL" up
        ;;
    down)
        migrate -path migrations -database "$DATABASE_URL" down ${2:-1}
        ;;
    create)
        migrate create -ext sql -dir migrations -seq "$2"
        ;;
    version)
        migrate -path migrations -database "$DATABASE_URL" version
        ;;
    *)
        echo "Usage: $0 {up|down [n]|create <name>|version}"
        exit 1
 esac
 ```
 ---
 ## 3. Asynq 任务队列
 ### 决策：选择 Asynq 作为异步任务队列
 **理由**：
 - **Redis 原生支持**：基于 Redis，无需额外中间件
 - **功能完整**：支持任务重试、优先级、定时任务、唯一性约束
 - **高性能**：支持并发处理，可配置 worker 数量
 - **可观测性**：提供 Web UI 监控面板（asynqmon）
 - **符合 Constitution**：项目技术栈要求使用 Asynq
 **替代方案**：
 - **Machinery**：功能类似，但社区活跃度不如 Asynq
 - **RabbitMQ + amqp091-go**：更重量级，需要额外部署 RabbitMQ
 - **Kafka**：适合大规模流处理，对本项目过于复杂
 ### Asynq 架构设计
 #### 3.1 Client（任务提交）
 ```go
 // pkg/queue/client.go
 import (
    "github.com/hibiken/asynq"
    "github.com/redis/go-redis/v9"
 )
 type Client struct {
    client *asynq.Client
    logger *zap.Logger
 }
 func NewClient(rdb *redis.Client, logger *zap.Logger) *Client {
    return &Client{
        client: asynq.NewClient(asynq.RedisClientOpt{Addr: rdb.Options().Addr}),
        logger: logger,
    }
 }
 func (c *Client) EnqueueTask(ctx context.Context, taskType string, payload []byte, opts ...asynq.Option) error {
    task := asynq.NewTask(taskType, payload, opts...)
    info, err := c.client.EnqueueContext(ctx, task)
    if err != nil {
        c.logger.Error("任务入队失败",
            zap.String("task_type", taskType),
            zap.Error(err))
        return err
    }
    c.logger.Info("任务入队成功",
        zap.String("task_id", info.ID),
        zap.String("queue", info.Queue))
    return nil
 }
 ```
 #### 3.2 Server（任务处理）
 ```go
 // pkg/queue/server.go
 func NewServer(rdb *redis.Client, cfg *config.QueueConfig, logger *zap.Logger) *asynq.Server {
    return asynq.NewServer(
        asynq.RedisClientOpt{Addr: rdb.Options().Addr},
        asynq.Config{
            Concurrency: cfg.Concurrency, // 并发数（默认 10）
            Queues: map[string]int{
                "critical": 6, // 权重：60%
                "default":  3, // 权重：30%
                "low":      1, // 权重：10%
            },
            ErrorHandler: asynq.ErrorHandlerFunc(func(ctx context.Context, task *asynq.Task, err error) {
                logger.Error("任务执行失败",
                    zap.String("task_type", task.Type()),
                    zap.Error(err))
            }),
            Logger: &AsynqLogger{logger: logger}, // 自定义日志适配器
        },
    )
 }
 // cmd/worker/main.go
 func main() {
    // ... 初始化配置、日志、Redis
    srv := queue.NewServer(rdb, cfg.Queue, logger)
    mux := asynq.NewServeMux()
    // 注册任务处理器
    mux.HandleFunc(constants.TaskTypeEmailSend, task.HandleEmailSend)
    mux.HandleFunc(constants.TaskTypeDataSync, task.HandleDataSync)
    if err := srv.Run(mux); err != nil {
        logger.Fatal("Worker 启动失败", zap.Error(err))
    }
 }
 ```
 #### 3.3 任务处理器（Handler）
 ```go
 // internal/task/email.go
 func HandleEmailSend(ctx context.Context, t *asynq.Task) error {
    var payload EmailPayload
    if err := json.Unmarshal(t.Payload(), &payload); err != nil {
        return fmt.Errorf("解析任务参数失败: %w", err)
    }
    // 幂等性检查（使用 Redis 或数据库）
    key := constants.RedisTaskLockKey(payload.RequestID)
    if exists, _ := rdb.Exists(ctx, key).Result(); exists > 0 {
        logger.Info("任务已处理，跳过",
            zap.String("request_id", payload.RequestID))
        return nil // 返回 nil 表示成功，避免重试
    }
    // 执行任务
    if err := sendEmail(ctx, payload); err != nil {
        return fmt.Errorf("发送邮件失败: %w", err) // 返回错误触发重试
    }
    // 标记任务已完成（设置过期时间，避免内存泄漏）
    rdb.SetEx(ctx, key, "1", 24*time.Hour)
    logger.Info("邮件发送成功",
        zap.String("to", payload.To),
        zap.String("request_id", payload.RequestID))
    return nil
 }
 ```
 ### Asynq 配置建议
 #### 3.4 重试策略
 ```go
 // 默认重试策略：指数退避
 task := asynq.NewTask(
    constants.TaskTypeDataSync,
    payload,
    asynq.MaxRetry(5),                    // 最大重试 5 次
    asynq.Timeout(10*time.Minute),        // 任务超时 10 分钟
    asynq.Queue("default"),               // 队列名称
    asynq.Retention(24*time.Hour),        // 保留成功任务 24 小时
 )
 // 自定义重试延迟（指数退避：1s, 2s, 4s, 8s, 16s）
 asynq.RetryDelayFunc(func(n int, e error, t *asynq.Task) time.Duration {
    return time.Duration(1<<uint(n)) * time.Second
 })
 ```
 #### 3.5 并发配置
 | 场景 | 并发数 | 理由 |
 |------|--------|------|
 | CPU 密集型任务 | CPU 核心数 | 避免上下文切换开销 |
 | I/O 密集型任务 | CPU 核心数 × 2 | 充分利用等待时间 |
 | 混合任务 | 10（默认） | 平衡性能和资源 |
 **水平扩展**：
 - 启动多个 Worker 进程（不同机器或容器）
 - 所有 Worker 连接同一个 Redis
 - Asynq 自动负载均衡
 #### 3.6 监控与调试
 ```bash
 # 安装 asynqmon（Web UI）
 go install github.com/hibiken/asynqmon@latest
 # 启动监控面板
 asynqmon --redis-addr=localhost:6379
 # 访问 http://localhost:8080
 # 查看任务状态、队列统计、失败任务、重试历史
 ```
 ---
 ## 4. 幂等性设计
 ### 4.1 为什么需要幂等性？
 **场景**：
 - 系统重启时，Asynq 自动重新排队未完成的任务
 - 任务执行失败后自动重试
 - 网络抖动导致任务重复提交
 **风险**：
 - 重复发送邮件/短信
 - 重复扣款/充值
 - 重复创建订单
 ### 4.2 幂等性实现模式
 #### 模式 1：唯一键去重（推荐）
 ```go
 func HandleOrderCreate(ctx context.Context, t *asynq.Task) error {
    var payload OrderPayload
    json.Unmarshal(t.Payload(), &payload)
    // 使用业务唯一键（如订单号）去重
    key := constants.RedisTaskLockKey(payload.OrderID)
    // SetNX：仅当 key 不存在时设置
    ok, err := rdb.SetNX(ctx, key, "1", 24*time.Hour).Result()
    if err != nil {
        return fmt.Errorf("Redis 操作失败: %w", err)
    }
    if !ok {
        logger.Info("订单已创建，跳过",
            zap.String("order_id", payload.OrderID))
        return nil // 幂等返回
    }
    // 执行业务逻辑
    if err := createOrder(ctx, payload); err != nil {
        rdb.Del(ctx, key) // 失败时删除锁，允许重试
        return err
    }
    return nil
 }
 ```
 #### 模式 2：数据库唯一约束
 ```sql
 CREATE TABLE tb_order (
    id SERIAL PRIMARY KEY,
    order_id VARCHAR(50) NOT NULL UNIQUE, -- 业务唯一键
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP NOT NULL
 );
 ```
 ```go
 func createOrder(ctx context.Context, payload OrderPayload) error {
    order := &model.Order{
        OrderID: payload.OrderID,
        Status:  constants.OrderStatusPending,
    }
    // GORM 插入，如果 order_id 重复则返回错误
    if err := db.WithContext(ctx).Create(order).Error; err != nil {
        if errors.Is(err, gorm.ErrDuplicatedKey) {
            logger.Info("订单已存在，跳过", zap.String("order_id", payload.OrderID))
            return nil // 幂等返回
        }
        return err
    }
    return nil
 }
 ```
 #### 模式 3：状态机（复杂业务）
 ```go
 func HandleOrderProcess(ctx context.Context, t *asynq.Task) error {
    var payload OrderPayload
    json.Unmarshal(t.Payload(), &payload)
    // 加载订单
    order, err := store.Order.GetByID(ctx, payload.OrderID)
    if err != nil {
        return err
    }
    // 状态检查：仅处理特定状态的订单
    if order.Status != constants.OrderStatusPending {
        logger.Info("订单状态不匹配，跳过",
            zap.String("order_id", payload.OrderID),
            zap.String("current_status", order.Status))
        return nil // 幂等返回
    }
    // 状态转换
    order.Status = constants.OrderStatusProcessing
    if err := store.Order.Update(ctx, order); err != nil {
        return err
    }
    // 执行业务逻辑
    // ...
    order.Status = constants.OrderStatusCompleted
    return store.Order.Update(ctx, order)
 }
 ```
 ---
 ## 5. 配置管理
 ### 5.1 数据库配置结构
 ```go
 // pkg/config/config.go
 type DatabaseConfig struct {
    Host            string        `mapstructure:"host"`
    Port            int           `mapstructure:"port"`
    User            string        `mapstructure:"user"`
    Password        string        `mapstructure:"password"` // 明文存储（按需求）
    DBName          string        `mapstructure:"dbname"`
    SSLMode         string        `mapstructure:"sslmode"`
    MaxOpenConns    int           `mapstructure:"max_open_conns"`
    MaxIdleConns    int           `mapstructure:"max_idle_conns"`
    ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"`
 }
 type QueueConfig struct {
    Concurrency int               `mapstructure:"concurrency"`
    Queues      map[string]int    `mapstructure:"queues"`
    RetryMax    int               `mapstructure:"retry_max"`
    Timeout     time.Duration     `mapstructure:"timeout"`
 }
 ```
 ### 5.2 配置文件示例
 ```yaml
 # configs/config.yaml
 database:
  host: localhost
  port: 5432
  user: postgres
  password: password          # 明文存储（生产环境建议使用环境变量）
  dbname: junhong_cmp
  sslmode: disable
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 5m
 queue:
  concurrency: 10
  queues:
    critical: 6
    default: 3
    low: 1
  retry_max: 5
  timeout: 10m
 ```
 ---
 ## 6. 性能优化建议
 ### 6.1 数据库查询优化
 **索引策略**：
 - 为 WHERE、JOIN、ORDER BY 常用字段添加索引
 - 复合索引按选择性从高到低排列
 - 避免过多索引（影响写入性能）
 ```sql
 -- 单列索引
 CREATE INDEX idx_user_status ON tb_user(status);
 -- 复合索引（状态 + 创建时间）
 CREATE INDEX idx_user_status_created ON tb_user(status, created_at);
 -- 部分索引（仅索引活跃用户）
 CREATE INDEX idx_user_active ON tb_user(status) WHERE status = 'active';
 ```
 **批量操作**：
 ```go
 // 避免 N+1 查询
 // ❌ 错误
 for _, orderID := range orderIDs {
    order, _ := db.Where("id = ?", orderID).First(&Order{}).Error
 }
 // ✅ 正确
 var orders []Order
 db.Where("id IN ?", orderIDs).Find(&orders)
 // 批量插入
 db.CreateInBatches(users, 100) // 每批 100 条
 ```
 ### 6.2 慢查询监控
 ```go
 // GORM 慢查询日志
 db.Logger = logger.New(
    log.New(os.Stdout, "\r\n", log.LstdFlags),
    logger.Config{
        SlowThreshold:             100 * time.Millisecond, // 慢查询阈值
        LogLevel:                  logger.Warn,
        IgnoreRecordNotFoundError: true,
        Colorful:                  false,
    },
 )
 ```
 ---
 ## 7. 故障处理与恢复
 ### 7.1 数据库连接失败
 **重试策略**：
 ```go
 func InitPostgresWithRetry(cfg *config.DatabaseConfig, logger *zap.Logger) (*gorm.DB, error) {
    maxRetries := 5
    retryDelay := 2 * time.Second
    for i := 0; i < maxRetries; i++ {
        db, err := InitPostgres(cfg, logger)
        if err == nil {
            return db, nil
        }
        logger.Warn("数据库连接失败，重试中",
            zap.Int("attempt", i+1),
            zap.Int("max_retries", maxRetries),
            zap.Error(err))
        time.Sleep(retryDelay)
        retryDelay *= 2 // 指数退避
    }
    return nil, fmt.Errorf("数据库连接失败，已重试 %d 次", maxRetries)
 }
 ```
 ### 7.2 任务队列故障恢复
 **Redis 断线重连**：
 - Asynq 自动处理 Redis 断线重连
 - Worker 重启后自动从 Redis 恢复未完成任务
 **脏任务清理**：
 ```bash
 # 使用 asynqmon 手动清理死信队列
 # 或编写定时任务自动归档失败任务
 ```
 ---
 ## 8. 测试策略
 ### 8.1 数据库集成测试
 ```go
 // tests/integration/database_test.go
 func TestUserCRUD(t *testing.T) {
    // 使用 testcontainers 启动 PostgreSQL
    ctx := context.Background()
    postgresContainer, err := postgres.RunContainer(ctx,
        testcontainers.WithImage("postgres:14"),
        postgres.WithDatabase("test_db"),
        postgres.WithUsername("postgres"),
        postgres.WithPassword("password"),
    )
    require.NoError(t, err)
    defer postgresContainer.Terminate(ctx)
    // 连接测试数据库
    connStr, _ := postgresContainer.ConnectionString(ctx)
    db, _ := gorm.Open(postgres.Open(connStr), &gorm.Config{})
    // 运行迁移
    db.AutoMigrate(&model.User{})
    // 测试 CRUD
    user := &model.User{Username: "test", Email: "test@example.com"}
    assert.NoError(t, db.Create(user).Error)
    var found model.User
    assert.NoError(t, db.Where("username = ?", "test").First(&found).Error)
    assert.Equal(t, "test@example.com", found.Email)
 }
 ```
 ### 8.2 任务队列测试
 ```go
 // tests/integration/task_test.go
 func TestEmailTask(t *testing.T) {
    // 启动内存模式的 Asynq（测试用）
    srv := asynq.NewServer(
        asynq.RedisClientOpt{Addr: "localhost:6379"},
        asynq.Config{Concurrency: 1},
    )
    mux := asynq.NewServeMux()
    mux.HandleFunc(constants.TaskTypeEmailSend, task.HandleEmailSend)
    // 提交任务
    client := asynq.NewClient(asynq.RedisClientOpt{Addr: "localhost:6379"})
    payload, _ := json.Marshal(EmailPayload{To: "test@example.com"})
    client.Enqueue(asynq.NewTask(constants.TaskTypeEmailSend, payload))
    // 启动 worker 处理
    go srv.Run(mux)
    time.Sleep(2 * time.Second)
    // 验证任务已处理
    // ...
 }
 ```
 ---
 ## 9. 安全考虑
 ### 9.1 SQL 注入防护
 **✅ GORM 自动防护**：
 ```go
 // GORM 使用预编译语句，自动转义参数
 db.Where("username = ?", userInput).First(&user)
 ```
 **❌ 避免原始 SQL**：
 ```go
 // 危险：SQL 注入风险
 db.Raw("SELECT * FROM users WHERE username = '" + userInput + "'").Scan(&user)
 // 安全：使用参数化查询
 db.Raw("SELECT * FROM users WHERE username = ?", userInput).Scan(&user)
 ```
 ### 9.2 密码存储
 ```yaml
 # configs/config.yaml
 database:
  password: ${DB_PASSWORD}  # 从环境变量读取（生产环境推荐）
 ```
 ```bash
 # .env 文件（不提交到 Git）
 export DB_PASSWORD=secret_password
 ```
 ---
 ## 10. 部署与运维
 ### 10.1 健康检查
 ```go
 // internal/handler/health.go
 func (h *Handler) HealthCheck(c *fiber.Ctx) error {
    health := map[string]string{
        "status": "ok",
    }
    // 检查 PostgreSQL
    sqlDB, _ := h.db.DB()
    if err := sqlDB.Ping(); err != nil {
        health["postgres"] = "down"
        health["status"] = "degraded"
    } else {
        health["postgres"] = "up"
    }
    // 检查 Redis（任务队列）
    if err := h.rdb.Ping(c.Context()).Err(); err != nil {
        health["redis"] = "down"
        health["status"] = "degraded"
    } else {
        health["redis"] = "up"
    }
    statusCode := fiber.StatusOK
    if health["status"] != "ok" {
        statusCode = fiber.StatusServiceUnavailable
    }
    return c.Status(statusCode).JSON(health)
 }
 ```
 ### 10.2 优雅关闭
 ```go
 // cmd/worker/main.go
 func main() {
    // ... 初始化
    srv := queue.NewServer(rdb, cfg.Queue, logger)
    // 处理信号
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    go func() {
        <-quit
        logger.Info("收到关闭信号，开始优雅关闭")
        // 停止接收新任务，等待现有任务完成（最多 30 秒）
        srv.Shutdown()
    }()
    // 启动 Worker
    if err := srv.Run(mux); err != nil {
        logger.Fatal("Worker 运行失败", zap.Error(err))
    }
 }
 ```
 ---
 ## 总结
 | 技术选型 | 关键决策 | 核心理由 |
 |---------|----------|----------|
 | **GORM** | 使用 GORM 而非 sqlx | 功能完整，符合项目技术栈 |
 | **golang-migrate** | 使用外部迁移工具而非 AutoMigrate | 版本控制，可回滚，生产安全 |
 | **Asynq** | 使用 Asynq 而非 Machinery | Redis 原生，功能完整，监控友好 |
 | **连接池** | MaxOpenConns=25, MaxIdleConns=10 | 平衡性能和资源消耗 |
 | **重试策略** | 最大 5 次，指数退避 | 避免雪崩，给系统恢复时间 |
 | **幂等性** | Redis 去重 + 数据库唯一约束 | 防止重复执行，确保数据一致性 |
 **下一步**：Phase 1 设计与契约生成（data-model.md、contracts/、quickstart.md）
--- a/specs/002-gorm-postgres-asynq/spec.md
+++ b/specs/002-gorm-postgres-asynq/spec.md
@@ -0,0 +1,194 @@
 # Feature Specification: 数据持久化与异步任务处理集成
 **Feature Branch**: `002-gorm-postgres-asynq`  
 **Created**: 2025-11-12  
 **Status**: Draft  
 **Input**: User description: "集成gorm、Postgresql数据库和asynq任务队列系统"
 ## Clarifications
 ### Session 2025-11-12
 - Q: PostgreSQL连接应如何处理凭证管理和传输安全? → A: 凭证直接写在配置文件(config.yaml)中,明文存储
 - Q: 任务失败后应该如何重试? → A: 最大重试5次,指数退避策略(1s、2s、4s、8s、16s)
 - Q: 数据库表结构的创建和变更应该如何执行? → A: 完全不使用GORM迁移,使用外部迁移工具(如golang-migrate)管理SQL迁移文件
 - Q: Worker进程应该如何配置并发任务处理? → A: 支持多个worker进程,每个进程可配置并发数(默认10);不同任务类型可配置独立的队列优先级
 - Q: 系统重启时,正在执行中或排队中的任务应该如何处理? → A: 所有未完成任务(包括执行中)自动重新排队,重启后继续执行;任务处理逻辑需保证幂等性
 ### Session 2025-11-13
 - Q: 数据库慢查询(>100ms)和任务执行状态应该如何进行监控和指标收集? → A: 仅记录日志文件,不收集指标
 - Q: 当数据库连接池耗尽时,新的数据库请求应该如何处理? → A: 请求排队等待直到获得连接(带超时,如5秒)
 - Q: 当数据库执行慢查询时,系统应该如何避免请求超时? → A: 使用context超时控制(如3秒),超时后取消查询
 - Q: 当PostgreSQL主从切换时,系统应该如何感知并重新连接? → A: 依赖GORM的自动重连机制,连接失败时重试
 - Q: 当并发事务产生死锁时,系统应该如何检测和恢复? → A: 依赖PostgreSQL自动检测,捕获死锁错误并重试(最多3次)
 ## User Scenarios & Testing *(mandatory)*
 ### User Story 1 - 可靠的数据存储与检索 (Priority: P1)
 作为系统,需要能够可靠地持久化存储业务数据(如用户信息、业务记录等),并支持高效的数据查询和修改操作,确保数据的一致性和完整性。
 **Why this priority**: 这是系统的核心基础能力,没有数据持久化就无法提供任何有意义的业务功能。所有后续功能都依赖于数据存储能力。
 **Independent Test**: 可以通过创建、读取、更新、删除(CRUD)测试数据来独立验证。测试应包括基本的数据操作、事务提交、数据一致性验证等场景。
 **Acceptance Scenarios**:
 1. **Given** 系统接收到新的业务数据, **When** 执行数据保存操作, **Then** 数据应成功持久化到数据库,并可以被后续查询检索到
 2. **Given** 需要修改已存在的数据, **When** 执行更新操作, **Then** 数据应被正确更新,且旧数据被新数据替换
 3. **Given** 需要删除数据, **When** 执行删除操作, **Then** 数据应从数据库中移除,后续查询不应返回该数据
 4. **Given** 多个数据操作需要原子性执行, **When** 在事务中执行这些操作, **Then** 要么全部成功提交,要么全部回滚,保证数据一致性
 5. **Given** 执行数据查询, **When** 查询条件匹配多条记录, **Then** 系统应返回所有匹配的记录,支持分页和排序
 ---
 ### User Story 2 - 异步任务处理能力 (Priority: P2)
 作为系统,需要能够将耗时的操作(如发送邮件、生成报表、数据同步等)放到后台异步执行,避免阻塞用户请求,提升用户体验和系统响应速度。
 **Why this priority**: 许多业务操作需要较长时间完成,如果在用户请求中同步执行会导致超时和糟糕的用户体验。异步任务处理是提升系统性能和用户体验的关键。
 **Independent Test**: 可以通过提交一个耗时任务(如模拟发送邮件),验证任务被成功加入队列,然后在后台完成执行,用户请求立即返回而不等待任务完成。
 **Acceptance Scenarios**:
 1. **Given** 系统需要执行一个耗时操作, **When** 将任务提交到任务队列, **Then** 任务应被成功加入队列,用户请求立即返回,不阻塞等待
 2. **Given** 任务队列中有待处理的任务, **When** 后台工作进程运行, **Then** 任务应按顺序被取出并执行
 3. **Given** 任务执行过程中发生错误, **When** 任务失败, **Then** 系统应记录错误信息,并根据配置进行重试
 4. **Given** 任务需要定时执行, **When** 到达指定时间, **Then** 任务应自动触发执行
 5. **Given** 需要查看任务执行状态, **When** 查询任务信息, **Then** 应能获取任务的当前状态(等待、执行中、成功、失败)和执行历史
 ---
 ### User Story 3 - 数据库连接管理与监控 (Priority: P3)
 作为系统管理员,需要能够监控数据库连接状态、查询性能和任务队列健康度,及时发现和解决潜在问题,确保系统稳定运行。
 **Why this priority**: 虽然不是核心业务功能,但对系统的稳定性和可维护性至关重要。良好的监控能力可以预防故障和提升运维效率。
 **Independent Test**: 可以通过健康检查接口验证数据库连接状态和任务队列状态,模拟连接失败场景验证系统的容错能力。
 **Acceptance Scenarios**:
 1. **Given** 系统启动时, **When** 初始化数据库连接池, **Then** 应成功建立连接,并验证数据库可访问性
 2. **Given** 数据库连接出现问题, **When** 检测到连接失败, **Then** 系统应记录错误日志,并尝试重新建立连接
 3. **Given** 需要监控系统健康状态, **When** 调用健康检查接口, **Then** 应返回数据库和任务队列的当前状态(正常/异常)
 4. **Given** 系统关闭时, **When** 执行清理操作, **Then** 应优雅地关闭数据库连接和任务队列,等待正在执行的任务完成
 ---
 ### Edge Cases
 - 当数据库连接池耗尽时,新的数据库请求会排队等待可用连接,等待超时时间为5秒。超时后返回503 Service Unavailable错误,错误消息提示"数据库连接池繁忙,请稍后重试"
 - 当任务队列积压过多任务(超过 10,000 个待处理任务或 Redis 内存使用超过 80%)时,系统应触发告警,并考虑暂停低优先级任务提交或扩展 Worker 进程数量
 - 当数据库执行慢查询时,系统使用context.WithTimeout为每个数据库操作设置超时时间(默认3秒)。超时后自动取消查询并返回504 Gateway Timeout错误,错误消息提示"数据库查询超时,请优化查询条件或联系管理员"
 - 当任务重复执行5次后仍然失败时,任务应被标记为"最终失败"状态,记录完整错误历史,并可选择发送告警通知或进入死信队列等待人工处理
 - 当PostgreSQL主从切换时,系统依赖GORM的自动重连机制。当检测到连接失败或不可用时,GORM会自动尝试重新建立连接。失败的查询会返回数据库连接错误,应用层应在合理范围内进行重试(建议重试1-3次,每次间隔100ms)
 - 当并发事务产生死锁时,PostgreSQL会自动检测并中止其中一个事务(返回SQLSTATE 40P01错误)。应用层捕获死锁错误后,应自动重试该事务(建议最多重试3次,每次间隔50-100ms随机延迟)。超过重试次数后,返回409 Conflict错误,提示"数据库操作冲突,请稍后重试"
 - 当系统重启时,所有未完成的任务(包括排队中和执行中的任务)会利用Asynq的Redis持久化机制自动重新排队,重启后Worker进程会继续处理这些任务。所有任务处理逻辑必须设计为幂等操作,确保任务重复执行不会产生副作用或数据不一致
 ## Requirements *(mandatory)*
 ### Functional Requirements
 - **FR-001**: 系统必须能够建立和管理与PostgreSQL数据库的连接池,支持配置最大连接数、空闲连接数等参数。数据库连接配置(包括主机地址、端口、用户名、密码、数据库名)存储在配置文件(config.yaml)中,明文形式保存。当连接池耗尽时,新请求排队等待可用连接(默认超时5秒),超时后返回503错误。系统依赖GORM的自动重连机制处理数据库连接失败或主从切换场景
 - **FR-002**: 系统必须支持标准的CRUD操作(创建、读取、更新、删除),并提供统一的数据访问接口。接口应包括但不限于: Create(创建记录)、GetByID(按ID查询)、Update(更新记录)、Delete(软删除)、List(分页列表查询)等基础方法,所有 Store 层接口遵循一致的命名和参数约定(详见 data-model.md)
 - **FR-003**: 系统必须支持数据库事务,包括事务的开始、提交、回滚操作,确保数据一致性。当发生死锁时(SQLSTATE 40P01),系统应捕获错误并自动重试事务(最多3次,每次间隔50-100ms随机延迟),超过重试次数后返回409错误
 - **FR-004**: 系统必须支持数据库迁移,使用外部迁移工具(如golang-migrate)通过版本化的SQL迁移文件管理表结构的创建和变更,不使用GORM AutoMigrate功能。迁移文件应包含up/down脚本以支持正向迁移和回滚
 - **FR-005**: 系统必须提供查询构建能力,支持条件查询、分页、排序、关联查询等常见操作。所有数据库查询必须使用context.WithTimeout设置超时时间(默认3秒),超时后自动取消查询并返回504错误
 - **FR-006**: 系统必须能够将任务提交到异步任务队列,任务应包含任务类型、参数、优先级等信息
 - **FR-007**: 系统必须提供后台工作进程,从任务队列中获取任务并执行。支持启动多个worker进程实例,每个进程可独立配置并发处理数(默认10个并发goroutine)。不同任务类型可配置到不同的队列,并设置队列优先级,实现资源隔离和灵活扩展。Worker 进程异常退出时,Asynq 会自动将执行中的任务标记为失败并重新排队;建议使用进程管理工具(如 systemd, supervisord)实现 Worker 自动重启
 - **FR-008**: 系统必须支持任务重试机制,当任务执行失败时能够按配置的策略自动重试。默认最大重试5次,采用指数退避策略(重试间隔为1s、2s、4s、8s、16s),每个任务类型可独立配置重试参数
 - **FR-009**: 系统必须支持任务优先级,高优先级任务应优先被处理
 - **FR-010**: 系统必须能够记录任务执行历史和状态,包括开始时间、结束时间、执行结果、错误信息等。任务执行状态通过日志文件记录,不使用外部指标收集系统
 - **FR-011**: 系统必须提供健康检查接口,能够验证数据库连接和任务队列的可用性
 - **FR-012**: 系统必须支持定时任务,能够按照cron表达式或固定间隔调度任务执行
 - **FR-013**: 系统必须记录慢查询日志,当数据库查询超过阈值(100ms)时记录详细信息用于优化。日志应包含 SQL 语句、执行时间、参数和上下文信息。监控采用日志文件方式,不使用 Prometheus 或其他指标收集系统
 - **FR-014**: 系统必须支持配置化的数据库和任务队列参数,如连接字符串、最大重试次数、任务超时时间等
 - **FR-015**: 系统必须在关闭时优雅地清理资源,关闭数据库连接并等待正在执行的任务完成
 - **FR-016**: 系统必须支持任务持久化和故障恢复。利用Asynq基于Redis的持久化机制,确保系统重启或崩溃时未完成的任务不会丢失。所有任务处理函数必须设计为幂等操作,支持任务重新执行而不产生副作用
 ### Technical Requirements (Constitution-Driven)
 **Tech Stack Compliance**:
 - [x] 所有数据库操作使用GORM (不直接使用 `database/sql`)
 - [x] 数据库迁移使用golang-migrate (不使用GORM AutoMigrate)
 - [x] 所有异步任务使用Asynq
 - [x] 所有HTTP操作使用Fiber框架 (不使用 `net/http`)
 - [x] 所有JSON操作使用sonic (不使用 `encoding/json`)
 - [x] 所有日志使用Zap + Lumberjack.v2
 - [x] 所有配置使用Viper
 - [x] 使用Go官方工具链: `go fmt`, `go vet`, `golangci-lint`
 **Architecture Requirements**:
 - [x] 实现遵循 Handler → Service → Store → Model 分层架构
 - [x] 依赖通过结构体字段注入(不使用构造函数模式)
 - [x] 统一错误码定义在 `pkg/errors/`
 - [x] 统一API响应通过 `pkg/response/`
 - [x] 所有常量定义在 `pkg/constants/` (不使用魔法数字/字符串)
 - [x] **不允许硬编码值: 3次及以上相同字面量必须定义为常量**
 - [x] **已定义的常量必须使用(不允许重复硬编码)**
 - [x] **代码注释优先使用中文(实现注释用中文)**
 - [x] **日志消息使用中文(logger.Info/Warn/Error/Debug用中文)**
 - [x] **错误消息支持中文(面向用户的错误有中文文本)**
 - [x] 所有Redis键通过 `pkg/constants/` 键生成函数管理
 - [x] 包结构扁平化,按功能组织(不按层级)
 **Go Idiomatic Design Requirements**:
 - [x] 不使用Java风格模式: 无getter/setter方法、无I-前缀接口、无Impl-后缀
 - [x] 接口应小型化(1-3个方法),在使用处定义
 - [x] 错误处理显式化(返回错误,不使用panic)
 - [x] 使用组合(结构体嵌入)而非继承
 - [x] 使用goroutines和channels处理并发
 - [x] 命名遵循Go约定: `UserID` 不是 `userId`, `HTTPServer` 不是 `HttpServer`
 - [x] 不使用匈牙利命名法或类型前缀
 - [x] 代码结构简单直接
 **API Design Requirements**:
 - [x] 所有API遵循RESTful原则
 - [x] 所有响应使用统一JSON格式,包含code/message/data/timestamp
 - [x] 所有错误消息包含错误码和双语描述
 - [x] 所有分页使用标准参数(page, page_size, total)
 - [x] 所有时间字段使用ISO 8601格式(RFC3339)
 - [x] 所有货币金额使用整数(分)
 **Performance Requirements**:
 - [x] API响应时间(P95) < 200ms
 - [x] 数据库查询 < 50ms
 - [x] 批量操作使用bulk查询
 - [x] 列表查询实现分页(默认20条,最大100条)
 - [x] 非实时操作委托给异步任务
 - [x] 使用 `context.Context` 进行超时和取消控制
 **Testing Requirements**:
 - [x] Service层业务逻辑必须有单元测试
 - [x] 所有API端点必须有集成测试
 - [x] 所有异步任务处理函数必须有幂等性测试,验证重复执行的正确性
 - [x] 测试使用Go标准testing框架,文件名为 `*_test.go`
 - [x] 多测试用例使用表驱动测试
 - [x] 测试相互独立,使用mocks/testcontainers
 - [x] 目标覆盖率: 总体70%+, 核心业务逻辑90%+
 ### Key Entities
 - **DatabaseConnection**: 代表与PostgreSQL数据库的连接,包含连接池配置、连接状态、健康检查等属性
 - **DataModel**: 代表业务数据模型,通过ORM映射到数据库表,包含数据验证规则和关联关系
 - **Task**: 代表异步任务,包含任务类型、任务参数、优先级、重试次数、执行状态等属性
 - **TaskQueue**: 代表任务队列,管理任务的提交、调度、执行和状态跟踪
 - **Worker**: 代表后台工作进程,从任务队列中获取任务并执行。每个Worker进程支持可配置的并发数(通过goroutine池实现),可以部署多个Worker进程实例实现水平扩展。不同Worker可订阅不同的任务队列,实现任务类型的资源隔离
 ## Success Criteria *(mandatory)*
 ### Measurable Outcomes
 - **SC-001**: 数据库基本CRUD操作响应时间(P95)应小于50毫秒
 - **SC-002**: 系统应支持至少1000个并发数据库连接而不出现连接池耗尽
 - **SC-003**: 任务队列应能够处理每秒至少100个任务的提交速率
 - **SC-004**: 异步任务从提交到开始执行的延迟(空闲情况下)应小于100毫秒
 - **SC-005**: 数据持久化的可靠性应达到99.99%,即每10000次操作中失败不超过1次
 - **SC-006**: 失败任务的自动重试成功率应达到90%以上
 - **SC-007**: 系统启动时应在10秒内完成数据库连接和任务队列初始化
 - **SC-008**: 数据库查询慢查询(超过100ms)的占比应小于1%
 - **SC-009**: 系统关闭时应在30秒内优雅完成所有资源清理,不丢失正在执行的任务
 - **SC-010**: 健康检查接口应在1秒内返回系统健康状态
--- a/specs/002-gorm-postgres-asynq/tasks.md
+++ b/specs/002-gorm-postgres-asynq/tasks.md
@@ -0,0 +1,393 @@
 # Tasks: 数据持久化与异步任务处理集成
 **Feature**: 002-gorm-postgres-asynq  
 **Input**: Design documents from `/specs/002-gorm-postgres-asynq/`  
 **Prerequisites**: plan.md, spec.md, data-model.md, contracts/api.yaml, research.md, quickstart.md
 **Organization**: Tasks are grouped by user story (US1: 数据存储与检索, US2: 异步任务处理, US3: 连接管理与监控) to enable independent implementation and testing.
 ## Format: `[ID] [P?] [Story] Description`
 - **[P]**: Can run in parallel (different files, no dependencies)
 - **[Story]**: Which user story this task belongs to (US1, US2, US3)
 - Include exact file paths in descriptions
 ---
 ## Phase 1: Setup (Shared Infrastructure)
 **Purpose**: Project initialization and basic structure (project already exists, validate/enhance)
 - [ ] T001 Validate project structure matches plan.md (internal/, pkg/, cmd/, configs/, migrations/, tests/)
 - [ ] T002 Validate Go dependencies for Fiber + GORM + Asynq + Viper + Zap + golang-migrate
 - [ ] T003 [P] Validate unified error codes in pkg/errors/codes.go and pkg/errors/errors.go
 - [ ] T004 [P] Validate unified API response in pkg/response/response.go
 - [ ] T005 [P] Add database configuration constants in pkg/constants/constants.go (DefaultMaxOpenConns=25, DefaultMaxIdleConns=10, etc.)
 - [ ] T006 [P] Add task queue constants in pkg/constants/constants.go (TaskTypeEmailSend, TaskTypeDataSync, QueueCritical, QueueDefault, etc.)
 - [ ] T007 [P] Add user/order status constants in pkg/constants/constants.go (UserStatusActive, OrderStatusPending, etc.)
 - [ ] T008 [P] Add Redis key generation functions in pkg/constants/redis.go (RedisTaskLockKey, RedisTaskStatusKey)
 ---
 ## Phase 2: Foundational (Blocking Prerequisites)
 **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
 **⚠️ CRITICAL**: No user story work can begin until this phase is complete
 - [ ] T009 Implement PostgreSQL connection initialization in pkg/database/postgres.go (GORM + connection pool)
 - [ ] T010 Validate Redis connection initialization in pkg/database/redis.go (connection pool: PoolSize=10, MinIdleConns=5)
 - [ ] T011 [P] Add DatabaseConfig to pkg/config/config.go (Host, Port, User, Password, MaxOpenConns, MaxIdleConns, ConnMaxLifetime)
 - [ ] T012 [P] Add QueueConfig to pkg/config/config.go (Concurrency, Queues, RetryMax, Timeout)
 - [ ] T013 [P] Update config.yaml files with database and queue configurations (config.dev.yaml, config.staging.yaml, config.prod.yaml)
 - [ ] T014 Implement Asynq client initialization in pkg/queue/client.go (EnqueueTask with logging)
 - [ ] T015 Implement Asynq server initialization in pkg/queue/server.go (with queue priorities and error handler)
 - [ ] T016 Create base Store structure in internal/store/store.go with transaction support
 - [ ] T017 Initialize postgres store in internal/store/postgres/store.go (embed UserStore, OrderStore)
 - [ ] T018 Validate migrations directory structure (migrations/000001_init_schema.up.sql and .down.sql exist)
 **Checkpoint**: Foundation ready - user story implementation can now begin in parallel
 ---
 ## Phase 3: User Story 1 - 可靠的数据存储与检索 (Priority: P1) 🎯 MVP
 **Goal**: 实现可靠的数据持久化存储和高效的 CRUD 操作，确保数据一致性和完整性
 **Independent Test**: 通过创建、读取、更新、删除用户和订单数据验证。包括基本 CRUD、事务提交、数据一致性验证等场景。
 ### Tests for User Story 1 (REQUIRED per Constitution)
 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
 - [ ] T019 [P] [US1] Unit tests for User Store layer in tests/unit/store_test.go (Create, GetByID, Update, Delete, List)
 - [ ] T020 [P] [US1] Unit tests for Order Store layer in tests/unit/store_test.go (Create, GetByID, Update, Delete, ListByUserID)
 - [ ] T021 [P] [US1] Unit tests for User Service layer in tests/unit/service_test.go (business logic validation)
 - [ ] T022 [P] [US1] Integration tests for User API endpoints in tests/integration/database_test.go (POST/GET/PUT/DELETE /users)
 - [ ] T023 [P] [US1] Transaction rollback tests in tests/unit/store_test.go (verify atomic operations)
 ### Implementation for User Story 1
 **Models & DTOs**:
 - [ ] T024 [P] [US1] Validate BaseModel in internal/model/base.go (ID, CreatedAt, UpdatedAt, DeletedAt)
 - [ ] T025 [P] [US1] Validate User model in internal/model/user.go with GORM tags (Username, Email, Password, Status)
 - [ ] T026 [P] [US1] Validate Order model in internal/model/order.go with GORM tags (OrderID, UserID, Amount, Status)
 - [ ] T027 [P] [US1] Validate User DTOs in internal/model/user_dto.go (CreateUserRequest, UpdateUserRequest, UserResponse, ListUsersResponse)
 - [ ] T028 [P] [US1] Create Order DTOs in internal/model/order_dto.go (CreateOrderRequest, UpdateOrderRequest, OrderResponse, ListOrdersResponse)
 **Store Layer (Data Access)**:
 - [ ] T029 [US1] Implement UserStore in internal/store/postgres/user_store.go (Create, GetByID, Update, Delete, List with pagination)
 - [ ] T030 [US1] Implement OrderStore in internal/store/postgres/order_store.go (Create, GetByID, Update, Delete, ListByUserID)
 - [ ] T031 [US1] Add context timeout handling (3s default) and slow query logging (>100ms) in Store methods
 **Service Layer (Business Logic)**:
 - [ ] T032 [US1] Implement UserService in internal/service/user/service.go (CreateUser, GetUserByID, UpdateUser, DeleteUser, ListUsers)
 - [ ] T033 [US1] Implement OrderService in internal/service/order/service.go (CreateOrder, GetOrderByID, UpdateOrder, DeleteOrder, ListOrdersByUserID)
 - [ ] T034 [US1] Add password hashing (bcrypt) in UserService.CreateUser
 - [ ] T035 [US1] Add validation logic in Service layer using Validator
 - [ ] T036 [US1] Implement transaction example in OrderService (CreateOrderWithUser)
 **Handler Layer (HTTP Endpoints)**:
 - [ ] T037 [US1] Validate/enhance User Handler in internal/handler/user.go (Create, GetByID, Update, Delete, List endpoints)
 - [ ] T038 [US1] Create Order Handler in internal/handler/order.go (Create, GetByID, Update, Delete, List endpoints)
 - [ ] T039 [US1] Add request validation using Validator in handlers
 - [ ] T040 [US1] Add unified error handling using pkg/errors/ and pkg/response/ in handlers
 - [ ] T041 [US1] Add structured logging with Zap in handlers (log user_id, order_id, operation, duration)
 - [ ] T042 [US1] Register User routes in cmd/api/main.go (POST/GET/PUT/DELETE /api/v1/users, /api/v1/users/:id)
 - [ ] T043 [US1] Register Order routes in cmd/api/main.go (POST/GET/PUT/DELETE /api/v1/orders, /api/v1/orders/:id)
 **Database Migrations**:
 - [ ] T044 [US1] Validate migration 000001_init_schema.up.sql (tb_user and tb_order tables with indexes)
 - [ ] T045 [US1] Validate migration 000001_init_schema.down.sql (DROP tables)
 - [ ] T046 [US1] Test migration up/down with scripts/migrate.sh
 **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
 ---
 ## Phase 4: User Story 2 - 异步任务处理能力 (Priority: P2)
 **Goal**: 实现耗时操作的后台异步执行，避免阻塞用户请求，提升系统响应速度
 **Independent Test**: 提交耗时任务（如发送邮件），验证任务被成功加入队列，用户请求立即返回，后台 Worker 完成任务执行。
 ### Tests for User Story 2 (REQUIRED per Constitution)
 - [ ] T047 [P] [US2] Unit tests for Email task handler in tests/unit/task_handler_test.go (HandleEmailSend idempotency)
 - [ ] T048 [P] [US2] Unit tests for Sync task handler in tests/unit/task_handler_test.go (HandleDataSync idempotency)
 - [ ] T049 [P] [US2] Integration tests for task submission in tests/integration/task_test.go (EnqueueEmailTask, EnqueueSyncTask)
 - [ ] T050 [P] [US2] Integration tests for task queue in tests/integration/task_test.go (verify Worker processes tasks)
 ### Implementation for User Story 2
 **Task Payloads**:
 - [ ] T051 [P] [US2] Validate EmailPayload in internal/task/email.go (RequestID, To, Subject, Body, CC, Attachments)
 - [ ] T052 [P] [US2] Validate DataSyncPayload in internal/task/sync.go (RequestID, SyncType, StartDate, EndDate, BatchSize)
 - [ ] T053 [P] [US2] Create SIMStatusSyncPayload in internal/task/sim.go (RequestID, ICCIDs, ForceSync)
 **Task Handlers (Worker)**:
 - [ ] T054 [US2] Implement HandleEmailSend in internal/task/email.go (with Redis idempotency lock and retry)
 - [ ] T055 [US2] Implement HandleDataSync in internal/task/sync.go (with idempotency and batch processing)
 - [ ] T056 [US2] Implement HandleSIMStatusSync in internal/task/sim.go (with idempotency)
 - [ ] T057 [US2] Add structured logging in task handlers (task_id, task_type, request_id, duration)
 - [ ] T058 [US2] Add error handling and retry logic in task handlers (max 5 retries, exponential backoff)
 **Service Integration**:
 - [ ] T059 [US2] Implement EmailService in internal/service/email/service.go (SendWelcomeEmail, EnqueueEmailTask)
 - [ ] T060 [US2] Implement SyncService in internal/service/sync/service.go (EnqueueDataSyncTask, EnqueueSIMStatusSyncTask)
 - [ ] T061 [US2] Add Queue Client dependency injection in Service constructors
 **Handler Layer (Task Submission)**:
 - [ ] T062 [US2] Validate/enhance Task Handler in internal/handler/task.go (SubmitEmailTask, SubmitSyncTask endpoints)
 - [ ] T063 [US2] Add request validation for task payloads in handler
 - [ ] T064 [US2] Add priority queue selection logic (critical/default/low) in handler
 - [ ] T065 [US2] Register task routes in cmd/api/main.go (POST /api/v1/tasks/email, POST /api/v1/tasks/sync)
 **Worker Process**:
 - [ ] T066 [US2] Validate Worker main in cmd/worker/main.go (initialize Server, register handlers, graceful shutdown)
 - [ ] T067 [US2] Register task handlers in Worker (HandleEmailSend, HandleDataSync, HandleSIMStatusSync)
 - [ ] T068 [US2] Add signal handling for graceful shutdown in Worker (SIGINT, SIGTERM)
 **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
 ---
 ## Phase 5: User Story 3 - 数据库连接管理与监控 (Priority: P3)
 **Goal**: 监控数据库连接状态、查询性能和任务队列健康度，确保系统稳定运行
 **Independent Test**: 通过健康检查接口验证数据库和 Redis 连接状态，模拟连接失败场景验证容错能力。
 ### Tests for User Story 3 (REQUIRED per Constitution)
 - [ ] T069 [P] [US3] Integration tests for health check in tests/integration/health_test.go (GET /health returns 200 when healthy)
 - [ ] T070 [P] [US3] Integration tests for degraded state in tests/integration/health_test.go (503 when database down)
 - [ ] T071 [P] [US3] Unit tests for graceful shutdown in tests/unit/shutdown_test.go (verify connections closed)
 ### Implementation for User Story 3
 **Health Check**:
 - [ ] T072 [US3] Validate/enhance Health Handler in internal/handler/health.go (check PostgreSQL and Redis status)
 - [ ] T073 [US3] Add database Ping check with timeout in Health Handler
 - [ ] T074 [US3] Add Redis Ping check with timeout in Health Handler
 - [ ] T075 [US3] Return appropriate status codes (200 ok, 503 degraded/unavailable)
 - [ ] T076 [US3] Register health route in cmd/api/main.go (GET /health)
 **Connection Management**:
 - [ ] T077 [US3] Add connection pool monitoring in pkg/database/postgres.go (log Stats: OpenConnections, InUse, Idle)
 - [ ] T078 [US3] Add connection retry logic in pkg/database/postgres.go (max 5 retries, exponential backoff)
 - [ ] T079 [US3] Add slow query logging middleware in pkg/logger/middleware.go (log queries >100ms)
 **Graceful Shutdown**:
 - [ ] T080 [US3] Implement graceful shutdown in cmd/api/main.go (close DB, Redis, wait for requests, max 30s timeout)
 - [ ] T081 [US3] Validate graceful shutdown in cmd/worker/main.go (stop accepting tasks, wait for completion, max 30s)
 - [ ] T082 [US3] Add signal handling (SIGINT, SIGTERM) in both API and Worker processes
 **Checkpoint**: All user stories should now be independently functional
 ---
 ## Phase 6: Polish & Quality Gates
 **Purpose**: Improvements that affect multiple user stories and final quality checks
 ### Documentation (Constitution Principle VII - REQUIRED)
 - [ ] T083 [P] Create feature summary doc in docs/002-gorm-postgres-asynq/功能总结.md (Chinese filename and content)
 - [ ] T084 [P] Create usage guide in docs/002-gorm-postgres-asynq/使用指南.md (Chinese filename and content)
 - [ ] T085 [P] Create architecture doc in docs/002-gorm-postgres-asynq/架构说明.md (Chinese filename and content)
 - [ ] T086 Update README.md with brief feature description (2-3 sentences in Chinese)
 ### Code Quality
 - [ ] T087 Code cleanup: Remove unused imports, variables, and functions
 - [ ] T088 Code refactoring: Extract duplicate logic into helper functions
 - [ ] T089 Performance optimization: Add database indexes for common queries (username, email, order_id, user_id, status)
 - [ ] T090 Performance testing: Verify API response time P95 < 200ms, P99 < 500ms
 - [ ] T091 [P] Additional unit tests to reach 70%+ overall coverage, 90%+ for Service layer
 - [ ] T092 Security audit: Verify no SQL injection (GORM uses prepared statements)
 - [ ] T093 Security audit: Verify password storage uses bcrypt hashing
 - [ ] T094 Security audit: Verify sensitive data not logged (passwords, tokens)
 - [ ] T095 Run quickstart.md validation (test all curl examples work)
 ### Quality Gates (Constitution Compliance)
 - [ ] T096 Quality Gate: Run `go test ./...` (all tests pass)
 - [ ] T097 Quality Gate: Run `gofmt -l .` (no formatting issues)
 - [ ] T098 Quality Gate: Run `go vet ./...` (no issues)
 - [ ] T099 Quality Gate: Run `golangci-lint run` (no critical issues)
 - [ ] T100 Quality Gate: Verify test coverage with `go test -cover ./...` (70%+ overall, 90%+ Service)
 - [ ] T101 Quality Gate: Check no TODO/FIXME remains (or documented in GitHub issues)
 - [ ] T102 Quality Gate: Verify database migrations work (up and down)
 - [ ] T103 Quality Gate: Verify API documentation in contracts/api.yaml matches implementation
 - [ ] T104 Quality Gate: Verify no hardcoded constants (all use pkg/constants/)
 - [ ] T105 Quality Gate: Verify no duplicate hardcoded values (3+ identical literals must be constants)
 - [ ] T106 Quality Gate: Verify defined constants are used (no duplicate hardcoding)
 - [ ] T107 Quality Gate: Verify code comments use Chinese (implementation comments in Chinese)
 - [ ] T108 Quality Gate: Verify log messages use Chinese (logger.Info/Warn/Error/Debug in Chinese)
 - [ ] T109 Quality Gate: Verify error messages support Chinese (user-facing errors have Chinese text)
 - [ ] T110 Quality Gate: Verify no Java-style patterns (no getter/setter, no I-prefix, no Impl-suffix)
 - [ ] T111 Quality Gate: Verify Go naming conventions (UserID not userId, HTTPServer not HttpServer)
 - [ ] T112 Quality Gate: Verify error handling is explicit (no panic/recover in business logic)
 - [ ] T113 Quality Gate: Verify uses goroutines/channels for concurrency (not thread pools)
 - [ ] T114 Quality Gate: Verify no ORM associations (foreignKey, belongsTo tags - use manual joins)
 - [ ] T115 Quality Gate: Verify feature docs created in docs/002-gorm-postgres-asynq/ with Chinese filenames
 - [ ] T116 Quality Gate: Verify summary doc content uses Chinese
 - [ ] T117 Quality Gate: Verify README.md updated with brief description
 - [ ] T118 Quality Gate: Verify ALL HTTP requests logged to access.log (via pkg/logger/Middleware())
 - [ ] T119 Quality Gate: Verify access log includes request/response bodies (limited to 50KB)
 - [ ] T120 Quality Gate: Verify no middleware bypasses logging (test auth failures, rate limits)
 - [ ] T121 Quality Gate: Verify access log has all required fields (method, path, status, duration_ms, request_id, ip, user_agent, request_body, response_body)
 ---
 ## Dependencies & Execution Order
 ### Phase Dependencies
 - **Setup (Phase 1)**: No dependencies - can start immediately
 - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
 - **User Stories (Phase 3-5)**: All depend on Foundational phase completion
  - User Story 1 (P1): Can start after Foundational - No dependencies on other stories
  - User Story 2 (P2): Can start after Foundational - Independent (may integrate with US1 for examples)
  - User Story 3 (P3): Can start after Foundational - Independent
 - **Polish (Phase 6)**: Depends on all user stories being complete
 ### User Story Independence
 - **US1 (P1)**: Fully independent - can be tested and deployed alone (MVP)
 - **US2 (P2)**: Fully independent - can be tested and deployed alone (may reference US1 models as examples)
 - **US3 (P3)**: Fully independent - can be tested and deployed alone
 ### Within Each User Story
 - Tests MUST be written and FAIL before implementation
 - Models → Store → Service → Handler → Routes
 - Core implementation before integration
 - Story complete before moving to next priority
 ### Parallel Opportunities
 **Phase 1 (Setup)**:
 - T003, T004, T005, T006, T007, T008 can all run in parallel
 **Phase 2 (Foundational)**:
 - T011, T012, T013 (config) can run in parallel
 - T014, T015 (queue client/server) can run in parallel after config
 **Phase 3 (User Story 1)**:
 - T019-T023 (all tests) can run in parallel
 - T024-T028 (all models/DTOs) can run in parallel
 - T029, T030 (Store implementations) can run in parallel after models
 - T032, T033 (Service implementations) can run in parallel after Store
 **Phase 4 (User Story 2)**:
 - T047-T050 (all tests) can run in parallel
 - T051-T053 (all payloads) can run in parallel
 - T054-T056 (all task handlers) can run in parallel after payloads
 - T059, T060 (Service implementations) can run in parallel after handlers
 **Phase 5 (User Story 3)**:
 - T069-T071 (all tests) can run in parallel
 - T073, T074 (Ping checks) can run in parallel
 - T077, T078, T079 (connection management) can run in parallel
 **Phase 6 (Polish)**:
 - T083-T085 (all docs) can run in parallel
 - T096-T121 (quality gates) run sequentially but can be automated in CI
 ---
 ## Parallel Example: User Story 1
 ```bash
 # Launch all tests together:
 go test -v tests/unit/store_test.go &       # T019, T020
 go test -v tests/unit/service_test.go &     # T021
 go test -v tests/integration/database_test.go &  # T022
 wait
 # Launch all models together:
 Task: "Validate User model in internal/model/user.go"   # T025
 Task: "Validate Order model in internal/model/order.go" # T026
 Task: "Validate User DTOs"                               # T027
 Task: "Create Order DTOs"                                # T028
 # Launch both Store implementations together:
 Task: "Implement UserStore"  # T029
 Task: "Implement OrderStore" # T030
 ```
 ---
 ## Implementation Strategy
 ### MVP First (User Story 1 Only)
 1. Complete Phase 1: Setup (T001-T008)
 2. Complete Phase 2: Foundational (T009-T018) - CRITICAL
 3. Complete Phase 3: User Story 1 (T019-T046)
 4. **STOP and VALIDATE**: Test CRUD operations independently
 5. Deploy/demo if ready
 ### Incremental Delivery
 1. Setup + Foundational → Foundation ready
 2. Add User Story 1 → Test independently → Deploy/Demo (MVP! 🎯)
 3. Add User Story 2 → Test independently → Deploy/Demo
 4. Add User Story 3 → Test independently → Deploy/Demo
 5. Polish → Final quality checks → Production ready
 ### Parallel Team Strategy
 With multiple developers:
 1. Team completes Setup (Phase 1) + Foundational (Phase 2) together
 2. Once Foundational is done:
   - Developer A: User Story 1 (T019-T046)
   - Developer B: User Story 2 (T047-T068)
   - Developer C: User Story 3 (T069-T082)
 3. Stories complete and integrate independently
 4. Team reconvenes for Polish (Phase 6)
 ---
 ## Notes
 - [P] tasks = different files, no dependencies, can run in parallel
 - [Story] label (US1, US2, US3) maps task to specific user story for traceability
 - Each user story is independently completable and testable
 - Tests are written FIRST and should FAIL before implementation (TDD approach)
 - Commit after each task or logical group
 - Stop at any checkpoint to validate story independently
 - Project structure already exists - tasks validate/enhance existing code where noted
 - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
 ---
 ## Task Count Summary
 - **Total Tasks**: 121
 - **Phase 1 (Setup)**: 8 tasks
 - **Phase 2 (Foundational)**: 10 tasks
 - **Phase 3 (User Story 1)**: 28 tasks (5 tests + 23 implementation)
 - **Phase 4 (User Story 2)**: 22 tasks (4 tests + 18 implementation)
 - **Phase 5 (User Story 3)**: 14 tasks (3 tests + 11 implementation)
 - **Phase 6 (Polish)**: 39 tasks (4 docs + 35 quality gates)
 **Parallel Opportunities**: ~40 tasks marked [P] can run in parallel within their phases
 **Suggested MVP Scope**: Phase 1 + Phase 2 + Phase 3 (User Story 1) = 46 tasks
--- a/tests/integration/auth_test.go
+++ b/tests/integration/auth_test.go
@@ -7,7 +7,6 @@ import (
 	"testing"
 	"time"
 	"github.com/break/junhong_cmp_fiber/internal/handler"
 	"github.com/break/junhong_cmp_fiber/internal/middleware"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
@@ -64,7 +63,8 @@ func setupAuthTestApp(t *testing.T, rdb *redis.Client) *fiber.App {
 		})
 	})
-	app.Get("/api/v1/users", handler.GetUsers)
+	// 注释：用户路由已移至实例方法，集成测试中使用测试路由即可
 	// 实际的用户路由测试应在 cmd/api/main.go 中完整初始化
 	return app
 }
--- a/tests/integration/database_test.go
+++ b/tests/integration/database_test.go
@@ -0,0 +1,489 @@
 package integration
 import (
 	"context"
 	"fmt"
 	"os"
 	"path/filepath"
 	"testing"
 	"time"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/golang-migrate/migrate/v4"
 	_ "github.com/golang-migrate/migrate/v4/database/postgres"
 	_ "github.com/golang-migrate/migrate/v4/source/file"
 	_ "github.com/lib/pq"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/testcontainers/testcontainers-go"
 	testcontainers_postgres "github.com/testcontainers/testcontainers-go/modules/postgres"
 	"github.com/testcontainers/testcontainers-go/wait"
 	"go.uber.org/zap"
 	postgresDriver "gorm.io/driver/postgres"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
 )
 // TestMain 设置测试环境
 func TestMain(m *testing.M) {
 	code := m.Run()
 	os.Exit(code)
 }
 // setupTestDB 启动 PostgreSQL 容器并使用迁移脚本初始化数据库
 func setupTestDB(t *testing.T) (*postgres.Store, func()) {
 	ctx := context.Background()
 	// 启动 PostgreSQL 容器
 	postgresContainer, err := testcontainers_postgres.RunContainer(ctx,
 		testcontainers.WithImage("postgres:14-alpine"),
 		testcontainers_postgres.WithDatabase("testdb"),
 		testcontainers_postgres.WithUsername("postgres"),
 		testcontainers_postgres.WithPassword("password"),
 		testcontainers.WithWaitStrategy(
 			wait.ForLog("database system is ready to accept connections").
 				WithOccurrence(2).
 				WithStartupTimeout(30*time.Second),
 		),
 	)
 	require.NoError(t, err, "启动 PostgreSQL 容器失败")
 	// 获取连接字符串
 	connStr, err := postgresContainer.ConnectionString(ctx, "sslmode=disable")
 	require.NoError(t, err, "获取数据库连接字符串失败")
 	// 应用数据库迁移
 	migrationsPath := getMigrationsPath(t)
 	m, err := migrate.New(
 		fmt.Sprintf("file://%s", migrationsPath),
 		connStr,
 	)
 	require.NoError(t, err, "创建迁移实例失败")
 	// 执行向上迁移
 	err = m.Up()
 	require.NoError(t, err, "执行数据库迁移失败")
 	// 连接数据库
 	db, err := gorm.Open(postgresDriver.Open(connStr), &gorm.Config{
 		Logger: logger.Default.LogMode(logger.Silent),
 	})
 	require.NoError(t, err, "连接数据库失败")
 	// 创建测试 logger
 	testLogger := zap.NewNop()
 	store := postgres.NewStore(db, testLogger)
 	// 返回清理函数
 	cleanup := func() {
 		// 执行向下迁移清理数据
 		if err := m.Down(); err != nil && err != migrate.ErrNoChange {
 			t.Logf("清理迁移失败: %v", err)
 		}
 		m.Close()
 		sqlDB, _ := db.DB()
 		if sqlDB != nil {
 			sqlDB.Close()
 		}
 		if err := postgresContainer.Terminate(ctx); err != nil {
 			t.Logf("终止容器失败: %v", err)
 		}
 	}
 	return store, cleanup
 }
 // getMigrationsPath 获取迁移文件路径
 func getMigrationsPath(t *testing.T) string {
 	// 获取项目根目录
 	wd, err := os.Getwd()
 	require.NoError(t, err, "获取工作目录失败")
 	// 从测试目录向上找到项目根目录
 	migrationsPath := filepath.Join(wd, "..", "..", "migrations")
 	// 验证迁移目录存在
 	_, err = os.Stat(migrationsPath)
 	require.NoError(t, err, fmt.Sprintf("迁移目录不存在: %s", migrationsPath))
 	return migrationsPath
 }
 // TestUserCRUD 测试用户 CRUD 操作
 func TestUserCRUD(t *testing.T) {
 	store, cleanup := setupTestDB(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("创建用户", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		assert.NoError(t, err)
 		assert.NotZero(t, user.ID)
 		assert.NotZero(t, user.CreatedAt)
 		assert.NotZero(t, user.UpdatedAt)
 	})
 	t.Run("根据ID查询用户", func(t *testing.T) {
 		// 创建测试用户
 		user := &model.User{
 			Username: "queryuser",
 			Email:    "query@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 查询用户
 		found, err := store.User.GetByID(ctx, user.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, user.Username, found.Username)
 		assert.Equal(t, user.Email, found.Email)
 		assert.Equal(t, constants.UserStatusActive, found.Status)
 	})
 	t.Run("根据用户名查询用户", func(t *testing.T) {
 		// 创建测试用户
 		user := &model.User{
 			Username: "findbyname",
 			Email:    "findbyname@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 根据用户名查询
 		found, err := store.User.GetByUsername(ctx, "findbyname")
 		assert.NoError(t, err)
 		assert.Equal(t, user.ID, found.ID)
 		assert.Equal(t, user.Email, found.Email)
 	})
 	t.Run("更新用户", func(t *testing.T) {
 		// 创建测试用户
 		user := &model.User{
 			Username: "updateuser",
 			Email:    "update@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 更新用户
 		user.Email = "newemail@example.com"
 		user.Status = constants.UserStatusInactive
 		err = store.User.Update(ctx, user)
 		assert.NoError(t, err)
 		// 验证更新
 		found, err := store.User.GetByID(ctx, user.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, "newemail@example.com", found.Email)
 		assert.Equal(t, constants.UserStatusInactive, found.Status)
 	})
 	t.Run("列表查询用户", func(t *testing.T) {
 		// 创建多个测试用户
 		for i := 1; i <= 5; i++ {
 			user := &model.User{
 				Username: fmt.Sprintf("listuser%d", i),
 				Email:    fmt.Sprintf("list%d@example.com", i),
 				Password: "hashedpassword",
 				Status:   constants.UserStatusActive,
 			}
 			err := store.User.Create(ctx, user)
 			require.NoError(t, err)
 		}
 		// 列表查询
 		users, total, err := store.User.List(ctx, 1, 3)
 		assert.NoError(t, err)
 		assert.GreaterOrEqual(t, len(users), 3)
 		assert.GreaterOrEqual(t, total, int64(5))
 	})
 	t.Run("软删除用户", func(t *testing.T) {
 		// 创建测试用户
 		user := &model.User{
 			Username: "deleteuser",
 			Email:    "delete@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 软删除
 		err = store.User.Delete(ctx, user.ID)
 		assert.NoError(t, err)
 		// 验证已删除（查询应该找不到）
 		_, err = store.User.GetByID(ctx, user.ID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 }
 // TestOrderCRUD 测试订单 CRUD 操作
 func TestOrderCRUD(t *testing.T) {
 	store, cleanup := setupTestDB(t)
 	defer cleanup()
 	ctx := context.Background()
 	// 创建测试用户
 	user := &model.User{
 		Username: "orderuser",
 		Email:    "orderuser@example.com",
 		Password: "hashedpassword",
 		Status:   constants.UserStatusActive,
 	}
 	err := store.User.Create(ctx, user)
 	require.NoError(t, err)
 	t.Run("创建订单", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-001",
 			UserID:  user.ID,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 			Remark:  "测试订单",
 		}
 		err := store.Order.Create(ctx, order)
 		assert.NoError(t, err)
 		assert.NotZero(t, order.ID)
 		assert.NotZero(t, order.CreatedAt)
 	})
 	t.Run("根据ID查询订单", func(t *testing.T) {
 		// 创建测试订单
 		order := &model.Order{
 			OrderID: "ORD-002",
 			UserID:  user.ID,
 			Amount:  20000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 查询订单
 		found, err := store.Order.GetByID(ctx, order.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, order.OrderID, found.OrderID)
 		assert.Equal(t, order.Amount, found.Amount)
 	})
 	t.Run("根据订单号查询", func(t *testing.T) {
 		// 创建测试订单
 		order := &model.Order{
 			OrderID: "ORD-003",
 			UserID:  user.ID,
 			Amount:  30000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 根据订单号查询
 		found, err := store.Order.GetByOrderID(ctx, "ORD-003")
 		assert.NoError(t, err)
 		assert.Equal(t, order.ID, found.ID)
 	})
 	t.Run("根据用户ID列表查询", func(t *testing.T) {
 		// 创建多个订单
 		for i := 1; i <= 3; i++ {
 			order := &model.Order{
 				OrderID: fmt.Sprintf("ORD-USER-%d", i),
 				UserID:  user.ID,
 				Amount:  int64(i * 10000),
 				Status:  constants.OrderStatusPending,
 			}
 			err := store.Order.Create(ctx, order)
 			require.NoError(t, err)
 		}
 		// 列表查询
 		orders, total, err := store.Order.ListByUserID(ctx, user.ID, 1, 10)
 		assert.NoError(t, err)
 		assert.GreaterOrEqual(t, len(orders), 3)
 		assert.GreaterOrEqual(t, total, int64(3))
 	})
 	t.Run("更新订单状态", func(t *testing.T) {
 		// 创建测试订单
 		order := &model.Order{
 			OrderID: "ORD-UPDATE",
 			UserID:  user.ID,
 			Amount:  50000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 更新状态
 		now := time.Now()
 		order.Status = constants.OrderStatusPaid
 		order.PaidAt = &now
 		err = store.Order.Update(ctx, order)
 		assert.NoError(t, err)
 		// 验证更新
 		found, err := store.Order.GetByID(ctx, order.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, constants.OrderStatusPaid, found.Status)
 		assert.NotNil(t, found.PaidAt)
 	})
 	t.Run("软删除订单", func(t *testing.T) {
 		// 创建测试订单
 		order := &model.Order{
 			OrderID: "ORD-DELETE",
 			UserID:  user.ID,
 			Amount:  60000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 软删除
 		err = store.Order.Delete(ctx, order.ID)
 		assert.NoError(t, err)
 		// 验证已删除
 		_, err = store.Order.GetByID(ctx, order.ID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 }
 // TestTransaction 测试事务功能
 func TestTransaction(t *testing.T) {
 	store, cleanup := setupTestDB(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("事务提交", func(t *testing.T) {
 		var userID uint
 		var orderID uint
 		err := store.Transaction(ctx, func(tx *postgres.Store) error {
 			// 创建用户
 			user := &model.User{
 				Username: "txuser",
 				Email:    "txuser@example.com",
 				Password: "hashedpassword",
 				Status:   constants.UserStatusActive,
 			}
 			if err := tx.User.Create(ctx, user); err != nil {
 				return err
 			}
 			userID = user.ID
 			// 创建订单
 			order := &model.Order{
 				OrderID: "ORD-TX-001",
 				UserID:  user.ID,
 				Amount:  10000,
 				Status:  constants.OrderStatusPending,
 			}
 			if err := tx.Order.Create(ctx, order); err != nil {
 				return err
 			}
 			orderID = order.ID
 			return nil
 		})
 		assert.NoError(t, err)
 		// 验证用户和订单都已创建
 		user, err := store.User.GetByID(ctx, userID)
 		assert.NoError(t, err)
 		assert.Equal(t, "txuser", user.Username)
 		order, err := store.Order.GetByID(ctx, orderID)
 		assert.NoError(t, err)
 		assert.Equal(t, "ORD-TX-001", order.OrderID)
 	})
 	t.Run("事务回滚", func(t *testing.T) {
 		var userID uint
 		err := store.Transaction(ctx, func(tx *postgres.Store) error {
 			// 创建用户
 			user := &model.User{
 				Username: "rollbackuser",
 				Email:    "rollback@example.com",
 				Password: "hashedpassword",
 				Status:   constants.UserStatusActive,
 			}
 			if err := tx.User.Create(ctx, user); err != nil {
 				return err
 			}
 			userID = user.ID
 			// 模拟错误，触发回滚
 			return fmt.Errorf("模拟错误")
 		})
 		assert.Error(t, err)
 		assert.Equal(t, "模拟错误", err.Error())
 		// 验证用户未创建（已回滚）
 		_, err = store.User.GetByID(ctx, userID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 }
 // TestConcurrentOperations 测试并发操作
 func TestConcurrentOperations(t *testing.T) {
 	store, cleanup := setupTestDB(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("并发创建用户", func(t *testing.T) {
 		concurrency := 10
 		errChan := make(chan error, concurrency)
 		for i := 0; i < concurrency; i++ {
 			go func(index int) {
 				user := &model.User{
 					Username: fmt.Sprintf("concurrent%d", index),
 					Email:    fmt.Sprintf("concurrent%d@example.com", index),
 					Password: "hashedpassword",
 					Status:   constants.UserStatusActive,
 				}
 				errChan <- store.User.Create(ctx, user)
 			}(i)
 		}
 		// 收集结果
 		successCount := 0
 		for i := 0; i < concurrency; i++ {
 			err := <-errChan
 			if err == nil {
 				successCount++
 			}
 		}
 		assert.Equal(t, concurrency, successCount, "所有并发创建应该成功")
 	})
 }
--- a/tests/integration/health_test.go
+++ b/tests/integration/health_test.go
@@ -0,0 +1,169 @@
 package integration
 import (
 	"context"
 	"net/http/httptest"
 	"testing"
 	"github.com/break/junhong_cmp_fiber/internal/handler"
 	"github.com/gofiber/fiber/v2"
 	"github.com/redis/go-redis/v9"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/zap"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 )
 // TestHealthCheckNormal 测试健康检查 - 正常状态
 func TestHealthCheckNormal(t *testing.T) {
 	// 初始化日志
 	logger, _ := zap.NewDevelopment()
 	// 初始化内存数据库
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
 	require.NoError(t, err)
 	// 初始化 Redis 客户端（使用本地 Redis）
 	rdb := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 		DB:   0,
 	})
 	defer rdb.Close()
 	// 创建 Fiber 应用
 	app := fiber.New()
 	// 创建健康检查处理器
 	healthHandler := handler.NewHealthHandler(db, rdb, logger)
 	app.Get("/health", healthHandler.Check)
 	// 发送测试请求
 	req := httptest.NewRequest("GET", "/health", nil)
 	resp, err := app.Test(req)
 	require.NoError(t, err)
 	defer resp.Body.Close()
 	// 验证响应状态码
 	assert.Equal(t, 200, resp.StatusCode)
 	// 验证响应内容
 	// 注意：这里可以进一步解析 JSON 响应体验证详细信息
 }
 // TestHealthCheckDatabaseDown 测试健康检查 - 数据库异常
 func TestHealthCheckDatabaseDown(t *testing.T) {
 	t.Skip("需要模拟数据库连接失败的场景")
 	// 初始化日志
 	logger, _ := zap.NewDevelopment()
 	// 初始化一个会失败的数据库连接
 	db, err := gorm.Open(sqlite.Open("/invalid/path/test.db"), &gorm.Config{})
 	if err != nil {
 		// 预期会失败
 		t.Log("数据库连接失败（预期行为）")
 	}
 	// 初始化 Redis 客户端
 	rdb := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 		DB:   0,
 	})
 	defer rdb.Close()
 	// 创建 Fiber 应用
 	app := fiber.New()
 	// 创建健康检查处理器
 	healthHandler := handler.NewHealthHandler(db, rdb, logger)
 	app.Get("/health", healthHandler.Check)
 	// 发送测试请求
 	req := httptest.NewRequest("GET", "/health", nil)
 	resp, err := app.Test(req)
 	require.NoError(t, err)
 	defer resp.Body.Close()
 	// 验证响应状态码应该是 503 (Service Unavailable)
 	assert.Equal(t, 503, resp.StatusCode)
 }
 // TestHealthCheckRedisDown 测试健康检查 - Redis 异常
 func TestHealthCheckRedisDown(t *testing.T) {
 	// 初始化日志
 	logger, _ := zap.NewDevelopment()
 	// 初始化内存数据库
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
 	require.NoError(t, err)
 	// 初始化一个连接到无效地址的 Redis 客户端
 	rdb := redis.NewClient(&redis.Options{
 		Addr: "localhost:9999", // 无效端口
 		DB:   0,
 	})
 	defer rdb.Close()
 	// 创建 Fiber 应用
 	app := fiber.New()
 	// 创建健康检查处理器
 	healthHandler := handler.NewHealthHandler(db, rdb, logger)
 	app.Get("/health", healthHandler.Check)
 	// 发送测试请求
 	req := httptest.NewRequest("GET", "/health", nil)
 	resp, err := app.Test(req)
 	require.NoError(t, err)
 	defer resp.Body.Close()
 	// 验证响应状态码应该是 503 (Service Unavailable)
 	assert.Equal(t, 503, resp.StatusCode)
 }
 // TestHealthCheckDetailed 测试健康检查 - 验证详细信息
 func TestHealthCheckDetailed(t *testing.T) {
 	// 初始化日志
 	logger, _ := zap.NewDevelopment()
 	// 初始化内存数据库
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
 	require.NoError(t, err)
 	// 初始化 Redis 客户端
 	rdb := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 		DB:   0,
 	})
 	defer rdb.Close()
 	// 测试 Redis 连接
 	ctx := context.Background()
 	_, err = rdb.Ping(ctx).Result()
 	if err != nil {
 		t.Skip("Redis 未运行，跳过测试")
 	}
 	// 创建 Fiber 应用
 	app := fiber.New()
 	// 创建健康检查处理器
 	healthHandler := handler.NewHealthHandler(db, rdb, logger)
 	app.Get("/health", healthHandler.Check)
 	// 发送测试请求
 	req := httptest.NewRequest("GET", "/health", nil)
 	resp, err := app.Test(req)
 	require.NoError(t, err)
 	defer resp.Body.Close()
 	// 验证响应状态码
 	assert.Equal(t, 200, resp.StatusCode)
 	// TODO: 解析 JSON 响应并验证包含以下字段：
 	// - status: "healthy"
 	// - postgres: "up"
 	// - redis: "up"
 	// - timestamp
 }
--- a/tests/integration/recover_test.go
+++ b/tests/integration/recover_test.go
@@ -1,7 +1,6 @@
 package integration
 import (
 	"encoding/json"
 	"io"
 	"net/http/httptest"
 	"os"
@@ -14,6 +13,7 @@ import (
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/logger"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
 	"github.com/bytedance/sonic"
 	"github.com/gofiber/fiber/v2"
 	"github.com/gofiber/fiber/v2/middleware/requestid"
 	"github.com/google/uuid"
@@ -115,7 +115,7 @@ func TestPanicRecovery(t *testing.T) {
 			if tt.shouldPanic {
 				// panic 应该返回统一错误响应
 				var response response.Response
-				if err := json.Unmarshal(body, &response); err != nil {
+				if err := sonic.Unmarshal(body, &response); err != nil {
 					t.Fatalf("Failed to unmarshal response: %v", err)
 				}
@@ -348,7 +348,7 @@ func TestSubsequentRequestsAfterPanic(t *testing.T) {
 			// 验证响应内容
 			var response map[string]any
-			if err := json.Unmarshal(body, &response); err != nil {
+			if err := sonic.Unmarshal(body, &response); err != nil {
 				t.Fatalf("Request %d: failed to unmarshal response: %v", i, err)
 			}
@@ -606,7 +606,7 @@ func TestRecoverMiddlewareOrder(t *testing.T) {
 	// 解析响应，验证返回了统一错误格式
 	body, _ := io.ReadAll(resp.Body)
 	var response response.Response
-	if err := json.Unmarshal(body, &response); err != nil {
+	if err := sonic.Unmarshal(body, &response); err != nil {
 		t.Fatalf("Failed to unmarshal response: %v", err)
 	}
--- a/tests/integration/task_test.go
+++ b/tests/integration/task_test.go
@@ -0,0 +1,312 @@
 package integration
 import (
 	"context"
 	"testing"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"github.com/redis/go-redis/v9"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 // EmailPayload 邮件任务载荷（测试用）
 type EmailPayload struct {
 	RequestID string   `json:"request_id"`
 	To        string   `json:"to"`
 	Subject   string   `json:"subject"`
 	Body      string   `json:"body"`
 	CC        []string `json:"cc,omitempty"`
 }
 // TestTaskSubmit 测试任务提交
 func TestTaskSubmit(t *testing.T) {
 	// 创建 Redis 客户端
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	// 清理测试数据
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	// 创建 Asynq 客户端
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	// 构造任务载荷
 	payload := &EmailPayload{
 		RequestID: "test-request-001",
 		To:        "test@example.com",
 		Subject:   "Test Email",
 		Body:      "This is a test email",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	// 提交任务
 	task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info, err := client.Enqueue(task,
 		asynq.Queue(constants.QueueDefault),
 		asynq.MaxRetry(constants.DefaultRetryMax),
 	)
 	// 验证
 	require.NoError(t, err)
 	assert.NotEmpty(t, info.ID)
 	assert.Equal(t, constants.QueueDefault, info.Queue)
 	assert.Equal(t, constants.DefaultRetryMax, info.MaxRetry)
 }
 // TestTaskPriority 测试任务优先级
 func TestTaskPriority(t *testing.T) {
 	// 创建 Redis 客户端
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	// 创建 Asynq 客户端
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	tests := []struct {
 		name  string
 		queue string
 	}{
 		{"Critical Priority", constants.QueueCritical},
 		{"Default Priority", constants.QueueDefault},
 		{"Low Priority", constants.QueueLow},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			payload := &EmailPayload{
 				RequestID: "test-request-" + tt.queue,
 				To:        "test@example.com",
 				Subject:   "Test",
 				Body:      "Test",
 			}
 			payloadBytes, err := sonic.Marshal(payload)
 			require.NoError(t, err)
 			task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 			info, err := client.Enqueue(task, asynq.Queue(tt.queue))
 			require.NoError(t, err)
 			assert.Equal(t, tt.queue, info.Queue)
 		})
 	}
 }
 // TestTaskRetry 测试任务重试机制
 func TestTaskRetry(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	payload := &EmailPayload{
 		RequestID: "retry-test-001",
 		To:        "test@example.com",
 		Subject:   "Retry Test",
 		Body:      "Test retry mechanism",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	// 提交任务并设置重试次数
 	task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info, err := client.Enqueue(task,
 		asynq.MaxRetry(3),
 		asynq.Timeout(30*time.Second),
 	)
 	require.NoError(t, err)
 	assert.Equal(t, 3, info.MaxRetry)
 	assert.Equal(t, 30*time.Second, info.Timeout)
 }
 // TestTaskIdempotency 测试任务幂等性键
 func TestTaskIdempotency(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	requestID := "idempotent-test-001"
 	lockKey := constants.RedisTaskLockKey(requestID)
 	// 第一次设置锁（模拟任务开始执行）
 	result, err := redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 	require.NoError(t, err)
 	assert.True(t, result, "第一次设置锁应该成功")
 	// 第二次设置锁（模拟重复任务）
 	result, err = redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 	require.NoError(t, err)
 	assert.False(t, result, "第二次设置锁应该失败（幂等性）")
 	// 验证锁存在
 	exists, err := redisClient.Exists(ctx, lockKey).Result()
 	require.NoError(t, err)
 	assert.Equal(t, int64(1), exists)
 	// 验证 TTL
 	ttl, err := redisClient.TTL(ctx, lockKey).Result()
 	require.NoError(t, err)
 	assert.Greater(t, ttl.Hours(), 23.0)
 	assert.LessOrEqual(t, ttl.Hours(), 24.0)
 }
 // TestTaskStatusTracking 测试任务状态跟踪
 func TestTaskStatusTracking(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	taskID := "task-123456"
 	statusKey := constants.RedisTaskStatusKey(taskID)
 	// 设置任务状态
 	statuses := []string{"pending", "processing", "completed"}
 	for _, status := range statuses {
 		err := redisClient.Set(ctx, statusKey, status, 7*24*time.Hour).Err()
 		require.NoError(t, err)
 		// 读取状态
 		result, err := redisClient.Get(ctx, statusKey).Result()
 		require.NoError(t, err)
 		assert.Equal(t, status, result)
 	}
 	// 验证 TTL
 	ttl, err := redisClient.TTL(ctx, statusKey).Result()
 	require.NoError(t, err)
 	assert.Greater(t, ttl.Hours(), 24.0*6)
 }
 // TestQueueInspection 测试队列检查
 func TestQueueInspection(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	// 提交多个任务
 	for i := 0; i < 5; i++ {
 		payload := &EmailPayload{
 			RequestID: "test-" + string(rune(i)),
 			To:        "test@example.com",
 			Subject:   "Test",
 			Body:      "Test",
 		}
 		payloadBytes, err := sonic.Marshal(payload)
 		require.NoError(t, err)
 		task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 		_, err = client.Enqueue(task, asynq.Queue(constants.QueueDefault))
 		require.NoError(t, err)
 	}
 	// 创建 Inspector 检查队列
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	// 获取队列信息
 	info, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.Equal(t, 5, info.Pending)
 	assert.Equal(t, 0, info.Active)
 }
 // TestTaskSerialization 测试任务序列化
 func TestTaskSerialization(t *testing.T) {
 	tests := []struct {
 		name    string
 		payload EmailPayload
 	}{
 		{
 			name: "Simple Email",
 			payload: EmailPayload{
 				RequestID: "req-001",
 				To:        "user@example.com",
 				Subject:   "Hello",
 				Body:      "Hello World",
 			},
 		},
 		{
 			name: "Email with CC",
 			payload: EmailPayload{
 				RequestID: "req-002",
 				To:        "user@example.com",
 				Subject:   "Hello",
 				Body:      "Hello World",
 				CC:        []string{"cc1@example.com", "cc2@example.com"},
 			},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			// 序列化
 			payloadBytes, err := sonic.Marshal(tt.payload)
 			require.NoError(t, err)
 			assert.NotEmpty(t, payloadBytes)
 			// 反序列化
 			var decoded EmailPayload
 			err = sonic.Unmarshal(payloadBytes, &decoded)
 			require.NoError(t, err)
 			// 验证
 			assert.Equal(t, tt.payload.RequestID, decoded.RequestID)
 			assert.Equal(t, tt.payload.To, decoded.To)
 			assert.Equal(t, tt.payload.Subject, decoded.Subject)
 			assert.Equal(t, tt.payload.Body, decoded.Body)
 			assert.Equal(t, tt.payload.CC, decoded.CC)
 		})
 	}
 }
--- a/tests/unit/model_test.go
+++ b/tests/unit/model_test.go
@@ -0,0 +1,502 @@
 package unit
 import (
 	"testing"
 	"time"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/go-playground/validator/v10"
 	"github.com/stretchr/testify/assert"
 )
 // TestUserValidation 测试用户模型验证
 func TestUserValidation(t *testing.T) {
 	validate := validator.New()
 	t.Run("有效的创建用户请求", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "validuser",
 			Email:    "valid@example.com",
 			Password: "password123",
 		}
 		err := validate.Struct(req)
 		assert.NoError(t, err)
 	})
 	t.Run("用户名太短", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "ab", // 少于 3 个字符
 			Email:    "valid@example.com",
 			Password: "password123",
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("用户名太长", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "a123456789012345678901234567890123456789012345678901", // 超过 50 个字符
 			Email:    "valid@example.com",
 			Password: "password123",
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("无效的邮箱格式", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "validuser",
 			Email:    "invalid-email",
 			Password: "password123",
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("密码太短", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "validuser",
 			Email:    "valid@example.com",
 			Password: "short", // 少于 8 个字符
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("缺少必填字段", func(t *testing.T) {
 		req := &model.CreateUserRequest{
 			Username: "validuser",
 			// 缺少 Email 和 Password
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 }
 // TestUserUpdateValidation 测试用户更新验证
 func TestUserUpdateValidation(t *testing.T) {
 	validate := validator.New()
 	t.Run("有效的更新请求", func(t *testing.T) {
 		email := "newemail@example.com"
 		status := constants.UserStatusActive
 		req := &model.UpdateUserRequest{
 			Email:  &email,
 			Status: &status,
 		}
 		err := validate.Struct(req)
 		assert.NoError(t, err)
 	})
 	t.Run("无效的邮箱格式", func(t *testing.T) {
 		email := "invalid-email"
 		req := &model.UpdateUserRequest{
 			Email: &email,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("无效的状态值", func(t *testing.T) {
 		status := "invalid_status"
 		req := &model.UpdateUserRequest{
 			Status: &status,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("空更新请求", func(t *testing.T) {
 		req := &model.UpdateUserRequest{}
 		err := validate.Struct(req)
 		assert.NoError(t, err) // 空更新请求应该是有效的
 	})
 }
 // TestOrderValidation 测试订单模型验证
 func TestOrderValidation(t *testing.T) {
 	validate := validator.New()
 	t.Run("有效的创建订单请求", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-2025-001",
 			UserID:  1,
 			Amount:  10000,
 			Remark:  "测试订单",
 		}
 		err := validate.Struct(req)
 		assert.NoError(t, err)
 	})
 	t.Run("订单号太短", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-123", // 少于 10 个字符
 			UserID:  1,
 			Amount:  10000,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("订单号太长", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-12345678901234567890123456789012345678901234567890", // 超过 50 个字符
 			UserID:  1,
 			Amount:  10000,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("用户ID无效", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-2025-001",
 			UserID:  0, // 用户ID必须大于0
 			Amount:  10000,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("金额为负数", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-2025-001",
 			UserID:  1,
 			Amount:  -1000, // 金额不能为负数
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 	t.Run("缺少必填字段", func(t *testing.T) {
 		req := &model.CreateOrderRequest{
 			OrderID: "ORD-2025-001",
 			// 缺少 UserID 和 Amount
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 }
 // TestOrderUpdateValidation 测试订单更新验证
 func TestOrderUpdateValidation(t *testing.T) {
 	validate := validator.New()
 	t.Run("有效的更新请求", func(t *testing.T) {
 		status := constants.OrderStatusPaid
 		remark := "已支付"
 		req := &model.UpdateOrderRequest{
 			Status: &status,
 			Remark: &remark,
 		}
 		err := validate.Struct(req)
 		assert.NoError(t, err)
 	})
 	t.Run("无效的状态值", func(t *testing.T) {
 		status := "invalid_status"
 		req := &model.UpdateOrderRequest{
 			Status: &status,
 		}
 		err := validate.Struct(req)
 		assert.Error(t, err)
 	})
 }
 // TestUserModel 测试用户模型
 func TestUserModel(t *testing.T) {
 	t.Run("创建用户模型", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		assert.Equal(t, "testuser", user.Username)
 		assert.Equal(t, "test@example.com", user.Email)
 		assert.Equal(t, constants.UserStatusActive, user.Status)
 	})
 	t.Run("用户表名", func(t *testing.T) {
 		user := &model.User{}
 		assert.Equal(t, "tb_user", user.TableName())
 	})
 	t.Run("软删除字段", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		// DeletedAt 应该是 nil (未删除)
 		assert.True(t, user.DeletedAt.Time.IsZero())
 	})
 	t.Run("LastLoginAt 可选字段", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		assert.Nil(t, user.LastLoginAt)
 		// 设置登录时间
 		now := time.Now()
 		user.LastLoginAt = &now
 		assert.NotNil(t, user.LastLoginAt)
 		assert.Equal(t, now, *user.LastLoginAt)
 	})
 }
 // TestOrderModel 测试订单模型
 func TestOrderModel(t *testing.T) {
 	t.Run("创建订单模型", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-2025-001",
 			UserID:  1,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 			Remark:  "测试订单",
 		}
 		assert.Equal(t, "ORD-2025-001", order.OrderID)
 		assert.Equal(t, uint(1), order.UserID)
 		assert.Equal(t, int64(10000), order.Amount)
 		assert.Equal(t, constants.OrderStatusPending, order.Status)
 	})
 	t.Run("订单表名", func(t *testing.T) {
 		order := &model.Order{}
 		assert.Equal(t, "tb_order", order.TableName())
 	})
 	t.Run("可选时间字段", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-2025-001",
 			UserID:  1,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 		}
 		assert.Nil(t, order.PaidAt)
 		assert.Nil(t, order.CompletedAt)
 		// 设置支付时间
 		now := time.Now()
 		order.PaidAt = &now
 		assert.NotNil(t, order.PaidAt)
 		assert.Equal(t, now, *order.PaidAt)
 	})
 }
 // TestBaseModel 测试基础模型
 func TestBaseModel(t *testing.T) {
 	t.Run("BaseModel 字段", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		// ID 应该是 0 (未保存)
 		assert.Zero(t, user.ID)
 		// 时间戳应该是零值
 		assert.True(t, user.CreatedAt.IsZero())
 		assert.True(t, user.UpdatedAt.IsZero())
 	})
 }
 // TestUserStatusConstants 测试用户状态常量
 func TestUserStatusConstants(t *testing.T) {
 	t.Run("用户状态常量定义", func(t *testing.T) {
 		assert.Equal(t, "active", constants.UserStatusActive)
 		assert.Equal(t, "inactive", constants.UserStatusInactive)
 		assert.Equal(t, "suspended", constants.UserStatusSuspended)
 	})
 	t.Run("用户状态验证", func(t *testing.T) {
 		validStatuses := []string{
 			constants.UserStatusActive,
 			constants.UserStatusInactive,
 			constants.UserStatusSuspended,
 		}
 		for _, status := range validStatuses {
 			user := &model.User{
 				Username: "testuser",
 				Email:    "test@example.com",
 				Password: "hashedpassword",
 				Status:   status,
 			}
 			assert.Contains(t, validStatuses, user.Status)
 		}
 	})
 }
 // TestOrderStatusConstants 测试订单状态常量
 func TestOrderStatusConstants(t *testing.T) {
 	t.Run("订单状态常量定义", func(t *testing.T) {
 		assert.Equal(t, "pending", constants.OrderStatusPending)
 		assert.Equal(t, "paid", constants.OrderStatusPaid)
 		assert.Equal(t, "processing", constants.OrderStatusProcessing)
 		assert.Equal(t, "completed", constants.OrderStatusCompleted)
 		assert.Equal(t, "cancelled", constants.OrderStatusCancelled)
 	})
 	t.Run("订单状态流转", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-2025-001",
 			UserID:  1,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 		}
 		// 订单状态流转：pending -> paid -> processing -> completed
 		assert.Equal(t, constants.OrderStatusPending, order.Status)
 		order.Status = constants.OrderStatusPaid
 		assert.Equal(t, constants.OrderStatusPaid, order.Status)
 		order.Status = constants.OrderStatusProcessing
 		assert.Equal(t, constants.OrderStatusProcessing, order.Status)
 		order.Status = constants.OrderStatusCompleted
 		assert.Equal(t, constants.OrderStatusCompleted, order.Status)
 	})
 	t.Run("订单取消", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-2025-002",
 			UserID:  1,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 		}
 		// 从任何状态都可以取消
 		order.Status = constants.OrderStatusCancelled
 		assert.Equal(t, constants.OrderStatusCancelled, order.Status)
 	})
 }
 // TestUserResponse 测试用户响应模型
 func TestUserResponse(t *testing.T) {
 	t.Run("创建用户响应", func(t *testing.T) {
 		now := time.Now()
 		resp := &model.UserResponse{
 			ID:        1,
 			Username:  "testuser",
 			Email:     "test@example.com",
 			Status:    constants.UserStatusActive,
 			CreatedAt: now,
 			UpdatedAt: now,
 		}
 		assert.Equal(t, uint(1), resp.ID)
 		assert.Equal(t, "testuser", resp.Username)
 		assert.Equal(t, "test@example.com", resp.Email)
 		assert.Equal(t, constants.UserStatusActive, resp.Status)
 	})
 	t.Run("用户响应不包含密码", func(t *testing.T) {
 		// UserResponse 结构体不应该包含 Password 字段
 		resp := &model.UserResponse{
 			ID:       1,
 			Username: "testuser",
 			Email:    "test@example.com",
 			Status:   constants.UserStatusActive,
 		}
 		// 验证结构体大小合理 (不包含密码字段)
 		assert.NotNil(t, resp)
 	})
 }
 // TestListResponse 测试列表响应模型
 func TestListResponse(t *testing.T) {
 	t.Run("用户列表响应", func(t *testing.T) {
 		users := []model.UserResponse{
 			{ID: 1, Username: "user1", Email: "user1@example.com", Status: constants.UserStatusActive},
 			{ID: 2, Username: "user2", Email: "user2@example.com", Status: constants.UserStatusActive},
 		}
 		resp := &model.ListUsersResponse{
 			Users:      users,
 			Page:       1,
 			PageSize:   20,
 			Total:      100,
 			TotalPages: 5,
 		}
 		assert.Equal(t, 2, len(resp.Users))
 		assert.Equal(t, 1, resp.Page)
 		assert.Equal(t, 20, resp.PageSize)
 		assert.Equal(t, int64(100), resp.Total)
 		assert.Equal(t, 5, resp.TotalPages)
 	})
 	t.Run("订单列表响应", func(t *testing.T) {
 		orders := []model.OrderResponse{
 			{ID: 1, OrderID: "ORD-001", UserID: 1, Amount: 10000, Status: constants.OrderStatusPending},
 			{ID: 2, OrderID: "ORD-002", UserID: 1, Amount: 20000, Status: constants.OrderStatusPaid},
 		}
 		resp := &model.ListOrdersResponse{
 			Orders:     orders,
 			Page:       1,
 			PageSize:   20,
 			Total:      50,
 			TotalPages: 3,
 		}
 		assert.Equal(t, 2, len(resp.Orders))
 		assert.Equal(t, 1, resp.Page)
 		assert.Equal(t, 20, resp.PageSize)
 		assert.Equal(t, int64(50), resp.Total)
 		assert.Equal(t, 3, resp.TotalPages)
 	})
 }
 // TestFieldTags 测试字段标签
 func TestFieldTags(t *testing.T) {
 	t.Run("User GORM 标签", func(t *testing.T) {
 		user := &model.User{}
 		// 验证 TableName 方法存在
 		tableName := user.TableName()
 		assert.Equal(t, "tb_user", tableName)
 	})
 	t.Run("Order GORM 标签", func(t *testing.T) {
 		order := &model.Order{}
 		// 验证 TableName 方法存在
 		tableName := order.TableName()
 		assert.Equal(t, "tb_order", tableName)
 	})
 }
--- a/tests/unit/queue_test.go
+++ b/tests/unit/queue_test.go
@@ -0,0 +1,555 @@
 package unit
 import (
 	"context"
 	"testing"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"github.com/redis/go-redis/v9"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 // TestQueueClientEnqueue 测试任务入队
 func TestQueueClientEnqueue(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	payload := map[string]string{
 		"request_id": "test-001",
 		"to":         "test@example.com",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info, err := client.Enqueue(task)
 	require.NoError(t, err)
 	assert.NotEmpty(t, info.ID)
 	assert.Equal(t, constants.QueueDefault, info.Queue)
 }
 // TestQueueClientEnqueueWithOptions 测试带选项的任务入队
 func TestQueueClientEnqueueWithOptions(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	tests := []struct {
 		name   string
 		opts   []asynq.Option
 		verify func(*testing.T, *asynq.TaskInfo)
 	}{
 		{
 			name: "Custom Queue",
 			opts: []asynq.Option{
 				asynq.Queue(constants.QueueCritical),
 			},
 			verify: func(t *testing.T, info *asynq.TaskInfo) {
 				assert.Equal(t, constants.QueueCritical, info.Queue)
 			},
 		},
 		{
 			name: "Custom Retry",
 			opts: []asynq.Option{
 				asynq.MaxRetry(3),
 			},
 			verify: func(t *testing.T, info *asynq.TaskInfo) {
 				assert.Equal(t, 3, info.MaxRetry)
 			},
 		},
 		{
 			name: "Custom Timeout",
 			opts: []asynq.Option{
 				asynq.Timeout(5 * time.Minute),
 			},
 			verify: func(t *testing.T, info *asynq.TaskInfo) {
 				assert.Equal(t, 5*time.Minute, info.Timeout)
 			},
 		},
 		{
 			name: "Delayed Task",
 			opts: []asynq.Option{
 				asynq.ProcessIn(10 * time.Second),
 			},
 			verify: func(t *testing.T, info *asynq.TaskInfo) {
 				assert.True(t, info.NextProcessAt.After(time.Now()))
 			},
 		},
 		{
 			name: "Combined Options",
 			opts: []asynq.Option{
 				asynq.Queue(constants.QueueCritical),
 				asynq.MaxRetry(5),
 				asynq.Timeout(10 * time.Minute),
 			},
 			verify: func(t *testing.T, info *asynq.TaskInfo) {
 				assert.Equal(t, constants.QueueCritical, info.Queue)
 				assert.Equal(t, 5, info.MaxRetry)
 				assert.Equal(t, 10*time.Minute, info.Timeout)
 			},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			payload := map[string]string{
 				"request_id": "test-" + tt.name,
 			}
 			payloadBytes, err := sonic.Marshal(payload)
 			require.NoError(t, err)
 			task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 			info, err := client.Enqueue(task, tt.opts...)
 			require.NoError(t, err)
 			tt.verify(t, info)
 		})
 	}
 }
 // TestQueueClientTaskUniqueness 测试任务唯一性
 func TestQueueClientTaskUniqueness(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	payload := map[string]string{
 		"request_id": "unique-001",
 		"to":         "test@example.com",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	// 第一次提交
 	task1 := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info1, err := client.Enqueue(task1,
 		asynq.TaskID("unique-task-001"),
 		asynq.Unique(1*time.Hour),
 	)
 	require.NoError(t, err)
 	assert.NotNil(t, info1)
 	// 第二次提交（重复）
 	task2 := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info2, err := client.Enqueue(task2,
 		asynq.TaskID("unique-task-001"),
 		asynq.Unique(1*time.Hour),
 	)
 	// 应该返回错误（任务已存在）
 	assert.Error(t, err)
 	assert.Nil(t, info2)
 }
 // TestQueuePriorityWeights 测试队列优先级权重
 func TestQueuePriorityWeights(t *testing.T) {
 	queues := map[string]int{
 		constants.QueueCritical: 6,
 		constants.QueueDefault:  3,
 		constants.QueueLow:      1,
 	}
 	// 验证权重总和
 	totalWeight := 0
 	for _, weight := range queues {
 		totalWeight += weight
 	}
 	assert.Equal(t, 10, totalWeight)
 	// 验证权重比例
 	assert.Equal(t, 0.6, float64(queues[constants.QueueCritical])/float64(totalWeight))
 	assert.Equal(t, 0.3, float64(queues[constants.QueueDefault])/float64(totalWeight))
 	assert.Equal(t, 0.1, float64(queues[constants.QueueLow])/float64(totalWeight))
 }
 // TestTaskPayloadSizeLimit 测试任务载荷大小限制
 func TestTaskPayloadSizeLimit(t *testing.T) {
 	tests := []struct {
 		name        string
 		payloadSize int
 		shouldError bool
 	}{
 		{
 			name:        "Small Payload (1KB)",
 			payloadSize: 1024,
 			shouldError: false,
 		},
 		{
 			name:        "Medium Payload (100KB)",
 			payloadSize: 100 * 1024,
 			shouldError: false,
 		},
 		{
 			name:        "Large Payload (1MB)",
 			payloadSize: 1024 * 1024,
 			shouldError: false,
 		},
 		// Redis 默认支持最大 512MB，但实际应用中不建议超过 1MB
 	}
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			// 创建指定大小的载荷
 			largeData := make([]byte, tt.payloadSize)
 			for i := range largeData {
 				largeData[i] = byte(i % 256)
 			}
 			payload := map[string]interface{}{
 				"request_id": "size-test-001",
 				"data":       largeData,
 			}
 			payloadBytes, err := sonic.Marshal(payload)
 			require.NoError(t, err)
 			task := asynq.NewTask(constants.TaskTypeDataSync, payloadBytes)
 			info, err := client.Enqueue(task)
 			if tt.shouldError {
 				assert.Error(t, err)
 			} else {
 				require.NoError(t, err)
 				assert.NotNil(t, info)
 			}
 		})
 	}
 }
 // TestTaskScheduling 测试任务调度
 func TestTaskScheduling(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	tests := []struct {
 		name         string
 		scheduleOpt  asynq.Option
 		expectedTime time.Time
 	}{
 		{
 			name:         "Process In 5 Seconds",
 			scheduleOpt:  asynq.ProcessIn(5 * time.Second),
 			expectedTime: time.Now().Add(5 * time.Second),
 		},
 		{
 			name:         "Process At Specific Time",
 			scheduleOpt:  asynq.ProcessAt(time.Now().Add(10 * time.Second)),
 			expectedTime: time.Now().Add(10 * time.Second),
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			payload := map[string]string{
 				"request_id": "schedule-test-" + tt.name,
 			}
 			payloadBytes, err := sonic.Marshal(payload)
 			require.NoError(t, err)
 			task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 			info, err := client.Enqueue(task, tt.scheduleOpt)
 			require.NoError(t, err)
 			assert.True(t, info.NextProcessAt.After(time.Now()))
 			// 允许 1 秒的误差
 			assert.WithinDuration(t, tt.expectedTime, info.NextProcessAt, 1*time.Second)
 		})
 	}
 }
 // TestQueueInspectorStats 测试队列统计
 func TestQueueInspectorStats(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	// 提交一些任务
 	for i := 0; i < 5; i++ {
 		payload := map[string]string{
 			"request_id": "stats-test-" + string(rune(i)),
 		}
 		payloadBytes, err := sonic.Marshal(payload)
 		require.NoError(t, err)
 		task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 		_, err = client.Enqueue(task)
 		require.NoError(t, err)
 	}
 	// 使用 Inspector 查询统计
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	info, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.Equal(t, 5, info.Pending)
 	assert.Equal(t, 0, info.Active)
 	assert.Equal(t, 0, info.Completed)
 }
 // TestTaskRetention 测试任务保留策略
 func TestTaskRetention(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	payload := map[string]string{
 		"request_id": "retention-test-001",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	// 提交任务并设置保留时间
 	task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info, err := client.Enqueue(task,
 		asynq.Retention(24*time.Hour), // 保留 24 小时
 	)
 	require.NoError(t, err)
 	assert.NotNil(t, info)
 }
 // TestQueueDraining 测试队列暂停和恢复
 func TestQueueDraining(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	// 暂停队列
 	err := inspector.PauseQueue(constants.QueueDefault)
 	require.NoError(t, err)
 	// 检查队列是否已暂停
 	info, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.True(t, info.Paused)
 	// 恢复队列
 	err = inspector.UnpauseQueue(constants.QueueDefault)
 	require.NoError(t, err)
 	// 检查队列是否已恢复
 	info, err = inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.False(t, info.Paused)
 }
 // TestTaskCancellation 测试任务取消
 func TestTaskCancellation(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	payload := map[string]string{
 		"request_id": "cancel-test-001",
 	}
 	payloadBytes, err := sonic.Marshal(payload)
 	require.NoError(t, err)
 	// 提交任务
 	task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 	info, err := client.Enqueue(task)
 	require.NoError(t, err)
 	// 取消任务
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	err = inspector.DeleteTask(constants.QueueDefault, info.ID)
 	require.NoError(t, err)
 	// 验证任务已删除
 	queueInfo, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.Equal(t, 0, queueInfo.Pending)
 }
 // TestBatchTaskEnqueue 测试批量任务入队
 func TestBatchTaskEnqueue(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	// 批量创建任务
 	batchSize := 100
 	for i := 0; i < batchSize; i++ {
 		payload := map[string]string{
 			"request_id": "batch-" + string(rune(i)),
 		}
 		payloadBytes, err := sonic.Marshal(payload)
 		require.NoError(t, err)
 		task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 		_, err = client.Enqueue(task)
 		require.NoError(t, err)
 	}
 	// 验证任务数量
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	info, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.Equal(t, batchSize, info.Pending)
 }
 // TestTaskGrouping 测试任务分组
 func TestTaskGrouping(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	client := asynq.NewClient(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer client.Close()
 	// 提交分组任务
 	groupKey := "email-batch-001"
 	for i := 0; i < 5; i++ {
 		payload := map[string]string{
 			"request_id": "group-" + string(rune(i)),
 			"group":      groupKey,
 		}
 		payloadBytes, err := sonic.Marshal(payload)
 		require.NoError(t, err)
 		task := asynq.NewTask(constants.TaskTypeEmailSend, payloadBytes)
 		_, err = client.Enqueue(task,
 			asynq.Group(groupKey),
 		)
 		require.NoError(t, err)
 	}
 	// 验证任务已按组提交
 	inspector := asynq.NewInspector(asynq.RedisClientOpt{
 		Addr: "localhost:6379",
 	})
 	defer inspector.Close()
 	info, err := inspector.GetQueueInfo(constants.QueueDefault)
 	require.NoError(t, err)
 	assert.GreaterOrEqual(t, info.Pending, 5)
 }
--- a/tests/unit/store_test.go
+++ b/tests/unit/store_test.go
@@ -0,0 +1,550 @@
 package unit
 import (
 	"context"
 	"errors"
 	"testing"
 	"time"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/zap"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
 )
 // setupTestStore 创建内存数据库用于单元测试
 func setupTestStore(t *testing.T) (*postgres.Store, func()) {
 	// 使用 SQLite 内存数据库进行单元测试
 	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
 		Logger: logger.Default.LogMode(logger.Silent),
 	})
 	require.NoError(t, err, "创建内存数据库失败")
 	// 自动迁移
 	err = db.AutoMigrate(&model.User{}, &model.Order{})
 	require.NoError(t, err, "数据库迁移失败")
 	// 创建测试 logger
 	testLogger := zap.NewNop()
 	store := postgres.NewStore(db, testLogger)
 	cleanup := func() {
 		sqlDB, _ := db.DB()
 		if sqlDB != nil {
 			sqlDB.Close()
 		}
 	}
 	return store, cleanup
 }
 // TestUserStore 测试用户 Store 层
 func TestUserStore(t *testing.T) {
 	store, cleanup := setupTestStore(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("创建用户成功", func(t *testing.T) {
 		user := &model.User{
 			Username: "testuser",
 			Email:    "test@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		assert.NoError(t, err)
 		assert.NotZero(t, user.ID)
 		assert.False(t, user.CreatedAt.IsZero())
 		assert.False(t, user.UpdatedAt.IsZero())
 	})
 	t.Run("创建重复用户名失败", func(t *testing.T) {
 		user1 := &model.User{
 			Username: "duplicate",
 			Email:    "user1@example.com",
 			Password: "password1",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user1)
 		require.NoError(t, err)
 		// 尝试创建相同用户名
 		user2 := &model.User{
 			Username: "duplicate",
 			Email:    "user2@example.com",
 			Password: "password2",
 			Status:   constants.UserStatusActive,
 		}
 		err = store.User.Create(ctx, user2)
 		assert.Error(t, err, "应该返回唯一约束错误")
 	})
 	t.Run("根据ID查询用户", func(t *testing.T) {
 		user := &model.User{
 			Username: "findbyid",
 			Email:    "findbyid@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		found, err := store.User.GetByID(ctx, user.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, user.Username, found.Username)
 		assert.Equal(t, user.Email, found.Email)
 	})
 	t.Run("查询不存在的用户", func(t *testing.T) {
 		_, err := store.User.GetByID(ctx, 99999)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 	t.Run("根据用户名查询用户", func(t *testing.T) {
 		user := &model.User{
 			Username: "findbyname",
 			Email:    "findbyname@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		found, err := store.User.GetByUsername(ctx, "findbyname")
 		assert.NoError(t, err)
 		assert.Equal(t, user.ID, found.ID)
 	})
 	t.Run("更新用户", func(t *testing.T) {
 		user := &model.User{
 			Username: "updatetest",
 			Email:    "update@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 更新用户
 		user.Email = "newemail@example.com"
 		user.Status = constants.UserStatusInactive
 		err = store.User.Update(ctx, user)
 		assert.NoError(t, err)
 		// 验证更新
 		found, err := store.User.GetByID(ctx, user.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, "newemail@example.com", found.Email)
 		assert.Equal(t, constants.UserStatusInactive, found.Status)
 	})
 	t.Run("软删除用户", func(t *testing.T) {
 		user := &model.User{
 			Username: "deletetest",
 			Email:    "delete@example.com",
 			Password: "hashedpassword",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		// 软删除
 		err = store.User.Delete(ctx, user.ID)
 		assert.NoError(t, err)
 		// 验证已删除
 		_, err = store.User.GetByID(ctx, user.ID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 	t.Run("分页列表查询", func(t *testing.T) {
 		// 创建10个用户
 		for i := 1; i <= 10; i++ {
 			user := &model.User{
 				Username: "listuser" + string(rune('0'+i)),
 				Email:    "list" + string(rune('0'+i)) + "@example.com",
 				Password: "password",
 				Status:   constants.UserStatusActive,
 			}
 			err := store.User.Create(ctx, user)
 			require.NoError(t, err)
 		}
 		// 第一页
 		users, total, err := store.User.List(ctx, 1, 5)
 		assert.NoError(t, err)
 		assert.GreaterOrEqual(t, len(users), 5)
 		assert.GreaterOrEqual(t, total, int64(10))
 		// 第二页
 		users2, total2, err := store.User.List(ctx, 2, 5)
 		assert.NoError(t, err)
 		assert.GreaterOrEqual(t, len(users2), 5)
 		assert.Equal(t, total, total2)
 		// 验证不同页的数据不同
 		if len(users) > 0 && len(users2) > 0 {
 			assert.NotEqual(t, users[0].ID, users2[0].ID)
 		}
 	})
 }
 // TestOrderStore 测试订单 Store 层
 func TestOrderStore(t *testing.T) {
 	store, cleanup := setupTestStore(t)
 	defer cleanup()
 	ctx := context.Background()
 	// 创建测试用户
 	user := &model.User{
 		Username: "orderuser",
 		Email:    "orderuser@example.com",
 		Password: "hashedpassword",
 		Status:   constants.UserStatusActive,
 	}
 	err := store.User.Create(ctx, user)
 	require.NoError(t, err)
 	t.Run("创建订单成功", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-TEST-001",
 			UserID:  user.ID,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 			Remark:  "测试订单",
 		}
 		err := store.Order.Create(ctx, order)
 		assert.NoError(t, err)
 		assert.NotZero(t, order.ID)
 		assert.False(t, order.CreatedAt.IsZero())
 	})
 	t.Run("创建重复订单号失败", func(t *testing.T) {
 		order1 := &model.Order{
 			OrderID: "ORD-DUP-001",
 			UserID:  user.ID,
 			Amount:  10000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order1)
 		require.NoError(t, err)
 		// 尝试创建相同订单号
 		order2 := &model.Order{
 			OrderID: "ORD-DUP-001",
 			UserID:  user.ID,
 			Amount:  20000,
 			Status:  constants.OrderStatusPending,
 		}
 		err = store.Order.Create(ctx, order2)
 		assert.Error(t, err, "应该返回唯一约束错误")
 	})
 	t.Run("根据ID查询订单", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-FIND-001",
 			UserID:  user.ID,
 			Amount:  20000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		found, err := store.Order.GetByID(ctx, order.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, order.OrderID, found.OrderID)
 		assert.Equal(t, order.Amount, found.Amount)
 	})
 	t.Run("根据订单号查询", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-FIND-002",
 			UserID:  user.ID,
 			Amount:  30000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		found, err := store.Order.GetByOrderID(ctx, "ORD-FIND-002")
 		assert.NoError(t, err)
 		assert.Equal(t, order.ID, found.ID)
 	})
 	t.Run("根据用户ID列表查询", func(t *testing.T) {
 		// 创建多个订单
 		for i := 1; i <= 5; i++ {
 			order := &model.Order{
 				OrderID: "ORD-LIST-" + string(rune('0'+i)),
 				UserID:  user.ID,
 				Amount:  int64(i * 10000),
 				Status:  constants.OrderStatusPending,
 			}
 			err := store.Order.Create(ctx, order)
 			require.NoError(t, err)
 		}
 		orders, total, err := store.Order.ListByUserID(ctx, user.ID, 1, 10)
 		assert.NoError(t, err)
 		assert.GreaterOrEqual(t, len(orders), 5)
 		assert.GreaterOrEqual(t, total, int64(5))
 	})
 	t.Run("更新订单状态", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-UPDATE-001",
 			UserID:  user.ID,
 			Amount:  50000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 更新状态
 		now := time.Now()
 		order.Status = constants.OrderStatusPaid
 		order.PaidAt = &now
 		err = store.Order.Update(ctx, order)
 		assert.NoError(t, err)
 		// 验证更新
 		found, err := store.Order.GetByID(ctx, order.ID)
 		assert.NoError(t, err)
 		assert.Equal(t, constants.OrderStatusPaid, found.Status)
 		assert.NotNil(t, found.PaidAt)
 	})
 	t.Run("软删除订单", func(t *testing.T) {
 		order := &model.Order{
 			OrderID: "ORD-DELETE-001",
 			UserID:  user.ID,
 			Amount:  60000,
 			Status:  constants.OrderStatusPending,
 		}
 		err := store.Order.Create(ctx, order)
 		require.NoError(t, err)
 		// 软删除
 		err = store.Order.Delete(ctx, order.ID)
 		assert.NoError(t, err)
 		// 验证已删除
 		_, err = store.Order.GetByID(ctx, order.ID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 }
 // TestStoreTransaction 测试事务功能
 func TestStoreTransaction(t *testing.T) {
 	store, cleanup := setupTestStore(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("事务提交成功", func(t *testing.T) {
 		var userID uint
 		var orderID uint
 		err := store.Transaction(ctx, func(tx *postgres.Store) error {
 			// 创建用户
 			user := &model.User{
 				Username: "txuser1",
 				Email:    "txuser1@example.com",
 				Password: "hashedpassword",
 				Status:   constants.UserStatusActive,
 			}
 			if err := tx.User.Create(ctx, user); err != nil {
 				return err
 			}
 			userID = user.ID
 			// 创建订单
 			order := &model.Order{
 				OrderID: "ORD-TX-001",
 				UserID:  user.ID,
 				Amount:  10000,
 				Status:  constants.OrderStatusPending,
 			}
 			if err := tx.Order.Create(ctx, order); err != nil {
 				return err
 			}
 			orderID = order.ID
 			return nil
 		})
 		assert.NoError(t, err)
 		// 验证用户和订单都已创建
 		user, err := store.User.GetByID(ctx, userID)
 		assert.NoError(t, err)
 		assert.Equal(t, "txuser1", user.Username)
 		order, err := store.Order.GetByID(ctx, orderID)
 		assert.NoError(t, err)
 		assert.Equal(t, "ORD-TX-001", order.OrderID)
 	})
 	t.Run("事务回滚", func(t *testing.T) {
 		var userID uint
 		err := store.Transaction(ctx, func(tx *postgres.Store) error {
 			// 创建用户
 			user := &model.User{
 				Username: "rollbackuser",
 				Email:    "rollback@example.com",
 				Password: "hashedpassword",
 				Status:   constants.UserStatusActive,
 			}
 			if err := tx.User.Create(ctx, user); err != nil {
 				return err
 			}
 			userID = user.ID
 			// 模拟错误，触发回滚
 			return errors.New("模拟错误")
 		})
 		assert.Error(t, err)
 		assert.Equal(t, "模拟错误", err.Error())
 		// 验证用户未创建（已回滚）
 		_, err = store.User.GetByID(ctx, userID)
 		assert.Error(t, err)
 		assert.Equal(t, gorm.ErrRecordNotFound, err)
 	})
 	t.Run("嵌套事务回滚", func(t *testing.T) {
 		var user1ID, user2ID uint
 		err := store.Transaction(ctx, func(tx1 *postgres.Store) error {
 			// 外层事务：创建第一个用户
 			user1 := &model.User{
 				Username: "nested1",
 				Email:    "nested1@example.com",
 				Password: "password",
 				Status:   constants.UserStatusActive,
 			}
 			if err := tx1.User.Create(ctx, user1); err != nil {
 				return err
 			}
 			user1ID = user1.ID
 			// 内层事务：创建第二个用户并失败
 			err := tx1.Transaction(ctx, func(tx2 *postgres.Store) error {
 				user2 := &model.User{
 					Username: "nested2",
 					Email:    "nested2@example.com",
 					Password: "password",
 					Status:   constants.UserStatusActive,
 				}
 				if err := tx2.User.Create(ctx, user2); err != nil {
 					return err
 				}
 				user2ID = user2.ID
 				// 内层事务失败
 				return errors.New("内层事务失败")
 			})
 			// 内层事务失败导致外层事务也失败
 			return err
 		})
 		assert.Error(t, err)
 		// 验证两个用户都未创建
 		_, err = store.User.GetByID(ctx, user1ID)
 		assert.Error(t, err)
 		_, err = store.User.GetByID(ctx, user2ID)
 		assert.Error(t, err)
 	})
 }
 // TestConcurrentAccess 测试并发访问
 func TestConcurrentAccess(t *testing.T) {
 	store, cleanup := setupTestStore(t)
 	defer cleanup()
 	ctx := context.Background()
 	t.Run("并发创建用户", func(t *testing.T) {
 		concurrency := 20
 		errChan := make(chan error, concurrency)
 		for i := 0; i < concurrency; i++ {
 			go func(index int) {
 				user := &model.User{
 					Username: "concurrent" + string(rune('A'+index)),
 					Email:    "concurrent" + string(rune('A'+index)) + "@example.com",
 					Password: "password",
 					Status:   constants.UserStatusActive,
 				}
 				errChan <- store.User.Create(ctx, user)
 			}(i)
 		}
 		// 收集结果
 		successCount := 0
 		for i := 0; i < concurrency; i++ {
 			err := <-errChan
 			if err == nil {
 				successCount++
 			}
 		}
 		assert.Equal(t, concurrency, successCount, "所有并发创建应该成功")
 	})
 	t.Run("并发读写同一用户", func(t *testing.T) {
 		// 创建测试用户
 		user := &model.User{
 			Username: "rwuser",
 			Email:    "rwuser@example.com",
 			Password: "password",
 			Status:   constants.UserStatusActive,
 		}
 		err := store.User.Create(ctx, user)
 		require.NoError(t, err)
 		concurrency := 10
 		done := make(chan bool, concurrency*2)
 		// 并发读
 		for i := 0; i < concurrency; i++ {
 			go func() {
 				_, err := store.User.GetByID(ctx, user.ID)
 				assert.NoError(t, err)
 				done <- true
 			}()
 		}
 		// 并发写
 		for i := 0; i < concurrency; i++ {
 			go func(index int) {
 				user.Status = constants.UserStatusActive
 				err := store.User.Update(ctx, user)
 				assert.NoError(t, err)
 				done <- true
 			}(i)
 		}
 		// 等待所有操作完成
 		for i := 0; i < concurrency*2; i++ {
 			<-done
 		}
 	})
 }
--- a/tests/unit/task_handler_test.go
+++ b/tests/unit/task_handler_test.go
@@ -0,0 +1,390 @@
 package unit
 import (
 	"context"
 	"testing"
 	"time"
 	"github.com/bytedance/sonic"
 	"github.com/hibiken/asynq"
 	"github.com/redis/go-redis/v9"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 )
 // MockEmailPayload 邮件任务载荷（测试用）
 type MockEmailPayload struct {
 	RequestID string   `json:"request_id"`
 	To        string   `json:"to"`
 	Subject   string   `json:"subject"`
 	Body      string   `json:"body"`
 	CC        []string `json:"cc,omitempty"`
 }
 // TestHandlerIdempotency 测试处理器幂等性逻辑
 func TestHandlerIdempotency(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	requestID := "test-req-001"
 	lockKey := constants.RedisTaskLockKey(requestID)
 	// 测试场景1: 第一次执行（未加锁）
 	t.Run("First Execution - Should Acquire Lock", func(t *testing.T) {
 		result, err := redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 		require.NoError(t, err)
 		assert.True(t, result, "第一次执行应该成功获取锁")
 	})
 	// 测试场景2: 重复执行（已加锁）
 	t.Run("Duplicate Execution - Should Skip", func(t *testing.T) {
 		result, err := redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 		require.NoError(t, err)
 		assert.False(t, result, "重复执行应该跳过（锁已存在）")
 	})
 	// 清理
 	redisClient.Del(ctx, lockKey)
 }
 // TestHandlerErrorHandling 测试处理器错误处理
 func TestHandlerErrorHandling(t *testing.T) {
 	tests := []struct {
 		name        string
 		payload     MockEmailPayload
 		shouldError bool
 		errorMsg    string
 	}{
 		{
 			name: "Valid Payload",
 			payload: MockEmailPayload{
 				RequestID: "valid-001",
 				To:        "test@example.com",
 				Subject:   "Test",
 				Body:      "Test Body",
 			},
 			shouldError: false,
 		},
 		{
 			name: "Missing RequestID",
 			payload: MockEmailPayload{
 				RequestID: "",
 				To:        "test@example.com",
 				Subject:   "Test",
 				Body:      "Test Body",
 			},
 			shouldError: true,
 			errorMsg:    "request_id 不能为空",
 		},
 		{
 			name: "Missing To",
 			payload: MockEmailPayload{
 				RequestID: "test-002",
 				To:        "",
 				Subject:   "Test",
 				Body:      "Test Body",
 			},
 			shouldError: true,
 			errorMsg:    "收件人不能为空",
 		},
 		{
 			name: "Invalid Email Format",
 			payload: MockEmailPayload{
 				RequestID: "test-003",
 				To:        "invalid-email",
 				Subject:   "Test",
 				Body:      "Test Body",
 			},
 			shouldError: true,
 			errorMsg:    "邮箱格式无效",
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			// 验证载荷
 			err := validateEmailPayload(&tt.payload)
 			if tt.shouldError {
 				require.Error(t, err)
 				assert.Contains(t, err.Error(), tt.errorMsg)
 			} else {
 				require.NoError(t, err)
 			}
 		})
 	}
 }
 // validateEmailPayload 验证邮件载荷（模拟实际处理器中的验证逻辑）
 func validateEmailPayload(payload *MockEmailPayload) error {
 	if payload.RequestID == "" {
 		return asynq.SkipRetry // 参数错误不重试
 	}
 	if payload.To == "" {
 		return asynq.SkipRetry
 	}
 	// 简单的邮箱格式验证
 	if payload.To != "" && !contains(payload.To, "@") {
 		return asynq.SkipRetry
 	}
 	return nil
 }
 func contains(s, substr string) bool {
 	for i := 0; i < len(s)-len(substr)+1; i++ {
 		if s[i:i+len(substr)] == substr {
 			return true
 		}
 	}
 	return false
 }
 // TestHandlerRetryLogic 测试重试逻辑
 func TestHandlerRetryLogic(t *testing.T) {
 	tests := []struct {
 		name        string
 		error       error
 		shouldRetry bool
 	}{
 		{
 			name:        "Retryable Error - Network Issue",
 			error:       assert.AnError,
 			shouldRetry: true,
 		},
 		{
 			name:        "Non-Retryable Error - Invalid Params",
 			error:       asynq.SkipRetry,
 			shouldRetry: false,
 		},
 		{
 			name:        "No Error",
 			error:       nil,
 			shouldRetry: false,
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			shouldRetry := tt.error != nil && tt.error != asynq.SkipRetry
 			assert.Equal(t, tt.shouldRetry, shouldRetry)
 		})
 	}
 }
 // TestPayloadDeserialization 测试载荷反序列化
 func TestPayloadDeserialization(t *testing.T) {
 	tests := []struct {
 		name        string
 		jsonPayload string
 		expectError bool
 	}{
 		{
 			name:        "Valid JSON",
 			jsonPayload: `{"request_id":"test-001","to":"test@example.com","subject":"Test","body":"Body"}`,
 			expectError: false,
 		},
 		{
 			name:        "Invalid JSON",
 			jsonPayload: `{invalid json}`,
 			expectError: true,
 		},
 		{
 			name:        "Empty JSON",
 			jsonPayload: `{}`,
 			expectError: false, // JSON 解析成功，但验证会失败
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			var payload MockEmailPayload
 			err := sonic.Unmarshal([]byte(tt.jsonPayload), &payload)
 			if tt.expectError {
 				require.Error(t, err)
 			} else {
 				require.NoError(t, err)
 			}
 		})
 	}
 }
 // TestTaskStatusTransition 测试任务状态转换
 func TestTaskStatusTransition(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	taskID := "task-transition-001"
 	statusKey := constants.RedisTaskStatusKey(taskID)
 	// 状态转换序列
 	transitions := []struct {
 		status string
 		valid  bool
 	}{
 		{"pending", true},
 		{"processing", true},
 		{"completed", true},
 		{"failed", false}, // completed 后不应该转到 failed
 	}
 	currentStatus := ""
 	for _, tr := range transitions {
 		t.Run("Transition to "+tr.status, func(t *testing.T) {
 			// 检查状态转换是否合法
 			if isValidTransition(currentStatus, tr.status) == tr.valid {
 				err := redisClient.Set(ctx, statusKey, tr.status, 7*24*time.Hour).Err()
 				require.NoError(t, err)
 				currentStatus = tr.status
 			} else {
 				// 不合法的转换应该被拒绝
 				assert.False(t, tr.valid)
 			}
 		})
 	}
 }
 // isValidTransition 检查状态转换是否合法
 func isValidTransition(from, to string) bool {
 	validTransitions := map[string][]string{
 		"":           {"pending"},
 		"pending":    {"processing", "failed"},
 		"processing": {"completed", "failed"},
 		"completed":  {}, // 终态
 		"failed":     {}, // 终态
 	}
 	allowed, exists := validTransitions[from]
 	if !exists {
 		return false
 	}
 	for _, valid := range allowed {
 		if valid == to {
 			return true
 		}
 	}
 	return false
 }
 // TestConcurrentTaskExecution 测试并发任务执行
 func TestConcurrentTaskExecution(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	// 模拟多个并发任务尝试获取同一个锁
 	requestID := "concurrent-test-001"
 	lockKey := constants.RedisTaskLockKey(requestID)
 	concurrency := 10
 	successCount := 0
 	done := make(chan bool, concurrency)
 	// 并发执行
 	for i := 0; i < concurrency; i++ {
 		go func() {
 			result, err := redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 			if err == nil && result {
 				successCount++
 			}
 			done <- true
 		}()
 	}
 	// 等待所有 goroutine 完成
 	for i := 0; i < concurrency; i++ {
 		<-done
 	}
 	// 验证只有一个成功获取锁
 	assert.Equal(t, 1, successCount, "只有一个任务应该成功获取锁")
 }
 // TestTaskTimeout 测试任务超时处理
 func TestTaskTimeout(t *testing.T) {
 	tests := []struct {
 		name          string
 		taskDuration  time.Duration
 		timeout       time.Duration
 		shouldTimeout bool
 	}{
 		{
 			name:          "Normal Execution",
 			taskDuration:  100 * time.Millisecond,
 			timeout:       1 * time.Second,
 			shouldTimeout: false,
 		},
 		{
 			name:          "Timeout Execution",
 			taskDuration:  2 * time.Second,
 			timeout:       500 * time.Millisecond,
 			shouldTimeout: true,
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			ctx, cancel := context.WithTimeout(context.Background(), tt.timeout)
 			defer cancel()
 			// 模拟任务执行
 			done := make(chan bool)
 			go func() {
 				time.Sleep(tt.taskDuration)
 				done <- true
 			}()
 			select {
 			case <-done:
 				assert.False(t, tt.shouldTimeout, "任务应该正常完成")
 			case <-ctx.Done():
 				assert.True(t, tt.shouldTimeout, "任务应该超时")
 			}
 		})
 	}
 }
 // TestLockExpiration 测试锁过期机制
 func TestLockExpiration(t *testing.T) {
 	redisClient := redis.NewClient(&redis.Options{
 		Addr: "localhost:6379",
 	})
 	defer redisClient.Close()
 	ctx := context.Background()
 	redisClient.FlushDB(ctx)
 	requestID := "expiration-test-001"
 	lockKey := constants.RedisTaskLockKey(requestID)
 	// 设置短 TTL 的锁
 	result, err := redisClient.SetNX(ctx, lockKey, "1", 100*time.Millisecond).Result()
 	require.NoError(t, err)
 	assert.True(t, result)
 	// 等待锁过期
 	time.Sleep(200 * time.Millisecond)
 	// 验证锁已过期，可以重新获取
 	result, err = redisClient.SetNX(ctx, lockKey, "1", 24*time.Hour).Result()
 	require.NoError(t, err)
 	assert.True(t, result, "锁过期后应该可以重新获取")
 }