设备的部分改造

2026-03-10 10:34:08 +08:00
parent 86f8d0b644
commit b5147d1acb
34 changed files with 1680 additions and 485 deletions
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -346,6 +346,7 @@ func initGateway(cfg *config.Config, appLogger *zap.Logger) *gateway.Client {
 		cfg.Gateway.BaseURL,
 		cfg.Gateway.AppID,
 		cfg.Gateway.AppSecret,
+		appLogger,
 	).WithTimeout(time.Duration(cfg.Gateway.Timeout) * time.Second)

 	appLogger.Info("Gateway 客户端初始化成功",
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -249,6 +249,7 @@ func initGateway(cfg *config.Config, appLogger *zap.Logger) *gateway.Client {
 		cfg.Gateway.BaseURL,
 		cfg.Gateway.AppID,
 		cfg.Gateway.AppSecret,
+		appLogger,
 	).WithTimeout(time.Duration(cfg.Gateway.Timeout) * time.Second)

 	appLogger.Info("Gateway 客户端初始化成功",
--- a/internal/bootstrap/handlers.go
+++ b/internal/bootstrap/handlers.go
@@ -31,9 +31,9 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		EnterpriseDeviceH5:          h5.NewEnterpriseDeviceHandler(svc.EnterpriseDevice),
 		Authorization:               admin.NewAuthorizationHandler(svc.Authorization),
 		MyCommission:                admin.NewMyCommissionHandler(svc.MyCommission),
-		IotCard:                     admin.NewIotCardHandler(svc.IotCard, deps.GatewayClient),
+		IotCard:                     admin.NewIotCardHandler(svc.IotCard),
 		IotCardImport:               admin.NewIotCardImportHandler(svc.IotCardImport),
-		Device:                      admin.NewDeviceHandler(svc.Device, deps.GatewayClient),
+		Device:                      admin.NewDeviceHandler(svc.Device),
 		DeviceImport:                admin.NewDeviceImportHandler(svc.DeviceImport),
 		AssetAllocationRecord:       admin.NewAssetAllocationRecordHandler(svc.AssetAllocationRecord),
 		Storage:                     admin.NewStorageHandler(deps.StorageService),
--- a/internal/bootstrap/services.go
+++ b/internal/bootstrap/services.go
@@ -124,7 +124,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 		MyCommission:               myCommissionSvc.New(deps.DB, s.Shop, s.AgentWallet, s.CommissionWithdrawalRequest, s.CommissionWithdrawalSetting, s.CommissionRecord, s.AgentWalletTransaction),
 		IotCard:                    iotCard,
 		IotCardImport:              iotCardImportSvc.New(deps.DB, s.IotCardImportTask, deps.QueueClient),
-		Device:                     deviceSvc.New(deps.DB, s.Device, s.DeviceSimBinding, s.IotCard, s.Shop, s.AssetAllocationRecord, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.PackageSeries),
+		Device:                     deviceSvc.New(deps.DB, s.Device, s.DeviceSimBinding, s.IotCard, s.Shop, s.AssetAllocationRecord, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.PackageSeries, deps.GatewayClient),
 		DeviceImport:               deviceImportSvc.New(deps.DB, s.DeviceImportTask, deps.QueueClient),
 		AssetAllocationRecord:      assetAllocationRecordSvc.New(deps.DB, s.AssetAllocationRecord, s.Shop, s.Account),
 		Carrier:                    carrierSvc.New(s.Carrier),
--- a/internal/gateway/client.go
+++ b/internal/gateway/client.go
@@ -1,5 +1,5 @@
 // Package gateway 提供 Gateway API 的统一客户端封装
-// 实现 AES-128-ECB 加密 + MD5 签名认证机制
+// 实现 AES-128-ECB 加密 + MD5 签名认证机制，支持请求日志和网络级错误重试
 package gateway

 import (
@@ -13,6 +13,7 @@ import (

 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 	"github.com/bytedance/sonic"
+	"go.uber.org/zap"
 )

 const (
@@ -22,6 +23,8 @@ const (
 	idleConnTimeout     = 90 * time.Second
 	contentTypeJSON     = "application/json;charset=utf-8"
 	gatewaySuccessCode  = 200
+	defaultMaxRetries   = 2
+	retryBaseDelay      = 100 * time.Millisecond
 )

 // Client 是 Gateway API 的 HTTP 客户端
@@ -31,13 +34,21 @@ type Client struct {
 	appSecret  string
 	httpClient *http.Client
 	timeout    time.Duration
+	logger     *zap.Logger
+	maxRetries int
+}
+
+// requestWrapper 用于将请求参数包装为 Gateway 的 {"params": ...} 格式
+type requestWrapper struct {
+	Params interface{} `json:"params"`
 }

 // NewClient 创建 Gateway 客户端实例
 // baseURL: Gateway 服务基础地址
 // appID: 应用 ID
 // appSecret: 应用密钥（用于加密和签名）
-func NewClient(baseURL, appID, appSecret string) *Client {
+// logger: Zap 日志记录器
+func NewClient(baseURL, appID, appSecret string, logger *zap.Logger) *Client {
 	return &Client{
 		baseURL:   baseURL,
 		appID:     appID,
@@ -49,7 +60,9 @@ func NewClient(baseURL, appID, appSecret string) *Client {
 				IdleConnTimeout:     idleConnTimeout,
 			},
 		},
-		timeout: defaultTimeout,
+		timeout:    defaultTimeout,
+		logger:     logger,
+		maxRetries: defaultMaxRetries,
 	}
 }

@@ -59,19 +72,86 @@ func (c *Client) WithTimeout(timeout time.Duration) *Client {
 	return c
 }

+// WithRetry 设置最大重试次数（支持链式调用）
+// maxRetries=0 表示不重试，maxRetries=2 表示最多重试 2 次（共 3 次尝试）
+func (c *Client) WithRetry(maxRetries int) *Client {
+	c.maxRetries = maxRetries
+	return c
+}
+
 // doRequest 执行 Gateway API 请求的统一方法
-// 流程：序列化 → 加密 → 签名 → HTTP POST → 解析响应 → 检查业务状态码
-func (c *Client) doRequest(ctx context.Context, path string, businessData interface{}) (json.RawMessage, error) {
-	dataBytes, err := sonic.Marshal(businessData)
+// 流程：包装参数 → 序列化 → 加密 → 签名 → HTTP POST（带重试）→ 解析响应 → 检查业务状态码
+// params: 请求参数结构体，内部自动包装为 {"params": <JSON>} 格式
+func (c *Client) doRequest(ctx context.Context, path string, params interface{}) (json.RawMessage, error) {
+	startTime := time.Now()
+
+	// 将参数包装为 {"params": ...} 格式后序列化
+	wrapper := requestWrapper{Params: params}
+	dataBytes, err := sonic.Marshal(wrapper)
 	if err != nil {
 		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化业务数据失败")
 	}

+	// 加密业务数据（加密结果不变，可在重试间复用）
 	encryptedData, err := aesEncrypt(dataBytes, c.appSecret)
 	if err != nil {
 		return nil, err
 	}

+	// 带重试的 HTTP 请求
+	var lastErr error
+	for attempt := 0; attempt <= c.maxRetries; attempt++ {
+		if attempt > 0 {
+			// 检查用户 Context 是否已取消
+			if ctx.Err() != nil {
+				break
+			}
+			// 指数退避等待：100ms → 200ms → 300ms（封顶 3 倍基础延迟）
+			delay := retryBaseDelay * time.Duration(1<<uint(attempt-1))
+			if delay > retryBaseDelay*3 {
+				delay = retryBaseDelay * 3
+			}
+			c.logger.Warn("Gateway 请求重试",
+				zap.String("path", path),
+				zap.Int("attempt", attempt+1),
+				zap.Duration("delay", delay),
+			)
+			time.Sleep(delay)
+		}
+
+		result, retryable, err := c.executeHTTPRequest(ctx, path, encryptedData)
+		if err != nil {
+			lastErr = err
+			// 仅对网络级错误重试
+			if retryable && ctx.Err() == nil {
+				continue
+			}
+			break
+		}
+
+		// 成功
+		duration := time.Since(startTime)
+		c.logger.Debug("Gateway 请求成功",
+			zap.String("path", path),
+			zap.Duration("duration", duration),
+		)
+		return result, nil
+	}
+
+	// 所有尝试都失败
+	duration := time.Since(startTime)
+	c.logger.Error("Gateway 请求失败",
+		zap.String("path", path),
+		zap.Duration("duration", duration),
+		zap.Error(lastErr),
+	)
+	return nil, lastErr
+}
+
+// executeHTTPRequest 执行单次 HTTP 请求（无重试逻辑）
+// 返回值：响应数据、是否可重试、错误
+func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedData string) (json.RawMessage, bool, error) {
+	// 每次重试使用新的时间戳和签名
 	timestamp := time.Now().Unix()
 	sign := generateSign(c.appID, encryptedData, timestamp, c.appSecret)

@@ -84,7 +164,7 @@ func (c *Client) doRequest(ctx context.Context, path string, businessData interf

 	reqBodyBytes, err := sonic.Marshal(reqBody)
 	if err != nil {
-		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化请求体失败")
+		return nil, false, errors.Wrap(errors.CodeInternalError, err, "序列化请求体失败")
 	}

 	reqCtx, cancel := context.WithTimeout(ctx, c.timeout)
@@ -92,39 +172,64 @@ func (c *Client) doRequest(ctx context.Context, path string, businessData interf

 	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.baseURL+path, bytes.NewReader(reqBodyBytes))
 	if err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayError, err, "创建 HTTP 请求失败")
+		return nil, false, errors.Wrap(errors.CodeGatewayError, err, "创建 HTTP 请求失败")
 	}
 	req.Header.Set("Content-Type", contentTypeJSON)

 	resp, err := c.httpClient.Do(req)
 	if err != nil {
-		if reqCtx.Err() == context.DeadlineExceeded {
-			return nil, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时")
-		}
+		// 用户 Context 已取消 — 不可重试
 		if ctx.Err() != nil {
-			return nil, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消")
+			return nil, false, errors.Wrap(errors.CodeGatewayError, ctx.Err(), "请求被取消")
 		}
-		return nil, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败")
+		// Client 超时 — 可重试
+		if reqCtx.Err() == context.DeadlineExceeded {
+			return nil, true, errors.Wrap(errors.CodeGatewayTimeout, err, "Gateway 请求超时")
+		}
+		// 其他网络错误（连接失败、DNS 解析等）— 可重试
+		return nil, true, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败")
 	}
 	defer resp.Body.Close()

+	// HTTP 状态码错误 — 不可重试
 	if resp.StatusCode != http.StatusOK {
-		return nil, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode))
+		return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("HTTP 状态码异常: %d", resp.StatusCode))
 	}

 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败")
+		return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败")
 	}

 	var gatewayResp GatewayResponse
 	if err := sonic.Unmarshal(body, &gatewayResp); err != nil {
+		return nil, false, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败")
+	}
+
+	// Gateway 业务错误 — 不可重试
+	if gatewayResp.Code != gatewaySuccessCode {
+		c.logger.Warn("Gateway 业务错误",
+			zap.String("path", path),
+			zap.Int("gateway_code", gatewayResp.Code),
+			zap.String("gateway_msg", gatewayResp.Msg),
+		)
+		return nil, false, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg))
+	}
+
+	return gatewayResp.Data, false, nil
+}
+
+// doRequestWithResponse 执行 Gateway API 请求并自动反序列化响应为目标类型
+func doRequestWithResponse[T any](c *Client, ctx context.Context, path string, params interface{}) (*T, error) {
+	data, err := c.doRequest(ctx, path, params)
+	if err != nil {
+		return nil, err
+	}
+
+	var result T
+	if err := sonic.Unmarshal(data, &result); err != nil {
 		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败")
 	}

-	if gatewayResp.Code != gatewaySuccessCode {
-		return nil, errors.New(errors.CodeGatewayError, fmt.Sprintf("Gateway 业务错误: code=%d, msg=%s", gatewayResp.Code, gatewayResp.Msg))
-	}
-
-	return gatewayResp.Data, nil
+	return &result, nil
 }
--- a/internal/gateway/device.go
+++ b/internal/gateway/device.go
@@ -5,165 +5,66 @@ import (
 	"context"

 	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/bytedance/sonic"
 )

 // GetDeviceInfo 获取设备信息
 // 通过卡号或设备 ID 查询设备的在线状态、信号强度、WiFi 信息等
