junhong_cmp_fiber/openspec/changes/implement-order-expiration/design.md

Context

当前系统中待支付订单创建后不会自动失效，虽然 iot-order 和 order-payment 规格文档中提到了超时取消机制，但实际代码中完全未实现。这导致：

1. 数据库膨胀：大量"僵尸订单"（待支付但永不支付）占用存储空间
2. 用户体验差：无法明确订单是否有效，用户可能尝试支付已过期订单
3. 资源浪费：钱包余额被冻结但订单永不完成（混合支付场景）
4. 数据质量低：订单统计数据不准确（包含大量永不完成的订单）

现有实现：

• tb_order 表缺少 expires_at 字段
• 无超时相关的 Asynq 定时任务
• OrderService.Cancel() 方法不支持钱包解冻
• 无超时相关常量定义

技术栈：

• Asynq v0.24.x 任务队列（已用于佣金计算、轮询等异步任务）
• GORM v1.25.x ORM
• PostgreSQL 14+（已有索引优化经验）
• Redis 6.0+（已用于分布式锁、缓存）

Goals / Non-Goals

Goals:

1. 实现订单 30 分钟超时自动取消机制
2. 支持钱包余额自动解冻（混合支付/H5 钱包支付场景）
3. 提供过期状态查询和筛选功能
4. 性能符合要求（定时任务查询 < 50ms，单批处理 < 5s）
5. 支持数据库迁移和回滚
6. 不影响现有订单业务逻辑

Non-Goals:

1. ❌ 不支持可配置的超时时间（固定 30 分钟）
2. ❌ 不支持订单续期（延长过期时间）
3. ❌ 不发送超时提醒通知（后续可扩展）
4. ❌ 不处理已支付订单的退款超时（不在本次范围）
5. ❌ 不修改第三方支付回调逻辑（已有幂等保证）

Decisions

Decision 1: 数据库字段设计

选择: 新增 expires_at TIMESTAMP NULL 字段到 tb_order 表

理由:

• NULL 语义：已支付/已取消/已退款订单无需过期时间，设为 NULL 节省存储
• TIMESTAMP 类型：支持时区，精度到秒（超时 30 分钟，秒级精度足够）
• 索引设计：复合索引 idx_order_expires(expires_at, payment_status) 优化定时任务查询

替代方案:

• 使用 expired_at 字段名：不符合业务语义（expires_at 表示"何时过期"，expired_at 表示"何时已过期"）
• 使用 INT 存储 Unix 时间戳：可读性差，不利于 SQL 调试
• 使用单列索引 idx_expires_at：性能不如复合索引（WHERE 条件包含 payment_status）

数据迁移策略:

• 迁移时已存在的订单 expires_at 初始化为 NULL
• 不对历史待支付订单设置过期时间（避免批量取消历史订单）
• 新创建的待支付订单才设置过期时间

---

Decision 2: 定时任务实现方式

选择: 使用 Asynq 的 Scheduler（周期任务调度器），每分钟执行一次

理由:

• 架构统一性：项目已使用 Asynq 作为任务队列基础设施，定时任务也应统一使用 Asynq Scheduler（而非 time.Ticker）
• 分布式支持：多 Worker 部署时，通过 Redis 分布式锁确保任务只执行一次，避免重复处理超时订单
• 任务持久化：任务记录在 Redis，支持查询执行历史、监控失败率
• 自动重试：支持任务失败自动重试（可配置重试次数和延迟）
• 无额外依赖：复用现有 Redis 基础设施
• 未来扩展性：为项目中现有的 time.Ticker 定时任务（告警检查器、数据清理）迁移到 Asynq 提供范例

替代方案:

• 使用 time.Ticker/time.Timer：虽然简单，但多 Worker 部署时会重复执行，且无任务持久化和执行历史
• 使用 PostgreSQL pg_cron 扩展：增加数据库负载，不符合项目架构（业务逻辑在应用层）
• 使用独立的 Cron 服务：增加运维复杂度，技术栈碎片化

实现步骤:

