fix: 资产信息接口 device_realtime 字段返回固定假数据，避免前端因 nil 报错

Gateway 同步接口尚未对接，临时为设备类型资产返回 mock 数据，
后续对接后搜索 buildMockDeviceRealtime 替换为真实数据

.config/dbhub.toml

@@ -0,0 +1,13 @@
+[[sources]]
+id = "main"
+dsn = "postgresql://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable"
+
+[[tools]]
+name = "search_objects"
+source = "main"
+
+[[tools]]
+name = "execute_sql"
+source = "main"
+readonly = true    # Only allow SELECT, SHOW, DESCRIBE, EXPLAIN
+max_rows = 1000     # Limit query results

Makefile

@@ -7,8 +7,8 @@ GOCLEAN=$(GOCMD) clean
 GOTEST=$(GOCMD) test
 GOGET=$(GOCMD) get
 BINARY_NAME=bin/junhong-cmp
-MAIN_PATH=cmd/api/main.go
-WORKER_PATH=cmd/worker/main.go
+MAIN_PATH=./cmd/api
+WORKER_PATH=./cmd/worker
 WORKER_BINARY=bin/junhong-worker
 
 # Database migration parameters

cmd/api/docs.go

@@ -5,6 +5,8 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app"
 	"github.com/break/junhong_cmp_fiber/internal/routes"
 	"github.com/break/junhong_cmp_fiber/pkg/openapi"
 )
@@ -22,6 +24,15 @@ func generateOpenAPIDocs(outputPath string, logger *zap.Logger) {
 
 	// 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构）
 	handlers := openapi.BuildDocHandlers()
+	handlers.AssetLifecycle = admin.NewAssetLifecycleHandler(nil)
+	handlers.ClientAuth = apphandler.NewClientAuthHandler(nil, nil)
+	handlers.ClientAsset = apphandler.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientWallet = apphandler.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientOrder = apphandler.NewClientOrderHandler(nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientExchange = apphandler.NewClientExchangeHandler(nil)
+	handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientDevice = apphandler.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil)
+	handlers.AdminExchange = admin.NewExchangeHandler(nil, nil)
 
 	// 4. 注册所有路由到文档生成器
 	routes.RegisterRoutesWithDoc(app, handlers, &bootstrap.Middlewares{}, adminDoc)

cmd/api/main.go

@@ -27,6 +27,7 @@ import (
 	"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/sms"
 	"github.com/break/junhong_cmp_fiber/pkg/storage"
 )
 
@@ -42,8 +43,6 @@ func main() {
 	// 3. 初始化日志
 	appLogger := initLogger(cfg)
 
-	// 4. 验证微信配置
-	validateWechatConfig(cfg, appLogger)
 	defer func() {
 		_ = logger.Sync()
 	}()
@@ -247,14 +246,11 @@ func applyRateLimiterToBusinessRoutes(app *fiber.App, rateLimitMiddleware fiber.
 	adminGroup := app.Group("/api/admin")
 	adminGroup.Use(rateLimitMiddleware)
 
-	h5Group := app.Group("/api/h5")
-	h5Group.Use(rateLimitMiddleware)
-
 	personalGroup := app.Group("/api/c/v1")
 	personalGroup.Use(rateLimitMiddleware)
 
 	appLogger.Info("限流器已应用到业务路由组",
-		zap.Strings("paths", []string{"/api/admin", "/api/h5", "/api/c/v1"}),
+		zap.Strings("paths", []string{"/api/admin", "/api/c/v1"}),
 	)
 }
 
@@ -311,11 +307,42 @@ func initAuthComponents(cfg *config.Config, redisClient *redis.Client, appLogger
 	refreshTTL := time.Duration(cfg.JWT.RefreshTokenTTL) * time.Second
 	tokenManager := auth.NewTokenManager(redisClient, accessTTL, refreshTTL)
 
-	verificationSvc := verification.NewService(redisClient, nil, appLogger)
+	smsClient := initSMS(cfg, appLogger)
+	verificationSvc := verification.NewService(redisClient, smsClient, appLogger)
 
 	return jwtManager, tokenManager, verificationSvc
 }
 
+func initSMS(cfg *config.Config, appLogger *zap.Logger) *sms.Client {
+	if cfg.SMS.GatewayURL == "" {
+		appLogger.Info("短信服务未配置，跳过初始化")
+		return nil
+	}
+
+	timeout := cfg.SMS.Timeout
+	if timeout == 0 {
+		timeout = 10 * time.Second
+	}
+
+	httpClient := sms.NewStandardHTTPClient(0)
+	client := sms.NewClient(
+		cfg.SMS.GatewayURL,
+		cfg.SMS.Username,
+		cfg.SMS.Password,
+		cfg.SMS.Signature,
+		timeout,
+		appLogger,
+		httpClient,
+	)
+
+	appLogger.Info("短信服务已初始化",
+		zap.String("gateway_url", cfg.SMS.GatewayURL),
+		zap.String("signature", cfg.SMS.Signature),
+	)
+
+	return client
+}
+
 func initStorage(cfg *config.Config, appLogger *zap.Logger) *storage.Service {
 	if cfg.Storage.Provider == "" || cfg.Storage.S3.Endpoint == "" {
 		appLogger.Info("对象存储未配置，跳过初始化")
@@ -355,20 +382,3 @@ func initGateway(cfg *config.Config, appLogger *zap.Logger) *gateway.Client {
 
 	return client
 }
-
-func validateWechatConfig(cfg *config.Config, appLogger *zap.Logger) {
-	wechatCfg := cfg.Wechat
-
-	if wechatCfg.OfficialAccount.AppID == "" {
-		appLogger.Warn("微信公众号配置未设置，OAuth 相关功能将不可用")
-		return
-	}
-
-	if wechatCfg.OfficialAccount.AppSecret == "" {
-		appLogger.Fatal("微信公众号配置不完整",
-			zap.String("missing", "app_secret"),
-			zap.String("env", "JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET"))
-	}
-	appLogger.Info("微信公众号配置已验证",
-		zap.String("app_id", wechatCfg.OfficialAccount.AppID))
-}

cmd/gendocs/main.go

@@ -7,6 +7,8 @@ import (
 	"github.com/gofiber/fiber/v2"
 
 	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app"
 	"github.com/break/junhong_cmp_fiber/internal/routes"
 	"github.com/break/junhong_cmp_fiber/pkg/openapi"
 )
@@ -31,6 +33,15 @@ func generateAdminDocs(outputPath string) error {
 
 	// 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构）
 	handlers := openapi.BuildDocHandlers()
+	handlers.AssetLifecycle = admin.NewAssetLifecycleHandler(nil)
+	handlers.ClientAuth = apphandler.NewClientAuthHandler(nil, nil)
+	handlers.ClientAsset = apphandler.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientWallet = apphandler.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientOrder = apphandler.NewClientOrderHandler(nil, nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientExchange = apphandler.NewClientExchangeHandler(nil)
+	handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
+	handlers.ClientDevice = apphandler.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil)
+	handlers.AdminExchange = admin.NewExchangeHandler(nil, nil)
 
 	// 4. 注册所有路由到文档生成器
 	routes.RegisterRoutesWithDoc(app, handlers, &bootstrap.Middlewares{}, adminDoc)

docker-compose.prod.yml

@@ -22,9 +22,11 @@ version: '3.8'
 #
 # 可选配置（根据需要启用）：
 #   - Gateway 服务配置（JUNHONG_GATEWAY_*）
-#   - 微信公众号配置（JUNHONG_WECHAT_OFFICIAL_ACCOUNT_*）
-#   - 微信支付配置（JUNHONG_WECHAT_PAYMENT_*）
 #   - 对象存储配置（JUNHONG_STORAGE_*）
+#   - 短信服务配置（JUNHONG_SMS_*）
+#
+# 微信公众号/小程序/支付配置已迁移至数据库（tb_wechat_config 表），
+# 不再需要环境变量和证书文件挂载。
 
 services:
   api:
@@ -65,28 +67,13 @@ services:
       - JUNHONG_GATEWAY_APP_ID=LfjL0WjUqpwkItQ0
       - JUNHONG_GATEWAY_APP_SECRET=K0DYuWzbRE6zg5bX
       - JUNHONG_GATEWAY_TIMEOUT=30
-      # 微信公众号配置（可选）
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID=your_app_id
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET=your_app_secret
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN=your_token
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY=your_aes_key
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL=https://your-domain.com/callback
-      # 微信支付配置（可选）
-      # - JUNHONG_WECHAT_PAYMENT_APP_ID=your_app_id
-      # - JUNHONG_WECHAT_PAYMENT_MCH_ID=your_mch_id
-      # - JUNHONG_WECHAT_PAYMENT_API_V3_KEY=your_32_char_api_v3_key
-      # - JUNHONG_WECHAT_PAYMENT_API_V2_KEY=your_api_v2_key
-      # - JUNHONG_WECHAT_PAYMENT_CERT_PATH=/app/certs/apiclient_cert.pem
-      # - JUNHONG_WECHAT_PAYMENT_KEY_PATH=/app/certs/apiclient_key.pem
-      # - JUNHONG_WECHAT_PAYMENT_SERIAL_NO=your_serial_no
-      # - JUNHONG_WECHAT_PAYMENT_NOTIFY_URL=https://your-domain.com/api/callback/wechat-pay
-      # - JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG=false
-      # - JUNHONG_WECHAT_PAYMENT_TIMEOUT=30s
+      # 短信服务配置
+      - JUNHONG_SMS_GATEWAY_URL=https://gateway.sms.whjhft.com:8443
+      - JUNHONG_SMS_USERNAME=JH0001
+      - JUNHONG_SMS_PASSWORD=wwR8E4qnL6F0
+      - JUNHONG_SMS_SIGNATURE=【JHFTIOT】
     volumes:
-      # 仅挂载日志目录（配置已嵌入二进制文件）
       - ./logs:/app/logs
-      # 微信支付证书目录（如果使用微信支付，需要挂载证书）
-      # - ./certs:/app/certs:ro
     networks:
       - junhong-network
     healthcheck:
@@ -137,27 +124,8 @@ services:
       - JUNHONG_GATEWAY_APP_ID=60bgt1X8i7AvXqkd
       - JUNHONG_GATEWAY_APP_SECRET=BZeQttaZQt0i73moF
       - JUNHONG_GATEWAY_TIMEOUT=30
-      # 微信公众号配置（可选）
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID=your_app_id
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET=your_app_secret
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN=your_token
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY=your_aes_key
-      # - JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL=https://your-domain.com/callback
-      # 微信支付配置（可选）
-      # - JUNHONG_WECHAT_PAYMENT_APP_ID=your_app_id
-      # - JUNHONG_WECHAT_PAYMENT_MCH_ID=your_mch_id
-      # - JUNHONG_WECHAT_PAYMENT_API_V3_KEY=your_32_char_api_v3_key
-      # - JUNHONG_WECHAT_PAYMENT_API_V2_KEY=your_api_v2_key
-      # - JUNHONG_WECHAT_PAYMENT_CERT_PATH=/app/certs/apiclient_cert.pem
-      # - JUNHONG_WECHAT_PAYMENT_KEY_PATH=/app/certs/apiclient_key.pem
-      # - JUNHONG_WECHAT_PAYMENT_SERIAL_NO=your_serial_no
-      # - JUNHONG_WECHAT_PAYMENT_NOTIFY_URL=https://your-domain.com/api/callback/wechat-pay
-      # - JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG=false
-      # - JUNHONG_WECHAT_PAYMENT_TIMEOUT=30s
     volumes:
       - ./logs:/app/logs
-      # 微信支付证书目录（如果使用微信支付，需要挂载证书）
-      # - ./certs:/app/certs:ro
     networks:
       - junhong-network
     depends_on:

docs/client-api-data-model-fixes/功能总结.md

@@ -0,0 +1,128 @@
+# 客户端接口数据模型基础准备 - 功能总结
+
+## 概述
+
+本提案作为客户端接口系列的前置基础，完成三类工作：BUG 修复、基础字段准备、旧接口清理。
+
+## 一、BUG 修复
+
+### BUG-1：代理零售价修复
+
+**问题**：`ShopPackageAllocation` 缺少 `retail_price` 字段，所有渠道统一使用 `Package.SuggestedRetailPrice`，代理无法设定自己的零售价。
+
+**修复内容**：
+
+- `ShopPackageAllocation` 新增 `retail_price` 字段（迁移中存量数据批量回填为 `SuggestedRetailPrice`）
+- `GetPurchasePrice()` 改为按渠道取价：代理渠道返回 `allocation.RetailPrice`，平台渠道返回 `SuggestedRetailPrice`
+- `validatePackages()` 价格累加同步修正，代理渠道额外校验 `RetailPrice >= CostPrice`
+- 分配创建（`shop_package_batch_allocation`、`shop_series_grant`）时自动设置 `RetailPrice = SuggestedRetailPrice`
+- 新增 cost_price 分配锁定：存在下级分配记录时禁止修改 `cost_price`
+- `BatchUpdatePricing` 接口仅支持成本价批量调整（保留 cost_price 锁定规则）
+- 新增独立接口 `PATCH /api/admin/packages/:id/retail-price`，代理可修改自己的套餐零售价
+- `PackageResponse` 新增 `retail_price` 字段，利润计算修正为 `RetailPrice - CostPrice`
+
+**涉及文件**：
+- `internal/model/shop_package_allocation.go`
+- `internal/model/dto/shop_package_batch_pricing_dto.go`
+- `internal/model/dto/package_dto.go`
+- `internal/service/purchase_validation/service.go`
+- `internal/service/shop_package_batch_allocation/service.go`
+- `internal/service/shop_series_grant/service.go`
+- `internal/service/shop_package_batch_pricing/service.go`
+- `internal/service/package/service.go`
+
+### BUG-2：一次性佣金触发条件修复
+
+**问题**：后台所有订单（包括代理自购）都可能触发一次性佣金。
+
+**修复内容**：
+
+- `Order` 新增 `source` 字段（`admin`/`client`），默认 `admin`
+- 佣金触发条件从 `!order.IsPurchaseOnBehalf` 改为 `!order.IsPurchaseOnBehalf && order.Source == "client"`
+- `CreateAdminOrder()` 设置 `Source: constants.OrderSourceAdmin`
+
+**涉及文件**：
+- `internal/model/order.go`
+- `internal/service/commission_calculation/service.go`（两个方法）
+- `internal/service/order/service.go`
+
+### BUG-4：充值回调事务一致性修复
+
+**问题**：`HandlePaymentCallback` 中 `UpdateStatusWithOptimisticLock` 和 `UpdatePaymentInfo` 使用 `s.db` 而非事务内 `tx`。
+
+**修复内容**：
+
+- `AssetRechargeStore` 新增 `UpdateStatusWithOptimisticLockDB` 和 `UpdatePaymentInfoWithDB` 方法（支持传入 `tx`）
+- 原方法保留（委托调用新方法），确保向后兼容
+- `HandlePaymentCallback` 改用事务内 `tx` 调用
+
+**涉及文件**：
+- `internal/store/postgres/asset_recharge_store.go`
+- `internal/service/recharge/service.go`
+
+## 二、基础字段准备
+
+### 新增常量文件
+
+| 文件 | 内容 |
+|------|------|
+| `pkg/constants/asset_status.go` | 资产业务状态（在库/已销售/已换货/已停用） |
+| `pkg/constants/order_source.go` | 订单来源（admin/client） |
+| `pkg/constants/operator_type.go` | 操作人类型（admin_user/personal_customer） |
+| `pkg/constants/realname_link.go` | 实名链接类型（none/template/gateway） |
+
+### 模型字段变更
+
+| 模型 | 新增字段 | 说明 |
+|------|---------|------|
+| `IotCard` | `asset_status`, `generation` | 业务生命周期状态、资产世代编号 |
+| `Device` | `asset_status`, `generation` | 同上 |
+| `Order` | `source`, `generation` | 订单来源、资产世代快照 |
+| `PackageUsage` | `generation` | 资产世代快照 |
+| `AssetRechargeRecord` | `operator_type`, `generation`, `linked_package_ids`, `linked_order_type`, `linked_carrier_type`, `linked_carrier_id` | 操作人类型、世代、强充关联字段 |
+| `Carrier` | `realname_link_type`, `realname_link_template` | 实名链接配置 |
+| `ShopPackageAllocation` | `retail_price` | 代理零售价 |
+| `PersonalCustomer` | `wx_open_id` 索引变更 | 唯一索引改为普通索引 |
+
+### Carrier 管理 DTO 更新
+
+- `CarrierCreateRequest`、`CarrierUpdateRequest` 新增 `realname_link_type` 和 `realname_link_template` 字段
+- `CarrierResponse` 新增对应展示字段
+- Carrier Service 的 Create/Update 方法同步处理，Update 时 `template` 类型强制校验模板非空
+
+### 资产手动停用
+
+- 新增 `PATCH /api/admin/iot-cards/:id/deactivate` 和 `PATCH /api/admin/devices/:id/deactivate`
+- 仅 `asset_status` 为 1（在库）或 2（已销售）时允许停用
+- 使用条件更新确保幂等
+
+## 三、旧接口清理
+
+### H5 接口删除
+
+- 删除 `internal/handler/h5/` 全部文件（5 个）
+- 删除 `internal/routes/h5*.go`（3 个文件）
+- 清理 `routes.go`、`order.go`、`recharge.go` 中的 H5 路由注册
+- 清理 `bootstrap/` 中 H5 Handler 构造和字段
+- 清理 `middlewares.go` 中 H5 认证中间件
+- 清理 `pkg/openapi/handlers.go` 中 H5 文档生成引用
+- 清理 `cmd/api/main.go` 中 H5 限流挂载
+
+### 个人客户旧登录方法删除
+
+- 删除 `internal/handler/app/personal_customer.go` 中 Login、SendCode、WechatOAuthLogin、BindWechat 方法
+- 清理对应路由注册
+- 保留 UpdateProfile 和 GetProfile
+
+## 四、数据库迁移
+
+- 迁移编号：000082
+- 涉及 7 张表、15+ 个字段变更
+- 包含存量 `retail_price` 批量回填
+- 包含 `wx_open_id` 索引从唯一改为普通
+- 所有字段使用 `NOT NULL DEFAULT` 确保存量兼容
+
+## 五、后台订单 generation 快照
+
+- `CreateAdminOrder()` 创建订单时从资产（IotCard/Device）获取当前 `Generation` 值写入订单
+- 不再依赖数据库默认值 1

docs/client-auth-system/功能总结.md

@@ -0,0 +1,141 @@
+# C 端认证系统功能总结
+
+## 概述
+
+本次实现了面向个人客户（C 端）的完整认证体系，替代旧 H5 登录接口。支持微信公众号和小程序两种登录方式，基于「资产标识符验证 → 微信授权 → 自动绑定资产 → 可选绑定手机号」的流程。
+
+## 接口列表
+
+| 接口 | 路径 | 认证 | 说明 |
+|------|------|------|------|
+| A1 | `POST /api/c/v1/auth/verify-asset` | 否 | 资产标识符验证，返回 asset_token |
+| A2 | `POST /api/c/v1/auth/wechat-login` | 否 | 微信公众号登录 |
+| A3 | `POST /api/c/v1/auth/miniapp-login` | 否 | 微信小程序登录 |
+| A4 | `POST /api/c/v1/auth/send-code` | 否 | 发送手机验证码 |
+| A5 | `POST /api/c/v1/auth/bind-phone` | 是 | 首次绑定手机号 |
+| A6 | `POST /api/c/v1/auth/change-phone` | 是 | 换绑手机号（双验证码） |
+| A7 | `POST /api/c/v1/auth/logout` | 是 | 退出登录 |
+
+## 登录流程
+
+```
+用户输入资产标识符（SN/IMEI/ICCID）
+    │
+    ▼
+[A1] verify-asset → asset_token（5分钟有效）
+    │
+    ▼
+微信授权（前端完成）
+    │
+    ├── 公众号 → [A2] wechat-login (code + asset_token)
+    └── 小程序 → [A3] miniapp-login (code + asset_token)
+                    │
+                    ▼
+             解析 asset_token → 获取微信 openid
+             → 查找/创建客户 → 绑定资产
+             → 签发 JWT + Redis 存储
+                    │
+                    ▼
+             返回 { token, need_bind_phone, is_new_user }
+                    │
+                    ▼
+             need_bind_phone == true?
+                 YES → [A4] 发送验证码 → [A5] 绑定手机号
+                 NO  → 进入主页面
+```
+
+## 核心设计
+
+### 有状态 JWT（JWT + Redis）
+
+- JWT payload 仅含 `customer_id` + `exp`
+- 登录时将 token 写入 Redis，TTL 与 JWT 一致
+- 每次请求在中间件同时校验 JWT 签名和 Redis 有效状态
+- 支持服务端主动失效（封禁、强制下线、退出登录）
+- 单点登录：新登录覆盖旧 token
+
+### OpenID 多记录管理
+
+- 新增 `tb_personal_customer_openid` 表
+- 同一客户可在多个 AppID（公众号/小程序）下拥有不同 OpenID
+- 唯一约束：`UNIQUE(app_id, open_id) WHERE deleted_at IS NULL`
+- 客户查找逻辑：openid 精确匹配 → unionid 回退合并 → 创建新客户
+
+### 资产绑定
+
+- 每次登录创建 `PersonalCustomerDevice` 绑定记录
+- 同一资产允许被多个客户绑定（支持转手场景）
+- 首次绑定时自动将资产状态从「在库(1)」更新为「已销售(2)」
+
+### 微信配置动态加载
+
+- 登录时从数据库 `tb_wechat_config` 动态读取激活配置
+- 优先走 WechatConfigService 的 Redis 缓存
+- 小程序登录直接 HTTP 调用微信 `jscode2session`（不依赖 PowerWeChat SDK）
+
+## 限流策略
+
+| 接口 | 维度 | 限制 |
+|------|------|------|
+| A1 | IP | 30 次/分钟 |
+| A4 | 手机号 | 60 秒冷却 |
+| A4 | IP | 20 次/小时 |
+| A4 | 手机号 | 10 次/天 |
+
+## 新增/修改文件
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `internal/model/personal_customer_openid.go` | OpenID 关联模型 |
+| `internal/model/dto/client_auth_dto.go` | A1-A7 请求/响应 DTO |
+| `internal/store/postgres/personal_customer_openid_store.go` | OpenID Store |
+| `internal/service/client_auth/service.go` | 认证 Service（核心业务逻辑） |
+| `internal/handler/app/client_auth.go` | 认证 Handler（7 个端点） |
+| `pkg/wechat/miniapp.go` | 小程序 SDK 封装 |
+| `migrations/000083_add_personal_customer_openid.up.sql` | 迁移文件 |
+| `migrations/000083_add_personal_customer_openid.down.sql` | 回滚文件 |
+
+### 修改文件
+
+| 文件 | 说明 |
+|------|------|
+| `internal/middleware/personal_auth.go` | 增加 Redis 双重校验 |
+| `pkg/constants/redis.go` | 新增 token 和限流 Redis Key |
+| `pkg/errors/codes.go` | 新增错误码 1180-1186 |
+| `pkg/config/defaults/config.yaml` | 新增 `client.require_phone_binding` |
+| `pkg/wechat/wechat.go` | 新增 MiniAppServiceInterface |
+| `pkg/wechat/config.go` | 新增 3 个 DB 动态工厂函数 |
+| `internal/bootstrap/types.go` | 新增 ClientAuth Handler 字段 |
+| `internal/bootstrap/handlers.go` | 实例化 ClientAuth Handler |
+| `internal/bootstrap/services.go` | 初始化 ClientAuth Service |
+| `internal/bootstrap/stores.go` | 初始化 OpenID Store |
+| `internal/routes/personal.go` | 注册 7 个认证端点 |
+| `cmd/api/docs.go` | 注册文档生成器 |
+| `cmd/gendocs/main.go` | 注册文档生成器 |
+
+## 错误码
+
+| 码值 | 常量名 | 说明 |
+|------|--------|------|
+| 1180 | CodeAssetNotFound | 资产不存在 |
+| 1181 | CodeWechatConfigUnavailable | 微信配置不可用 |
+| 1182 | CodeSmsSendFailed | 短信发送失败 |
+| 1183 | CodeVerificationCodeInvalid | 验证码错误或已过期 |
+| 1184 | CodePhoneAlreadyBound | 手机号已被其他客户绑定 |
+| 1185 | CodeAlreadyBoundPhone | 已绑定手机号不可重复绑定 |
+| 1186 | CodeOldPhoneMismatch | 旧手机号与当前绑定不匹配 |
+
+## 数据库变更
+
+- 新建表 `tb_personal_customer_openid`（迁移 000083）
+- 唯一索引：`idx_pco_app_id_open_id` (app_id, open_id) 软删除条件
+- 普通索引：`idx_pco_customer_id` (customer_id)
+- 条件索引：`idx_pco_union_id` (union_id) WHERE union_id != ''
+
+## 配置项
+
+| 配置路径 | 环境变量 | 默认值 | 说明 |
+|---------|---------|-------|------|
+| `client.require_phone_binding` | `JUNHONG_CLIENT_REQUIRE_PHONE_BINDING` | `true` | 是否要求绑定手机号 |

docs/client-core-business-api/功能总结.md

@@ -0,0 +1,122 @@
+# 客户端核心业务 API — 功能总结
+
+## 概述
+
+本提案为客户端（C 端个人客户）提供完整的业务接口，覆盖资产查询、钱包充值、套餐购买、实名跳转、设备操作 5 大模块共 18 个 API 端点，全部挂载在 `/api/c/v1/` 路径下。
+
+**前置依赖**：提案 0（数据模型修复）、提案 1（C 端认证系统）。
+
+## API 端点一览
+
+### 模块 B：资产信息（4 个接口）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/c/v1/asset/info` | B1 资产基本信息查询 |
+| GET | `/api/c/v1/asset/packages` | B2 可购买套餐列表 |
+| GET | `/api/c/v1/asset/package-history` | B3 历史套餐列表 |
+| POST | `/api/c/v1/asset/refresh` | B4 手动刷新资产状态 |
+
+### 模块 C：钱包与充值（5 个接口）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/c/v1/wallet/detail` | C1 钱包详情（不存在自动创建） |
+| GET | `/api/c/v1/wallet/transactions` | C2 钱包流水列表 |
+| GET | `/api/c/v1/wallet/recharge-check` | C3 充值预检（强充检查） |
+| POST | `/api/c/v1/wallet/recharge` | C4 创建充值订单（JSAPI 支付） |
+| GET | `/api/c/v1/wallet/recharges` | C5 充值订单列表 |
+
+### 模块 D：套餐购买（3 个接口）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/c/v1/orders/create` | D1 创建套餐购买订单（含强充分流） |
+| GET | `/api/c/v1/orders` | D2 套餐订单列表 |
+| GET | `/api/c/v1/orders/:id` | D3 套餐订单详情 |
+
+### 模块 E：实名认证（1 个接口）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/c/v1/realname/link` | E1 获取实名跳转链接 |
+
+### 模块 F：设备能力（5 个接口）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/c/v1/device/cards` | F1 设备卡列表 |
+| POST | `/api/c/v1/device/reboot` | F2 设备重启 |
+| POST | `/api/c/v1/device/factory-reset` | F3 恢复出厂设置 |
+| POST | `/api/c/v1/device/wifi` | F4 设置 WiFi |
+| POST | `/api/c/v1/device/switch-card` | F5 切卡 |
+
+## 核心设计决策
+
+### 1. 数据权限绕过
+
+客户端调用后台复用 Service 时，统一使用 `gorm.SkipDataPermission(ctx)` 绕过 shop_id 自动过滤，避免个人客户因非店铺主体被误拦截。
+
+### 2. 归属校验
+
+所有涉及资产操作的接口统一前置归属校验：查询 `PersonalCustomerDevice` 条件 `customer_id = 当前登录客户` 且 `virtual_no = 资产虚拟号`，未命中返回 403。
+
+### 3. Generation 过滤
+
+客户端历史查询统一附加 `WHERE generation = 资产当前 generation`，确保转手后数据隔离。
+
+### 4. OpenID 安全规范
+
+支付接口（C4/D1）所需 OpenID 由后端按 `customer_id + app_type` 查询，客户端禁止传入 OpenID。根据 `app_type` 选择对应的微信 AppID 创建支付实例。
+
+### 5. 强充两阶段
+
+- 第一阶段（同步）：充值入账、更新状态
+- 第二阶段（异步 Asynq）：钱包扣款 → 创建订单 → 激活套餐
+
+`AssetRechargeRecord.auto_purchase_status` 字段追踪异步状态（pending/success/failed）。
+
+## 新增文件
+
+```
+internal/model/dto/client_asset_dto.go            # 资产模块 DTO
+internal/model/dto/client_wallet_dto.go            # 钱包模块 DTO
+internal/model/dto/client_order_dto.go             # 订单模块 DTO
+internal/model/dto/client_realname_device_dto.go   # 实名+设备模块 DTO
+internal/handler/app/client_asset.go               # 资产 Handler
+internal/handler/app/client_wallet.go              # 钱包 Handler
+internal/handler/app/client_order.go               # 订单 Handler
+internal/handler/app/client_realname.go            # 实名 Handler
+internal/handler/app/client_device.go              # 设备 Handler
+internal/service/client_order/service.go           # 客户端订单编排 Service
+internal/task/auto_purchase.go                     # 强充异步自动购买任务
+migrations/000084_add_auto_purchase_status_*.sql   # 数据库迁移
+```
+
+## 修改文件
+
+```
+pkg/constants/constants.go      # 新增 auto_purchase_status 常量 + 任务类型
+pkg/constants/redis.go           # 新增客户端购买幂等键
+pkg/errors/codes.go              # 新增 NEED_REALNAME/OPENID_NOT_FOUND 错误码
+internal/model/asset_wallet.go   # AssetRechargeRecord 新增字段
+internal/bootstrap/types.go      # 5 个 Handler 字段
+internal/bootstrap/handlers.go   # Handler 实例化
+internal/routes/personal.go      # 18 个路由注册
+pkg/openapi/handlers.go          # 文档生成 Handler
+cmd/api/docs.go                  # 文档注册
+cmd/gendocs/main.go              # 文档注册
+```
+
+## 新增错误码
+
+| 错误码 | 常量名 | 消息 |
+|--------|--------|------|
+| 1187 | CodeNeedRealname | 该套餐需实名认证后购买 |
+| 1188 | CodeOpenIDNotFound | 未找到微信授权信息，请先完成授权 |
+
+## 数据库变更
+
+- 表：`tb_asset_recharge_record`
+- 新增字段：`auto_purchase_status VARCHAR(20) DEFAULT '' NOT NULL`
+- 迁移版本：000084

docs/client-exchange-system/功能总结.md

@@ -0,0 +1,94 @@
+# 客户端换货系统功能总结
+
+## 1. 功能概述
+
+本次实现完成了客户端换货系统的后台与客户端闭环能力，覆盖「后台建单 → 客户端填写收货信息 → 后台发货 → 后台确认完成（可选全量迁移） → 旧资产转新」完整流程。
+
+## 2. 数据模型与迁移
+
+- 新增 `tb_exchange_order` 表，承载换货生命周期全量字段：旧/新资产、收货信息、物流信息、迁移状态、业务状态、多租户字段。
+- 保留历史能力：将旧表 `tb_card_replacement_record` 重命名为 `tb_card_replacement_record_legacy`。
+- 新增迁移文件：
+  - `000085_add_exchange_order.up/down.sql`
+  - `000086_rename_card_replacement_to_legacy.up/down.sql`
+
+## 3. 后端实现
+
+### 3.1 Store 层
+
+- 新增 `ExchangeOrderStore`：
+  - 创建、按 ID 查询、分页列表查询
+  - 条件状态流转更新（`WHERE status = fromStatus`）
+  - 按旧资产查询进行中换货单（状态 `1/2/3`）
+
+- 新增 `ResourceTagStore`：用于资源标签复制。
+
+### 3.2 Service 层
+
+- 新增 `internal/service/exchange/service.go`：
+  - H1 创建换货单（资产存在校验、进行中校验、单号生成、状态初始化）
+  - H2 列表查询
+  - H3 详情查询
+  - H4 发货（状态校验、同类型校验、新资产在库校验、物流与新资产快照写入）
+  - H5 确认完成（状态校验，可选全量迁移）
+  - H6 取消（仅允许 `1/2 -> 5`）
+  - H7 转新（校验已换货状态、`generation+1`、状态重置、清理绑定、创建新钱包）
+  - G1 查询待处理换货单
+  - G2 提交收货信息（`1 -> 2`）
+
+- 新增 `internal/service/exchange/migration.go`：
+  - 单事务迁移实现
+  - 钱包余额迁移并写入迁移流水
+  - 套餐使用记录迁移（`tb_package_usage`）
+  - 套餐日记录联动更新（`tb_package_usage_daily_record`）
+  - 累计充值/首充字段复制（旧资产 -> 新资产）
+  - 标签复制（`tb_resource_tag`）
+  - 客户绑定 `virtual_no` 更新（`tb_personal_customer_device`）
+  - 旧资产状态置为已换货（`asset_status=3`）
+  - 换货单迁移结果回写（`migration_completed`、`migration_balance`）
+
+## 4. Handler 与路由
+
+### 4.1 后台换货接口
+
+- 新增 `internal/handler/admin/exchange.go`
+- 新增 `internal/routes/exchange.go`
+- 注册接口（标签：`换货管理`）：
+  - `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`
+
+### 4.2 客户端换货接口
+
+- 新增 `internal/handler/app/client_exchange.go`
+- 在 `internal/routes/personal.go` 注册：
+  - `GET /api/c/v1/exchange/pending`
+  - `POST /api/c/v1/exchange/:id/shipping-info`
+
+## 5. 兼容与替换
+
+- `iot_card_store.go` 的 `is_replaced` 过滤逻辑已切换至 `tb_exchange_order`。
+- 业务主流程不再依赖旧换卡表（仅模型与 legacy 表保留用于历史数据）。
+
+## 6. 启动装配与文档生成
+
+已完成换货模块在以下位置的全链路接入：
+
+- `internal/bootstrap/types.go`
+- `internal/bootstrap/stores.go`
+- `internal/bootstrap/services.go`
+- `internal/bootstrap/handlers.go`
+- `internal/routes/admin.go`
+- `pkg/openapi/handlers.go`
+- `cmd/api/docs.go`
+- `cmd/gendocs/main.go`
+
+## 7. 验证结果
+
+- 已执行：`go build ./...`，编译通过。
+- 已执行：数据库迁移 `make migrate-up`，版本到 `86`。
+- 已完成：变更文件 LSP 诊断检查（无 error 级问题）。

internal/bootstrap/dependencies.go

@@ -24,6 +24,5 @@ type Dependencies struct {
 	QueueClient         *queue.Client                  // Asynq 任务队列客户端
 	StorageService      *storage.Service               // 对象存储服务（可选，配置缺失时为 nil）
 	GatewayClient       *gateway.Client                // Gateway API 客户端（可选，配置缺失时为 nil）
-	WechatOfficialAccount wechat.OfficialAccountServiceInterface // 微信公众号服务（可选）
 	WechatPayment       wechat.PaymentServiceInterface // 微信支付服务（可选）
 }

internal/bootstrap/handlers.go

@@ -5,12 +5,41 @@ import (
 	"github.com/break/junhong_cmp_fiber/internal/handler/app"
 	authHandler "github.com/break/junhong_cmp_fiber/internal/handler/auth"
 	"github.com/break/junhong_cmp_fiber/internal/handler/callback"
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
+	clientOrderSvc "github.com/break/junhong_cmp_fiber/internal/service/client_order"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/go-playground/validator/v10"
 )
 
 func initHandlers(svc *services, deps *Dependencies) *Handlers {
 	validate := validator.New()
+	personalCustomerDeviceStore := postgres.NewPersonalCustomerDeviceStore(deps.DB)
+	assetWalletStore := postgres.NewAssetWalletStore(deps.DB, deps.Redis)
+	packageStore := postgres.NewPackageStore(deps.DB)
+	shopPackageAllocationStore := postgres.NewShopPackageAllocationStore(deps.DB)
+	iotCardStore := postgres.NewIotCardStore(deps.DB, deps.Redis)
+	deviceStore := postgres.NewDeviceStore(deps.DB, deps.Redis)
+	assetWalletTransactionStore := postgres.NewAssetWalletTransactionStore(deps.DB, deps.Redis)
+	assetRechargeStore := postgres.NewAssetRechargeStore(deps.DB, deps.Redis)
+	personalCustomerOpenIDStore := postgres.NewPersonalCustomerOpenIDStore(deps.DB)
+	orderStore := postgres.NewOrderStore(deps.DB, deps.Redis)
+	packageSeriesStore := postgres.NewPackageSeriesStore(deps.DB)
+	shopSeriesAllocationStore := postgres.NewShopSeriesAllocationStore(deps.DB)
+	deviceSimBindingStore := postgres.NewDeviceSimBindingStore(deps.DB, deps.Redis)
+	carrierStore := postgres.NewCarrierStore(deps.DB)
+	clientOrderService := clientOrderSvc.New(
+		svc.Asset,
+		svc.PurchaseValidation,
+		orderStore,
+		assetRechargeStore,
+		assetWalletStore,
+		personalCustomerDeviceStore,
+		personalCustomerOpenIDStore,
+		svc.WechatConfig,
+		packageSeriesStore,
+		shopSeriesAllocationStore,
+		deps.Redis,
+		deps.Logger,
+	)
 
 	return &Handlers{
 		Auth:                        authHandler.NewHandler(svc.Auth, validate),
@@ -18,17 +47,22 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		Role:                        admin.NewRoleHandler(svc.Role, validate),
 		Permission:                  admin.NewPermissionHandler(svc.Permission),
 		PersonalCustomer:            app.NewPersonalCustomerHandler(svc.PersonalCustomer, deps.Logger),
+		ClientAuth:                  app.NewClientAuthHandler(svc.ClientAuth, deps.Logger),
+		ClientAsset:                 app.NewClientAssetHandler(svc.Asset, personalCustomerDeviceStore, assetWalletStore, packageStore, shopPackageAllocationStore, iotCardStore, deviceStore, deps.DB, deps.Logger),
+		ClientWallet:                app.NewClientWalletHandler(svc.Asset, personalCustomerDeviceStore, assetWalletStore, assetWalletTransactionStore, assetRechargeStore, svc.Recharge, personalCustomerOpenIDStore, svc.WechatConfig, deps.Redis, deps.Logger, deps.DB, iotCardStore, deviceStore),
+		ClientOrder:                 app.NewClientOrderHandler(clientOrderService, svc.Asset, orderStore, personalCustomerDeviceStore, iotCardStore, deviceStore, deps.Logger, deps.DB),
+		ClientExchange:              app.NewClientExchangeHandler(svc.Exchange),
+		ClientRealname:              app.NewClientRealnameHandler(svc.Asset, personalCustomerDeviceStore, iotCardStore, deviceSimBindingStore, carrierStore, deps.GatewayClient, deps.Logger),
+		ClientDevice:                app.NewClientDeviceHandler(svc.Asset, personalCustomerDeviceStore, deviceStore, deviceSimBindingStore, iotCardStore, deps.GatewayClient, deps.Logger),
 		Shop:                        admin.NewShopHandler(svc.Shop),
 		ShopRole:                    admin.NewShopRoleHandler(svc.Shop),
 		AdminAuth:                   admin.NewAuthHandler(svc.Auth, validate),
-		H5Auth:                      h5.NewAuthHandler(svc.Auth, validate),
 		ShopCommission:              admin.NewShopCommissionHandler(svc.ShopCommission),
 		CommissionWithdrawal:        admin.NewCommissionWithdrawalHandler(svc.CommissionWithdrawal),
 		CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(svc.CommissionWithdrawalSetting),
 		Enterprise:                  admin.NewEnterpriseHandler(svc.Enterprise),
 		EnterpriseCard:              admin.NewEnterpriseCardHandler(svc.EnterpriseCard),
 		EnterpriseDevice:            admin.NewEnterpriseDeviceHandler(svc.EnterpriseDevice),
-		EnterpriseDeviceH5:          h5.NewEnterpriseDeviceHandler(svc.EnterpriseDevice),
 		Authorization:               admin.NewAuthorizationHandler(svc.Authorization),
 		MyCommission:                admin.NewMyCommissionHandler(svc.MyCommission),
 		IotCard:                     admin.NewIotCardHandler(svc.IotCard),
@@ -41,13 +75,11 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		PackageSeries:               admin.NewPackageSeriesHandler(svc.PackageSeries),
 		Package:                     admin.NewPackageHandler(svc.Package),
 		PackageUsage:                admin.NewPackageUsageHandler(svc.PackageDailyRecord),
-		H5PackageUsage:              h5.NewPackageUsageHandler(deps.DB, svc.PackageCustomerView),
 		ShopPackageBatchAllocation:  admin.NewShopPackageBatchAllocationHandler(svc.ShopPackageBatchAllocation),
 		ShopPackageBatchPricing:     admin.NewShopPackageBatchPricingHandler(svc.ShopPackageBatchPricing),
 		ShopSeriesGrant:             admin.NewShopSeriesGrantHandler(svc.ShopSeriesGrant),
 		AdminOrder:                  admin.NewOrderHandler(svc.Order, validate),
-		H5Order:                     h5.NewOrderHandler(svc.Order),
-		H5Recharge:                  h5.NewRechargeHandler(svc.Recharge),
+		AdminExchange:               admin.NewExchangeHandler(svc.Exchange, validate),
 		PaymentCallback:             callback.NewPaymentHandler(svc.Order, svc.Recharge, svc.AgentRecharge, deps.WechatPayment),
 		PollingConfig:               admin.NewPollingConfigHandler(svc.PollingConfig),
 		PollingConcurrency:          admin.NewPollingConcurrencyHandler(svc.PollingConcurrency),
@@ -56,6 +88,7 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		PollingCleanup:              admin.NewPollingCleanupHandler(svc.PollingCleanup),
 		PollingManualTrigger:        admin.NewPollingManualTriggerHandler(svc.PollingManualTrigger),
 		Asset:                       admin.NewAssetHandler(svc.Asset, svc.Device, svc.StopResumeService),
+		AssetLifecycle:              admin.NewAssetLifecycleHandler(svc.AssetLifecycle),
 		AssetWallet:                 admin.NewAssetWalletHandler(svc.AssetWallet),
 		WechatConfig:                admin.NewWechatConfigHandler(svc.WechatConfig),
 		AgentRecharge:               admin.NewAgentRechargeHandler(svc.AgentRecharge),

internal/bootstrap/middlewares.go

@@ -22,7 +22,7 @@ func initMiddlewares(deps *Dependencies, stores *stores) *Middlewares {
 	jwtManager := pkgauth.NewJWTManager(cfg.JWT.SecretKey, cfg.JWT.TokenDuration)
 
 	// 创建个人客户认证中间件
-	personalAuthMiddleware := middleware.NewPersonalAuthMiddleware(jwtManager, deps.Logger)
+	personalAuthMiddleware := middleware.NewPersonalAuthMiddleware(jwtManager, deps.Redis, deps.Logger)
 
 	// 创建 Token Manager（用于后台和H5认证）
 	accessTTL := time.Duration(cfg.JWT.AccessTokenTTL) * time.Second
@@ -32,13 +32,9 @@ func initMiddlewares(deps *Dependencies, stores *stores) *Middlewares {
 	// 创建后台认证中间件（传入 ShopStore 以支持预计算下级店铺 ID）
 	adminAuthMiddleware := createAdminAuthMiddleware(tokenManager, stores.Shop)
 
-	// 创建H5认证中间件（传入 ShopStore 以支持预计算下级店铺 ID）
-	h5AuthMiddleware := createH5AuthMiddleware(tokenManager, stores.Shop)
-
 	return &Middlewares{
 		PersonalAuth: personalAuthMiddleware,
 		AdminAuth:    adminAuthMiddleware,
-		H5Auth:       h5AuthMiddleware,
 	}
 }
 
@@ -68,29 +64,3 @@ func createAdminAuthMiddleware(tokenManager *pkgauth.TokenManager, shopStore pkg
 		ShopStore: shopStore,
 	})
 }
-
-func createH5AuthMiddleware(tokenManager *pkgauth.TokenManager, shopStore pkgmiddleware.AuthShopStoreInterface) fiber.Handler {
-	return pkgmiddleware.Auth(pkgmiddleware.AuthConfig{
-		TokenValidator: func(token string) (*pkgmiddleware.UserContextInfo, error) {
-			tokenInfo, err := tokenManager.ValidateAccessToken(context.Background(), token)
-			if err != nil {
-				return nil, errors.New(errors.CodeInvalidToken, "认证令牌无效或已过期")
-			}
-
-			// 检查用户类型：H5 允许 Agent(3), Enterprise(4)
-			if tokenInfo.UserType != constants.UserTypeAgent &&
-				tokenInfo.UserType != constants.UserTypeEnterprise {
-				return nil, errors.New(errors.CodeForbidden, "权限不足")
-			}
-
-			return &pkgmiddleware.UserContextInfo{
-				UserID:       tokenInfo.UserID,
-				UserType:     tokenInfo.UserType,
-				ShopID:       tokenInfo.ShopID,
-				EnterpriseID: tokenInfo.EnterpriseID,
-			}, nil
-		},
-		SkipPaths: []string{"/api/h5/login", "/api/h5/refresh-token"},
-		ShopStore: shopStore,
-	})
-}

internal/bootstrap/services.go

@@ -7,6 +7,7 @@ import (
 	assetAllocationRecordSvc "github.com/break/junhong_cmp_fiber/internal/service/asset_allocation_record"
 	authSvc "github.com/break/junhong_cmp_fiber/internal/service/auth"
 	carrierSvc "github.com/break/junhong_cmp_fiber/internal/service/carrier"
+	clientAuthSvc "github.com/break/junhong_cmp_fiber/internal/service/client_auth"
 	commissionCalculationSvc "github.com/break/junhong_cmp_fiber/internal/service/commission_calculation"
 	commissionStatsSvc "github.com/break/junhong_cmp_fiber/internal/service/commission_stats"
 	commissionWithdrawalSvc "github.com/break/junhong_cmp_fiber/internal/service/commission_withdrawal"
@@ -19,6 +20,7 @@ import (
 	enterpriseSvc "github.com/break/junhong_cmp_fiber/internal/service/enterprise"
 	enterpriseCardSvc "github.com/break/junhong_cmp_fiber/internal/service/enterprise_card"
 	enterpriseDeviceSvc "github.com/break/junhong_cmp_fiber/internal/service/enterprise_device"
+	exchangeSvc "github.com/break/junhong_cmp_fiber/internal/service/exchange"
 	iotCardSvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
 	iotCardImportSvc "github.com/break/junhong_cmp_fiber/internal/service/iot_card_import"
 	myCommissionSvc "github.com/break/junhong_cmp_fiber/internal/service/my_commission"
@@ -47,6 +49,7 @@ type services struct {
 	Role                        *roleSvc.Service
 	Permission                  *permissionSvc.Service
 	PersonalCustomer            *personalCustomerSvc.Service
+	ClientAuth                  *clientAuthSvc.Service
 	Shop                        *shopSvc.Service
 	Auth                        *authSvc.Service
 	ShopCommission              *shopCommissionSvc.Service
@@ -74,6 +77,7 @@ type services struct {
 	CommissionStats             *commissionStatsSvc.Service
 	PurchaseValidation          *purchaseValidationSvc.Service
 	Order                       *orderSvc.Service
+	Exchange                    *exchangeSvc.Service
 	Recharge                    *rechargeSvc.Service
 	PollingConfig               *pollingSvc.ConfigService
 	PollingConcurrency          *pollingSvc.ConcurrencyService
@@ -82,6 +86,7 @@ type services struct {
 	PollingCleanup              *pollingSvc.CleanupService
 	PollingManualTrigger        *pollingSvc.ManualTriggerService
 	Asset                       *assetSvc.Service
+	AssetLifecycle              *assetSvc.LifecycleService
 	AssetWallet                 *assetWalletSvc.Service
 	StopResumeService           *iotCardSvc.StopResumeService
 	WechatConfig                *wechatConfigSvc.Service
@@ -105,8 +110,22 @@ func initServices(s *stores, deps *Dependencies) *services {
 		AccountAudit:     accountAudit,
 		Role:             roleSvc.New(s.Role, s.Permission, s.RolePermission),
 		Permission:       permissionSvc.New(s.Permission, s.AccountRole, s.RolePermission, account, deps.Redis),
-		PersonalCustomer:            personalCustomerSvc.NewService(s.PersonalCustomer, s.PersonalCustomerPhone, deps.VerificationService, deps.JWTManager, deps.WechatOfficialAccount, deps.Logger),
-		Shop:                        shopSvc.New(s.Shop, s.Account, s.ShopRole, s.Role, s.AccountRole),
+		PersonalCustomer: personalCustomerSvc.NewService(s.PersonalCustomer, s.PersonalCustomerPhone, deps.Logger),
+		ClientAuth: clientAuthSvc.New(
+			deps.DB,
+			s.PersonalCustomerOpenID,
+			s.PersonalCustomer,
+			s.PersonalCustomerDevice,
+			s.PersonalCustomerPhone,
+			s.IotCard,
+			s.Device,
+			wechatConfig,
+			deps.VerificationService,
+			deps.JWTManager,
+			deps.Redis,
+			deps.Logger,
+		),
+		Shop:                        shopSvc.New(s.Shop, s.Account, s.ShopRole, s.Role, s.AccountRole, s.AgentWallet),
 		Auth:                        authSvc.New(s.Account, s.AccountRole, s.RolePermission, s.Permission, s.Shop, deps.TokenManager, deps.Logger),
 		ShopCommission:              shopCommissionSvc.New(s.Shop, s.Account, s.AgentWallet, s.CommissionWithdrawalRequest, s.CommissionRecord),
 		CommissionWithdrawal:        commissionWithdrawalSvc.New(deps.DB, s.Shop, s.Account, s.AgentWallet, s.AgentWalletTransaction, s.CommissionWithdrawalRequest),
@@ -150,6 +169,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 		CommissionStats:            commissionStatsSvc.New(s.ShopSeriesCommissionStats),
 		PurchaseValidation:         purchaseValidation,
 		Order:                      orderSvc.New(deps.DB, deps.Redis, s.Order, s.OrderItem, s.AgentWallet, s.AssetWallet, purchaseValidation, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.IotCard, s.Device, s.PackageSeries, s.PackageUsage, s.Package, wechatConfig, deps.WechatPayment, deps.QueueClient, deps.Logger),
+		Exchange:                   exchangeSvc.New(deps.DB, s.ExchangeOrder, s.IotCard, s.Device, s.AssetWallet, s.AssetWalletTransaction, s.PackageUsage, s.PackageUsageDailyRecord, s.ResourceTag, s.PersonalCustomerDevice, deps.Logger),
 		Recharge:                   rechargeSvc.New(deps.DB, s.AssetRecharge, s.AssetWallet, s.AssetWalletTransaction, s.IotCard, s.Device, s.ShopSeriesAllocation, s.PackageSeries, s.CommissionRecord, wechatConfig, deps.Logger),
 		PollingConfig:              pollingSvc.NewConfigService(s.PollingConfig),
 		PollingConcurrency:         pollingSvc.NewConcurrencyService(s.PollingConcurrencyConfig, deps.Redis),
@@ -158,6 +178,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 		PollingCleanup:             pollingSvc.NewCleanupService(s.DataCleanupConfig, s.DataCleanupLog, deps.Logger),
 		PollingManualTrigger:       pollingSvc.NewManualTriggerService(s.PollingManualTriggerLog, s.IotCard, deps.Redis, deps.Logger),
 		Asset:                      assetSvc.New(deps.DB, s.Device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.DeviceSimBinding, s.Shop, deps.Redis, iotCard),
+		AssetLifecycle:             assetSvc.NewLifecycleService(deps.DB, s.IotCard, s.Device),
 		AssetWallet:                assetWalletSvc.New(s.AssetWallet, s.AssetWalletTransaction),
 		StopResumeService:          iotCardSvc.NewStopResumeService(deps.DB, deps.Redis, s.IotCard, s.DeviceSimBinding, deps.GatewayClient, deps.Logger),
 		WechatConfig:               wechatConfig,

internal/bootstrap/stores.go

@@ -14,6 +14,8 @@ type stores struct {
 	ShopRole                          *postgres.ShopRoleStore
 	RolePermission                    *postgres.RolePermissionStore
 	PersonalCustomer                  *postgres.PersonalCustomerStore
+	PersonalCustomerOpenID            *postgres.PersonalCustomerOpenIDStore
+	PersonalCustomerDevice            *postgres.PersonalCustomerDeviceStore
 	PersonalCustomerPhone             *postgres.PersonalCustomerPhoneStore
 	CommissionWithdrawalRequest       *postgres.CommissionWithdrawalRequestStore
 	CommissionRecord                  *postgres.CommissionRecordStore
@@ -38,6 +40,8 @@ type stores struct {
 	ShopSeriesCommissionStats         *postgres.ShopSeriesCommissionStatsStore
 	Order                             *postgres.OrderStore
 	OrderItem                         *postgres.OrderItemStore
+	ExchangeOrder                     *postgres.ExchangeOrderStore
+	ResourceTag                       *postgres.ResourceTagStore
 	PollingConfig                     *postgres.PollingConfigStore
 	PollingConcurrencyConfig          *postgres.PollingConcurrencyConfigStore
 	PollingAlertRule                  *postgres.PollingAlertRuleStore
@@ -68,6 +72,8 @@ func initStores(deps *Dependencies) *stores {
 		ShopRole:                          postgres.NewShopRoleStore(deps.DB, deps.Redis),
 		RolePermission:                    postgres.NewRolePermissionStore(deps.DB, deps.Redis),
 		PersonalCustomer:                  postgres.NewPersonalCustomerStore(deps.DB, deps.Redis),
+		PersonalCustomerOpenID:            postgres.NewPersonalCustomerOpenIDStore(deps.DB),
+		PersonalCustomerDevice:            postgres.NewPersonalCustomerDeviceStore(deps.DB),
 		PersonalCustomerPhone:             postgres.NewPersonalCustomerPhoneStore(deps.DB),
 		CommissionWithdrawalRequest:       postgres.NewCommissionWithdrawalRequestStore(deps.DB, deps.Redis),
 		CommissionRecord:                  postgres.NewCommissionRecordStore(deps.DB, deps.Redis),
@@ -92,6 +98,8 @@ func initStores(deps *Dependencies) *stores {
 		ShopSeriesCommissionStats:         postgres.NewShopSeriesCommissionStatsStore(deps.DB),
 		Order:                             postgres.NewOrderStore(deps.DB, deps.Redis),
 		OrderItem:                         postgres.NewOrderItemStore(deps.DB, deps.Redis),
+		ExchangeOrder:                     postgres.NewExchangeOrderStore(deps.DB),
+		ResourceTag:                       postgres.NewResourceTagStore(deps.DB),
 		PollingConfig:                     postgres.NewPollingConfigStore(deps.DB),
 		PollingConcurrencyConfig:          postgres.NewPollingConcurrencyConfigStore(deps.DB),
 		PollingAlertRule:                  postgres.NewPollingAlertRuleStore(deps.DB),

internal/bootstrap/types.go

@@ -5,7 +5,6 @@ import (
 	"github.com/break/junhong_cmp_fiber/internal/handler/app"
 	authHandler "github.com/break/junhong_cmp_fiber/internal/handler/auth"
 	"github.com/break/junhong_cmp_fiber/internal/handler/callback"
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
 	"github.com/break/junhong_cmp_fiber/internal/middleware"
 	"github.com/gofiber/fiber/v2"
 )
@@ -16,17 +15,22 @@ type Handlers struct {
 	Role                        *admin.RoleHandler
 	Permission                  *admin.PermissionHandler
 	PersonalCustomer            *app.PersonalCustomerHandler
+	ClientAuth                  *app.ClientAuthHandler
+	ClientAsset                 *app.ClientAssetHandler
+	ClientWallet                *app.ClientWalletHandler
+	ClientOrder                 *app.ClientOrderHandler
+	ClientExchange              *app.ClientExchangeHandler
+	ClientRealname              *app.ClientRealnameHandler
+	ClientDevice                *app.ClientDeviceHandler
 	Shop                        *admin.ShopHandler
 	ShopRole                    *admin.ShopRoleHandler
 	AdminAuth                   *admin.AuthHandler
-	H5Auth                      *h5.AuthHandler
 	ShopCommission              *admin.ShopCommissionHandler
 	CommissionWithdrawal        *admin.CommissionWithdrawalHandler
 	CommissionWithdrawalSetting *admin.CommissionWithdrawalSettingHandler
 	Enterprise                  *admin.EnterpriseHandler
 	EnterpriseCard              *admin.EnterpriseCardHandler
 	EnterpriseDevice            *admin.EnterpriseDeviceHandler
-	EnterpriseDeviceH5          *h5.EnterpriseDeviceHandler
 	Authorization               *admin.AuthorizationHandler
 	MyCommission                *admin.MyCommissionHandler
 	IotCard                     *admin.IotCardHandler
@@ -39,13 +43,11 @@ type Handlers struct {
 	PackageSeries               *admin.PackageSeriesHandler
 	Package                     *admin.PackageHandler
 	PackageUsage                *admin.PackageUsageHandler
-	H5PackageUsage              *h5.PackageUsageHandler
 	ShopPackageBatchAllocation  *admin.ShopPackageBatchAllocationHandler
 	ShopPackageBatchPricing     *admin.ShopPackageBatchPricingHandler
 	ShopSeriesGrant             *admin.ShopSeriesGrantHandler
 	AdminOrder                  *admin.OrderHandler
-	H5Order                     *h5.OrderHandler
-	H5Recharge                  *h5.RechargeHandler
+	AdminExchange               *admin.ExchangeHandler
 	PaymentCallback             *callback.PaymentHandler
 	PollingConfig               *admin.PollingConfigHandler
 	PollingConcurrency          *admin.PollingConcurrencyHandler
@@ -54,6 +56,7 @@ type Handlers struct {
 	PollingCleanup              *admin.PollingCleanupHandler
 	PollingManualTrigger        *admin.PollingManualTriggerHandler
 	Asset                       *admin.AssetHandler
+	AssetLifecycle              *admin.AssetLifecycleHandler
 	AssetWallet                 *admin.AssetWalletHandler
 	WechatConfig                *admin.WechatConfigHandler
 	AgentRecharge               *admin.AgentRechargeHandler
@@ -64,6 +67,5 @@ type Handlers struct {
 type Middlewares struct {
 	PersonalAuth *middleware.PersonalAuthMiddleware
 	AdminAuth    func(*fiber.Ctx) error
-	H5Auth       func(*fiber.Ctx) error
 	// TODO: 新增 Middleware 在此添加字段
 }

internal/handler/admin/asset_lifecycle.go

@@ -0,0 +1,59 @@
+package admin
+
+import (
+	"context"
+	"strconv"
+
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+// AssetLifecycleService 资产生命周期服务接口
+type AssetLifecycleService interface {
+	// DeactivateIotCard 停用 IoT 卡
+	DeactivateIotCard(ctx context.Context, id uint) error
+	// DeactivateDevice 停用设备
+	DeactivateDevice(ctx context.Context, id uint) error
+}
+
+// AssetLifecycleHandler 资产生命周期处理器
+type AssetLifecycleHandler struct {
+	service AssetLifecycleService
+}
+
+// NewAssetLifecycleHandler 创建资产生命周期处理器
+func NewAssetLifecycleHandler(service AssetLifecycleService) *AssetLifecycleHandler {
+	return &AssetLifecycleHandler{service: service}
+}
+
+// DeactivateIotCard 手动停用 IoT 卡
+// PATCH /api/admin/iot-cards/:id/deactivate
+func (h *AssetLifecycleHandler) DeactivateIotCard(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "无效的卡ID")
+	}
+
+	if err := h.service.DeactivateIotCard(c.UserContext(), uint(id)); err != nil {
+		return err
+	}
+
+	return response.Success(c, nil)
+}
+
+// DeactivateDevice 手动停用设备
+// PATCH /api/admin/devices/:id/deactivate
+func (h *AssetLifecycleHandler) DeactivateDevice(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "无效的设备ID")
+	}
+
+	if err := h.service.DeactivateDevice(c.UserContext(), uint(id)); err != nil {
+		return err
+	}
+
+	return response.Success(c, nil)
+}

internal/handler/admin/exchange.go

@@ -0,0 +1,131 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	exchangeService "github.com/break/junhong_cmp_fiber/internal/service/exchange"
+	"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"
+)
+
+type ExchangeHandler struct {
+	service   *exchangeService.Service
+	validator *validator.Validate
+}
+
+func NewExchangeHandler(service *exchangeService.Service, validator *validator.Validate) *ExchangeHandler {
+	return &ExchangeHandler{service: service, validator: validator}
+}
+
+func (h *ExchangeHandler) Create(c *fiber.Ctx) error {
+	var req dto.CreateExchangeRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	data, err := h.service.Create(c.UserContext(), &req)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, data)
+}
+
+func (h *ExchangeHandler) List(c *fiber.Ctx) error {
+	var req dto.ExchangeListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	data, err := h.service.List(c.UserContext(), &req)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, data)
+}
+
+func (h *ExchangeHandler) Get(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的换货单ID")
+	}
+
+	data, err := h.service.Get(c.UserContext(), uint(id))
+	if err != nil {
+		return err
+	}
+	return response.Success(c, data)
+}
+
+func (h *ExchangeHandler) Ship(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的换货单ID")
+	}
+
+	var req dto.ExchangeShipRequest
+	if err = c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err = h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	data, err := h.service.Ship(c.UserContext(), uint(id), &req)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, data)
+}
+
+func (h *ExchangeHandler) Complete(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的换货单ID")
+	}
+
+	if err = h.service.Complete(c.UserContext(), uint(id)); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}
+
+func (h *ExchangeHandler) Cancel(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的换货单ID")
+	}
+
+	var req dto.ExchangeCancelRequest
+	if err = c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err = h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if err = h.service.Cancel(c.UserContext(), uint(id), &req); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}
+
+func (h *ExchangeHandler) Renew(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的换货单ID")
+	}
+
+	if err = h.service.Renew(c.UserContext(), uint(id)); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}

internal/handler/admin/package.go

@@ -128,3 +128,21 @@ func (h *PackageHandler) UpdateShelfStatus(c *fiber.Ctx) error {
 
 	return response.Success(c, nil)
 }
+
+func (h *PackageHandler) UpdateRetailPrice(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam, "无效的套餐 ID")
+	}
+
+	var req dto.UpdateRetailPriceRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+
+	if err := h.service.UpdateRetailPrice(c.UserContext(), uint(id), req.RetailPrice); err != nil {
+		return err
+	}
+
+	return response.Success(c, nil)
+}

internal/handler/app/client_asset.go

@@ -0,0 +1,635 @@
+package app
+
+import (
+	"context"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	"github.com/break/junhong_cmp_fiber/internal/store"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"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"
+	"gorm.io/gorm"
+)
+
+// ClientAssetHandler C 端资产信息处理器
+// 提供 B1~B4 资产信息、可购套餐、套餐历史、手动刷新接口
+type ClientAssetHandler struct {
+	assetService               *asset.Service
+	personalDeviceStore        *postgres.PersonalCustomerDeviceStore
+	assetWalletStore           *postgres.AssetWalletStore
+	packageStore               *postgres.PackageStore
+	shopPackageAllocationStore *postgres.ShopPackageAllocationStore
+	iotCardStore               *postgres.IotCardStore
+	deviceStore                *postgres.DeviceStore
+	db                         *gorm.DB
+	logger                     *zap.Logger
+}
+
+// NewClientAssetHandler 创建 C 端资产信息处理器
+func NewClientAssetHandler(
+	assetService *asset.Service,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	assetWalletStore *postgres.AssetWalletStore,
+	packageStore *postgres.PackageStore,
+	shopPackageAllocationStore *postgres.ShopPackageAllocationStore,
+	iotCardStore *postgres.IotCardStore,
+	deviceStore *postgres.DeviceStore,
+	db *gorm.DB,
+	logger *zap.Logger,
+) *ClientAssetHandler {
+	return &ClientAssetHandler{
+		assetService:               assetService,
+		personalDeviceStore:        personalDeviceStore,
+		assetWalletStore:           assetWalletStore,
+		packageStore:               packageStore,
+		shopPackageAllocationStore: shopPackageAllocationStore,
+		iotCardStore:               iotCardStore,
+		deviceStore:                deviceStore,
+		db:                         db,
+		logger:                     logger,
+	}
+}
+
+type resolvedAssetContext struct {
+	CustomerID         uint
+	Identifier         string
+	Asset              *dto.AssetResolveResponse
+	Generation         int
+	WalletBalance      int64
+	SkipPermissionCtx  context.Context
+	IsAgentChannel     bool
+	SellerShopID       uint
+	MainPackageActived bool
+}
+
+// resolveAssetFromIdentifier 统一执行资产解析与归属校验
+// 处理流程：客户鉴权 -> 标识符解析 -> 资产解析 -> 归属校验 -> 世代与钱包信息补齐
+func (h *ClientAssetHandler) resolveAssetFromIdentifier(c *fiber.Ctx, identifier string) (*resolvedAssetContext, error) {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+
+	identifier = strings.TrimSpace(identifier)
+	if identifier == "" {
+		identifier = strings.TrimSpace(c.Query("identifier"))
+	}
+	if identifier == "" {
+		var req dto.AssetRefreshRequest
+		if err := c.BodyParser(&req); err == nil {
+			identifier = strings.TrimSpace(req.Identifier)
+		}
+	}
+	if identifier == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	skipPermissionCtx := context.WithValue(c.UserContext(), constants.ContextKeySubordinateShopIDs, []uint{})
+	assetInfo, err := h.assetService.Resolve(skipPermissionCtx, identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	owned, ownErr := h.isCustomerOwnAsset(skipPermissionCtx, customerID, assetInfo.VirtualNo)
+	if ownErr != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, ownErr, "查询资产归属失败")
+	}
+	if !owned {
+		return nil, errors.New(errors.CodeForbidden, "无权限操作该资产或资源不存在")
+	}
+
+	generation, genErr := h.getAssetGeneration(skipPermissionCtx, assetInfo.AssetType, assetInfo.AssetID)
+	if genErr != nil {
+		return nil, genErr
+	}
+
+	walletBalance, walletErr := h.getAssetWalletBalance(skipPermissionCtx, assetInfo.AssetType, assetInfo.AssetID)
+	if walletErr != nil {
+		return nil, walletErr
+	}
+
+	ctxInfo := &resolvedAssetContext{
+		CustomerID:        customerID,
+		Identifier:        identifier,
+		Asset:             assetInfo,
+		Generation:        generation,
+		WalletBalance:     walletBalance,
+		SkipPermissionCtx: skipPermissionCtx,
+	}
+
+	if assetInfo.ShopID != nil && *assetInfo.ShopID > 0 {
+		ctxInfo.IsAgentChannel = true
+		ctxInfo.SellerShopID = *assetInfo.ShopID
+	}
+
+	return ctxInfo, nil
+}
+
+// GetAssetInfo B1 资产信息
+// GET /api/c/v1/asset/info
+func (h *ClientAssetHandler) GetAssetInfo(c *fiber.Ctx) error {
+	var req dto.AssetInfoRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	resp := &dto.AssetInfoResponse{
+		AssetType:           resolved.Asset.AssetType,
+		AssetID:             resolved.Asset.AssetID,
+		Identifier:          resolved.Identifier,
+		VirtualNo:           resolved.Asset.VirtualNo,
+		Status:              resolved.Asset.Status,
+		RealNameStatus:      resolved.Asset.RealNameStatus,
+		CarrierName:         resolved.Asset.CarrierName,
+		Generation:          strconv.Itoa(resolved.Generation),
+		WalletBalance:       resolved.WalletBalance,
+		ActivatedAt:         resolved.Asset.ActivatedAt,
+		CurrentPackage:      resolved.Asset.CurrentPackage,
+		PackageTotalMB:      resolved.Asset.PackageTotalMB,
+		PackageUsedMB:       resolved.Asset.PackageUsedMB,
+		PackageRemainMB:     resolved.Asset.PackageRemainMB,
+		DeviceName:          resolved.Asset.DeviceName,
+		IMEI:                resolved.Asset.IMEI,
+		SN:                  resolved.Asset.SN,
+		DeviceModel:         resolved.Asset.DeviceModel,
+		DeviceType:          resolved.Asset.DeviceType,
+		Manufacturer:        resolved.Asset.Manufacturer,
+		MaxSimSlots:         resolved.Asset.MaxSimSlots,
+		BoundCardCount:      resolved.Asset.BoundCardCount,
+		Cards:               resolved.Asset.Cards,
+		DeviceProtectStatus: resolved.Asset.DeviceProtectStatus,
+		ICCID:               resolved.Asset.ICCID,
+		MSISDN:              resolved.Asset.MSISDN,
+		CarrierID:           resolved.Asset.CarrierID,
+		CarrierType:         resolved.Asset.CarrierType,
+		NetworkStatus:       resolved.Asset.NetworkStatus,
+		ActivationStatus:    resolved.Asset.ActivationStatus,
+		CardCategory:        resolved.Asset.CardCategory,
+		BoundDeviceID:       resolved.Asset.BoundDeviceID,
+		BoundDeviceNo:       resolved.Asset.BoundDeviceNo,
+		BoundDeviceName:     resolved.Asset.BoundDeviceName,
+	}
+
+	// TODO: Gateway 同步接口对接后，替换为真实设备实时数据
+	if resp.AssetType == "device" {
+		resp.DeviceRealtime = buildMockDeviceRealtime()
+	}
+
+	return response.Success(c, resp)
+}
+
+// GetAvailablePackages B2 资产可购套餐列表
+// GET /api/c/v1/asset/packages
+func (h *ClientAssetHandler) GetAvailablePackages(c *fiber.Ctx) error {
+	var req dto.AssetPackageListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	if resolved.Asset.SeriesID == nil || *resolved.Asset.SeriesID == 0 {
+		return errors.New(errors.CodeNoAvailablePackage, "当前无可购买套餐")
+	}
+
+	allUsages, err := h.assetService.GetPackages(resolved.SkipPermissionCtx, resolved.Asset.AssetType, resolved.Asset.AssetID)
+	if err != nil {
+		return err
+	}
+	resolved.MainPackageActived = hasActiveMainPackage(allUsages)
+
+	listCtx := resolved.SkipPermissionCtx
+	if resolved.IsAgentChannel {
+		listCtx = context.WithValue(listCtx, constants.ContextKeyUserType, constants.UserTypeAgent)
+		listCtx = context.WithValue(listCtx, constants.ContextKeyShopID, resolved.SellerShopID)
+	}
+
+	pkgs, _, err := h.packageStore.List(listCtx, &store.QueryOptions{
+		Page:     1,
+		PageSize: constants.MaxPageSize,
+		OrderBy:  "id DESC",
+	}, map[string]any{
+		"series_id": *resolved.Asset.SeriesID,
+		"status":    constants.StatusEnabled,
+	})
+	if err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询可购套餐失败")
+	}
+
+	allocationMap := make(map[uint]*model.ShopPackageAllocation)
+	if resolved.IsAgentChannel {
+		packageIDs := collectPackageIDs(pkgs)
+		allocations, allocErr := h.shopPackageAllocationStore.GetByShopAndPackages(
+			resolved.SkipPermissionCtx,
+			resolved.SellerShopID,
+			packageIDs,
+		)
+		if allocErr != nil {
+			return errors.Wrap(errors.CodeDatabaseError, allocErr, "查询套餐分配记录失败")
+		}
+		for _, allocation := range allocations {
+			allocationMap[allocation.PackageID] = allocation
+		}
+	}
+
+	items := make([]dto.ClientPackageItem, 0, len(pkgs))
+	for _, pkg := range pkgs {
+		item, ok := buildClientPackageItem(pkg, resolved, allocationMap)
+		if !ok {
+			continue
+		}
+		items = append(items, item)
+	}
+
+	if len(items) == 0 {
+		return errors.New(errors.CodeNoAvailablePackage, "当前无可购买套餐")
+	}
+
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].RetailPrice < items[j].RetailPrice
+	})
+
+	return response.Success(c, &dto.AssetPackageListResponse{Packages: items})
+}
+
+// GetPackageHistory B3 资产套餐历史
+// GET /api/c/v1/asset/package-history
+func (h *ClientAssetHandler) GetPackageHistory(c *fiber.Ctx) error {
+	var req dto.AssetPackageHistoryRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if req.Page < 1 {
+		req.Page = 1
+	}
+	if req.PageSize < 1 {
+		req.PageSize = constants.DefaultPageSize
+	}
+	if req.PageSize > constants.MaxPageSize {
+		req.PageSize = constants.MaxPageSize
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	query := h.db.WithContext(resolved.SkipPermissionCtx).Model(&model.PackageUsage{}).
+		Where("generation = ?", resolved.Generation)
+	if resolved.Asset.AssetType == "card" {
+		query = query.Where("iot_card_id = ?", resolved.Asset.AssetID)
+	} else {
+		query = query.Where("device_id = ?", resolved.Asset.AssetID)
+	}
+	if req.Status != nil {
+		query = query.Where("status = ?", *req.Status)
+	}
+	if req.PackageType != nil {
+		query = query.Where("package_id IN (?)",
+			h.db.Model(&model.Package{}).Select("id").Where("package_type = ?", *req.PackageType))
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐历史总数失败")
+	}
+
+	var usages []*model.PackageUsage
+	offset := (req.Page - 1) * req.PageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(req.PageSize).Find(&usages).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐历史失败")
+	}
+
+	packageMap, err := h.loadPackageMap(resolved.SkipPermissionCtx, usages)
+	if err != nil {
+		return err
+	}
+
+	list := make([]dto.AssetPackageResponse, 0, len(usages))
+	for _, usage := range usages {
+		pkg := packageMap[usage.PackageID]
+		ratio := 1.0
+		pkgName := ""
+		pkgType := ""
+		if pkg != nil {
+			ratio = safeVirtualRatio(pkg.VirtualRatio)
+			pkgName = pkg.PackageName
+			pkgType = pkg.PackageType
+		}
+
+		list = append(list, dto.AssetPackageResponse{
+			PackageUsageID:  usage.ID,
+			PackageID:       usage.PackageID,
+			PackageName:     pkgName,
+			PackageType:     pkgType,
+			UsageType:       usage.UsageType,
+			Status:          usage.Status,
+			StatusName:      packageStatusName(usage.Status),
+			DataLimitMB:     usage.DataLimitMB,
+			VirtualLimitMB:  int64(float64(usage.DataLimitMB) / ratio),
+			DataUsageMB:     usage.DataUsageMB,
+			VirtualUsedMB:   float64(usage.DataUsageMB) / ratio,
+			VirtualRemainMB: float64(usage.DataLimitMB-usage.DataUsageMB) / ratio,
+			VirtualRatio:    ratio,
+			ActivatedAt:     nonZeroTimePtr(usage.ActivatedAt),
+			ExpiresAt:       nonZeroTimePtr(usage.ExpiresAt),
+			MasterUsageID:   usage.MasterUsageID,
+			Priority:        usage.Priority,
+			CreatedAt:       usage.CreatedAt,
+		})
+	}
+
+	return response.SuccessWithPagination(c, list, total, req.Page, req.PageSize)
+}
+
+// RefreshAsset B4 资产刷新
+// POST /api/c/v1/asset/refresh
+func (h *ClientAssetHandler) RefreshAsset(c *fiber.Ctx) error {
+	var req dto.AssetRefreshRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	if _, err := h.assetService.Refresh(
+		resolved.SkipPermissionCtx,
+		resolved.Asset.AssetType,
+		resolved.Asset.AssetID,
+	); err != nil {
+		return err
+	}
+
+	resp := &dto.AssetRefreshResponse{
+		RefreshType:     resolved.Asset.AssetType,
+		Accepted:        true,
+		CooldownSeconds: 0,
+	}
+	if resolved.Asset.AssetType == constants.ResourceTypeDevice {
+		resp.CooldownSeconds = int(constants.DeviceRefreshCooldownDuration / time.Second)
+	}
+
+	return response.Success(c, resp)
+}
+
+func (h *ClientAssetHandler) isCustomerOwnAsset(ctx context.Context, customerID uint, virtualNo string) (bool, error) {
+	records, err := h.personalDeviceStore.GetByCustomerID(ctx, customerID)
+	if err != nil {
+		return false, err
+	}
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		if record.Status == constants.StatusEnabled && record.VirtualNo == virtualNo {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func (h *ClientAssetHandler) getAssetGeneration(ctx context.Context, assetType string, assetID uint) (int, error) {
+	switch assetType {
+	case "card":
+		card, err := h.iotCardStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询卡信息失败")
+		}
+		return card.Generation, nil
+	case "device":
+		device, err := h.deviceStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询设备信息失败")
+		}
+		return device.Generation, nil
+	default:
+		return 0, errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func (h *ClientAssetHandler) getAssetWalletBalance(ctx context.Context, assetType string, assetID uint) (int64, error) {
+	resourceType := constants.AssetWalletResourceTypeIotCard
+	if assetType == constants.ResourceTypeDevice {
+		resourceType = constants.AssetWalletResourceTypeDevice
+	}
+
+	wallet, err := h.assetWalletStore.GetByResourceTypeAndID(ctx, resourceType, assetID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return 0, nil
+		}
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询资产钱包失败")
+	}
+
+	return wallet.Balance, nil
+}
+
+func (h *ClientAssetHandler) loadPackageMap(ctx context.Context, usages []*model.PackageUsage) (map[uint]*model.Package, error) {
+	ids := make([]uint, 0, len(usages))
+	seen := make(map[uint]struct{}, len(usages))
+	for _, usage := range usages {
+		if usage == nil {
+			continue
+		}
+		if _, ok := seen[usage.PackageID]; ok {
+			continue
+		}
+		seen[usage.PackageID] = struct{}{}
+		ids = append(ids, usage.PackageID)
+	}
+
+	packages, err := h.packageStore.GetByIDsUnscoped(ctx, ids)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐信息失败")
+	}
+
+	result := make(map[uint]*model.Package, len(packages))
+	for _, pkg := range packages {
+		result[pkg.ID] = pkg
+	}
+
+	return result, nil
+}
+
+func collectPackageIDs(pkgs []*model.Package) []uint {
+	ids := make([]uint, 0, len(pkgs))
+	for _, pkg := range pkgs {
+		if pkg == nil {
+			continue
+		}
+		ids = append(ids, pkg.ID)
+	}
+	return ids
+}
+
+func hasActiveMainPackage(usages []*dto.AssetPackageResponse) bool {
+	for _, usage := range usages {
+		if usage == nil {
+			continue
+		}
+		if usage.PackageType == constants.PackageTypeFormal && usage.Status == constants.PackageUsageStatusActive {
+			return true
+		}
+	}
+	return false
+}
+
+func buildClientPackageItem(
+	pkg *model.Package,
+	resolved *resolvedAssetContext,
+	allocationMap map[uint]*model.ShopPackageAllocation,
+) (dto.ClientPackageItem, bool) {
+	if pkg == nil || pkg.Status != constants.StatusEnabled {
+		return dto.ClientPackageItem{}, false
+	}
+
+	isAddon := pkg.PackageType == constants.PackageTypeAddon
+	if isAddon && !resolved.MainPackageActived {
+		return dto.ClientPackageItem{}, false
+	}
+
+	retailPrice := pkg.SuggestedRetailPrice
+	costPrice := pkg.CostPrice
+
+	if resolved.IsAgentChannel {
+		allocation, ok := allocationMap[pkg.ID]
+		if !ok || allocation == nil {
+			return dto.ClientPackageItem{}, false
+		}
+		if allocation.ShelfStatus != constants.ShelfStatusOn || allocation.Status != constants.StatusEnabled {
+			return dto.ClientPackageItem{}, false
+		}
+		retailPrice = allocation.RetailPrice
+		costPrice = allocation.CostPrice
+	} else if pkg.ShelfStatus != constants.ShelfStatusOn {
+		return dto.ClientPackageItem{}, false
+	}
+
+	if retailPrice < costPrice {
+		return dto.ClientPackageItem{}, false
+	}
+
+	validityDays := pkg.DurationDays
+	if validityDays <= 0 && pkg.DurationMonths > 0 {
+		validityDays = pkg.DurationMonths * 30
+	}
+
+	dataAllowance := pkg.VirtualDataMB
+	if dataAllowance <= 0 {
+		dataAllowance = pkg.RealDataMB
+	}
+
+	return dto.ClientPackageItem{
+		PackageID:     pkg.ID,
+		PackageName:   pkg.PackageName,
+		PackageType:   pkg.PackageType,
+		RetailPrice:   retailPrice,
+		CostPrice:     costPrice,
+		ValidityDays:  validityDays,
+		IsAddon:       isAddon,
+		DataAllowance: dataAllowance,
+		DataUnit:      "MB",
+		Description:   pkg.PackageCode,
+	}, true
+}
+
+func nonZeroTimePtr(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
+
+func safeVirtualRatio(ratio float64) float64 {
+	if ratio <= 0 {
+		return 1.0
+	}
+	return ratio
+}
+
+func packageStatusName(status int) string {
+	switch status {
+	case constants.PackageUsageStatusPending:
+		return "待生效"
+	case constants.PackageUsageStatusActive:
+		return "生效中"
+	case constants.PackageUsageStatusDepleted:
+		return "已用完"
+	case constants.PackageUsageStatusExpired:
+		return "已过期"
+	case constants.PackageUsageStatusInvalidated:
+		return "已失效"
+	default:
+		return "未知"
+	}
+}
+
+// buildMockDeviceRealtime 构建设备实时状态假数据
+// TODO: Gateway 同步接口对接后移除此函数，改为调用 Gateway 接口获取真实数据
+func buildMockDeviceRealtime() *dto.DeviceRealtimeInfo {
+	onlineStatus := int64(1)
+	batteryLevel := int64(85)
+	deviceStatus := int64(1)
+	runTime := "3600"
+	connectTime := "3500"
+	rsrp := int64(-80)
+	rsrq := int64(-10)
+	rssi := "-65"
+	sinr := int64(15)
+	ssid := "JunHong-WiFi"
+	wifiEnabled := true
+	wifiPassword := "12345678"
+	ipAddress := "192.168.1.1"
+	lanIP := "192.168.1.1"
+	dailyUsage := "0"
+	maxClients := int64(32)
+	switchMode := 0
+
+	return &dto.DeviceRealtimeInfo{
+		OnlineStatus: &onlineStatus,
+		BatteryLevel: &batteryLevel,
+		Status:       &deviceStatus,
+		RunTime:      &runTime,
+		ConnectTime:  &connectTime,
+		Rsrp:         &rsrp,
+		Rsrq:         &rsrq,
+		Rssi:         &rssi,
+		Sinr:         &sinr,
+		SSID:         &ssid,
+		WifiEnabled:  &wifiEnabled,
+		WifiPassword: &wifiPassword,
+		IPAddress:    &ipAddress,
+		LANIP:        &lanIP,
+		DailyUsage:   &dailyUsage,
+		MaxClients:   &maxClients,
+		SwitchMode:   &switchMode,
+	}
+}

internal/handler/app/client_auth.go

@@ -0,0 +1,165 @@
+package app
+
+import (
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	clientAuthSvc "github.com/break/junhong_cmp_fiber/internal/service/client_auth"
+	"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/go-playground/validator/v10"
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
+)
+
+var clientAuthValidator = validator.New()
+
+// ClientAuthHandler C 端认证处理器
+type ClientAuthHandler struct {
+	service *clientAuthSvc.Service
+	logger  *zap.Logger
+}
+
+// NewClientAuthHandler 创建 C 端认证处理器
+func NewClientAuthHandler(service *clientAuthSvc.Service, logger *zap.Logger) *ClientAuthHandler {
+	return &ClientAuthHandler{service: service, logger: logger}
+}
+
+// VerifyAsset A1 资产验证
+// POST /api/c/v1/auth/verify-asset
+func (h *ClientAuthHandler) VerifyAsset(c *fiber.Ctx) error {
+	var req dto.VerifyAssetRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("资产验证参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.VerifyAsset(c.UserContext(), &req, c.IP())
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// WechatLogin A2 公众号登录
+// POST /api/c/v1/auth/wechat-login
+func (h *ClientAuthHandler) WechatLogin(c *fiber.Ctx) error {
+	var req dto.WechatLoginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("公众号登录参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.WechatLogin(c.UserContext(), &req, c.IP())
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// MiniappLogin A3 小程序登录
+// POST /api/c/v1/auth/miniapp-login
+func (h *ClientAuthHandler) MiniappLogin(c *fiber.Ctx) error {
+	var req dto.MiniappLoginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("小程序登录参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.MiniappLogin(c.UserContext(), &req, c.IP())
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// SendCode A4 发送验证码
+// POST /api/c/v1/auth/send-code
+func (h *ClientAuthHandler) SendCode(c *fiber.Ctx) error {
+	var req dto.ClientSendCodeRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("发送验证码参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.SendCode(c.UserContext(), &req, c.IP())
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// BindPhone A5 绑定手机号
+// POST /api/c/v1/auth/bind-phone
+func (h *ClientAuthHandler) BindPhone(c *fiber.Ctx) error {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	var req dto.BindPhoneRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("绑定手机号参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.BindPhone(c.UserContext(), customerID, &req)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// ChangePhone A6 更换手机号
+// POST /api/c/v1/auth/change-phone
+func (h *ClientAuthHandler) ChangePhone(c *fiber.Ctx) error {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	var req dto.ChangePhoneRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientAuthValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("更换手机号参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resp, err := h.service.ChangePhone(c.UserContext(), customerID, &req)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}
+
+// Logout A7 退出登录
+// POST /api/c/v1/auth/logout
+func (h *ClientAuthHandler) Logout(c *fiber.Ctx) error {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	resp, err := h.service.Logout(c.UserContext(), customerID)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, resp)
+}

internal/handler/app/client_device.go

@@ -0,0 +1,317 @@
+package app
+
+import (
+	"github.com/break/junhong_cmp_fiber/internal/gateway"
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	assetSvc "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"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/go-playground/validator/v10"
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
+)
+
+var clientDeviceValidator = validator.New()
+
+// deviceAssetInfo validateDeviceAsset 解析后的设备资产信息
+type deviceAssetInfo struct {
+	DeviceID  uint   // 设备数据库 ID
+	IMEI      string // 设备 IMEI（用于 Gateway API 调用）
+	VirtualNo string // 设备虚拟号（用于所有权校验）
+}
+
+// ClientDeviceHandler C 端设备能力处理器
+// 提供设备卡列表、重启、恢复出厂、WiFi 配置、切卡等操作
+type ClientDeviceHandler struct {
+	assetService          *assetSvc.Service
+	personalDeviceStore   *postgres.PersonalCustomerDeviceStore
+	deviceStore           *postgres.DeviceStore
+	deviceSimBindingStore *postgres.DeviceSimBindingStore
+	iotCardStore          *postgres.IotCardStore
+	gatewayClient         *gateway.Client
+	logger                *zap.Logger
+}
+
+// NewClientDeviceHandler 创建 C 端设备能力处理器
+func NewClientDeviceHandler(
+	assetService *assetSvc.Service,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	deviceStore *postgres.DeviceStore,
+	deviceSimBindingStore *postgres.DeviceSimBindingStore,
+	iotCardStore *postgres.IotCardStore,
+	gatewayClient *gateway.Client,
+	logger *zap.Logger,
+) *ClientDeviceHandler {
+	return &ClientDeviceHandler{
+		assetService:          assetService,
+		personalDeviceStore:   personalDeviceStore,
+		deviceStore:           deviceStore,
+		deviceSimBindingStore: deviceSimBindingStore,
+		iotCardStore:          iotCardStore,
+		gatewayClient:         gatewayClient,
+		logger:                logger,
+	}
+}
+
+// validateDeviceAsset 校验设备资产的所有权和有效性
+// 流程：认证 → 资产解析 → 类型校验（仅设备）→ 所有权校验 → IMEI 校验
+func (h *ClientDeviceHandler) validateDeviceAsset(c *fiber.Ctx, identifier string) (*deviceAssetInfo, error) {
+	// 获取当前登录的个人客户 ID
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+
+	ctx := c.UserContext()
+
+	// 通过标识符解析资产
+	asset, err := h.assetService.Resolve(ctx, identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	// 仅设备资产支持设备能力操作
+	if asset.AssetType != "device" {
+		return nil, errors.New(errors.CodeInvalidParam, "仅设备资产支持该操作")
+	}
+
+	// 校验个人客户对该设备的所有权
+	owns, err := h.personalDeviceStore.ExistsByCustomerAndDevice(ctx, customerID, asset.VirtualNo)
+	if err != nil {
+		h.logger.Error("校验设备所有权失败",
+			zap.Uint("customer_id", customerID),
+			zap.String("virtual_no", asset.VirtualNo),
+			zap.Error(err))
+		return nil, errors.New(errors.CodeInternalError)
+	}
+	if !owns {
+		return nil, errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
+	}
+
+	// 校验设备 IMEI 是否存在（Gateway API 调用必需）
+	if asset.IMEI == "" {
+		return nil, errors.New(errors.CodeInvalidParam, "设备IMEI缺失")
+	}
+
+	return &deviceAssetInfo{
+		DeviceID:  asset.AssetID,
+		IMEI:      asset.IMEI,
+		VirtualNo: asset.VirtualNo,
+	}, nil
+}
+
+// GetDeviceCards F1 获取设备卡列表
+// GET /api/c/v1/device/cards
+func (h *ClientDeviceHandler) GetDeviceCards(c *fiber.Ctx) error {
+	var req dto.DeviceCardListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientDeviceValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("设备卡列表参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	info, err := h.validateDeviceAsset(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	ctx := c.UserContext()
+
+	// 查询设备绑定的所有 SIM 卡
+	bindings, err := h.deviceSimBindingStore.ListByDeviceID(ctx, info.DeviceID)
+	if err != nil {
+		h.logger.Error("查询设备SIM绑定失败",
+			zap.Uint("device_id", info.DeviceID),
+			zap.Error(err))
+		return errors.New(errors.CodeInternalError)
+	}
+
+	// 无绑定卡时返回空列表
+	if len(bindings) == 0 {
+		return response.Success(c, &dto.DeviceCardListResponse{Cards: []dto.DeviceCardItem{}})
+	}
+
+	// 收集卡 ID 并记录插槽位置映射
+	cardIDs := make([]uint, 0, len(bindings))
+	slotMap := make(map[uint]int, len(bindings))
+	for _, b := range bindings {
+		cardIDs = append(cardIDs, b.IotCardID)
+		slotMap[b.IotCardID] = b.SlotPosition
+	}
+
+	// 批量查询卡详情
+	cards, err := h.iotCardStore.GetByIDs(ctx, cardIDs)
+	if err != nil {
+		h.logger.Error("批量查询IoT卡失败",
+			zap.Uints("card_ids", cardIDs),
+			zap.Error(err))
+		return errors.New(errors.CodeInternalError)
+	}
+
+	// 组装响应，slot_position == 1 视为当前激活卡
+	items := make([]dto.DeviceCardItem, 0, len(cards))
+	for _, card := range cards {
+		slot := slotMap[card.ID]
+		items = append(items, dto.DeviceCardItem{
+			CardID:         card.ID,
+			ICCID:          card.ICCID,
+			MSISDN:         card.MSISDN,
+			CarrierName:    card.CarrierName,
+			NetworkStatus:  networkStatusText(card.NetworkStatus),
+			RealNameStatus: card.RealNameStatus,
+			SlotPosition:   slot,
+			IsActive:       slot == 1,
+		})
+	}
+
+	return response.Success(c, &dto.DeviceCardListResponse{Cards: items})
+}
+
+// RebootDevice F2 设备重启
+// POST /api/c/v1/device/reboot
+func (h *ClientDeviceHandler) RebootDevice(c *fiber.Ctx) error {
+	var req dto.DeviceRebootRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientDeviceValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("设备重启参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	info, err := h.validateDeviceAsset(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	// 调用 Gateway 重启设备
+	if err := h.gatewayClient.RebootDevice(c.UserContext(), &gateway.DeviceOperationReq{
+		DeviceID: info.IMEI,
+	}); err != nil {
+		h.logger.Error("Gateway重启设备失败",
+			zap.String("imei", info.IMEI),
+			zap.Error(err))
+		return errors.Wrap(errors.CodeGatewayError, err, "设备重启失败")
+	}
+
+	return response.Success(c, &dto.DeviceOperationResponse{Accepted: true})
+}
+
+// FactoryResetDevice F3 恢复出厂设置
+// POST /api/c/v1/device/factory-reset
+func (h *ClientDeviceHandler) FactoryResetDevice(c *fiber.Ctx) error {
+	var req dto.DeviceFactoryResetRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientDeviceValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("恢复出厂设置参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	info, err := h.validateDeviceAsset(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	// 调用 Gateway 恢复出厂设置
+	if err := h.gatewayClient.ResetDevice(c.UserContext(), &gateway.DeviceOperationReq{
+		DeviceID: info.IMEI,
+	}); err != nil {
+		h.logger.Error("Gateway恢复出厂设置失败",
+			zap.String("imei", info.IMEI),
+			zap.Error(err))
+		return errors.Wrap(errors.CodeGatewayError, err, "恢复出厂设置失败")
+	}
+
+	return response.Success(c, &dto.DeviceOperationResponse{Accepted: true})
+}
+
+// SetWiFi F4 设备WiFi配置
+// POST /api/c/v1/device/wifi
+// 注意：WiFiReq.CardNo 字段名具有误导性，实际传入的是设备 IMEI，而非卡号
+func (h *ClientDeviceHandler) SetWiFi(c *fiber.Ctx) error {
+	var req dto.DeviceWifiRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientDeviceValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("WiFi配置参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	info, err := h.validateDeviceAsset(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	// 调用 Gateway 配置 WiFi
+	// CardNo 字段虽名为"卡号"，但 Gateway 实际要求传入设备 IMEI
+	if err := h.gatewayClient.SetWiFi(c.UserContext(), &gateway.WiFiReq{
+		CardNo:   info.IMEI,
+		DeviceID: info.IMEI,
+		SSID:     req.SSID,
+		Password: req.Password,
+		Enabled:  req.Enabled,
+	}); err != nil {
+		h.logger.Error("Gateway配置WiFi失败",
+			zap.String("imei", info.IMEI),
+			zap.String("ssid", req.SSID),
+			zap.Error(err))
+		return errors.Wrap(errors.CodeGatewayError, err, "WiFi配置失败")
+	}
+
+	return response.Success(c, &dto.DeviceOperationResponse{Accepted: true})
+}
+
+// SwitchCard F5 设备切卡
+// POST /api/c/v1/device/switch-card
+func (h *ClientDeviceHandler) SwitchCard(c *fiber.Ctx) error {
+	var req dto.DeviceSwitchCardRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientDeviceValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("设备切卡参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	info, err := h.validateDeviceAsset(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	// 调用 Gateway 切卡，CardNo 传设备 IMEI
+	if err := h.gatewayClient.SwitchCard(c.UserContext(), &gateway.SwitchCardReq{
+		CardNo: info.IMEI,
+		ICCID:  req.TargetICCID,
+	}); err != nil {
+		h.logger.Error("Gateway切卡失败",
+			zap.String("imei", info.IMEI),
+			zap.String("target_iccid", req.TargetICCID),
+			zap.Error(err))
+		return errors.Wrap(errors.CodeGatewayError, err, "设备切卡失败")
+	}
+
+	return response.Success(c, &dto.DeviceSwitchCardResponse{
+		Accepted:    true,
+		TargetICCID: req.TargetICCID,
+	})
+}
+
+// networkStatusText 将网络状态码转为文本描述
+func networkStatusText(status int) string {
+	switch status {
+	case 0:
+		return "停机"
+	case 1:
+		return "开机"
+	default:
+		return "未知"
+	}
+}

internal/handler/app/client_exchange.go

@@ -0,0 +1,57 @@
+package app
+
+import (
+	"strconv"
+
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	exchangeService "github.com/break/junhong_cmp_fiber/internal/service/exchange"
+	"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"
+)
+
+type ClientExchangeHandler struct {
+	service   *exchangeService.Service
+	validator *validator.Validate
+}
+
+func NewClientExchangeHandler(service *exchangeService.Service) *ClientExchangeHandler {
+	return &ClientExchangeHandler{service: service, validator: validator.New()}
+}
+
+func (h *ClientExchangeHandler) GetPending(c *fiber.Ctx) error {
+	var req dto.ClientExchangePendingRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	data, err := h.service.GetPending(c.UserContext(), req.Identifier)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, data)
+}
+
+func (h *ClientExchangeHandler) SubmitShippingInfo(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	var req dto.ClientShippingInfoRequest
+	if err = c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err = h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if err = h.service.SubmitShippingInfo(c.UserContext(), uint(id), &req); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}

internal/handler/app/client_order.go

@@ -0,0 +1,415 @@
+package app
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	clientorder "github.com/break/junhong_cmp_fiber/internal/service/client_order"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"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"
+	"gorm.io/gorm"
+)
+
+// ClientOrderHandler C 端订单处理器
+// 提供 D1~D3 下单、列表、详情接口。
+type ClientOrderHandler struct {
+	clientOrderService  *clientorder.Service
+	assetService        *asset.Service
+	orderStore          *postgres.OrderStore
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore
+	iotCardStore        *postgres.IotCardStore
+	deviceStore         *postgres.DeviceStore
+	logger              *zap.Logger
+	db                  *gorm.DB
+}
+
+// NewClientOrderHandler 创建 C 端订单处理器。
+func NewClientOrderHandler(
+	clientOrderService *clientorder.Service,
+	assetService *asset.Service,
+	orderStore *postgres.OrderStore,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	iotCardStore *postgres.IotCardStore,
+	deviceStore *postgres.DeviceStore,
+	logger *zap.Logger,
+	db *gorm.DB,
+) *ClientOrderHandler {
+	return &ClientOrderHandler{
+		clientOrderService:  clientOrderService,
+		assetService:        assetService,
+		orderStore:          orderStore,
+		personalDeviceStore: personalDeviceStore,
+		iotCardStore:        iotCardStore,
+		deviceStore:         deviceStore,
+		logger:              logger,
+		db:                  db,
+	}
+}
+
+// CreateOrder D1 创建订单。
+// POST /api/c/v1/orders/create
+func (h *ClientOrderHandler) CreateOrder(c *fiber.Ctx) error {
+	var req dto.ClientCreateOrderRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	resp, err := h.clientOrderService.CreateOrder(c.UserContext(), customerID, &req)
+	if err != nil {
+		return err
+	}
+
+	return response.Success(c, resp)
+}
+
+// ListOrders D2 订单列表。
+// GET /api/c/v1/orders
+func (h *ClientOrderHandler) ListOrders(c *fiber.Ctx) error {
+	var req dto.ClientOrderListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if req.Page < 1 {
+		req.Page = 1
+	}
+	if req.PageSize < 1 {
+		req.PageSize = constants.DefaultPageSize
+	}
+	if req.PageSize > constants.MaxPageSize {
+		req.PageSize = constants.MaxPageSize
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	query := h.db.WithContext(resolved.SkipPermissionCtx).
+		Model(&model.Order{}).
+		Where("generation = ?", resolved.Generation)
+
+	if resolved.Asset.AssetType == constants.ResourceTypeDevice {
+		query = query.Where("order_type = ? AND device_id = ?", model.OrderTypeDevice, resolved.Asset.AssetID)
+	} else {
+		query = query.Where("order_type = ? AND iot_card_id = ?", model.OrderTypeSingleCard, resolved.Asset.AssetID)
+	}
+
+	if req.PaymentStatus != nil {
+		paymentStatus, ok := clientPaymentStatusToOrderStatus(*req.PaymentStatus)
+		if !ok {
+			return errors.New(errors.CodeInvalidParam)
+		}
+		query = query.Where("payment_status = ?", paymentStatus)
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询订单总数失败")
+	}
+
+	var orders []*model.Order
+	offset := (req.Page - 1) * req.PageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(req.PageSize).Find(&orders).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询订单列表失败")
+	}
+
+	orderIDs := make([]uint, 0, len(orders))
+	for _, order := range orders {
+		if order == nil {
+			continue
+		}
+		orderIDs = append(orderIDs, order.ID)
+	}
+
+	itemMap, err := h.loadOrderItemMap(resolved.SkipPermissionCtx, orderIDs)
+	if err != nil {
+		return err
+	}
+
+	list := make([]dto.ClientOrderListItem, 0, len(orders))
+	for _, order := range orders {
+		if order == nil {
+			continue
+		}
+
+		packageNames := make([]string, 0, len(itemMap[order.ID]))
+		for _, item := range itemMap[order.ID] {
+			if item == nil || item.PackageName == "" {
+				continue
+			}
+			packageNames = append(packageNames, item.PackageName)
+		}
+
+		list = append(list, dto.ClientOrderListItem{
+			OrderID:       order.ID,
+			OrderNo:       order.OrderNo,
+			TotalAmount:   order.TotalAmount,
+			PaymentStatus: orderStatusToClientPaymentStatus(order.PaymentStatus),
+			CreatedAt:     formatClientOrderTime(order.CreatedAt),
+			PackageNames:  packageNames,
+		})
+	}
+
+	return response.SuccessWithPagination(c, list, total, req.Page, req.PageSize)
+}
+
+// GetOrderDetail D3 订单详情。
+// GET /api/c/v1/orders/:id
+func (h *ClientOrderHandler) GetOrderDetail(c *fiber.Ctx) error {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	orderID, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || orderID == 0 {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	order, items, err := h.orderStore.GetByIDWithItems(c.UserContext(), uint(orderID))
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeNotFound, "订单不存在")
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询订单详情失败")
+	}
+
+	virtualNo, err := h.getOrderVirtualNo(c.UserContext(), order)
+	if err != nil {
+		return err
+	}
+
+	owned, ownErr := h.isCustomerOwnAsset(c.UserContext(), customerID, virtualNo)
+	if ownErr != nil {
+		return errors.Wrap(errors.CodeDatabaseError, ownErr, "查询资产归属失败")
+	}
+	if !owned {
+		return errors.New(errors.CodeForbidden, "无权限操作该资产或资源不存在")
+	}
+
+	packages := make([]dto.ClientOrderPackageItem, 0, len(items))
+	for _, item := range items {
+		if item == nil {
+			continue
+		}
+
+		packages = append(packages, dto.ClientOrderPackageItem{
+			PackageID:   item.PackageID,
+			PackageName: item.PackageName,
+			Price:       item.UnitPrice,
+			Quantity:    item.Quantity,
+		})
+	}
+
+	resp := &dto.ClientOrderDetailResponse{
+		OrderID:       order.ID,
+		OrderNo:       order.OrderNo,
+		TotalAmount:   order.TotalAmount,
+		PaymentStatus: orderStatusToClientPaymentStatus(order.PaymentStatus),
+		PaymentMethod: order.PaymentMethod,
+		CreatedAt:     formatClientOrderTime(order.CreatedAt),
+		PaidAt:        formatClientOrderTimePtr(order.PaidAt),
+		CompletedAt:   nil,
+		Packages:      packages,
+	}
+
+	return response.Success(c, resp)
+}
+
+func (h *ClientOrderHandler) resolveAssetFromIdentifier(c *fiber.Ctx, identifier string) (*resolvedAssetContext, error) {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+
+	identifier = strings.TrimSpace(identifier)
+	if identifier == "" {
+		identifier = strings.TrimSpace(c.Query("identifier"))
+	}
+	if identifier == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	skipPermissionCtx := context.WithValue(c.UserContext(), constants.ContextKeySubordinateShopIDs, []uint{})
+	assetInfo, err := h.assetService.Resolve(skipPermissionCtx, identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	owned, ownErr := h.isCustomerOwnAsset(skipPermissionCtx, customerID, assetInfo.VirtualNo)
+	if ownErr != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, ownErr, "查询资产归属失败")
+	}
+	if !owned {
+		return nil, errors.New(errors.CodeForbidden, "无权限操作该资产或资源不存在")
+	}
+
+	generation, genErr := h.getAssetGeneration(skipPermissionCtx, assetInfo.AssetType, assetInfo.AssetID)
+	if genErr != nil {
+		return nil, genErr
+	}
+
+	return &resolvedAssetContext{
+		CustomerID:        customerID,
+		Identifier:        identifier,
+		Asset:             assetInfo,
+		Generation:        generation,
+		SkipPermissionCtx: skipPermissionCtx,
+	}, nil
+}
+
+func (h *ClientOrderHandler) isCustomerOwnAsset(ctx context.Context, customerID uint, virtualNo string) (bool, error) {
+	records, err := h.personalDeviceStore.GetByCustomerID(ctx, customerID)
+	if err != nil {
+		return false, err
+	}
+
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		if record.Status == constants.StatusEnabled && record.VirtualNo == virtualNo {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+func (h *ClientOrderHandler) getAssetGeneration(ctx context.Context, assetType string, assetID uint) (int, error) {
+	switch assetType {
+	case "card":
+		card, err := h.iotCardStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询卡信息失败")
+		}
+		return card.Generation, nil
+	case constants.ResourceTypeDevice:
+		device, err := h.deviceStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询设备信息失败")
+		}
+		return device.Generation, nil
+	default:
+		return 0, errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func (h *ClientOrderHandler) loadOrderItemMap(ctx context.Context, orderIDs []uint) (map[uint][]*model.OrderItem, error) {
+	result := make(map[uint][]*model.OrderItem)
+	if len(orderIDs) == 0 {
+		return result, nil
+	}
+
+	var items []*model.OrderItem
+	if err := h.db.WithContext(ctx).Where("order_id IN ?", orderIDs).Order("id ASC").Find(&items).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询订单明细失败")
+	}
+
+	for _, item := range items {
+		if item == nil {
+			continue
+		}
+		result[item.OrderID] = append(result[item.OrderID], item)
+	}
+
+	return result, nil
+}
+
+func (h *ClientOrderHandler) getOrderVirtualNo(ctx context.Context, order *model.Order) (string, error) {
+	if order == nil {
+		return "", errors.New(errors.CodeNotFound, "订单不存在")
+	}
+
+	switch order.OrderType {
+	case model.OrderTypeSingleCard:
+		if order.IotCardID == nil || *order.IotCardID == 0 {
+			return "", errors.New(errors.CodeInvalidParam)
+		}
+		card, err := h.iotCardStore.GetByID(ctx, *order.IotCardID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return "", errors.New(errors.CodeAssetNotFound)
+			}
+			return "", errors.Wrap(errors.CodeDatabaseError, err, "查询卡信息失败")
+		}
+		return card.VirtualNo, nil
+	case model.OrderTypeDevice:
+		if order.DeviceID == nil || *order.DeviceID == 0 {
+			return "", errors.New(errors.CodeInvalidParam)
+		}
+		device, err := h.deviceStore.GetByID(ctx, *order.DeviceID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return "", errors.New(errors.CodeAssetNotFound)
+			}
+			return "", errors.Wrap(errors.CodeDatabaseError, err, "查询设备信息失败")
+		}
+		return device.VirtualNo, nil
+	default:
+		return "", errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func orderStatusToClientPaymentStatus(status int) int {
+	switch status {
+	case model.PaymentStatusPending:
+		return 0
+	case model.PaymentStatusPaid:
+		return 1
+	case model.PaymentStatusCancelled:
+		return 2
+	default:
+		return status
+	}
+}
+
+func clientPaymentStatusToOrderStatus(status int) (int, bool) {
+	switch status {
+	case 0:
+		return model.PaymentStatusPending, true
+	case 1:
+		return model.PaymentStatusPaid, true
+	case 2:
+		return model.PaymentStatusCancelled, true
+	default:
+		return 0, false
+	}
+}
+
+func formatClientOrderTime(t time.Time) string {
+	if t.IsZero() {
+		return ""
+	}
+	return t.Format(time.RFC3339)
+}
+
+func formatClientOrderTimePtr(t *time.Time) *string {
+	if t == nil || t.IsZero() {
+		return nil
+	}
+	formatted := formatClientOrderTime(*t)
+	return &formatted
+}

internal/handler/app/client_realname.go

@@ -0,0 +1,249 @@
+package app
+
+import (
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
+
+	"github.com/break/junhong_cmp_fiber/internal/gateway"
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	assetService "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"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/go-playground/validator/v10"
+)
+
+var clientRealnameValidator = validator.New()
+
+// ClientRealnameHandler C 端实名认证处理器
+type ClientRealnameHandler struct {
+	assetService          *assetService.Service
+	personalDeviceStore   *postgres.PersonalCustomerDeviceStore
+	iotCardStore          *postgres.IotCardStore
+	deviceSimBindingStore *postgres.DeviceSimBindingStore
+	carrierStore          *postgres.CarrierStore
+	gatewayClient         *gateway.Client
+	logger                *zap.Logger
+}
+
+// NewClientRealnameHandler 创建 C 端实名认证处理器
+func NewClientRealnameHandler(
+	assetSvc *assetService.Service,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	iotCardStore *postgres.IotCardStore,
+	deviceSimBindingStore *postgres.DeviceSimBindingStore,
+	carrierStore *postgres.CarrierStore,
+	gatewayClient *gateway.Client,
+	logger *zap.Logger,
+) *ClientRealnameHandler {
+	return &ClientRealnameHandler{
+		assetService:          assetSvc,
+		personalDeviceStore:   personalDeviceStore,
+		iotCardStore:          iotCardStore,
+		deviceSimBindingStore: deviceSimBindingStore,
+		carrierStore:          carrierStore,
+		gatewayClient:         gatewayClient,
+		logger:                logger,
+	}
+}
+
+// GetRealnameLink E1 获取实名认证链接
+// GET /api/c/v1/realname/link
+func (h *ClientRealnameHandler) GetRealnameLink(c *fiber.Ctx) error {
+	// 1. 获取当前登录客户
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return errors.New(errors.CodeUnauthorized)
+	}
+
+	// 2. 解析请求参数
+	var req dto.RealnimeLinkRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if err := clientRealnameValidator.Struct(&req); err != nil {
+		logger.GetAppLogger().Warn("实名链接参数校验失败", zap.Error(err))
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	ctx := c.UserContext()
+
+	// 3. 通过标识符解析资产
+	asset, err := h.assetService.Resolve(ctx, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	// 4. 验证资产归属（个人客户必须绑定过该资产）
+	owned, err := h.personalDeviceStore.ExistsByCustomerAndDevice(ctx, customerID, asset.VirtualNo)
+	if err != nil {
+		logger.GetAppLogger().Error("查询资产归属失败",
+			zap.Uint("customer_id", customerID),
+			zap.String("virtual_no", asset.VirtualNo),
+			zap.Error(err))
+		return errors.New(errors.CodeInternalError, "查询资产归属失败")
+	}
+	if !owned {
+		return errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
+	}
+
+	// 5. 定位目标卡（3 条路径）
+	var targetCard *model.IotCard
+	switch {
+	case asset.AssetType == "card":
+		// 路径 1：资产本身就是卡，直接使用
+		card, cardErr := h.iotCardStore.GetByID(ctx, asset.AssetID)
+		if cardErr != nil {
+			return errors.New(errors.CodeIotCardNotFound, "卡信息查询失败")
+		}
+		targetCard = card
+
+	case asset.AssetType == "device" && req.ICCID != "":
+		// 路径 2：资产是设备，指定了 ICCID，从设备绑定中查找该卡
+		card, cardErr := h.findCardInDeviceBindings(c, asset.AssetID, req.ICCID)
+		if cardErr != nil {
+			return cardErr
+		}
+		targetCard = card
+
+	case asset.AssetType == "device":
+		// 路径 3：资产是设备，未指定 ICCID，取第一张绑定卡（按插槽位置排序）
+		card, cardErr := h.findFirstBoundCard(c, asset.AssetID)
+		if cardErr != nil {
+			return cardErr
+		}
+		targetCard = card
+
+	default:
+		return errors.New(errors.CodeInvalidParam, "不支持的资产类型")
+	}
+
+	// 6. 检查实名状态
+	if targetCard.RealNameStatus == 1 {
+		return errors.New(errors.CodeInvalidStatus, "该卡已完成实名")
+	}
+
+	// 7. 获取运营商信息，根据实名链接类型生成 URL
+	carrier, err := h.carrierStore.GetByID(ctx, targetCard.CarrierID)
+	if err != nil {
+		logger.GetAppLogger().Error("查询运营商失败",
+			zap.Uint("carrier_id", targetCard.CarrierID),
+			zap.Error(err))
+		return errors.New(errors.CodeCarrierNotFound, "运营商信息查询失败")
+	}
+
+	resp := &dto.RealnimeLinkResponse{
+		CardInfo: dto.CardInfoBrief{
+			ICCID:     targetCard.ICCID,
+			MSISDN:    targetCard.MSISDN,
+			VirtualNo: targetCard.VirtualNo,
+		},
+	}
+
+	switch carrier.RealnameLinkType {
+	case constants.RealnameLinkTypeNone:
+		// 该运营商不支持在线实名
+		return errors.New(errors.CodeInvalidStatus, "该运营商暂不支持在线实名")
+
+	case constants.RealnameLinkTypeTemplate:
+		// 模板模式：替换占位符生成实名链接
+		url := carrier.RealnameLinkTemplate
+		url = strings.ReplaceAll(url, "{iccid}", targetCard.ICCID)
+		url = strings.ReplaceAll(url, "{msisdn}", targetCard.MSISDN)
+		url = strings.ReplaceAll(url, "{virtual_no}", targetCard.VirtualNo)
+		resp.RealnameMode = constants.RealnameLinkTypeTemplate
+		resp.RealnameURL = url
+
+	case constants.RealnameLinkTypeGateway:
+		// 网关模式：调用 Gateway 接口获取实名链接
+		linkResp, gwErr := h.gatewayClient.GetRealnameLink(ctx, &gateway.CardStatusReq{
+			CardNo: targetCard.ICCID,
+		})
+		if gwErr != nil {
+			logger.GetAppLogger().Error("Gateway 获取实名链接失败",
+				zap.String("iccid", targetCard.ICCID),
+				zap.Error(gwErr))
+			return errors.Wrap(errors.CodeGatewayError, gwErr, "获取实名链接失败")
+		}
+		resp.RealnameMode = constants.RealnameLinkTypeGateway
+		resp.RealnameURL = linkResp.URL
+
+	default:
+		logger.GetAppLogger().Warn("未知的实名链接类型",
+			zap.Uint("carrier_id", carrier.ID),
+			zap.String("realname_link_type", carrier.RealnameLinkType))
+		return errors.New(errors.CodeInvalidStatus, "该运营商暂不支持在线实名")
+	}
+
+	return response.Success(c, resp)
+}
+
+// findCardInDeviceBindings 在设备绑定中查找指定 ICCID 的卡
+func (h *ClientRealnameHandler) findCardInDeviceBindings(c *fiber.Ctx, deviceID uint, iccid string) (*model.IotCard, error) {
+	ctx := c.UserContext()
+
+	// 查询设备的所有有效绑定
+	bindings, err := h.deviceSimBindingStore.ListByDeviceID(ctx, deviceID)
+	if err != nil {
+		logger.GetAppLogger().Error("查询设备绑定失败",
+			zap.Uint("device_id", deviceID),
+			zap.Error(err))
+		return nil, errors.New(errors.CodeInternalError, "查询设备绑定失败")
+	}
+
+	// 收集所有绑定卡的 ID
+	cardIDs := make([]uint, 0, len(bindings))
+	for _, b := range bindings {
+		cardIDs = append(cardIDs, b.IotCardID)
+	}
+
+	if len(cardIDs) == 0 {
+		return nil, errors.New(errors.CodeIotCardNotFound, "该设备未绑定任何卡")
+	}
+
+	// 批量查询卡，匹配指定的 ICCID
+	cards, err := h.iotCardStore.GetByIDs(ctx, cardIDs)
+	if err != nil {
+		return nil, errors.New(errors.CodeInternalError, "查询卡信息失败")
+	}
+
+	for _, card := range cards {
+		if card.ICCID == iccid {
+			return card, nil
+		}
+	}
+
+	return nil, errors.New(errors.CodeIotCardNotFound, "该设备未绑定指定的 ICCID")
+}
+
+// findFirstBoundCard 获取设备第一张绑定卡（按插槽位置排序，取第一张）
+func (h *ClientRealnameHandler) findFirstBoundCard(c *fiber.Ctx, deviceID uint) (*model.IotCard, error) {
+	ctx := c.UserContext()
+
+	// ListByDeviceID 返回 bind_status=1 的绑定，按 slot_position ASC 排序
+	bindings, err := h.deviceSimBindingStore.ListByDeviceID(ctx, deviceID)
+	if err != nil {
+		logger.GetAppLogger().Error("查询设备绑定失败",
+			zap.Uint("device_id", deviceID),
+			zap.Error(err))
+		return nil, errors.New(errors.CodeInternalError, "查询设备绑定失败")
+	}
+
+	if len(bindings) == 0 {
+		return nil, errors.New(errors.CodeIotCardNotFound, "该设备未绑定任何卡")
+	}
+
+	// 取第一张绑定卡（插槽位置最小的）
+	card, err := h.iotCardStore.GetByID(ctx, bindings[0].IotCardID)
+	if err != nil {
+		return nil, errors.New(errors.CodeIotCardNotFound, "卡信息查询失败")
+	}
+
+	return card, nil
+}

internal/handler/app/client_wallet.go

@@ -0,0 +1,660 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"math/rand"
+	"strings"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/middleware"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	rechargeSvc "github.com/break/junhong_cmp_fiber/internal/service/recharge"
+	wechatConfigSvc "github.com/break/junhong_cmp_fiber/internal/service/wechat_config"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+	"github.com/break/junhong_cmp_fiber/pkg/wechat"
+	"github.com/gofiber/fiber/v2"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+// ClientWalletHandler C 端钱包处理器
+// 提供 C1~C5 钱包详情、流水、充值前校验、充值下单、充值记录接口
+type ClientWalletHandler struct {
+	assetService        *asset.Service
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore
+	walletStore         *postgres.AssetWalletStore
+	transactionStore    *postgres.AssetWalletTransactionStore
+	rechargeStore       *postgres.AssetRechargeStore
+	rechargeService     *rechargeSvc.Service
+	openIDStore         *postgres.PersonalCustomerOpenIDStore
+	wechatConfigService *wechatConfigSvc.Service
+	redis               *redis.Client
+	logger              *zap.Logger
+	db                  *gorm.DB
+	iotCardStore        *postgres.IotCardStore
+	deviceStore         *postgres.DeviceStore
+}
+
+// NewClientWalletHandler 创建 C 端钱包处理器
+func NewClientWalletHandler(
+	assetService *asset.Service,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	walletStore *postgres.AssetWalletStore,
+	transactionStore *postgres.AssetWalletTransactionStore,
+	rechargeStore *postgres.AssetRechargeStore,
+	rechargeService *rechargeSvc.Service,
+	openIDStore *postgres.PersonalCustomerOpenIDStore,
+	wechatConfigService *wechatConfigSvc.Service,
+	redisClient *redis.Client,
+	logger *zap.Logger,
+	db *gorm.DB,
+	iotCardStore *postgres.IotCardStore,
+	deviceStore *postgres.DeviceStore,
+) *ClientWalletHandler {
+	return &ClientWalletHandler{
+		assetService:        assetService,
+		personalDeviceStore: personalDeviceStore,
+		walletStore:         walletStore,
+		transactionStore:    transactionStore,
+		rechargeStore:       rechargeStore,
+		rechargeService:     rechargeService,
+		openIDStore:         openIDStore,
+		wechatConfigService: wechatConfigService,
+		redis:               redisClient,
+		logger:              logger,
+		db:                  db,
+		iotCardStore:        iotCardStore,
+		deviceStore:         deviceStore,
+	}
+}
+
+type resolvedWalletAssetContext struct {
+	CustomerID        uint
+	Identifier        string
+	Asset             *dto.AssetResolveResponse
+	Generation        int
+	ResourceType      string
+	SkipPermissionCtx context.Context
+}
+
+// GetWalletDetail C1 钱包详情
+// GET /api/c/v1/wallet/detail
+func (h *ClientWalletHandler) GetWalletDetail(c *fiber.Ctx) error {
+	var req dto.WalletDetailRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	wallet, err := h.getOrCreateWallet(resolved)
+	if err != nil {
+		return err
+	}
+
+	resp := &dto.WalletDetailResponse{
+		WalletID:      wallet.ID,
+		ResourceType:  wallet.ResourceType,
+		ResourceID:    wallet.ResourceID,
+		Balance:       wallet.Balance,
+		FrozenBalance: wallet.FrozenBalance,
+		UpdatedAt:     wallet.UpdatedAt.Format(time.RFC3339),
+	}
+
+	return response.Success(c, resp)
+}
+
+// GetWalletTransactions C2 钱包流水列表
+// GET /api/c/v1/wallet/transactions
+func (h *ClientWalletHandler) GetWalletTransactions(c *fiber.Ctx) error {
+	var req dto.WalletTransactionListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if req.Page < 1 {
+		req.Page = 1
+	}
+	if req.PageSize < 1 {
+		req.PageSize = constants.DefaultPageSize
+	}
+	if req.PageSize > constants.MaxPageSize {
+		req.PageSize = constants.MaxPageSize
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	wallet, err := h.walletStore.GetByResourceTypeAndID(resolved.SkipPermissionCtx, resolved.ResourceType, resolved.Asset.AssetID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return response.SuccessWithPagination(c, []dto.WalletTransactionItem{}, 0, req.Page, req.PageSize)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询钱包失败")
+	}
+
+	var txType *string
+	if strings.TrimSpace(req.TransactionType) != "" {
+		v := strings.TrimSpace(req.TransactionType)
+		txType = &v
+	}
+
+	startTime, err := parseOptionalTime(req.StartTime)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	endTime, err := parseOptionalTime(req.EndTime)
+	if err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if startTime != nil && endTime != nil && endTime.Before(*startTime) {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	offset := (req.Page - 1) * req.PageSize
+	list, err := h.transactionStore.ListByResourceIDWithFilter(
+		resolved.SkipPermissionCtx,
+		wallet.ResourceType,
+		wallet.ResourceID,
+		txType,
+		startTime,
+		endTime,
+		offset,
+		req.PageSize,
+	)
+	if err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询钱包流水失败")
+	}
+
+	total, err := h.transactionStore.CountByResourceIDWithFilter(
+		resolved.SkipPermissionCtx,
+		wallet.ResourceType,
+		wallet.ResourceID,
+		txType,
+		startTime,
+		endTime,
+	)
+	if err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询钱包流水总数失败")
+	}
+
+	items := make([]dto.WalletTransactionItem, 0, len(list))
+	for _, tx := range list {
+		if tx == nil {
+			continue
+		}
+
+		remark := ""
+		if tx.Remark != nil {
+			remark = *tx.Remark
+		}
+
+		items = append(items, dto.WalletTransactionItem{
+			TransactionID: tx.ID,
+			Type:          tx.TransactionType,
+			Amount:        tx.Amount,
+			BalanceAfter:  tx.BalanceAfter,
+			CreatedAt:     tx.CreatedAt.Format(time.RFC3339),
+			Remark:        remark,
+		})
+	}
+
+	return response.SuccessWithPagination(c, items, total, req.Page, req.PageSize)
+}
+
+// GetRechargeCheck C3 充值前校验
+// GET /api/c/v1/wallet/recharge-check
+func (h *ClientWalletHandler) GetRechargeCheck(c *fiber.Ctx) error {
+	var req dto.ClientRechargeCheckRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	check, err := h.rechargeService.GetRechargeCheck(resolved.SkipPermissionCtx, resolved.ResourceType, resolved.Asset.AssetID)
+	if err != nil {
+		return err
+	}
+
+	resp := &dto.ClientRechargeCheckResponse{
+		NeedForceRecharge:   check.NeedForceRecharge,
+		ForceRechargeAmount: check.ForceRechargeAmount,
+		TriggerType:         check.TriggerType,
+		MinAmount:           check.MinAmount,
+		MaxAmount:           check.MaxAmount,
+		Message:             check.Message,
+	}
+
+	return response.Success(c, resp)
+}
+
+// CreateRecharge C4 创建充值订单
+// POST /api/c/v1/wallet/recharge
+func (h *ClientWalletHandler) CreateRecharge(c *fiber.Ctx) error {
+	var req dto.ClientCreateRechargeRequest
+	if err := c.BodyParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if req.PaymentMethod != constants.RechargeMethodWechat {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	wallet, err := h.getOrCreateWallet(resolved)
+	if err != nil {
+		return err
+	}
+
+	config, err := h.wechatConfigService.GetActiveConfig(resolved.SkipPermissionCtx)
+	if err != nil {
+		return err
+	}
+	if config == nil {
+		return errors.New(errors.CodeWechatConfigUnavailable)
+	}
+
+	appID, err := pickAppIDByType(config, req.AppType)
+	if err != nil {
+		return err
+	}
+
+	openID, err := h.findOpenIDByCustomerAndAppID(resolved.SkipPermissionCtx, resolved.CustomerID, appID)
+	if err != nil {
+		return err
+	}
+
+	rechargeNo := generateClientRechargeNo()
+	recharge := &model.AssetRechargeRecord{
+		UserID:          resolved.CustomerID,
+		AssetWalletID:   wallet.ID,
+		ResourceType:    resolved.ResourceType,
+		ResourceID:      resolved.Asset.AssetID,
+		RechargeNo:      rechargeNo,
+		Amount:          req.Amount,
+		PaymentMethod:   constants.RechargeMethodWechat,
+		PaymentConfigID: &config.ID,
+		Status:          constants.RechargeStatusPending,
+		ShopIDTag:       wallet.ShopIDTag,
+		EnterpriseIDTag: wallet.EnterpriseIDTag,
+		OperatorType:    constants.OperatorTypePersonalCustomer,
+		Generation:      resolved.Generation,
+	}
+	if err := h.rechargeStore.Create(resolved.SkipPermissionCtx, recharge); err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "创建充值记录失败")
+	}
+
+	cache := wechat.NewRedisCache(h.redis)
+	paymentApp, err := wechat.NewPaymentAppFromConfig(config, appID, cache, h.logger)
+	if err != nil {
+		return errors.Wrap(errors.CodeWechatPayFailed, err, "初始化微信支付实例失败")
+	}
+	paymentService := wechat.NewPaymentService(paymentApp, h.logger)
+	payResult, err := paymentService.CreateJSAPIOrder(
+		resolved.SkipPermissionCtx,
+		recharge.RechargeNo,
+		"资产钱包充值",
+		openID,
+		int(req.Amount),
+	)
+	if err != nil {
+		return err
+	}
+
+	payConfig := buildClientRechargePayConfig(appID, payResult)
+	resp := &dto.ClientRechargeResponse{
+		Recharge: dto.ClientRechargeResult{
+			RechargeID: recharge.ID,
+			RechargeNo: recharge.RechargeNo,
+			Amount:     recharge.Amount,
+			Status:     recharge.Status,
+		},
+		PayConfig: payConfig,
+	}
+
+	return response.Success(c, resp)
+}
+
+// GetRechargeList C5 充值记录列表
+// GET /api/c/v1/wallet/recharges
+func (h *ClientWalletHandler) GetRechargeList(c *fiber.Ctx) error {
+	var req dto.ClientRechargeListRequest
+	if err := c.QueryParser(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+
+	if req.Page < 1 {
+		req.Page = 1
+	}
+	if req.PageSize < 1 {
+		req.PageSize = constants.DefaultPageSize
+	}
+	if req.PageSize > constants.MaxPageSize {
+		req.PageSize = constants.MaxPageSize
+	}
+
+	resolved, err := h.resolveAssetFromIdentifier(c, req.Identifier)
+	if err != nil {
+		return err
+	}
+
+	query := h.db.WithContext(resolved.SkipPermissionCtx).
+		Model(&model.AssetRechargeRecord{}).
+		Where("resource_type = ? AND resource_id = ? AND generation = ?", resolved.ResourceType, resolved.Asset.AssetID, resolved.Generation)
+	if req.Status != nil {
+		query = query.Where("status = ?", *req.Status)
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询充值记录总数失败")
+	}
+
+	var records []*model.AssetRechargeRecord
+	offset := (req.Page - 1) * req.PageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(req.PageSize).Find(&records).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询充值记录失败")
+	}
+
+	items := make([]dto.ClientRechargeListItem, 0, len(records))
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		items = append(items, dto.ClientRechargeListItem{
+			RechargeID:         record.ID,
+			RechargeNo:         record.RechargeNo,
+			Amount:             record.Amount,
+			Status:             record.Status,
+			PaymentMethod:      record.PaymentMethod,
+			CreatedAt:          record.CreatedAt.Format(time.RFC3339),
+			AutoPurchaseStatus: record.AutoPurchaseStatus,
+		})
+	}
+
+	return response.SuccessWithPagination(c, items, total, req.Page, req.PageSize)
+}
+
+// resolveAssetFromIdentifier 统一执行资产解析与归属校验
+func (h *ClientWalletHandler) resolveAssetFromIdentifier(c *fiber.Ctx, identifier string) (*resolvedWalletAssetContext, error) {
+	customerID, ok := middleware.GetCustomerID(c)
+	if !ok || customerID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+
+	identifier = strings.TrimSpace(identifier)
+	if identifier == "" {
+		identifier = strings.TrimSpace(c.Query("identifier"))
+	}
+	if identifier == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	skipPermissionCtx := context.WithValue(c.UserContext(), constants.ContextKeySubordinateShopIDs, []uint{})
+	assetInfo, err := h.assetService.Resolve(skipPermissionCtx, identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	owned, ownErr := h.isCustomerOwnAsset(skipPermissionCtx, customerID, assetInfo.VirtualNo)
+	if ownErr != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, ownErr, "查询资产归属失败")
+	}
+	if !owned {
+		return nil, errors.New(errors.CodeForbidden, "无权限操作该资产或资源不存在")
+	}
+
+	resourceType, mapErr := mapAssetTypeToWalletResource(assetInfo.AssetType)
+	if mapErr != nil {
+		return nil, mapErr
+	}
+
+	generation, genErr := h.getAssetGeneration(skipPermissionCtx, assetInfo.AssetType, assetInfo.AssetID)
+	if genErr != nil {
+		return nil, genErr
+	}
+
+	return &resolvedWalletAssetContext{
+		CustomerID:        customerID,
+		Identifier:        identifier,
+		Asset:             assetInfo,
+		Generation:        generation,
+		ResourceType:      resourceType,
+		SkipPermissionCtx: skipPermissionCtx,
+	}, nil
+}
+
+func (h *ClientWalletHandler) isCustomerOwnAsset(ctx context.Context, customerID uint, virtualNo string) (bool, error) {
+	records, err := h.personalDeviceStore.GetByCustomerID(ctx, customerID)
+	if err != nil {
+		return false, err
+	}
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		if record.Status == constants.StatusEnabled && record.VirtualNo == virtualNo {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func (h *ClientWalletHandler) getAssetGeneration(ctx context.Context, assetType string, assetID uint) (int, error) {
+	switch assetType {
+	case "card":
+		card, err := h.iotCardStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询卡信息失败")
+		}
+		return card.Generation, nil
+	case "device":
+		device, err := h.deviceStore.GetByID(ctx, assetID)
+		if err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return 0, errors.New(errors.CodeAssetNotFound)
+			}
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询设备信息失败")
+		}
+		return device.Generation, nil
+	default:
+		return 0, errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func (h *ClientWalletHandler) getOrCreateWallet(resolved *resolvedWalletAssetContext) (*model.AssetWallet, error) {
+	wallet, err := h.walletStore.GetByResourceTypeAndID(resolved.SkipPermissionCtx, resolved.ResourceType, resolved.Asset.AssetID)
+	if err == nil {
+		return wallet, nil
+	}
+	if err != gorm.ErrRecordNotFound {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询钱包失败")
+	}
+
+	shopIDTag := uint(0)
+	if resolved.Asset.ShopID != nil {
+		shopIDTag = *resolved.Asset.ShopID
+	}
+
+	newWallet := &model.AssetWallet{
+		ResourceType:  resolved.ResourceType,
+		ResourceID:    resolved.Asset.AssetID,
+		Balance:       0,
+		FrozenBalance: 0,
+		Currency:      "CNY",
+		Status:        constants.AssetWalletStatusNormal,
+		Version:       0,
+		ShopIDTag:     shopIDTag,
+	}
+	if createErr := h.walletStore.Create(resolved.SkipPermissionCtx, newWallet); createErr != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, createErr, "创建钱包失败")
+	}
+
+	wallet, err = h.walletStore.GetByResourceTypeAndID(resolved.SkipPermissionCtx, resolved.ResourceType, resolved.Asset.AssetID)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询钱包失败")
+	}
+	return wallet, nil
+}
+
+func (h *ClientWalletHandler) findOpenIDByCustomerAndAppID(ctx context.Context, customerID uint, appID string) (string, error) {
+	list, err := h.openIDStore.ListByCustomerID(ctx, customerID)
+	if err != nil {
+		return "", errors.Wrap(errors.CodeDatabaseError, err, "查询微信授权信息失败")
+	}
+	for _, item := range list {
+		if item == nil {
+			continue
+		}
+		if item.AppID == appID && strings.TrimSpace(item.OpenID) != "" {
+			return item.OpenID, nil
+		}
+	}
+	return "", errors.New(errors.CodeOpenIDNotFound)
+}
+
+func mapAssetTypeToWalletResource(assetType string) (string, error) {
+	switch assetType {
+	case "card":
+		return constants.AssetWalletResourceTypeIotCard, nil
+	case "device":
+		return constants.AssetWalletResourceTypeDevice, nil
+	default:
+		return "", errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func parseOptionalTime(value string) (*time.Time, error) {
+	v := strings.TrimSpace(value)
+	if v == "" {
+		return nil, nil
+	}
+
+	layouts := []string{time.RFC3339, "2006-01-02 15:04:05", "2006-01-02"}
+	for _, layout := range layouts {
+		t, err := time.Parse(layout, v)
+		if err == nil {
+			return &t, nil
+		}
+	}
+
+	return nil, fmt.Errorf("invalid time format")
+}
+
+func pickAppIDByType(config *model.WechatConfig, appType string) (string, error) {
+	switch appType {
+	case "official_account":
+		if strings.TrimSpace(config.OaAppID) == "" {
+			return "", errors.New(errors.CodeWechatConfigUnavailable)
+		}
+		return config.OaAppID, nil
+	case "miniapp":
+		if strings.TrimSpace(config.MiniappAppID) == "" {
+			return "", errors.New(errors.CodeWechatConfigUnavailable)
+		}
+		return config.MiniappAppID, nil
+	default:
+		return "", errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func generateClientRechargeNo() string {
+	timestamp := time.Now().Format("20060102150405")
+	randomNum := rand.Intn(1000000)
+	return fmt.Sprintf("%s%s%06d", constants.AssetRechargeOrderPrefix, timestamp, randomNum)
+}
+
+func buildClientRechargePayConfig(appID string, result *wechat.JSAPIPayResult) dto.ClientRechargePayConfig {
+	resp := dto.ClientRechargePayConfig{AppID: appID}
+	if result == nil || result.PayConfig == nil {
+		return resp
+	}
+
+	if cfg, ok := result.PayConfig.(map[string]any); ok {
+		resp.Timestamp = getStringFromAnyMap(cfg, "timeStamp", "timestamp")
+		resp.NonceStr = getStringFromAnyMap(cfg, "nonceStr", "nonce_str")
+		resp.PackageVal = getStringFromAnyMap(cfg, "package")
+		resp.SignType = getStringFromAnyMap(cfg, "signType", "sign_type")
+		resp.PaySign = getStringFromAnyMap(cfg, "paySign", "pay_sign")
+		if appIDVal := getStringFromAnyMap(cfg, "appId", "app_id"); appIDVal != "" {
+			resp.AppID = appIDVal
+		}
+		return resp
+	}
+
+	if cfg, ok := result.PayConfig.(map[string]string); ok {
+		resp.Timestamp = cfg["timeStamp"]
+		if resp.Timestamp == "" {
+			resp.Timestamp = cfg["timestamp"]
+		}
+		resp.NonceStr = cfg["nonceStr"]
+		if resp.NonceStr == "" {
+			resp.NonceStr = cfg["nonce_str"]
+		}
+		resp.PackageVal = cfg["package"]
+		resp.SignType = cfg["signType"]
+		if resp.SignType == "" {
+			resp.SignType = cfg["sign_type"]
+		}
+		resp.PaySign = cfg["paySign"]
+		if resp.PaySign == "" {
+			resp.PaySign = cfg["pay_sign"]
+		}
+		if cfg["appId"] != "" {
+			resp.AppID = cfg["appId"]
+		} else if cfg["app_id"] != "" {
+			resp.AppID = cfg["app_id"]
+		}
+	}
+
+	return resp
+}
+
+func getStringFromAnyMap(m map[string]any, keys ...string) string {
+	for _, key := range keys {
+		val, ok := m[key]
+		if !ok || val == nil {
+			continue
+		}
+		switch v := val.(type) {
+		case string:
+			if v != "" {
+				return v
+			}
+		case fmt.Stringer:
+			text := v.String()
+			if text != "" {
+				return text
+			}
+		default:
+			text := fmt.Sprintf("%v", v)
+			if text != "" && text != "<nil>" {
+				return text
+			}
+		}
+	}
+	return ""
+}

internal/handler/app/personal_customer.go

@@ -3,7 +3,6 @@
 package app
 
 import (
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	"github.com/break/junhong_cmp_fiber/internal/service/personal_customer"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/break/junhong_cmp_fiber/pkg/response"
@@ -25,45 +24,6 @@ func NewPersonalCustomerHandler(service *personal_customer.Service, logger *zap.
 	}
 }
 
-// SendCodeRequest 发送验证码请求
-type SendCodeRequest struct {
-	Phone string `json:"phone" validate:"required,len=11"` // 手机号（11位）
-}
-
-// SendCode 发送验证码
-// POST /api/c/v1/login/send-code
-func (h *PersonalCustomerHandler) SendCode(c *fiber.Ctx) error {
-	var req SendCodeRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	// 发送验证码
-	if err := h.service.SendVerificationCode(c.Context(), req.Phone); err != nil {
-		h.logger.Error("发送验证码失败",
-			zap.String("phone", req.Phone),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "发送验证码失败")
-	}
-
-	return response.Success(c, fiber.Map{
-		"message": "验证码已发送",
-	})
-}
-
-// LoginRequest 登录请求
-type LoginRequest struct {
-	Phone string `json:"phone" validate:"required,len=11"` // 手机号（11位）
-	Code  string `json:"code" validate:"required,len=6"`   // 验证码（6位）
-}
-
-// LoginResponse 登录响应
-type LoginResponse struct {
-	Token    string               `json:"token"`    // 访问令牌
-	Customer *PersonalCustomerDTO `json:"customer"` // 客户信息
-}
-
 // PersonalCustomerDTO 个人客户 DTO
 type PersonalCustomerDTO struct {
 	ID        uint   `json:"id"`
@@ -74,87 +34,6 @@ type PersonalCustomerDTO struct {
 	Status    int    `json:"status"`
 }
 
-// Login 登录（手机号 + 验证码）
-// POST /api/c/v1/login
-func (h *PersonalCustomerHandler) Login(c *fiber.Ctx) error {
-	var req LoginRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	// 登录
-	token, customer, err := h.service.LoginByPhone(c.Context(), req.Phone, req.Code)
-	if err != nil {
-		h.logger.Error("登录失败",
-			zap.String("phone", req.Phone),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "登录失败")
-	}
-
-	// 构造响应
-	// 注意：Phone 字段已从 PersonalCustomer 模型移除，需要从 PersonalCustomerPhone 表查询
-	resp := &LoginResponse{
-		Token: token,
-		Customer: &PersonalCustomerDTO{
-			ID:        customer.ID,
-			Phone:     req.Phone, // 使用请求中的手机号（临时方案）
-			Nickname:  customer.Nickname,
-			AvatarURL: customer.AvatarURL,
-			WxOpenID:  customer.WxOpenID,
-			Status:    customer.Status,
-		},
-	}
-
-	return response.Success(c, resp)
-}
-
-// WechatOAuthLogin 微信 OAuth 登录
-// POST /api/c/v1/wechat/auth
-func (h *PersonalCustomerHandler) WechatOAuthLogin(c *fiber.Ctx) error {
-	var req dto.WechatOAuthRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	result, err := h.service.WechatOAuthLogin(c.Context(), req.Code)
-	if err != nil {
-		h.logger.Error("微信 OAuth 登录失败",
-			zap.String("code", req.Code),
-			zap.Error(err),
-		)
-		return err
-	}
-
-	return response.Success(c, result)
-}
-
-// BindWechat 绑定微信
-// POST /api/c/v1/bind-wechat
-func (h *PersonalCustomerHandler) BindWechat(c *fiber.Ctx) error {
-	var req dto.WechatOAuthRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	customerID, ok := c.Locals("customer_id").(uint)
-	if !ok {
-		return errors.New(errors.CodeUnauthorized, "未找到客户信息")
-	}
-
-	if err := h.service.BindWechatWithCode(c.Context(), customerID, req.Code); err != nil {
-		h.logger.Error("绑定微信失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return err
-	}
-
-	return response.Success(c, fiber.Map{
-		"message": "绑定成功",
-	})
-}
-
 // UpdateProfileRequest 更新个人资料请求
 type UpdateProfileRequest struct {
 	Nickname  string `json:"nickname"`   // 昵称

internal/handler/h5/auth.go

@@ -1,160 +0,0 @@
-package h5
-
-import (
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/internal/service/auth"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/logger"
-	"github.com/break/junhong_cmp_fiber/pkg/middleware"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
-	"github.com/go-playground/validator/v10"
-	"github.com/gofiber/fiber/v2"
-	"go.uber.org/zap"
-)
-
-// AuthHandler H5认证处理器
-type AuthHandler struct {
-	authService *auth.Service
-	validator   *validator.Validate
-}
-
-// NewAuthHandler 创建H5认证处理器
-func NewAuthHandler(authService *auth.Service, validator *validator.Validate) *AuthHandler {
-	return &AuthHandler{
-		authService: authService,
-		validator:   validator,
-	}
-}
-
-// Login H5登录
-func (h *AuthHandler) Login(c *fiber.Ctx) error {
-	var req dto.LoginRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	if err := h.validator.Struct(&req); err != nil {
-		logger.GetAppLogger().Warn("参数验证失败",
-			zap.String("path", c.Path()),
-			zap.String("method", c.Method()),
-			zap.Error(err),
-		)
-		return errors.New(errors.CodeInvalidParam)
-	}
-
-	clientIP := c.IP()
-	ctx := c.UserContext()
-
-	resp, err := h.authService.Login(ctx, &req, clientIP)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, resp)
-}
-
-// Logout H5登出
-func (h *AuthHandler) Logout(c *fiber.Ctx) error {
-	auth := c.Get("Authorization")
-	accessToken := ""
-	if len(auth) > 7 && auth[:7] == "Bearer " {
-		accessToken = auth[7:]
-	}
-
-	refreshToken := ""
-	var req dto.RefreshTokenRequest
-	if err := c.BodyParser(&req); err == nil {
-		refreshToken = req.RefreshToken
-	}
-
-	ctx := c.UserContext()
-
-	if err := h.authService.Logout(ctx, accessToken, refreshToken); err != nil {
-		return err
-	}
-
-	return response.Success(c, nil)
-}
-
-// RefreshToken 刷新访问令牌
-func (h *AuthHandler) RefreshToken(c *fiber.Ctx) error {
-	var req dto.RefreshTokenRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	if err := h.validator.Struct(&req); err != nil {
-		logger.GetAppLogger().Warn("参数验证失败",
-			zap.String("path", c.Path()),
-			zap.String("method", c.Method()),
-			zap.Error(err),
-		)
-		return errors.New(errors.CodeInvalidParam)
-	}
-
-	ctx := c.UserContext()
-
-	newAccessToken, err := h.authService.RefreshToken(ctx, req.RefreshToken)
-	if err != nil {
-		return err
-	}
-
-	resp := &dto.RefreshTokenResponse{
-		AccessToken: newAccessToken,
-		ExpiresIn:   86400,
-	}
-
-	return response.Success(c, resp)
-}
-
-// GetMe 获取当前用户信息
-func (h *AuthHandler) GetMe(c *fiber.Ctx) error {
-	userID := middleware.GetUserIDFromContext(c.UserContext())
-	if userID == 0 {
-		return errors.New(errors.CodeUnauthorized, "未授权访问")
-	}
-
-	ctx := c.UserContext()
-
-	userInfo, permissions, err := h.authService.GetCurrentUser(ctx, userID)
-	if err != nil {
-		return err
-	}
-
-	data := map[string]interface{}{
-		"user":        userInfo,
-		"permissions": permissions,
-	}
-
-	return response.Success(c, data)
-}
-
-// ChangePassword 修改密码
-func (h *AuthHandler) ChangePassword(c *fiber.Ctx) error {
-	userID := middleware.GetUserIDFromContext(c.UserContext())
-	if userID == 0 {
-		return errors.New(errors.CodeUnauthorized, "未授权访问")
-	}
-
-	var req dto.ChangePasswordRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	if err := h.validator.Struct(&req); err != nil {
-		logger.GetAppLogger().Warn("参数验证失败",
-			zap.String("path", c.Path()),
-			zap.String("method", c.Method()),
-			zap.Error(err),
-		)
-		return errors.New(errors.CodeInvalidParam)
-	}
-
-	ctx := c.UserContext()
-
-	if err := h.authService.ChangePassword(ctx, userID, req.OldPassword, req.NewPassword); err != nil {
-		return err
-	}
-
-	return response.Success(c, nil)
-}

internal/handler/h5/enterprise_device.go

@@ -1,55 +0,0 @@
-package h5
-
-import (
-	"strconv"
-
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	enterpriseDeviceService "github.com/break/junhong_cmp_fiber/internal/service/enterprise_device"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
-)
-
-type EnterpriseDeviceHandler struct {
-	service *enterpriseDeviceService.Service
-}
-
-func NewEnterpriseDeviceHandler(service *enterpriseDeviceService.Service) *EnterpriseDeviceHandler {
-	return &EnterpriseDeviceHandler{service: service}
-}
-
-func (h *EnterpriseDeviceHandler) ListDevices(c *fiber.Ctx) error {
-	var req dto.H5EnterpriseDeviceListReq
-	if err := c.QueryParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	serviceReq := &dto.EnterpriseDeviceListReq{
-		Page:      req.Page,
-		PageSize:  req.PageSize,
-		VirtualNo: req.VirtualNo,
-	}
-
-	result, err := h.service.ListDevicesForEnterprise(c.UserContext(), serviceReq)
-	if err != nil {
-		return err
-	}
-
-	return response.SuccessWithPagination(c, result.List, result.Total, req.Page, req.PageSize)
-}
-
-func (h *EnterpriseDeviceHandler) GetDeviceDetail(c *fiber.Ctx) error {
-	deviceIDStr := c.Params("device_id")
-	deviceID, err := strconv.ParseUint(deviceIDStr, 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "设备ID格式错误")
-	}
-
-	result, err := h.service.GetDeviceDetail(c.UserContext(), uint(deviceID))
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}

internal/handler/h5/order.go

@@ -1,211 +0,0 @@
-package h5
-
-import (
-	"strconv"
-
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	orderService "github.com/break/junhong_cmp_fiber/internal/service/order"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/middleware"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
-)
-
-type OrderHandler struct {
-	service *orderService.Service
-}
-
-func NewOrderHandler(service *orderService.Service) *OrderHandler {
-	return &OrderHandler{service: service}
-}
-
-func (h *OrderHandler) Create(c *fiber.Ctx) error {
-	var req dto.CreateOrderRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	if req.PaymentMethod != model.PaymentMethodWallet {
-		return errors.New(errors.CodeInvalidParam, "H5端只支持钱包支付")
-	}
-
-	ctx := c.UserContext()
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var buyerType string
-	var buyerID uint
-
-	switch userType {
-	case constants.UserTypeAgent:
-		buyerType = model.BuyerTypeAgent
-		buyerID = middleware.GetShopIDFromContext(ctx)
-	case constants.UserTypeEnterprise:
-		return errors.New(errors.CodeForbidden, "企业账号不支持在线购买")
-	case constants.UserTypePersonalCustomer:
-		buyerType = model.BuyerTypePersonal
-		buyerID = middleware.GetCustomerIDFromContext(ctx)
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	order, err := h.service.CreateH5Order(ctx, &req, buyerType, buyerID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, order)
-}
-
-func (h *OrderHandler) Get(c *fiber.Ctx) error {
-	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "无效的订单ID")
-	}
-
-	order, err := h.service.Get(c.UserContext(), uint(id))
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, order)
-}
-
-func (h *OrderHandler) List(c *fiber.Ctx) error {
-	var req dto.OrderListRequest
-	if err := c.QueryParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	ctx := c.UserContext()
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var buyerType string
-	var buyerID uint
-
-	switch userType {
-	case constants.UserTypeAgent:
-		buyerType = model.BuyerTypeAgent
-		buyerID = middleware.GetShopIDFromContext(ctx)
-	case constants.UserTypePersonalCustomer:
-		buyerType = model.BuyerTypePersonal
-		buyerID = middleware.GetCustomerIDFromContext(ctx)
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	orders, err := h.service.List(ctx, &req, buyerType, buyerID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, orders)
-}
-
-func (h *OrderHandler) WalletPay(c *fiber.Ctx) error {
-	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "无效的订单ID")
-	}
-
-	ctx := c.UserContext()
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var buyerType string
-	var buyerID uint
-
-	switch userType {
-	case constants.UserTypeAgent:
-		buyerType = model.BuyerTypeAgent
-		buyerID = middleware.GetShopIDFromContext(ctx)
-	case constants.UserTypePersonalCustomer:
-		buyerType = model.BuyerTypePersonal
-		buyerID = middleware.GetCustomerIDFromContext(ctx)
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	if err := h.service.WalletPay(ctx, uint(id), buyerType, buyerID); err != nil {
-		return err
-	}
-
-	return response.Success(c, nil)
-}
-
-// WechatPayJSAPI 微信 JSAPI 支付
-// POST /api/h5/orders/:id/wechat-pay/jsapi
-func (h *OrderHandler) WechatPayJSAPI(c *fiber.Ctx) error {
-	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "无效的订单ID")
-	}
-
-	var req dto.WechatPayJSAPIRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	ctx := c.UserContext()
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var buyerType string
-	var buyerID uint
-
-	switch userType {
-	case constants.UserTypeAgent:
-		buyerType = model.BuyerTypeAgent
-		buyerID = middleware.GetShopIDFromContext(ctx)
-	case constants.UserTypePersonalCustomer:
-		buyerType = model.BuyerTypePersonal
-		buyerID = middleware.GetCustomerIDFromContext(ctx)
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	result, err := h.service.WechatPayJSAPI(ctx, uint(id), req.OpenID, buyerType, buyerID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}
-
-// WechatPayH5 微信 H5 支付
-// POST /api/h5/orders/:id/wechat-pay/h5
-func (h *OrderHandler) WechatPayH5(c *fiber.Ctx) error {
-	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "无效的订单ID")
-	}
-
-	var req dto.WechatPayH5Request
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	ctx := c.UserContext()
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var buyerType string
-	var buyerID uint
-
-	switch userType {
-	case constants.UserTypeAgent:
-		buyerType = model.BuyerTypeAgent
-		buyerID = middleware.GetShopIDFromContext(ctx)
-	case constants.UserTypePersonalCustomer:
-		buyerType = model.BuyerTypePersonal
-		buyerID = middleware.GetCustomerIDFromContext(ctx)
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	result, err := h.service.WechatPayH5(ctx, uint(id), &req.SceneInfo, buyerType, buyerID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}

internal/handler/h5/package_usage.go

@@ -1,93 +0,0 @@
-package h5
-
-import (
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	packageService "github.com/break/junhong_cmp_fiber/internal/service/package"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/middleware"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
-	"gorm.io/gorm"
-)
-
-// PackageUsageHandler H5 端套餐使用情况 Handler
-type PackageUsageHandler struct {
-	db                  *gorm.DB
-	customerViewService *packageService.CustomerViewService
-}
-
-// NewPackageUsageHandler 创建 H5 端套餐使用情况 Handler
-func NewPackageUsageHandler(db *gorm.DB, customerViewService *packageService.CustomerViewService) *PackageUsageHandler {
-	return &PackageUsageHandler{
-		db:                  db,
-		customerViewService: customerViewService,
-	}
-}
-
-// GetMyUsage 任务 15.2-15.5: 获取我的套餐使用情况
-// GET /api/h5/packages/my-usage
-func (h *PackageUsageHandler) GetMyUsage(c *fiber.Ctx) error {
-	ctx := c.UserContext()
-
-	// 任务 15.3: 从 JWT 上下文中提取用户信息
-	userType := middleware.GetUserTypeFromContext(ctx)
-
-	var carrierType string
-	var carrierID uint
-
-	// 根据用户类型获取载体信息
-	switch userType {
-	case constants.UserTypePersonalCustomer:
-		// 个人客户：查询其订单关联的 IoT 卡或设备
-		customerID := middleware.GetCustomerIDFromContext(ctx)
-		if customerID == 0 {
-			return errors.New(errors.CodeInvalidParam, "未找到客户信息")
-		}
-
-		// 查询该客户的套餐使用记录，获取载体信息
-		var usage model.PackageUsage
-		err := h.db.WithContext(ctx).
-			Joins("JOIN tb_order ON tb_order.id = tb_package_usage.order_id").
-			Where("tb_order.buyer_type = ? AND tb_order.buyer_id = ?", model.BuyerTypePersonal, customerID).
-			Where("tb_package_usage.status IN ?", []int{constants.PackageUsageStatusActive, constants.PackageUsageStatusDepleted}).
-			Order("tb_package_usage.activated_at DESC").
-			First(&usage).Error
-
-		if err != nil {
-			if err == gorm.ErrRecordNotFound {
-				return errors.New(errors.CodeNotFound, "未找到套餐使用记录")
-			}
-			return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐使用记录失败")
-		}
-
-		// 确定载体类型和 ID
-		if usage.IotCardID > 0 {
-			carrierType = "iot_card"
-			carrierID = usage.IotCardID
-		} else if usage.DeviceID > 0 {
-			carrierType = "device"
-			carrierID = usage.DeviceID
-		} else {
-			return errors.New(errors.CodeInvalidParam, "套餐使用记录未关联卡或设备")
-		}
-
-	case constants.UserTypeAgent, constants.UserTypeEnterprise:
-		// 代理和企业用户暂不支持通过此接口查询
-		// 他们应该使用后台管理接口查询指定卡/设备的套餐情况
-		return errors.New(errors.CodeForbidden, "此接口仅供个人客户使用")
-
-	default:
-		return errors.New(errors.CodeForbidden, "不支持的用户类型")
-	}
-
-	// 任务 15.4: 调用 CustomerViewService.GetMyUsage 获取流量数据
-	usageData, err := h.customerViewService.GetMyUsage(ctx, carrierType, carrierID)
-	if err != nil {
-		return err
-	}
-
-	// 任务 15.5: 返回 PackageUsageCustomerViewResponse 响应
-	return response.Success(c, usageData)
-}

internal/handler/h5/recharge.go

@@ -1,169 +0,0 @@
-package h5
-
-import (
-	"strconv"
-
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	rechargeService "github.com/break/junhong_cmp_fiber/internal/service/recharge"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/middleware"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
-)
-
-// RechargeHandler 充值订单处理器
-// 提供充值订单的创建、预检、查询等接口
-type RechargeHandler struct {
-	service *rechargeService.Service
-}
-
-// NewRechargeHandler 创建充值订单处理器实例
-// 参数:
-//   - service: 充值服务
-//
-// 返回:
-//   - *RechargeHandler: 充值订单处理器实例
-func NewRechargeHandler(service *rechargeService.Service) *RechargeHandler {
-	return &RechargeHandler{service: service}
-}
-
-// Create 创建充值订单
-// POST /api/h5/wallets/recharge
-// 请求参数:
-//   - resource_type: 资源类型（iot_card/device）
-//   - resource_id: 资源ID（卡ID或设备ID）
-//   - amount: 充值金额（分）
-//   - payment_method: 支付方式（wechat/alipay）
-//
-// 响应:
-//   - 成功: 返回充值订单信息（订单ID、订单号、金额、状态等）
-//   - 失败: 返回错误信息
-func (h *RechargeHandler) Create(c *fiber.Ctx) error {
-	var req dto.CreateRechargeRequest
-	if err := c.BodyParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	ctx := c.UserContext()
-	// 获取个人客户ID作为用户ID
-	userID := middleware.GetCustomerIDFromContext(ctx)
-	if userID == 0 {
-		return errors.New(errors.CodeUnauthorized, "用户未登录")
-	}
-
-	result, err := h.service.Create(ctx, &req, userID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}
-
-// RechargeCheck 充值预检
-// GET /api/h5/wallets/recharge-check
-// 请求参数:
-//   - resource_type: 资源类型（iot_card/device）
-//   - resource_id: 资源ID（卡ID或设备ID）
-//
-// 响应:
-//   - 成功: 返回预检信息（是否需要强充、强充金额、最小/最大充值金额等）
-//   - 失败: 返回错误信息
-func (h *RechargeHandler) RechargeCheck(c *fiber.Ctx) error {
-	var req dto.RechargeCheckRequest
-	if err := c.QueryParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	// 验证必填参数
-	if req.ResourceType == "" {
-		return errors.New(errors.CodeInvalidParam, "资源类型不能为空")
-	}
-	if req.ResourceID == 0 {
-		return errors.New(errors.CodeInvalidParam, "资源ID不能为空")
-	}
-
-	ctx := c.UserContext()
-	result, err := h.service.GetRechargeCheck(ctx, req.ResourceType, req.ResourceID)
-	if err != nil {
-		return err
-	}
-
-	// 转换为 DTO 响应
-	resp := &dto.RechargeCheckResponse{
-		NeedForceRecharge:   result.NeedForceRecharge,
-		ForceRechargeAmount: result.ForceRechargeAmount,
-		TriggerType:         result.TriggerType,
-		MinAmount:           result.MinAmount,
-		MaxAmount:           result.MaxAmount,
-		CurrentAccumulated:  result.CurrentAccumulated,
-		Threshold:           result.Threshold,
-		Message:             result.Message,
-		FirstCommissionPaid: result.FirstCommissionPaid,
-	}
-
-	return response.Success(c, resp)
-}
-
-// List 查询充值订单列表
-// GET /api/h5/wallets/recharges
-// 请求参数:
-//   - page: 页码（从1开始，默认1）
-//   - page_size: 每页数量（默认20，最大100）
-//   - wallet_id: 钱包ID筛选（可选）
-//   - status: 状态筛选（可选，1-待支付 2-已支付 3-已完成 4-已关闭 5-已退款）
-//   - start_time: 开始时间筛选（可选）
-//   - end_time: 结束时间筛选（可选）
-//
-// 响应:
-//   - 成功: 返回充值订单列表（分页数据、总记录数、总页数）
-//   - 失败: 返回错误信息
-func (h *RechargeHandler) List(c *fiber.Ctx) error {
-	var req dto.RechargeListRequest
-	if err := c.QueryParser(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
-	}
-
-	ctx := c.UserContext()
-	// 获取个人客户ID作为用户ID
-	userID := middleware.GetCustomerIDFromContext(ctx)
-	if userID == 0 {
-		return errors.New(errors.CodeUnauthorized, "用户未登录")
-	}
-
-	result, err := h.service.List(ctx, &req, userID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}
-
-// Get 查询充值订单详情
-// GET /api/h5/wallets/recharges/:id
-// 路径参数:
-//   - id: 充值订单ID
-//
-// 响应:
-//   - 成功: 返回充值订单详情（订单ID、订单号、金额、状态、支付信息等）
-//   - 失败: 返回错误信息
-func (h *RechargeHandler) Get(c *fiber.Ctx) error {
-	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
-	if err != nil {
-		return errors.New(errors.CodeInvalidParam, "无效的充值订单ID")
-	}
-
-	ctx := c.UserContext()
-	// 获取个人客户ID作为用户ID
-	userID := middleware.GetCustomerIDFromContext(ctx)
-	if userID == 0 {
-		return errors.New(errors.CodeUnauthorized, "用户未登录")
-	}
-
-	result, err := h.service.GetByID(ctx, uint(id), userID)
-	if err != nil {
-		return err
-	}
-
-	return response.Success(c, result)
-}

internal/middleware/personal_auth.go

@@ -1,32 +1,37 @@
 package middleware
 
 import (
+	"context"
 	"strings"
 
 	"github.com/break/junhong_cmp_fiber/pkg/auth"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/gofiber/fiber/v2"
+	"github.com/redis/go-redis/v9"
 	"go.uber.org/zap"
 )
 
 // PersonalAuthMiddleware 个人客户认证中间件
 type PersonalAuthMiddleware struct {
 	jwtManager *auth.JWTManager
+	redis      *redis.Client
 	logger     *zap.Logger
 }
 
 // NewPersonalAuthMiddleware 创建个人客户认证中间件
-func NewPersonalAuthMiddleware(jwtManager *auth.JWTManager, logger *zap.Logger) *PersonalAuthMiddleware {
+func NewPersonalAuthMiddleware(jwtManager *auth.JWTManager, rdb *redis.Client, logger *zap.Logger) *PersonalAuthMiddleware {
 	return &PersonalAuthMiddleware{
 		jwtManager: jwtManager,
+		redis:      rdb,
 		logger:     logger,
 	}
 }
 
 // Authenticate 认证中间件
+// JWT + Redis 双重校验：先验证 JWT 签名和有效期，再检查 Redis 中 token 是否存在
 func (m *PersonalAuthMiddleware) Authenticate() fiber.Handler {
 	return func(c *fiber.Ctx) error {
-		// 从 Authorization header 获取 token
 		authHeader := c.Get("Authorization")
 		if authHeader == "" {
 			m.logger.Warn("个人客户认证失败：缺少 Authorization header",
@@ -36,7 +41,6 @@ func (m *PersonalAuthMiddleware) Authenticate() fiber.Handler {
 			return errors.New(errors.CodeUnauthorized, "未提供认证令牌")
 		}
 
-		// 检查 Bearer 前缀
 		parts := strings.SplitN(authHeader, " ", 2)
 		if len(parts) != 2 || parts[0] != "Bearer" {
 			m.logger.Warn("个人客户认证失败：Authorization header 格式错误",
@@ -48,7 +52,6 @@ func (m *PersonalAuthMiddleware) Authenticate() fiber.Handler {
 
 		token := parts[1]
 
-		// 验证 token
 		claims, err := m.jwtManager.VerifyPersonalCustomerToken(token)
 		if err != nil {
 			m.logger.Warn("个人客户认证失败：token 验证失败",
@@ -58,12 +61,35 @@ func (m *PersonalAuthMiddleware) Authenticate() fiber.Handler {
 			return errors.New(errors.CodeUnauthorized, "认证令牌无效或已过期")
 		}
 
-		// 将客户信息存储到 context 中
+		// Redis 有效性检查：token 必须在 Redis 中存在才视为有效
+		// 支持服务端主动失效（封禁/强制下线/退出登录）
+		redisKey := constants.RedisPersonalCustomerTokenKey(claims.CustomerID)
+		storedToken, redisErr := m.redis.Get(context.Background(), redisKey).Result()
+		if redisErr == redis.Nil {
+			m.logger.Warn("个人客户认证失败：token 已被服务端失效",
+				zap.Uint("customer_id", claims.CustomerID),
+				zap.String("path", c.Path()),
+			)
+			return errors.New(errors.CodeUnauthorized, "认证令牌已失效，请重新登录")
+		}
+		if redisErr != nil {
+			m.logger.Error("个人客户认证：Redis 查询异常",
+				zap.Uint("customer_id", claims.CustomerID),
+				zap.Error(redisErr),
+			)
+			return errors.New(errors.CodeUnauthorized, "认证服务异常，请稍后重试")
+		}
+		// 比对 Redis 中存储的 token 与当前请求 token 是否一致
+		if storedToken != token {
+			m.logger.Warn("个人客户认证失败：token 不匹配（可能已在其他设备登录）",
+				zap.Uint("customer_id", claims.CustomerID),
+				zap.String("path", c.Path()),
+			)
+			return errors.New(errors.CodeUnauthorized, "认证令牌已失效，请重新登录")
+		}
+
 		c.Locals("customer_id", claims.CustomerID)
 		c.Locals("customer_phone", claims.Phone)
-
-		// 设置 SkipOwnerFilter 标记，跳过 B 端数据权限过滤
-		// 个人客户不参与 RBAC 权限体系，不需要 Owner 过滤
 		c.Locals("skip_owner_filter", true)
 
 		m.logger.Debug("个人客户认证成功",

internal/model/asset_wallet.go

@@ -3,6 +3,7 @@ package model
 import (
 	"time"
 
+	"gorm.io/datatypes"
 	"gorm.io/gorm"
 )
 
@@ -85,6 +86,13 @@ type AssetRechargeRecord struct {
 	EnterpriseIDTag      *uint          `gorm:"column:enterprise_id_tag;index;comment:企业ID标签(多租户过滤)" json:"enterprise_id_tag,omitempty"`
 	CreatedAt            time.Time      `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
 	UpdatedAt            time.Time      `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
+	OperatorType         string         `gorm:"column:operator_type;type:varchar(20);not null;default:'admin_user';comment:操作人类型" json:"operator_type"`
+	Generation           int            `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"`
+	LinkedPackageIDs     datatypes.JSON `gorm:"column:linked_package_ids;type:jsonb;default:'[]';comment:强充关联套餐ID列表" json:"linked_package_ids,omitempty"`
+	LinkedOrderType      string         `gorm:"column:linked_order_type;type:varchar(20);comment:关联订单类型" json:"linked_order_type,omitempty"`
+	LinkedCarrierType    string         `gorm:"column:linked_carrier_type;type:varchar(20);comment:关联载体类型" json:"linked_carrier_type,omitempty"`
+	LinkedCarrierID      *uint          `gorm:"column:linked_carrier_id;type:bigint;comment:关联载体ID" json:"linked_carrier_id,omitempty"`
+	AutoPurchaseStatus   string         `gorm:"column:auto_purchase_status;type:varchar(20);default:'';comment:强充自动代购状态(pending-待处理 success-成功 failed-失败)" json:"auto_purchase_status,omitempty"`
 	DeletedAt            gorm.DeletedAt `gorm:"column:deleted_at;index" json:"deleted_at,omitempty"`
 }
 

internal/model/carrier.go

@@ -13,6 +13,8 @@ type Carrier struct {
 	Description          string `gorm:"column:description;type:varchar(500);comment:运营商描述" json:"description"`
 	Status               int    `gorm:"column:status;type:int;default:1;comment:状态 1-启用 0-禁用" json:"status"`
 	BillingDay           int    `gorm:"column:billing_day;type:int;default:1;comment:运营商计费日（用于流量查询接口的计费周期计算，联通=27，其他=1）" json:"billing_day"`
+	RealnameLinkType     string `gorm:"column:realname_link_type;type:varchar(20);not null;default:'none';comment:实名链接类型 none-不支持 template-模板URL gateway-Gateway接口" json:"realname_link_type"`
+	RealnameLinkTemplate string `gorm:"column:realname_link_template;type:varchar(500);default:'';comment:实名链接模板URL" json:"realname_link_template"`
 }
 
 // TableName 指定表名

internal/model/device.go

@@ -35,6 +35,8 @@ type Device struct {
 	AccumulatedRecharge                int64      `gorm:"column:accumulated_recharge;type:bigint;default:0;comment:累计充值金额(分,废弃,使用按系列追踪)" json:"accumulated_recharge"`
 	AccumulatedRechargeBySeriesJSON    string     `gorm:"column:accumulated_recharge_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的累计充值金额" json:"-"`
 	FirstRechargeTriggeredBySeriesJSON string     `gorm:"column:first_recharge_triggered_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的首充触发状态" json:"-"`
+	AssetStatus                        int        `gorm:"column:asset_status;type:int;not null;default:1;comment:业务状态 1-在库 2-已销售 3-已换货 4-已停用" json:"asset_status"`
+	Generation                         int        `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"`
 }
 
 // TableName 指定表名

internal/model/dto/agent_recharge_dto.go

@@ -12,6 +12,12 @@ type AgentOfflinePayRequest struct {
 	OperationPassword string `json:"operation_password" validate:"required" required:"true" description:"操作密码"`
 }
 
+// AgentOfflinePayParams 确认线下充值聚合参数 (用于文档生成)
+type AgentOfflinePayParams struct {
+	IDReq
+	AgentOfflinePayRequest
+}
+
 // AgentRechargeResponse 代理充值记录响应
 type AgentRechargeResponse struct {
 	ID                   uint    `json:"id" description:"充值记录ID"`

internal/model/dto/carrier_dto.go

@@ -5,11 +5,15 @@ type CreateCarrierRequest struct {
 	CarrierName          string  `json:"carrier_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"运营商名称"`
 	CarrierType          string  `json:"carrier_type" validate:"required,oneof=CMCC CUCC CTCC CBN" required:"true" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
 	Description          string  `json:"description" validate:"omitempty,max=500" maxLength:"500" description:"运营商描述"`
+	RealnameLinkType     *string `json:"realname_link_type" validate:"omitempty,oneof=none template gateway" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
+	RealnameLinkTemplate *string `json:"realname_link_template" validate:"omitempty,max=500" maxLength:"500" description:"实名链接模板URL，支持 {iccid}/{msisdn}/{virtual_no} 占位符"`
 }
 
 type UpdateCarrierRequest struct {
 	CarrierName          *string `json:"carrier_name" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"运营商名称"`
 	Description          *string `json:"description" validate:"omitempty,max=500" maxLength:"500" description:"运营商描述"`
+	RealnameLinkType     *string `json:"realname_link_type" validate:"omitempty,oneof=none template gateway" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
+	RealnameLinkTemplate *string `json:"realname_link_template" validate:"omitempty,max=500" maxLength:"500" description:"实名链接模板URL，支持 {iccid}/{msisdn}/{virtual_no} 占位符"`
 }
 
 type CarrierListRequest struct {
@@ -30,6 +34,8 @@ type CarrierResponse struct {
 	CarrierName          string `json:"carrier_name" description:"运营商名称"`
 	CarrierType          string `json:"carrier_type" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
 	Description          string `json:"description" description:"运营商描述"`
+	RealnameLinkType     string `json:"realname_link_type" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
+	RealnameLinkTemplate string `json:"realname_link_template" description:"实名链接模板URL"`
 	Status               int    `json:"status" description:"状态 (1:启用, 0:禁用)"`
 	CreatedAt            string `json:"created_at" description:"创建时间"`
 	UpdatedAt            string `json:"updated_at" description:"更新时间"`

internal/model/dto/client_asset_dto.go

@@ -0,0 +1,181 @@
+package dto
+
+import "time"
+
+// ========================================
+// B1 资产信息
+// ========================================
+
+// AssetInfoRequest B1 资产信息请求
+type AssetInfoRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// AssetInfoResponse B1 资产信息响应
+// 根据 asset_type 不同，设备专属字段或卡专属字段会分别填充（另一侧为零值/omit）
+type AssetInfoResponse struct {
+	// === 基础信息（通用） ===
+	AssetType      string     `json:"asset_type" description:"资产类型（card:卡, device:设备）"`
+	AssetID        uint       `json:"asset_id" description:"资产ID"`
+	Identifier     string     `json:"identifier" description:"资产标识符"`
+	VirtualNo      string     `json:"virtual_no" description:"虚拟号"`
+	Status         int        `json:"status" description:"状态（1:在库, 2:已分销, 3:已激活, 4:已停用）"`
+	RealNameStatus int        `json:"real_name_status" description:"实名状态（0:未实名, 1:已实名）"`
+	CarrierName    string     `json:"carrier_name" description:"运营商名称"`
+	Generation     string     `json:"generation" description:"世代"`
+	WalletBalance  int64      `json:"wallet_balance" description:"钱包余额（分）"`
+	ActivatedAt    *time.Time `json:"activated_at,omitempty" description:"激活时间"`
+
+	// === 套餐信息（通用） ===
+	CurrentPackage  string  `json:"current_package" description:"当前套餐名称（无套餐时为空）"`
+	PackageTotalMB  int64   `json:"package_total_mb" description:"当前套餐总虚流量(MB)，已按虚流量比例换算"`
+	PackageUsedMB   float64 `json:"package_used_mb" description:"当前已用虚流量(MB)，已按虚流量比例换算"`
+	PackageRemainMB float64 `json:"package_remain_mb" description:"当前剩余虚流量(MB)，已按虚流量比例换算"`
+
+	// === 设备专属字段（asset_type=device 时有效） ===
+	DeviceName          string          `json:"device_name,omitempty" description:"设备名称"`
+	IMEI                string          `json:"imei,omitempty" description:"设备IMEI"`
+	SN                  string          `json:"sn,omitempty" description:"设备序列号"`
+	DeviceModel         string          `json:"device_model,omitempty" description:"设备型号"`
+	DeviceType          string          `json:"device_type,omitempty" description:"设备类型"`
+	Manufacturer        string          `json:"manufacturer,omitempty" description:"制造商"`
+	MaxSimSlots         int             `json:"max_sim_slots,omitempty" description:"最大插槽数"`
+	BoundCardCount      int             `json:"bound_card_count,omitempty" description:"绑定卡数量"`
+	Cards               []BoundCardInfo `json:"cards,omitempty" description:"绑定卡列表（含每张卡的ICCID/MSISDN/网络状态/实名状态/插槽位置）"`
+	DeviceProtectStatus string          `json:"device_protect_status,omitempty" description:"设备保护期状态（none:无, stop:停机保护, start:开机保护）"`
+
+	// === 卡专属字段（asset_type=card 时有效） ===
+	ICCID            string `json:"iccid,omitempty" description:"卡ICCID"`
+	MSISDN           string `json:"msisdn,omitempty" description:"手机号"`
+	CarrierID        uint   `json:"carrier_id,omitempty" description:"运营商ID"`
+	CarrierType      string `json:"carrier_type,omitempty" description:"运营商类型（CMCC/CUCC/CTCC/CBN）"`
+	NetworkStatus    int    `json:"network_status,omitempty" description:"网络状态（0:停机, 1:开机）"`
+	ActivationStatus int    `json:"activation_status,omitempty" description:"激活状态（0:未激活, 1:已激活）"`
+	CardCategory     string `json:"card_category,omitempty" description:"卡业务类型（normal:普通卡, industry:行业卡）"`
+
+	// === 卡绑定设备信息（asset_type=card 且绑定了设备时有效） ===
+	BoundDeviceID   *uint  `json:"bound_device_id,omitempty" description:"绑定的设备ID"`
+	BoundDeviceNo   string `json:"bound_device_no,omitempty" description:"绑定的设备虚拟号"`
+	BoundDeviceName string `json:"bound_device_name,omitempty" description:"绑定的设备名称"`
+
+	// === 设备实时状态（来自 Gateway，同步接口对接后自动填充，当前返回 null） ===
+	DeviceRealtime *DeviceRealtimeInfo `json:"device_realtime,omitempty" description:"设备实时状态（Gateway 同步接口对接后填充，当前为 null）"`
+}
+
+// DeviceRealtimeInfo 设备实时状态信息
+// 全量映射 Gateway DeviceInfoDetail 结构，所有字段均为可选
+// 当前 Gateway 同步接口尚未对接，预留结构待后续填充
+type DeviceRealtimeInfo struct {
+	// === 设备状态 ===
+	OnlineStatus   *int64  `json:"online_status,omitempty" description:"在线状态（1:在线, 2:离线）"`
+	BatteryLevel   *int64  `json:"battery_level,omitempty" description:"电池电量百分比"`
+	Status         *int64  `json:"status,omitempty" description:"设备状态（1:正常, 0:禁用）"`
+	RunTime        *string `json:"run_time,omitempty" description:"设备本次开机运行时间(秒)"`
+	ConnectTime    *string `json:"connect_time,omitempty" description:"设备本次联网时间(秒)"`
+	LastOnlineTime *string `json:"last_online_time,omitempty" description:"设备最后在线时间"`
+	LastUpdateTime *string `json:"last_update_time,omitempty" description:"设备信息最后更新时间"`
+
+	// === 信号相关 ===
+	Rsrp *int64  `json:"rsrp,omitempty" description:"参考信号接收功率(dBm)"`
+	Rsrq *int64  `json:"rsrq,omitempty" description:"参考信号接收质量(dB)"`
+	Rssi *string `json:"rssi,omitempty" description:"接收信号强度"`
+	Sinr *int64  `json:"sinr,omitempty" description:"信噪比(dB)"`
+
+	// === WiFi 相关 ===
+	SSID         *string `json:"ssid,omitempty" description:"WiFi热点名称"`
+	WifiEnabled  *bool   `json:"wifi_enabled,omitempty" description:"WiFi开关状态"`
+	WifiPassword *string `json:"wifi_password,omitempty" description:"WiFi密码"`
+
+	// === 网络相关 ===
+	IPAddress  *string `json:"ip_address,omitempty" description:"IP地址"`
+	WANIP      *string `json:"wan_ip,omitempty" description:"基站分配IPv4地址"`
+	LANIP      *string `json:"lan_ip,omitempty" description:"局域网网关IP地址"`
+	MACAddress *string `json:"mac_address,omitempty" description:"MAC地址"`
+
+	// === 流量与速率 ===
+	DailyUsage *string `json:"daily_usage,omitempty" description:"日使用流量(字节)"`
+	DLStats    *string `json:"dl_stats,omitempty" description:"本次开机下载流量(字节)"`
+	ULStats    *string `json:"ul_stats,omitempty" description:"本次开机上传流量(字节)"`
+	LimitSpeed *int64  `json:"limit_speed,omitempty" description:"限速速率(KB/s)"`
+
+	// === 设备属性 ===
+	CurrentIccid    *string `json:"current_iccid,omitempty" description:"当前使用的ICCID"`
+	MaxClients      *int64  `json:"max_clients,omitempty" description:"最大连接客户端数"`
+	SoftwareVersion *string `json:"software_version,omitempty" description:"软件版本号"`
+	SwitchMode      *int    `json:"switch_mode,omitempty" description:"切卡模式（0:自动, 1:手动）"`
+	SyncInterval    *int64  `json:"sync_interval,omitempty" description:"信息上报周期(秒)"`
+
+	// === Gateway 原始标识字段 ===
+	DeviceID   *string `json:"device_id,omitempty" description:"Gateway设备ID(IMEI/SN)"`
+	DeviceName *string `json:"device_name,omitempty" description:"Gateway返回的设备名称"`
+	DeviceType *string `json:"device_type,omitempty" description:"Gateway返回的设备型号"`
+	Imei       *string `json:"imei,omitempty" description:"Gateway返回的IMEI号"`
+	Imsi       *string `json:"imsi,omitempty" description:"Gateway返回的IMSI"`
+	CreatedAt  *int64  `json:"created_at,omitempty" description:"Gateway创建时间(Unix时间戳)"`
+	UpdatedAt  *int64  `json:"updated_at,omitempty" description:"Gateway更新时间(Unix时间戳)"`
+}
+
+// ========================================
+// B2 资产可购套餐列表
+// ========================================
+
+// AssetPackageListRequest B2 资产可购套餐列表请求
+type AssetPackageListRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// ClientPackageItem B2 客户端套餐项
+type ClientPackageItem struct {
+	PackageID     uint   `json:"package_id" description:"套餐ID"`
+	PackageName   string `json:"package_name" description:"套餐名称"`
+	PackageType   string `json:"package_type" description:"套餐类型 (formal:正式套餐, addon:加油包)"`
+	RetailPrice   int64  `json:"retail_price" description:"零售价（分）"`
+	CostPrice     int64  `json:"cost_price" description:"成本价（分）"`
+	ValidityDays  int    `json:"validity_days" description:"有效天数"`
+	IsAddon       bool   `json:"is_addon" description:"是否加油包"`
+	DataAllowance int64  `json:"data_allowance" description:"流量额度"`
+	DataUnit      string `json:"data_unit" description:"流量单位"`
+	Description   string `json:"description" description:"套餐说明"`
+}
+
+// AssetPackageListResponse B2 资产可购套餐列表响应
+type AssetPackageListResponse struct {
+	Packages []ClientPackageItem `json:"packages" description:"套餐列表"`
+}
+
+// ========================================
+// B3 资产套餐历史
+// ========================================
+
+// AssetPackageHistoryRequest B3 资产套餐历史请求
+type AssetPackageHistoryRequest struct {
+	Identifier  string  `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	PackageType *string `json:"package_type" query:"package_type" validate:"omitempty,oneof=formal addon" description:"套餐类型 (formal:正式套餐, addon:加油包)"`
+	Status      *int    `json:"status" query:"status" validate:"omitempty,min=0,max=4" minimum:"0" maximum:"4" description:"套餐状态 (0:待生效, 1:生效中, 2:已用完, 3:已过期, 4:已失效)"`
+	Page        int     `json:"page" query:"page" validate:"required,min=1" required:"true" minimum:"1" description:"页码"`
+	PageSize    int     `json:"page_size" query:"page_size" validate:"required,min=1,max=100" required:"true" minimum:"1" maximum:"100" description:"每页数量"`
+}
+
+// AssetPackageHistoryResponse B3 资产套餐历史响应
+type AssetPackageHistoryResponse struct {
+	List     []AssetPackageResponse `json:"list" description:"套餐历史列表"`
+	Total    int64                  `json:"total" description:"总数"`
+	Page     int                    `json:"page" description:"页码"`
+	PageSize int                    `json:"page_size" description:"每页数量"`
+}
+
+// ========================================
+// B4 资产刷新
+// ========================================
+
+// AssetRefreshRequest B4 资产刷新请求
+type AssetRefreshRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// AssetRefreshResponse B4 资产刷新响应
+type AssetRefreshResponse struct {
+	RefreshType     string `json:"refresh_type" description:"刷新类型 (card:卡, device:设备)"`
+	Accepted        bool   `json:"accepted" description:"是否已受理"`
+	CooldownSeconds int    `json:"cooldown_seconds" description:"冷却秒数"`
+}

internal/model/dto/client_auth_dto.go

@@ -0,0 +1,103 @@
+package dto
+
+// ========================================
+// A1 资产验证
+// ========================================
+
+// VerifyAssetRequest A1 资产验证请求
+type VerifyAssetRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// VerifyAssetResponse A1 资产验证响应
+type VerifyAssetResponse struct {
+	AssetToken string `json:"asset_token" description:"资产令牌（5分钟有效）"`
+	ExpiresIn  int    `json:"expires_in" description:"过期时间（秒）"`
+}
+
+// ========================================
+// A2 公众号登录
+// ========================================
+
+// WechatLoginRequest A2 公众号登录请求
+type WechatLoginRequest struct {
+	Code       string `json:"code" validate:"required" required:"true" description:"微信OAuth授权码"`
+	AssetToken string `json:"asset_token" validate:"required" required:"true" description:"A1返回的资产令牌"`
+}
+
+// WechatLoginResponse A2/A3 登录统一响应
+type WechatLoginResponse struct {
+	Token         string `json:"token" description:"登录JWT令牌"`
+	NeedBindPhone bool   `json:"need_bind_phone" description:"是否需要绑定手机号"`
+	IsNewUser     bool   `json:"is_new_user" description:"是否新创建用户"`
+}
+
+// ========================================
+// A3 小程序登录
+// ========================================
+
+// MiniappLoginRequest A3 小程序登录请求
+type MiniappLoginRequest struct {
+	Code       string `json:"code" validate:"required" required:"true" description:"小程序登录凭证"`
+	AssetToken string `json:"asset_token" validate:"required" required:"true" description:"A1返回的资产令牌"`
+	Nickname   string `json:"nickname" description:"用户昵称（前端授权后传入）"`
+	AvatarURL  string `json:"avatar_url" description:"用户头像URL（前端授权后传入）"`
+}
+
+// ========================================
+// A4 发送验证码
+// ========================================
+
+// ClientSendCodeRequest A4 发送验证码请求
+type ClientSendCodeRequest struct {
+	Phone string `json:"phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"手机号"`
+	Scene string `json:"scene" validate:"required,oneof=bind_phone change_phone_old change_phone_new" required:"true" description:"业务场景 (bind_phone:绑定手机号, change_phone_old:换绑旧手机, change_phone_new:换绑新手机)"`
+}
+
+// ClientSendCodeResponse A4 发送验证码响应
+type ClientSendCodeResponse struct {
+	CooldownSeconds int `json:"cooldown_seconds" description:"冷却秒数"`
+}
+
+// ========================================
+// A5 绑定手机号
+// ========================================
+
+// BindPhoneRequest A5 绑定手机号请求
+type BindPhoneRequest struct {
+	Phone string `json:"phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"手机号"`
+	Code  string `json:"code" validate:"required,len=6" required:"true" minLength:"6" maxLength:"6" description:"验证码"`
+}
+
+// BindPhoneResponse A5 绑定手机号响应
+type BindPhoneResponse struct {
+	Phone   string `json:"phone" description:"已绑定手机号"`
+	BoundAt string `json:"bound_at" description:"绑定时间"`
+}
+
+// ========================================
+// A6 换绑手机号
+// ========================================
+
+// ChangePhoneRequest A6 换绑手机号请求
+type ChangePhoneRequest struct {
+	OldPhone string `json:"old_phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"旧手机号"`
+	OldCode  string `json:"old_code" validate:"required,len=6" required:"true" minLength:"6" maxLength:"6" description:"旧手机号验证码"`
+	NewPhone string `json:"new_phone" validate:"required,len=11" required:"true" minLength:"11" maxLength:"11" description:"新手机号"`
+	NewCode  string `json:"new_code" validate:"required,len=6" required:"true" minLength:"6" maxLength:"6" description:"新手机号验证码"`
+}
+
+// ChangePhoneResponse A6 换绑手机号响应
+type ChangePhoneResponse struct {
+	Phone     string `json:"phone" description:"换绑后手机号"`
+	ChangedAt string `json:"changed_at" description:"换绑时间"`
+}
+
+// ========================================
+// A7 退出登录
+// ========================================
+
+// LogoutResponse A7 退出登录响应
+type LogoutResponse struct {
+	Success bool `json:"success" description:"是否成功"`
+}

internal/model/dto/client_order_dto.go

@@ -0,0 +1,113 @@
+package dto
+
+// ========================================
+// D1 客户端创建订单
+// ========================================
+
+// ClientCreateOrderRequest D1 客户端创建订单请求
+type ClientCreateOrderRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	PackageIDs []uint `json:"package_ids" validate:"required,min=1,dive,gt=0" required:"true" description:"套餐ID列表"`
+	AppType    string `json:"app_type" validate:"required,oneof=official_account miniapp" required:"true" description:"应用类型 (official_account:公众号, miniapp:小程序)"`
+}
+
+// ClientCreateOrderResponse D1 客户端创建订单响应
+type ClientCreateOrderResponse struct {
+	OrderType         string              `json:"order_type" description:"订单类型 (package:套餐订单, recharge:充值订单)"`
+	Order             *ClientOrderInfo    `json:"order,omitempty" description:"套餐订单信息"`
+	Recharge          *ClientRechargeInfo `json:"recharge,omitempty" description:"充值订单信息"`
+	PayConfig         *ClientPayConfig    `json:"pay_config" description:"支付配置"`
+	LinkedPackageInfo *LinkedPackageInfo  `json:"linked_package_info,omitempty" description:"关联套餐信息"`
+}
+
+// ClientOrderInfo D1 套餐订单信息
+type ClientOrderInfo struct {
+	OrderID       uint   `json:"order_id" description:"订单ID"`
+	OrderNo       string `json:"order_no" description:"订单号"`
+	TotalAmount   int64  `json:"total_amount" description:"订单总金额（分）"`
+	PaymentStatus int    `json:"payment_status" description:"支付状态 (0:待支付, 1:已支付, 2:已取消)"`
+	CreatedAt     string `json:"created_at" description:"创建时间"`
+}
+
+// ClientRechargeInfo D1 充值订单信息
+type ClientRechargeInfo struct {
+	RechargeID         uint   `json:"recharge_id" description:"充值ID"`
+	RechargeNo         string `json:"recharge_no" description:"充值单号"`
+	Amount             int64  `json:"amount" description:"充值金额（分）"`
+	Status             int    `json:"status" description:"状态 (0:待支付, 1:已支付, 2:已关闭)"`
+	AutoPurchaseStatus string `json:"auto_purchase_status" description:"自动购包状态"`
+}
+
+// ClientPayConfig D1 支付配置
+type ClientPayConfig struct {
+	AppID      string `json:"app_id" description:"应用ID"`
+	Timestamp  string `json:"timestamp" description:"时间戳"`
+	NonceStr   string `json:"nonce_str" description:"随机字符串"`
+	PackageVal string `json:"package" description:"预支付参数"`
+	SignType   string `json:"sign_type" description:"签名类型"`
+	PaySign    string `json:"pay_sign" description:"支付签名"`
+}
+
+// LinkedPackageInfo D1 关联套餐信息
+type LinkedPackageInfo struct {
+	PackageNames        []string `json:"package_names" description:"套餐名称列表"`
+	TotalPackageAmount  int64    `json:"total_package_amount" description:"套餐总金额（分）"`
+	ForceRechargeAmount int64    `json:"force_recharge_amount" description:"强制充值金额（分）"`
+	WalletCredit        int64    `json:"wallet_credit" description:"钱包抵扣金额（分）"`
+}
+
+// ========================================
+// D2 客户端订单列表
+// ========================================
+
+// ClientOrderListRequest D2 客户端订单列表请求
+type ClientOrderListRequest struct {
+	Identifier    string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	PaymentStatus *int   `json:"payment_status" query:"payment_status" validate:"omitempty,min=0,max=2" minimum:"0" maximum:"2" description:"支付状态 (0:待支付, 1:已支付, 2:已取消)"`
+	Page          int    `json:"page" query:"page" validate:"required,min=1" required:"true" minimum:"1" description:"页码"`
+	PageSize      int    `json:"page_size" query:"page_size" validate:"required,min=1,max=100" required:"true" minimum:"1" maximum:"100" description:"每页数量"`
+}
+
+// ClientOrderListItem D2 客户端订单列表项
+type ClientOrderListItem struct {
+	OrderID       uint     `json:"order_id" description:"订单ID"`
+	OrderNo       string   `json:"order_no" description:"订单号"`
+	TotalAmount   int64    `json:"total_amount" description:"订单总金额（分）"`
+	PaymentStatus int      `json:"payment_status" description:"支付状态 (0:待支付, 1:已支付, 2:已取消)"`
+	CreatedAt     string   `json:"created_at" description:"创建时间"`
+	PackageNames  []string `json:"package_names" description:"套餐名称列表"`
+}
+
+// ClientOrderListResponse D2 客户端订单列表响应
+type ClientOrderListResponse struct {
+	List     []ClientOrderListItem `json:"list" description:"订单列表"`
+	Total    int64                 `json:"total" description:"总数"`
+	Page     int                   `json:"page" description:"页码"`
+	PageSize int                   `json:"page_size" description:"每页数量"`
+}
+
+// ========================================
+// D3 客户端订单详情
+// ========================================
+
+// ClientOrderDetailResponse D3 客户端订单详情响应
+type ClientOrderDetailResponse struct {
+	OrderID       uint                     `json:"order_id" description:"订单ID"`
+	OrderNo       string                   `json:"order_no" description:"订单号"`
+	TotalAmount   int64                    `json:"total_amount" description:"订单总金额（分）"`
+	PaymentStatus int                      `json:"payment_status" description:"支付状态 (0:待支付, 1:已支付, 2:已取消)"`
+	PaymentMethod string                   `json:"payment_method" description:"支付方式"`
+	CreatedAt     string                   `json:"created_at" description:"创建时间"`
+	PaidAt        *string                  `json:"paid_at,omitempty" description:"支付时间"`
+	CompletedAt   *string                  `json:"completed_at,omitempty" description:"完成时间"`
+	Packages      []ClientOrderPackageItem `json:"packages" description:"订单套餐列表"`
+}
+
+// ClientOrderPackageItem D3 订单套餐项
+type ClientOrderPackageItem struct {
+	PackageID   uint   `json:"package_id" description:"套餐ID"`
+	PackageName string `json:"package_name" description:"套餐名称"`
+	PackageType string `json:"package_type" description:"套餐类型 (formal:正式套餐, addon:加油包)"`
+	Price       int64  `json:"price" description:"单价（分）"`
+	Quantity    int    `json:"quantity" description:"数量"`
+}

internal/model/dto/client_realname_device_dto.go

@@ -0,0 +1,104 @@
+package dto
+
+// ========================================
+// E1 实名链接获取
+// ========================================
+
+// RealnimeLinkRequest E1 实名链接请求
+type RealnimeLinkRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	ICCID      string `json:"iccid" query:"iccid" validate:"omitempty,max=30" maxLength:"30" description:"物联网卡ICCID"`
+}
+
+// RealnimeLinkResponse E1 实名链接响应
+type RealnimeLinkResponse struct {
+	RealnameMode string        `json:"realname_mode" description:"实名模式 (none:无需实名, template:模板实名, gateway:网关实名)"`
+	RealnameURL  string        `json:"realname_url" description:"实名链接"`
+	CardInfo     CardInfoBrief `json:"card_info" description:"卡片简要信息"`
+	ExpireAt     *string       `json:"expire_at,omitempty" description:"过期时间"`
+}
+
+// CardInfoBrief E1 卡片简要信息
+type CardInfoBrief struct {
+	ICCID     string `json:"iccid" description:"物联网卡ICCID"`
+	MSISDN    string `json:"msisdn" description:"手机号"`
+	VirtualNo string `json:"virtual_no" description:"虚拟号"`
+}
+
+// ========================================
+// F1 设备卡列表
+// ========================================
+
+// DeviceCardListRequest F1 设备卡列表请求
+type DeviceCardListRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// DeviceCardItem F1 设备卡项
+type DeviceCardItem struct {
+	CardID         uint   `json:"card_id" description:"卡ID"`
+	ICCID          string `json:"iccid" description:"物联网卡ICCID"`
+	MSISDN         string `json:"msisdn" description:"手机号"`
+	CarrierName    string `json:"carrier_name" description:"运营商名称"`
+	NetworkStatus  string `json:"network_status" description:"网络状态"`
+	RealNameStatus int    `json:"real_name_status" description:"实名状态 (0:未实名, 1:已实名)"`
+	SlotPosition   int    `json:"slot_position" description:"插槽位置"`
+	IsActive       bool   `json:"is_active" description:"是否当前激活卡"`
+}
+
+// DeviceCardListResponse F1 设备卡列表响应
+type DeviceCardListResponse struct {
+	Cards []DeviceCardItem `json:"cards" description:"设备卡列表"`
+}
+
+// ========================================
+// F2 设备重启
+// ========================================
+
+// DeviceRebootRequest F2 设备重启请求
+type DeviceRebootRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// DeviceOperationResponse F2/F3/F4 设备操作响应
+type DeviceOperationResponse struct {
+	Accepted  bool   `json:"accepted" description:"是否已受理"`
+	RequestID string `json:"request_id,omitempty" description:"请求ID"`
+}
+
+// ========================================
+// F3 恢复出厂设置
+// ========================================
+
+// DeviceFactoryResetRequest F3 恢复出厂设置请求
+type DeviceFactoryResetRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// ========================================
+// F4 设备WiFi配置
+// ========================================
+
+// DeviceWifiRequest F4 设备WiFi配置请求
+type DeviceWifiRequest struct {
+	Identifier string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	SSID       string `json:"ssid" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi名称"`
+	Password   string `json:"password" validate:"required,min=1,max=64" required:"true" minLength:"1" maxLength:"64" description:"WiFi密码"`
+	Enabled    bool   `json:"enabled" validate:"required" required:"true" description:"是否启用WiFi"`
+}
+
+// ========================================
+// F5 设备切卡
+// ========================================
+
+// DeviceSwitchCardRequest F5 设备切卡请求
+type DeviceSwitchCardRequest struct {
+	Identifier  string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	TargetICCID string `json:"target_iccid" validate:"required,min=1,max=30" required:"true" minLength:"1" maxLength:"30" description:"目标ICCID"`
+}
+
+// DeviceSwitchCardResponse F5 设备切卡响应
+type DeviceSwitchCardResponse struct {
+	Accepted    bool   `json:"accepted" description:"是否已受理"`
+	TargetICCID string `json:"target_iccid" description:"目标ICCID"`
+}

internal/model/dto/client_wallet_dto.go

@@ -0,0 +1,138 @@
+package dto
+
+// ========================================
+// C1 钱包详情
+// ========================================
+
+// WalletDetailRequest C1 钱包详情请求
+type WalletDetailRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// WalletDetailResponse C1 钱包详情响应
+type WalletDetailResponse struct {
+	WalletID      uint   `json:"wallet_id" description:"钱包ID"`
+	ResourceType  string `json:"resource_type" description:"资源类型 (iot_card:物联网卡, device:设备)"`
+	ResourceID    uint   `json:"resource_id" description:"资源ID"`
+	Balance       int64  `json:"balance" description:"可用余额（分）"`
+	FrozenBalance int64  `json:"frozen_balance" description:"冻结余额（分）"`
+	UpdatedAt     string `json:"updated_at" description:"更新时间"`
+}
+
+// ========================================
+// C2 钱包流水列表
+// ========================================
+
+// WalletTransactionListRequest C2 钱包流水列表请求
+type WalletTransactionListRequest struct {
+	Identifier      string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	TransactionType string `json:"transaction_type" query:"transaction_type" validate:"omitempty,max=50" maxLength:"50" description:"流水类型"`
+	StartTime       string `json:"start_time" query:"start_time" validate:"omitempty,max=32" maxLength:"32" description:"开始时间"`
+	EndTime         string `json:"end_time" query:"end_time" validate:"omitempty,max=32" maxLength:"32" description:"结束时间"`
+	Page            int    `json:"page" query:"page" validate:"required,min=1" required:"true" minimum:"1" description:"页码"`
+	PageSize        int    `json:"page_size" query:"page_size" validate:"required,min=1,max=100" required:"true" minimum:"1" maximum:"100" description:"每页数量"`
+}
+
+// WalletTransactionItem C2 钱包流水项
+type WalletTransactionItem struct {
+	TransactionID uint   `json:"transaction_id" description:"流水ID"`
+	Type          string `json:"type" description:"流水类型"`
+	Amount        int64  `json:"amount" description:"变动金额（分）"`
+	BalanceAfter  int64  `json:"balance_after" description:"变动后余额（分）"`
+	CreatedAt     string `json:"created_at" description:"创建时间"`
+	Remark        string `json:"remark" description:"备注"`
+}
+
+// WalletTransactionListResponse C2 钱包流水列表响应
+type WalletTransactionListResponse struct {
+	List     []WalletTransactionItem `json:"list" description:"流水列表"`
+	Total    int64                   `json:"total" description:"总数"`
+	Page     int                     `json:"page" description:"页码"`
+	PageSize int                     `json:"page_size" description:"每页数量"`
+}
+
+// ========================================
+// C3 充值前校验
+// ========================================
+
+// ClientRechargeCheckRequest C3 充值前校验请求
+type ClientRechargeCheckRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+}
+
+// ClientRechargeCheckResponse C3 充值前校验响应
+type ClientRechargeCheckResponse struct {
+	NeedForceRecharge   bool   `json:"need_force_recharge" description:"是否需要强制充值"`
+	ForceRechargeAmount int64  `json:"force_recharge_amount" description:"强制充值金额（分）"`
+	TriggerType         string `json:"trigger_type" description:"触发类型"`
+	MinAmount           int64  `json:"min_amount" description:"最小充值金额（分）"`
+	MaxAmount           int64  `json:"max_amount" description:"最大充值金额（分）"`
+	Message             string `json:"message" description:"提示信息"`
+}
+
+// ========================================
+// C4 创建充值订单
+// ========================================
+
+// ClientCreateRechargeRequest C4 创建充值订单请求
+type ClientCreateRechargeRequest struct {
+	Identifier    string `json:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	Amount        int64  `json:"amount" validate:"required,min=100,max=10000000" required:"true" minimum:"100" maximum:"10000000" description:"充值金额（分）"`
+	PaymentMethod string `json:"payment_method" validate:"required,oneof=wechat" required:"true" description:"支付方式 (wechat:微信支付)"`
+	AppType       string `json:"app_type" validate:"required,oneof=official_account miniapp" required:"true" description:"应用类型 (official_account:公众号, miniapp:小程序)"`
+}
+
+// ClientRechargeResponse C4 创建充值订单响应
+type ClientRechargeResponse struct {
+	Recharge  ClientRechargeResult    `json:"recharge" description:"充值信息"`
+	PayConfig ClientRechargePayConfig `json:"pay_config" description:"支付配置"`
+}
+
+// ClientRechargeResult C4 充值信息
+type ClientRechargeResult struct {
+	RechargeID uint   `json:"recharge_id" description:"充值ID"`
+	RechargeNo string `json:"recharge_no" description:"充值单号"`
+	Amount     int64  `json:"amount" description:"充值金额（分）"`
+	Status     int    `json:"status" description:"状态 (0:待支付, 1:已支付, 2:已关闭)"`
+}
+
+// ClientRechargePayConfig C4 支付配置
+type ClientRechargePayConfig struct {
+	AppID      string `json:"app_id" description:"应用ID"`
+	Timestamp  string `json:"timestamp" description:"时间戳"`
+	NonceStr   string `json:"nonce_str" description:"随机字符串"`
+	PackageVal string `json:"package" description:"预支付参数"`
+	SignType   string `json:"sign_type" description:"签名类型"`
+	PaySign    string `json:"pay_sign" description:"支付签名"`
+}
+
+// ========================================
+// C5 充值记录列表
+// ========================================
+
+// ClientRechargeListRequest C5 充值记录列表请求
+type ClientRechargeListRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"资产标识符（SN/IMEI/虚拟号/ICCID/MSISDN）"`
+	Status     *int   `json:"status" query:"status" validate:"omitempty,min=0,max=2" minimum:"0" maximum:"2" description:"充值状态 (0:待支付, 1:已支付, 2:已关闭)"`
+	Page       int    `json:"page" query:"page" validate:"required,min=1" required:"true" minimum:"1" description:"页码"`
+	PageSize   int    `json:"page_size" query:"page_size" validate:"required,min=1,max=100" required:"true" minimum:"1" maximum:"100" description:"每页数量"`
+}
+
+// ClientRechargeListItem C5 充值记录项
+type ClientRechargeListItem struct {
+	RechargeID         uint   `json:"recharge_id" description:"充值ID"`
+	RechargeNo         string `json:"recharge_no" description:"充值单号"`
+	Amount             int64  `json:"amount" description:"充值金额（分）"`
+	Status             int    `json:"status" description:"状态 (0:待支付, 1:已支付, 2:已关闭)"`
+	PaymentMethod      string `json:"payment_method" description:"支付方式"`
+	CreatedAt          string `json:"created_at" description:"创建时间"`
+	AutoPurchaseStatus string `json:"auto_purchase_status" description:"自动购包状态"`
+}
+
+// ClientRechargeListResponse C5 充值记录列表响应
+type ClientRechargeListResponse struct {
+	List     []ClientRechargeListItem `json:"list" description:"充值记录列表"`
+	Total    int64                    `json:"total" description:"总数"`
+	Page     int                      `json:"page" description:"页码"`
+	PageSize int                      `json:"page_size" description:"每页数量"`
+}

internal/model/dto/exchange_dto.go

@@ -0,0 +1,104 @@
+package dto
+
+import "time"
+
+type CreateExchangeRequest struct {
+	OldAssetType   string  `json:"old_asset_type" validate:"required,oneof=iot_card device" required:"true" description:"旧资产类型 (iot_card:物联网卡, device:设备)"`
+	OldIdentifier  string  `json:"old_identifier" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"旧资产标识符(ICCID/虚拟号/IMEI/SN)"`
+	ExchangeReason string  `json:"exchange_reason" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"换货原因"`
+	Remark         *string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注"`
+}
+
+type ExchangeListRequest struct {
+	Page           int        `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
+	PageSize       int        `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
+	Status         *int       `json:"status" query:"status" validate:"omitempty,min=1,max=5" minimum:"1" maximum:"5" description:"换货状态 (1:待填写信息, 2:待发货, 3:已发货待确认, 4:已完成, 5:已取消)"`
+	Identifier     string     `json:"identifier" query:"identifier" validate:"omitempty,max=100" maxLength:"100" description:"资产标识符搜索(旧资产/新资产标识符模糊匹配)"`
+	CreatedAtStart *time.Time `json:"created_at_start" query:"created_at_start" description:"创建时间起始"`
+	CreatedAtEnd   *time.Time `json:"created_at_end" query:"created_at_end" description:"创建时间结束"`
+}
+
+type ExchangeShipRequest struct {
+	ExpressCompany string `json:"express_company" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"快递公司"`
+	ExpressNo      string `json:"express_no" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"快递单号"`
+	NewIdentifier  string `json:"new_identifier" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"新资产标识符(ICCID/虚拟号/IMEI/SN)"`
+	MigrateData    bool   `json:"migrate_data" required:"true" description:"是否执行全量迁移 (true:执行, false:不执行)"`
+}
+
+type ExchangeCancelRequest struct {
+	Remark *string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"取消备注"`
+}
+
+type ClientShippingInfoRequest struct {
+	RecipientName    string `json:"recipient_name" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"收件人姓名"`
+	RecipientPhone   string `json:"recipient_phone" validate:"required,min=1,max=20" required:"true" minLength:"1" maxLength:"20" description:"收件人电话"`
+	RecipientAddress string `json:"recipient_address" validate:"required,min=1,max=500" required:"true" minLength:"1" maxLength:"500" description:"收货地址"`
+}
+
+type ClientExchangePendingRequest struct {
+	Identifier string `json:"identifier" query:"identifier" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"资产标识符(ICCID/虚拟号/IMEI/SN)"`
+}
+
+type ExchangeIDRequest struct {
+	ID uint `path:"id" required:"true" description:"换货单ID"`
+}
+
+type ExchangeShipParams struct {
+	ID uint `path:"id" required:"true" description:"换货单ID"`
+	ExchangeShipRequest
+}
+
+type ExchangeCancelParams struct {
+	ID uint `path:"id" required:"true" description:"换货单ID"`
+	ExchangeCancelRequest
+}
+
+type ClientShippingInfoParams struct {
+	ID uint `path:"id" required:"true" description:"换货单ID"`
+	ClientShippingInfoRequest
+}
+
+type ExchangeOrderResponse struct {
+	ID                 uint       `json:"id" description:"换货单ID"`
+	ExchangeNo         string     `json:"exchange_no" description:"换货单号"`
+	OldAssetType       string     `json:"old_asset_type" description:"旧资产类型 (iot_card:物联网卡, device:设备)"`
+	OldAssetID         uint       `json:"old_asset_id" description:"旧资产ID"`
+	OldAssetIdentifier string     `json:"old_asset_identifier" description:"旧资产标识符"`
+	NewAssetType       string     `json:"new_asset_type" description:"新资产类型 (iot_card:物联网卡, device:设备)"`
+	NewAssetID         *uint      `json:"new_asset_id,omitempty" description:"新资产ID"`
+	NewAssetIdentifier string     `json:"new_asset_identifier" description:"新资产标识符"`
+	RecipientName      string     `json:"recipient_name" description:"收件人姓名"`
+	RecipientPhone     string     `json:"recipient_phone" description:"收件人电话"`
+	RecipientAddress   string     `json:"recipient_address" description:"收货地址"`
+	ExpressCompany     string     `json:"express_company" description:"快递公司"`
+	ExpressNo          string     `json:"express_no" description:"快递单号"`
+	MigrateData        bool       `json:"migrate_data" description:"是否执行全量迁移"`
+	MigrationCompleted bool       `json:"migration_completed" description:"迁移是否已完成"`
+	MigrationBalance   int64      `json:"migration_balance" description:"迁移转移金额(分)"`
+	ExchangeReason     string     `json:"exchange_reason" description:"换货原因"`
+	Remark             *string    `json:"remark,omitempty" description:"备注"`
+	Status             int        `json:"status" description:"换货状态 (1:待填写信息, 2:待发货, 3:已发货待确认, 4:已完成, 5:已取消)"`
+	StatusText         string     `json:"status_text" description:"换货状态文本"`
+	ShopID             *uint      `json:"shop_id,omitempty" description:"所属店铺ID"`
+	CreatedAt          time.Time  `json:"created_at" description:"创建时间"`
+	UpdatedAt          time.Time  `json:"updated_at" description:"更新时间"`
+	DeletedAt          *time.Time `json:"deleted_at,omitempty" description:"删除时间"`
+	Creator            uint       `json:"creator" description:"创建人ID"`
+	Updater            uint       `json:"updater" description:"更新人ID"`
+}
+
+type ExchangeListResponse struct {
+	List     []*ExchangeOrderResponse `json:"list" description:"换货单列表"`
+	Total    int64                    `json:"total" description:"总数"`
+	Page     int                      `json:"page" description:"当前页码"`
+	PageSize int                      `json:"page_size" description:"每页数量"`
+}
+
+type ClientExchangePendingResponse struct {
+	ID             uint      `json:"id" description:"换货单ID"`
+	ExchangeNo     string    `json:"exchange_no" description:"换货单号"`
+	Status         int       `json:"status" description:"换货状态 (1:待填写信息, 2:待发货, 3:已发货待确认, 4:已完成, 5:已取消)"`
+	StatusText     string    `json:"status_text" description:"换货状态文本"`
+	ExchangeReason string    `json:"exchange_reason" description:"换货原因"`
+	CreatedAt      time.Time `json:"created_at" description:"创建时间"`
+}

internal/model/dto/package_dto.go

@@ -56,6 +56,11 @@ type UpdatePackageShelfStatusRequest struct {
 	ShelfStatus int `json:"shelf_status" validate:"required,oneof=1 2" required:"true" description:"上架状态 (1:上架, 2:下架)"`
 }
 
+// UpdateRetailPriceRequest 更新零售价请求
+type UpdateRetailPriceRequest struct {
+	RetailPrice int64 `json:"retail_price" validate:"required,min=0" required:"true" minimum:"0" description:"零售价（单位：分）"`
+}
+
 // CommissionTierInfo 返佣梯度信息
 type CommissionTierInfo struct {
 	CurrentRate   string `json:"current_rate" description:"当前返佣比例"`
@@ -83,6 +88,7 @@ type PackageResponse struct {
 	ShelfStatus              int                 `json:"shelf_status" description:"上架状态 (1:上架, 2:下架)"`
 	CreatedAt                string              `json:"created_at" description:"创建时间"`
 	UpdatedAt                string              `json:"updated_at" description:"更新时间"`
+	RetailPrice              *int64              `json:"retail_price,omitempty" description:"代理零售价（分），仅代理用户可见"`
 	ProfitMargin             *int64              `json:"profit_margin,omitempty" description:"利润空间（分，仅代理用户可见）"`
 	CurrentCommissionRate    string              `json:"current_commission_rate,omitempty" description:"当前返佣比例（仅代理用户可见）"`
 	TierInfo                 *CommissionTierInfo `json:"tier_info,omitempty" description:"梯度返佣信息（仅代理用户可见）"`
@@ -110,6 +116,12 @@ type UpdatePackageShelfStatusParams struct {
 	UpdatePackageShelfStatusRequest
 }
 
+// UpdateRetailPriceParams 更新零售价聚合参数
+type UpdateRetailPriceParams struct {
+	IDReq
+	UpdateRetailPriceRequest
+}
+
 // PackagePageResult 套餐分页结果
 type PackagePageResult struct {
 	List       []*PackageResponse `json:"list" description:"套餐列表"`

internal/model/dto/shop_package_batch_pricing_dto.go

@@ -12,4 +12,11 @@ type BatchUpdateCostPriceRequest struct {
 type BatchUpdateCostPriceResponse struct {
 	UpdatedCount int                   `json:"updated_count" description:"更新数量"`
 	AffectedIDs  []uint                `json:"affected_ids" description:"受影响的分配ID列表"`
+	Skipped      []BatchPricingSkipped `json:"skipped,omitempty" description:"跳过的记录"`
+}
+
+// BatchPricingSkipped 批量调价跳过记录
+type BatchPricingSkipped struct {
+	AllocationID uint   `json:"allocation_id" description:"分配ID"`
+	Reason       string `json:"reason" description:"跳过原因"`
 }

internal/model/dto/wechat_config_dto.go

@@ -70,6 +70,12 @@ type UpdateWechatConfigRequest struct {
 	FyNotifyURL  *string `json:"fy_notify_url" validate:"omitempty,max=500" maxLength:"500" description:"富友支付回调地址"`
 }
 
+// UpdateWechatConfigParams 更新微信参数配置聚合参数 (用于文档生成)
+type UpdateWechatConfigParams struct {
+	IDReq
+	UpdateWechatConfigRequest
+}
+
 // WechatConfigListRequest 微信参数配置列表查询请求
 type WechatConfigListRequest struct {
 	Page         int     `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`

internal/model/exchange_order.go

@@ -0,0 +1,65 @@
+package model
+
+import (
+	"fmt"
+	"math/rand"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// ExchangeOrder 换货单模型
+// 承载客户端换货的完整生命周期：后台发起 → 客户端填写收货信息 → 后台发货 → 确认完成（含可选全量迁移） → 旧资产可转新
+// 状态机：1-待填写信息 → 2-待发货 → 3-已发货待确认 → 4-已完成，1/2 时可取消 → 5-已取消
+type ExchangeOrder struct {
+	gorm.Model
+	BaseModel `gorm:"embedded"`
+
+	// 单号
+	ExchangeNo string `gorm:"column:exchange_no;type:varchar(50);not null;uniqueIndex:idx_exchange_order_no,where:deleted_at IS NULL;comment:换货单号(EXC+日期+随机数)" json:"exchange_no"`
+
+	// 旧资产快照
+	OldAssetType       string `gorm:"column:old_asset_type;type:varchar(20);not null;comment:旧资产类型(iot_card/device)" json:"old_asset_type"`
+	OldAssetID         uint   `gorm:"column:old_asset_id;not null;index:idx_exchange_order_old_asset;comment:旧资产ID" json:"old_asset_id"`
+	OldAssetIdentifier string `gorm:"column:old_asset_identifier;type:varchar(100);not null;comment:旧资产标识符(ICCID/虚拟号)" json:"old_asset_identifier"`
+
+	// 新资产快照（发货时填写）
+	NewAssetType       string `gorm:"column:new_asset_type;type:varchar(20);comment:新资产类型(iot_card/device)" json:"new_asset_type"`
+	NewAssetID         *uint  `gorm:"column:new_asset_id;comment:新资产ID" json:"new_asset_id,omitempty"`
+	NewAssetIdentifier string `gorm:"column:new_asset_identifier;type:varchar(100);comment:新资产标识符(ICCID/虚拟号)" json:"new_asset_identifier"`
+
+	// 收货信息（客户端填写）
+	RecipientName    string `gorm:"column:recipient_name;type:varchar(50);comment:收件人姓名" json:"recipient_name"`
+	RecipientPhone   string `gorm:"column:recipient_phone;type:varchar(20);comment:收件人电话" json:"recipient_phone"`
+	RecipientAddress string `gorm:"column:recipient_address;type:text;comment:收货地址" json:"recipient_address"`
+
+	// 物流信息（后台发货时填写）
+	ExpressCompany string `gorm:"column:express_company;type:varchar(100);comment:快递公司" json:"express_company"`
+	ExpressNo      string `gorm:"column:express_no;type:varchar(100);comment:快递单号" json:"express_no"`
+
+	// 迁移相关
+	MigrateData        bool  `gorm:"column:migrate_data;type:boolean;default:false;comment:是否执行全量迁移" json:"migrate_data"`
+	MigrationCompleted bool  `gorm:"column:migration_completed;type:boolean;default:false;comment:迁移是否已完成" json:"migration_completed"`
+	MigrationBalance   int64 `gorm:"column:migration_balance;type:bigint;default:0;comment:迁移转移金额(分)" json:"migration_balance"`
+
+	// 业务信息
+	ExchangeReason string  `gorm:"column:exchange_reason;type:varchar(100);not null;comment:换货原因" json:"exchange_reason"`
+	Remark         *string `gorm:"column:remark;type:text;comment:备注" json:"remark,omitempty"`
+	Status         int     `gorm:"column:status;type:int;not null;default:1;index:idx_exchange_order_status;comment:换货状态 1-待填写信息 2-待发货 3-已发货待确认 4-已完成 5-已取消" json:"status"`
+
+	// 多租户
+	ShopID *uint `gorm:"column:shop_id;index;comment:所属店铺ID" json:"shop_id,omitempty"`
+}
+
+// TableName 指定表名
+func (ExchangeOrder) TableName() string {
+	return "tb_exchange_order"
+}
+
+// GenerateExchangeNo 生成换货单号
+// 格式：EXC + 年月日时分秒 + 6位随机数，如 EXC20260319143052123456
+func GenerateExchangeNo() string {
+	now := time.Now()
+	randomNum := rand.Intn(1000000)
+	return fmt.Sprintf("EXC%s%06d", now.Format("20060102150405"), randomNum)
+}

internal/model/iot_card.go

@@ -48,6 +48,8 @@ type IotCard struct {
 	StoppedAt       *time.Time `gorm:"column:stopped_at;comment:停机时间" json:"stopped_at,omitempty"`
 	ResumedAt       *time.Time `gorm:"column:resumed_at;comment:最近复机时间" json:"resumed_at,omitempty"`
 	StopReason      string     `gorm:"column:stop_reason;type:varchar(50);comment:停机原因(traffic_exhausted=流量耗尽,manual=手动停机,arrears=欠费)" json:"stop_reason,omitempty"`
+	AssetStatus     int        `gorm:"column:asset_status;type:int;not null;default:1;comment:业务状态 1-在库 2-已销售 3-已换货 4-已停用" json:"asset_status"`
+	Generation      int        `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"`
 	IsStandalone    bool       `gorm:"column:is_standalone;type:boolean;default:true;not null;comment:是否为独立卡(未绑定设备) 由触发器自动维护" json:"is_standalone"`
 	VirtualNo       string     `gorm:"column:virtual_no;type:varchar(50);uniqueIndex:idx_iot_card_virtual_no,where:deleted_at IS NULL AND virtual_no IS NOT NULL AND virtual_no <> '';comment:虚拟号(可空，全局唯一)" json:"virtual_no,omitempty"`
 }

internal/model/order.go

@@ -40,6 +40,10 @@ type Order struct {
 	SellerCostPrice         int64 `gorm:"column:seller_cost_price;type:bigint;default:0;comment:销售成本价（分，用于计算利润）" json:"seller_cost_price"`
 	SeriesID                *uint `gorm:"column:series_id;index;comment:系列ID（用于查询分配配置）" json:"series_id,omitempty"`
 
+	// 订单来源和世代
+	Source     string `gorm:"column:source;type:varchar(20);not null;default:'admin';comment:订单来源 admin-后台 client-客户端" json:"source"`
+	Generation int    `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"`
+
 	// 代购信息
 	IsPurchaseOnBehalf bool `gorm:"column:is_purchase_on_behalf;type:boolean;default:false;comment:是否为代购订单" json:"is_purchase_on_behalf"`
 

internal/model/package.go

@@ -79,6 +79,7 @@ type PackageUsage struct {
 	DataResetCycle            string     `gorm:"column:data_reset_cycle;type:varchar(20);comment:流量重置周期(从Package复制,用于历史记录)" json:"data_reset_cycle"`
 	LastResetAt               *time.Time `gorm:"column:last_reset_at;comment:最后一次流量重置时间" json:"last_reset_at"`
 	NextResetAt               *time.Time `gorm:"column:next_reset_at;index:idx_package_usage_next_reset_at;comment:下次流量重置时间(用于定时任务查询)" json:"next_reset_at"`
+	Generation                int        `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"`
 }
 
 // TableName 指定表名

internal/model/personal_customer.go

@@ -9,7 +9,7 @@ import (
 // 手机号、ICCID、设备号通过关联表存储
 type PersonalCustomer struct {
 	gorm.Model
-	WxOpenID  string `gorm:"column:wx_open_id;type:varchar(100);uniqueIndex:idx_personal_customer_wx_open_id,where:deleted_at IS NULL;not null;comment:微信OpenID（唯一标识）" json:"wx_open_id"`
+	WxOpenID  string `gorm:"column:wx_open_id;type:varchar(100);index:idx_personal_customer_wx_open_id;not null;comment:微信OpenID（唯一标识）" json:"wx_open_id"`
 	WxUnionID string `gorm:"column:wx_union_id;type:varchar(100);index;not null;comment:微信UnionID" json:"wx_union_id"`
 	Nickname  string `gorm:"column:nickname;type:varchar(100);comment:微信昵称" json:"nickname"`
 	AvatarURL string `gorm:"column:avatar_url;type:varchar(500);comment:微信头像URL" json:"avatar_url"`

internal/model/personal_customer_openid.go

@@ -0,0 +1,23 @@
+package model
+
+import (
+	"gorm.io/gorm"
+)
+
+// PersonalCustomerOpenID 个人客户 OpenID 关联模型
+// 保存客户在不同微信应用（公众号/小程序）下的 OpenID 记录
+// 同一客户可在多个 AppID 下拥有不同的 OpenID
+// 唯一约束：UNIQUE(app_id, open_id) WHERE deleted_at IS NULL
+type PersonalCustomerOpenID struct {
+	gorm.Model
+	CustomerID uint   `gorm:"column:customer_id;type:bigint;not null;index:idx_pco_customer_id;comment:关联个人客户ID" json:"customer_id"`
+	AppID      string `gorm:"column:app_id;type:varchar(100);not null;comment:微信应用标识（公众号或小程序AppID）" json:"app_id"`
+	OpenID     string `gorm:"column:open_id;type:varchar(100);not null;comment:当前应用下的OpenID" json:"open_id"`
+	UnionID    string `gorm:"column:union_id;type:varchar(100);not null;default:'';comment:微信开放平台统一标识（可选）" json:"union_id"`
+	AppType    string `gorm:"column:app_type;type:varchar(20);not null;default:'';comment:应用类型（official_account/miniapp）" json:"app_type"`
+}
+
+// TableName 指定表名
+func (PersonalCustomerOpenID) TableName() string {
+	return "tb_personal_customer_openid"
+}

internal/model/shop_package_allocation.go

@@ -14,6 +14,7 @@ type ShopPackageAllocation struct {
 	SeriesAllocationID *uint `gorm:"column:series_allocation_id;index;comment:关联的系列分配ID" json:"series_allocation_id"`
 	Status             int   `gorm:"column:status;type:int;default:1;not null;comment:状态 1-启用 2-禁用" json:"status"`
 	ShelfStatus        int   `gorm:"column:shelf_status;type:int;default:1;not null;comment:上架状态 1-上架 2-下架" json:"shelf_status"`
+	RetailPrice        int64 `gorm:"column:retail_price;type:bigint;not null;default:0;comment:代理面向终端客户的零售价（分）" json:"retail_price"`
 }
 
 // TableName 指定表名

internal/routes/admin.go

@@ -59,6 +59,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.Device != nil {
 		registerDeviceRoutes(authGroup, handlers.Device, handlers.DeviceImport, doc, basePath)
 	}
+	if handlers.AssetLifecycle != nil {
+		registerAssetLifecycleRoutes(authGroup, handlers.AssetLifecycle, doc, basePath)
+	}
 	if handlers.AssetAllocationRecord != nil {
 		registerAssetAllocationRecordRoutes(authGroup, handlers.AssetAllocationRecord, doc, basePath)
 	}
@@ -89,6 +92,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.AdminOrder != nil {
 		registerAdminOrderRoutes(authGroup, handlers.AdminOrder, doc, basePath)
 	}
+	if handlers.AdminExchange != nil {
+		registerAdminExchangeRoutes(authGroup, handlers.AdminExchange, doc, basePath)
+	}
 	if handlers.PollingConfig != nil {
 		registerPollingConfigRoutes(authGroup, handlers.PollingConfig, doc, basePath)
 	}

internal/routes/agent_recharge.go

@@ -48,7 +48,7 @@ func registerAgentRechargeRoutes(router fiber.Router, handler *admin.AgentRechar
 	Register(group, doc, groupPath, "POST", "/:id/offline-pay", handler.OfflinePay, RouteSpec{
 		Summary: "确认线下充值",
 		Tags:    []string{"代理预充值"},
-		Input:   new(dto.AgentOfflinePayRequest),
+		Input:   new(dto.AgentOfflinePayParams),
 		Output:  new(dto.AgentRechargeResponse),
 		Auth:    true,
 	})

internal/routes/asset_lifecycle.go

@@ -0,0 +1,28 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerAssetLifecycleRoutes 注册资产手动停用路由
+func registerAssetLifecycleRoutes(router fiber.Router, handler *admin.AssetLifecycleHandler, doc *openapi.Generator, basePath string) {
+	Register(router, doc, basePath, "PATCH", "/iot-cards/:id/deactivate", handler.DeactivateIotCard, RouteSpec{
+		Summary: "手动停用IoT卡",
+		Tags:    []string{"IoT卡管理"},
+		Input:   new(dto.IDReq),
+		Output:  nil,
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "PATCH", "/devices/:id/deactivate", handler.DeactivateDevice, RouteSpec{
+		Summary: "手动停用设备",
+		Tags:    []string{"设备管理"},
+		Input:   new(dto.IDReq),
+		Output:  nil,
+		Auth:    true,
+	})
+}

internal/routes/exchange.go

@@ -0,0 +1,66 @@
+package routes
+
+import (
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+	"github.com/gofiber/fiber/v2"
+)
+
+func registerAdminExchangeRoutes(router fiber.Router, handler *admin.ExchangeHandler, doc *openapi.Generator, basePath string) {
+	Register(router, doc, basePath, "POST", "/exchanges", handler.Create, RouteSpec{
+		Summary: "创建换货单",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.CreateExchangeRequest),
+		Output:  new(dto.ExchangeOrderResponse),
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "GET", "/exchanges", handler.List, RouteSpec{
+		Summary: "获取换货单列表",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeListRequest),
+		Output:  new(dto.ExchangeListResponse),
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "GET", "/exchanges/:id", handler.Get, RouteSpec{
+		Summary: "获取换货单详情",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeIDRequest),
+		Output:  new(dto.ExchangeOrderResponse),
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "POST", "/exchanges/:id/ship", handler.Ship, RouteSpec{
+		Summary: "换货发货",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeShipParams),
+		Output:  new(dto.ExchangeOrderResponse),
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "POST", "/exchanges/:id/complete", handler.Complete, RouteSpec{
+		Summary: "确认换货完成",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeIDRequest),
+		Output:  nil,
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "POST", "/exchanges/:id/cancel", handler.Cancel, RouteSpec{
+		Summary: "取消换货",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeCancelParams),
+		Output:  nil,
+		Auth:    true,
+	})
+
+	Register(router, doc, basePath, "POST", "/exchanges/:id/renew", handler.Renew, RouteSpec{
+		Summary: "旧资产转新",
+		Tags:    []string{"换货管理"},
+		Input:   new(dto.ExchangeIDRequest),
+		Output:  nil,
+		Auth:    true,
+	})
+}

internal/routes/h5.go

@@ -1,27 +0,0 @@
-package routes
-
-import (
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
-	"github.com/break/junhong_cmp_fiber/pkg/openapi"
-)
-
-// RegisterH5Routes 注册H5相关路由
-func RegisterH5Routes(router fiber.Router, handlers *bootstrap.Handlers, middlewares *bootstrap.Middlewares, doc *openapi.Generator, basePath string) {
-	// 认证路由已迁移到 /api/auth，参见 RegisterAuthRoutes
-	authGroup := router.Group("", middlewares.H5Auth)
-
-	if handlers.H5Order != nil {
-		registerH5OrderRoutes(authGroup, handlers.H5Order, doc, basePath)
-	}
-	if handlers.H5Recharge != nil {
-		registerH5RechargeRoutes(authGroup, handlers.H5Recharge, doc, basePath)
-	}
-	if handlers.EnterpriseDeviceH5 != nil {
-		registerH5EnterpriseDeviceRoutes(authGroup, handlers.EnterpriseDeviceH5, doc, basePath)
-	}
-	if handlers.H5PackageUsage != nil {
-		registerH5PackageUsageRoutes(authGroup, handlers.H5PackageUsage, doc, basePath)
-	}
-}

internal/routes/h5_enterprise_device.go

@@ -1,31 +0,0 @@
-package routes
-
-import (
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/pkg/openapi"
-)
-
-func registerH5EnterpriseDeviceRoutes(router fiber.Router, handler *h5.EnterpriseDeviceHandler, doc *openapi.Generator, basePath string) {
-	devices := router.Group("/devices")
-	groupPath := basePath + "/devices"
-
-	Register(devices, doc, groupPath, "GET", "", handler.ListDevices, RouteSpec{
-		Summary: "企业设备列表（H5）",
-		Tags:    []string{"H5-企业设备"},
-		Input:   new(dto.H5EnterpriseDeviceListReq),
-		Output:  new(dto.EnterpriseDeviceListResp),
-		Auth:    true,
-	})
-
-	Register(devices, doc, groupPath, "GET", "/:device_id", handler.GetDeviceDetail, RouteSpec{
-		Summary: "获取设备详情（H5）",
-		Tags:    []string{"H5-企业设备"},
-		Input:   new(dto.DeviceDetailReq),
-		Output:  new(dto.EnterpriseDeviceDetailResp),
-		Auth:    true,
-	})
-
-}

internal/routes/h5_package_usage.go

@@ -1,23 +0,0 @@
-package routes
-
-import (
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/pkg/openapi"
-)
-
-// registerH5PackageUsageRoutes 注册 H5 端套餐使用情况路由
-func registerH5PackageUsageRoutes(router fiber.Router, handler *h5.PackageUsageHandler, doc *openapi.Generator, basePath string) {
-	packages := router.Group("/packages")
-	groupPath := basePath + "/packages"
-
-	Register(packages, doc, groupPath, "GET", "/my-usage", handler.GetMyUsage, RouteSpec{
-		Summary: "获取我的套餐使用情况",
-		Tags:    []string{"H5-套餐"},
-		Input:   nil,
-		Output:  new(dto.PackageUsageCustomerViewResponse),
-		Auth:    true,
-	})
-}

internal/routes/order.go

@@ -5,7 +5,6 @@ import (
 
 	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
 	"github.com/break/junhong_cmp_fiber/internal/handler/callback"
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	"github.com/break/junhong_cmp_fiber/pkg/openapi"
 )
@@ -53,57 +52,6 @@ func registerAdminOrderRoutes(router fiber.Router, handler *admin.OrderHandler,
 	})
 }
 
-// registerH5OrderRoutes 注册H5订单路由
-func registerH5OrderRoutes(router fiber.Router, handler *h5.OrderHandler, doc *openapi.Generator, basePath string) {
-	Register(router, doc, basePath, "POST", "/orders", handler.Create, RouteSpec{
-		Summary: "创建订单",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.CreateOrderRequest),
-		Output:  new(dto.OrderResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "GET", "/orders", handler.List, RouteSpec{
-		Summary: "获取订单列表",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.OrderListRequest),
-		Output:  new(dto.OrderListResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "GET", "/orders/:id", handler.Get, RouteSpec{
-		Summary: "获取订单详情",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.GetOrderRequest),
-		Output:  new(dto.OrderResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "POST", "/orders/:id/wallet-pay", handler.WalletPay, RouteSpec{
-		Summary: "钱包支付",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.CancelOrderRequest),
-		Output:  nil,
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "POST", "/orders/:id/wechat-pay/jsapi", handler.WechatPayJSAPI, RouteSpec{
-		Summary: "微信 JSAPI 支付",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.WechatPayJSAPIParams),
-		Output:  new(dto.WechatPayJSAPIResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "POST", "/orders/:id/wechat-pay/h5", handler.WechatPayH5, RouteSpec{
-		Summary: "微信 H5 支付",
-		Tags:    []string{"H5 订单"},
-		Input:   new(dto.WechatPayH5Params),
-		Output:  new(dto.WechatPayH5Response),
-		Auth:    true,
-	})
-}
-
 // registerPaymentCallbackRoutes 注册支付回调路由
 func registerPaymentCallbackRoutes(router fiber.Router, handler *callback.PaymentHandler, doc *openapi.Generator, basePath string) {
 	Register(router, doc, basePath, "POST", "/wechat-pay", handler.WechatPayCallback, RouteSpec{

internal/routes/package.go

@@ -67,4 +67,12 @@ func registerPackageRoutes(router fiber.Router, handler *admin.PackageHandler, d
 		Output:  nil,
 		Auth:    true,
 	})
+
+	Register(packages, doc, groupPath, "PATCH", "/:id/retail-price", handler.UpdateRetailPrice, RouteSpec{
+		Summary: "修改零售价（代理）",
+		Tags:    []string{"套餐管理"},
+		Input:   new(dto.UpdateRetailPriceParams),
+		Output:  nil,
+		Auth:    true,
+	})
 }

internal/routes/personal.go

@@ -12,54 +12,79 @@ import (
 
 // RegisterPersonalCustomerRoutes 注册个人客户路由
 // 路由挂载在 /api/c/v1 下
+//
+// 重要：Fiber 的 Group.Use() 会在路由表中注册全局 USE 处理器，
+// 匹配该前缀下的所有请求（不区分 Group 对象）。
+// 因此公开路由必须在任何 Use() 调用之前注册，利用 Fiber 按注册顺序匹配的机制，
+// 确保公开路由优先命中并直接返回，不会被后续的认证中间件拦截。
 func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers, personalAuthMiddleware *middleware.PersonalAuthMiddleware) {
-	// 公开路由（不需要认证）
-	publicGroup := router.Group("")
+	authBasePath := "/auth"
 
-	// 发送验证码
-	Register(publicGroup, doc, basePath, "POST", "/login/send-code", handlers.PersonalCustomer.SendCode, RouteSpec{
+	// === 公开路由（无需认证）===
+	Register(router, doc, basePath, "POST", authBasePath+"/verify-asset", handlers.ClientAuth.VerifyAsset, RouteSpec{
+		Summary: "资产验证",
+		Tags:    []string{"个人客户 - 认证"},
+		Auth:    false,
+		Input:   &dto.VerifyAssetRequest{},
+		Output:  &dto.VerifyAssetResponse{},
+	})
+
+	Register(router, doc, basePath, "POST", authBasePath+"/wechat-login", handlers.ClientAuth.WechatLogin, RouteSpec{
+		Summary: "公众号登录",
+		Tags:    []string{"个人客户 - 认证"},
+		Auth:    false,
+		Input:   &dto.WechatLoginRequest{},
+		Output:  &dto.WechatLoginResponse{},
+	})
+
+	Register(router, doc, basePath, "POST", authBasePath+"/miniapp-login", handlers.ClientAuth.MiniappLogin, RouteSpec{
+		Summary: "小程序登录",
+		Tags:    []string{"个人客户 - 认证"},
+		Auth:    false,
+		Input:   &dto.MiniappLoginRequest{},
+		Output:  &dto.WechatLoginResponse{},
+	})
+
+	Register(router, doc, basePath, "POST", authBasePath+"/send-code", handlers.ClientAuth.SendCode, RouteSpec{
 		Summary: "发送验证码",
-		Description: "向指定手机号发送登录验证码",
 		Tags:    []string{"个人客户 - 认证"},
 		Auth:    false,
-		Input:       &apphandler.SendCodeRequest{},
-		Output:      nil,
+		Input:   &dto.ClientSendCodeRequest{},
+		Output:  &dto.ClientSendCodeResponse{},
 	})
 
-	// 登录
-	Register(publicGroup, doc, basePath, "POST", "/login", handlers.PersonalCustomer.Login, RouteSpec{
-		Summary:     "手机号登录",
-		Description: "使用手机号和验证码登录",
+	// === 需要认证的 auth 路由 ===
+	authProtectedGroup := router.Group(authBasePath)
+	authProtectedGroup.Use(personalAuthMiddleware.Authenticate())
+
+	Register(authProtectedGroup, doc, basePath+authBasePath, "POST", "/bind-phone", handlers.ClientAuth.BindPhone, RouteSpec{
+		Summary: "绑定手机号",
 		Tags:    []string{"个人客户 - 认证"},
-		Auth:        false,
-		Input:       &apphandler.LoginRequest{},
-		Output:      &apphandler.LoginResponse{},
+		Auth:    true,
+		Input:   &dto.BindPhoneRequest{},
+		Output:  &dto.BindPhoneResponse{},
 	})
 
-	// 微信 OAuth 登录（公开）
-	Register(publicGroup, doc, basePath, "POST", "/wechat/auth", handlers.PersonalCustomer.WechatOAuthLogin, RouteSpec{
-		Summary:     "微信授权登录",
-		Description: "使用微信授权码登录，自动创建或关联用户",
+	Register(authProtectedGroup, doc, basePath+authBasePath, "POST", "/change-phone", handlers.ClientAuth.ChangePhone, RouteSpec{
+		Summary: "更换手机号",
 		Tags:    []string{"个人客户 - 认证"},
-		Auth:        false,
-		Input:       &dto.WechatOAuthRequest{},
-		Output:      &dto.WechatOAuthResponse{},
+		Auth:    true,
+		Input:   &dto.ChangePhoneRequest{},
+		Output:  &dto.ChangePhoneResponse{},
+	})
+
+	Register(authProtectedGroup, doc, basePath+authBasePath, "POST", "/logout", handlers.ClientAuth.Logout, RouteSpec{
+		Summary: "退出登录",
+		Tags:    []string{"个人客户 - 认证"},
+		Auth:    true,
+		Input:   nil,
+		Output:  &dto.LogoutResponse{},
 	})
 
 	// 需要认证的路由
 	authGroup := router.Group("")
 	authGroup.Use(personalAuthMiddleware.Authenticate())
 
-	// 绑定微信
-	Register(authGroup, doc, basePath, "POST", "/bind-wechat", handlers.PersonalCustomer.BindWechat, RouteSpec{
-		Summary:     "绑定微信",
-		Description: "绑定微信账号到当前个人客户",
-		Tags:        []string{"个人客户 - 账户"},
-		Auth:        true,
-		Input:       &dto.WechatOAuthRequest{},
-		Output:      nil,
-	})
-
 	// 获取个人资料
 	Register(authGroup, doc, basePath, "GET", "/profile", handlers.PersonalCustomer.GetProfile, RouteSpec{
 		Summary:     "获取个人资料",
@@ -79,4 +104,164 @@ func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator,
 		Input:       &apphandler.UpdateProfileRequest{},
 		Output:      nil,
 	})
+
+	Register(authGroup, doc, basePath, "GET", "/asset/info", handlers.ClientAsset.GetAssetInfo, RouteSpec{
+		Summary: "资产信息",
+		Tags:    []string{"个人客户 - 资产"},
+		Auth:    true,
+		Input:   &dto.AssetInfoRequest{},
+		Output:  &dto.AssetInfoResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/asset/packages", handlers.ClientAsset.GetAvailablePackages, RouteSpec{
+		Summary: "资产可购套餐列表",
+		Tags:    []string{"个人客户 - 资产"},
+		Auth:    true,
+		Input:   &dto.AssetPackageListRequest{},
+		Output:  &dto.AssetPackageListResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/asset/package-history", handlers.ClientAsset.GetPackageHistory, RouteSpec{
+		Summary: "资产套餐历史",
+		Tags:    []string{"个人客户 - 资产"},
+		Auth:    true,
+		Input:   &dto.AssetPackageHistoryRequest{},
+		Output:  &dto.AssetPackageHistoryResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/asset/refresh", handlers.ClientAsset.RefreshAsset, RouteSpec{
+		Summary: "资产刷新",
+		Tags:    []string{"个人客户 - 资产"},
+		Auth:    true,
+		Input:   &dto.AssetRefreshRequest{},
+		Output:  &dto.AssetRefreshResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/wallet/detail", handlers.ClientWallet.GetWalletDetail, RouteSpec{
+		Summary: "钱包详情",
+		Tags:    []string{"个人客户 - 钱包"},
+		Auth:    true,
+		Input:   &dto.WalletDetailRequest{},
+		Output:  &dto.WalletDetailResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/wallet/transactions", handlers.ClientWallet.GetWalletTransactions, RouteSpec{
+		Summary: "钱包流水列表",
+		Tags:    []string{"个人客户 - 钱包"},
+		Auth:    true,
+		Input:   &dto.WalletTransactionListRequest{},
+		Output:  &dto.WalletTransactionListResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/wallet/recharge-check", handlers.ClientWallet.GetRechargeCheck, RouteSpec{
+		Summary: "充值前校验",
+		Tags:    []string{"个人客户 - 钱包"},
+		Auth:    true,
+		Input:   &dto.ClientRechargeCheckRequest{},
+		Output:  &dto.ClientRechargeCheckResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/wallet/recharge", handlers.ClientWallet.CreateRecharge, RouteSpec{
+		Summary: "创建充值订单",
+		Tags:    []string{"个人客户 - 钱包"},
+		Auth:    true,
+		Input:   &dto.ClientCreateRechargeRequest{},
+		Output:  &dto.ClientRechargeResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/wallet/recharges", handlers.ClientWallet.GetRechargeList, RouteSpec{
+		Summary: "充值记录列表",
+		Tags:    []string{"个人客户 - 钱包"},
+		Auth:    true,
+		Input:   &dto.ClientRechargeListRequest{},
+		Output:  &dto.ClientRechargeListResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/orders/create", handlers.ClientOrder.CreateOrder, RouteSpec{
+		Summary: "创建订单",
+		Tags:    []string{"个人客户 - 订单"},
+		Auth:    true,
+		Input:   &dto.ClientCreateOrderRequest{},
+		Output:  &dto.ClientCreateOrderResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/orders", handlers.ClientOrder.ListOrders, RouteSpec{
+		Summary: "订单列表",
+		Tags:    []string{"个人客户 - 订单"},
+		Auth:    true,
+		Input:   &dto.ClientOrderListRequest{},
+		Output:  &dto.ClientOrderListResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/orders/:id", handlers.ClientOrder.GetOrderDetail, RouteSpec{
+		Summary: "订单详情",
+		Tags:    []string{"个人客户 - 订单"},
+		Auth:    true,
+		Input:   &dto.IDReq{},
+		Output:  &dto.ClientOrderDetailResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/exchange/pending", handlers.ClientExchange.GetPending, RouteSpec{
+		Summary: "查询待处理换货单",
+		Tags:    []string{"个人客户 - 换货"},
+		Auth:    true,
+		Input:   &dto.ClientExchangePendingRequest{},
+		Output:  &dto.ClientExchangePendingResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/exchange/:id/shipping-info", handlers.ClientExchange.SubmitShippingInfo, RouteSpec{
+		Summary: "提交收货信息",
+		Tags:    []string{"个人客户 - 换货"},
+		Auth:    true,
+		Input:   &dto.ClientShippingInfoParams{},
+		Output:  nil,
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/realname/link", handlers.ClientRealname.GetRealnameLink, RouteSpec{
+		Summary: "获取实名认证链接",
+		Tags:    []string{"个人客户 - 实名"},
+		Auth:    true,
+		Input:   &dto.RealnimeLinkRequest{},
+		Output:  &dto.RealnimeLinkResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "GET", "/device/cards", handlers.ClientDevice.GetDeviceCards, RouteSpec{
+		Summary: "获取设备卡列表",
+		Tags:    []string{"个人客户 - 设备"},
+		Auth:    true,
+		Input:   &dto.DeviceCardListRequest{},
+		Output:  &dto.DeviceCardListResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/device/reboot", handlers.ClientDevice.RebootDevice, RouteSpec{
+		Summary: "设备重启",
+		Tags:    []string{"个人客户 - 设备"},
+		Auth:    true,
+		Input:   &dto.DeviceRebootRequest{},
+		Output:  &dto.DeviceOperationResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/device/factory-reset", handlers.ClientDevice.FactoryResetDevice, RouteSpec{
+		Summary: "恢复出厂设置",
+		Tags:    []string{"个人客户 - 设备"},
+		Auth:    true,
+		Input:   &dto.DeviceFactoryResetRequest{},
+		Output:  &dto.DeviceOperationResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/device/wifi", handlers.ClientDevice.SetWiFi, RouteSpec{
+		Summary: "设备WiFi配置",
+		Tags:    []string{"个人客户 - 设备"},
+		Auth:    true,
+		Input:   &dto.DeviceWifiRequest{},
+		Output:  &dto.DeviceOperationResponse{},
+	})
+
+	Register(authGroup, doc, basePath, "POST", "/device/switch-card", handlers.ClientDevice.SwitchCard, RouteSpec{
+		Summary: "设备切卡",
+		Tags:    []string{"个人客户 - 设备"},
+		Auth:    true,
+		Input:   &dto.DeviceSwitchCardRequest{},
+		Output:  &dto.DeviceSwitchCardResponse{},
+	})
 }

internal/routes/recharge.go

@@ -1,44 +1 @@
 package routes
-
-import (
-	"github.com/gofiber/fiber/v2"
-
-	"github.com/break/junhong_cmp_fiber/internal/handler/h5"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/pkg/openapi"
-)
-
-// registerH5RechargeRoutes 注册H5充值路由
-func registerH5RechargeRoutes(router fiber.Router, handler *h5.RechargeHandler, doc *openapi.Generator, basePath string) {
-	Register(router, doc, basePath, "POST", "/wallets/recharge", handler.Create, RouteSpec{
-		Summary: "创建充值订单",
-		Tags:    []string{"H5 充值"},
-		Input:   new(dto.CreateRechargeRequest),
-		Output:  new(dto.RechargeResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "GET", "/wallets/recharge-check", handler.RechargeCheck, RouteSpec{
-		Summary: "充值预检",
-		Tags:    []string{"H5 充值"},
-		Input:   new(dto.RechargeCheckRequest),
-		Output:  new(dto.RechargeCheckResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "GET", "/wallets/recharges", handler.List, RouteSpec{
-		Summary: "获取充值订单列表",
-		Tags:    []string{"H5 充值"},
-		Input:   new(dto.RechargeListRequest),
-		Output:  new(dto.RechargeListResponse),
-		Auth:    true,
-	})
-
-	Register(router, doc, basePath, "GET", "/wallets/recharges/:id", handler.Get, RouteSpec{
-		Summary: "获取充值订单详情",
-		Tags:    []string{"H5 充值"},
-		Input:   new(dto.GetRechargeRequest),
-		Output:  new(dto.RechargeResponse),
-		Auth:    true,
-	})
-}

internal/routes/routes.go

@@ -28,15 +28,11 @@ func RegisterRoutesWithDoc(app *fiber.App, handlers *bootstrap.Handlers, middlew
 	adminGroup := app.Group("/api/admin")
 	RegisterAdminRoutes(adminGroup, handlers, middlewares, doc, "/api/admin")
 
-	// 4. H5 域 (挂载在 /api/h5)
-	h5Group := app.Group("/api/h5")
-	RegisterH5Routes(h5Group, handlers, middlewares, doc, "/api/h5")
-
-	// 5. 个人客户路由 (挂载在 /api/c/v1)
+	// 4. 个人客户路由 (挂载在 /api/c/v1)
 	personalGroup := app.Group("/api/c/v1")
 	RegisterPersonalCustomerRoutes(personalGroup, doc, "/api/c/v1", handlers, middlewares.PersonalAuth)
 
-	// 6. 支付回调路由 (挂载在 /api/callback，无需认证)
+	// 5. 支付回调路由 (挂载在 /api/callback，无需认证)
 	if handlers.PaymentCallback != nil {
 		callbackGroup := app.Group("/api/callback")
 		registerPaymentCallbackRoutes(callbackGroup, handlers.PaymentCallback, doc, "/api/callback")

internal/routes/wechat_config.go

@@ -58,7 +58,7 @@ func registerWechatConfigRoutes(router fiber.Router, handler *admin.WechatConfig
 	Register(group, doc, groupPath, "PUT", "/:id", handler.Update, RouteSpec{
 		Summary: "更新支付配置",
 		Tags:    []string{"微信支付配置管理"},
-		Input:   new(dto.UpdateWechatConfigRequest),
+		Input:   new(dto.UpdateWechatConfigParams),
 		Output:  new(dto.WechatConfigResponse),
 		Auth:    true,
 	})

internal/service/asset/lifecycle_service.go

@@ -0,0 +1,88 @@
+package asset
+
+import (
+	"context"
+	stderrors "errors"
+
+	"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/break/junhong_cmp_fiber/pkg/errors"
+	"gorm.io/gorm"
+)
+
+var deactivatableAssetStatuses = []int{constants.AssetStatusInStock, constants.AssetStatusSold}
+
+// LifecycleService 资产生命周期服务
+type LifecycleService struct {
+	db           *gorm.DB
+	iotCardStore *postgres.IotCardStore
+	deviceStore  *postgres.DeviceStore
+}
+
+// NewLifecycleService 创建资产生命周期服务
+func NewLifecycleService(db *gorm.DB, iotCardStore *postgres.IotCardStore, deviceStore *postgres.DeviceStore) *LifecycleService {
+	return &LifecycleService{
+		db:           db,
+		iotCardStore: iotCardStore,
+		deviceStore:  deviceStore,
+	}
+}
+
+// DeactivateIotCard 手动停用 IoT 卡
+func (s *LifecycleService) DeactivateIotCard(ctx context.Context, id uint) error {
+	card, err := s.iotCardStore.GetByID(ctx, id)
+	if err != nil {
+		if stderrors.Is(err, gorm.ErrRecordNotFound) {
+			return errors.New(errors.CodeIotCardNotFound)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询IoT卡失败")
+	}
+
+	if !canDeactivateAsset(card.AssetStatus) {
+		return errors.New(errors.CodeForbidden, "当前状态不允许停用")
+	}
+
+	result := s.db.WithContext(ctx).Model(&model.IotCard{}).
+		Where("id = ? AND asset_status IN ?", id, deactivatableAssetStatuses).
+		Update("asset_status", constants.AssetStatusDeactivated)
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "停用IoT卡失败")
+	}
+	if result.RowsAffected == 0 {
+		return errors.New(errors.CodeConflict, "状态已变更，请刷新后重试")
+	}
+
+	return nil
+}
+
+// DeactivateDevice 手动停用设备
+func (s *LifecycleService) DeactivateDevice(ctx context.Context, id uint) error {
+	device, err := s.deviceStore.GetByID(ctx, id)
+	if err != nil {
+		if stderrors.Is(err, gorm.ErrRecordNotFound) {
+			return errors.New(errors.CodeNotFound, "设备不存在")
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询设备失败")
+	}
+
+	if !canDeactivateAsset(device.AssetStatus) {
+		return errors.New(errors.CodeForbidden, "当前状态不允许停用")
+	}
+
+	result := s.db.WithContext(ctx).Model(&model.Device{}).
+		Where("id = ? AND asset_status IN ?", id, deactivatableAssetStatuses).
+		Update("asset_status", constants.AssetStatusDeactivated)
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "停用设备失败")
+	}
+	if result.RowsAffected == 0 {
+		return errors.New(errors.CodeConflict, "状态已变更，请刷新后重试")
+	}
+
+	return nil
+}
+
+func canDeactivateAsset(assetStatus int) bool {
+	return assetStatus == constants.AssetStatusInStock || assetStatus == constants.AssetStatusSold
+}

internal/service/carrier/service.go

@@ -41,6 +41,12 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateCarrierRequest) (*d
 		Description: req.Description,
 		Status:      constants.StatusEnabled,
 	}
+	if req.RealnameLinkType != nil {
+		carrier.RealnameLinkType = *req.RealnameLinkType
+	}
+	if req.RealnameLinkTemplate != nil {
+		carrier.RealnameLinkTemplate = *req.RealnameLinkTemplate
+	}
 	carrier.Creator = currentUserID
 
 	if err := s.carrierStore.Create(ctx, carrier); err != nil {
@@ -81,6 +87,15 @@ func (s *Service) Update(ctx context.Context, id uint, req *dto.UpdateCarrierReq
 	if req.Description != nil {
 		carrier.Description = *req.Description
 	}
+	if req.RealnameLinkType != nil {
+		carrier.RealnameLinkType = *req.RealnameLinkType
+	}
+	if req.RealnameLinkTemplate != nil {
+		carrier.RealnameLinkTemplate = *req.RealnameLinkTemplate
+	}
+	if carrier.RealnameLinkType == "template" && carrier.RealnameLinkTemplate == "" {
+		return nil, errors.New(errors.CodeInvalidParam, "模板URL类型必须提供实名链接模板")
+	}
 	carrier.Updater = currentUserID
 
 	if err := s.carrierStore.Update(ctx, carrier); err != nil {
@@ -174,6 +189,8 @@ func (s *Service) toResponse(c *model.Carrier) *dto.CarrierResponse {
 		CarrierName:          c.CarrierName,
 		CarrierType:          c.CarrierType,
 		Description:          c.Description,
+		RealnameLinkType:     c.RealnameLinkType,
+		RealnameLinkTemplate: c.RealnameLinkTemplate,
 		Status:               c.Status,
 		CreatedAt:            c.CreatedAt.Format(time.RFC3339),
 		UpdatedAt:            c.UpdatedAt.Format(time.RFC3339),

internal/service/client_auth/service.go

@@ -0,0 +1,761 @@
+// Package client_auth 提供 C 端认证业务逻辑
+// 包含资产验证、微信登录、手机号绑定与退出登录等能力
+package client_auth
+
+import (
+	"context"
+	"regexp"
+	"time"
+
+	"github.com/ArtisanCloud/PowerWeChat/v3/src/kernel"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/internal/service/verification"
+	wechatConfigSvc "github.com/break/junhong_cmp_fiber/internal/service/wechat_config"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/auth"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/wechat"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/redis/go-redis/v9"
+	"github.com/spf13/viper"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+const (
+	assetTypeIotCard = "iot_card"
+	assetTypeDevice  = "device"
+
+	appTypeOfficialAccount = "official_account"
+	appTypeMiniapp         = "miniapp"
+
+	assetTokenExpireSeconds = 300
+)
+
+var identifierRegex = regexp.MustCompile(`^[A-Za-z0-9-]{1,50}$`)
+
+// Service C 端认证服务
+type Service struct {
+	db                  *gorm.DB
+	openidStore         *postgres.PersonalCustomerOpenIDStore
+	customerStore       *postgres.PersonalCustomerStore
+	deviceBindStore     *postgres.PersonalCustomerDeviceStore
+	phoneStore          *postgres.PersonalCustomerPhoneStore
+	iotCardStore        *postgres.IotCardStore
+	deviceStore         *postgres.DeviceStore
+	wechatConfigService *wechatConfigSvc.Service
+	verificationService *verification.Service
+	jwtManager          *auth.JWTManager
+	redis               *redis.Client
+	logger              *zap.Logger
+	wechatCache         kernel.CacheInterface
+}
+
+// New 创建 C 端认证服务实例
+func New(
+	db *gorm.DB,
+	openidStore *postgres.PersonalCustomerOpenIDStore,
+	customerStore *postgres.PersonalCustomerStore,
+	deviceBindStore *postgres.PersonalCustomerDeviceStore,
+	phoneStore *postgres.PersonalCustomerPhoneStore,
+	iotCardStore *postgres.IotCardStore,
+	deviceStore *postgres.DeviceStore,
+	wechatConfigService *wechatConfigSvc.Service,
+	verificationService *verification.Service,
+	jwtManager *auth.JWTManager,
+	redisClient *redis.Client,
+	logger *zap.Logger,
+) *Service {
+	return &Service{
+		db:                  db,
+		openidStore:         openidStore,
+		customerStore:       customerStore,
+		deviceBindStore:     deviceBindStore,
+		phoneStore:          phoneStore,
+		iotCardStore:        iotCardStore,
+		deviceStore:         deviceStore,
+		wechatConfigService: wechatConfigService,
+		verificationService: verificationService,
+		jwtManager:          jwtManager,
+		redis:               redisClient,
+		logger:              logger,
+		wechatCache:         wechat.NewRedisCache(redisClient),
+	}
+}
+
+type assetTokenClaims struct {
+	AssetType string `json:"asset_type"`
+	AssetID   uint   `json:"asset_id"`
+	jwt.RegisteredClaims
+}
+
+// VerifyAsset A1 验证资产并签发短期资产令牌
+func (s *Service) VerifyAsset(ctx context.Context, req *dto.VerifyAssetRequest, clientIP string) (*dto.VerifyAssetResponse, error) {
+	if req == nil || !identifierRegex.MatchString(req.Identifier) {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	if err := s.checkAssetVerifyRateLimit(ctx, clientIP); err != nil {
+		return nil, err
+	}
+
+	assetType, assetID, err := s.resolveAsset(ctx, req.Identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	assetToken, err := s.signAssetToken(assetType, assetID)
+	if err != nil {
+		s.logger.Error("签发资产令牌失败", zap.Error(err))
+		return nil, errors.Wrap(errors.CodeInternalError, err, "签发资产令牌失败")
+	}
+
+	return &dto.VerifyAssetResponse{
+		AssetToken: assetToken,
+		ExpiresIn:  assetTokenExpireSeconds,
+	}, nil
+}
+
+// WechatLogin A2 公众号登录
+func (s *Service) WechatLogin(ctx context.Context, req *dto.WechatLoginRequest, clientIP string) (*dto.WechatLoginResponse, error) {
+	if req == nil {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	assetClaims, err := s.verifyAssetToken(req.AssetToken)
+	if err != nil {
+		return nil, err
+	}
+
+	wechatConfig, err := s.wechatConfigService.GetActiveConfig(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if wechatConfig == nil {
+		return nil, errors.New(errors.CodeWechatConfigUnavailable)
+	}
+
+	oaApp, err := wechat.NewOfficialAccountAppFromConfig(wechatConfig, s.wechatCache, s.logger)
+	if err != nil {
+		s.logger.Error("创建公众号实例失败", zap.Error(err))
+		return nil, errors.Wrap(errors.CodeWechatConfigUnavailable, err, "微信公众号配置不可用")
+	}
+	oaService := wechat.NewOfficialAccountService(oaApp, s.logger)
+
+	userInfo, err := oaService.GetUserInfoDetailed(ctx, req.Code)
+	if err != nil {
+		return nil, err
+	}
+
+	customerID, isNewUser, err := s.loginByOpenID(
+		ctx,
+		assetClaims.AssetType,
+		assetClaims.AssetID,
+		wechatConfig.OaAppID,
+		userInfo.OpenID,
+		userInfo.UnionID,
+		userInfo.Nickname,
+		userInfo.Avatar,
+		appTypeOfficialAccount,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	token, needBindPhone, err := s.issueLoginToken(ctx, customerID)
+	if err != nil {
+		return nil, err
+	}
+
+	s.logger.Info("公众号登录成功",
+		zap.Uint("customer_id", customerID),
+		zap.String("client_ip", clientIP),
+	)
+
+	return &dto.WechatLoginResponse{
+		Token:         token,
+		NeedBindPhone: needBindPhone,
+		IsNewUser:     isNewUser,
+	}, nil
+}
+
+// MiniappLogin A3 小程序登录
+func (s *Service) MiniappLogin(ctx context.Context, req *dto.MiniappLoginRequest, clientIP string) (*dto.WechatLoginResponse, error) {
+	if req == nil {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	assetClaims, err := s.verifyAssetToken(req.AssetToken)
+	if err != nil {
+		return nil, err
+	}
+
+	wechatConfig, err := s.wechatConfigService.GetActiveConfig(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if wechatConfig == nil {
+		return nil, errors.New(errors.CodeWechatConfigUnavailable)
+	}
+
+	miniService, err := wechat.NewMiniAppServiceFromConfig(wechatConfig, s.logger)
+	if err != nil {
+		s.logger.Error("创建小程序服务失败", zap.Error(err))
+		return nil, errors.Wrap(errors.CodeWechatConfigUnavailable, err, "小程序配置不可用")
+	}
+
+	openID, unionID, _, err := miniService.Code2Session(ctx, req.Code)
+	if err != nil {
+		return nil, err
+	}
+
+	customerID, isNewUser, err := s.loginByOpenID(
+		ctx,
+		assetClaims.AssetType,
+		assetClaims.AssetID,
+		wechatConfig.MiniappAppID,
+		openID,
+		unionID,
+		req.Nickname,
+		req.AvatarURL,
+		appTypeMiniapp,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	token, needBindPhone, err := s.issueLoginToken(ctx, customerID)
+	if err != nil {
+		return nil, err
+	}
+
+	s.logger.Info("小程序登录成功",
+		zap.Uint("customer_id", customerID),
+		zap.String("client_ip", clientIP),
+	)
+
+	return &dto.WechatLoginResponse{
+		Token:         token,
+		NeedBindPhone: needBindPhone,
+		IsNewUser:     isNewUser,
+	}, nil
+}
+
+// SendCode A4 发送验证码
+func (s *Service) SendCode(ctx context.Context, req *dto.ClientSendCodeRequest, clientIP string) (*dto.ClientSendCodeResponse, error) {
+	if req == nil || req.Phone == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	if err := s.checkSendCodeRateLimit(ctx, req.Phone, clientIP); err != nil {
+		return nil, err
+	}
+
+	if err := s.verificationService.SendCode(ctx, req.Phone); err != nil {
+		s.logger.Error("发送验证码失败", zap.String("phone", req.Phone), zap.Error(err))
+		return nil, errors.Wrap(errors.CodeSmsSendFailed, err, "发送验证码失败")
+	}
+
+	cooldownKey := constants.RedisClientSendCodePhoneLimitKey(req.Phone)
+	if err := s.redis.Set(ctx, cooldownKey, "1", 60*time.Second).Err(); err != nil {
+		s.logger.Error("设置验证码冷却键失败", zap.String("phone", req.Phone), zap.Error(err))
+		return nil, errors.Wrap(errors.CodeRedisError, err, "设置验证码冷却失败")
+	}
+
+	return &dto.ClientSendCodeResponse{CooldownSeconds: 60}, nil
+}
+
+// BindPhone A5 绑定手机号
+func (s *Service) BindPhone(ctx context.Context, customerID uint, req *dto.BindPhoneRequest) (*dto.BindPhoneResponse, error) {
+	if req == nil {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	if _, err := s.phoneStore.GetPrimaryPhone(ctx, customerID); err == nil {
+		return nil, errors.New(errors.CodeAlreadyBoundPhone)
+	} else if err != gorm.ErrRecordNotFound {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询主手机号失败")
+	}
+
+	if err := s.verificationService.VerifyCode(ctx, req.Phone, req.Code); err != nil {
+		return nil, errors.Wrap(errors.CodeVerificationCodeInvalid, err)
+	}
+
+	if existed, err := s.phoneStore.GetByPhone(ctx, req.Phone); err == nil {
+		if existed.CustomerID != customerID {
+			return nil, errors.New(errors.CodePhoneAlreadyBound)
+		}
+		return nil, errors.New(errors.CodeAlreadyBoundPhone)
+	} else if err != gorm.ErrRecordNotFound {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询手机号绑定关系失败")
+	}
+
+	record := &model.PersonalCustomerPhone{
+		CustomerID: customerID,
+		Phone:      req.Phone,
+		IsPrimary:  true,
+		Status:     1,
+	}
+	if err := s.phoneStore.Create(ctx, record); err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "创建手机号绑定记录失败")
+	}
+
+	return &dto.BindPhoneResponse{
+		Phone:   req.Phone,
+		BoundAt: record.VerifiedAt.Format("2006-01-02 15:04:05"),
+	}, nil
+}
+
+// ChangePhone A6 换绑手机号
+func (s *Service) ChangePhone(ctx context.Context, customerID uint, req *dto.ChangePhoneRequest) (*dto.ChangePhoneResponse, error) {
+	if req == nil {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	primary, err := s.phoneStore.GetPrimaryPhone(ctx, customerID)
+	if err == gorm.ErrRecordNotFound {
+		return nil, errors.New(errors.CodeOldPhoneMismatch)
+	}
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询主手机号失败")
+	}
+
+	if primary.Phone != req.OldPhone {
+		return nil, errors.New(errors.CodeOldPhoneMismatch)
+	}
+
+	if err := s.verificationService.VerifyCode(ctx, req.OldPhone, req.OldCode); err != nil {
+		return nil, errors.Wrap(errors.CodeVerificationCodeInvalid, err)
+	}
+	if err := s.verificationService.VerifyCode(ctx, req.NewPhone, req.NewCode); err != nil {
+		return nil, errors.Wrap(errors.CodeVerificationCodeInvalid, err)
+	}
+
+	if existed, err := s.phoneStore.GetByPhone(ctx, req.NewPhone); err == nil && existed.CustomerID != customerID {
+		return nil, errors.New(errors.CodePhoneAlreadyBound)
+	} else if err != nil && err != gorm.ErrRecordNotFound {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询新手机号绑定关系失败")
+	}
+
+	now := time.Now()
+	if err := s.db.WithContext(ctx).Model(&model.PersonalCustomerPhone{}).
+		Where("id = ? AND customer_id = ?", primary.ID, customerID).
+		Updates(map[string]any{
+			"phone":       req.NewPhone,
+			"verified_at": now,
+			"updated_at":  now,
+		}).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "更新手机号失败")
+	}
+
+	return &dto.ChangePhoneResponse{
+		Phone:     req.NewPhone,
+		ChangedAt: now.Format("2006-01-02 15:04:05"),
+	}, nil
+}
+
+// Logout A7 退出登录
+func (s *Service) Logout(ctx context.Context, customerID uint) (*dto.LogoutResponse, error) {
+	redisKey := constants.RedisPersonalCustomerTokenKey(customerID)
+	if err := s.redis.Del(ctx, redisKey).Err(); err != nil {
+		return nil, errors.Wrap(errors.CodeRedisError, err, "退出登录失败")
+	}
+
+	return &dto.LogoutResponse{Success: true}, nil
+}
+
+func (s *Service) checkAssetVerifyRateLimit(ctx context.Context, clientIP string) error {
+	if clientIP == "" {
+		return nil
+	}
+
+	key := constants.RedisClientAuthRateLimitIPKey(clientIP)
+	count, err := s.redis.Incr(ctx, key).Result()
+	if err != nil {
+		return errors.Wrap(errors.CodeRedisError, err, "校验资产限流失败")
+	}
+	if count == 1 {
+		if expErr := s.redis.Expire(ctx, key, 60*time.Second).Err(); expErr != nil {
+			return errors.Wrap(errors.CodeRedisError, expErr, "设置资产限流过期时间失败")
+		}
+	}
+	if count > 30 {
+		return errors.New(errors.CodeTooManyRequests)
+	}
+	return nil
+}
+
+func (s *Service) resolveAsset(ctx context.Context, identifier string) (string, uint, error) {
+	var card model.IotCard
+	if err := s.db.WithContext(ctx).
+		Where("iccid = ?", identifier).
+		First(&card).Error; err == nil {
+		return assetTypeIotCard, card.ID, nil
+	} else if err != gorm.ErrRecordNotFound {
+		return "", 0, errors.Wrap(errors.CodeInternalError, err, "查询卡资产失败")
+	}
+
+	var device model.Device
+	if err := s.db.WithContext(ctx).
+		Where("virtual_no = ? OR imei = ?", identifier, identifier).
+		First(&device).Error; err == nil {
+		return assetTypeDevice, device.ID, nil
+	} else if err != gorm.ErrRecordNotFound {
+		return "", 0, errors.Wrap(errors.CodeInternalError, err, "查询设备资产失败")
+	}
+
+	return "", 0, errors.New(errors.CodeAssetNotFound)
+}
+
+func (s *Service) signAssetToken(assetType string, assetID uint) (string, error) {
+	now := time.Now()
+	claims := &assetTokenClaims{
+		AssetType: assetType,
+		AssetID:   assetID,
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(now.Add(5 * time.Minute)),
+			IssuedAt:  jwt.NewNumericDate(now),
+			NotBefore: jwt.NewNumericDate(now),
+		},
+	}
+
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	return token.SignedString([]byte(viper.GetString("jwt.secret_key") + ":asset"))
+}
+
+func (s *Service) verifyAssetToken(assetToken string) (*assetTokenClaims, error) {
+	if assetToken == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	parsed, err := jwt.ParseWithClaims(assetToken, &assetTokenClaims{}, func(token *jwt.Token) (interface{}, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, errors.New(errors.CodeInvalidToken)
+		}
+		return []byte(viper.GetString("jwt.secret_key") + ":asset"), nil
+	})
+	if err != nil {
+		return nil, errors.New(errors.CodeInvalidToken)
+	}
+
+	claims, ok := parsed.Claims.(*assetTokenClaims)
+	if !ok || !parsed.Valid || claims.AssetID == 0 || claims.AssetType == "" {
+		return nil, errors.New(errors.CodeInvalidToken)
+	}
+
+	return claims, nil
+}
+
+func (s *Service) loginByOpenID(
+	ctx context.Context,
+	assetType string,
+	assetID uint,
+	appID string,
+	openID string,
+	unionID string,
+	nickname string,
+	avatar string,
+	appType string,
+) (uint, bool, error) {
+	var (
+		customerID uint
+		isNewUser  bool
+	)
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		cid, created, findErr := s.findOrCreateCustomer(ctx, tx, appID, openID, unionID, nickname, avatar, appType)
+		if findErr != nil {
+			return findErr
+		}
+		if bindErr := s.bindAsset(ctx, tx, cid, assetType, assetID); bindErr != nil {
+			return bindErr
+		}
+
+		customerID = cid
+		isNewUser = created
+		return nil
+	})
+	if err != nil {
+		return 0, false, err
+	}
+
+	return customerID, isNewUser, nil
+}
+
+// findOrCreateCustomer 根据 OpenID/UnionID 查找或创建客户
+func (s *Service) findOrCreateCustomer(
+	ctx context.Context,
+	tx *gorm.DB,
+	appID string,
+	openID string,
+	unionID string,
+	nickname string,
+	avatar string,
+	appType string,
+) (uint, bool, error) {
+	openidStore := postgres.NewPersonalCustomerOpenIDStore(tx)
+	customerStore := postgres.NewPersonalCustomerStore(tx, s.redis)
+
+	if existed, err := openidStore.FindByAppIDAndOpenID(ctx, appID, openID); err == nil {
+		customer, getErr := customerStore.GetByID(ctx, existed.CustomerID)
+		if getErr != nil {
+			if getErr == gorm.ErrRecordNotFound {
+				return 0, false, errors.New(errors.CodeCustomerNotFound)
+			}
+			return 0, false, errors.Wrap(errors.CodeInternalError, getErr, "查询客户失败")
+		}
+		if customer.Status == 0 {
+			return 0, false, errors.New(errors.CodeForbidden, "账号已被禁用")
+		}
+
+		if nickname != "" && customer.Nickname != nickname {
+			customer.Nickname = nickname
+		}
+		if avatar != "" && customer.AvatarURL != avatar {
+			customer.AvatarURL = avatar
+		}
+		if saveErr := customerStore.Update(ctx, customer); saveErr != nil {
+			return 0, false, errors.Wrap(errors.CodeInternalError, saveErr, "更新客户信息失败")
+		}
+		return customer.ID, false, nil
+	} else if err != gorm.ErrRecordNotFound {
+		return 0, false, errors.Wrap(errors.CodeInternalError, err, "查询 OpenID 记录失败")
+	}
+
+	if unionID != "" {
+		if existed, err := openidStore.FindByUnionID(ctx, unionID); err == nil {
+			customer, getErr := customerStore.GetByID(ctx, existed.CustomerID)
+			if getErr != nil {
+				if getErr == gorm.ErrRecordNotFound {
+					return 0, false, errors.New(errors.CodeCustomerNotFound)
+				}
+				return 0, false, errors.Wrap(errors.CodeInternalError, getErr, "查询客户失败")
+			}
+			if customer.Status == 0 {
+				return 0, false, errors.New(errors.CodeForbidden, "账号已被禁用")
+			}
+
+			record := &model.PersonalCustomerOpenID{
+				CustomerID: customer.ID,
+				AppID:      appID,
+				OpenID:     openID,
+				UnionID:    unionID,
+				AppType:    appType,
+			}
+			if createErr := openidStore.Create(ctx, record); createErr != nil {
+				return 0, false, errors.Wrap(errors.CodeInternalError, createErr, "创建 OpenID 关联失败")
+			}
+
+			if nickname != "" && customer.Nickname != nickname {
+				customer.Nickname = nickname
+			}
+			if avatar != "" && customer.AvatarURL != avatar {
+				customer.AvatarURL = avatar
+			}
+			if saveErr := customerStore.Update(ctx, customer); saveErr != nil {
+				return 0, false, errors.Wrap(errors.CodeInternalError, saveErr, "更新客户信息失败")
+			}
+
+			return customer.ID, false, nil
+		} else if err != gorm.ErrRecordNotFound {
+			return 0, false, errors.Wrap(errors.CodeInternalError, err, "按 UnionID 查询失败")
+		}
+	}
+
+	newCustomer := &model.PersonalCustomer{
+		WxOpenID:  openID,
+		WxUnionID: unionID,
+		Nickname:  nickname,
+		AvatarURL: avatar,
+		Status:    1,
+	}
+	if err := customerStore.Create(ctx, newCustomer); err != nil {
+		return 0, false, errors.Wrap(errors.CodeInternalError, err, "创建客户失败")
+	}
+
+	record := &model.PersonalCustomerOpenID{
+		CustomerID: newCustomer.ID,
+		AppID:      appID,
+		OpenID:     openID,
+		UnionID:    unionID,
+		AppType:    appType,
+	}
+	if err := openidStore.Create(ctx, record); err != nil {
+		return 0, false, errors.Wrap(errors.CodeInternalError, err, "创建 OpenID 关联失败")
+	}
+
+	return newCustomer.ID, true, nil
+}
+
+// bindAsset 绑定客户与资产关系
+func (s *Service) bindAsset(ctx context.Context, tx *gorm.DB, customerID uint, assetType string, assetID uint) error {
+	assetKey, err := s.resolveAssetBindingKey(ctx, tx, assetType, assetID)
+	if err != nil {
+		return err
+	}
+
+	var bindCount int64
+	if err := tx.WithContext(ctx).
+		Model(&model.PersonalCustomerDevice{}).
+		Where("virtual_no = ?", assetKey).
+		Count(&bindCount).Error; err != nil {
+		return errors.Wrap(errors.CodeInternalError, err, "查询资产绑定关系失败")
+	}
+	firstEverBind := bindCount == 0
+
+	bindStore := postgres.NewPersonalCustomerDeviceStore(tx)
+	exists, err := bindStore.ExistsByCustomerAndDevice(ctx, customerID, assetKey)
+	if err != nil {
+		return errors.Wrap(errors.CodeInternalError, err, "查询客户资产绑定关系失败")
+	}
+
+	if !exists {
+		record := &model.PersonalCustomerDevice{
+			CustomerID: customerID,
+			VirtualNo:  assetKey,
+			Status:     1,
+		}
+		if err := bindStore.Create(ctx, record); err != nil {
+			return errors.Wrap(errors.CodeInternalError, err, "创建资产绑定关系失败")
+		}
+	}
+
+	if firstEverBind {
+		if err := s.markAssetAsSold(ctx, tx, assetType, assetID); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (s *Service) resolveAssetBindingKey(ctx context.Context, tx *gorm.DB, assetType string, assetID uint) (string, error) {
+	if assetType == assetTypeIotCard {
+		var card model.IotCard
+		if err := tx.WithContext(ctx).First(&card, assetID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return "", errors.New(errors.CodeAssetNotFound)
+			}
+			return "", errors.Wrap(errors.CodeInternalError, err, "查询卡资产失败")
+		}
+		return card.VirtualNo, nil
+	}
+
+	if assetType == assetTypeDevice {
+		var device model.Device
+		if err := tx.WithContext(ctx).First(&device, assetID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return "", errors.New(errors.CodeAssetNotFound)
+			}
+			return "", errors.Wrap(errors.CodeInternalError, err, "查询设备资产失败")
+		}
+		if device.VirtualNo != "" {
+			return device.VirtualNo, nil
+		}
+		return device.IMEI, nil
+	}
+
+	return "", errors.New(errors.CodeInvalidParam)
+}
+
+func (s *Service) markAssetAsSold(ctx context.Context, tx *gorm.DB, assetType string, assetID uint) error {
+	if assetType == assetTypeIotCard {
+		if err := tx.WithContext(ctx).
+			Model(&model.IotCard{}).
+			Where("id = ? AND asset_status = ?", assetID, 1).
+			Update("asset_status", 2).Error; err != nil {
+			return errors.Wrap(errors.CodeInternalError, err, "更新卡资产状态失败")
+		}
+		return nil
+	}
+
+	if assetType == assetTypeDevice {
+		if err := tx.WithContext(ctx).
+			Model(&model.Device{}).
+			Where("id = ? AND asset_status = ?", assetID, 1).
+			Update("asset_status", 2).Error; err != nil {
+			return errors.Wrap(errors.CodeInternalError, err, "更新设备资产状态失败")
+		}
+		return nil
+	}
+
+	return errors.New(errors.CodeInvalidParam)
+}
+
+func (s *Service) issueLoginToken(ctx context.Context, customerID uint) (string, bool, error) {
+	token, err := s.jwtManager.GeneratePersonalCustomerToken(customerID, "")
+	if err != nil {
+		return "", false, errors.Wrap(errors.CodeInternalError, err, "生成登录令牌失败")
+	}
+
+	claims, err := s.jwtManager.VerifyPersonalCustomerToken(token)
+	if err != nil {
+		return "", false, errors.Wrap(errors.CodeInternalError, err, "解析登录令牌失败")
+	}
+
+	ttl := time.Until(claims.ExpiresAt.Time)
+	if ttl <= 0 {
+		ttl = 24 * time.Hour
+	}
+
+	redisKey := constants.RedisPersonalCustomerTokenKey(customerID)
+	if err := s.redis.Set(ctx, redisKey, token, ttl).Err(); err != nil {
+		return "", false, errors.Wrap(errors.CodeRedisError, err, "保存登录状态失败")
+	}
+
+	needBindPhone := false
+	if viper.GetBool("client.require_phone_binding") {
+		if _, err := s.phoneStore.GetPrimaryPhone(ctx, customerID); err == gorm.ErrRecordNotFound {
+			needBindPhone = true
+		} else if err != nil {
+			return "", false, errors.Wrap(errors.CodeInternalError, err, "查询手机号绑定关系失败")
+		}
+	}
+
+	return token, needBindPhone, nil
+}
+
+func (s *Service) checkSendCodeRateLimit(ctx context.Context, phone, clientIP string) error {
+	phoneCooldownKey := constants.RedisClientSendCodePhoneLimitKey(phone)
+	exists, err := s.redis.Exists(ctx, phoneCooldownKey).Result()
+	if err != nil {
+		return errors.Wrap(errors.CodeRedisError, err, "检查手机号冷却失败")
+	}
+	if exists > 0 {
+		return errors.New(errors.CodeTooManyRequests, "验证码发送过于频繁，请稍后再试")
+	}
+
+	ipKey := constants.RedisClientSendCodeIPHourKey(clientIP)
+	ipCount, err := s.redis.Incr(ctx, ipKey).Result()
+	if err != nil {
+		return errors.Wrap(errors.CodeRedisError, err, "检查 IP 限流失败")
+	}
+	if ipCount == 1 {
+		if expErr := s.redis.Expire(ctx, ipKey, time.Hour).Err(); expErr != nil {
+			return errors.Wrap(errors.CodeRedisError, expErr, "设置 IP 限流过期时间失败")
+		}
+	}
+	if ipCount > 20 {
+		return errors.New(errors.CodeTooManyRequests)
+	}
+
+	phoneDayKey := constants.RedisClientSendCodePhoneDayKey(phone)
+	phoneDayCount, err := s.redis.Incr(ctx, phoneDayKey).Result()
+	if err != nil {
+		return errors.Wrap(errors.CodeRedisError, err, "检查手机号日限流失败")
+	}
+	if phoneDayCount == 1 {
+		nextDay := time.Now().Truncate(24 * time.Hour).Add(24 * time.Hour)
+		ttl := time.Until(nextDay)
+		if expErr := s.redis.Expire(ctx, phoneDayKey, ttl).Err(); expErr != nil {
+			return errors.Wrap(errors.CodeRedisError, expErr, "设置手机号日限流过期时间失败")
+		}
+	}
+	if phoneDayCount > 10 {
+		return errors.New(errors.CodeTooManyRequests)
+	}
+
+	return nil
+}

internal/service/client_order/service.go

@@ -0,0 +1,701 @@
+// Package client_order 提供 C 端订单下单服务。
+package client_order
+
+import (
+	"context"
+	"fmt"
+	"math/rand"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
+	"github.com/break/junhong_cmp_fiber/internal/service/purchase_validation"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/wechat"
+	"github.com/bytedance/sonic"
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+	"gorm.io/datatypes"
+	"gorm.io/gorm"
+)
+
+const (
+	clientPurchaseIdempotencyTTL = 5 * time.Minute
+	clientPurchaseLockTTL        = 10 * time.Second
+)
+
+// WechatConfigServiceInterface 微信配置服务接口。
+type WechatConfigServiceInterface interface {
+	GetActiveConfig(ctx context.Context) (*model.WechatConfig, error)
+}
+
+// ForceRechargeRequirement 强充要求。
+type ForceRechargeRequirement struct {
+	NeedForceRecharge   bool
+	ForceRechargeAmount int64
+}
+
+// Service 客户端订单服务。
+type Service struct {
+	assetService              *asset.Service
+	purchaseValidationService *purchase_validation.Service
+	orderStore                *postgres.OrderStore
+	rechargeRecordStore       *postgres.AssetRechargeStore
+	walletStore               *postgres.AssetWalletStore
+	personalDeviceStore       *postgres.PersonalCustomerDeviceStore
+	openIDStore               *postgres.PersonalCustomerOpenIDStore
+	wechatConfigService       WechatConfigServiceInterface
+	packageSeriesStore        *postgres.PackageSeriesStore
+	shopSeriesAllocationStore *postgres.ShopSeriesAllocationStore
+	redis                     *redis.Client
+	logger                    *zap.Logger
+}
+
+// New 创建客户端订单服务。
+func New(
+	assetService *asset.Service,
+	purchaseValidationService *purchase_validation.Service,
+	orderStore *postgres.OrderStore,
+	rechargeRecordStore *postgres.AssetRechargeStore,
+	walletStore *postgres.AssetWalletStore,
+	personalDeviceStore *postgres.PersonalCustomerDeviceStore,
+	openIDStore *postgres.PersonalCustomerOpenIDStore,
+	wechatConfigService WechatConfigServiceInterface,
+	packageSeriesStore *postgres.PackageSeriesStore,
+	shopSeriesAllocationStore *postgres.ShopSeriesAllocationStore,
+	redisClient *redis.Client,
+	logger *zap.Logger,
+) *Service {
+	return &Service{
+		assetService:              assetService,
+		purchaseValidationService: purchaseValidationService,
+		orderStore:                orderStore,
+		rechargeRecordStore:       rechargeRecordStore,
+		walletStore:               walletStore,
+		personalDeviceStore:       personalDeviceStore,
+		openIDStore:               openIDStore,
+		wechatConfigService:       wechatConfigService,
+		packageSeriesStore:        packageSeriesStore,
+		shopSeriesAllocationStore: shopSeriesAllocationStore,
+		redis:                     redisClient,
+		logger:                    logger,
+	}
+}
+
+// CreateOrder 创建客户端订单。
+func (s *Service) CreateOrder(ctx context.Context, customerID uint, req *dto.ClientCreateOrderRequest) (*dto.ClientCreateOrderResponse, error) {
+	if req == nil {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+	if s.redis == nil {
+		return nil, errors.New(errors.CodeInternalError, "Redis 服务未配置")
+	}
+
+	skipPermissionCtx := context.WithValue(ctx, constants.ContextKeySubordinateShopIDs, []uint{})
+	assetInfo, err := s.assetService.Resolve(skipPermissionCtx, strings.TrimSpace(req.Identifier))
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.checkAssetOwnership(skipPermissionCtx, customerID, assetInfo.VirtualNo); err != nil {
+		return nil, err
+	}
+
+	validationResult, err := s.validatePurchase(skipPermissionCtx, assetInfo, req.PackageIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	if packagesNeedRealname(validationResult.Packages) && assetInfo.RealNameStatus != 1 {
+		return nil, errors.New(errors.CodeNeedRealname)
+	}
+
+	activeConfig, appID, err := s.resolveWechatConfig(skipPermissionCtx, req.AppType)
+	if err != nil {
+		return nil, err
+	}
+
+	openID, err := s.resolveCustomerOpenID(skipPermissionCtx, customerID, appID)
+	if err != nil {
+		return nil, err
+	}
+
+	businessKey := buildClientPurchaseBusinessKey(customerID, assetInfo, req)
+	redisKey := constants.RedisClientPurchaseIdempotencyKey(businessKey)
+	lockKey := constants.RedisClientPurchaseLockKey(assetInfo.AssetType, assetInfo.AssetID)
+
+	lockAcquired, err := s.redis.SetNX(skipPermissionCtx, lockKey, time.Now().String(), clientPurchaseLockTTL).Result()
+	if err != nil {
+		s.logger.Warn("获取客户端购买分布式锁失败，继续尝试幂等标记",
+			zap.Error(err),
+			zap.String("lock_key", lockKey),
+		)
+	}
+	if err == nil && !lockAcquired {
+		return nil, errors.New(errors.CodeTooManyRequests, "订单正在创建中，请勿重复提交")
+	}
+
+	claimed, err := s.redis.SetNX(skipPermissionCtx, redisKey, "processing", clientPurchaseIdempotencyTTL).Result()
+	if err != nil {
+		if lockAcquired {
+			_ = s.redis.Del(skipPermissionCtx, lockKey).Err()
+		}
+		return nil, errors.Wrap(errors.CodeInternalError, err, "设置客户端购买幂等标记失败")
+	}
+	if !claimed {
+		if lockAcquired {
+			_ = s.redis.Del(skipPermissionCtx, lockKey).Err()
+		}
+		return nil, errors.New(errors.CodeTooManyRequests, "订单正在创建中，请勿重复提交")
+	}
+
+	created := false
+	defer func() {
+		if lockAcquired {
+			_ = s.redis.Del(skipPermissionCtx, lockKey).Err()
+		}
+		if !created {
+			_ = s.redis.Del(skipPermissionCtx, redisKey).Err()
+		}
+	}()
+
+	paymentService, err := s.newPaymentService(activeConfig, appID)
+	if err != nil {
+		return nil, err
+	}
+
+	forceRecharge := s.checkForceRechargeRequirement(skipPermissionCtx, validationResult)
+	if forceRecharge.NeedForceRecharge {
+		return s.createForceRechargeOrder(skipPermissionCtx, customerID, appID, openID, assetInfo, validationResult, activeConfig, forceRecharge, redisKey, paymentService, &created)
+	}
+
+	return s.createPackageOrder(skipPermissionCtx, customerID, appID, openID, validationResult, activeConfig, redisKey, paymentService, &created)
+}
+
+func (s *Service) checkAssetOwnership(ctx context.Context, customerID uint, virtualNo string) error {
+	owned, err := s.personalDeviceStore.ExistsByCustomerAndDevice(ctx, customerID, virtualNo)
+	if err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询资产归属失败")
+	}
+	if owned {
+		return nil
+	}
+
+	records, err := s.personalDeviceStore.GetByCustomerID(ctx, customerID)
+	if err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询资产归属失败")
+	}
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		if record.Status == constants.StatusEnabled && record.VirtualNo == virtualNo {
+			return nil
+		}
+	}
+
+	return errors.New(errors.CodeForbidden, "无权限操作该资产或资源不存在")
+}
+
+func (s *Service) validatePurchase(ctx context.Context, assetInfo *dto.AssetResolveResponse, packageIDs []uint) (*purchase_validation.PurchaseValidationResult, error) {
+	switch assetInfo.AssetType {
+	case "card":
+		return s.purchaseValidationService.ValidateCardPurchase(ctx, assetInfo.AssetID, packageIDs)
+	case constants.ResourceTypeDevice:
+		return s.purchaseValidationService.ValidateDevicePurchase(ctx, assetInfo.AssetID, packageIDs)
+	default:
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func (s *Service) resolveWechatConfig(ctx context.Context, appType string) (*model.WechatConfig, string, error) {
+	activeConfig, err := s.wechatConfigService.GetActiveConfig(ctx)
+	if err != nil {
+		return nil, "", errors.Wrap(errors.CodeDatabaseError, err, "查询微信配置失败")
+	}
+	if activeConfig == nil {
+		return nil, "", errors.New(errors.CodeWechatPayFailed, "未找到生效的微信支付配置")
+	}
+
+	switch appType {
+	case "official_account":
+		if activeConfig.OaAppID == "" {
+			return nil, "", errors.New(errors.CodeWechatPayFailed, "公众号支付配置不完整")
+		}
+		return activeConfig, activeConfig.OaAppID, nil
+	case "miniapp":
+		if activeConfig.MiniappAppID == "" {
+			return nil, "", errors.New(errors.CodeWechatPayFailed, "小程序支付配置不完整")
+		}
+		return activeConfig, activeConfig.MiniappAppID, nil
+	default:
+		return nil, "", errors.New(errors.CodeInvalidParam)
+	}
+}
+
+func (s *Service) resolveCustomerOpenID(ctx context.Context, customerID uint, appID string) (string, error) {
+	records, err := s.openIDStore.ListByCustomerID(ctx, customerID)
+	if err != nil {
+		return "", errors.Wrap(errors.CodeDatabaseError, err, "查询微信授权信息失败")
+	}
+
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+		if record.AppID == appID && strings.TrimSpace(record.OpenID) != "" {
+			return record.OpenID, nil
+		}
+	}
+
+	return "", errors.New(errors.CodeNotFound, "未找到当前应用的微信授权信息")
+}
+
+func (s *Service) newPaymentService(wechatConfig *model.WechatConfig, appID string) (*wechat.PaymentService, error) {
+	cache := wechat.NewRedisCache(s.redis)
+	paymentApp, err := wechat.NewPaymentAppFromConfig(wechatConfig, appID, cache, s.logger)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeWechatPayFailed, err, "创建微信支付应用失败")
+	}
+	return wechat.NewPaymentService(paymentApp, s.logger), nil
+}
+
+func (s *Service) createPackageOrder(
+	ctx context.Context,
+	customerID uint,
+	appID string,
+	openID string,
+	validationResult *purchase_validation.PurchaseValidationResult,
+	activeConfig *model.WechatConfig,
+	redisKey string,
+	paymentService *wechat.PaymentService,
+	created *bool,
+) (*dto.ClientCreateOrderResponse, error) {
+	order, err := s.buildPendingOrder(customerID, validationResult, activeConfig)
+	if err != nil {
+		return nil, err
+	}
+
+	items, err := s.buildOrderItems(ctx, customerID, validationResult)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.orderStore.Create(ctx, order, items); err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建订单失败")
+	}
+
+	s.markClientPurchaseCreated(ctx, redisKey, order.OrderNo)
+	*created = true
+
+	description := "套餐购买"
+	if len(items) > 0 && items[0] != nil && items[0].PackageName != "" {
+		description = items[0].PackageName
+	}
+
+	payResult, err := paymentService.CreateJSAPIOrder(ctx, order.OrderNo, description, openID, int(order.TotalAmount))
+	if err != nil {
+		return nil, err
+	}
+
+	return &dto.ClientCreateOrderResponse{
+		OrderType: "package",
+		Order: &dto.ClientOrderInfo{
+			OrderID:       order.ID,
+			OrderNo:       order.OrderNo,
+			TotalAmount:   order.TotalAmount,
+			PaymentStatus: orderStatusToClientStatus(order.PaymentStatus),
+			CreatedAt:     formatClientServiceTime(order.CreatedAt),
+		},
+		PayConfig: buildClientPayConfig(appID, payResult.PayConfig),
+	}, nil
+}
+
+func (s *Service) createForceRechargeOrder(
+	ctx context.Context,
+	customerID uint,
+	appID string,
+	openID string,
+	assetInfo *dto.AssetResolveResponse,
+	validationResult *purchase_validation.PurchaseValidationResult,
+	activeConfig *model.WechatConfig,
+	forceRecharge *ForceRechargeRequirement,
+	redisKey string,
+	paymentService *wechat.PaymentService,
+	created *bool,
+) (*dto.ClientCreateOrderResponse, error) {
+	resourceType, resourceID, err := resolveWalletResource(validationResult)
+	if err != nil {
+		return nil, err
+	}
+
+	wallet, err := s.walletStore.GetByResourceTypeAndID(ctx, resourceType, resourceID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeWalletNotFound, "钱包不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询资产钱包失败")
+	}
+
+	linkedPackageIDs, err := sonic.Marshal(extractPackageIDs(validationResult.Packages))
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化关联套餐失败")
+	}
+
+	carrierID := resourceID
+	recharge := &model.AssetRechargeRecord{
+		UserID:             customerID,
+		AssetWalletID:      wallet.ID,
+		ResourceType:       resourceType,
+		ResourceID:         resourceID,
+		RechargeNo:         generateClientRechargeNo(),
+		Amount:             forceRecharge.ForceRechargeAmount,
+		PaymentMethod:      model.PaymentMethodWechat,
+		PaymentConfigID:    &activeConfig.ID,
+		Status:             1,
+		ShopIDTag:          wallet.ShopIDTag,
+		EnterpriseIDTag:    wallet.EnterpriseIDTag,
+		OperatorType:       "personal_customer",
+		Generation:         resolveGeneration(validationResult),
+		LinkedPackageIDs:   datatypes.JSON(linkedPackageIDs),
+		LinkedOrderType:    resolveOrderType(validationResult),
+		LinkedCarrierType:  assetInfo.AssetType,
+		LinkedCarrierID:    &carrierID,
+		AutoPurchaseStatus: constants.AutoPurchaseStatusPending,
+	}
+
+	if err := s.rechargeRecordStore.Create(ctx, recharge); err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建充值记录失败")
+	}
+
+	s.markClientPurchaseCreated(ctx, redisKey, recharge.RechargeNo)
+	*created = true
+
+	payResult, err := paymentService.CreateJSAPIOrder(ctx, recharge.RechargeNo, "余额充值", openID, int(recharge.Amount))
+	if err != nil {
+		return nil, err
+	}
+
+	return &dto.ClientCreateOrderResponse{
+		OrderType: "recharge",
+		Recharge: &dto.ClientRechargeInfo{
+			RechargeID:         recharge.ID,
+			RechargeNo:         recharge.RechargeNo,
+			Amount:             recharge.Amount,
+			Status:             rechargeStatusToClientStatus(recharge.Status),
+			AutoPurchaseStatus: recharge.AutoPurchaseStatus,
+		},
+		PayConfig:         buildClientPayConfig(appID, payResult.PayConfig),
+		LinkedPackageInfo: buildLinkedPackageInfo(validationResult, forceRecharge),
+	}, nil
+}
+
+func (s *Service) buildPendingOrder(customerID uint, result *purchase_validation.PurchaseValidationResult, activeConfig *model.WechatConfig) (*model.Order, error) {
+	orderType := resolveOrderType(result)
+	if orderType == "" {
+		return nil, errors.New(errors.CodeInvalidParam)
+	}
+
+	now := time.Now()
+	expiresAt := now.Add(constants.OrderExpireTimeout)
+	order := &model.Order{
+		BaseModel: model.BaseModel{
+			Creator: customerID,
+			Updater: customerID,
+		},
+		OrderNo:                 s.orderStore.GenerateOrderNo(),
+		OrderType:               orderType,
+		BuyerType:               model.BuyerTypePersonal,
+		BuyerID:                 customerID,
+		TotalAmount:             result.TotalPrice,
+		PaymentMethod:           model.PaymentMethodWechat,
+		PaymentStatus:           model.PaymentStatusPending,
+		CommissionStatus:        model.CommissionStatusPending,
+		CommissionConfigVersion: 0,
+		Source:                  constants.OrderSourceClient,
+		Generation:              resolveGeneration(result),
+		ExpiresAt:               &expiresAt,
+		PaymentConfigID:         &activeConfig.ID,
+	}
+
+	if result.Card != nil {
+		order.IotCardID = &result.Card.ID
+		order.SeriesID = result.Card.SeriesID
+		order.SellerShopID = result.Card.ShopID
+	} else if result.Device != nil {
+		order.DeviceID = &result.Device.ID
+		order.SeriesID = result.Device.SeriesID
+		order.SellerShopID = result.Device.ShopID
+	}
+
+	return order, nil
+}
+
+func (s *Service) buildOrderItems(ctx context.Context, customerID uint, result *purchase_validation.PurchaseValidationResult) ([]*model.OrderItem, error) {
+	sellerShopID := resolveSellerShopID(result)
+	items := make([]*model.OrderItem, 0, len(result.Packages))
+
+	for _, pkg := range result.Packages {
+		if pkg == nil {
+			continue
+		}
+
+		unitPrice, err := s.purchaseValidationService.GetPurchasePrice(ctx, pkg, sellerShopID)
+		if err != nil {
+			return nil, err
+		}
+
+		items = append(items, &model.OrderItem{
+			BaseModel: model.BaseModel{
+				Creator: customerID,
+				Updater: customerID,
+			},
+			PackageID:   pkg.ID,
+			PackageName: pkg.PackageName,
+			Quantity:    1,
+			UnitPrice:   unitPrice,
+			Amount:      unitPrice,
+		})
+	}
+
+	return items, nil
+}
+
+func (s *Service) checkForceRechargeRequirement(ctx context.Context, result *purchase_validation.PurchaseValidationResult) *ForceRechargeRequirement {
+	defaultResult := &ForceRechargeRequirement{NeedForceRecharge: false}
+
+	var seriesID *uint
+	var sellerShopID uint
+	if result.Card != nil {
+		seriesID = result.Card.SeriesID
+		if result.Card.ShopID != nil {
+			sellerShopID = *result.Card.ShopID
+		}
+	} else if result.Device != nil {
+		seriesID = result.Device.SeriesID
+		if result.Device.ShopID != nil {
+			sellerShopID = *result.Device.ShopID
+		}
+	}
+
+	if seriesID == nil || *seriesID == 0 {
+		return defaultResult
+	}
+
+	series, err := s.packageSeriesStore.GetByID(ctx, *seriesID)
+	if err != nil {
+		s.logger.Warn("查询套餐系列失败", zap.Uint("series_id", *seriesID), zap.Error(err))
+		return defaultResult
+	}
+
+	config, err := series.GetOneTimeCommissionConfig()
+	if err != nil || config == nil || !config.Enable {
+		return defaultResult
+	}
+
+	if config.TriggerType == model.OneTimeCommissionTriggerFirstRecharge {
+		return &ForceRechargeRequirement{
+			NeedForceRecharge:   true,
+			ForceRechargeAmount: config.Threshold,
+		}
+	}
+
+	if config.EnableForceRecharge {
+		amount := config.ForceAmount
+		if amount == 0 {
+			amount = config.Threshold
+		}
+		return &ForceRechargeRequirement{
+			NeedForceRecharge:   true,
+			ForceRechargeAmount: amount,
+		}
+	}
+
+	if sellerShopID > 0 {
+		allocation, allocErr := s.shopSeriesAllocationStore.GetByShopAndSeries(ctx, sellerShopID, *seriesID)
+		if allocErr == nil && allocation.EnableForceRecharge {
+			amount := allocation.ForceRechargeAmount
+			if amount == 0 {
+				amount = config.Threshold
+			}
+			return &ForceRechargeRequirement{
+				NeedForceRecharge:   true,
+				ForceRechargeAmount: amount,
+			}
+		}
+	}
+
+	return defaultResult
+}
+
+func (s *Service) markClientPurchaseCreated(ctx context.Context, redisKey string, value string) {
+	if err := s.redis.Set(ctx, redisKey, value, clientPurchaseIdempotencyTTL).Err(); err != nil {
+		s.logger.Warn("设置客户端购买幂等标记失败",
+			zap.String("redis_key", redisKey),
+			zap.Error(err),
+		)
+	}
+}
+
+func buildLinkedPackageInfo(result *purchase_validation.PurchaseValidationResult, forceRecharge *ForceRechargeRequirement) *dto.LinkedPackageInfo {
+	packageNames := make([]string, 0, len(result.Packages))
+	for _, pkg := range result.Packages {
+		if pkg == nil || pkg.PackageName == "" {
+			continue
+		}
+		packageNames = append(packageNames, pkg.PackageName)
+	}
+
+	return &dto.LinkedPackageInfo{
+		PackageNames:        packageNames,
+		TotalPackageAmount:  result.TotalPrice,
+		ForceRechargeAmount: forceRecharge.ForceRechargeAmount,
+		WalletCredit:        forceRecharge.ForceRechargeAmount,
+	}
+}
+
+func buildClientPayConfig(appID string, payConfig any) *dto.ClientPayConfig {
+	configMap, _ := payConfig.(map[string]any)
+	if configMap == nil {
+		configMap = map[string]any{}
+	}
+
+	return &dto.ClientPayConfig{
+		AppID:      firstNonEmpty(stringFromAny(configMap["appId"]), appID),
+		Timestamp:  firstNonEmpty(stringFromAny(configMap["timeStamp"]), stringFromAny(configMap["timestamp"])),
+		NonceStr:   stringFromAny(configMap["nonceStr"]),
+		PackageVal: stringFromAny(configMap["package"]),
+		SignType:   stringFromAny(configMap["signType"]),
+		PaySign:    stringFromAny(configMap["paySign"]),
+	}
+}
+
+func resolveWalletResource(result *purchase_validation.PurchaseValidationResult) (string, uint, error) {
+	if result.Card != nil {
+		return constants.AssetWalletResourceTypeIotCard, result.Card.ID, nil
+	}
+	if result.Device != nil {
+		return constants.AssetWalletResourceTypeDevice, result.Device.ID, nil
+	}
+	return "", 0, errors.New(errors.CodeInvalidParam)
+}
+
+func resolveOrderType(result *purchase_validation.PurchaseValidationResult) string {
+	if result.Card != nil {
+		return model.OrderTypeSingleCard
+	}
+	if result.Device != nil {
+		return model.OrderTypeDevice
+	}
+	return ""
+}
+
+func resolveGeneration(result *purchase_validation.PurchaseValidationResult) int {
+	if result.Card != nil && result.Card.Generation > 0 {
+		return result.Card.Generation
+	}
+	if result.Device != nil && result.Device.Generation > 0 {
+		return result.Device.Generation
+	}
+	return 1
+}
+
+func resolveSellerShopID(result *purchase_validation.PurchaseValidationResult) uint {
+	if result.Card != nil && result.Card.ShopID != nil {
+		return *result.Card.ShopID
+	}
+	if result.Device != nil && result.Device.ShopID != nil {
+		return *result.Device.ShopID
+	}
+	return 0
+}
+
+func packagesNeedRealname(packages []*model.Package) bool {
+	for _, pkg := range packages {
+		if pkg != nil && pkg.EnableRealnameActivation {
+			return true
+		}
+	}
+	return false
+}
+
+func extractPackageIDs(packages []*model.Package) []uint {
+	ids := make([]uint, 0, len(packages))
+	for _, pkg := range packages {
+		if pkg == nil {
+			continue
+		}
+		ids = append(ids, pkg.ID)
+	}
+	return ids
+}
+
+func buildClientPurchaseBusinessKey(customerID uint, assetInfo *dto.AssetResolveResponse, req *dto.ClientCreateOrderRequest) string {
+	packageIDs := make([]uint, 0, len(req.PackageIDs))
+	packageIDs = append(packageIDs, req.PackageIDs...)
+	slices.Sort(packageIDs)
+
+	parts := make([]string, 0, len(packageIDs))
+	for _, packageID := range packageIDs {
+		parts = append(parts, strconv.FormatUint(uint64(packageID), 10))
+	}
+
+	return fmt.Sprintf("%d:%s:%d:%s:%s", customerID, assetInfo.AssetType, assetInfo.AssetID, req.AppType, strings.Join(parts, ","))
+}
+
+func orderStatusToClientStatus(status int) int {
+	switch status {
+	case model.PaymentStatusPending:
+		return 0
+	case model.PaymentStatusPaid:
+		return 1
+	case model.PaymentStatusCancelled:
+		return 2
+	default:
+		return status
+	}
+}
+
+func rechargeStatusToClientStatus(status int) int {
+	switch status {
+	case 1:
+		return 0
+	case 2, 3:
+		return 1
+	default:
+		return 2
+	}
+}
+
+func formatClientServiceTime(t time.Time) string {
+	if t.IsZero() {
+		return ""
+	}
+	return t.Format(time.RFC3339)
+}
+
+func generateClientRechargeNo() string {
+	return fmt.Sprintf("CRCH%d%06d", time.Now().UnixNano()/1e6, rand.Intn(1000000))
+}
+
+func stringFromAny(value any) string {
+	if value == nil {
+		return ""
+	}
+	return fmt.Sprint(value)
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+	return ""
+}

internal/service/commission_calculation/service.go

@@ -8,6 +8,7 @@ import (
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/service/commission_stats"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
@@ -201,7 +202,7 @@ func (s *Service) CalculateCostDiffCommission(ctx context.Context, order *model.
 }
 
 func (s *Service) triggerOneTimeCommissionForCardInTx(ctx context.Context, tx *gorm.DB, order *model.Order, cardID uint) error {
-	if order.IsPurchaseOnBehalf {
+	if order.IsPurchaseOnBehalf || order.Source != constants.OrderSourceClient {
 		return nil
 	}
 
@@ -285,7 +286,7 @@ func (s *Service) TriggerOneTimeCommissionForCard(ctx context.Context, order *mo
 }
 
 func (s *Service) triggerOneTimeCommissionForDeviceInTx(ctx context.Context, tx *gorm.DB, order *model.Order, deviceID uint) error {
-	if order.IsPurchaseOnBehalf {
+	if order.IsPurchaseOnBehalf || order.Source != constants.OrderSourceClient {
 		return nil
 	}
 

internal/service/customer/service.go

@@ -1,126 +0,0 @@
-// Package customer 提供客户管理的业务逻辑服务
-// 包含客户信息管理、客户查询等功能
-package customer
-
-import (
-	"context"
-
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/internal/store"
-	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-	"github.com/break/junhong_cmp_fiber/pkg/errors"
-)
-
-// Service 个人客户业务服务
-type Service struct {
-	customerStore *postgres.PersonalCustomerStore
-}
-
-// New 创建个人客户服务
-func New(customerStore *postgres.PersonalCustomerStore) *Service {
-	return &Service{
-		customerStore: customerStore,
-	}
-}
-
-// Create 创建个人客户
-func (s *Service) Create(ctx context.Context, req *dto.CreatePersonalCustomerRequest) (*model.PersonalCustomer, error) {
-	// 检查手机号唯一性
-	if req.Phone != "" {
-		existing, err := s.customerStore.GetByPhone(ctx, req.Phone)
-		if err == nil && existing != nil {
-			return nil, errors.New(errors.CodeCustomerPhoneExists, "手机号已存在")
-		}
-	}
-
-	// 创建个人客户
-	// 注意：根据新的数据模型，手机号应该存储在 PersonalCustomerPhone 表中
-	// 这里暂时先创建客户记录，手机号的存储后续通过 PersonalCustomerPhoneStore 实现
-	customer := &model.PersonalCustomer{
-		Nickname:  req.Nickname,
-		AvatarURL: req.AvatarURL,
-		WxOpenID:  req.WxOpenID,
-		WxUnionID: req.WxUnionID,
-		Status:    constants.StatusEnabled,
-	}
-
-	if err := s.customerStore.Create(ctx, customer); err != nil {
-		return nil, err
-	}
-
-	// TODO: 创建 PersonalCustomerPhone 记录，需要通过 PersonalCustomerPhoneStore 创建手机号关联
-
-	return customer, nil
-}
-
-// Update 更新个人客户信息
-func (s *Service) Update(ctx context.Context, id uint, req *dto.UpdatePersonalCustomerRequest) (*model.PersonalCustomer, error) {
-	// 查询客户
-	customer, err := s.customerStore.GetByID(ctx, id)
-	if err != nil {
-		return nil, errors.New(errors.CodeCustomerNotFound, "个人客户不存在")
-	}
-
-	// TODO: 手机号的更新逻辑需要通过 PersonalCustomerPhoneStore 更新或创建手机号记录
-
-	// 更新字段
-	if req.Nickname != nil {
-		customer.Nickname = *req.Nickname
-	}
-	if req.AvatarURL != nil {
-		customer.AvatarURL = *req.AvatarURL
-	}
-
-	if err := s.customerStore.Update(ctx, customer); err != nil {
-		return nil, err
-	}
-
-	return customer, nil
-}
-
-// BindWeChat 绑定微信信息
-func (s *Service) BindWeChat(ctx context.Context, id uint, wxOpenID, wxUnionID string) error {
-	customer, err := s.customerStore.GetByID(ctx, id)
-	if err != nil {
-		return errors.New(errors.CodeCustomerNotFound, "个人客户不存在")
-	}
-
-	customer.WxOpenID = wxOpenID
-	customer.WxUnionID = wxUnionID
-
-	return s.customerStore.Update(ctx, customer)
-}
-
-// GetByID 获取个人客户详情
-func (s *Service) GetByID(ctx context.Context, id uint) (*model.PersonalCustomer, error) {
-	customer, err := s.customerStore.GetByID(ctx, id)
-	if err != nil {
-		return nil, errors.New(errors.CodeCustomerNotFound, "个人客户不存在")
-	}
-	return customer, nil
-}
-
-// GetByPhone 根据手机号获取个人客户
-func (s *Service) GetByPhone(ctx context.Context, phone string) (*model.PersonalCustomer, error) {
-	customer, err := s.customerStore.GetByPhone(ctx, phone)
-	if err != nil {
-		return nil, errors.New(errors.CodeCustomerNotFound, "个人客户不存在")
-	}
-	return customer, nil
-}
-
-// GetByWxOpenID 根据微信 OpenID 获取个人客户
-func (s *Service) GetByWxOpenID(ctx context.Context, wxOpenID string) (*model.PersonalCustomer, error) {
-	customer, err := s.customerStore.GetByWxOpenID(ctx, wxOpenID)
-	if err != nil {
-		return nil, errors.New(errors.CodeCustomerNotFound, "个人客户不存在")
-	}
-	return customer, nil
-}
-
-// List 查询个人客户列表
-func (s *Service) List(ctx context.Context, opts *store.QueryOptions, filters map[string]interface{}) ([]*model.PersonalCustomer, int64, error) {
-	return s.customerStore.List(ctx, opts, filters)
-}

internal/service/device/service.go

@@ -973,7 +973,7 @@ func (s *Service) StartDevice(ctx context.Context, deviceID uint) error {
 
 	// 全部失败时返回 error
 	if successCount == 0 && lastErr != nil {
-		return errors.Wrap(errors.CodeInternalError, lastErr, "设备复机失败")
+		return errors.Wrap(errors.CodeGatewayError, lastErr, "设备复机失败，所有卡均复机失败")
 	}
 
 	return nil

internal/service/exchange/migration.go

@@ -0,0 +1,243 @@
+package exchange
+
+import (
+	"context"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (s *Service) executeMigration(ctx context.Context, order *model.ExchangeOrder) (int64, error) {
+	var migrationBalance int64
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if order.NewAssetID == nil || *order.NewAssetID == 0 {
+			return errors.New(errors.CodeInvalidParam, "新资产信息缺失")
+		}
+
+		oldAsset, err := s.resolveAssetByIdentifier(ctx, order.OldAssetType, order.OldAssetIdentifier)
+		if err != nil {
+			return err
+		}
+		newAsset, err := s.resolveAssetByIdentifier(ctx, order.OldAssetType, order.NewAssetIdentifier)
+		if err != nil {
+			return err
+		}
+
+		migrationBalance, err = s.transferWalletBalanceWithTx(ctx, tx, order, oldAsset, newAsset)
+		if err != nil {
+			return err
+		}
+
+		if err = s.migratePackageUsageWithTx(ctx, tx, oldAsset, newAsset); err != nil {
+			return err
+		}
+
+		if err = s.copyAccumulatedFieldsWithTx(tx, oldAsset, newAsset); err != nil {
+			return err
+		}
+
+		if err = s.copyResourceTagsWithTx(ctx, tx, oldAsset, newAsset); err != nil {
+			return err
+		}
+
+		if oldAsset.VirtualNo != "" && newAsset.VirtualNo != "" {
+			if err = tx.Model(&model.PersonalCustomerDevice{}).
+				Where("virtual_no = ?", oldAsset.VirtualNo).
+				Updates(map[string]any{"virtual_no": newAsset.VirtualNo, "updated_at": time.Now()}).Error; err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "更新客户绑定关系失败")
+			}
+		}
+
+		if err = s.updateOldAssetStatusWithTx(tx, oldAsset); err != nil {
+			return err
+		}
+
+		if err = tx.Model(&model.ExchangeOrder{}).Where("id = ?", order.ID).Updates(map[string]any{
+			"migration_completed": true,
+			"migration_balance":   migrationBalance,
+			"updater":             middleware.GetUserIDFromContext(ctx),
+			"updated_at":          time.Now(),
+		}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "更新换货单迁移状态失败")
+		}
+
+		return nil
+	})
+	if err != nil {
+		return 0, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "执行全量迁移失败")
+	}
+
+	return migrationBalance, nil
+}
+
+func (s *Service) transferWalletBalanceWithTx(ctx context.Context, tx *gorm.DB, order *model.ExchangeOrder, oldAsset, newAsset *resolvedExchangeAsset) (int64, error) {
+	var oldWallet model.AssetWallet
+	if err := tx.WithContext(ctx).Where("resource_type = ? AND resource_id = ?", oldAsset.AssetType, oldAsset.AssetID).First(&oldWallet).Error; err != nil {
+		if err != gorm.ErrRecordNotFound {
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询旧资产钱包失败")
+		}
+	}
+
+	var newWallet model.AssetWallet
+	if err := tx.WithContext(ctx).Where("resource_type = ? AND resource_id = ?", newAsset.AssetType, newAsset.AssetID).First(&newWallet).Error; err != nil {
+		if err != gorm.ErrRecordNotFound {
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询新资产钱包失败")
+		}
+
+		shopTag := uint(0)
+		if newAsset.ShopID != nil {
+			shopTag = *newAsset.ShopID
+		}
+		newWallet = model.AssetWallet{ResourceType: newAsset.AssetType, ResourceID: newAsset.AssetID, Balance: 0, FrozenBalance: 0, Currency: "CNY", Status: 1, Version: 0, ShopIDTag: shopTag}
+		if err = tx.WithContext(ctx).Create(&newWallet).Error; err != nil {
+			return 0, errors.Wrap(errors.CodeDatabaseError, err, "创建新资产钱包失败")
+		}
+	}
+
+	migrationBalance := oldWallet.Balance
+	if migrationBalance <= 0 {
+		return 0, nil
+	}
+
+	beforeBalance := newWallet.Balance
+	if err := tx.WithContext(ctx).Model(&model.AssetWallet{}).Where("id = ?", oldWallet.ID).Updates(map[string]any{"balance": 0, "updated_at": time.Now()}).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "清空旧资产钱包余额失败")
+	}
+
+	if err := tx.WithContext(ctx).Model(&model.AssetWallet{}).Where("id = ?", newWallet.ID).Updates(map[string]any{"balance": gorm.Expr("balance + ?", migrationBalance), "updated_at": time.Now()}).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "增加新资产钱包余额失败")
+	}
+
+	refType := "exchange"
+	if err := tx.WithContext(ctx).Create(&model.AssetWalletTransaction{
+		AssetWalletID:   newWallet.ID,
+		ResourceType:    newAsset.AssetType,
+		ResourceID:      newAsset.AssetID,
+		UserID:          middleware.GetUserIDFromContext(ctx),
+		TransactionType: "refund",
+		Amount:          migrationBalance,
+		BalanceBefore:   beforeBalance,
+		BalanceAfter:    beforeBalance + migrationBalance,
+		Status:          1,
+		ReferenceType:   &refType,
+		ReferenceNo:     &order.ExchangeNo,
+		Creator:         middleware.GetUserIDFromContext(ctx),
+		ShopIDTag:       newWallet.ShopIDTag,
+		EnterpriseIDTag: newWallet.EnterpriseIDTag,
+	}).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "写入迁移钱包流水失败")
+	}
+
+	return migrationBalance, nil
+}
+
+func (s *Service) migratePackageUsageWithTx(ctx context.Context, tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) error {
+	query := tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("status IN ?", []int{constants.PackageUsageStatusPending, constants.PackageUsageStatusActive, constants.PackageUsageStatusDepleted})
+	if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
+		query = query.Where("iot_card_id = ?", oldAsset.AssetID)
+	} else {
+		query = query.Where("device_id = ?", oldAsset.AssetID)
+	}
+
+	var usageIDs []uint
+	if err := query.Pluck("id", &usageIDs).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐使用记录失败")
+	}
+
+	if len(usageIDs) == 0 {
+		return nil
+	}
+
+	updates := map[string]any{"updated_at": time.Now()}
+	if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
+		updates["iot_card_id"] = newAsset.AssetID
+	} else {
+		updates["device_id"] = newAsset.AssetID
+	}
+
+	if err := tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("id IN ?", usageIDs).Updates(updates).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐使用记录失败")
+	}
+
+	if err := tx.WithContext(ctx).Model(&model.PackageUsageDailyRecord{}).Where("package_usage_id IN ?", usageIDs).Update("updated_at", gorm.Expr("updated_at")).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐日记录失败")
+	}
+
+	return nil
+}
+
+func (s *Service) copyAccumulatedFieldsWithTx(tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) error {
+	if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
+		if oldAsset.Card == nil {
+			return errors.New(errors.CodeAssetNotFound)
+		}
+		if err := tx.Model(&model.IotCard{}).Where("id = ?", newAsset.AssetID).Updates(map[string]any{
+			"accumulated_recharge":               oldAsset.Card.AccumulatedRecharge,
+			"first_commission_paid":              oldAsset.Card.FirstCommissionPaid,
+			"accumulated_recharge_by_series":     oldAsset.Card.AccumulatedRechargeBySeriesJSON,
+			"first_recharge_triggered_by_series": oldAsset.Card.FirstRechargeTriggeredBySeriesJSON,
+			"updated_at":                         time.Now(),
+		}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "复制旧卡累计字段失败")
+		}
+		return nil
+	}
+
+	if oldAsset.Device == nil {
+		return errors.New(errors.CodeAssetNotFound)
+	}
+	if err := tx.Model(&model.Device{}).Where("id = ?", newAsset.AssetID).Updates(map[string]any{
+		"accumulated_recharge":               oldAsset.Device.AccumulatedRecharge,
+		"first_commission_paid":              oldAsset.Device.FirstCommissionPaid,
+		"accumulated_recharge_by_series":     oldAsset.Device.AccumulatedRechargeBySeriesJSON,
+		"first_recharge_triggered_by_series": oldAsset.Device.FirstRechargeTriggeredBySeriesJSON,
+		"updated_at":                         time.Now(),
+	}).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "复制旧设备累计字段失败")
+	}
+	return nil
+}
+
+func (s *Service) copyResourceTagsWithTx(ctx context.Context, tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) error {
+	var tags []*model.ResourceTag
+	if err := tx.WithContext(ctx).Where("resource_type = ? AND resource_id = ?", oldAsset.AssetType, oldAsset.AssetID).Find(&tags).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询资源标签失败")
+	}
+	var creator = middleware.GetUserIDFromContext(ctx)
+	for _, item := range tags {
+		if item == nil {
+			continue
+		}
+		record := &model.ResourceTag{
+			ResourceType: newAsset.AssetType,
+			ResourceID:   newAsset.AssetID,
+			TagID:        item.TagID,
+			EnterpriseID: item.EnterpriseID,
+			ShopID:       item.ShopID,
+			BaseModel:    model.BaseModel{Creator: creator, Updater: creator},
+		}
+		if err := tx.WithContext(ctx).Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "resource_type"}, {Name: "resource_id"}, {Name: "tag_id"}}, DoNothing: true}).Create(record).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "复制资源标签失败")
+		}
+	}
+	return nil
+}
+
+func (s *Service) updateOldAssetStatusWithTx(tx *gorm.DB, oldAsset *resolvedExchangeAsset) error {
+	if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
+		if err := tx.Model(&model.IotCard{}).Where("id = ?", oldAsset.AssetID).Updates(map[string]any{"asset_status": 3, "updated_at": time.Now()}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "更新旧卡状态失败")
+		}
+		return nil
+	}
+	if err := tx.Model(&model.Device{}).Where("id = ?", oldAsset.AssetID).Updates(map[string]any{"asset_status": 3, "updated_at": time.Now()}).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "更新旧设备状态失败")
+	}
+	return nil
+}

internal/service/exchange/service.go

@@ -0,0 +1,487 @@
+package exchange
+
+import (
+	"context"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+type Service struct {
+	db                           *gorm.DB
+	exchangeStore                *postgres.ExchangeOrderStore
+	iotCardStore                 *postgres.IotCardStore
+	deviceStore                  *postgres.DeviceStore
+	assetWalletStore             *postgres.AssetWalletStore
+	assetWalletTransactionStore  *postgres.AssetWalletTransactionStore
+	packageUsageStore            *postgres.PackageUsageStore
+	packageUsageDailyRecordStore *postgres.PackageUsageDailyRecordStore
+	resourceTagStore             *postgres.ResourceTagStore
+	personalCustomerDeviceStore  *postgres.PersonalCustomerDeviceStore
+	logger                       *zap.Logger
+}
+
+func New(
+	db *gorm.DB,
+	exchangeStore *postgres.ExchangeOrderStore,
+	iotCardStore *postgres.IotCardStore,
+	deviceStore *postgres.DeviceStore,
+	assetWalletStore *postgres.AssetWalletStore,
+	assetWalletTransactionStore *postgres.AssetWalletTransactionStore,
+	packageUsageStore *postgres.PackageUsageStore,
+	packageUsageDailyRecordStore *postgres.PackageUsageDailyRecordStore,
+	resourceTagStore *postgres.ResourceTagStore,
+	personalCustomerDeviceStore *postgres.PersonalCustomerDeviceStore,
+	logger *zap.Logger,
+) *Service {
+	return &Service{
+		db:                           db,
+		exchangeStore:                exchangeStore,
+		iotCardStore:                 iotCardStore,
+		deviceStore:                  deviceStore,
+		assetWalletStore:             assetWalletStore,
+		assetWalletTransactionStore:  assetWalletTransactionStore,
+		packageUsageStore:            packageUsageStore,
+		packageUsageDailyRecordStore: packageUsageDailyRecordStore,
+		resourceTagStore:             resourceTagStore,
+		personalCustomerDeviceStore:  personalCustomerDeviceStore,
+		logger:                       logger,
+	}
+}
+
+func (s *Service) Create(ctx context.Context, req *dto.CreateExchangeRequest) (*dto.ExchangeOrderResponse, error) {
+	asset, err := s.resolveAssetByIdentifier(ctx, req.OldAssetType, req.OldIdentifier)
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err = s.exchangeStore.FindActiveByOldAsset(ctx, asset.AssetType, asset.AssetID); err == nil {
+		return nil, errors.New(errors.CodeExchangeInProgress)
+	} else if err != gorm.ErrRecordNotFound {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询进行中换货单失败")
+	}
+
+	shopID := middleware.GetShopIDFromContext(ctx)
+	creator := middleware.GetUserIDFromContext(ctx)
+	order := &model.ExchangeOrder{
+		ExchangeNo:         model.GenerateExchangeNo(),
+		OldAssetType:       asset.AssetType,
+		OldAssetID:         asset.AssetID,
+		OldAssetIdentifier: asset.Identifier,
+		ExchangeReason:     req.ExchangeReason,
+		Remark:             req.Remark,
+		Status:             constants.ExchangeStatusPendingInfo,
+		MigrationCompleted: false,
+		MigrationBalance:   0,
+		MigrateData:        false,
+		BaseModel:          model.BaseModel{Creator: creator, Updater: creator},
+	}
+	if shopID > 0 {
+		order.ShopID = &shopID
+	}
+
+	if err = s.exchangeStore.Create(ctx, order); err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建换货单失败")
+	}
+
+	return s.toExchangeOrderResponse(order), nil
+}
+
+func (s *Service) List(ctx context.Context, req *dto.ExchangeListRequest) (*dto.ExchangeListResponse, error) {
+	page := req.Page
+	page = max(page, 1)
+	pageSize := req.PageSize
+	if pageSize < 1 {
+		pageSize = constants.DefaultPageSize
+	}
+	if pageSize > constants.MaxPageSize {
+		pageSize = constants.MaxPageSize
+	}
+
+	filters := make(map[string]any)
+	if req.Status != nil {
+		filters["status"] = *req.Status
+	}
+	if req.Identifier != "" {
+		filters["identifier"] = req.Identifier
+	}
+	if req.CreatedAtStart != nil {
+		filters["created_at_start"] = *req.CreatedAtStart
+	}
+	if req.CreatedAtEnd != nil {
+		filters["created_at_end"] = *req.CreatedAtEnd
+	}
+
+	orders, total, err := s.exchangeStore.List(ctx, filters, page, pageSize)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询换货单列表失败")
+	}
+
+	list := make([]*dto.ExchangeOrderResponse, 0, len(orders))
+	for _, item := range orders {
+		list = append(list, s.toExchangeOrderResponse(item))
+	}
+
+	return &dto.ExchangeListResponse{List: list, Total: total, Page: page, PageSize: pageSize}, nil
+}
+
+func (s *Service) Get(ctx context.Context, id uint) (*dto.ExchangeOrderResponse, error) {
+	order, err := s.exchangeStore.GetByID(ctx, id)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeExchangeOrderNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询换货单详情失败")
+	}
+	return s.toExchangeOrderResponse(order), nil
+}
+
+func (s *Service) Ship(ctx context.Context, id uint, req *dto.ExchangeShipRequest) (*dto.ExchangeOrderResponse, error) {
+	order, err := s.exchangeStore.GetByID(ctx, id)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeExchangeOrderNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询换货单失败")
+	}
+	if order.Status != constants.ExchangeStatusPendingShip {
+		return nil, errors.New(errors.CodeExchangeStatusInvalid)
+	}
+
+	newAsset, err := s.resolveAssetByIdentifier(ctx, order.OldAssetType, req.NewIdentifier)
+	if err != nil {
+		return nil, err
+	}
+	if newAsset.AssetType != order.OldAssetType {
+		return nil, errors.New(errors.CodeExchangeAssetTypeMismatch)
+	}
+	if newAsset.AssetStatus != 1 {
+		return nil, errors.New(errors.CodeExchangeNewAssetNotInStock)
+	}
+
+	updates := map[string]any{
+		"new_asset_type":       newAsset.AssetType,
+		"new_asset_id":         newAsset.AssetID,
+		"new_asset_identifier": newAsset.Identifier,
+		"express_company":      req.ExpressCompany,
+		"express_no":           req.ExpressNo,
+		"migrate_data":         req.MigrateData,
+		"updater":              middleware.GetUserIDFromContext(ctx),
+		"updated_at":           time.Now(),
+	}
+	if err = s.exchangeStore.UpdateStatus(ctx, id, constants.ExchangeStatusPendingShip, constants.ExchangeStatusShipped, updates); err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeExchangeStatusInvalid)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新换货单发货状态失败")
+	}
+
+	return s.Get(ctx, id)
+}
+
+func (s *Service) Complete(ctx context.Context, id uint) error {
+	order, err := s.exchangeStore.GetByID(ctx, id)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeOrderNotFound)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询换货单失败")
+	}
+	if order.Status != constants.ExchangeStatusShipped {
+		return errors.New(errors.CodeExchangeStatusInvalid)
+	}
+
+	updates := map[string]any{
+		"updater":    middleware.GetUserIDFromContext(ctx),
+		"updated_at": time.Now(),
+	}
+	if order.MigrateData {
+		var migrationBalance int64
+		migrationBalance, err = s.executeMigration(ctx, order)
+		if err != nil {
+			return err
+		}
+		updates["migration_completed"] = true
+		updates["migration_balance"] = migrationBalance
+	}
+
+	if err = s.exchangeStore.UpdateStatus(ctx, id, constants.ExchangeStatusShipped, constants.ExchangeStatusCompleted, updates); err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeStatusInvalid)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "确认换货完成失败")
+	}
+
+	return nil
+}
+
+func (s *Service) Cancel(ctx context.Context, id uint, req *dto.ExchangeCancelRequest) error {
+	order, err := s.exchangeStore.GetByID(ctx, id)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeOrderNotFound)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询换货单失败")
+	}
+	if order.Status != constants.ExchangeStatusPendingInfo && order.Status != constants.ExchangeStatusPendingShip {
+		return errors.New(errors.CodeExchangeStatusInvalid)
+	}
+
+	updates := map[string]any{
+		"updater":    middleware.GetUserIDFromContext(ctx),
+		"updated_at": time.Now(),
+	}
+	if req != nil {
+		updates["remark"] = req.Remark
+	}
+	if err = s.exchangeStore.UpdateStatus(ctx, id, order.Status, constants.ExchangeStatusCancelled, updates); err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeStatusInvalid)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "取消换货失败")
+	}
+	return nil
+}
+
+func (s *Service) Renew(ctx context.Context, id uint) error {
+	order, err := s.exchangeStore.GetByID(ctx, id)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeOrderNotFound)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询换货单失败")
+	}
+	if order.Status != constants.ExchangeStatusCompleted {
+		return errors.New(errors.CodeExchangeStatusInvalid)
+	}
+
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if order.OldAssetType == constants.ExchangeAssetTypeIotCard {
+			var card model.IotCard
+			if err = tx.Where("id = ?", order.OldAssetID).First(&card).Error; err != nil {
+				if err == gorm.ErrRecordNotFound {
+					return errors.New(errors.CodeAssetNotFound)
+				}
+				return errors.Wrap(errors.CodeDatabaseError, err, "查询旧卡失败")
+			}
+			if card.AssetStatus != 3 {
+				return errors.New(errors.CodeExchangeAssetNotExchanged)
+			}
+
+			if err = tx.Model(&model.IotCard{}).Where("id = ?", card.ID).Updates(map[string]any{
+				"generation":                         card.Generation + 1,
+				"asset_status":                       1,
+				"accumulated_recharge":               0,
+				"first_commission_paid":              false,
+				"accumulated_recharge_by_series":     "{}",
+				"first_recharge_triggered_by_series": "{}",
+				"updater":                            middleware.GetUserIDFromContext(ctx),
+				"updated_at":                         time.Now(),
+			}).Error; err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "重置旧卡转新状态失败")
+			}
+
+			if err = tx.Where("virtual_no = ?", card.VirtualNo).Delete(&model.PersonalCustomerDevice{}).Error; err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "清理个人客户绑定失败")
+			}
+
+			if err = tx.Where("resource_type = ? AND resource_id = ?", constants.ExchangeAssetTypeIotCard, card.ID).Delete(&model.AssetWallet{}).Error; err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "清理旧钱包失败")
+			}
+
+			shopTag := uint(0)
+			if card.ShopID != nil {
+				shopTag = *card.ShopID
+			}
+			if err = tx.Create(&model.AssetWallet{ResourceType: constants.ExchangeAssetTypeIotCard, ResourceID: card.ID, Balance: 0, FrozenBalance: 0, Currency: "CNY", Status: 1, Version: 0, ShopIDTag: shopTag}).Error; err != nil {
+				return errors.Wrap(errors.CodeDatabaseError, err, "创建新钱包失败")
+			}
+			return nil
+		}
+
+		var device model.Device
+		if err = tx.Where("id = ?", order.OldAssetID).First(&device).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeAssetNotFound)
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "查询旧设备失败")
+		}
+		if device.AssetStatus != 3 {
+			return errors.New(errors.CodeExchangeAssetNotExchanged)
+		}
+
+		if err = tx.Model(&model.Device{}).Where("id = ?", device.ID).Updates(map[string]any{
+			"generation":                         device.Generation + 1,
+			"asset_status":                       1,
+			"accumulated_recharge":               0,
+			"first_commission_paid":              false,
+			"accumulated_recharge_by_series":     "{}",
+			"first_recharge_triggered_by_series": "{}",
+			"updater":                            middleware.GetUserIDFromContext(ctx),
+			"updated_at":                         time.Now(),
+		}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "重置旧设备转新状态失败")
+		}
+
+		if err = tx.Where("virtual_no = ?", device.VirtualNo).Delete(&model.PersonalCustomerDevice{}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "清理个人客户绑定失败")
+		}
+
+		if err = tx.Where("resource_type = ? AND resource_id = ?", constants.ExchangeAssetTypeDevice, device.ID).Delete(&model.AssetWallet{}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "清理旧钱包失败")
+		}
+
+		shopTag := uint(0)
+		if device.ShopID != nil {
+			shopTag = *device.ShopID
+		}
+		if err = tx.Create(&model.AssetWallet{ResourceType: constants.ExchangeAssetTypeDevice, ResourceID: device.ID, Balance: 0, FrozenBalance: 0, Currency: "CNY", Status: 1, Version: 0, ShopIDTag: shopTag}).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "创建新钱包失败")
+		}
+		return nil
+	})
+}
+
+func (s *Service) GetPending(ctx context.Context, identifier string) (*dto.ClientExchangePendingResponse, error) {
+	asset, err := s.resolveAssetByIdentifier(ctx, "", identifier)
+	if err != nil {
+		return nil, err
+	}
+
+	order, err := s.exchangeStore.FindActiveByOldAsset(ctx, asset.AssetType, asset.AssetID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, nil
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询待处理换货单失败")
+	}
+
+	return &dto.ClientExchangePendingResponse{
+		ID:             order.ID,
+		ExchangeNo:     order.ExchangeNo,
+		Status:         order.Status,
+		StatusText:     exchangeStatusText(order.Status),
+		ExchangeReason: order.ExchangeReason,
+		CreatedAt:      order.CreatedAt,
+	}, nil
+}
+
+func (s *Service) SubmitShippingInfo(ctx context.Context, id uint, req *dto.ClientShippingInfoRequest) error {
+	updates := map[string]any{
+		"recipient_name":    req.RecipientName,
+		"recipient_phone":   req.RecipientPhone,
+		"recipient_address": req.RecipientAddress,
+		"updated_at":        time.Now(),
+	}
+	if err := s.exchangeStore.UpdateStatus(ctx, id, constants.ExchangeStatusPendingInfo, constants.ExchangeStatusPendingShip, updates); err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeExchangeStatusInvalid)
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "提交收货信息失败")
+	}
+	return nil
+}
+
+type resolvedExchangeAsset struct {
+	AssetType   string
+	AssetID     uint
+	Identifier  string
+	VirtualNo   string
+	AssetStatus int
+	ShopID      *uint
+	Card        *model.IotCard
+	Device      *model.Device
+}
+
+func (s *Service) resolveAssetByIdentifier(ctx context.Context, expectedAssetType, identifier string) (*resolvedExchangeAsset, error) {
+	if expectedAssetType == "" || expectedAssetType == constants.ExchangeAssetTypeDevice {
+		device, err := s.deviceStore.GetByIdentifier(ctx, identifier)
+		if err == nil {
+			if expectedAssetType != "" && expectedAssetType != constants.ExchangeAssetTypeDevice {
+				return nil, errors.New(errors.CodeExchangeAssetTypeMismatch)
+			}
+			return &resolvedExchangeAsset{AssetType: constants.ExchangeAssetTypeDevice, AssetID: device.ID, Identifier: identifier, VirtualNo: device.VirtualNo, AssetStatus: device.AssetStatus, ShopID: device.ShopID, Device: device}, nil
+		}
+		if err != gorm.ErrRecordNotFound {
+			return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询设备失败")
+		}
+	}
+
+	if expectedAssetType == "" || expectedAssetType == constants.ExchangeAssetTypeIotCard {
+		var card model.IotCard
+		query := s.db.WithContext(ctx).Where("virtual_no = ? OR iccid = ? OR msisdn = ?", identifier, identifier, identifier)
+		query = middleware.ApplyShopFilter(ctx, query)
+		if err := query.First(&card).Error; err == nil {
+			if expectedAssetType != "" && expectedAssetType != constants.ExchangeAssetTypeIotCard {
+				return nil, errors.New(errors.CodeExchangeAssetTypeMismatch)
+			}
+			return &resolvedExchangeAsset{AssetType: constants.ExchangeAssetTypeIotCard, AssetID: card.ID, Identifier: identifier, VirtualNo: card.VirtualNo, AssetStatus: card.AssetStatus, ShopID: card.ShopID, Card: &card}, nil
+		} else if err != gorm.ErrRecordNotFound {
+			return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询IoT卡失败")
+		}
+	}
+
+	return nil, errors.New(errors.CodeAssetNotFound)
+}
+
+func (s *Service) toExchangeOrderResponse(order *model.ExchangeOrder) *dto.ExchangeOrderResponse {
+	if order == nil {
+		return nil
+	}
+	var deletedAt *time.Time
+	if order.DeletedAt.Valid {
+		deletedAt = &order.DeletedAt.Time
+	}
+	return &dto.ExchangeOrderResponse{
+		ID:                 order.ID,
+		ExchangeNo:         order.ExchangeNo,
+		OldAssetType:       order.OldAssetType,
+		OldAssetID:         order.OldAssetID,
+		OldAssetIdentifier: order.OldAssetIdentifier,
+		NewAssetType:       order.NewAssetType,
+		NewAssetID:         order.NewAssetID,
+		NewAssetIdentifier: order.NewAssetIdentifier,
+		RecipientName:      order.RecipientName,
+		RecipientPhone:     order.RecipientPhone,
+		RecipientAddress:   order.RecipientAddress,
+		ExpressCompany:     order.ExpressCompany,
+		ExpressNo:          order.ExpressNo,
+		MigrateData:        order.MigrateData,
+		MigrationCompleted: order.MigrationCompleted,
+		MigrationBalance:   order.MigrationBalance,
+		ExchangeReason:     order.ExchangeReason,
+		Remark:             order.Remark,
+		Status:             order.Status,
+		StatusText:         exchangeStatusText(order.Status),
+		ShopID:             order.ShopID,
+		CreatedAt:          order.CreatedAt,
+		UpdatedAt:          order.UpdatedAt,
+		DeletedAt:          deletedAt,
+		Creator:            order.Creator,
+		Updater:            order.Updater,
+	}
+}
+
+func exchangeStatusText(status int) string {
+	switch status {
+	case constants.ExchangeStatusPendingInfo:
+		return "待填写信息"
+	case constants.ExchangeStatusPendingShip:
+		return "待发货"
+	case constants.ExchangeStatusShipped:
+		return "已发货待确认"
+	case constants.ExchangeStatusCompleted:
+		return "已完成"
+	case constants.ExchangeStatusCancelled:
+		return "已取消"
+	default:
+		return "未知状态"
+	}
+}

internal/service/iot_card/stop_resume_service.go

@@ -264,15 +264,18 @@ func (s *StopResumeService) ManualStopCard(ctx context.Context, iccid string) er
 	}
 
 	if err := s.stopCardWithRetry(ctx, card); err != nil {
-		return errors.Wrap(errors.CodeInternalError, err, "调网关停机失败")
+		return errors.Wrap(errors.CodeGatewayError, err, "调用运营商停机失败，请稍后重试")
 	}
 
 	now := time.Now()
-	return s.db.WithContext(ctx).Model(card).Updates(map[string]any{
+	if err := s.db.WithContext(ctx).Model(card).Updates(map[string]any{
 		"network_status": constants.NetworkStatusOffline,
 		"stopped_at":     now,
 		"stop_reason":    constants.StopReasonManual,
-	}).Error
+	}).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "更新卡状态失败")
+	}
+	return nil
 }
 
 // ManualStartCard 手动复机单张卡（通过ICCID）
@@ -300,13 +303,16 @@ func (s *StopResumeService) ManualStartCard(ctx context.Context, iccid string) e
 	}
 
 	if err := s.resumeCardWithRetry(ctx, card); err != nil {
-		return errors.Wrap(errors.CodeInternalError, err, "调网关复机失败")
+		return errors.Wrap(errors.CodeGatewayError, err, "调用运营商复机失败，请稍后重试")
 	}
 
 	now := time.Now()
-	return s.db.WithContext(ctx).Model(card).Updates(map[string]any{
+	if err := s.db.WithContext(ctx).Model(card).Updates(map[string]any{
 		"network_status": constants.NetworkStatusOnline,
 		"resumed_at":     now,
 		"stop_reason":    "",
-	}).Error
+	}).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "更新卡状态失败")
+	}
+	return nil
 }

internal/service/order/service.go

@@ -564,6 +564,17 @@ func (s *Service) CreateAdminOrder(ctx context.Context, req *dto.CreateAdminOrde
 		}
 	}
 
+	// 从资产获取当前 generation（用于订单快照）
+	var assetGeneration int
+	if validationResult.Card != nil {
+		assetGeneration = validationResult.Card.Generation
+	} else if validationResult.Device != nil {
+		assetGeneration = validationResult.Device.Generation
+	}
+	if assetGeneration == 0 {
+		assetGeneration = 1
+	}
+
 	order := &model.Order{
 		BaseModel: model.BaseModel{
 			Creator: userID,
@@ -571,6 +582,8 @@ func (s *Service) CreateAdminOrder(ctx context.Context, req *dto.CreateAdminOrde
 		},
 		OrderNo:                 s.orderStore.GenerateOrderNo(),
 		OrderType:               req.OrderType,
+		Source:                  constants.OrderSourceAdmin,
+		Generation:              assetGeneration,
 		BuyerType:               orderBuyerType,
 		BuyerID:                 orderBuyerID,
 		IotCardID:               req.IotCardID,

internal/service/package/service.go

@@ -456,6 +456,42 @@ func (s *Service) UpdateShelfStatus(ctx context.Context, id uint, shelfStatus in
 	return nil
 }
 
+// UpdateRetailPrice 代理修改自己店铺的套餐零售价
+func (s *Service) UpdateRetailPrice(ctx context.Context, packageID uint, retailPrice int64) error {
+	currentUserID := middleware.GetUserIDFromContext(ctx)
+	if currentUserID == 0 {
+		return errors.New(errors.CodeUnauthorized, "未授权访问")
+	}
+
+	userType := middleware.GetUserTypeFromContext(ctx)
+	if userType != constants.UserTypeAgent {
+		return errors.New(errors.CodeForbidden, "仅代理用户可修改零售价")
+	}
+
+	shopID := middleware.GetShopIDFromContext(ctx)
+	if shopID == 0 {
+		return errors.New(errors.CodeUnauthorized, "当前用户不属于任何店铺")
+	}
+
+	allocation, err := s.packageAllocationStore.GetByShopAndPackage(ctx, shopID, packageID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return errors.New(errors.CodeNotFound, "该套餐未分配给您")
+		}
+		return errors.Wrap(errors.CodeInternalError, err, "获取分配记录失败")
+	}
+
+	if retailPrice < allocation.CostPrice {
+		return errors.New(errors.CodeInvalidParam, "零售价不能低于成本价")
+	}
+
+	if err := s.packageAllocationStore.UpdateRetailPrice(ctx, allocation.ID, retailPrice, currentUserID); err != nil {
+		return errors.Wrap(errors.CodeInternalError, err, "更新零售价失败")
+	}
+
+	return nil
+}
+
 // updateAgentShelfStatus 代理上下架路径：更新分配记录的 shelf_status
 func (s *Service) updateAgentShelfStatus(ctx context.Context, packageID uint, shelfStatus int, updaterID uint) error {
 	shopID := middleware.GetShopIDFromContext(ctx)
@@ -533,9 +569,9 @@ func (s *Service) toResponse(ctx context.Context, pkg *model.Package) *dto.Packa
 		allocation, err := s.packageAllocationStore.GetByShopAndPackage(ctx, shopID, pkg.ID)
 		if err == nil && allocation != nil {
 			resp.CostPrice = allocation.CostPrice
-			profitMargin := pkg.SuggestedRetailPrice - allocation.CostPrice
+			resp.RetailPrice = &allocation.RetailPrice
+			profitMargin := allocation.RetailPrice - allocation.CostPrice
 			resp.ProfitMargin = &profitMargin
-			// 代理查询时，shelf_status 返回自己分配记录的值，而非平台全局值
 			resp.ShelfStatus = allocation.ShelfStatus
 		}
 	}
@@ -595,9 +631,9 @@ func (s *Service) toResponseWithAllocation(_ context.Context, pkg *model.Package
 	if allocationMap != nil {
 		if allocation, ok := allocationMap[pkg.ID]; ok {
 			resp.CostPrice = allocation.CostPrice
-			profitMargin := pkg.SuggestedRetailPrice - allocation.CostPrice
+			resp.RetailPrice = &allocation.RetailPrice
+			profitMargin := allocation.RetailPrice - allocation.CostPrice
 			resp.ProfitMargin = &profitMargin
-			// 代理查询时，shelf_status 返回自己分配记录的值，而非平台全局值
 			resp.ShelfStatus = allocation.ShelfStatus
 		}
 	}

internal/service/personal_customer/service.go

@@ -1,17 +1,12 @@
-// Package personal_customer 提供个人客户管理的业务逻辑服务
-// 包含个人客户注册、登录、微信绑定、短信验证等功能
+// Package personal_customer 提供个人客户资料管理的业务逻辑服务
 package personal_customer
 
 import (
 	"context"
 
 	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/internal/model/dto"
-	"github.com/break/junhong_cmp_fiber/internal/service/verification"
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
-	"github.com/break/junhong_cmp_fiber/pkg/auth"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/wechat"
 	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
@@ -20,9 +15,6 @@ import (
 type Service struct {
 	store      *postgres.PersonalCustomerStore
 	phoneStore *postgres.PersonalCustomerPhoneStore
-	verificationService   *verification.Service
-	jwtManager            *auth.JWTManager
-	wechatOfficialAccount wechat.OfficialAccountServiceInterface
 	logger     *zap.Logger
 }
 
@@ -30,140 +22,15 @@ type Service struct {
 func NewService(
 	store *postgres.PersonalCustomerStore,
 	phoneStore *postgres.PersonalCustomerPhoneStore,
-	verificationService *verification.Service,
-	jwtManager *auth.JWTManager,
-	wechatOfficialAccount wechat.OfficialAccountServiceInterface,
 	logger *zap.Logger,
 ) *Service {
 	return &Service{
 		store:      store,
 		phoneStore: phoneStore,
-		verificationService:   verificationService,
-		jwtManager:            jwtManager,
-		wechatOfficialAccount: wechatOfficialAccount,
 		logger:     logger,
 	}
 }
 
-// SendVerificationCode 发送验证码
-func (s *Service) SendVerificationCode(ctx context.Context, phone string) error {
-	return s.verificationService.SendCode(ctx, phone)
-}
-
-// VerifyCode 验证验证码
-func (s *Service) VerifyCode(ctx context.Context, phone string, code string) error {
-	return s.verificationService.VerifyCode(ctx, phone, code)
-}
-
-// LoginByPhone 通过手机号登录
-// 如果手机号不存在，自动创建新的个人客户
-// 注意：此方法是临时实现，完整的登录流程应该是先微信授权，再绑定手机号
-func (s *Service) LoginByPhone(ctx context.Context, phone string, code string) (string, *model.PersonalCustomer, error) {
-	// 验证验证码
-	if err := s.verificationService.VerifyCode(ctx, phone, code); err != nil {
-		s.logger.Warn("验证码验证失败",
-			zap.String("phone", phone),
-			zap.Error(err),
-		)
-		return "", nil, err
-	}
-
-	// 查找或创建个人客户
-	customer, err := s.store.GetByPhone(ctx, phone)
-	if err != nil {
-		if err == gorm.ErrRecordNotFound {
-			// 客户不存在，创建新客户
-			// 注意：临时实现，使用空的微信信息（正式应该先微信授权）
-			customer = &model.PersonalCustomer{
-				WxOpenID:  "", // 临时为空，后续需绑定微信
-				WxUnionID: "", // 临时为空，后续需绑定微信
-				Status:    1,  // 默认启用
-			}
-			if err := s.store.Create(ctx, customer); err != nil {
-				s.logger.Error("创建个人客户失败",
-					zap.String("phone", phone),
-					zap.Error(err),
-				)
-				return "", nil, errors.Wrap(errors.CodeInternalError, err, "创建个人客户失败")
-			}
-
-			// 创建手机号绑定记录
-			// TODO: 这里需要通过 PersonalCustomerPhoneStore 来创建
-			// 暂时跳过，等待 PersonalCustomerPhoneStore 实现
-
-			s.logger.Info("创建新个人客户",
-				zap.Uint("customer_id", customer.ID),
-				zap.String("phone", phone),
-			)
-		} else {
-			s.logger.Error("查询个人客户失败",
-				zap.String("phone", phone),
-				zap.Error(err),
-			)
-			return "", nil, errors.Wrap(errors.CodeInternalError, err, "查询个人客户失败")
-		}
-	}
-
-	// 检查客户状态
-	if customer.Status == 0 {
-		s.logger.Warn("个人客户已被禁用",
-			zap.Uint("customer_id", customer.ID),
-			zap.String("phone", phone),
-		)
-		return "", nil, errors.New(errors.CodeForbidden, "账号已被禁用")
-	}
-
-	// 生成 Token（临时传递 phone，后续应该从 Token 中移除 phone 字段）
-	token, err := s.jwtManager.GeneratePersonalCustomerToken(customer.ID, phone)
-	if err != nil {
-		s.logger.Error("生成 Token 失败",
-			zap.Uint("customer_id", customer.ID),
-			zap.String("phone", phone),
-			zap.Error(err),
-		)
-		return "", nil, errors.Wrap(errors.CodeInternalError, err, "生成 Token 失败")
-	}
-
-	s.logger.Info("个人客户登录成功",
-		zap.Uint("customer_id", customer.ID),
-		zap.String("phone", phone),
-	)
-
-	return token, customer, nil
-}
-
-// BindWechat 绑定微信信息
-func (s *Service) BindWechat(ctx context.Context, customerID uint, wxOpenID, wxUnionID string) error {
-	// 获取客户
-	customer, err := s.store.GetByID(ctx, customerID)
-	if err != nil {
-		s.logger.Error("查询个人客户失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "查询个人客户失败")
-	}
-
-	// 更新微信信息
-	customer.WxOpenID = wxOpenID
-	customer.WxUnionID = wxUnionID
-
-	if err := s.store.Update(ctx, customer); err != nil {
-		s.logger.Error("更新微信信息失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "更新微信信息失败")
-	}
-
-	s.logger.Info("绑定微信信息成功",
-		zap.Uint("customer_id", customerID),
-		zap.String("wx_open_id", wxOpenID),
-	)
-
-	return nil
-}
-
 // UpdateProfile 更新个人资料
 func (s *Service) UpdateProfile(ctx context.Context, customerID uint, nickname, avatarURL string) error {
 	customer, err := s.store.GetByID(ctx, customerID)
@@ -198,20 +65,6 @@ func (s *Service) UpdateProfile(ctx context.Context, customerID uint, nickname,
 	return nil
 }
 
-// GetProfile 获取个人资料
-func (s *Service) GetProfile(ctx context.Context, customerID uint) (*model.PersonalCustomer, error) {
-	customer, err := s.store.GetByID(ctx, customerID)
-	if err != nil {
-		s.logger.Error("查询个人客户失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return nil, errors.Wrap(errors.CodeInternalError, err, "查询个人客户失败")
-	}
-
-	return customer, nil
-}
-
 // GetProfileWithPhone 获取个人资料（包含主手机号）
 func (s *Service) GetProfileWithPhone(ctx context.Context, customerID uint) (*model.PersonalCustomer, string, error) {
 	// 获取客户信息
@@ -241,190 +94,3 @@ func (s *Service) GetProfileWithPhone(ctx context.Context, customerID uint) (*mo
 
 	return customer, phone, nil
 }
-
-// WechatOAuthLogin 微信 OAuth 登录
-// 通过微信授权码登录，如果用户不存在则自动创建
-func (s *Service) WechatOAuthLogin(ctx context.Context, code string) (*dto.WechatOAuthResponse, error) {
-	// 检查微信服务是否已配置
-	if s.wechatOfficialAccount == nil {
-		s.logger.Error("微信公众号服务未配置")
-		return nil, errors.New(errors.CodeWechatOAuthFailed, "微信服务未配置")
-	}
-
-	// 通过授权码获取用户详细信息
-	userInfo, err := s.wechatOfficialAccount.GetUserInfoDetailed(ctx, code)
-	if err != nil {
-		s.logger.Error("获取微信用户信息失败",
-			zap.String("code", code),
-			zap.Error(err),
-		)
-		return nil, err
-	}
-
-	// 通过 OpenID 查找现有客户
-	customer, err := s.store.GetByWxOpenID(ctx, userInfo.OpenID)
-	if err != nil {
-		if err == gorm.ErrRecordNotFound {
-			// 客户不存在，创建新客户
-			customer = &model.PersonalCustomer{
-				WxOpenID:  userInfo.OpenID,
-				WxUnionID: userInfo.UnionID,
-				Nickname:  userInfo.Nickname,
-				AvatarURL: userInfo.Avatar,
-				Status:    1, // 默认启用
-			}
-			if err := s.store.Create(ctx, customer); err != nil {
-				s.logger.Error("创建微信用户失败",
-					zap.String("open_id", userInfo.OpenID),
-					zap.Error(err),
-				)
-				return nil, errors.Wrap(errors.CodeInternalError, err, "创建用户失败")
-			}
-			s.logger.Info("通过微信创建新用户",
-				zap.Uint("customer_id", customer.ID),
-				zap.String("open_id", userInfo.OpenID),
-			)
-		} else {
-			s.logger.Error("查询微信用户失败",
-				zap.String("open_id", userInfo.OpenID),
-				zap.Error(err),
-			)
-			return nil, errors.Wrap(errors.CodeInternalError, err, "查询用户失败")
-		}
-	} else {
-		// 客户已存在，更新昵称和头像（如果有变化）
-		needUpdate := false
-		if userInfo.Nickname != "" && customer.Nickname != userInfo.Nickname {
-			customer.Nickname = userInfo.Nickname
-			needUpdate = true
-		}
-		if userInfo.Avatar != "" && customer.AvatarURL != userInfo.Avatar {
-			customer.AvatarURL = userInfo.Avatar
-			needUpdate = true
-		}
-		if needUpdate {
-			if err := s.store.Update(ctx, customer); err != nil {
-				s.logger.Warn("更新微信用户信息失败",
-					zap.Uint("customer_id", customer.ID),
-					zap.Error(err),
-				)
-				// 不阻断登录流程
-			}
-		}
-	}
-
-	// 检查客户状态
-	if customer.Status == 0 {
-		s.logger.Warn("微信用户已被禁用",
-			zap.Uint("customer_id", customer.ID),
-			zap.String("open_id", userInfo.OpenID),
-		)
-		return nil, errors.New(errors.CodeForbidden, "账号已被禁用")
-	}
-
-	// 生成 JWT Token
-	token, err := s.jwtManager.GeneratePersonalCustomerToken(customer.ID, "")
-	if err != nil {
-		s.logger.Error("生成 Token 失败",
-			zap.Uint("customer_id", customer.ID),
-			zap.Error(err),
-		)
-		return nil, errors.Wrap(errors.CodeInternalError, err, "生成 Token 失败")
-	}
-
-	// 获取主手机号（如果有）
-	phone := ""
-	primaryPhone, err := s.phoneStore.GetPrimaryPhone(ctx, customer.ID)
-	if err == nil {
-		phone = primaryPhone.Phone
-	}
-
-	s.logger.Info("微信 OAuth 登录成功",
-		zap.Uint("customer_id", customer.ID),
-		zap.String("open_id", userInfo.OpenID),
-	)
-
-	return &dto.WechatOAuthResponse{
-		AccessToken: token,
-		ExpiresIn:   24 * 60 * 60, // 24 小时
-		Customer: &dto.PersonalCustomerResponse{
-			ID:        customer.ID,
-			Phone:     phone,
-			Nickname:  customer.Nickname,
-			AvatarURL: customer.AvatarURL,
-			WxOpenID:  customer.WxOpenID,
-			WxUnionID: customer.WxUnionID,
-			Status:    customer.Status,
-			CreatedAt: customer.CreatedAt.Format("2006-01-02 15:04:05"),
-			UpdatedAt: customer.UpdatedAt.Format("2006-01-02 15:04:05"),
-		},
-	}, nil
-}
-
-// BindWechatWithCode 通过微信授权码绑定微信
-// customerID: 当前登录的客户 ID
-// code: 微信授权码
-func (s *Service) BindWechatWithCode(ctx context.Context, customerID uint, code string) error {
-	// 检查微信服务是否已配置
-	if s.wechatOfficialAccount == nil {
-		s.logger.Error("微信公众号服务未配置")
-		return errors.New(errors.CodeWechatOAuthFailed, "微信服务未配置")
-	}
-
-	// 获取客户信息
-	customer, err := s.store.GetByID(ctx, customerID)
-	if err != nil {
-		s.logger.Error("查询个人客户失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "查询客户失败")
-	}
-
-	// 获取微信用户信息
-	userInfo, err := s.wechatOfficialAccount.GetUserInfoDetailed(ctx, code)
-	if err != nil {
-		s.logger.Error("获取微信用户信息失败",
-			zap.Uint("customer_id", customerID),
-			zap.String("code", code),
-			zap.Error(err),
-		)
-		return err
-	}
-
-	// 检查该 OpenID 是否已被其他用户绑定
-	existingCustomer, err := s.store.GetByWxOpenID(ctx, userInfo.OpenID)
-	if err == nil && existingCustomer.ID != customerID {
-		s.logger.Warn("微信账号已被其他用户绑定",
-			zap.Uint("customer_id", customerID),
-			zap.Uint("existing_customer_id", existingCustomer.ID),
-			zap.String("open_id", userInfo.OpenID),
-		)
-		return errors.New(errors.CodeConflict, "该微信账号已被其他用户绑定")
-	}
-
-	// 更新微信信息
-	customer.WxOpenID = userInfo.OpenID
-	customer.WxUnionID = userInfo.UnionID
-	if userInfo.Nickname != "" {
-		customer.Nickname = userInfo.Nickname
-	}
-	if userInfo.Avatar != "" {
-		customer.AvatarURL = userInfo.Avatar
-	}
-
-	if err := s.store.Update(ctx, customer); err != nil {
-		s.logger.Error("绑定微信信息失败",
-			zap.Uint("customer_id", customerID),
-			zap.Error(err),
-		)
-		return errors.Wrap(errors.CodeInternalError, err, "绑定微信失败")
-	}
-
-	s.logger.Info("绑定微信成功",
-		zap.Uint("customer_id", customerID),
-		zap.String("open_id", userInfo.OpenID),
-	)
-
-	return nil
-}

internal/service/purchase_validation/service.go

@@ -133,44 +133,57 @@ func (s *Service) validatePackages(ctx context.Context, packageIDs []uint, serie
 		}
 
 		if sellerShopID > 0 {
-			// 代理渠道：检查卖家代理的 allocation.shelf_status，不检查 package.shelf_status
-			if err := s.validateAgentShelfStatus(ctx, sellerShopID, pkgID); err != nil {
-				return nil, 0, err
+			// 代理渠道：检查上架状态并获取分配记录，使用零售价
+			allocation, allocErr := s.validateAgentAllocation(ctx, sellerShopID, pkgID)
+			if allocErr != nil {
+				return nil, 0, allocErr
 			}
+			// 零售价低于成本价时视为不可购买，防止亏损售卖
+			if allocation.RetailPrice < allocation.CostPrice {
+				return nil, 0, errors.New(errors.CodeInvalidParam, "套餐价格配置异常，暂不可购买")
+			}
+			totalPrice += allocation.RetailPrice
 		} else {
-			// 平台自营渠道：检查 package.shelf_status
 			if pkg.ShelfStatus != constants.ShelfStatusOn {
 				return nil, 0, errors.New(errors.CodeInvalidParam, "套餐已下架")
 			}
+			totalPrice += pkg.SuggestedRetailPrice
 		}
 
 		packages = append(packages, pkg)
-		totalPrice += pkg.SuggestedRetailPrice
 	}
 
 	return packages, totalPrice, nil
 }
 
-// validateAgentShelfStatus 校验卖家代理的分配记录上架状态
-func (s *Service) validateAgentShelfStatus(ctx context.Context, sellerShopID, packageID uint) error {
-	// 使用不带数据权限过滤的查询，避免 buyer ctx 的权限限制干扰系统级校验
+// validateAgentAllocation 校验卖家代理的分配记录上架状态，并返回分配记录
+func (s *Service) validateAgentAllocation(ctx context.Context, sellerShopID, packageID uint) (*model.ShopPackageAllocation, error) {
 	allocation, err := s.packageAllocationStore.GetByShopAndPackageForSystem(ctx, sellerShopID, packageID)
 	if err != nil {
 		if err == gorm.ErrRecordNotFound {
-			return errors.New(errors.CodeInvalidParam, "套餐已下架")
+			return nil, errors.New(errors.CodeInvalidParam, "套餐已下架")
 		}
-		return errors.Wrap(errors.CodeInternalError, err, "查询套餐分配记录失败")
+		return nil, errors.Wrap(errors.CodeInternalError, err, "查询套餐分配记录失败")
 	}
 
 	if allocation.ShelfStatus != constants.ShelfStatusOn {
-		return errors.New(errors.CodeInvalidParam, "套餐已下架")
+		return nil, errors.New(errors.CodeInvalidParam, "套餐已下架")
 	}
 
-	return nil
+	return allocation, nil
 }
 
-func (s *Service) GetPurchasePrice(ctx context.Context, pkg *model.Package, buyerType string) int64 {
-	return pkg.SuggestedRetailPrice
+// GetPurchasePrice 获取购买价格
+// 代理渠道（sellerShopID > 0）返回 allocation.RetailPrice，平台渠道返回 Package.SuggestedRetailPrice
+func (s *Service) GetPurchasePrice(ctx context.Context, pkg *model.Package, sellerShopID uint) (int64, error) {
+	if sellerShopID > 0 {
+		allocation, err := s.packageAllocationStore.GetByShopAndPackageForSystem(ctx, sellerShopID, pkg.ID)
+		if err != nil {
+			return 0, errors.Wrap(errors.CodeInternalError, err, "查询套餐分配记录失败")
+		}
+		return allocation.RetailPrice, nil
+	}
+	return pkg.SuggestedRetailPrice, nil
 }
 
 // ValidateAdminOfflineCardPurchase 后台 offline 订单专用卡验证

internal/service/recharge/service.go

@@ -306,18 +306,17 @@ func (s *Service) HandlePaymentCallback(ctx context.Context, rechargeNo string,
 	// 6. 事务处理：更新订单状态、增加余额、更新累计充值、触发佣金
 	now := time.Now()
 	err = s.db.Transaction(func(tx *gorm.DB) error {
-		// 6.1 更新充值订单状态（带状态检查，实现乐观锁）
+		// 6.1 更新充值订单状态（带状态检查，使用事务内 tx 确保原子性）
 		oldStatus := constants.RechargeStatusPending
-		if err := s.assetRechargeStore.UpdateStatusWithOptimisticLock(ctx, recharge.ID, &oldStatus, constants.RechargeStatusPaid, &now, nil); err != nil {
+		if err := s.assetRechargeStore.UpdateStatusWithOptimisticLockDB(ctx, tx, recharge.ID, &oldStatus, constants.RechargeStatusPaid, &now, nil); err != nil {
 			if err == gorm.ErrRecordNotFound {
-				// 状态已变更，幂等处理
 				return nil
 			}
 			return errors.Wrap(errors.CodeDatabaseError, err, "更新充值订单状态失败")
 		}
 
-		// 6.2 更新支付信息
-		if err := s.assetRechargeStore.UpdatePaymentInfo(ctx, recharge.ID, &paymentMethod, &paymentTransactionID); err != nil {
+		// 6.2 更新支付信息（使用事务内 tx）
+		if err := s.assetRechargeStore.UpdatePaymentInfoWithDB(ctx, tx, recharge.ID, &paymentMethod, &paymentTransactionID); err != nil {
 			return errors.Wrap(errors.CodeDatabaseError, err, "更新支付信息失败")
 		}
 

internal/service/shop/service.go

@@ -20,6 +20,7 @@ type Service struct {
 	shopRoleStore    *postgres.ShopRoleStore
 	roleStore        *postgres.RoleStore
 	accountRoleStore *postgres.AccountRoleStore
+	agentWalletStore *postgres.AgentWalletStore
 }
 
 func New(
@@ -28,6 +29,7 @@ func New(
 	shopRoleStore *postgres.ShopRoleStore,
 	roleStore *postgres.RoleStore,
 	accountRoleStore *postgres.AccountRoleStore,
+	agentWalletStore *postgres.AgentWalletStore,
 ) *Service {
 	return &Service{
 		shopStore:        shopStore,
@@ -35,6 +37,7 @@ func New(
 		shopRoleStore:    shopRoleStore,
 		roleStore:        roleStore,
 		accountRoleStore: accountRoleStore,
+		agentWalletStore: agentWalletStore,
 	}
 }
 
@@ -147,6 +150,32 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateShopRequest) (*dto.
 		return nil, errors.Wrap(errors.CodeInternalError, err, "设置店铺默认角色失败")
 	}
 
+	// 初始化店铺代理钱包：主钱包 + 分佣钱包
+	// 新店铺必须有两个钱包才能参与充值和分佣体系
+	wallets := []*model.AgentWallet{
+		{
+			ShopID:     shop.ID,
+			WalletType: constants.AgentWalletTypeMain,
+			Balance:    0,
+			Currency:   "CNY",
+			Status:     constants.AgentWalletStatusNormal,
+			ShopIDTag:  shop.ID,
+		},
+		{
+			ShopID:     shop.ID,
+			WalletType: constants.AgentWalletTypeCommission,
+			Balance:    0,
+			Currency:   "CNY",
+			Status:     constants.AgentWalletStatusNormal,
+			ShopIDTag:  shop.ID,
+		},
+	}
+	for _, wallet := range wallets {
+		if err := s.agentWalletStore.Create(ctx, wallet); err != nil {
+			return nil, errors.Wrap(errors.CodeInternalError, err, "初始化店铺钱包失败")
+		}
+	}
+
 	return &dto.ShopResponse{
 		ID:           shop.ID,
 		ShopName:     shop.ShopName,

internal/service/shop_package_batch_allocation/service.go

@@ -95,6 +95,7 @@ func (s *Service) BatchAllocate(ctx context.Context, req *dto.BatchAllocatePacka
 				PackageID:          pkg.ID,
 				AllocatorShopID:    allocatorShopID,
 				CostPrice:          costPrice,
+				RetailPrice:        pkg.SuggestedRetailPrice,
 				SeriesAllocationID: &seriesAllocation.ID,
 				Status:             constants.StatusEnabled,
 			}

internal/service/shop_package_batch_pricing/service.go

@@ -67,18 +67,30 @@ func (s *Service) BatchUpdatePricing(ctx context.Context, req *dto.BatchUpdateCo
 
 	updatedCount := 0
 	now := time.Now()
-
 	affectedIDs := make([]uint, 0)
+	skipped := make([]dto.BatchPricingSkipped, 0)
 
 	err = s.db.Transaction(func(tx *gorm.DB) error {
 		for _, allocation := range allocations {
 			oldPrice := allocation.CostPrice
 			newPrice := s.calculateAdjustedPrice(oldPrice, &req.PriceAdjustment)
-
 			if newPrice == oldPrice {
 				continue
 			}
 
+			// cost_price 锁定检查：存在下级分配记录时跳过
+			var subCount int64
+			tx.Model(&model.ShopPackageAllocation{}).
+				Where("allocator_shop_id = ? AND package_id = ? AND deleted_at IS NULL", allocation.ShopID, allocation.PackageID).
+				Count(&subCount)
+			if subCount > 0 {
+				skipped = append(skipped, dto.BatchPricingSkipped{
+					AllocationID: allocation.ID,
+					Reason:       "存在下级分配记录，请先回收后再修改成本价",
+				})
+				continue
+			}
+
 			history := &model.ShopPackageAllocationPriceHistory{
 				AllocationID:  allocation.ID,
 				OldCostPrice:  oldPrice,
@@ -87,7 +99,6 @@ func (s *Service) BatchUpdatePricing(ctx context.Context, req *dto.BatchUpdateCo
 				ChangedBy:     currentUserID,
 				EffectiveFrom: now,
 			}
-
 			if err := tx.Create(history).Error; err != nil {
 				return errors.Wrap(errors.CodeInternalError, err, "创建价格历史失败")
 			}
@@ -112,6 +123,7 @@ func (s *Service) BatchUpdatePricing(ctx context.Context, req *dto.BatchUpdateCo
 	return &dto.BatchUpdateCostPriceResponse{
 		UpdatedCount: updatedCount,
 		AffectedIDs:  affectedIDs,
+		Skipped:      skipped,
 	}, nil
 }
 

internal/service/shop_series_grant/service.go

@@ -332,6 +332,7 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateShopSeriesGrantRequ
 					PackageID:          item.PackageID,
 					AllocatorShopID:    allocatorShopID,
 					CostPrice:          item.CostPrice,
+					RetailPrice:        pkg.SuggestedRetailPrice,
 					SeriesAllocationID: &allocation.ID,
 					Status:             constants.StatusEnabled,
 					ShelfStatus:        constants.StatusEnabled,
@@ -341,7 +342,6 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateShopSeriesGrantRequ
 				if err := txPkgStore.Create(ctx, pkgAlloc); err != nil {
 					return errors.Wrap(errors.CodeDatabaseError, err, "创建套餐分配失败")
 				}
-				// 写成本价历史
 				_ = txHistoryStore.Create(ctx, &model.ShopPackageAllocationPriceHistory{
 					AllocationID:  pkgAlloc.ID,
 					OldCostPrice:  0,
@@ -632,6 +632,16 @@ func (s *Service) ManagePackages(ctx context.Context, id uint, req *dto.ManageGr
 			if findErr == nil {
 				// 已有记录：更新成本价并写历史
 				oldPrice := existing.CostPrice
+				if oldPrice != item.CostPrice {
+					// cost_price 锁定检查：存在下级分配记录时禁止修改
+					var subCount int64
+					tx.Model(&model.ShopPackageAllocation{}).
+						Where("allocator_shop_id = ? AND package_id = ? AND deleted_at IS NULL", allocation.ShopID, item.PackageID).
+						Count(&subCount)
+					if subCount > 0 {
+						return errors.New(errors.CodeForbidden, "存在下级分配记录，请先回收后再修改成本价")
+					}
+				}
 				existing.CostPrice = item.CostPrice
 				existing.Updater = operatorID
 				if updateErr := txPkgStore.Update(ctx, existing); updateErr != nil {
@@ -648,24 +658,22 @@ func (s *Service) ManagePackages(ctx context.Context, id uint, req *dto.ManageGr
 					})
 				}
 			} else {
-			// W1: 校验套餐归属于该系列，防止跨系列套餐混入
 				pkg, pkgErr := s.packageStore.GetByID(ctx, item.PackageID)
 				if pkgErr != nil || pkg.SeriesID != allocation.SeriesID {
 					return errors.New(errors.CodeInvalidParam, "套餐不属于该系列，无法添加到此授权")
 				}
-			// W2: 代理操作时，校验分配者已拥有此套餐授权，防止越权分配
 				if allocation.AllocatorShopID > 0 {
 					_, authErr := s.shopPackageAllocationStore.GetByShopAndPackageForSystem(ctx, allocation.AllocatorShopID, item.PackageID)
 					if authErr != nil {
 						return errors.New(errors.CodeForbidden, "无权限分配该套餐")
 					}
 				}
-				// 新建分配
 				pkgAlloc := &model.ShopPackageAllocation{
 					ShopID:             allocation.ShopID,
 					PackageID:          item.PackageID,
 					AllocatorShopID:    allocation.AllocatorShopID,
 					CostPrice:          item.CostPrice,
+					RetailPrice:        pkg.SuggestedRetailPrice,
 					SeriesAllocationID: &allocation.ID,
 					Status:             constants.StatusEnabled,
 					ShelfStatus:        constants.StatusEnabled,

internal/store/postgres/asset_recharge_store.go

@@ -189,6 +189,11 @@ func (s *AssetRechargeStore) List(ctx context.Context, params *ListAssetRecharge
 
 // UpdatePaymentInfo 更新支付信息
 func (s *AssetRechargeStore) UpdatePaymentInfo(ctx context.Context, id uint, paymentMethod *string, paymentTransactionID *string) error {
+	return s.UpdatePaymentInfoWithDB(ctx, s.db, id, paymentMethod, paymentTransactionID)
+}
+
+// UpdatePaymentInfoWithDB 更新支付信息（支持传入事务 tx）
+func (s *AssetRechargeStore) UpdatePaymentInfoWithDB(ctx context.Context, db *gorm.DB, id uint, paymentMethod *string, paymentTransactionID *string) error {
 	updates := map[string]interface{}{}
 	if paymentMethod != nil {
 		updates["payment_method"] = paymentMethod
@@ -201,7 +206,7 @@ func (s *AssetRechargeStore) UpdatePaymentInfo(ctx context.Context, id uint, pay
 		return nil
 	}
 
-	result := s.db.WithContext(ctx).Model(&model.AssetRechargeRecord{}).Where("id = ?", id).Updates(updates)
+	result := db.WithContext(ctx).Model(&model.AssetRechargeRecord{}).Where("id = ?", id).Updates(updates)
 	if result.Error != nil {
 		return result.Error
 	}
@@ -213,6 +218,11 @@ func (s *AssetRechargeStore) UpdatePaymentInfo(ctx context.Context, id uint, pay
 
 // UpdateStatusWithOptimisticLock 更新充值状态（支持乐观锁）
 func (s *AssetRechargeStore) UpdateStatusWithOptimisticLock(ctx context.Context, id uint, oldStatus *int, newStatus int, paidAt interface{}, completedAt interface{}) error {
+	return s.UpdateStatusWithOptimisticLockDB(ctx, s.db, id, oldStatus, newStatus, paidAt, completedAt)
+}
+
+// UpdateStatusWithOptimisticLockDB 更新充值状态（支持传入事务 tx）
+func (s *AssetRechargeStore) UpdateStatusWithOptimisticLockDB(ctx context.Context, db *gorm.DB, id uint, oldStatus *int, newStatus int, paidAt interface{}, completedAt interface{}) error {
 	updates := map[string]interface{}{
 		"status": newStatus,
 	}
@@ -223,7 +233,7 @@ func (s *AssetRechargeStore) UpdateStatusWithOptimisticLock(ctx context.Context,
 		updates["completed_at"] = completedAt
 	}
 
-	query := s.db.WithContext(ctx).Model(&model.AssetRechargeRecord{}).Where("id = ?", id)
+	query := db.WithContext(ctx).Model(&model.AssetRechargeRecord{}).Where("id = ?", id)
 
 	if oldStatus != nil {
 		query = query.Where("status = ?", *oldStatus)

internal/store/postgres/exchange_order_store.go

@@ -0,0 +1,106 @@
+package postgres
+
+import (
+	"context"
+	"maps"
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"gorm.io/gorm"
+)
+
+type ExchangeOrderStore struct {
+	db *gorm.DB
+}
+
+func NewExchangeOrderStore(db *gorm.DB) *ExchangeOrderStore {
+	return &ExchangeOrderStore{db: db}
+}
+
+func (s *ExchangeOrderStore) Create(ctx context.Context, order *model.ExchangeOrder) error {
+	return s.db.WithContext(ctx).Create(order).Error
+}
+
+func (s *ExchangeOrderStore) GetByID(ctx context.Context, id uint) (*model.ExchangeOrder, error) {
+	var order model.ExchangeOrder
+	query := s.db.WithContext(ctx).Where("id = ?", id)
+	query = middleware.ApplyShopFilter(ctx, query)
+	if err := query.First(&order).Error; err != nil {
+		return nil, err
+	}
+	return &order, nil
+}
+
+func (s *ExchangeOrderStore) List(ctx context.Context, filters map[string]any, page, pageSize int) ([]*model.ExchangeOrder, int64, error) {
+	var orders []*model.ExchangeOrder
+	var total int64
+
+	query := s.db.WithContext(ctx).Model(&model.ExchangeOrder{})
+	query = middleware.ApplyShopFilter(ctx, query)
+
+	if status, ok := filters["status"].(int); ok && status > 0 {
+		query = query.Where("status = ?", status)
+	}
+	if identifier, ok := filters["identifier"].(string); ok && identifier != "" {
+		like := "%" + identifier + "%"
+		query = query.Where("old_asset_identifier LIKE ? OR new_asset_identifier LIKE ?", like, like)
+	}
+	if createdAtStart, ok := filters["created_at_start"].(time.Time); ok && !createdAtStart.IsZero() {
+		query = query.Where("created_at >= ?", createdAtStart)
+	}
+	if createdAtEnd, ok := filters["created_at_end"].(time.Time); ok && !createdAtEnd.IsZero() {
+		query = query.Where("created_at <= ?", createdAtEnd)
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 {
+		pageSize = constants.DefaultPageSize
+	}
+	if pageSize > constants.MaxPageSize {
+		pageSize = constants.MaxPageSize
+	}
+
+	offset := (page - 1) * pageSize
+	if err := query.Order("created_at DESC").Offset(offset).Limit(pageSize).Find(&orders).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return orders, total, nil
+}
+
+func (s *ExchangeOrderStore) UpdateStatus(ctx context.Context, id uint, fromStatus, toStatus int, updates map[string]any) error {
+	values := make(map[string]any, len(updates)+1)
+	maps.Copy(values, updates)
+	values["status"] = toStatus
+
+	result := s.db.WithContext(ctx).Model(&model.ExchangeOrder{}).
+		Where("id = ? AND status = ?", id, fromStatus).
+		Updates(values)
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (s *ExchangeOrderStore) FindActiveByOldAsset(ctx context.Context, assetType string, assetID uint) (*model.ExchangeOrder, error) {
+	var order model.ExchangeOrder
+	query := s.db.WithContext(ctx).
+		Where("old_asset_type = ? AND old_asset_id = ?", assetType, assetID).
+		Where("status IN ?", []int{constants.ExchangeStatusPendingInfo, constants.ExchangeStatusPendingShip, constants.ExchangeStatusShipped})
+	query = middleware.ApplyShopFilter(ctx, query)
+	if err := query.Order("id DESC").First(&order).Error; err != nil {
+		return nil, err
+	}
+	return &order, nil
+}

internal/store/postgres/iot_card_store.go

@@ -644,14 +644,14 @@ func (s *IotCardStore) applyStandaloneFilters(ctx context.Context, query *gorm.D
 	if isReplaced, ok := filters["is_replaced"].(bool); ok {
 		if isReplaced {
 			query = query.Where("id IN (?)",
-				s.db.WithContext(ctx).Table("tb_card_replacement_record").
-					Select("old_iot_card_id").
-					Where("deleted_at IS NULL"))
+				s.db.WithContext(ctx).Table("tb_exchange_order").
+					Select("old_asset_id").
+					Where("old_asset_type = ? AND status IN ? AND deleted_at IS NULL", constants.ExchangeAssetTypeIotCard, []int{constants.ExchangeStatusShipped, constants.ExchangeStatusCompleted}))
 		} else {
 			query = query.Where("id NOT IN (?)",
-				s.db.WithContext(ctx).Table("tb_card_replacement_record").
-					Select("old_iot_card_id").
-					Where("deleted_at IS NULL"))
+				s.db.WithContext(ctx).Table("tb_exchange_order").
+					Select("old_asset_id").
+					Where("old_asset_type = ? AND status IN ? AND deleted_at IS NULL", constants.ExchangeAssetTypeIotCard, []int{constants.ExchangeStatusShipped, constants.ExchangeStatusCompleted}))
 		}
 	}
 	if seriesID, ok := filters["series_id"].(uint); ok && seriesID > 0 {
@@ -836,7 +836,7 @@ func (s *IotCardStore) ListBySeriesID(ctx context.Context, seriesID uint) ([]*mo
 func (s *IotCardStore) UpdateRechargeTrackingFields(ctx context.Context, cardID uint, accumulatedJSON, triggeredJSON string) error {
 	return s.db.WithContext(ctx).Model(&model.IotCard{}).
 		Where("id = ?", cardID).
-		Updates(map[string]interface{}{
+		Updates(map[string]any{
 			"accumulated_recharge_by_series":     accumulatedJSON,
 			"first_recharge_triggered_by_series": triggeredJSON,
 		}).Error
@@ -961,8 +961,8 @@ func hashFilters(filters map[string]any) string {
 
 	h := fnv.New32a()
 	for _, k := range keys {
-		h.Write([]byte(k))
-		h.Write([]byte(fmt.Sprint(filters[k])))
+		_, _ = h.Write([]byte(k))
+		_, _ = fmt.Fprint(h, filters[k])
 	}
 	return fmt.Sprintf("%08x", h.Sum32())
 }

internal/store/postgres/personal_customer_device_store.go

@@ -44,7 +44,7 @@ func (s *PersonalCustomerDeviceStore) GetByCustomerID(ctx context.Context, custo
 func (s *PersonalCustomerDeviceStore) GetByDeviceNo(ctx context.Context, deviceNo string) ([]*model.PersonalCustomerDevice, error) {
 	var records []*model.PersonalCustomerDevice
 	if err := s.db.WithContext(ctx).
-		Where("device_no = ?", deviceNo).
+		Where("virtual_no = ?", deviceNo).
 		Order("last_used_at DESC").
 		Find(&records).Error; err != nil {
 		return nil, err
@@ -56,7 +56,7 @@ func (s *PersonalCustomerDeviceStore) GetByDeviceNo(ctx context.Context, deviceN
 func (s *PersonalCustomerDeviceStore) GetByCustomerAndDevice(ctx context.Context, customerID uint, deviceNo string) (*model.PersonalCustomerDevice, error) {
 	var record model.PersonalCustomerDevice
 	if err := s.db.WithContext(ctx).
-		Where("customer_id = ? AND device_no = ?", customerID, deviceNo).
+		Where("customer_id = ? AND virtual_no = ?", customerID, deviceNo).
 		First(&record).Error; err != nil {
 		return nil, err
 	}
@@ -89,7 +89,7 @@ func (s *PersonalCustomerDeviceStore) ExistsByCustomerAndDevice(ctx context.Cont
 	var count int64
 	if err := s.db.WithContext(ctx).
 		Model(&model.PersonalCustomerDevice{}).
-		Where("customer_id = ? AND device_no = ? AND status = ?", customerID, deviceNo, 1).
+		Where("customer_id = ? AND virtual_no = ? AND status = ?", customerID, deviceNo, 1).
 		Count(&count).Error; err != nil {
 		return false, err
 	}

internal/store/postgres/personal_customer_openid_store.go

@@ -0,0 +1,58 @@
+package postgres
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"gorm.io/gorm"
+)
+
+// PersonalCustomerOpenIDStore 个人客户 OpenID 关联数据访问层
+type PersonalCustomerOpenIDStore struct {
+	db *gorm.DB
+}
+
+// NewPersonalCustomerOpenIDStore 创建个人客户 OpenID Store
+func NewPersonalCustomerOpenIDStore(db *gorm.DB) *PersonalCustomerOpenIDStore {
+	return &PersonalCustomerOpenIDStore{db: db}
+}
+
+// FindByAppIDAndOpenID 根据 AppID 和 OpenID 查询关联记录
+func (s *PersonalCustomerOpenIDStore) FindByAppIDAndOpenID(ctx context.Context, appID, openID string) (*model.PersonalCustomerOpenID, error) {
+	var record model.PersonalCustomerOpenID
+	if err := s.db.WithContext(ctx).
+		Where("app_id = ? AND open_id = ?", appID, openID).
+		First(&record).Error; err != nil {
+		return nil, err
+	}
+	return &record, nil
+}
+
+// FindByUnionID 根据 UnionID 查询首条关联记录
+func (s *PersonalCustomerOpenIDStore) FindByUnionID(ctx context.Context, unionID string) (*model.PersonalCustomerOpenID, error) {
+	var record model.PersonalCustomerOpenID
+	if err := s.db.WithContext(ctx).
+		Where("union_id = ?", unionID).
+		Order("id ASC").
+		First(&record).Error; err != nil {
+		return nil, err
+	}
+	return &record, nil
+}
+
+// Create 创建 OpenID 关联记录
+func (s *PersonalCustomerOpenIDStore) Create(ctx context.Context, record *model.PersonalCustomerOpenID) error {
+	return s.db.WithContext(ctx).Create(record).Error
+}
+
+// ListByCustomerID 根据客户 ID 查询所有 OpenID 关联记录
+func (s *PersonalCustomerOpenIDStore) ListByCustomerID(ctx context.Context, customerID uint) ([]*model.PersonalCustomerOpenID, error) {
+	var records []*model.PersonalCustomerOpenID
+	if err := s.db.WithContext(ctx).
+		Where("customer_id = ?", customerID).
+		Order("id ASC").
+		Find(&records).Error; err != nil {
+		return nil, err
+	}
+	return records, nil
+}

internal/store/postgres/resource_tag_store.go

@@ -0,0 +1,30 @@
+package postgres
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"gorm.io/gorm"
+)
+
+type ResourceTagStore struct {
+	db *gorm.DB
+}
+
+func NewResourceTagStore(db *gorm.DB) *ResourceTagStore {
+	return &ResourceTagStore{db: db}
+}
+
+func (s *ResourceTagStore) ListByResource(ctx context.Context, resourceType string, resourceID uint) ([]*model.ResourceTag, error) {
+	var list []*model.ResourceTag
+	if err := s.db.WithContext(ctx).
+		Where("resource_type = ? AND resource_id = ?", resourceType, resourceID).
+		Find(&list).Error; err != nil {
+		return nil, err
+	}
+	return list, nil
+}
+
+func (s *ResourceTagStore) Create(ctx context.Context, item *model.ResourceTag) error {
+	return s.db.WithContext(ctx).Create(item).Error
+}

internal/store/postgres/shop_package_allocation_store.go

@@ -139,6 +139,16 @@ func (s *ShopPackageAllocationStore) UpdateShelfStatus(ctx context.Context, id u
 		}).Error
 }
 
+func (s *ShopPackageAllocationStore) UpdateRetailPrice(ctx context.Context, id uint, retailPrice int64, updater uint) error {
+	return s.db.WithContext(ctx).
+		Model(&model.ShopPackageAllocation{}).
+		Where("id = ?", id).
+		Updates(map[string]interface{}{
+			"retail_price": retailPrice,
+			"updater":      updater,
+		}).Error
+}
+
 func (s *ShopPackageAllocationStore) GetByShopID(ctx context.Context, shopID uint) ([]*model.ShopPackageAllocation, error) {
 	var allocations []*model.ShopPackageAllocation
 	query := s.db.WithContext(ctx).Where("shop_id = ? AND status = 1", shopID)

internal/task/auto_purchase.go

@@ -0,0 +1,556 @@
+package task
+
+import (
+	"context"
+	"errors"
+	"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/internal/model"
+	packagepkg "github.com/break/junhong_cmp_fiber/internal/service/package"
+	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// AutoPurchasePayload 充值后自动购包任务载荷
+type AutoPurchasePayload struct {
+	RechargeRecordID uint `json:"recharge_record_id"`
+}
+
+// AutoPurchaseHandler 充值后自动购包任务处理器
+type AutoPurchaseHandler struct {
+	db                     *gorm.DB
+	orderStore             *postgres.OrderStore
+	rechargeRecordStore    *postgres.AssetRechargeStore
+	walletStore            *postgres.AssetWalletStore
+	walletTransactionStore *postgres.AssetWalletTransactionStore
+	packageUsageStore      *postgres.PackageUsageStore
+	redis                  *redis.Client
+	logger                 *zap.Logger
+}
+
+// NewAutoPurchaseHandler 创建充值后自动购包处理器
+func NewAutoPurchaseHandler(
+	db *gorm.DB,
+	orderStore *postgres.OrderStore,
+	rechargeRecordStore *postgres.AssetRechargeStore,
+	walletStore *postgres.AssetWalletStore,
+	walletTransactionStore *postgres.AssetWalletTransactionStore,
+	packageUsageStore *postgres.PackageUsageStore,
+	redisClient *redis.Client,
+	logger *zap.Logger,
+) *AutoPurchaseHandler {
+	if orderStore == nil {
+		orderStore = postgres.NewOrderStore(db, redisClient)
+	}
+	if rechargeRecordStore == nil {
+		rechargeRecordStore = postgres.NewAssetRechargeStore(db, redisClient)
+	}
+	if walletStore == nil {
+		walletStore = postgres.NewAssetWalletStore(db, redisClient)
+	}
+	if walletTransactionStore == nil {
+		walletTransactionStore = postgres.NewAssetWalletTransactionStore(db, redisClient)
+	}
+	if packageUsageStore == nil {
+		packageUsageStore = postgres.NewPackageUsageStore(db, redisClient)
+	}
+
+	return &AutoPurchaseHandler{
+		db:                     db,
+		orderStore:             orderStore,
+		rechargeRecordStore:    rechargeRecordStore,
+		walletStore:            walletStore,
+		walletTransactionStore: walletTransactionStore,
+		packageUsageStore:      packageUsageStore,
+		redis:                  redisClient,
+		logger:                 logger,
+	}
+}
+
+// ProcessTask 处理充值后自动购包任务
+func (h *AutoPurchaseHandler) ProcessTask(ctx context.Context, task *asynq.Task) error {
+	var payload AutoPurchasePayload
+	if err := sonic.Unmarshal(task.Payload(), &payload); err != nil {
+		h.logger.Error("解析自动购包任务载荷失败", zap.Error(err))
+		return asynq.SkipRetry
+	}
+	if payload.RechargeRecordID == 0 {
+		h.logger.Error("自动购包任务载荷无效", zap.Uint("recharge_record_id", payload.RechargeRecordID))
+		return asynq.SkipRetry
+	}
+
+	rechargeRecord, err := h.rechargeRecordStore.GetByID(ctx, payload.RechargeRecordID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			h.logger.Warn("充值记录不存在，跳过自动购包", zap.Uint("recharge_record_id", payload.RechargeRecordID))
+			return asynq.SkipRetry
+		}
+		h.logger.Error("查询充值记录失败", zap.Uint("recharge_record_id", payload.RechargeRecordID), zap.Error(err))
+		return err
+	}
+
+	if rechargeRecord.AutoPurchaseStatus == constants.AutoPurchaseStatusSuccess {
+		return nil
+	}
+	if rechargeRecord.AutoPurchaseStatus == constants.AutoPurchaseStatusFailed {
+		return nil
+	}
+
+	packageIDs, err := parseLinkedPackageIDs(rechargeRecord.LinkedPackageIDs)
+	if err != nil {
+		h.logger.Error("解析关联套餐ID失败", zap.Uint("recharge_record_id", rechargeRecord.ID), zap.Error(err))
+		h.markAutoPurchaseFailedIfFinalRetry(ctx, rechargeRecord.ID)
+		return asynq.SkipRetry
+	}
+	if len(packageIDs) == 0 {
+		h.logger.Error("关联套餐ID为空，无法自动购包", zap.Uint("recharge_record_id", rechargeRecord.ID))
+		h.markAutoPurchaseFailedIfFinalRetry(ctx, rechargeRecord.ID)
+		return asynq.SkipRetry
+	}
+
+	packages, totalAmount, err := h.loadPackages(ctx, packageIDs)
+	if err != nil {
+		h.logger.Error("加载关联套餐失败", zap.Uint("recharge_record_id", rechargeRecord.ID), zap.Error(err))
+		h.markAutoPurchaseFailedIfFinalRetry(ctx, rechargeRecord.ID)
+		return err
+	}
+
+	if err := h.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		wallet, walletErr := h.walletStore.GetByID(ctx, rechargeRecord.AssetWalletID)
+		if walletErr != nil {
+			if walletErr == gorm.ErrRecordNotFound {
+				return errors.New("资产钱包不存在")
+			}
+			return walletErr
+		}
+		if wallet.GetAvailableBalance() < totalAmount {
+			return errors.New("钱包余额不足")
+		}
+
+		if err = h.walletStore.DeductBalanceWithTx(ctx, tx, wallet.ID, totalAmount, wallet.Version); err != nil {
+			return err
+		}
+
+		now := time.Now()
+		order, orderItems, buildErr := h.buildOrderAndItems(rechargeRecord, packages, totalAmount, now)
+		if buildErr != nil {
+			return buildErr
+		}
+
+		if err = tx.Create(order).Error; err != nil {
+			return err
+		}
+
+		for _, item := range orderItems {
+			item.OrderID = order.ID
+		}
+		if err = tx.CreateInBatches(orderItems, 100).Error; err != nil {
+			return err
+		}
+
+		refType := constants.ReferenceTypeOrder
+		walletTx := &model.AssetWalletTransaction{
+			AssetWalletID:   wallet.ID,
+			ResourceType:    wallet.ResourceType,
+			ResourceID:      wallet.ResourceID,
+			UserID:          rechargeRecord.UserID,
+			TransactionType: constants.AssetTransactionTypeDeduct,
+			Amount:          -totalAmount,
+			BalanceBefore:   wallet.Balance,
+			BalanceAfter:    wallet.Balance - totalAmount,
+			Status:          constants.TransactionStatusSuccess,
+			ReferenceType:   &refType,
+			ReferenceNo:     &order.OrderNo,
+			Creator:         rechargeRecord.UserID,
+			ShopIDTag:       wallet.ShopIDTag,
+			EnterpriseIDTag: wallet.EnterpriseIDTag,
+		}
+		if err = h.walletTransactionStore.CreateWithTx(ctx, tx, walletTx); err != nil {
+			return err
+		}
+
+		if err = h.activatePackages(ctx, tx, order, packages, now); err != nil {
+			return err
+		}
+
+		if err = tx.Model(&model.AssetRechargeRecord{}).
+			Where("id = ?", rechargeRecord.ID).
+			Update("auto_purchase_status", constants.AutoPurchaseStatusSuccess).Error; err != nil {
+			return err
+		}
+
+		return nil
+	}); err != nil {
+		h.logger.Error("自动购包任务执行失败",
+			zap.Uint("recharge_record_id", rechargeRecord.ID),
+			zap.Error(err),
+		)
+		h.markAutoPurchaseFailedIfFinalRetry(ctx, rechargeRecord.ID)
+		return err
+	}
+
+	h.logger.Info("自动购包任务执行成功", zap.Uint("recharge_record_id", rechargeRecord.ID))
+	return nil
+}
+
+// NewAutoPurchaseTask 创建充值后自动购包任务
+func NewAutoPurchaseTask(rechargeRecordID uint) (*asynq.Task, error) {
+	payloadBytes, err := sonic.Marshal(AutoPurchasePayload{RechargeRecordID: rechargeRecordID})
+	if err != nil {
+		return nil, err
+	}
+
+	return asynq.NewTask(constants.TaskTypeAutoPurchaseAfterRecharge, payloadBytes,
+		asynq.MaxRetry(3),
+		asynq.Timeout(2*time.Minute),
+		asynq.Queue(constants.QueueDefault),
+	), nil
+}
+
+func (h *AutoPurchaseHandler) markAutoPurchaseFailedIfFinalRetry(ctx context.Context, rechargeRecordID uint) {
+	retryCount, ok := asynq.GetRetryCount(ctx)
+	if !ok {
+		return
+	}
+	maxRetry, ok := asynq.GetMaxRetry(ctx)
+	if !ok {
+		return
+	}
+	if retryCount < maxRetry-1 {
+		return
+	}
+
+	if err := h.db.WithContext(ctx).
+		Model(&model.AssetRechargeRecord{}).
+		Where("id = ?", rechargeRecordID).
+		Update("auto_purchase_status", constants.AutoPurchaseStatusFailed).Error; err != nil {
+		h.logger.Error("更新自动购包失败状态失败",
+			zap.Uint("recharge_record_id", rechargeRecordID),
+			zap.Error(err),
+		)
+		return
+	}
+
+	h.logger.Warn("自动购包达到最大重试次数，已标记失败", zap.Uint("recharge_record_id", rechargeRecordID))
+}
+
+func (h *AutoPurchaseHandler) loadPackages(ctx context.Context, packageIDs []uint) ([]*model.Package, int64, error) {
+	packages := make([]*model.Package, 0, len(packageIDs))
+	if err := h.db.WithContext(ctx).Where("id IN ?", packageIDs).Find(&packages).Error; err != nil {
+		return nil, 0, err
+	}
+	if len(packages) != len(packageIDs) {
+		return nil, 0, gorm.ErrRecordNotFound
+	}
+
+	totalAmount := int64(0)
+	for _, pkg := range packages {
+		totalAmount += pkg.SuggestedRetailPrice
+	}
+
+	if err := validatePackageTypeMix(packages); err != nil {
+		return nil, 0, err
+	}
+
+	return packages, totalAmount, nil
+}
+
+func (h *AutoPurchaseHandler) buildOrderAndItems(
+	rechargeRecord *model.AssetRechargeRecord,
+	packages []*model.Package,
+	totalAmount int64,
+	now time.Time,
+) (*model.Order, []*model.OrderItem, error) {
+	orderType, iotCardID, deviceID, err := parseLinkedCarrier(rechargeRecord.LinkedOrderType, rechargeRecord.LinkedCarrierType, rechargeRecord.LinkedCarrierID)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	generation := rechargeRecord.Generation
+	if generation <= 0 {
+		generation = 1
+	}
+
+	paidAmount := totalAmount
+	order := &model.Order{
+		BaseModel: model.BaseModel{
+			Creator: rechargeRecord.UserID,
+			Updater: rechargeRecord.UserID,
+		},
+		OrderNo:                 h.orderStore.GenerateOrderNo(),
+		OrderType:               orderType,
+		BuyerType:               model.BuyerTypePersonal,
+		BuyerID:                 rechargeRecord.UserID,
+		IotCardID:               iotCardID,
+		DeviceID:                deviceID,
+		TotalAmount:             totalAmount,
+		PaymentMethod:           model.PaymentMethodWallet,
+		PaymentStatus:           model.PaymentStatusPaid,
+		PaidAt:                  &now,
+		CommissionStatus:        model.CommissionStatusPending,
+		CommissionConfigVersion: 0,
+		Source:                  constants.OrderSourceClient,
+		Generation:              generation,
+		ActualPaidAmount:        &paidAmount,
+		SellerShopID:            &rechargeRecord.ShopIDTag,
+	}
+
+	items := make([]*model.OrderItem, 0, len(packages))
+	for _, pkg := range packages {
+		items = append(items, &model.OrderItem{
+			BaseModel: model.BaseModel{
+				Creator: rechargeRecord.UserID,
+				Updater: rechargeRecord.UserID,
+			},
+			PackageID:   pkg.ID,
+			PackageName: pkg.PackageName,
+			Quantity:    1,
+			UnitPrice:   pkg.SuggestedRetailPrice,
+			Amount:      pkg.SuggestedRetailPrice,
+		})
+	}
+
+	return order, items, nil
+}
+
+func (h *AutoPurchaseHandler) activatePackages(
+	ctx context.Context,
+	tx *gorm.DB,
+	order *model.Order,
+	packages []*model.Package,
+	now time.Time,
+) error {
+	carrierType := constants.AssetWalletResourceTypeIotCard
+	carrierID := uint(0)
+	if order.OrderType == model.OrderTypeSingleCard && order.IotCardID != nil {
+		carrierID = *order.IotCardID
+	} else if order.OrderType == model.OrderTypeDevice && order.DeviceID != nil {
+		carrierType = constants.AssetWalletResourceTypeDevice
+		carrierID = *order.DeviceID
+	} else {
+		return errors.New("无效的订单载体")
+	}
+
+	for _, pkg := range packages {
+		var existingUsage model.PackageUsage
+		err := tx.Where("order_id = ? AND package_id = ?", order.ID, pkg.ID).First(&existingUsage).Error
+		if err == nil {
+			continue
+		}
+		if err != gorm.ErrRecordNotFound {
+			return err
+		}
+
+		if pkg.PackageType == constants.PackageTypeFormal {
+			if err = h.activateMainPackage(ctx, tx, order, pkg, carrierType, carrierID, now); err != nil {
+				return err
+			}
+			continue
+		}
+		if pkg.PackageType == constants.PackageTypeAddon {
+			if err = h.activateAddonPackage(ctx, tx, order, pkg, carrierType, carrierID, now); err != nil {
+				return err
+			}
+		}
+	}
+
+	return nil
+}
+
+func (h *AutoPurchaseHandler) activateMainPackage(
+	ctx context.Context,
+	tx *gorm.DB,
+	order *model.Order,
+	pkg *model.Package,
+	carrierType string,
+	carrierID uint,
+	now time.Time,
+) error {
+	_ = ctx
+	var activeMainPackage model.PackageUsage
+	err := tx.Where("status = ?", constants.PackageUsageStatusActive).
+		Where("master_usage_id IS NULL").
+		Where(carrierType+"_id = ?", carrierID).
+		Order("priority ASC").
+		First(&activeMainPackage).Error
+
+	hasActiveMain := err == nil
+
+	var status int
+	var priority int
+	var activatedAt time.Time
+	var expiresAt time.Time
+	var nextResetAt *time.Time
+	var pendingRealnameActivation bool
+
+	if hasActiveMain {
+		status = constants.PackageUsageStatusPending
+		var maxPriority int
+		tx.Model(&model.PackageUsage{}).
+			Where(carrierType+"_id = ?", carrierID).
+			Select("COALESCE(MAX(priority), 0)").
+			Scan(&maxPriority)
+		priority = maxPriority + 1
+	} else {
+		status = constants.PackageUsageStatusActive
+		priority = 1
+		activatedAt = now
+		expiresAt = packagepkg.CalculateExpiryTime(pkg.CalendarType, activatedAt, pkg.DurationMonths, pkg.DurationDays)
+		nextResetAt = packagepkg.CalculateNextResetTime(pkg.DataResetCycle, pkg.CalendarType, now, activatedAt)
+	}
+
+	if pkg.EnableRealnameActivation {
+		status = constants.PackageUsageStatusPending
+		pendingRealnameActivation = true
+	}
+
+	usage := &model.PackageUsage{
+		BaseModel: model.BaseModel{
+			Creator: order.Creator,
+			Updater: order.Creator,
+		},
+		OrderID:                   order.ID,
+		PackageID:                 pkg.ID,
+		UsageType:                 order.OrderType,
+		DataLimitMB:               pkg.RealDataMB,
+		Status:                    status,
+		Priority:                  priority,
+		DataResetCycle:            pkg.DataResetCycle,
+		PendingRealnameActivation: pendingRealnameActivation,
+		Generation:                order.Generation,
+	}
+
+	if carrierType == constants.AssetWalletResourceTypeIotCard {
+		usage.IotCardID = carrierID
+	} else {
+		usage.DeviceID = carrierID
+	}
+
+	if status == constants.PackageUsageStatusActive {
+		usage.ActivatedAt = activatedAt
+		usage.ExpiresAt = expiresAt
+		usage.NextResetAt = nextResetAt
+	}
+
+	if err = tx.Omit("status", "pending_realname_activation").Create(usage).Error; err != nil {
+		return err
+	}
+
+	return tx.Model(usage).Updates(map[string]any{
+		"status":                      usage.Status,
+		"pending_realname_activation": usage.PendingRealnameActivation,
+	}).Error
+}
+
+func (h *AutoPurchaseHandler) activateAddonPackage(
+	ctx context.Context,
+	tx *gorm.DB,
+	order *model.Order,
+	pkg *model.Package,
+	carrierType string,
+	carrierID uint,
+	now time.Time,
+) error {
+	_ = ctx
+	var mainPackage model.PackageUsage
+	err := tx.Where("status IN ?", []int{constants.PackageUsageStatusPending, constants.PackageUsageStatusActive}).
+		Where("master_usage_id IS NULL").
+		Where(carrierType+"_id = ?", carrierID).
+		Order("priority ASC").
+		First(&mainPackage).Error
+	if err == gorm.ErrRecordNotFound {
+		return errors.New("必须有主套餐才能购买加油包")
+	}
+	if err != nil {
+		return err
+	}
+
+	var maxPriority int
+	tx.Model(&model.PackageUsage{}).
+		Where(carrierType+"_id = ?", carrierID).
+		Select("COALESCE(MAX(priority), 0)").
+		Scan(&maxPriority)
+
+	priority := maxPriority + 1
+	expiresAt := mainPackage.ExpiresAt
+
+	usage := &model.PackageUsage{
+		BaseModel: model.BaseModel{
+			Creator: order.Creator,
+			Updater: order.Creator,
+		},
+		OrderID:        order.ID,
+		PackageID:      pkg.ID,
+		UsageType:      order.OrderType,
+		DataLimitMB:    pkg.RealDataMB,
+		Status:         constants.PackageUsageStatusActive,
+		Priority:       priority,
+		MasterUsageID:  &mainPackage.ID,
+		ActivatedAt:    now,
+		ExpiresAt:      expiresAt,
+		DataResetCycle: pkg.DataResetCycle,
+		Generation:     order.Generation,
+	}
+
+	if carrierType == constants.AssetWalletResourceTypeIotCard {
+		usage.IotCardID = carrierID
+	} else {
+		usage.DeviceID = carrierID
+	}
+
+	return tx.Create(usage).Error
+}
+
+func parseLinkedPackageIDs(raw []byte) ([]uint, error) {
+	var packageIDs []uint
+	if len(raw) == 0 {
+		return nil, nil
+	}
+	if err := sonic.Unmarshal(raw, &packageIDs); err != nil {
+		return nil, err
+	}
+	return packageIDs, nil
+}
+
+func parseLinkedCarrier(linkedOrderType string, linkedCarrierType string, linkedCarrierID *uint) (string, *uint, *uint, error) {
+	if linkedCarrierID == nil || *linkedCarrierID == 0 {
+		return "", nil, nil, errors.New("关联载体ID为空")
+	}
+
+	if linkedOrderType == model.OrderTypeSingleCard || linkedCarrierType == "card" || linkedCarrierType == constants.AssetWalletResourceTypeIotCard {
+		id := *linkedCarrierID
+		return model.OrderTypeSingleCard, &id, nil, nil
+	}
+	if linkedOrderType == model.OrderTypeDevice || linkedCarrierType == "device" || linkedCarrierType == constants.AssetWalletResourceTypeDevice {
+		id := *linkedCarrierID
+		return model.OrderTypeDevice, nil, &id, nil
+	}
+
+	return "", nil, nil, errors.New("关联载体类型无效")
+}
+
+func validatePackageTypeMix(packages []*model.Package) error {
+	hasFormal := false
+	hasAddon := false
+
+	for _, pkg := range packages {
+		switch pkg.PackageType {
+		case constants.PackageTypeFormal:
+			hasFormal = true
+		case constants.PackageTypeAddon:
+			hasAddon = true
+		}
+
+		if hasFormal && hasAddon {
+			return errors.New("不允许在同一订单中同时购买正式套餐和加油包")
+		}
+	}
+
+	return nil
+}

migrations/000082_client_api_data_model_fixes.down.sql

@@ -0,0 +1,35 @@
+-- 回滚: 客户端接口数据模型基础准备
+
+-- 9. tb_personal_customer: 恢复唯一索引
+DROP INDEX IF EXISTS idx_personal_customer_wx_open_id;
+CREATE UNIQUE INDEX idx_personal_customer_wx_open_id ON tb_personal_customer(wx_open_id) WHERE deleted_at IS NULL;
+
+-- 7. tb_shop_package_allocation: 移除 retail_price
+ALTER TABLE tb_shop_package_allocation DROP COLUMN IF EXISTS retail_price;
+
+-- 6. tb_carrier: 移除实名链接配置
+ALTER TABLE tb_carrier DROP COLUMN IF EXISTS realname_link_template;
+ALTER TABLE tb_carrier DROP COLUMN IF EXISTS realname_link_type;
+
+-- 5. tb_asset_recharge_record: 移除新增字段
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS linked_carrier_id;
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS linked_carrier_type;
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS linked_order_type;
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS linked_package_ids;
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS generation;
+ALTER TABLE tb_asset_recharge_record DROP COLUMN IF EXISTS operator_type;
+
+-- 4. tb_package_usage: 移除 generation
+ALTER TABLE tb_package_usage DROP COLUMN IF EXISTS generation;
+
+-- 3. tb_order: 移除 source 和 generation
+ALTER TABLE tb_order DROP COLUMN IF EXISTS generation;
+ALTER TABLE tb_order DROP COLUMN IF EXISTS source;
+
+-- 2. tb_device: 移除 asset_status 和 generation
+ALTER TABLE tb_device DROP COLUMN IF EXISTS generation;
+ALTER TABLE tb_device DROP COLUMN IF EXISTS asset_status;
+
+-- 1. tb_iot_card: 移除 asset_status 和 generation
+ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS generation;
+ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS asset_status;

migrations/000082_client_api_data_model_fixes.up.sql

@@ -0,0 +1,58 @@
+-- 客户端接口数据模型基础准备
+-- 提案: client-api-data-model-fixes
+-- 包含: 资产状态、世代编号、订单来源、操作人类型、实名链接配置、代理零售价、索引变更
+
+-- 1. tb_iot_card: 新增 asset_status 和 generation
+ALTER TABLE tb_iot_card ADD COLUMN asset_status int NOT NULL DEFAULT 1;
+ALTER TABLE tb_iot_card ADD COLUMN generation int NOT NULL DEFAULT 1;
+COMMENT ON COLUMN tb_iot_card.asset_status IS '业务状态 1-在库 2-已销售 3-已换货 4-已停用';
+COMMENT ON COLUMN tb_iot_card.generation IS '资产世代编号';
+
+-- 2. tb_device: 新增 asset_status 和 generation
+ALTER TABLE tb_device ADD COLUMN asset_status int NOT NULL DEFAULT 1;
+ALTER TABLE tb_device ADD COLUMN generation int NOT NULL DEFAULT 1;
+COMMENT ON COLUMN tb_device.asset_status IS '业务状态 1-在库 2-已销售 3-已换货 4-已停用';
+COMMENT ON COLUMN tb_device.generation IS '资产世代编号';
+
+-- 3. tb_order: 新增 source 和 generation
+ALTER TABLE tb_order ADD COLUMN source varchar(20) NOT NULL DEFAULT 'admin';
+ALTER TABLE tb_order ADD COLUMN generation int NOT NULL DEFAULT 1;
+COMMENT ON COLUMN tb_order.source IS '订单来源 admin-后台 client-客户端';
+COMMENT ON COLUMN tb_order.generation IS '资产世代编号';
+
+-- 4. tb_package_usage: 新增 generation
+ALTER TABLE tb_package_usage ADD COLUMN generation int NOT NULL DEFAULT 1;
+COMMENT ON COLUMN tb_package_usage.generation IS '资产世代编号';
+
+-- 5. tb_asset_recharge_record: 新增 operator_type、generation 和强充关联字段
+ALTER TABLE tb_asset_recharge_record ADD COLUMN operator_type varchar(20) NOT NULL DEFAULT 'admin_user';
+ALTER TABLE tb_asset_recharge_record ADD COLUMN generation int NOT NULL DEFAULT 1;
+ALTER TABLE tb_asset_recharge_record ADD COLUMN linked_package_ids jsonb DEFAULT '[]';
+ALTER TABLE tb_asset_recharge_record ADD COLUMN linked_order_type varchar(20);
+ALTER TABLE tb_asset_recharge_record ADD COLUMN linked_carrier_type varchar(20);
+ALTER TABLE tb_asset_recharge_record ADD COLUMN linked_carrier_id bigint;
+COMMENT ON COLUMN tb_asset_recharge_record.operator_type IS '操作人类型 admin_user-后台用户 personal_customer-个人客户';
+COMMENT ON COLUMN tb_asset_recharge_record.generation IS '资产世代编号';
+COMMENT ON COLUMN tb_asset_recharge_record.linked_package_ids IS '强充关联套餐ID列表';
+COMMENT ON COLUMN tb_asset_recharge_record.linked_order_type IS '关联订单类型';
+COMMENT ON COLUMN tb_asset_recharge_record.linked_carrier_type IS '关联载体类型';
+COMMENT ON COLUMN tb_asset_recharge_record.linked_carrier_id IS '关联载体ID';
+
+-- 6. tb_carrier: 新增实名链接配置
+ALTER TABLE tb_carrier ADD COLUMN realname_link_type varchar(20) NOT NULL DEFAULT 'none';
+ALTER TABLE tb_carrier ADD COLUMN realname_link_template varchar(500) DEFAULT '';
+COMMENT ON COLUMN tb_carrier.realname_link_type IS '实名链接类型 none-不支持 template-模板URL gateway-Gateway接口';
+COMMENT ON COLUMN tb_carrier.realname_link_template IS '实名链接模板URL';
+
+-- 7. tb_shop_package_allocation: 新增 retail_price
+ALTER TABLE tb_shop_package_allocation ADD COLUMN retail_price bigint NOT NULL DEFAULT 0;
+COMMENT ON COLUMN tb_shop_package_allocation.retail_price IS '代理面向终端客户的零售价（分）';
+
+-- 8. 存量数据修复: 将 retail_price 设为对应套餐的 suggested_retail_price
+UPDATE tb_shop_package_allocation spa
+SET retail_price = (SELECT suggested_retail_price FROM tb_package p WHERE p.id = spa.package_id)
+WHERE retail_price = 0;
+
+-- 9. tb_personal_customer: wx_open_id 唯一索引改为普通索引
+DROP INDEX IF EXISTS idx_personal_customer_wx_open_id;
+CREATE INDEX idx_personal_customer_wx_open_id ON tb_personal_customer(wx_open_id);

migrations/000083_add_personal_customer_openid.down.sql

@@ -0,0 +1,2 @@
+-- 回滚：删除个人客户 OpenID 关联表
+DROP TABLE IF EXISTS tb_personal_customer_openid;