设备的部分改造

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
 }

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
 }

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 批量查询（预留接口，暂未实现）

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 是设备操作（重启、恢复出厂）的请求