1. 创建 Asynq Scheduler 实例（cmd/worker/main.go）：

   // 创建 Asynq Scheduler
   asynqScheduler := asynq.NewScheduler(
       asynq.RedisClientOpt{
           Addr:     redisAddr,
           Password: cfg.Redis.Password,
           DB:       cfg.Redis.DB,
       },
       &asynq.SchedulerOpts{
           Location: time.Local, // 使用本地时区
       },
   )
   

2. 注册周期任务：

   // 注册订单超时检查任务（每分钟执行）
   _, err := asynqScheduler.Register(
       "@every 1m",  // cron 表达式：每分钟
       asynq.NewTask(constants.TaskTypeOrderExpire, nil),
       asynq.Queue(constants.QueueDefault),
   )
   if err != nil {
       appLogger.Fatal("注册订单超时任务失败", zap.Error(err))
   }
   

3. 启动 Scheduler：

   if err := asynqScheduler.Start(); err != nil {
       appLogger.Fatal("启动 Asynq Scheduler 失败", zap.Error(err))
   }
   defer asynqScheduler.Shutdown()
   

4. 创建 Task Handler（internal/task/order_expire.go）：

   type OrderExpireHandler struct {
       orderService *order.Service
       logger       *zap.Logger
   }
   
   func (h *OrderExpireHandler) HandleOrderExpire(ctx context.Context, task *asynq.Task) error {
       count, err := h.orderService.CancelExpiredOrders(ctx)
       if err != nil {
           h.logger.Error("取消超时订单失败", zap.Error(err))
           return err // 返回错误，Asynq 自动重试
       }
   
       if count > 0 {
           h.logger.Info("成功取消超时订单", zap.Int("count", count))
       }
       return nil
   }
   

5. 注册 Handler（pkg/queue/handler.go）：

   func (h *Handler) registerOrderExpireHandler() {
       orderExpireHandler := task.NewOrderExpireHandler(
           h.workerResult.Services.OrderService,
           h.logger,
       )
       h.mux.HandleFunc(constants.TaskTypeOrderExpire, orderExpireHandler.HandleOrderExpire)
       h.logger.Info("注册订单超时检查任务处理器", zap.String("task_type", constants.TaskTypeOrderExpire))
   }
   

---

Decision 3: 批量处理策略

选择: 单次最多处理 100 条订单，使用事务批量更新

理由:

• 避免单次处理时间过长（单批 < 5s）
• 事务保证订单状态更新和钱包解冻的原子性
• 超过 100 条的订单在下次任务执行时处理（每分钟执行，延迟可接受）

替代方案:

• 使用 LIMIT 1000：单批处理时间可能超过 5s，影响任务调度
• 使用分页循环处理：复杂度高，事务范围难控制
• 不使用事务：订单状态更新和钱包解冻可能不一致

实现细节:

// 单批处理逻辑
func (s *Service) CancelExpiredOrders(ctx context.Context) (int, error) {
    // 1. 查询超时订单（最多 100 条）
    orders, err := s.orderStore.FindExpiredOrders(ctx, 100)

    // 2. 开启事务
    return len(orders), s.db.Transaction(func(tx *gorm.DB) error {
        // 3. 批量更新订单状态
        // 4. 批量解冻钱包余额（如需）
    })
}

---

Decision 4: 钱包余额解冻逻辑

选择: 在 OrderService.Cancel() 方法中统一处理解冻逻辑，支持手动取消和自动取消两种场景

理由:

• 代码复用：手动取消和自动取消共用同一解冻逻辑
• 事务保证：订单状态更新和钱包解冻在同一事务中
• 支持多种支付方式：钱包支付、混合支付

解冻规则:

支付方式	是否解冻	解冻金额
钱包支付（H5 端待支付）	✅	total_amount
混合支付	✅	wallet_payment_amount
纯在线支付（wechat/alipay）	❌	-
后台钱包一步支付	❌	- (订单创建时已完成支付)

替代方案:

• 在定时任务中直接解冻钱包：代码重复，手动取消时需重复实现
• 不在事务中解冻：可能导致订单已取消但钱包未解冻

实现细节:

