修复设备WiFi上游请求参数

2026-04-27 15:19:23 +08:00
parent 66cec7515a
commit c3ae7fcfbc
10 changed files with 50 additions and 52 deletions
--- a/docs/admin-openapi.yaml
+++ b/docs/admin-openapi.yaml
@@ -6318,9 +6318,6 @@ components:
            type: object
        DtoSetWiFiRequest:
            properties:
-                card_no:
-                    description: 流量卡号（ICCID）
-                    type: string
                enabled:
                    description: 启用状态
                    type: boolean
@@ -6333,7 +6330,6 @@ components:
                    minLength: 1
                    type: string
            required:
-                - card_no
                - ssid
            type: object
        DtoShopCascadeItem:
--- a/docs/gateway-api-reference.md
+++ b/docs/gateway-api-reference.md
@@ -470,27 +470,30 @@ fmt.Println("限速设置成功")

 ### 4. 设置设备 WiFi

-设置设备的 WiFi 名称、密码和启用状态。
+设置设备的 WiFi 信息。

 **方法**: `SetWiFi`

 **请求参数**:
 ```go
 type WiFiReq struct {
-    DeviceID string `json:"deviceId" validate:"required"`
-    SSID     string `json:"ssid" validate:"required,min=1,max=32"`
-    Password string `json:"password" validate:"required,min=8,max=63"`
-    Enabled  int    `json:"enabled" validate:"required,oneof=0 1"`
-    Extend   string `json:"extend,omitempty"`
+    CardNo string `json:"cardNo" validate:"required"`
+    Params WiFiParams `json:"params" validate:"required"`
+    Extend string `json:"extend,omitempty"`
+}
+
+type WiFiParams struct {
+    SSIDName     string `json:"ssidName" validate:"required,min=1,max=32"`
+    SSIDPassword string `json:"ssidPassword,omitempty"`
 }
 ```

 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| DeviceID | string | ✅ | 设备 ID/IMEI |
-| SSID | string | ✅ | WiFi 名称（1-32字符） |
-| Password | string | ✅ | WiFi 密码（8-63字符） |
-| Enabled | int | ✅ | 启用状态（0:禁用, 1:启用） |
+| CardNo | string | ✅ | 设备 IMEI |
+| Params | object | ✅ | WiFi 配置参数 |
+| SSIDName | string | ✅ | WiFi 名称（1-32字符） |
+| SSIDPassword | string | ❌ | WiFi 密码 |
 | Extend | string | ❌ | 扩展字段 |

 **响应参数**: 无（成功返回 nil，失败返回 error）