+// POST /device/info
 func (c *Client) GetDeviceInfo(ctx context.Context, req *DeviceInfoReq) (*DeviceInfoResp, error) {
 	if req.CardNo == "" && req.DeviceID == "" {
 		return nil, errors.New(errors.CodeInvalidParam, "cardNo 和 deviceId 至少需要一个")
 	}
-
-	params := make(map[string]interface{})
-	if req.CardNo != "" {
-		params["cardNo"] = req.CardNo
-	}
-	if req.DeviceID != "" {
-		params["deviceId"] = req.DeviceID
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	resp, err := c.doRequest(ctx, "/device/info", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result DeviceInfoResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析设备信息响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[DeviceInfoResp](c, ctx, "/device/info", req)
 }

 // GetSlotInfo 获取设备卡槽信息
 // 查询设备的所有卡槽及其中的卡信息
+// POST /device/slot-info
 func (c *Client) GetSlotInfo(ctx context.Context, req *DeviceInfoReq) (*SlotInfoResp, error) {
 	if req.CardNo == "" && req.DeviceID == "" {
 		return nil, errors.New(errors.CodeInvalidParam, "cardNo 和 deviceId 至少需要一个")
 	}
-
-	params := make(map[string]interface{})
-	if req.CardNo != "" {
-		params["cardNo"] = req.CardNo
-	}
-	if req.DeviceID != "" {
-		params["deviceId"] = req.DeviceID
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	resp, err := c.doRequest(ctx, "/device/slot-info", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result SlotInfoResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析卡槽信息响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[SlotInfoResp](c, ctx, "/device/slot-info", req)
 }

 // SetSpeedLimit 设置设备限速
-// 设置设备的上行和下行速率限制
+// 设置设备的统一限速值（单位 KB/s）
+// POST /device/speed-limit
 func (c *Client) SetSpeedLimit(ctx context.Context, req *SpeedLimitReq) error {
-	params := map[string]interface{}{
-		"deviceId":      req.DeviceID,
-		"uploadSpeed":   req.UploadSpeed,
-		"downloadSpeed": req.DownloadSpeed,
-	}
-	if req.Extend != "" {
-		params["extend"] = req.Extend
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	_, err := c.doRequest(ctx, "/device/speed-limit", businessData)
+	_, err := c.doRequest(ctx, "/device/speed-limit", req)
 	return err
 }

 // SetWiFi 设置设备 WiFi
-// 设置设备的 WiFi 名称、密码和启用状态
+// 配置 WiFi 名称、密码及启用状态，cardNo（ICCID）为必填参数
+// POST /device/wifi-config
 func (c *Client) SetWiFi(ctx context.Context, req *WiFiReq) error {
-	params := map[string]interface{}{
-		"deviceId": req.DeviceID,
-		"ssid":     req.SSID,
-		"password": req.Password,
-		"enabled":  req.Enabled,
-	}
-	if req.Extend != "" {
-		params["extend"] = req.Extend
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	_, err := c.doRequest(ctx, "/device/wifi", businessData)
+	_, err := c.doRequest(ctx, "/device/wifi-config", req)
 	return err
 }

 // SwitchCard 设备切换卡
-// 切换设备当前使用的卡到指定的目标卡
+// 为多卡设备切换到目标 ICCID，operationType 固定为 2
+// POST /device/card-switch
 func (c *Client) SwitchCard(ctx context.Context, req *SwitchCardReq) error {
-	params := map[string]interface{}{
-		"deviceId":    req.DeviceID,
-		"targetIccid": req.TargetICCID,
-	}
-	if req.Extend != "" {
-		params["extend"] = req.Extend
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	_, err := c.doRequest(ctx, "/device/switch-card", businessData)
+	// 强制设置 operationType 为 2（切卡操作）
+	req.OperationType = 2
+	_, err := c.doRequest(ctx, "/device/card-switch", req)
 	return err
 }

 // ResetDevice 设备恢复出厂设置
 // 将设备恢复到出厂设置状态
+// POST /device/factory-reset
 func (c *Client) ResetDevice(ctx context.Context, req *DeviceOperationReq) error {
-	params := map[string]interface{}{
-		"deviceId": req.DeviceID,
-	}
-	if req.Extend != "" {
-		params["extend"] = req.Extend
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	_, err := c.doRequest(ctx, "/device/reset", businessData)
+	_, err := c.doRequest(ctx, "/device/factory-reset", req)
 	return err
 }

 // RebootDevice 设备重启
 // 远程重启设备
+// POST /device/restart
 func (c *Client) RebootDevice(ctx context.Context, req *DeviceOperationReq) error {
-	params := map[string]interface{}{
-		"deviceId": req.DeviceID,
-	}
-	if req.Extend != "" {
-		params["extend"] = req.Extend
-	}
-
-	businessData := map[string]interface{}{
-		"params": params,
-	}
-
-	_, err := c.doRequest(ctx, "/device/reboot", businessData)
+	_, err := c.doRequest(ctx, "/device/restart", req)
 	return err
 }
--- a/internal/gateway/flow_card.go
+++ b/internal/gateway/flow_card.go
@@ -5,121 +5,44 @@ import (
 	"context"

 	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/bytedance/sonic"
 )

 // QueryCardStatus 查询流量卡状态
+// POST /flow-card/status
 func (c *Client) QueryCardStatus(ctx context.Context, req *CardStatusReq) (*CardStatusResp, error) {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-
-	resp, err := c.doRequest(ctx, "/flow-card/status", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result CardStatusResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析卡状态响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[CardStatusResp](c, ctx, "/flow-card/status", req)
 }

 // QueryFlow 查询流量使用情况
+// POST /flow-card/flow
 func (c *Client) QueryFlow(ctx context.Context, req *FlowQueryReq) (*FlowUsageResp, error) {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-
-	resp, err := c.doRequest(ctx, "/flow-card/flow", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result FlowUsageResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析流量使用响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[FlowUsageResp](c, ctx, "/flow-card/flow", req)
 }

 // QueryRealnameStatus 查询实名认证状态
+// POST /flow-card/realName
 func (c *Client) QueryRealnameStatus(ctx context.Context, req *CardStatusReq) (*RealnameStatusResp, error) {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-
-	resp, err := c.doRequest(ctx, "/flow-card/realName", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result RealnameStatusResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析实名认证状态响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[RealnameStatusResp](c, ctx, "/flow-card/realName", req)
 }

 // StopCard 流量卡停机
+// POST /flow-card/cardStop
 func (c *Client) StopCard(ctx context.Context, req *CardOperationReq) error {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-	if req.Extend != "" {
-		businessData["params"].(map[string]interface{})["extend"] = req.Extend
-	}
-
-	_, err := c.doRequest(ctx, "/flow-card/cardStop", businessData)
+	_, err := c.doRequest(ctx, "/flow-card/cardStop", req)
 	return err
 }

 // StartCard 流量卡复机
+// POST /flow-card/cardStart
 func (c *Client) StartCard(ctx context.Context, req *CardOperationReq) error {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-	if req.Extend != "" {
-		businessData["params"].(map[string]interface{})["extend"] = req.Extend
-	}
-
-	_, err := c.doRequest(ctx, "/flow-card/cardStart", businessData)
+	_, err := c.doRequest(ctx, "/flow-card/cardStart", req)
 	return err
 }

 // GetRealnameLink 获取实名认证跳转链接
+// POST /flow-card/RealNameVerification
 func (c *Client) GetRealnameLink(ctx context.Context, req *CardStatusReq) (*RealnameLinkResp, error) {
-	businessData := map[string]interface{}{
-		"params": map[string]interface{}{
-			"cardNo": req.CardNo,
-		},
-	}
-
-	resp, err := c.doRequest(ctx, "/flow-card/RealNameVerification", businessData)
-	if err != nil {
-		return nil, err
-	}
-
-	var result RealnameLinkResp
-	if err := sonic.Unmarshal(resp, &result); err != nil {
-		return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析实名认证链接响应失败")
-	}
-
-	return &result, nil
+	return doRequestWithResponse[RealnameLinkResp](c, ctx, "/flow-card/RealNameVerification", req)
 }

 // BatchQuery 批量查询（预留接口，暂未实现）
--- a/internal/gateway/models.go
+++ b/internal/gateway/models.go
@@ -86,26 +86,28 @@ type DeviceInfoResp struct {

 // SpeedLimitReq 是设置设备限速的请求
 type SpeedLimitReq struct {
-	DeviceID      string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"`
-	UploadSpeed   int    `json:"uploadSpeed" validate:"required,min=1" required:"true" minimum:"1" description:"上行速率（KB/s）"`
-	DownloadSpeed int    `json:"downloadSpeed" validate:"required,min=1" required:"true" minimum:"1" description:"下行速率（KB/s）"`
-	Extend        string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
+	CardNo     string `json:"cardNo,omitempty" description:"流量卡号（与 DeviceID 二选一）"`
+	DeviceID   string `json:"deviceId,omitempty" description:"设备 ID/IMEI（与 CardNo 二选一）"`
+	SpeedLimit int    `json:"speedLimit" validate:"required,min=1" required:"true" minimum:"1" description:"限速值（KB/s）"`
+	Extend     string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
 }

 // WiFiReq 是设置设备 WiFi 的请求
 type WiFiReq struct {
-	DeviceID string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"`
+	CardNo   string `json:"cardNo" validate:"required" required:"true" description:"流量卡号（ICCID）"`
+	DeviceID string `json:"deviceId,omitempty" description:"设备 ID/IMEI"`
 	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=8,max=63" required:"true" minLength:"8" maxLength:"63" description:"WiFi 密码"`
-	Enabled  int    `json:"enabled" validate:"required,oneof=0 1" required:"true" description:"启用状态（0:禁用, 1:启用）"`
+	Password string `json:"password,omitempty" description:"WiFi 密码"`
+	Enabled  bool   `json:"enabled" description:"启用状态"`
 	Extend   string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
 }

 // SwitchCardReq 是设备切换卡的请求
 type SwitchCardReq struct {
-	DeviceID    string `json:"deviceId" validate:"required" required:"true" description:"设备 ID/IMEI"`
-	TargetICCID string `json:"targetIccid" validate:"required" required:"true" description:"目标卡 ICCID"`
-	Extend      string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
+	CardNo        string `json:"cardNo" validate:"required" required:"true" description:"设备编号（IMEI）"`
+	ICCID         string `json:"iccid" validate:"required" required:"true" description:"目标卡 ICCID"`
+	OperationType int    `json:"operationType" description:"操作类型（固定值 2）"`
+	Extend        string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
 }

 // DeviceOperationReq 是设备操作（重启、恢复出厂）的请求
--- a/internal/handler/admin/device.go
+++ b/internal/handler/admin/device.go
@@ -5,7 +5,6 @@ import (

 	"github.com/gofiber/fiber/v2"

-	"github.com/break/junhong_cmp_fiber/internal/gateway"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	deviceService "github.com/break/junhong_cmp_fiber/internal/service/device"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -15,14 +14,12 @@ import (
 )

 type DeviceHandler struct {
-	service       *deviceService.Service
-	gatewayClient *gateway.Client
+	service *deviceService.Service
 }

-func NewDeviceHandler(service *deviceService.Service, gatewayClient *gateway.Client) *DeviceHandler {
+func NewDeviceHandler(service *deviceService.Service) *DeviceHandler {
 	return &DeviceHandler{
-		service:       service,
-		gatewayClient: gatewayClient,
+		service: service,
 	}
 }

@@ -55,13 +52,15 @@ func (h *DeviceHandler) GetByID(c *fiber.Ctx) error {
 	return response.Success(c, result)
 }

-func (h *DeviceHandler) GetByIMEI(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+// GetByIdentifier 通过标识符查询设备详情
+// GET /api/admin/devices/by-identifier/:identifier
+func (h *DeviceHandler) GetByIdentifier(c *fiber.Ctx) error {
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	result, err := h.service.GetByDeviceNo(c.UserContext(), imei)
+	result, err := h.service.GetByIdentifier(c.UserContext(), identifier)
 	if err != nil {
 		return err
 	}
@@ -225,22 +224,14 @@ func (h *DeviceHandler) BatchSetSeriesBinding(c *fiber.Ctx) error {
 }

 // GetGatewayInfo 查询设备信息
+// GET /api/admin/devices/by-identifier/:identifier/gateway-info
 func (h *DeviceHandler) GetGatewayInfo(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	resp, err := h.gatewayClient.GetDeviceInfo(c.UserContext(), &gateway.DeviceInfoReq{
-		DeviceID: imei,
-	})
+	resp, err := h.service.GatewayGetDeviceInfo(c.UserContext(), identifier)
 	if err != nil {
 		return err
 	}
@@ -249,22 +240,14 @@ func (h *DeviceHandler) GetGatewayInfo(c *fiber.Ctx) error {
 }

 // GetGatewaySlots 查询设备卡槽信息
+// GET /api/admin/devices/by-identifier/:identifier/gateway-slots
 func (h *DeviceHandler) GetGatewaySlots(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	resp, err := h.gatewayClient.GetSlotInfo(c.UserContext(), &gateway.DeviceInfoReq{
-		DeviceID: imei,
-	})
+	resp, err := h.service.GatewayGetSlotInfo(c.UserContext(), identifier)
 	if err != nil {
 		return err
 	}
@@ -273,10 +256,11 @@ func (h *DeviceHandler) GetGatewaySlots(c *fiber.Ctx) error {
 }

 // SetSpeedLimit 设置设备限速
+// PUT /api/admin/devices/by-identifier/:identifier/speed-limit
 func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

 	var req dto.SetSpeedLimitRequest
@@ -284,19 +268,7 @@ func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.SetSpeedLimit(c.UserContext(), &gateway.SpeedLimitReq{
-		DeviceID:      imei,
-		UploadSpeed:   req.UploadSpeed,
-		DownloadSpeed: req.DownloadSpeed,
-	})
-	if err != nil {
+	if err := h.service.GatewaySetSpeedLimit(c.UserContext(), identifier, &req); err != nil {
 		return err
 	}

@@ -304,27 +276,19 @@ func (h *DeviceHandler) SetSpeedLimit(c *fiber.Ctx) error {
 }

 // SetWiFi 设置设备 WiFi
+// PUT /api/admin/devices/by-identifier/:identifier/wifi
 func (h *DeviceHandler) SetWiFi(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	var req gateway.WiFiReq
+	var req dto.SetWiFiRequest
 	if err := c.BodyParser(&req); err != nil {
 		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	req.DeviceID = imei
-	err = h.gatewayClient.SetWiFi(c.UserContext(), &req)
-	if err != nil {
+	if err := h.service.GatewaySetWiFi(c.UserContext(), identifier, &req); err != nil {
 		return err
 	}

@@ -332,10 +296,11 @@ func (h *DeviceHandler) SetWiFi(c *fiber.Ctx) error {
 }

 // SwitchCard 切换设备使用的卡
+// POST /api/admin/devices/by-identifier/:identifier/switch-card
 func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

 	var req dto.SwitchCardRequest
@@ -343,18 +308,7 @@ func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.SwitchCard(c.UserContext(), &gateway.SwitchCardReq{
-		DeviceID:    imei,
-		TargetICCID: req.TargetICCID,
-	})
-	if err != nil {
+	if err := h.service.GatewaySwitchCard(c.UserContext(), identifier, &req); err != nil {
 		return err
 	}

@@ -362,23 +316,14 @@ func (h *DeviceHandler) SwitchCard(c *fiber.Ctx) error {
 }

 // RebootDevice 重启设备
+// POST /api/admin/devices/by-identifier/:identifier/reboot
 func (h *DeviceHandler) RebootDevice(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.RebootDevice(c.UserContext(), &gateway.DeviceOperationReq{
-		DeviceID: imei,
-	})
-	if err != nil {
+	if err := h.service.GatewayRebootDevice(c.UserContext(), identifier); err != nil {
 		return err
 	}

@@ -386,23 +331,14 @@ func (h *DeviceHandler) RebootDevice(c *fiber.Ctx) error {
 }

 // ResetDevice 恢复设备出厂设置
+// POST /api/admin/devices/by-identifier/:identifier/reset
 func (h *DeviceHandler) ResetDevice(c *fiber.Ctx) error {
-	imei := c.Params("imei")
-	if imei == "" {
-		return errors.New(errors.CodeInvalidParam, "设备号不能为空")
+	identifier := c.Params("identifier")
+	if identifier == "" {
+		return errors.New(errors.CodeInvalidParam, "设备标识符不能为空")
 	}

-	// 验证权限：查询数据库确认设备存在且用户有权限访问
-	_, err := h.service.GetByDeviceNo(c.UserContext(), imei)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.ResetDevice(c.UserContext(), &gateway.DeviceOperationReq{
-		DeviceID: imei,
-	})
-	if err != nil {
+	if err := h.service.GatewayResetDevice(c.UserContext(), identifier); err != nil {
 		return err
 	}

--- a/internal/handler/admin/iot_card.go
+++ b/internal/handler/admin/iot_card.go
@@ -3,7 +3,6 @@ package admin
 import (
 	"github.com/gofiber/fiber/v2"

-	"github.com/break/junhong_cmp_fiber/internal/gateway"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	iotCardService "github.com/break/junhong_cmp_fiber/internal/service/iot_card"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -13,14 +12,12 @@ import (
 )

 type IotCardHandler struct {
-	service       *iotCardService.Service
-	gatewayClient *gateway.Client
+	service *iotCardService.Service
 }

-func NewIotCardHandler(service *iotCardService.Service, gatewayClient *gateway.Client) *IotCardHandler {
+func NewIotCardHandler(service *iotCardService.Service) *IotCardHandler {
 	return &IotCardHandler{
-		service:       service,
-		gatewayClient: gatewayClient,
+		service: service,
 	}
 }

@@ -136,16 +133,7 @@ func (h *IotCardHandler) GetGatewayStatus(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	resp, err := h.gatewayClient.QueryCardStatus(c.UserContext(), &gateway.CardStatusReq{
-		CardNo: iccid,
-	})
+	resp, err := h.service.GatewayQueryCardStatus(c.UserContext(), iccid)
 	if err != nil {
 		return err
 	}
@@ -160,16 +148,7 @@ func (h *IotCardHandler) GetGatewayFlow(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	resp, err := h.gatewayClient.QueryFlow(c.UserContext(), &gateway.FlowQueryReq{
-		CardNo: iccid,
-	})
+	resp, err := h.service.GatewayQueryFlow(c.UserContext(), iccid)
 	if err != nil {
 		return err
 	}
@@ -184,16 +163,7 @@ func (h *IotCardHandler) GetGatewayRealname(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	resp, err := h.gatewayClient.QueryRealnameStatus(c.UserContext(), &gateway.CardStatusReq{
-		CardNo: iccid,
-	})
+	resp, err := h.service.GatewayQueryRealnameStatus(c.UserContext(), iccid)
 	if err != nil {
 		return err
 	}
@@ -208,16 +178,7 @@ func (h *IotCardHandler) GetRealnameLink(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	link, err := h.gatewayClient.GetRealnameLink(c.UserContext(), &gateway.CardStatusReq{
-		CardNo: iccid,
-	})
+	link, err := h.service.GatewayGetRealnameLink(c.UserContext(), iccid)
 	if err != nil {
 		return err
 	}
@@ -232,17 +193,7 @@ func (h *IotCardHandler) StopCard(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.StopCard(c.UserContext(), &gateway.CardOperationReq{
-		CardNo: iccid,
-	})
-	if err != nil {
+	if err := h.service.GatewayStopCard(c.UserContext(), iccid); err != nil {
 		return err
 	}

@@ -256,17 +207,7 @@ func (h *IotCardHandler) StartCard(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "ICCID不能为空")
 	}

-	// 验证权限：查询数据库确认卡存在且用户有权限访问
-	_, err := h.service.GetByICCID(c.UserContext(), iccid)
-	if err != nil {
-		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
-	}
-
-	// 调用 Gateway
-	err = h.gatewayClient.StartCard(c.UserContext(), &gateway.CardOperationReq{
-		CardNo: iccid,
-	})
-	if err != nil {
+	if err := h.service.GatewayStartCard(c.UserContext(), iccid); err != nil {
 		return err
 	}

--- a/internal/model/device.go
+++ b/internal/model/device.go
@@ -11,10 +11,13 @@ import (
 // Device 设备模型
 // 物联网设备(如 GPS 追踪器、智能传感器)
 // 通过 shop_id 区分所有权：NULL=平台库存，有值=店铺所有
+// 标识符说明：device_no 为虚拟号/别名，imei/sn 为设备真实标识
 type Device struct {
 	gorm.Model
 	BaseModel                          `gorm:"embedded"`
-	DeviceNo                           string     `gorm:"column:device_no;type:varchar(100);uniqueIndex:idx_device_no,where:deleted_at IS NULL;not null;comment:设备编号(唯一标识)" json:"device_no"`
+	DeviceNo                           string     `gorm:"column:device_no;type:varchar(100);uniqueIndex:idx_device_no,where:deleted_at IS NULL;not null;comment:设备虚拟号/别名(用户友好的短标识)" json:"device_no"`
+	IMEI                               string     `gorm:"column:imei;type:varchar(20);comment:设备IMEI(有蜂窝网络的设备标识,用于Gateway API调用)" json:"imei"`
+	SN                                 string     `gorm:"column:sn;type:varchar(100);comment:设备序列号(厂商唯一标识,预留字段)" json:"sn"`
 	DeviceName                         string     `gorm:"column:device_name;type:varchar(255);comment:设备名称" json:"device_name"`
 	DeviceModel                        string     `gorm:"column:device_model;type:varchar(100);comment:设备型号" json:"device_model"`
 	DeviceType                         string     `gorm:"column:device_type;type:varchar(50);comment:设备类型" json:"device_type"`
--- a/internal/model/dto/device_dto.go
+++ b/internal/model/dto/device_dto.go
@@ -19,7 +19,9 @@ type ListDeviceRequest struct {

 type DeviceResponse struct {
 	ID                  uint       `json:"id" description:"设备ID"`
-	DeviceNo            string     `json:"device_no" description:"设备号"`
+	DeviceNo            string     `json:"device_no" description:"设备虚拟号/别名"`
+	IMEI                string     `json:"imei" description:"设备IMEI"`
+	SN                  string     `json:"sn" description:"设备序列号"`
 	DeviceName          string     `json:"device_name" description:"设备名称"`
 	DeviceModel         string     `json:"device_model" description:"设备型号"`
 	DeviceType          string     `json:"device_type" description:"设备类型"`
@@ -52,8 +54,9 @@ type GetDeviceRequest struct {
 	ID uint `path:"id" description:"设备ID" required:"true"`
 }

-type GetDeviceByIMEIRequest struct {
-	DeviceNo string `path:"imei" description:"设备号(IMEI)" required:"true"`
+// GetDeviceByIdentifierRequest 通过标识符查询设备请求
+type GetDeviceByIdentifierRequest struct {
+	Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"`
 }

 type DeleteDeviceRequest struct {
@@ -148,21 +151,24 @@ type BatchSetDeviceSeriesBindngResponse struct {
 	FailedItems  []DeviceSeriesBindngFailedItem `json:"failed_items" description:"失败详情列表"`
 }

+// SetSpeedLimitRequest 设置设备限速请求
 type SetSpeedLimitRequest struct {
-	IMEI          string `path:"imei" description:"设备号(IMEI)" required:"true"`
-	UploadSpeed   int    `json:"upload_speed" validate:"required,min=1" required:"true" minimum:"1" description:"上行速率（KB/s）"`
-	DownloadSpeed int    `json:"download_speed" validate:"required,min=1" required:"true" minimum:"1" description:"下行速率（KB/s）"`
+	Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"`
+	SpeedLimit int    `json:"speed_limit" validate:"required,min=1" required:"true" minimum:"1" description:"限速值（KB/s）"`
 }

+// SetWiFiRequest 设置设备 WiFi 请求
 type SetWiFiRequest struct {
-	IMEI     string `path:"imei" description:"设备号(IMEI)" required:"true"`
-	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=8,max=63" required:"true" minLength:"8" maxLength:"63" description:"WiFi 密码"`
-	Enabled  int    `json:"enabled" validate:"required,oneof=0 1" required:"true" description:"启用状态（0:禁用, 1:启用）"`
+	Identifier string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"`
+	CardNo     string `json:"card_no" validate:"required" required:"true" description:"流量卡号（ICCID）"`
+	SSID       string `json:"ssid" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi 名称"`
+	Password   string `json:"password,omitempty" description:"WiFi 密码"`
+	Enabled    bool   `json:"enabled" description:"启用状态"`
 }

+// SwitchCardRequest 切卡请求
 type SwitchCardRequest struct {
-	IMEI        string `path:"imei" description:"设备号(IMEI)" required:"true"`
+	Identifier  string `path:"identifier" description:"设备标识符(支持虚拟号/IMEI/SN)" required:"true"`
 	TargetICCID string `json:"target_iccid" validate:"required" required:"true" description:"目标卡 ICCID"`
 }

--- a/internal/routes/device.go
+++ b/internal/routes/device.go
@@ -29,12 +29,13 @@ func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, imp
 		Auth:    true,
 	})

-	Register(devices, doc, groupPath, "GET", "/by-imei/:imei", handler.GetByIMEI, RouteSpec{
-		Summary: "通过设备号查询设备详情",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.GetDeviceByIMEIRequest),
-		Output:  new(dto.DeviceResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier", handler.GetByIdentifier, RouteSpec{
+		Summary:     "通过标识符查询设备详情",
+		Description: "支持通过虚拟号(device_no)、IMEI、SN 任意一个标识符查询设备。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.GetDeviceByIdentifierRequest),
+		Output:      new(dto.DeviceResponse),
+		Auth:        true,
 	})

 	Register(devices, doc, groupPath, "DELETE", "/:id", handler.Delete, RouteSpec{
@@ -145,59 +146,66 @@ func registerDeviceRoutes(router fiber.Router, handler *admin.DeviceHandler, imp
 		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-info", handler.GetGatewayInfo, RouteSpec{
-		Summary: "查询设备信息",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.GetDeviceByIMEIRequest),
-		Output:  new(gateway.DeviceInfoResp),
-		Auth:    true,
+	Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier/gateway-info", handler.GetGatewayInfo, RouteSpec{
+		Summary:     "查询设备信息",
+		Description: "通过虚拟号/IMEI/SN 查询设备网关信息。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.GetDeviceByIdentifierRequest),
+		Output:      new(gateway.DeviceInfoResp),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-slots", handler.GetGatewaySlots, RouteSpec{
-		Summary: "查询卡槽信息",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.GetDeviceByIMEIRequest),
-		Output:  new(gateway.SlotInfoResp),
-		Auth:    true,
+	Register(devices, doc, groupPath, "GET", "/by-identifier/:identifier/gateway-slots", handler.GetGatewaySlots, RouteSpec{
+		Summary:     "查询卡槽信息",
+		Description: "通过虚拟号/IMEI/SN 查询设备卡槽信息。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.GetDeviceByIdentifierRequest),
+		Output:      new(gateway.SlotInfoResp),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/speed-limit", handler.SetSpeedLimit, RouteSpec{
-		Summary: "设置限速",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.SetSpeedLimitRequest),
-		Output:  new(dto.EmptyResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "PUT", "/by-identifier/:identifier/speed-limit", handler.SetSpeedLimit, RouteSpec{
+		Summary:     "设置限速",
+		Description: "通过虚拟号/IMEI/SN 设置设备限速。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.SetSpeedLimitRequest),
+		Output:      new(dto.EmptyResponse),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/wifi", handler.SetWiFi, RouteSpec{
-		Summary: "设置 WiFi",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.SetWiFiRequest),
-		Output:  new(dto.EmptyResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "PUT", "/by-identifier/:identifier/wifi", handler.SetWiFi, RouteSpec{
+		Summary:     "设置 WiFi",
+		Description: "通过虚拟号/IMEI/SN 设置设备 WiFi。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.SetWiFiRequest),
+		Output:      new(dto.EmptyResponse),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "POST", "/by-imei/:imei/switch-card", handler.SwitchCard, RouteSpec{
-		Summary: "切卡",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.SwitchCardRequest),
-		Output:  new(dto.EmptyResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/switch-card", handler.SwitchCard, RouteSpec{
+		Summary:     "切卡",
+		Description: "通过虚拟号/IMEI/SN 切换设备当前使用的卡。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.SwitchCardRequest),
+		Output:      new(dto.EmptyResponse),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reboot", handler.RebootDevice, RouteSpec{
-		Summary: "重启设备",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.GetDeviceByIMEIRequest),
-		Output:  new(dto.EmptyResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/reboot", handler.RebootDevice, RouteSpec{
+		Summary:     "重启设备",
+		Description: "通过虚拟号/IMEI/SN 重启设备。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.GetDeviceByIdentifierRequest),
+		Output:      new(dto.EmptyResponse),
+		Auth:        true,
 	})

-	Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reset", handler.ResetDevice, RouteSpec{
-		Summary: "恢复出厂",
-		Tags:    []string{"设备管理"},
-		Input:   new(dto.GetDeviceByIMEIRequest),
-		Output:  new(dto.EmptyResponse),
-		Auth:    true,
+	Register(devices, doc, groupPath, "POST", "/by-identifier/:identifier/reset", handler.ResetDevice, RouteSpec{
+		Summary:     "恢复出厂",
+		Description: "通过虚拟号/IMEI/SN 恢复设备出厂设置。设备必须已配置 IMEI。",
+		Tags:        []string{"设备管理"},
+		Input:       new(dto.GetDeviceByIdentifierRequest),
+		Output:      new(dto.EmptyResponse),
+		Auth:        true,
 	})
 }
--- a/internal/service/device/gateway_service.go
+++ b/internal/service/device/gateway_service.go
@@ -0,0 +1,105 @@
+package device
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/gateway"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// getDeviceIMEI 通过标识符获取设备并验证 IMEI 存在
+// 提供统一的设备查找 + IMEI 校验逻辑，供所有 Gateway 代理方法复用
+func (s *Service) getDeviceIMEI(ctx context.Context, identifier string) (string, error) {
+	device, err := s.deviceStore.GetByIdentifier(ctx, identifier)
+	if err != nil {
+		return "", errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
+	}
+	if device.IMEI == "" {
+		return "", errors.New(errors.CodeInvalidParam, "该设备未配置 IMEI，无法调用网关接口")
+	}
+	return device.IMEI, nil
+}
+
+// GatewayGetDeviceInfo 通过标识符查询设备网关信息
+func (s *Service) GatewayGetDeviceInfo(ctx context.Context, identifier string) (*gateway.DeviceInfoResp, error) {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.GetDeviceInfo(ctx, &gateway.DeviceInfoReq{
+		DeviceID: imei,
+	})
+}
+
+// GatewayGetSlotInfo 通过标识符查询设备卡槽信息
+func (s *Service) GatewayGetSlotInfo(ctx context.Context, identifier string) (*gateway.SlotInfoResp, error) {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.GetSlotInfo(ctx, &gateway.DeviceInfoReq{
+		DeviceID: imei,
+	})
+}
+
+// GatewaySetSpeedLimit 通过标识符设置设备限速
+func (s *Service) GatewaySetSpeedLimit(ctx context.Context, identifier string, req *dto.SetSpeedLimitRequest) error {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return err
+	}
+	return s.gatewayClient.SetSpeedLimit(ctx, &gateway.SpeedLimitReq{
+		DeviceID:   imei,
+		SpeedLimit: req.SpeedLimit,
+	})
+}
+
+// GatewaySetWiFi 通过标识符设置设备 WiFi
+func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dto.SetWiFiRequest) error {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return err
+	}
+	return s.gatewayClient.SetWiFi(ctx, &gateway.WiFiReq{
+		CardNo:   req.CardNo,
+		DeviceID: imei,
+		SSID:     req.SSID,
+		Password: req.Password,
+		Enabled:  req.Enabled,
+	})
+}
+
+// GatewaySwitchCard 通过标识符切换设备使用的卡
+func (s *Service) GatewaySwitchCard(ctx context.Context, identifier string, req *dto.SwitchCardRequest) error {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return err
+	}
+	return s.gatewayClient.SwitchCard(ctx, &gateway.SwitchCardReq{
+		CardNo: imei,
+		ICCID:  req.TargetICCID,
+	})
+}
+
+// GatewayRebootDevice 通过标识符重启设备
+func (s *Service) GatewayRebootDevice(ctx context.Context, identifier string) error {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return err
+	}
+	return s.gatewayClient.RebootDevice(ctx, &gateway.DeviceOperationReq{
+		DeviceID: imei,
+	})
+}
+
+// GatewayResetDevice 通过标识符恢复设备出厂设置
+func (s *Service) GatewayResetDevice(ctx context.Context, identifier string) error {
+	imei, err := s.getDeviceIMEI(ctx, identifier)
+	if err != nil {
+		return err
+	}
+	return s.gatewayClient.ResetDevice(ctx, &gateway.DeviceOperationReq{
+		DeviceID: imei,
+	})
+}
--- a/internal/service/device/service.go
+++ b/internal/service/device/service.go
@@ -3,6 +3,7 @@ package device
 import (
 	"context"

+	"github.com/break/junhong_cmp_fiber/internal/gateway"
 	"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"
@@ -22,6 +23,7 @@ type Service struct {
 	shopPackageAllocationStore *postgres.ShopPackageAllocationStore
 	shopSeriesAllocationStore  *postgres.ShopSeriesAllocationStore
 	packageSeriesStore         *postgres.PackageSeriesStore
+	gatewayClient              *gateway.Client
 }

 func New(
@@ -34,6 +36,7 @@ func New(
 	shopPackageAllocationStore *postgres.ShopPackageAllocationStore,
 	shopSeriesAllocationStore *postgres.ShopSeriesAllocationStore,
 	packageSeriesStore *postgres.PackageSeriesStore,
+	gatewayClient *gateway.Client,
 ) *Service {
 	return &Service{
 		db:                         db,
@@ -45,6 +48,7 @@ func New(
 		shopPackageAllocationStore: shopPackageAllocationStore,
 		shopSeriesAllocationStore:  shopSeriesAllocationStore,
 		packageSeriesStore:         packageSeriesStore,
+		gatewayClient:              gatewayClient,
 	}
 }

@@ -168,6 +172,40 @@ func (s *Service) GetByDeviceNo(ctx context.Context, deviceNo string) (*dto.Devi
 	return s.toDeviceResponse(device, shopMap, seriesMap, bindingCounts), nil
 }

+// GetByIdentifier 通过任意标识符获取设备详情
+// 支持 device_no（虚拟号）、imei、sn 三个字段的自动匹配
+func (s *Service) GetByIdentifier(ctx context.Context, identifier string) (*dto.DeviceResponse, error) {
+	device, err := s.deviceStore.GetByIdentifier(ctx, identifier)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "设备不存在")
+		}
+		return nil, err
+	}
+
+	shopMap := s.loadShopData(ctx, []*model.Device{device})
+	seriesMap := s.loadSeriesNames(ctx, []*model.Device{device})
+	bindingCounts, err := s.getBindingCounts(ctx, []uint{device.ID})
+	if err != nil {
+		return nil, err
+	}
+
+	return s.toDeviceResponse(device, shopMap, seriesMap, bindingCounts), nil
+}
+
+// GetDeviceByIdentifier 通过任意标识符获取设备模型（内部使用，不转为 DTO）
+// 用于 Handler 层获取设备后提取 IMEI 调用 Gateway API
+func (s *Service) GetDeviceByIdentifier(ctx context.Context, identifier string) (*model.Device, error) {
+	device, err := s.deviceStore.GetByIdentifier(ctx, identifier)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "设备不存在或无权限访问")
+		}
+		return nil, err
+	}
+	return device, nil
+}
+
 func (s *Service) Delete(ctx context.Context, id uint) error {
 	device, err := s.deviceStore.GetByID(ctx, id)
 	if err != nil {
@@ -491,6 +529,8 @@ func (s *Service) toDeviceResponse(device *model.Device, shopMap map[uint]string
 	resp := &dto.DeviceResponse{
 		ID:                  device.ID,
 		DeviceNo:            device.DeviceNo,
+		IMEI:                device.IMEI,
+		SN:                  device.SN,
 		DeviceName:          device.DeviceName,
 		DeviceModel:         device.DeviceModel,
 		DeviceType:          device.DeviceType,
--- a/internal/service/iot_card/gateway_service.go
+++ b/internal/service/iot_card/gateway_service.go
@@ -0,0 +1,78 @@
+package iot_card
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/internal/gateway"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// validateCardAccess 通过 ICCID 验证卡存在且当前用户有权限访问
+// 利用 GORM 数据权限回调自动过滤，确保越权请求返回 404
+func (s *Service) validateCardAccess(ctx context.Context, iccid string) error {
+	_, err := s.iotCardStore.GetByICCID(ctx, iccid)
+	if err != nil {
+		return errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
+	}
+	return nil
+}
+
+// GatewayQueryCardStatus 查询卡实时状态
+func (s *Service) GatewayQueryCardStatus(ctx context.Context, iccid string) (*gateway.CardStatusResp, error) {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+		CardNo: iccid,
+	})
+}
+
+// GatewayQueryFlow 查询流量使用情况
+func (s *Service) GatewayQueryFlow(ctx context.Context, iccid string) (*gateway.FlowUsageResp, error) {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.QueryFlow(ctx, &gateway.FlowQueryReq{
+		CardNo: iccid,
+	})
+}
+
+// GatewayQueryRealnameStatus 查询实名认证状态
+func (s *Service) GatewayQueryRealnameStatus(ctx context.Context, iccid string) (*gateway.RealnameStatusResp, error) {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.QueryRealnameStatus(ctx, &gateway.CardStatusReq{
+		CardNo: iccid,
+	})
+}
+
+// GatewayGetRealnameLink 获取实名认证跳转链接
+func (s *Service) GatewayGetRealnameLink(ctx context.Context, iccid string) (*gateway.RealnameLinkResp, error) {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return nil, err
+	}
+	return s.gatewayClient.GetRealnameLink(ctx, &gateway.CardStatusReq{
+		CardNo: iccid,
+	})
+}
+
+// GatewayStopCard 停止卡服务（通过 Gateway API）
+func (s *Service) GatewayStopCard(ctx context.Context, iccid string) error {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return err
+	}
+	return s.gatewayClient.StopCard(ctx, &gateway.CardOperationReq{
+		CardNo: iccid,
+	})
+}
+
+// GatewayStartCard 恢复卡服务（通过 Gateway API）
+func (s *Service) GatewayStartCard(ctx context.Context, iccid string) error {
+	if err := s.validateCardAccess(ctx, iccid); err != nil {
+		return err
+	}
+	return s.gatewayClient.StartCard(ctx, &gateway.CardOperationReq{
+		CardNo: iccid,
+	})
+}
--- a/internal/store/postgres/device_store.go
+++ b/internal/store/postgres/device_store.go
@@ -57,6 +57,19 @@ func (s *DeviceStore) GetByDeviceNo(ctx context.Context, deviceNo string) (*mode
 	return &device, nil
 }

+// GetByIdentifier 通过任意标识符查找设备
+// 支持 device_no（虚拟号）、imei、sn 三个字段的自动匹配
+func (s *DeviceStore) GetByIdentifier(ctx context.Context, identifier string) (*model.Device, error) {
+	var device model.Device
+	query := s.db.WithContext(ctx).Where("device_no = ? OR imei = ? OR sn = ?", identifier, identifier, identifier)
+	// 应用数据权限过滤（NULL shop_id 对代理用户不可见）
+	query = middleware.ApplyShopFilter(ctx, query)
+	if err := query.First(&device).Error; err != nil {
+		return nil, err
+	}
+	return &device, nil
+}
+
 func (s *DeviceStore) GetByIDs(ctx context.Context, ids []uint) ([]*model.Device, error) {
 	var devices []*model.Device
 	if len(ids) == 0 {
--- a/migrations/000072_add_device_imei_sn_fields.down.sql
+++ b/migrations/000072_add_device_imei_sn_fields.down.sql
@@ -0,0 +1,12 @@
+-- 回滚设备标识符模型重构
+
+-- 删除索引
+DROP INDEX IF EXISTS idx_device_imei;
+DROP INDEX IF EXISTS idx_device_sn;
+
+-- 删除字段
+ALTER TABLE tb_device DROP COLUMN IF EXISTS imei;
+ALTER TABLE tb_device DROP COLUMN IF EXISTS sn;
+
+-- 恢复 device_no 注释
+COMMENT ON COLUMN tb_device.device_no IS '设备编号(唯一标识)';
--- a/migrations/000072_add_device_imei_sn_fields.up.sql
+++ b/migrations/000072_add_device_imei_sn_fields.up.sql
@@ -0,0 +1,23 @@
+-- 设备标识符模型重构
+-- 新增 imei 和 sn 字段，将 device_no 定位为虚拟号/别名
+-- imei: 设备 IMEI（有蜂窝网络的设备），用于调用 Gateway API
+-- sn: 设备序列号（厂商唯一标识），预留字段
+
+-- 新增 imei 字段（可空，有索引）
+ALTER TABLE tb_device
+ADD COLUMN imei VARCHAR(20);
+
+COMMENT ON COLUMN tb_device.imei IS '设备IMEI(有蜂窝网络的设备标识,用于Gateway API调用)';
+
+CREATE INDEX idx_device_imei ON tb_device(imei) WHERE deleted_at IS NULL AND imei IS NOT NULL;
+
+-- 新增 sn 字段（可空）
+ALTER TABLE tb_device
+ADD COLUMN sn VARCHAR(100);
+
+COMMENT ON COLUMN tb_device.sn IS '设备序列号(厂商唯一标识,预留字段)';
+
+CREATE INDEX idx_device_sn ON tb_device(sn) WHERE deleted_at IS NULL AND sn IS NOT NULL;
+
+-- 更新 device_no 字段注释，明确其虚拟号定位
+COMMENT ON COLUMN tb_device.device_no IS '设备虚拟号/别名(用户友好的短标识,业务方自定义格式)';
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-09
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/design.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/design.md
@@ -0,0 +1,194 @@
+## Context
+
+当前 `internal/gateway/` 包存在以下问题：
+
+1. **仅为薄 HTTP 包装**：`Client` 只有 `doRequest` 统一处理加密/签名/HTTP 请求，每个业务方法手动构建 `map[string]interface{}` 参数和手动 unmarshal 响应
+2. **Handler 层架构违规**：IotCard Handler（6 处）和 Device Handler（7 处）直接持有并调用 `gateway.Client`，跳过了 Service 层
+3. **无日志和重试**：Gateway 调用无请求/响应日志，网络错误无重试机制
+4. **代码重复度高**：13 个方法中大量 map 构建 + unmarshal 模式重复
+
+### 当前调用链
+
+```
+// 违规模式（当前）
+Handler.gatewayClient.XXX() → gateway.Client.doRequest() → HTTP
+
+// 正确模式（目标）
+Handler → Service.XXX() → gateway.Client.XXX() → HTTP
+```
+
+### 现有依赖关系
+
+| 使用者 | 使用方式 | 是否合规 |
+|--------|----------|---------|
+| `handler/admin/iot_card.go` | 直接调用 gatewayClient（6 处） | ❌ |
+| `handler/admin/device.go` | 直接调用 gatewayClient（7 处） | ❌ |
+| `service/iot_card/service.go` | 通过 Service 调用（1 处：QueryCardStatus） | ✅ |
+| `service/iot_card/stop_resume_service.go` | 通过 Service 调用（2 处：StopCard、StartCard） | ✅ |
+| `task/polling_handler.go` | Worker 任务中调用（合理） | ✅ |
+| `pkg/queue/handler.go` | Worker 中初始化 polling_handler | ✅ |
+
+## Goals / Non-Goals
+
+**Goals:**
+1. 消除手动 map 构建，请求结构体直接序列化为 Gateway 参数格式
+2. 添加泛型响应解析方法，消除重复 unmarshal 代码
+3. 在 `doRequest` 中添加 Zap 日志（请求路径、耗时、错误）
+4. 添加网络级错误重试机制（连接失败、超时等）
+5. 将 Handler 层 13 个 Gateway 直接调用下沉到对应 Service 层
+6. Handler 不再持有 `gateway.Client` 引用
+
+**Non-Goals:**
+- 异步接口（device/info、device/card-info）的轮询/回调处理
+- 新增未封装的 Gateway 端点
+- 修改 Gateway 上游项目
+- 修改 crypto.go（加密/签名逻辑不变）
+- 修改响应模型的字段（不确定上游实际返回结构，保持现状）
+
+## Decisions
+
+### Decision 1：请求参数序列化方式
+
+**选择**：请求结构体通过 `sonic.Marshal` 直接序列化后嵌入 `businessData.params` 字段
+
+**理由**：
+- 现有请求结构体（`SpeedLimitReq`、`WiFiReq` 等）已有正确的 `json` tag
+- 直接序列化后再嵌入 params，比手动构建 map 更安全、更不易出错
+- 保持 `doRequest` 的签名不变，只改变调用方式
+
+**实现**：
+```go
+// 之前
+params := map[string]interface{}{
+    "cardNo":     req.CardNo,
+    "speedLimit": req.SpeedLimit,
+}
+businessData := map[string]interface{}{"params": params}
+
+// 之后（方案 A：修改 doRequest 签名）
+// doRequest 接收结构体，内部自动包装为 {"params": ...}
+resp, err := c.doRequest(ctx, "/device/speed-limit", req)
+
+// doRequest 内部逻辑变更：
+// businessData → 直接是 req 结构体
+// 序列化时自动包装为 {"params": <req JSON>}
+```
+
+**替代方案**：保留 map 构建但提取为辅助方法 — 更侵入性小但不消除根因
+
+### Decision 2：泛型响应解析
+
+**选择**：提供 `doRequestWithResponse[T any]` 泛型方法
+
+```go
+func doRequestWithResponse[T any](ctx context.Context, path string, req interface{}) (*T, error) {
+    data, err := c.doRequest(ctx, path, req)
+    if err != nil {
+        return nil, err
+    }
+    var result T
+    if err := sonic.Unmarshal(data, &result); err != nil {
+        return nil, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败")
+    }
+    return &result, nil
+}
+```
+
+**理由**：每个返回结构体的方法都有相同的 unmarshal 模式，泛型可以完全消除
+
+### Decision 3：日志集成
+
+**选择**：在 `doRequest` 中注入 `*zap.Logger`（通过 Client 构造函数传入）
+
+**日志内容**：
+- 请求：路径、请求体大小
+- 成功响应：路径、耗时
+- 失败响应：路径、耗时、错误码、错误信息
+
+**日志级别**：
+- 正常请求：`Debug`（避免高频日志影响性能）
+- 错误：`Warn`（Gateway 业务错误）或 `Error`（网络错误）
+
+**理由**：
+- 不用全局 `zap.L()`，通过构造函数注入，保持可测试性
+- Debug 级别日志在生产环境默认关闭，不影响性能
+
+### Decision 4：重试机制
+
+**选择**：在 `doRequest` 内部实现简单重试逻辑
+
+**重试条件（仅网络级错误）**：
+- 连接失败（`net.Error` 的 `Temporary()`）
+- 请求超时（`context.DeadlineExceeded`，仅限 Client 自身超时，非用户 ctx 超时）
+- DNS 解析失败
+
+**不重试的情况**：
+- Gateway 业务错误（code != 200）
+- HTTP 状态码错误（4xx、5xx）
+- 用户 Context 取消
+- 加密/序列化失败
+
+**参数**：
+- 默认最大重试 2 次（共 3 次尝试）
+- 指数退避：100ms → 300ms
+- 通过 `WithRetry(maxRetries int)` 链式方法可配置
+
+**理由**：不引入外部重试库（如 `cenkalti/backoff`），保持零新依赖
+
+### Decision 5：分层修复策略
+
+**选择**：将 Handler 中的 Gateway 调用逐个迁移到对应 Service 层
+
+**IotCard Service 新增方法**（6 个）：
+- `QueryGatewayStatus(ctx, iccid) → (*gateway.CardStatusResp, error)` — 已有权限检查 + Gateway 调用
+- `QueryGatewayFlow(ctx, iccid) → (*gateway.FlowUsageResp, error)`
+- `QueryGatewayRealname(ctx, iccid) → (*gateway.RealnameStatusResp, error)`
+- `GetGatewayRealnameLink(ctx, iccid) → (*gateway.RealnameLinkResp, error)`
+- `GatewayStopCard(ctx, iccid) → error` — 注意：与已有的 `stop_resume_service.go` 中的 `StopCard` 区分，Handler 层的更简单（直接停卡，无业务逻辑）
+- `GatewayStartCard(ctx, iccid) → error`
+
+**Device Service 新增方法**（7 个）：
+- `GetGatewayInfo(ctx, identifier) → (*gateway.DeviceInfoResp, error)` — 包含 identifier→IMEI 转换
+- `GetGatewaySlots(ctx, identifier) → (*gateway.SlotInfoResp, error)`
+- `SetGatewaySpeedLimit(ctx, identifier, speedLimit) → error`
+- `SetGatewayWiFi(ctx, identifier, req) → error`
+- `GatewaySwitchCard(ctx, identifier, targetICCID) → error`
+- `GatewayRebootDevice(ctx, identifier) → error`
+- `GatewayResetDevice(ctx, identifier) → error`
+
+**Handler 变更**：
+- `IotCardHandler` 移除 `gatewayClient` 字段，改为调用 Service 方法
+- `DeviceHandler` 移除 `gatewayClient` 字段，改为调用 Service 方法
+- `NewIotCardHandler` 和 `NewDeviceHandler` 签名去掉 `gatewayClient` 参数
+- 权限检查（`service.GetByICCID`、`service.GetDeviceByIdentifier`）移入 Service 方法内部
+
+**Bootstrap 变更**：
+- `handlers.go`：Handler 初始化不再传入 `gatewayClient`
+- `services.go`：确保 Device Service 接收 `gatewayClient`（当前未注入）
+
+### Decision 6：Logger 注入到 Client
+
+**选择**：`NewClient` 增加 `logger *zap.Logger` 参数
+
+```go
+func NewClient(baseURL, appID, appSecret string, logger *zap.Logger) *Client
+```
+
+**理由**：
+- 保持依赖注入风格，与项目其他组件一致
+- 不使用全局 logger `zap.L()`
+
+## Risks / Trade-offs
+
+| 风险 | 缓解措施 |
+|------|----------|
+| IotCard Handler 已有的停卡/复机逻辑在 `stop_resume_service.go` 中有更复杂的实现（包含状态更新）| Handler 层的 `StopCard`/`StartCard` 是直接透传，与 `stop_resume_service` 不同。Service 层新增的方法命名区分（`GatewayStopCard` vs `StopCardService`）|
+| `doRequest` 签名变更影响所有调用方 | doRequest 保持返回 `json.RawMessage`，新增 `doRequestWithResponse` 泛型方法，渐进迁移 |
+| Logger 注入改变 `NewClient` 签名 | 只有 `cmd/api/main.go` 和 `cmd/worker/main.go` 两处调用，改动可控 |
+| 重试可能导致写操作重复执行（如 StopCard） | 仅对网络级错误重试，Gateway 已返回 response 的不重试。写操作的幂等性由 Gateway 端保证 |
+| 泛型需要 Go 1.18+ | 项目已使用 Go 1.25，无兼容问题 |
+
+## Open Questions
+
+1. ~~Device Service 当前没有 `gatewayClient` 注入，需要修改 `NewDeviceService` 构造函数~~ — 已确认需要修改
+2. IotCard Handler 的 `GatewayStopCard`/`GatewayStartCard` 与已有的 `stop_resume_service` 如何命名区分 — 方案：Handler 下沉的方法以 `Gateway` 前缀命名
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/proposal.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/proposal.md
@@ -0,0 +1,54 @@
+## Why
+
+当前 `internal/gateway/` 包只是一个薄 HTTP 客户端包装，每个方法手动构建 `map[string]interface{}` 参数、手动 unmarshal 响应，代码高度重复。更严重的是 Handler 层（`iot_card.go` 6 处、`device.go` 7 处）直接调用 `gateway.Client` 跳过了 Service 层，违反了项目 `Handler → Service → Store → Model` 的分层架构。此外缺少请求/响应日志和重试机制，排查问题困难，网络抖动直接导致失败。
+
+## What Changes
+
+### Gateway 包内部重构
+- **消除手动 map 构建**：请求结构体直接序列化，不再手动构建 `map[string]interface{}`
+- **泛型响应解析**：提供泛型方法统一处理 `doRequest + unmarshal` 模式，消除每个方法的重复 unmarshal 代码
+- **添加请求/响应日志**：在 `doRequest` 中集成 Zap 日志，记录请求路径、参数摘要、响应状态、耗时等关键信息
+- **添加重试机制**：对网络级错误（连接失败、DNS 解析失败、超时）自动重试，业务错误不重试；默认最多重试 2 次，指数退避
+- **验证响应模型**：对照 Gateway 上游源码验证 `DeviceInfoResp`、`SlotInfoResp` 等响应结构的字段准确性
+
+### 分层架构修复（**BREAKING**）
+- **IotCard Handler 的 6 个 Gateway 直接调用下沉到 IotCard Service 层**：`QueryCardStatus`、`QueryFlow`、`QueryRealnameStatus`、`GetRealnameLink`、`StopCard`、`StartCard`
+- **Device Handler 的 7 个 Gateway 直接调用下沉到 Device Service 层**：`GetDeviceInfo`、`GetSlotInfo`、`SetSpeedLimit`、`SetWiFi`、`SwitchCard`、`RebootDevice`、`ResetDevice`
+- Handler 层不再持有 `gateway.Client` 引用，所有 Gateway 调用通过 Service 层发起
+
+### 不在本次范围
+- 异步接口（`device/info`、`device/card-info`）的轮询/回调处理 — 暂不处理
+- 新增 Gateway 端点封装 — 只重构已有的
+
+## Capabilities
+
+### New Capabilities
+- `gateway-request-logging`: Gateway 请求/响应的日志记录能力，包括请求路径、参数摘要、响应状态码、耗时、错误信息
+- `gateway-retry`: Gateway 网络级错误的自动重试能力，支持指数退避和可配置的重试次数
+
+### Modified Capabilities
+- `gateway-client`: 消除手动 map 构建、泛型响应解析、请求结构体直接序列化
+- `iot-card`: IotCard Handler 中 6 个 Gateway 直接调用下沉到 Service 层，Handler 不再持有 gateway.Client
+- `iot-device`: Device Handler 中 7 个 Gateway 直接调用下沉到 Service 层，Handler 不再持有 gateway.Client
+
+## Impact
+
+### 代码变更范围
+- `internal/gateway/client.go` — 添加日志、重试、泛型方法
+- `internal/gateway/device.go` — 消除 map 构建，使用泛型响应解析
+- `internal/gateway/flow_card.go` — 消除 map 构建，使用泛型响应解析
+- `internal/gateway/models.go` — 可能调整请求结构体（添加 JSON tag 使其可直接序列化）
+- `internal/handler/admin/iot_card.go` — 移除 `gatewayClient` 依赖，Gateway 调用改为调 Service
+- `internal/handler/admin/device.go` — 移除 `gatewayClient` 依赖，Gateway 调用改为调 Service
+- `internal/service/iot_card/service.go` — 新增 6 个 Gateway 代理方法
+- `internal/service/device/service.go` — 新增 7 个 Gateway 代理方法
+- `internal/bootstrap/handlers.go` — Handler 初始化不再传入 gatewayClient
+- `internal/bootstrap/services.go` — Service 初始化需确保 gatewayClient 注入
+
+### API 影响
+- 无 API 签名变更，前端无感知
+- 行为上完全兼容，只是内部调用链路变更
+
+### 依赖影响
+- 新增 `go.uber.org/zap` 在 gateway 包中的依赖（项目已有）
+- 无新外部依赖
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-client/spec.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-client/spec.md
@@ -0,0 +1,100 @@
+## MODIFIED Requirements
+
+### Requirement: 统一请求方法
+
+系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。请求参数 SHALL 直接接收结构体，内部自动序列化并包装为 `{"params": <JSON>}` 格式。
+
+#### Scenario: 请求参数自动序列化
+
+- **WHEN** 调用 `doRequest(ctx, "/device/speed-limit", &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})`
+- **THEN** 请求结构体自动通过 `sonic.Marshal` 序列化
+- **AND** 序列化结果嵌入 `{"params": <序列化JSON>}` 中进行加密和签名
+
+#### Scenario: 成功的 API 调用
+
+- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)`
+- **THEN** 业务数据使用 AES-128-ECB 加密
+- **AND** 请求使用 MD5 签名
+- **AND** HTTP POST 发送到 `{baseURL}/flow-card/status`
+- **AND** 响应中的 `data` 字段返回为 `json.RawMessage`
+
+#### Scenario: 网络错误
+
+- **WHEN** HTTP 请求失败（网络中断、DNS 解析失败）
+- **THEN** 返回 `CodeGatewayError` 错误
+- **AND** 错误信息包含原始网络错误
+
+#### Scenario: 请求超时
+
+- **WHEN** HTTP 请求超过配置的超时时间
+- **THEN** 返回 `CodeGatewayTimeout` 错误
+- **AND** Context 超时错误被正确识别
+
+#### Scenario: 响应格式错误
+
+- **WHEN** Gateway 响应无法解析为 JSON
+- **THEN** 返回 `CodeGatewayInvalidResp` 错误
+
+#### Scenario: Gateway 业务错误
+
+- **WHEN** Gateway 响应中 `code != 200`
+- **THEN** 返回 `CodeGatewayError` 错误
+- **AND** 错误信息包含 Gateway 的 code 和 msg
+
+### Requirement: 泛型响应解析方法
+
+系统 SHALL 提供 `doRequestWithResponse[T any]` 泛型方法，自动完成请求发送和响应反序列化。
+
+#### Scenario: 自动反序列化响应
+
+- **WHEN** 调用 `doRequestWithResponse[CardStatusResp](ctx, "/flow-card/status", req)`
+- **THEN** 返回 `*CardStatusResp` 类型的结构体
+- **AND** 内部调用 `doRequest` 获取 `json.RawMessage` 后自动 unmarshal
+
+#### Scenario: 反序列化失败
+
+- **WHEN** Gateway 返回的 JSON 无法匹配目标结构体
+- **THEN** 返回 `CodeGatewayInvalidResp` 错误
+- **AND** 错误信息为 "解析 Gateway 响应失败"
+
+### Requirement: 请求结构体直接序列化
+
+系统 SHALL 消除手动 `map[string]interface{}` 构建，所有业务方法直接将请求结构体传递给 `doRequest` 或 `doRequestWithResponse`。
+
+#### Scenario: 设备限速请求
+
+- **WHEN** 调用 `SetSpeedLimit(ctx, &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})`
+- **THEN** `SpeedLimitReq` 结构体直接序列化为 JSON
+- **AND** 不再手动构建 `map[string]interface{}`
+
+#### Scenario: 流量卡停机请求
+
+- **WHEN** 调用 `StopCard(ctx, &CardOperationReq{CardNo: "xxx", Extend: "ext"})`
+- **THEN** `CardOperationReq` 结构体直接序列化
+- **AND** `Extend` 字段通过 `json:"extend,omitempty"` 标签在为空时自动省略
+
+### Requirement: Gateway 客户端结构
+
+系统 SHALL 提供 `gateway.Client` 结构体，封装所有 Gateway API 调用。
+
+客户端字段：
+- `baseURL string` - Gateway API 基础 URL
+- `appID string` - 应用 ID
+- `appSecret string` - 应用密钥
+- `httpClient *http.Client` - HTTP 客户端（支持连接复用）
+- `timeout time.Duration` - 请求超时时间
+- `logger *zap.Logger` - 日志记录器
+- `maxRetries int` - 最大重试次数
+
+#### Scenario: 创建 Gateway 客户端
+
+- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)`
+- **THEN** 返回已初始化的 `Client` 实例
+- **AND** HTTP 客户端配置正确（支持 Keep-Alive）
+- **AND** 默认最大重试次数为 2
+
+#### Scenario: 配置超时时间
+
+- **WHEN** 调用 `client.WithTimeout(30 * time.Second)`
+- **THEN** 客户端的 `timeout` 字段更新为 30 秒
+- **AND** 返回客户端自身（支持链式调用）
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-request-logging/spec.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-request-logging/spec.md
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Gateway 请求日志
+
+系统 SHALL 在每次 Gateway API 调用时记录请求日志，包含请求路径和请求体大小。
+
+#### Scenario: 正常请求记录 Debug 日志
+
+- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` 且请求成功
+- **THEN** 记录 Debug 级别日志
+- **AND** 日志包含字段：`path`（请求路径）、`duration`（耗时）
+
+#### Scenario: Gateway 业务错误记录 Warn 日志
+
+- **WHEN** Gateway 返回 `code != 200` 的业务错误
+- **THEN** 记录 Warn 级别日志
+- **AND** 日志包含字段：`path`、`duration`、`gateway_code`（Gateway 状态码）、`gateway_msg`（Gateway 错误信息）
+
+#### Scenario: 网络错误记录 Error 日志
+
+- **WHEN** HTTP 请求失败（连接失败、超时、DNS 解析失败等）
+- **THEN** 记录 Error 级别日志
+- **AND** 日志包含字段：`path`、`duration`、`error`（错误信息）
+
+### Requirement: Logger 依赖注入
+
+系统 SHALL 通过构造函数将 `*zap.Logger` 注入到 `Client` 中。
+
+#### Scenario: 创建带日志的客户端
+
+- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)`
+- **THEN** 客户端使用传入的 logger 记录日志
+- **AND** 不使用全局 `zap.L()`
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-retry/spec.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/gateway-retry/spec.md
@@ -0,0 +1,51 @@
+## ADDED Requirements
+
+### Requirement: 网络级错误自动重试
+
+系统 SHALL 在 Gateway API 调用遇到网络级错误时自动重试。
+
+#### Scenario: 连接失败自动重试
+
+- **WHEN** Gateway HTTP 请求因连接失败（TCP 连接拒绝、DNS 解析失败）失败
+- **THEN** 系统自动重试，最多重试 2 次（共 3 次尝试）
+- **AND** 重试间隔使用指数退避（100ms → 300ms）
+
+#### Scenario: Client 超时自动重试
+
+- **WHEN** Gateway HTTP 请求因 Client 配置的超时时间到期而失败
+- **THEN** 系统自动重试
+- **AND** 用户传入的 Context 未被取消
+
+#### Scenario: Gateway 业务错误不重试
+
+- **WHEN** Gateway 返回 HTTP 200 但业务状态码 `code != 200`
+- **THEN** 系统不重试，直接返回业务错误
+
+#### Scenario: HTTP 状态码错误不重试
+
+- **WHEN** Gateway 返回 HTTP 4xx 或 5xx 状态码
+- **THEN** 系统不重试，直接返回错误
+
+#### Scenario: 用户 Context 取消不重试
+
+- **WHEN** 用户传入的 Context 被取消
+- **THEN** 系统立即停止，不重试
+
+#### Scenario: 加密或序列化错误不重试
+
+- **WHEN** 请求参数加密或序列化失败
+- **THEN** 系统不重试，直接返回错误
+
+### Requirement: 重试配置
+
+系统 SHALL 支持通过链式方法配置重试参数。
+
+#### Scenario: 自定义最大重试次数
+
+- **WHEN** 调用 `client.WithRetry(3)` 后发起 API 请求
+- **THEN** 网络级错误时最多重试 3 次（共 4 次尝试）
+
+#### Scenario: 禁用重试
+
+- **WHEN** 调用 `client.WithRetry(0)` 后发起 API 请求
+- **THEN** 不进行任何重试
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-card/spec.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-card/spec.md
@@ -0,0 +1,89 @@
+## MODIFIED Requirements
+
+### Requirement: IotCard Handler 分层修复
+
+IotCard Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 IotCard Service 层发起。
+
+#### Scenario: IotCardHandler 不持有 gatewayClient
+
+- **WHEN** 创建 `IotCardHandler` 实例
+- **THEN** `NewIotCardHandler` 构造函数不接收 `gateway.Client` 参数
+- **AND** Handler 结构体不包含 `gatewayClient` 字段
+
+#### Scenario: 查询卡实时状态通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayStatus` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayStatus(ctx, iccid)`
+- **AND** Service 内部完成权限检查 + Gateway API 调用
+
+#### Scenario: 查询流量使用通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayFlow` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayFlow(ctx, iccid)`
+
+#### Scenario: 查询实名状态通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayRealname` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayRealname(ctx, iccid)`
+
+#### Scenario: 获取实名链接通过 Service 调用
+
+- **WHEN** Handler 的 `GetRealnameLink` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewayRealnameLink(ctx, iccid)`
+
+#### Scenario: 停卡通过 Service 调用
+
+- **WHEN** Handler 的 `StopCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewayStopCard(ctx, iccid)`
+
+#### Scenario: 复机通过 Service 调用
+
+- **WHEN** Handler 的 `StartCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewayStartCard(ctx, iccid)`
+
+### Requirement: IotCard Service Gateway 代理方法
+
+IotCard Service SHALL 提供 Gateway API 的代理方法，封装权限检查和 Gateway 调用。
+
+#### Scenario: QueryGatewayStatus 方法
+
+- **WHEN** 调用 `service.QueryGatewayStatus(ctx, iccid)`
+- **THEN** 先通过 `GetByICCID` 验证卡存在且用户有权限
+- **AND** 然后调用 `gatewayClient.QueryCardStatus`
+- **AND** 返回 `*gateway.CardStatusResp`
+
+#### Scenario: QueryGatewayFlow 方法
+
+- **WHEN** 调用 `service.QueryGatewayFlow(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.QueryFlow`
+- **AND** 返回 `*gateway.FlowUsageResp`
+
+#### Scenario: QueryGatewayRealname 方法
+
+- **WHEN** 调用 `service.QueryGatewayRealname(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.QueryRealnameStatus`
+- **AND** 返回 `*gateway.RealnameStatusResp`
+
+#### Scenario: GetGatewayRealnameLink 方法
+
+- **WHEN** 调用 `service.GetGatewayRealnameLink(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.GetRealnameLink`
+- **AND** 返回 `*gateway.RealnameLinkResp`
+
+#### Scenario: GatewayStopCard 方法
+
+- **WHEN** 调用 `service.GatewayStopCard(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.StopCard`
+- **AND** 返回 error
+
+#### Scenario: GatewayStartCard 方法
+
+- **WHEN** 调用 `service.GatewayStartCard(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.StartCard`
+- **AND** 返回 error
+
+#### Scenario: 卡不存在或无权限
+
+- **WHEN** 调用任意 Gateway 代理方法且 ICCID 对应的卡不存在或用户无权限
+- **THEN** 返回 `CodeNotFound` 错误
+- **AND** 错误信息为 "卡不存在或无权限访问"
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-device/spec.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/specs/iot-device/spec.md
@@ -0,0 +1,123 @@
+## MODIFIED Requirements
+
+### Requirement: Device Handler 分层修复
+
+Device Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 Device Service 层发起。
+
+#### Scenario: DeviceHandler 不持有 gatewayClient
+
+- **WHEN** 创建 `DeviceHandler` 实例
+- **THEN** `NewDeviceHandler` 构造函数不接收 `gateway.Client` 参数
+- **AND** Handler 结构体不包含 `gatewayClient` 字段
+
+#### Scenario: 查询设备网关信息通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayInfo` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewayInfo(ctx, identifier)`
+
+#### Scenario: 查询设备卡槽信息通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewaySlots` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewaySlots(ctx, identifier)`
+
+#### Scenario: 设置设备限速通过 Service 调用
+
+- **WHEN** Handler 的 `SetSpeedLimit` 方法被调用
+- **THEN** Handler 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)`
+
+#### Scenario: 设置设备 WiFi 通过 Service 调用
+
+- **WHEN** Handler 的 `SetWiFi` 方法被调用
+- **THEN** Handler 调用 `service.SetGatewayWiFi(ctx, identifier, req)`
+
+#### Scenario: 切换设备卡通过 Service 调用
+
+- **WHEN** Handler 的 `SwitchCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)`
+
+#### Scenario: 重启设备通过 Service 调用
+
+- **WHEN** Handler 的 `RebootDevice` 方法被调用
+- **THEN** Handler 调用 `service.GatewayRebootDevice(ctx, identifier)`
+
+#### Scenario: 恢复出厂设置通过 Service 调用
+
+- **WHEN** Handler 的 `ResetDevice` 方法被调用
+- **THEN** Handler 调用 `service.GatewayResetDevice(ctx, identifier)`
+
+### Requirement: Device Service Gateway 代理方法
+
+Device Service SHALL 提供 Gateway API 的代理方法，封装设备标识符解析、IMEI 检查和 Gateway 调用。
+
+#### Scenario: GetGatewayInfo 方法
+
+- **WHEN** 调用 `service.GetGatewayInfo(ctx, identifier)`
+- **THEN** 先通过 `GetDeviceByIdentifier` 查找设备并验证权限
+- **AND** 检查设备 IMEI 不为空
+- **AND** 调用 `gatewayClient.GetDeviceInfo` 传入设备 IMEI
+- **AND** 返回 `*gateway.DeviceInfoResp`
+
+#### Scenario: GetGatewaySlots 方法
+
+- **WHEN** 调用 `service.GetGatewaySlots(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI 不为空
+- **AND** 调用 `gatewayClient.GetSlotInfo`
+- **AND** 返回 `*gateway.SlotInfoResp`
+
+#### Scenario: SetGatewaySpeedLimit 方法
+
+- **WHEN** 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SetSpeedLimit` 传入设备 IMEI 和限速值
+
+#### Scenario: SetGatewayWiFi 方法
+
+- **WHEN** 调用 `service.SetGatewayWiFi(ctx, identifier, cardNo, ssid, password string, enabled bool)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SetWiFi` 传入设备 IMEI、cardNo（ICCID）、ssid、password、enabled
+
+#### Scenario: GatewaySwitchCard 方法
+
+- **WHEN** 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SwitchCard` 传入设备 IMEI 作为 cardNo 和目标 ICCID
+
+#### Scenario: GatewayRebootDevice 方法
+
+- **WHEN** 调用 `service.GatewayRebootDevice(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.RebootDevice` 传入设备 IMEI
+
+#### Scenario: GatewayResetDevice 方法
+
+- **WHEN** 调用 `service.GatewayResetDevice(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.ResetDevice` 传入设备 IMEI
+
+#### Scenario: 设备 IMEI 为空
+
+- **WHEN** 调用任意 Gateway 代理方法且设备的 IMEI 字段为空
+- **THEN** 返回 `CodeInvalidParam` 错误
+- **AND** 错误信息说明该设备未配置 IMEI
+
+#### Scenario: 设备不存在或无权限
+
+- **WHEN** 调用任意 Gateway 代理方法且标识符无法匹配到设备
+- **THEN** 返回对应的错误（由 `GetDeviceByIdentifier` 返回）
+
+### Requirement: Device Service 接收 Gateway Client
+
+Device Service SHALL 在构造函数中接收 `*gateway.Client` 依赖。
+
+#### Scenario: Device Service 初始化
+
+- **WHEN** 创建 Device Service 实例
+- **THEN** 构造函数接收 `gatewayClient *gateway.Client` 参数
+- **AND** 存储为 Service 的内部字段
+- **AND** `gatewayClient` 可以为 nil（Gateway 配置缺失时）
+
+#### Scenario: Gateway Client 为 nil 时调用 Gateway 方法
+
+- **WHEN** `gatewayClient` 为 nil 且调用任意 Gateway 代理方法
+- **THEN** 返回 `CodeGatewayError` 错误
+- **AND** 错误信息为 "Gateway 客户端未配置"
--- a/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md
+++ b/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md
@@ -0,0 +1,101 @@
+## 1. Gateway Client 核心重构
+
+- [x] 1.1 修改 `Client` 结构体：添加 `logger *zap.Logger` 和 `maxRetries int` 字段
+- [x] 1.2 修改 `NewClient` 签名：增加 `logger *zap.Logger` 参数，默认 `maxRetries = 2`
+- [x] 1.3 添加 `WithRetry(maxRetries int) *Client` 链式方法
+- [x] 1.4 修改 `doRequest`：请求参数改为直接接收结构体（`interface{}`），内部自动包装为 `{"params": <JSON>}` 格式
+- [x] 1.5 在 `doRequest` 中添加请求/响应日志（Debug 级别正常、Warn 级别业务错误、Error 级别网络错误）
+- [x] 1.6 在 `doRequest` 中添加网络级错误重试逻辑（指数退避 100ms→300ms，仅对连接失败/Client 超时/DNS 失败重试）
+- [x] 1.7 添加 `doRequestWithResponse[T any]` 泛型方法，自动完成 doRequest + unmarshal
+- [x] 1.8 更新 `cmd/api/main.go` 和 `cmd/worker/main.go` 中的 `initGateway` 函数，传入 logger
+- [x] 1.9 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 2. 流量卡方法重构（消除 map 构建和重复 unmarshal）
+
+- [x] 2.1 重构 `QueryCardStatus`：使用 `doRequestWithResponse[CardStatusResp]`，去掉手动 map 构建
+- [x] 2.2 重构 `QueryFlow`：使用 `doRequestWithResponse[FlowUsageResp]`
+- [x] 2.3 重构 `QueryRealnameStatus`：使用 `doRequestWithResponse[RealnameStatusResp]`
+- [x] 2.4 重构 `StopCard`：直接传 req 给 doRequest，去掉手动 map
+- [x] 2.5 重构 `StartCard`：同上
+- [x] 2.6 重构 `GetRealnameLink`：使用 `doRequestWithResponse[RealnameLinkResp]`
+- [x] 2.7 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 3. 设备方法重构（消除 map 构建和重复 unmarshal）
+
+- [x] 3.1 重构 `GetDeviceInfo`：使用 `doRequestWithResponse[DeviceInfoResp]`，去掉手动 map
+- [x] 3.2 重构 `GetSlotInfo`：使用 `doRequestWithResponse[SlotInfoResp]`
+- [x] 3.3 重构 `SetSpeedLimit`：直接传 req 给 doRequest
+- [x] 3.4 重构 `SetWiFi`：同上
+- [x] 3.5 重构 `SwitchCard`：同上
+- [x] 3.6 重构 `ResetDevice`：同上
+- [x] 3.7 重构 `RebootDevice`：同上
+- [x] 3.8 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 4. Device Service 注入 Gateway Client
+
+- [x] 4.1 修改 `internal/service/device/service.go`：Service 结构体添加 `gatewayClient *gateway.Client` 字段
+- [x] 4.2 修改 `New` 构造函数：增加 `gatewayClient *gateway.Client` 参数
+- [x] 4.3 修改 `internal/bootstrap/services.go`：Device Service 初始化时传入 `deps.GatewayClient`
+- [x] 4.4 验证：`go build ./...` 编译通过
+
+## 5. Device Service Gateway 代理方法
+
+- [x] 5.1 实现 `GatewayGetDeviceInfo(ctx, identifier) → (*gateway.DeviceInfoResp, error)`：identifier→设备→检查IMEI→调用 Gateway
+- [x] 5.2 实现 `GatewayGetSlotInfo(ctx, identifier) → (*gateway.SlotInfoResp, error)`
+- [x] 5.3 实现 `GatewaySetSpeedLimit(ctx, identifier string, req *dto.SetSpeedLimitRequest) → error`
+- [x] 5.4 实现 `GatewaySetWiFi(ctx, identifier string, req *dto.SetWiFiRequest) → error`
+- [x] 5.5 实现 `GatewaySwitchCard(ctx, identifier string, req *dto.SwitchCardRequest) → error`
+- [x] 5.6 实现 `GatewayRebootDevice(ctx, identifier string) → error`
+- [x] 5.7 实现 `GatewayResetDevice(ctx, identifier string) → error`
+- [x] 5.8 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 6. IotCard Service Gateway 代理方法
+
+- [x] 6.1 实现 `GatewayQueryCardStatus(ctx, iccid) → (*gateway.CardStatusResp, error)`：权限检查→Gateway 调用
+- [x] 6.2 实现 `GatewayQueryFlow(ctx, iccid) → (*gateway.FlowUsageResp, error)`
+- [x] 6.3 实现 `GatewayQueryRealnameStatus(ctx, iccid) → (*gateway.RealnameStatusResp, error)`
+- [x] 6.4 实现 `GatewayGetRealnameLink(ctx, iccid) → (*gateway.RealnameLinkResp, error)`
+- [x] 6.5 实现 `GatewayStopCard(ctx, iccid) → error`
+- [x] 6.6 实现 `GatewayStartCard(ctx, iccid) → error`
+- [x] 6.7 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 7. Handler 分层修复 — Device Handler
+
+- [x] 7.1 修改 `DeviceHandler` 结构体：移除 `gatewayClient` 字段
+- [x] 7.2 修改 `NewDeviceHandler`：移除 `gatewayClient` 参数
+- [x] 7.3 重构 `GetGatewayInfo`：改为调用 `h.service.GatewayGetDeviceInfo(ctx, identifier)`
+- [x] 7.4 重构 `GetGatewaySlots`：改为调用 `h.service.GatewayGetSlotInfo(ctx, identifier)`
+- [x] 7.5 重构 `SetSpeedLimit`：改为调用 `h.service.GatewaySetSpeedLimit(ctx, identifier, &req)`
+- [x] 7.6 重构 `SetWiFi`：改为调用 `h.service.GatewaySetWiFi(ctx, identifier, &req)`
+- [x] 7.7 重构 `SwitchCard`：改为调用 `h.service.GatewaySwitchCard(ctx, identifier, &req)`
+- [x] 7.8 重构 `RebootDevice`：改为调用 `h.service.GatewayRebootDevice(ctx, identifier)`
+- [x] 7.9 重构 `ResetDevice`：改为调用 `h.service.GatewayResetDevice(ctx, identifier)`
+- [x] 7.10 移除 `import "github.com/break/junhong_cmp_fiber/internal/gateway"` 导入（如果不再需要）
+- [x] 7.11 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 8. Handler 分层修复 — IotCard Handler
+
+- [x] 8.1 修改 `IotCardHandler` 结构体：移除 `gatewayClient` 字段
+- [x] 8.2 修改 `NewIotCardHandler`：移除 `gatewayClient` 参数
+- [x] 8.3 重构 `GetGatewayStatus`：改为调用 `h.service.GatewayQueryCardStatus(ctx, iccid)`
+- [x] 8.4 重构 `GetGatewayFlow`：改为调用 `h.service.GatewayQueryFlow(ctx, iccid)`
+- [x] 8.5 重构 `GetGatewayRealname`：改为调用 `h.service.GatewayQueryRealnameStatus(ctx, iccid)`
+- [x] 8.6 重构 `GetRealnameLink`：改为调用 `h.service.GatewayGetRealnameLink(ctx, iccid)`
+- [x] 8.7 重构 `StopCard`：改为调用 `h.service.GatewayStopCard(ctx, iccid)`
+- [x] 8.8 重构 `StartCard`：改为调用 `h.service.GatewayStartCard(ctx, iccid)`
+- [x] 8.9 移除 `import "github.com/break/junhong_cmp_fiber/internal/gateway"` 导入（如果不再需要）
+- [x] 8.10 验证：`go build ./...` 编译通过，`lsp_diagnostics` 无错误
+
+## 9. Bootstrap 层适配
+
+- [x] 9.1 修改 `internal/bootstrap/handlers.go`：`NewIotCardHandler` 不再传入 `deps.GatewayClient`
+- [x] 9.2 修改 `internal/bootstrap/handlers.go`：`NewDeviceHandler` 不再传入 `deps.GatewayClient`
+- [x] 9.3 验证：`go build ./...` 编译通过，确认所有 Handler/Service/Bootstrap 链路正确
+
+## 10. 最终验证
+
+- [x] 10.1 `go build ./...` 全量编译通过
+- [x] 10.2 `go vet ./...` 无问题
+- [x] 10.3 所有修改文件 `lsp_diagnostics` 无错误
+- [x] 10.4 确认无遗留的 Handler 层 Gateway 直接调用（grep 验证）
+- [x] 10.5 确认 Worker 端（`polling_handler.go`、`queue/handler.go`）不受影响
--- a/openspec/specs/gateway-client/spec.md
+++ b/openspec/specs/gateway-client/spec.md
@@ -14,12 +14,15 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。
 - `appSecret string` - 应用密钥
 - `httpClient *http.Client` - HTTP 客户端（支持连接复用）
 - `timeout time.Duration` - 请求超时时间
+- `logger *zap.Logger` - 日志记录器
+- `maxRetries int` - 最大重试次数

 #### Scenario: 创建 Gateway 客户端

- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret)`
+- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)`
 - **THEN** 返回已初始化的 `Client` 实例
 - **AND** HTTP 客户端配置正确（支持 Keep-Alive）
+- **AND** 默认最大重试次数为 2

 #### Scenario: 配置超时时间

@@ -29,15 +32,21 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。

 ### Requirement: 统一请求方法

-系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。
+系统 SHALL 提供 `doRequest` 方法，统一处理加密、签名、HTTP 请求和响应解析。请求参数 SHALL 直接接收结构体，内部自动序列化并包装为 `{"params": <JSON>}` 格式。
+
+#### Scenario: 请求参数自动序列化
+
+- **WHEN** 调用 `doRequest(ctx, "/device/speed-limit", &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})`
+- **THEN** 请求结构体自动通过 `sonic.Marshal` 序列化
+- **AND** 序列化结果嵌入 `{"params": <序列化JSON>}` 中进行加密和签名

 #### Scenario: 成功的 API 调用

- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", businessData)`
+- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)`
 - **THEN** 业务数据使用 AES-128-ECB 加密
 - **AND** 请求使用 MD5 签名
 - **AND** HTTP POST 发送到 `{baseURL}/flow-card/status`
- **AND** 响应中的 `data` 字段解密并返回
+- **AND** 响应中的 `data` 字段返回为 `json.RawMessage`

 #### Scenario: 网络错误

@@ -55,7 +64,7 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。

 - **WHEN** Gateway 响应无法解析为 JSON
 - **THEN** 返回 `CodeGatewayInvalidResp` 错误
- **AND** 错误信息包含原始响应内容（限制 200 字符）
+- **AND** 错误信息包含原始响应内容

 #### Scenario: Gateway 业务错误

@@ -63,6 +72,37 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。
 - **THEN** 返回 `CodeGatewayError` 错误
 - **AND** 错误信息包含 Gateway 的 code 和 msg

+### Requirement: 泛型响应解析方法
+
+系统 SHALL 提供 `doRequestWithResponse[T any]` 泛型方法，自动完成请求发送和响应反序列化。
+
+#### Scenario: 自动反序列化响应
+
+- **WHEN** 调用 `doRequestWithResponse[CardStatusResp](ctx, "/flow-card/status", req)`
+- **THEN** 返回 `*CardStatusResp` 类型的结构体
+- **AND** 内部调用 `doRequest` 获取 `json.RawMessage` 后自动 unmarshal
+
+#### Scenario: 反序列化失败
+
+- **WHEN** Gateway 返回的 JSON 无法匹配目标结构体
+- **THEN** 返回 `CodeGatewayInvalidResp` 错误
+- **AND** 错误信息为 "解析 Gateway 响应失败"
+
+### Requirement: 请求结构体直接序列化
+
+系统 SHALL 消除手动 `map[string]interface{}` 构建，所有业务方法直接将请求结构体传递给 `doRequest` 或 `doRequestWithResponse`。
+
+#### Scenario: 设备限速请求
+
+- **WHEN** 调用 `SetSpeedLimit(ctx, &SpeedLimitReq{CardNo: "xxx", SpeedLimit: 1024})`
+- **THEN** `SpeedLimitReq` 结构体直接序列化为 JSON
+- **AND** 不再手动构建 `map[string]interface{}`
+
+#### Scenario: 流量卡停机请求
+
+- **WHEN** 调用 `StopCard(ctx, &CardOperationReq{CardNo: "xxx", Extend: "ext"})`
+- **THEN** `CardOperationReq` 结构体直接序列化
+- **AND** `Extend` 字段通过 `json:"extend,omitempty"` 标签在为空时自动省略
 ### Requirement: 流量卡 API 封装

 系统 SHALL 提供 7 个流量卡相关的 API 方法。
--- a/openspec/specs/gateway-request-logging/spec.md
+++ b/openspec/specs/gateway-request-logging/spec.md
@@ -0,0 +1,39 @@
+# Gateway Request Logging
+
+## Purpose
+
+Gateway 请求日志记录，在每次 Gateway API 调用时按结果级别记录请求日志，便于问题排查和运维监控。
+
+## ADDED Requirements
+
+### Requirement: Gateway 请求日志
+
+系统 SHALL 在每次 Gateway API 调用时记录请求日志，包含请求路径和请求体大小。
+
+#### Scenario: 正常请求记录 Debug 日志
+
+- **WHEN** 调用 `doRequest(ctx, "/flow-card/status", req)` 且请求成功
+- **THEN** 记录 Debug 级别日志
+- **AND** 日志包含字段：`path`（请求路径）、`duration`（耗时）
+
+#### Scenario: Gateway 业务错误记录 Warn 日志
+
+- **WHEN** Gateway 返回 `code != 200` 的业务错误
+- **THEN** 记录 Warn 级别日志
+- **AND** 日志包含字段：`path`、`duration`、`gateway_code`（Gateway 状态码）、`gateway_msg`（Gateway 错误信息）
+
+#### Scenario: 网络错误记录 Error 日志
+
+- **WHEN** HTTP 请求失败（连接失败、超时、DNS 解析失败等）
+- **THEN** 记录 Error 级别日志
+- **AND** 日志包含字段：`path`、`duration`、`error`（错误信息）
+
+### Requirement: Logger 依赖注入
+
+系统 SHALL 通过构造函数将 `*zap.Logger` 注入到 `Client` 中。
+
+#### Scenario: 创建带日志的客户端
+
+- **WHEN** 调用 `gateway.NewClient(baseURL, appID, appSecret, logger)`
+- **THEN** 客户端使用传入的 logger 记录日志
+- **AND** 不使用全局 `zap.L()`
--- a/openspec/specs/gateway-retry/spec.md
+++ b/openspec/specs/gateway-retry/spec.md
@@ -0,0 +1,57 @@
+# Gateway Retry
+
+## Purpose
+
+Gateway 请求自动重试机制，在网络级错误时自动重试，提高 Gateway API 调用的可靠性。
+
+## ADDED Requirements
+
+### Requirement: 网络级错误自动重试
+
+系统 SHALL 在 Gateway API 调用遇到网络级错误时自动重试。
+
+#### Scenario: 连接失败自动重试
+
+- **WHEN** Gateway HTTP 请求因连接失败（TCP 连接拒绝、DNS 解析失败）失败
+- **THEN** 系统自动重试，最多重试 2 次（共 3 次尝试）
+- **AND** 重试间隔使用指数退避（100ms → 300ms）
+
+#### Scenario: Client 超时自动重试
+
+- **WHEN** Gateway HTTP 请求因 Client 配置的超时时间到期而失败
+- **THEN** 系统自动重试
+- **AND** 用户传入的 Context 未被取消
+
+#### Scenario: Gateway 业务错误不重试
+
+- **WHEN** Gateway 返回 HTTP 200 但业务状态码 `code != 200`
+- **THEN** 系统不重试，直接返回业务错误
+
+#### Scenario: HTTP 状态码错误不重试
+
+- **WHEN** Gateway 返回 HTTP 4xx 或 5xx 状态码
+- **THEN** 系统不重试，直接返回错误
+
+#### Scenario: 用户 Context 取消不重试
+
+- **WHEN** 用户传入的 Context 被取消
+- **THEN** 系统立即停止，不重试
+
+#### Scenario: 加密或序列化错误不重试
+
+- **WHEN** 请求参数加密或序列化失败
+- **THEN** 系统不重试，直接返回错误
+
+### Requirement: 重试配置
+
+系统 SHALL 支持通过链式方法配置重试参数。
+
+#### Scenario: 自定义最大重试次数
+
+- **WHEN** 调用 `client.WithRetry(3)` 后发起 API 请求
+- **THEN** 网络级错误时最多重试 3 次（共 4 次尝试）
+
+#### Scenario: 禁用重试
+
+- **WHEN** 调用 `client.WithRetry(0)` 后发起 API 请求
+- **THEN** 不进行任何重试
--- a/openspec/specs/iot-card/spec.md
+++ b/openspec/specs/iot-card/spec.md
@@ -624,3 +624,93 @@ This capability supports:
 - **WHEN** 系统时间到达每月1号 00:00:00
 - **THEN** 系统重置所有 data_reset_cycle=monthly 的套餐 data_usage_mb=0

+
+---
+
+### Requirement: IotCard Handler 分层修复
+
+IotCard Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 IotCard Service 层发起。
+
+#### Scenario: IotCardHandler 不持有 gatewayClient
+
+- **WHEN** 创建 `IotCardHandler` 实例
+- **THEN** `NewIotCardHandler` 构造函数不接收 `gateway.Client` 参数
+- **AND** Handler 结构体不包含 `gatewayClient` 字段
+
+#### Scenario: 查询卡实时状态通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayStatus` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayStatus(ctx, iccid)`
+- **AND** Service 内部完成权限检查 + Gateway API 调用
+
+#### Scenario: 查询流量使用通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayFlow` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayFlow(ctx, iccid)`
+
+#### Scenario: 查询实名状态通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayRealname` 方法被调用
+- **THEN** Handler 调用 `service.QueryGatewayRealname(ctx, iccid)`
+
+#### Scenario: 获取实名链接通过 Service 调用
+
+- **WHEN** Handler 的 `GetRealnameLink` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewayRealnameLink(ctx, iccid)`
+
+#### Scenario: 停卡通过 Service 调用
+
+- **WHEN** Handler 的 `StopCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewayStopCard(ctx, iccid)`
+
+#### Scenario: 复机通过 Service 调用
+
+- **WHEN** Handler 的 `StartCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewayStartCard(ctx, iccid)`
+
+### Requirement: IotCard Service Gateway 代理方法
+
+IotCard Service SHALL 提供 Gateway API 的代理方法，封装权限检查和 Gateway 调用。
+
+#### Scenario: QueryGatewayStatus 方法
+
+- **WHEN** 调用 `service.QueryGatewayStatus(ctx, iccid)`
+- **THEN** 先通过 `GetByICCID` 验证卡存在且用户有权限
+- **AND** 然后调用 `gatewayClient.QueryCardStatus`
+- **AND** 返回 `*gateway.CardStatusResp`
+
+#### Scenario: QueryGatewayFlow 方法
+
+- **WHEN** 调用 `service.QueryGatewayFlow(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.QueryFlow`
+- **AND** 返回 `*gateway.FlowUsageResp`
+
+#### Scenario: QueryGatewayRealname 方法
+
+- **WHEN** 调用 `service.QueryGatewayRealname(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.QueryRealnameStatus`
+- **AND** 返回 `*gateway.RealnameStatusResp`
+
+#### Scenario: GetGatewayRealnameLink 方法
+
+- **WHEN** 调用 `service.GetGatewayRealnameLink(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.GetRealnameLink`
+- **AND** 返回 `*gateway.RealnameLinkResp`
+
+#### Scenario: GatewayStopCard 方法
+
+- **WHEN** 调用 `service.GatewayStopCard(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.StopCard`
+- **AND** 返回 error
+
+#### Scenario: GatewayStartCard 方法
+
+- **WHEN** 调用 `service.GatewayStartCard(ctx, iccid)`
+- **THEN** 先验证权限，再调用 `gatewayClient.StartCard`
+- **AND** 返回 error
+
+#### Scenario: 卡不存在或无权限
+
+- **WHEN** 调用任意 Gateway 代理方法且 ICCID 对应的卡不存在或用户无权限
+- **THEN** 返回 `CodeNotFound` 错误
+- **AND** 错误信息为 "卡不存在或无权限访问"
--- a/openspec/specs/iot-device/spec.md
+++ b/openspec/specs/iot-device/spec.md
@@ -389,3 +389,127 @@ func (DeviceSimBinding) TableName() string {
 - **WHEN** 开发者需要查找或修改 DeviceSimBinding 模型
 - **THEN** 模型定义位于 `internal/model/device_sim_binding.go` 文件中,而非混杂在 `package.go` 中

+
+---
+
+### Requirement: Device Handler 分层修复
+
+Device Handler SHALL 不再直接持有 `gateway.Client` 引用。所有 Gateway API 调用 SHALL 通过 Device Service 层发起。
+
+#### Scenario: DeviceHandler 不持有 gatewayClient
+
+- **WHEN** 创建 `DeviceHandler` 实例
+- **THEN** `NewDeviceHandler` 构造函数不接收 `gateway.Client` 参数
+- **AND** Handler 结构体不包含 `gatewayClient` 字段
+
+#### Scenario: 查询设备网关信息通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewayInfo` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewayInfo(ctx, identifier)`
+
+#### Scenario: 查询设备卡槽信息通过 Service 调用
+
+- **WHEN** Handler 的 `GetGatewaySlots` 方法被调用
+- **THEN** Handler 调用 `service.GetGatewaySlots(ctx, identifier)`
+
+#### Scenario: 设置设备限速通过 Service 调用
+
+- **WHEN** Handler 的 `SetSpeedLimit` 方法被调用
+- **THEN** Handler 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)`
+
+#### Scenario: 设置设备 WiFi 通过 Service 调用
+
+- **WHEN** Handler 的 `SetWiFi` 方法被调用
+- **THEN** Handler 调用 `service.SetGatewayWiFi(ctx, identifier, req)`
+
+#### Scenario: 切换设备卡通过 Service 调用
+
+- **WHEN** Handler 的 `SwitchCard` 方法被调用
+- **THEN** Handler 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)`
+
+#### Scenario: 重启设备通过 Service 调用
+
+- **WHEN** Handler 的 `RebootDevice` 方法被调用
+- **THEN** Handler 调用 `service.GatewayRebootDevice(ctx, identifier)`
+
+#### Scenario: 恢复出厂设置通过 Service 调用
+
+- **WHEN** Handler 的 `ResetDevice` 方法被调用
+- **THEN** Handler 调用 `service.GatewayResetDevice(ctx, identifier)`
+
+### Requirement: Device Service Gateway 代理方法
+
+Device Service SHALL 提供 Gateway API 的代理方法，封装设备标识符解析、IMEI 检查和 Gateway 调用。
+
+#### Scenario: GetGatewayInfo 方法
+
+- **WHEN** 调用 `service.GetGatewayInfo(ctx, identifier)`
+- **THEN** 先通过 `GetDeviceByIdentifier` 查找设备并验证权限
+- **AND** 检查设备 IMEI 不为空
+- **AND** 调用 `gatewayClient.GetDeviceInfo` 传入设备 IMEI
+- **AND** 返回 `*gateway.DeviceInfoResp`
+
+#### Scenario: GetGatewaySlots 方法
+
+- **WHEN** 调用 `service.GetGatewaySlots(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI 不为空
+- **AND** 调用 `gatewayClient.GetSlotInfo`
+- **AND** 返回 `*gateway.SlotInfoResp`
+
+#### Scenario: SetGatewaySpeedLimit 方法
+
+- **WHEN** 调用 `service.SetGatewaySpeedLimit(ctx, identifier, speedLimit)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SetSpeedLimit` 传入设备 IMEI 和限速值
+
+#### Scenario: SetGatewayWiFi 方法
+
+- **WHEN** 调用 `service.SetGatewayWiFi(ctx, identifier, cardNo, ssid, password string, enabled bool)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SetWiFi` 传入设备 IMEI、cardNo（ICCID）、ssid、password、enabled
+
+#### Scenario: GatewaySwitchCard 方法
+
+- **WHEN** 调用 `service.GatewaySwitchCard(ctx, identifier, targetICCID)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.SwitchCard` 传入设备 IMEI 作为 cardNo 和目标 ICCID
+
+#### Scenario: GatewayRebootDevice 方法
+
+- **WHEN** 调用 `service.GatewayRebootDevice(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.RebootDevice` 传入设备 IMEI
+
+#### Scenario: GatewayResetDevice 方法
+
+- **WHEN** 调用 `service.GatewayResetDevice(ctx, identifier)`
+- **THEN** 先查找设备、验证 IMEI
+- **AND** 调用 `gatewayClient.ResetDevice` 传入设备 IMEI
+
+#### Scenario: 设备 IMEI 为空
+
+- **WHEN** 调用任意 Gateway 代理方法且设备的 IMEI 字段为空
+- **THEN** 返回 `CodeInvalidParam` 错误
+- **AND** 错误信息说明该设备未配置 IMEI
+
+#### Scenario: 设备不存在或无权限
+
+- **WHEN** 调用任意 Gateway 代理方法且标识符无法匹配到设备
+- **THEN** 返回对应的错误（由 `GetDeviceByIdentifier` 返回）
+
+### Requirement: Device Service 接收 Gateway Client
+
+Device Service SHALL 在构造函数中接收 `*gateway.Client` 依赖。
+
+#### Scenario: Device Service 初始化
+
+- **WHEN** 创建 Device Service 实例
+- **THEN** 构造函数接收 `gatewayClient *gateway.Client` 参数
+- **AND** 存储为 Service 的内部字段
+- **AND** `gatewayClient` 可以为 nil（Gateway 配置缺失时）
+
+#### Scenario: Gateway Client 为 nil 时调用 Gateway 方法
+
+- **WHEN** `gatewayClient` 为 nil 且调用任意 Gateway 代理方法
+- **THEN** 返回 `CodeGatewayError` 错误
+- **AND** 错误信息为 "Gateway 客户端未配置"
--- a/pkg/openapi/handlers.go
+++ b/pkg/openapi/handlers.go
@@ -28,9 +28,9 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		EnterpriseDeviceH5:          h5.NewEnterpriseDeviceHandler(nil),
 		Authorization:               admin.NewAuthorizationHandler(nil),
 		MyCommission:                admin.NewMyCommissionHandler(nil),
-		IotCard:                     admin.NewIotCardHandler(nil, nil),
+		IotCard:                     admin.NewIotCardHandler(nil),
 		IotCardImport:               admin.NewIotCardImportHandler(nil),
-		Device:                      admin.NewDeviceHandler(nil, nil),
+		Device:                      admin.NewDeviceHandler(nil),
 		DeviceImport:                admin.NewDeviceImportHandler(nil),
 		AssetAllocationRecord:       admin.NewAssetAllocationRecordHandler(nil),
 		Storage:                     admin.NewStorageHandler(nil),