feat: 技术债务清理（支付配置动态化、API文档补全、轮询常量提取、废弃代码清理）

pkg/constants/iot.go

@@ -186,11 +186,11 @@ const (
 	CommissionStatusPendingReview = 99 // 待人工修正（链路断裂，需平台处理）
 )
 
-// 阶梯类型
+// 阶梯类型（[预留] 用于分佣阶梯功能，待产品规划）
 const (
-	LadderTypeActivation = "activation" // 激活量
-	LadderTypePickup     = "pickup"     // 提货量
-	LadderTypeDeposit    = "deposit"    // 充值量
+	LadderTypeActivation = "activation" // 激活量（[预留]）
+	LadderTypePickup     = "pickup"     // 提货量（[预留]）
+	LadderTypeDeposit    = "deposit"    // 充值量（[预留]）
 )
 
 // 卡类型
@@ -199,17 +199,17 @@ const (
 	CardTypeIotCard    = "iot_card"    // IoT卡
 )
 
-// 审批类型
+// 审批类型（[预留] 用于审批流程功能，待产品规划）
 const (
-	ApprovalTypeAuto   = "auto"   // 自动
-	ApprovalTypeManual = "manual" // 人工
+	ApprovalTypeAuto   = "auto"   // 自动（[预留]）
+	ApprovalTypeManual = "manual" // 人工（[预留]）
 )
 
-// 审批状态
+// 审批状态（[预留] 用于审批流程功能，待产品规划）
 const (
-	ApprovalStatusPending  = 1 // 待审批
-	ApprovalStatusApproved = 2 // 已通过
-	ApprovalStatusRejected = 3 // 已拒绝
+	ApprovalStatusPending  = 1 // 待审批（[预留]）
+	ApprovalStatusApproved = 2 // 已通过（[预留]）
+	ApprovalStatusRejected = 3 // 已拒绝（[预留]）
 )
 
 // ========================================
@@ -231,23 +231,23 @@ const (
 	WithdrawalMethodBank   = "bank"   // 银行卡
 )
 
-// 商户类型
+// 商户类型（[预留] 用于未来商户管理功能，待产品规划）
 const (
-	MerchantTypeAlipay = "alipay" // 支付宝
-	MerchantTypeWechat = "wechat" // 微信
-	MerchantTypeBank   = "bank"   // 银行卡
+	MerchantTypeAlipay = "alipay" // 支付宝（[预留]）
+	MerchantTypeWechat = "wechat" // 微信（[预留]）
+	MerchantTypeBank   = "bank"   // 银行卡（[预留]）
 )
 
 // ========================================
 // 5. 系统管理常量
 // ========================================
 
-// 换卡申请状态
+// 换卡申请状态（[预留] 用于换卡申请功能，待产品规划）
 const (
-	ReplacementStatusPending   = 1 // 待处理
-	ReplacementStatusApproved  = 2 // 已通过
-	ReplacementStatusRejected  = 3 // 已拒绝
-	ReplacementStatusCompleted = 4 // 已完成
+	ReplacementStatusPending   = 1 // 待处理（[预留]）
+	ReplacementStatusApproved  = 2 // 已通过（[预留]）
+	ReplacementStatusRejected  = 3 // 已拒绝（[预留]）
+	ReplacementStatusCompleted = 4 // 已完成（[预留]）
 )
 
 // ========================================
@@ -261,10 +261,137 @@ const (
 	CarrierCodeCBN  = "CBN"  // 广电
 )
 
+// 换货原因（[预留] 用于换卡原因管理功能，待产品规划）
 const (
-	ReplacementReasonDamaged     = "damaged"
-	ReplacementReasonLost        = "lost"
-	ReplacementReasonMalfunction = "malfunction"
-	ReplacementReasonUpgrade     = "upgrade"
-	ReplacementReasonOther       = "other"
+	ReplacementReasonDamaged     = "damaged"     // 损坏（[预留]）
+	ReplacementReasonLost        = "lost"        // 丢失（[预留]）
+	ReplacementReasonMalfunction = "malfunction" // 故障（[预留]）
+	ReplacementReasonUpgrade     = "upgrade"     // 升级（[预留]）
+	ReplacementReasonOther       = "other"       // 其他（[预留]）
 )