func (s *Service) Cancel(ctx context.Context, orderID uint) error {
    return s.db.Transaction(func(tx *gorm.DB) error {
        // 1. 查询订单
        order, err := s.orderStore.GetByID(ctx, orderID)

        // 2. 校验状态（只能取消待支付订单）
        if order.PaymentStatus != model.PaymentStatusPending {
            return errors.New(errors.CodeInvalidParam, "只能取消待支付订单")
        }

        // 3. 更新订单状态
        order.PaymentStatus = model.PaymentStatusCancelled
        order.ExpiresAt = nil

        // 4. 解冻钱包余额（如需）
        if needUnfreeze(order) {
            amount := getUnfreezeAmount(order)
            err := s.walletService.Unfreeze(ctx, tx, order.BuyerType, order.BuyerID, amount)
        }

        return s.orderStore.Update(ctx, tx, order)
    })
}

---

Decision 5: 订单创建流程修改

选择: 在 OrderService.Create() 方法中，仅对待支付订单设置 expires_at

理由:

• 后台钱包一步支付订单创建时立即完成支付（payment_status = 2），无需过期时间
• 线下支付订单（offline）创建时立即标记为已支付，无需过期时间
• 只有 H5 端或后台创建的待支付订单需要设置过期时间

设置规则:

场景	订单状态	是否设置 expires_at
H5 端创建钱包支付订单	payment_status = 1	✅ now + 30min
H5 端创建在线支付订单（wechat/alipay）	payment_status = 1	✅ now + 30min
H5 端创建混合支付订单	payment_status = 1	✅ now + 30min
后台创建钱包支付订单	payment_status = 2	❌ NULL
后台创建线下支付订单	payment_status = 2	❌ NULL

实现细节:

func (s *Service) Create(ctx context.Context, req *dto.CreateOrderRequest) (*model.Order, error) {
    order := &model.Order{
        // ... 其他字段
        PaymentStatus: model.PaymentStatusPending,
    }

    // 仅待支付订单设置过期时间
    if order.PaymentStatus == model.PaymentStatusPending {
        expiresAt := time.Now().Add(constants.OrderExpireTimeout)
        order.ExpiresAt = &expiresAt
    }

    // 后台钱包一步支付逻辑
    if req.PaymentMethod == "wallet" && isAdminContext(ctx) {
        // 立即扣款并支付
        order.PaymentStatus = model.PaymentStatusPaid
        order.ExpiresAt = nil // 已支付订单无需过期时间
    }
}

---

Decision 6: 订单支付成功后清除过期时间

选择: 在订单支付成功时（payment_status 变更为 2），将 expires_at 设置为 NULL

理由:

• 已支付订单不需要过期时间
• 避免查询混淆（expires_at IS NOT NULL 可快速筛选待支付订单）
• 节省存储（NULL 值不占用索引空间）

实现位置:

• OrderService.WalletPay() - H5 端钱包支付成功
• OrderService.HandlePaymentCallback() - 第三方支付回调成功

实现细节:

func (s *Service) WalletPay(ctx context.Context, orderID uint) error {
    return s.db.Transaction(func(tx *gorm.DB) error {
        // ... 扣款逻辑

        // 更新订单状态并清除过期时间
        err := s.orderStore.UpdatePaymentStatus(ctx, tx, orderID, model.PaymentStatusPaid, time.Now(), nil)
    })
}

---

Decision 7: 查询过期状态实现方式

选择: 在 DTO 响应中动态计算 is_expired 字段，不存储在数据库

理由:

• 避免数据冗余（is_expired 可由 expires_at 和当前时间计算得出）
• 避免定时任务更新 is_expired 字段（增加数据库写负载）
• 支持按过期状态筛选（查询时使用 SQL 条件 expires_at <= NOW()）

替代方案:

• 在数据库中存储 is_expired 布尔字段：需要定时更新，增加数据库负载
• 使用数据库视图：不符合项目架构（不使用视图）

实现细节:

// DTO 响应
type OrderResponse struct {
    // ... 其他字段
    ExpiresAt *time.Time `json:"expires_at"`
    IsExpired bool       `json:"is_expired"` // 动态计算
}

