设备的部分改造

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 方法。

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()`

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** 不进行任何重试

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** 错误信息为 "卡不存在或无权限访问"

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 客户端未配置"