+
+// ========================================
+// 状态名称映射函数
+// ========================================
+
+// GetIotCardStatusName 获取 IoT 卡业务状态名称
+// 对应 IotCardStatus* 常量：1=在库, 2=已分销, 3=已激活, 4=已停用
+func GetIotCardStatusName(status int) string {
+	switch status {
+	case IotCardStatusInStock:
+		return "在库"
+	case IotCardStatusDistributed:
+		return "已分销"
+	case IotCardStatusActivated:
+		return "已激活"
+	case IotCardStatusSuspended:
+		return "已停用"
+	default:
+		return "未知"
+	}
+}
+
+// GetActivationStatusName 获取激活状态名称
+// 对应 ActivationStatus* 常量：0=未激活, 1=已激活
+func GetActivationStatusName(status int) string {
+	switch status {
+	case ActivationStatusInactive:
+		return "未激活"
+	case ActivationStatusActive:
+		return "已激活"
+	default:
+		return "未知"
+	}
+}
+
+// GetRealNameStatusName 获取实名状态名称
+// 对应 RealNameStatus* 常量：0=未实名, 1=已实名
+func GetRealNameStatusName(status int) string {
+	switch status {
+	case RealNameStatusNotVerified:
+		return "未实名"
+	case RealNameStatusVerified:
+		return "已实名"
+	default:
+		return "未知"
+	}
+}
+
+// GetNetworkStatusName 获取网络状态名称
+// 对应 NetworkStatus* 常量：0=停机, 1=开机
+func GetNetworkStatusName(status int) string {
+	switch status {
+	case NetworkStatusOffline:
+		return "停机"
+	case NetworkStatusOnline:
+		return "开机"
+	default:
+		return "未知"
+	}
+}
+
+// GetCommissionRecordStatusName 获取佣金记录状态名称
+// 对应 CommissionStatus* 常量：1=已冻结, 2=解冻中, 3=已发放, 4=已失效, 99=待人工修正
+func GetCommissionRecordStatusName(status int) string {
+	switch status {
+	case CommissionStatusFrozen:
+		return "已冻结"
+	case CommissionStatusUnfreezing:
+		return "解冻中"
+	case CommissionStatusReleased:
+		return "已发放"
+	case CommissionStatusInvalid:
+		return "已失效"
+	case CommissionStatusPendingReview:
+		return "待人工修正"
+	default:
+		return "未知"
+	}
+}
+
+// GetOrderPaymentStatusName 获取订单支付状态名称
+// 1=待支付, 2=已支付, 3=已取消, 4=已退款
+func GetOrderPaymentStatusName(status int) string {
+	switch status {
+	case 1:
+		return "待支付"
+	case 2:
+		return "已支付"
+	case 3:
+		return "已取消"
+	case 4:
+		return "已退款"
+	default:
+		return "未知"
+	}
+}
+
+// GetOrderCommissionStatusName 获取订单佣金计算状态名称
+// 1=待计算, 2=已计算
+func GetOrderCommissionStatusName(status int) string {
+	switch status {
+	case 1:
+		return "待计算"
+	case 2:
+		return "已计算"
+	default:
+		return "未知"
+	}
+}
+
+// GetRefundStatusName 获取退款申请状态名称
+// 1=待审批, 2=已通过, 3=已拒绝, 4=已退回
+func GetRefundStatusName(status int) string {
+	switch status {
+	case 1:
+		return "待审批"
+	case 2:
+		return "已通过"
+	case 3:
+		return "已拒绝"
+	case 4:
+		return "已退回"
+	default:
+		return "未知"
+	}
+}