// 动态计算逻辑
func buildOrderResponse(order *model.Order) *dto.OrderResponse {
    resp := &dto.OrderResponse{
        ExpiresAt: order.ExpiresAt,
    }

    // 动态计算是否过期
    if order.ExpiresAt != nil && order.PaymentStatus == model.PaymentStatusPending {
        resp.IsExpired = time.Now().After(*order.ExpiresAt)
    }

    return resp
}

// 查询过期订单的 SQL 条件
// WHERE expires_at <= NOW() AND payment_status = 1

---

Decision 8: 性能优化策略

选择: 使用复合索引 + 批量操作 + 事务优化

优化措施:

1. 索引优化: 复合索引 idx_order_expires(expires_at, payment_status) 覆盖查询条件
2. 批量更新: 单 SQL 语句批量更新订单状态（避免 N 次数据库调用）
3. 批量解冻: 钱包解冻支持批量操作（单事务中处理多个钱包）
4. 限制批次大小: 单次最多处理 100 条，避免长事务

性能指标:

• 定时任务查询耗时：< 50ms
• 单批次处理耗时：< 5s
• 数据库连接池无阻塞

监控指标:

• 每次任务处理的订单数量
• 任务执行耗时
• 钱包解冻次数
• 失败订单数量

---

Decision 9: 错误处理和重试策略

选择: 使用 Asynq 的重试机制，最多重试 3 次

重试策略:

• 可重试错误：数据库连接失败、Redis 连接失败、钱包服务暂时不可用
• 不可重试错误：数据不一致（如钱包不存在）、业务逻辑错误

实现细节:

func (h *OrderExpireHandler) HandleOrderExpire(ctx context.Context, task *asynq.Task) error {
    count, err := h.service.CancelExpiredOrders(ctx)
    if err != nil {
        h.logger.Error("取消超时订单失败", zap.Error(err))

        // 判断是否可重试
        if isRetryableError(err) {
            return err // 返回错误，Asynq 自动重试
        }

        return asynq.SkipRetry // 不可重试错误，跳过重试
    }

    h.logger.Info("取消超时订单成功", zap.Int("count", count))
    return nil
}

---

Decision 10: 常量定义

选择: 在 pkg/constants/constants.go 中定义超时相关常量

常量列表:

// 订单超时时间（30 分钟）
const OrderExpireTimeout = 30 * time.Minute

// 订单超时取消任务类型
const TaskTypeOrderExpire = "order:expire"

// 单批处理订单数量上限
const OrderExpireBatchSize = 100

理由:

• 统一管理常量，避免硬编码
• 便于后续调整（如修改超时时间）
• 符合项目规范（所有常量定义在 pkg/constants/）

---

Decision 11: 重构现有定时任务为 Asynq Scheduler

选择: 将现有的 time.Ticker/time.Timer 定时任务迁移到 Asynq Scheduler

理由:

• 统一任务调度机制：项目架构设计初衷就是用 Asynq 承载所有任务和定时功能
• 分布式支持：Asynq Scheduler 原生支持多 Worker 分布式执行，避免重复执行
• 持久化和可靠性：任务存储在 Redis，Worker 重启不丢失任务
• 监控和管理：通过 Asynq Dashboard 统一监控所有定时任务执行状态
• 代码一致性：避免混用多种定时任务实现方式

迁移范围:

定时任务	当前实现	迁移后
告警检查器 (startAlertChecker)	time.NewTicker(1 * time.Minute)	Asynq Scheduler @every 1m + TaskTypeAlertCheck
数据清理定时任务 (startCleanupScheduler)	time.NewTimer (每天凌晨2点)	Asynq Scheduler 0 2 * * * + TaskTypeDataCleanup

对比分析:

特性	time.Ticker/Timer	Asynq Scheduler
分布式支持	❌ 多 Worker 重复执行	✅ 自动去重，单次执行
任务持久化	❌ Worker 重启丢失	✅ 存储在 Redis
监控和管理	❌ 无统一界面	✅ Asynq Dashboard
错误重试	❌ 需手动实现	✅ 内置重试机制
代码复杂度	中等（需手动管理 goroutine）	低（声明式配置）
依赖	无（Go 标准库）	Redis

