junhong_cmp_fiber/openspec/changes/archive/2026-03-09-refactor-gateway-client/tasks.md

1. Gateway Client 核心重构

• 1.1 修改 Client 结构体：添加 logger *zap.Logger 和 maxRetries int 字段
• 1.2 修改 NewClient 签名：增加 logger *zap.Logger 参数，默认 maxRetries = 2
• 1.3 添加 WithRetry(maxRetries int) *Client 链式方法
• 1.4 修改 doRequest：请求参数改为直接接收结构体（interface{}），内部自动包装为 {"params": <JSON>} 格式
• 1.5 在 doRequest 中添加请求/响应日志（Debug 级别正常、Warn 级别业务错误、Error 级别网络错误）
• 1.6 在 doRequest 中添加网络级错误重试逻辑（指数退避 100ms→300ms，仅对连接失败/Client 超时/DNS 失败重试）
• 1.7 添加 doRequestWithResponse[T any] 泛型方法，自动完成 doRequest + unmarshal
• 1.8 更新 cmd/api/main.go 和 cmd/worker/main.go 中的 initGateway 函数，传入 logger
• 1.9 验证：go build ./... 编译通过，lsp_diagnostics 无错误

2. 流量卡方法重构（消除 map 构建和重复 unmarshal）

• 2.1 重构 QueryCardStatus：使用 doRequestWithResponse[CardStatusResp]，去掉手动 map 构建
• 2.2 重构 QueryFlow：使用 doRequestWithResponse[FlowUsageResp]
• 2.3 重构 QueryRealnameStatus：使用 doRequestWithResponse[RealnameStatusResp]
• 2.4 重构 StopCard：直接传 req 给 doRequest，去掉手动 map
• 2.5 重构 StartCard：同上
• 2.6 重构 GetRealnameLink：使用 doRequestWithResponse[RealnameLinkResp]
• 2.7 验证：go build ./... 编译通过，lsp_diagnostics 无错误

3. 设备方法重构（消除 map 构建和重复 unmarshal）

• 3.1 重构 GetDeviceInfo：使用 doRequestWithResponse[DeviceInfoResp]，去掉手动 map
• 3.2 重构 GetSlotInfo：使用 doRequestWithResponse[SlotInfoResp]
• 3.3 重构 SetSpeedLimit：直接传 req 给 doRequest
• 3.4 重构 SetWiFi：同上
• 3.5 重构 SwitchCard：同上
• 3.6 重构 ResetDevice：同上
• 3.7 重构 RebootDevice：同上
• 3.8 验证：go build ./... 编译通过，lsp_diagnostics 无错误

4. Device Service 注入 Gateway Client

• 4.1 修改 internal/service/device/service.go：Service 结构体添加 gatewayClient *gateway.Client 字段
• 4.2 修改 New 构造函数：增加 gatewayClient *gateway.Client 参数
• 4.3 修改 internal/bootstrap/services.go：Device Service 初始化时传入 deps.GatewayClient
• 4.4 验证：go build ./... 编译通过

5. Device Service Gateway 代理方法

• 5.1 实现 GatewayGetDeviceInfo(ctx, identifier) → (*gateway.DeviceInfoResp, error)：identifier→设备→检查IMEI→调用 Gateway
• 5.2 实现 GatewayGetSlotInfo(ctx, identifier) → (*gateway.SlotInfoResp, error)
• 5.3 实现 GatewaySetSpeedLimit(ctx, identifier string, req *dto.SetSpeedLimitRequest) → error
• 5.4 实现 GatewaySetWiFi(ctx, identifier string, req *dto.SetWiFiRequest) → error
• 5.5 实现 GatewaySwitchCard(ctx, identifier string, req *dto.SwitchCardRequest) → error
• 5.6 实现 GatewayRebootDevice(ctx, identifier string) → error
• 5.7 实现 GatewayResetDevice(ctx, identifier string) → error
• 5.8 验证：go build ./... 编译通过，lsp_diagnostics 无错误

