设备的部分改造

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