实现细节:

// 告警检查任务 Handler
type AlertCheckHandler struct {
    service *pollingSvc.AlertService
    logger  *zap.Logger
}

func (h *AlertCheckHandler) HandleAlertCheck(ctx context.Context, task *asynq.Task) error {
    if err := h.service.CheckAlerts(ctx); err != nil {
        h.logger.Error("告警检查失败", zap.Error(err))
        return err // Asynq 自动重试
    }
    h.logger.Info("告警检查成功")
    return nil
}

// 数据清理任务 Handler
type DataCleanupHandler struct {
    service *pollingSvc.CleanupService
    logger  *zap.Logger
}

func (h *DataCleanupHandler) HandleDataCleanup(ctx context.Context, task *asynq.Task) error {
    if err := h.service.RunScheduledCleanup(ctx); err != nil {
        h.logger.Error("数据清理失败", zap.Error(err))
        return err
    }
    h.logger.Info("数据清理成功")
    return nil
}

// 注册到 Asynq Scheduler（cmd/worker/main.go）
scheduler.Register("@every 1m", asynq.NewTask(constants.TaskTypeAlertCheck, nil))
scheduler.Register("0 2 * * *", asynq.NewTask(constants.TaskTypeDataCleanup, nil))

Cron 表达式说明:

• @every 1m - 每分钟执行（告警检查）
• 0 2 * * * - 每天凌晨 2:00 执行（数据清理）

迁移后的优势:

1. 统一架构: 所有定时任务都使用 Asynq Scheduler，代码风格一致
2. 易于管理: 通过 Asynq Dashboard 查看所有定时任务的执行历史和状态
3. 易于扩展: 新增定时任务只需注册 Cron 表达式，无需管理 goroutine
4. 可靠性提升: 任务持久化在 Redis，Worker 重启后自动恢复
5. 分布式友好: 多 Worker 部署时自动避免重复执行

风险和缓解:

• Redis 依赖: 如果 Redis 故障，定时任务无法执行
  • 缓解：Redis 高可用部署（主从 + 哨兵）
• 迁移风险: 迁移过程中可能遗漏某些任务
  • 缓解：保留旧代码注释，测试验证所有任务正常执行后再删除

Risks / Trade-offs

Risk 1: 定时任务延迟导致订单超时时间不精确

风险: 定时任务每分钟执行一次，订单实际取消时间可能晚于过期时间 1 分钟

影响: 低。30 分钟超时容忍 1 分钟误差（最多 3.3% 误差）

缓解措施:

• 在用户支付时检查订单是否过期（前端 + 后端双重校验）
• 在订单详情中显示过期时间，提示用户尽快支付

---

Risk 2: 批量处理可能导致部分订单取消失败

风险: 批量处理 100 条订单时，如果某个订单的钱包解冻失败，整个事务回滚

影响: 中。失败的订单会在下次任务执行时重新处理，但可能延迟 1 分钟

缓解措施:

• 使用 Asynq 重试机制（最多重试 3 次）
• 记录失败日志，便于排查问题
• 后续优化：考虑单个订单失败不影响其他订单（分批事务）

---

Risk 3: 钱包余额解冻失败导致用户损失

风险: 订单取消成功但钱包解冻失败（如钱包不存在、冻结余额不足）

影响: 高。用户钱包余额永久冻结

缓解措施:

• 在同一事务中处理订单取消和钱包解冻，任一失败则全部回滚
• 记录详细日志，包含订单 ID、钱包 ID、解冻金额
• 提供人工介入机制（运营后台手动解冻）

---

Risk 4: 数据库索引失效导致查询性能下降

风险: 随着订单数量增长，索引选择性下降，查询性能降低

影响: 中。定时任务查询耗时超过 50ms

缓解措施:

• 定期监控查询耗时
• 定期归档历史订单（如 6 个月前的已完成/已取消订单）
• 必要时调整索引策略（如分区表）

---

Risk 5: Redis 故障导致定时任务无法执行

风险: Redis 故障导致 Asynq 任务调度失败，超时订单无法取消