6. IotCard Service Gateway 代理方法

• 6.1 实现 GatewayQueryCardStatus(ctx, iccid) → (*gateway.CardStatusResp, error)：权限检查→Gateway 调用
• 6.2 实现 GatewayQueryFlow(ctx, iccid) → (*gateway.FlowUsageResp, error)
• 6.3 实现 GatewayQueryRealnameStatus(ctx, iccid) → (*gateway.RealnameStatusResp, error)
• 6.4 实现 GatewayGetRealnameLink(ctx, iccid) → (*gateway.RealnameLinkResp, error)
• 6.5 实现 GatewayStopCard(ctx, iccid) → error
• 6.6 实现 GatewayStartCard(ctx, iccid) → error
• 6.7 验证：go build ./... 编译通过，lsp_diagnostics 无错误

7. Handler 分层修复 — Device Handler

• 7.1 修改 DeviceHandler 结构体：移除 gatewayClient 字段
• 7.2 修改 NewDeviceHandler：移除 gatewayClient 参数
• 7.3 重构 GetGatewayInfo：改为调用 h.service.GatewayGetDeviceInfo(ctx, identifier)
• 7.4 重构 GetGatewaySlots：改为调用 h.service.GatewayGetSlotInfo(ctx, identifier)
• 7.5 重构 SetSpeedLimit：改为调用 h.service.GatewaySetSpeedLimit(ctx, identifier, &req)
• 7.6 重构 SetWiFi：改为调用 h.service.GatewaySetWiFi(ctx, identifier, &req)
• 7.7 重构 SwitchCard：改为调用 h.service.GatewaySwitchCard(ctx, identifier, &req)
• 7.8 重构 RebootDevice：改为调用 h.service.GatewayRebootDevice(ctx, identifier)
• 7.9 重构 ResetDevice：改为调用 h.service.GatewayResetDevice(ctx, identifier)
• 7.10 移除 import "github.com/break/junhong_cmp_fiber/internal/gateway" 导入（如果不再需要）
• 7.11 验证：go build ./... 编译通过，lsp_diagnostics 无错误

8. Handler 分层修复 — IotCard Handler

• 8.1 修改 IotCardHandler 结构体：移除 gatewayClient 字段
• 8.2 修改 NewIotCardHandler：移除 gatewayClient 参数
• 8.3 重构 GetGatewayStatus：改为调用 h.service.GatewayQueryCardStatus(ctx, iccid)
• 8.4 重构 GetGatewayFlow：改为调用 h.service.GatewayQueryFlow(ctx, iccid)
• 8.5 重构 GetGatewayRealname：改为调用 h.service.GatewayQueryRealnameStatus(ctx, iccid)
• 8.6 重构 GetRealnameLink：改为调用 h.service.GatewayGetRealnameLink(ctx, iccid)
• 8.7 重构 StopCard：改为调用 h.service.GatewayStopCard(ctx, iccid)
• 8.8 重构 StartCard：改为调用 h.service.GatewayStartCard(ctx, iccid)
• 8.9 移除 import "github.com/break/junhong_cmp_fiber/internal/gateway" 导入（如果不再需要）
• 8.10 验证：go build ./... 编译通过，lsp_diagnostics 无错误

9. Bootstrap 层适配

• 9.1 修改 internal/bootstrap/handlers.go：NewIotCardHandler 不再传入 deps.GatewayClient
• 9.2 修改 internal/bootstrap/handlers.go：NewDeviceHandler 不再传入 deps.GatewayClient
• 9.3 验证：go build ./... 编译通过，确认所有 Handler/Service/Bootstrap 链路正确

10. 最终验证

• 10.1 go build ./... 全量编译通过
• 10.2 go vet ./... 无问题
• 10.3 所有修改文件 lsp_diagnostics 无错误
• 10.4 确认无遗留的 Handler 层 Gateway 直接调用（grep 验证）
• 10.5 确认 Worker 端（polling_handler.go、queue/handler.go）不受影响