feat: 实现客户端换货系统（client-exchange-system）

新增完整换货生命周期管理：后台发起 → 客户端填收货信息 → 后台发货 → 确认完成（含可选全量迁移） → 旧资产转新再销售后台接口（7个）： - POST /api/admin/exchanges（发起换货） - GET /api/admin/exchanges（换货列表） - GET /api/admin/exchanges/:id（换货详情） - POST /api/admin/exchanges/:id/ship（发货） - POST /api/admin/exchanges/:id/complete（确认完成+可选迁移） - POST /api/admin/exchanges/:id/cancel（取消） - POST /api/admin/exchanges/:id/renew（旧资产转新）客户端接口（2个）： - GET /api/c/v1/exchange/pending（查询换货通知） - POST /api/c/v1/exchange/:id/shipping-info（填写收货信息）核心能力： - ExchangeOrder 模型与状态机（1待填写→2待发货→3已发货→4已完成，1/2可取消→5） - 全量迁移事务（11张表：钱包、套餐、标签、客户绑定等） - 旧资产转新（generation+1、状态重置、新钱包、历史隔离） - 旧 CardReplacementRecord 表改名为 legacy，is_replaced 过滤改为查新表 - 数据库迁移：000085 新建 tb_exchange_order，000086 旧表改名
2026-03-19 13:26:54 +08:00
parent df76e33105
commit e78f5794b9
41 changed files with 5242 additions and 10 deletions
--- a/pkg/constants/constants.go
+++ b/pkg/constants/constants.go
@@ -64,7 +64,8 @@ const (
 	TaskTypePackageDataReset       = "package:data:reset"       // 套餐流量重置

 	// 订单超时任务类型
-	TaskTypeOrderExpire = "order:expire" // 订单超时自动取消
+	TaskTypeOrderExpire               = "order:expire"                      // 订单超时自动取消
+	TaskTypeAutoPurchaseAfterRecharge = "task:auto_purchase_after_recharge" // 充值后自动购包

 	// 定时任务类型（由 Asynq Scheduler 调度）
 	TaskTypeAlertCheck  = "alert:check"  // 告警检查
@@ -205,8 +206,30 @@ const (
 	AuthorizerTypeAgent    = UserTypeAgent    // 代理账号授权(3)
 )

+// 自动代购状态常量（强充二阶段异步购买）
+const (
+	AutoPurchaseStatusPending = "pending" // 待处理
+	AutoPurchaseStatusSuccess = "success" // 成功
+	AutoPurchaseStatusFailed  = "failed"  // 失败
+)
+
 // 设备保护期相关时长常量
 const (
 	DeviceProtectPeriodDuration   = 1 * time.Hour    // 设备停/复机保护期时长（1小时）
 	DeviceRefreshCooldownDuration = 30 * time.Second // 设备网关刷新冷却时长（30秒）
 )
+
+// 换货单状态常量
+const (
+	ExchangeStatusPendingInfo = 1 // 待填写信息（等待客户端填写收货地址）
+	ExchangeStatusPendingShip = 2 // 待发货（客户端已填写，等待后台发货）
+	ExchangeStatusShipped     = 3 // 已发货待确认（后台已发货，等待确认完成）
+	ExchangeStatusCompleted   = 4 // 已完成
+	ExchangeStatusCancelled   = 5 // 已取消
+)
+
+// 换货资产类型常量
+const (
+	ExchangeAssetTypeIotCard = "iot_card" // 物联网卡
+	ExchangeAssetTypeDevice  = "device"   // 设备
+)
--- a/pkg/constants/redis.go
+++ b/pkg/constants/redis.go
@@ -329,6 +329,24 @@ func RedisOrderCreateLockKey(carrierType string, carrierID uint) string {
 	return fmt.Sprintf("order:create:lock:%s:%d", carrierType, carrierID)
 }

+// ========================================
+// 客户端购买相关 Redis Key
+// ========================================
+
+// RedisClientPurchaseIdempotencyKey 生成客户端套餐购买幂等性检测的 Redis 键
+// 用途：防止同一个人客户对同一资产重复提交购买请求（SETNX 快速拒绝）
+// 过期时间：3 分钟
+func RedisClientPurchaseIdempotencyKey(businessKey string) string {
+	return fmt.Sprintf("client:purchase:idempotency:%s", businessKey)
+}
+
+// RedisClientPurchaseLockKey 生成客户端套餐购买分布式锁的 Redis 键
+// 用途：防止同一资产的购买请求并发执行
+// 过期时间：10 秒
+func RedisClientPurchaseLockKey(assetType string, assetID uint) string {
+	return fmt.Sprintf("client:purchase:lock:%s:%d", assetType, assetID)
+}
+
 // ========================================
 // 设备保护期相关 Redis Key
 // ========================================
--- a/pkg/errors/codes.go
+++ b/pkg/errors/codes.go
@@ -149,6 +149,17 @@ const (
 	CodePhoneAlreadyBound       = 1184 // 手机号已被其他客户绑定
 	CodeAlreadyBoundPhone       = 1185 // 当前客户已绑定手机号，不可重复绑定
 	CodeOldPhoneMismatch        = 1186 // 旧手机号与当前绑定不匹配
+	CodeNeedRealname            = 1187 // 该套餐需实名认证后购买
+	CodeOpenIDNotFound          = 1188 // 未找到微信授权信息，请先完成授权
+
+	// 换货相关错误 (1200-1209)
+	CodeExchangeOrderNotFound      = 1200 // 换货单不存在
+	CodeExchangeInProgress         = 1201 // 存在进行中的换货单
+	CodeExchangeStatusInvalid      = 1202 // 换货单状态不允许此操作
+	CodeExchangeAssetTypeMismatch  = 1203 // 换货资产类型必须一致
+	CodeExchangeNewAssetNotInStock = 1204 // 新资产非在库状态
+	CodeExchangeAssetNotExchanged  = 1205 // 资产未处于已换货状态，不允许转新
+	CodeExchangeMigrationFailed    = 1206 // 数据迁移失败

 	// 服务端错误 (2000-2999) -> 5xx HTTP 状态码
 	CodeInternalError      = 2001 // 内部服务器错误
@@ -274,6 +285,15 @@ var allErrorCodes = []int{
 	CodePhoneAlreadyBound,
 	CodeAlreadyBoundPhone,
 	CodeOldPhoneMismatch,
+	CodeNeedRealname,
+	CodeOpenIDNotFound,
+	CodeExchangeOrderNotFound,
+	CodeExchangeInProgress,
+	CodeExchangeStatusInvalid,
+	CodeExchangeAssetTypeMismatch,
+	CodeExchangeNewAssetNotInStock,
+	CodeExchangeAssetNotExchanged,
+	CodeExchangeMigrationFailed,
 	CodeInternalError,
 	CodeDatabaseError,
 	CodeRedisError,
@@ -396,6 +416,15 @@ var errorMessages = map[int]string{
 	CodePhoneAlreadyBound:                 "手机号已被其他客户绑定",
 	CodeAlreadyBoundPhone:                 "当前客户已绑定手机号，不可重复绑定",
 	CodeOldPhoneMismatch:                  "旧手机号与当前绑定不匹配",
+	CodeNeedRealname:                      "该套餐需实名认证后购买",
+	CodeOpenIDNotFound:                    "未找到微信授权信息，请先完成授权",
+	CodeExchangeOrderNotFound:             "换货单不存在或无权限",
+	CodeExchangeInProgress:                "该资产存在进行中的换货单",
+	CodeExchangeStatusInvalid:             "换货单当前状态不允许此操作",
+	CodeExchangeAssetTypeMismatch:         "换货资产类型必须一致（卡换卡/设备换设备）",
+	CodeExchangeNewAssetNotInStock:        "新资产非在库状态，不可用于换货",
+	CodeExchangeAssetNotExchanged:         "资产当前状态不允许转新",
+	CodeExchangeMigrationFailed:           "换货数据迁移失败",
 	CodeInvalidCredentials:                "用户名或密码错误",
 	CodeAccountLocked:                     "账号已锁定",
 	CodePasswordExpired:                   "密码已过期",
--- a/pkg/openapi/handlers.go
+++ b/pkg/openapi/handlers.go
@@ -16,6 +16,12 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		Role:                        admin.NewRoleHandler(nil, nil),
 		Permission:                  admin.NewPermissionHandler(nil),
 		PersonalCustomer:            app.NewPersonalCustomerHandler(nil, nil),
+		ClientAsset:                 app.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil),
+		ClientWallet:                app.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil),
+		ClientOrder:                 app.NewClientOrderHandler(nil, nil, nil, nil, nil, nil, nil, nil),
+		ClientExchange:              app.NewClientExchangeHandler(nil),
+		ClientRealname:              app.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil),
+		ClientDevice:                app.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil),
 		Shop:                        admin.NewShopHandler(nil),
 		ShopRole:                    admin.NewShopRoleHandler(nil),
 		ShopCommission:              admin.NewShopCommissionHandler(nil),
@@ -40,6 +46,7 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		ShopPackageBatchPricing:     admin.NewShopPackageBatchPricingHandler(nil),
 		ShopSeriesGrant:             admin.NewShopSeriesGrantHandler(nil),
 		AdminOrder:                  admin.NewOrderHandler(nil, nil),
+		AdminExchange:               admin.NewExchangeHandler(nil, nil),
 		PaymentCallback:             callback.NewPaymentHandler(nil, nil, nil, nil),
 		PollingConfig:               admin.NewPollingConfigHandler(nil),
 		PollingConcurrency:          admin.NewPollingConcurrencyHandler(nil),