@@ -498,10 +501,11 @@ type WiFiReq struct {
 **使用示例**:
 ```go
 err := client.SetWiFi(ctx, &gateway.WiFiReq{
-    DeviceID: "123456789012345",
-    SSID:     "MyWiFi",
-    Password: "password123",
-    Enabled:  1,
+    CardNo: "123456789012345",
+    Params: gateway.WiFiParams{
+        SSIDName:     "MyWiFi",
+        SSIDPassword: "password123",
+    },
 })
 if err != nil {
    return err
--- a/docs/gateway-client-usage.md
+++ b/docs/gateway-client-usage.md
@@ -237,17 +237,13 @@ func (s *Service) SetDeviceSpeed(ctx context.Context, imei string, uploadKBps, d
 #### 设置设备 WiFi

 ```go
-func (s *Service) ConfigureWiFi(ctx context.Context, imei, ssid, password string, enabled bool) error {
-    enabledInt := 0
-    if enabled {
-        enabledInt = 1
-    }
-
+func (s *Service) ConfigureWiFi(ctx context.Context, imei, ssid, password string) error {
    err := s.gatewayClient.SetWiFi(ctx, &gateway.WiFiReq{
-        DeviceID: imei,
-        SSID:     ssid,
-        Password: password,
-        Enabled:  enabledInt,
+        CardNo: imei,
+        Params: gateway.WiFiParams{
+            SSIDName:     ssid,
+            SSIDPassword: password,
+        },
    })
    if err != nil {
        return errors.Wrap(errors.CodeGatewayError, err, "设置WiFi失败")
--- a/internal/gateway/device.go
+++ b/internal/gateway/device.go
@@ -36,7 +36,7 @@ func (c *Client) SetSpeedLimit(ctx context.Context, req *SpeedLimitReq) error {
 }

 // SetWiFi 设置设备 WiFi
-// 配置 WiFi 名称、密码及启用状态，cardNo（ICCID）为必填参数
+// Gateway 实际要求 cardNo 传设备 IMEI，并搭配内层 params 下发 WiFi 名称和密码
 // POST /device/wifi-config
 func (c *Client) SetWiFi(ctx context.Context, req *WiFiReq) error {
 	_, err := c.doRequest(ctx, "/device/wifi-config", req)
--- a/internal/gateway/models.go
+++ b/internal/gateway/models.go
@@ -162,14 +162,18 @@ type SpeedLimitReq struct {
 	Extend     string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
 }

+// WiFiParams 是设置设备 WiFi 的内层参数
+type WiFiParams struct {
+	SSIDName     string `json:"ssidName" validate:"required,min=1,max=32" required:"true" minLength:"1" maxLength:"32" description:"WiFi 名称"`
+	SSIDPassword string `json:"ssidPassword,omitempty" description:"WiFi 密码"`
+}
+
 // WiFiReq 是设置设备 WiFi 的请求
+// Gateway 实际要求的结构为 {"params":{"cardNo":"设备IMEI","params":{"ssidName":"...","ssidPassword":"..."}}}
 type WiFiReq struct {
-	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,omitempty" description:"WiFi 密码"`
-	Enabled  bool   `json:"enabled" description:"启用状态"`
-	Extend   string `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
+	CardNo string     `json:"cardNo" validate:"required" required:"true" description:"设备 IMEI"`
+	Params WiFiParams `json:"params" required:"true" description:"WiFi 配置参数"`
+	Extend string     `json:"extend,omitempty" description:"扩展字段（广电国网特殊参数）"`
 }

 // SwitchCardReq 是设备切换卡的请求
--- a/internal/handler/app/client_device.go
+++ b/internal/handler/app/client_device.go
@@ -254,11 +254,11 @@ func (h *ClientDeviceHandler) SetWiFi(c *fiber.Ctx) error {
 	// 调用 Gateway 配置 WiFi
 	// CardNo 字段虽名为"卡号"，但 Gateway 实际要求传入设备 IMEI
 	if err := h.gatewayClient.SetWiFi(c.UserContext(), &gateway.WiFiReq{
-		CardNo:   info.IMEI,
-		DeviceID: info.IMEI,
-		SSID:     req.SSID,
-		Password: req.Password,
-		Enabled:  req.Enabled,
+		CardNo: info.IMEI,
+		Params: gateway.WiFiParams{
+			SSIDName:     req.SSID,
+			SSIDPassword: req.Password,
+		},
 	}); err != nil {
 		h.logger.Error("Gateway配置WiFi失败",
 			zap.String("imei", info.IMEI),
--- a/internal/model/dto/device_dto.go
+++ b/internal/model/dto/device_dto.go
@@ -169,7 +169,6 @@ type SetSpeedLimitRequest struct {
 // SetWiFiRequest 设置设备 WiFi 请求
 type SetWiFiRequest struct {
 	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:"启用状态"`
--- a/internal/service/asset_audit/operation_content.go
+++ b/internal/service/asset_audit/operation_content.go
@@ -290,7 +290,7 @@ func getOperationFieldDesc(operationType string) map[string]string {
 		}
 	case "device_set_wifi":
 		return map[string]string{
-			"card_no":  "卡槽/卡序号",
+			"imei":     "设备 IMEI",
 			"ssid":     "WiFi 名称",
 			"password": "WiFi 密码（脱敏）",
 			"enabled":  "WiFi 开关状态",
--- a/internal/service/device/gateway_service.go
+++ b/internal/service/device/gateway_service.go
@@ -116,7 +116,6 @@ func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dt
 			nil,
 			map[string]any{
 				"identifier": identifier,
-				"card_no":    req.CardNo,
 				"ssid":       req.SSID,
 				"enabled":    req.Enabled,
 				"password":   req.Password,
@@ -129,11 +128,11 @@ func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dt
 		return err
 	}
 	if err = s.gatewayClient.SetWiFi(ctx, &gateway.WiFiReq{
-		CardNo:   req.CardNo,
-		DeviceID: imei,
-		SSID:     req.SSID,
-		Password: req.Password,
-		Enabled:  req.Enabled,
+		CardNo: imei,
+		Params: gateway.WiFiParams{
+			SSIDName:     req.SSID,
+			SSIDPassword: req.Password,
+		},
 	}); err != nil {
 		s.logDeviceOperation(
 			ctx,
@@ -143,7 +142,7 @@ func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dt
 			device,
 			map[string]any{"device": deviceSnapshot(device)},
 			map[string]any{
-				"card_no":  req.CardNo,
+				"imei":     imei,
 				"ssid":     req.SSID,
 				"enabled":  req.Enabled,
 				"password": req.Password,
@@ -164,7 +163,7 @@ func (s *Service) GatewaySetWiFi(ctx context.Context, identifier string, req *dt
 		device,
 		map[string]any{"device": deviceSnapshot(device)},
 		map[string]any{
-			"card_no":  req.CardNo,
+			"imei":     imei,
 			"ssid":     req.SSID,
 			"enabled":  req.Enabled,
 			"password": req.Password,
--- a/openspec/specs/gateway-client/spec.md
+++ b/openspec/specs/gateway-client/spec.md
@@ -176,9 +176,9 @@ Gateway API 统一客户端，提供 14 个接口的类型安全封装。

 #### Scenario: 设置设备 WiFi

- **WHEN** 调用 `client.SetWiFi(ctx, &WiFiReq{DeviceID: "868123456789012", SSID: "MyWiFi", Password: "12345678", Enabled: true})`
+- **WHEN** 调用 `client.SetWiFi(ctx, &WiFiReq{CardNo: "868123456789012", Params: WiFiParams{SSIDName: "MyWiFi", SSIDPassword: "12345678"}})`
 - **THEN** 设备 WiFi 配置更新
- **AND** WiFi 名称、密码和启用状态正确设置
+- **AND** WiFi 名称和密码正确设置

 #### Scenario: 设备切换卡