设备的部分改造

2026-03-10 10:34:08 +08:00
parent 86f8d0b644
commit b5147d1acb
34 changed files with 1680 additions and 485 deletions
--- 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 {