影响: 高。订单堆积，数据库膨胀

缓解措施:

• Redis 高可用部署（主从复制 + 哨兵）
• 监控 Redis 可用性和 Asynq 任务执行状态
• 提供手动触发取消超时订单的 API（运营后台）

---

Trade-off: 性能 vs 准确性

选择: 优先保证性能（每分钟执行，单批 100 条），牺牲部分准确性（延迟 1 分钟）

理由: 30 分钟超时场景下，1 分钟延迟影响可接受；性能更重要（避免数据库负载过高）

---

Trade-off: 代码复用 vs 逻辑独立

选择: Cancel() 方法同时支持手动取消和自动取消，逻辑复用

理由: 避免代码重复，降低维护成本；风险是逻辑耦合，但通过参数区分场景（手动 vs 自动）可缓解

Migration Plan

Phase 1: 数据库迁移（不影响业务）

1. 执行迁移脚本 migrations/000xxx_add_order_expiration.up.sql

   ALTER TABLE tb_order ADD COLUMN expires_at TIMESTAMP NULL COMMENT '订单过期时间';
   CREATE INDEX idx_order_expires ON tb_order(expires_at, payment_status);
   

2. 验证迁移成功：

   SHOW INDEX FROM tb_order WHERE Key_name = 'idx_order_expires';
   

3. 已存在的订单 expires_at 为 NULL（不影响现有业务）

回滚方案:

DROP INDEX idx_order_expires ON tb_order;
ALTER TABLE tb_order DROP COLUMN expires_at;

---

Phase 2: 代码部署（API 服务）

1. 部署修改后的 API 服务（包含 Create() 和 Cancel() 逻辑）
2. 验证新创建的订单 expires_at 字段正确设置
3. 验证手动取消订单时钱包解冻正常

验证步骤:

• 创建待支付订单，检查 expires_at 是否为 created_at + 30min
• 手动取消混合支付订单，检查钱包余额是否解冻
• 监控错误日志，确认无异常

---

Phase 3: 定时任务部署（Worker 服务）

1. 部署修改后的 Worker 服务（包含定时任务）
2. 在 cmd/worker/main.go 中注册周期任务
3. 验证定时任务执行正常

验证步骤:

• 检查 Asynq 日志，确认任务每分钟执行
• 人工创建过期订单（修改 expires_at 为过去时间），等待 1 分钟后检查订单状态
• 监控任务执行耗时和处理订单数量

---

Phase 4: 监控和告警

1. 配置 Prometheus 监控指标（任务执行次数、耗时、处理订单数）
2. 配置告警规则（任务执行失败、耗时超过 5s）
3. 定期检查定时任务执行日志

监控指标:

• order_expire_task_duration_seconds - 任务执行耗时
• order_expire_task_processed_total - 处理订单总数
• order_expire_task_failed_total - 失败次数

---

Rollback Strategy

如果出现严重问题，按以下顺序回滚:

1. 立即停止 Worker 服务（停止定时任务执行）
2. 回滚 API 服务代码（恢复到未修改的版本）
3. 回滚数据库（执行 migrations/000xxx_add_order_expiration.down.sql）

触发回滚的条件:

• 定时任务导致大量订单误取消
• 钱包余额解冻失败率 > 5%
• 数据库性能严重下降（查询耗时 > 500ms）

Open Questions

1. 是否需要发送订单超时通知？

   • 当前不发送通知（Non-Goal）
   • 后续可扩展（如微信模板消息、短信提醒）

2. 是否支持可配置的超时时间？

   • 当前固定 30 分钟（Non-Goal）
   • 后续可考虑按订单类型配置不同超时时间（如大额订单 1 小时）

3. 历史待支付订单如何处理？

   • 当前不处理（expires_at 为 NULL，不会被定时任务取消）
   • 建议：运营后台提供批量取消功能，人工清理历史订单

4. 是否需要订单超时后自动重建订单？

   • 当前不支持（Non-Goal）
   • 用户需要手动重新创建订单

5. 是否需要支持订单续期？

   • 当前不支持（Non-Goal）
   • 如需支持，需增加 API 端点和业务逻辑