chore: apply task changes

2026-01-30 17:05:44 +08:00
parent 4856a88d41
commit 3f63fffbb1
22 changed files with 4696 additions and 8 deletions
--- a/docs/gateway-client-usage.md
+++ b/docs/gateway-client-usage.md
@@ -0,0 +1,551 @@
+# Gateway 客户端使用指南
+
+## 概述
+
+Gateway 客户端是对第三方 Gateway API 的 Go 封装，提供流量卡和设备管理的统一接口。客户端内置了 AES-128-ECB 加密、MD5 签名验证、HTTP 连接池管理等功能。
+
+**核心特性**：
+- ✅ 自动加密/签名处理
+- ✅ 统一错误处理
+- ✅ HTTP Keep-Alive 连接池
+- ✅ 可配置超时时间
+- ✅ 完整的测试覆盖（88.8%）
+
+## 配置说明
+
+### 环境变量配置
+
+Gateway 客户端通过环境变量配置，支持以下参数：
+
+| 环境变量 | 说明 | 默认值 | 必填 |
+|---------|------|--------|------|
+| `JUNHONG_GATEWAY_BASE_URL` | Gateway API 基础 URL | - | ✅ |
+| `JUNHONG_GATEWAY_APP_ID` | 应用 ID | - | ✅ |
+| `JUNHONG_GATEWAY_APP_SECRET` | 应用密钥 | - | ✅ |
+| `JUNHONG_GATEWAY_TIMEOUT` | 请求超时时间（秒） | 30 | ❌ |
+
+### 配置示例
+
+**开发环境** (`.env.local`):
+```bash
+export JUNHONG_GATEWAY_BASE_URL=https://lplan.whjhft.com/openapi
+export JUNHONG_GATEWAY_APP_ID=60bgt1X8i7AvXqkd
+export JUNHONG_GATEWAY_APP_SECRET=BZeQttaZQt0i73moF
+export JUNHONG_GATEWAY_TIMEOUT=30
+```
+
+**生产环境** (`docker-compose.yml`):
+```yaml
+services:
+  api:
+    environment:
+      - JUNHONG_GATEWAY_BASE_URL=https://gateway.prod.example.com
+      - JUNHONG_GATEWAY_APP_ID=${GATEWAY_APP_ID}
+      - JUNHONG_GATEWAY_APP_SECRET=${GATEWAY_APP_SECRET}
+      - JUNHONG_GATEWAY_TIMEOUT=60
+```
+
+## 使用示例
+
+### 1. 基础用法
+
+#### 获取客户端实例
+
+Gateway 客户端在 Bootstrap 阶段自动初始化，通过依赖注入获取：
+
+```go
+package iot_card
+
+import (
+    "context"
+    "github.com/break/junhong_cmp_fiber/internal/gateway"
+    "github.com/break/junhong_cmp_fiber/pkg/errors"
+    "go.uber.org/zap"
+)
+
+type Service struct {
+    gatewayClient *gateway.Client
+    logger        *zap.Logger
+}
+
+func New(gatewayClient *gateway.Client, logger *zap.Logger) *Service {
+    return &Service{
+        gatewayClient: gatewayClient,
+        logger:        logger,
+    }
+}
+```
+
+#### 查询流量卡状态
+
+```go
+func (s *Service) SyncCardStatus(ctx context.Context, iccid string) error {
+    if s.gatewayClient == nil {
+        return errors.New(errors.CodeGatewayError, "Gateway 客户端未配置")
+    }
+
+    resp, err := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        s.logger.Error("查询卡状态失败", zap.String("iccid", iccid), zap.Error(err))
+        return errors.Wrap(errors.CodeGatewayError, err, "查询卡状态失败")
+    }
+
+    s.logger.Info("查询卡状态成功",
+        zap.String("iccid", resp.ICCID),
+        zap.String("status", resp.CardStatus),
+    )
+
+    return nil
+}
+```
+
+### 2. 流量卡管理
+
+#### 查询流量使用情况
+
+```go
+func (s *Service) GetFlowUsage(ctx context.Context, iccid string) (*gateway.FlowUsageResp, error) {
+    resp, err := s.gatewayClient.QueryFlow(ctx, &gateway.FlowQueryReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        return nil, errors.Wrap(errors.CodeGatewayError, err, "查询流量失败")
+    }
+
+    return resp, nil
+}
+```
+
+#### 流量卡停机
+
+```go
+func (s *Service) StopCard(ctx context.Context, iccid string) error {
+    err := s.gatewayClient.StopCard(ctx, &gateway.CardOperationReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "停机失败")
+    }
+
+    s.logger.Info("停机成功", zap.String("iccid", iccid))
+    return nil
+}
+```
+
+#### 流量卡复机
+
+```go
+func (s *Service) StartCard(ctx context.Context, iccid string) error {
+    err := s.gatewayClient.StartCard(ctx, &gateway.CardOperationReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "复机失败")
+    }
+
+    s.logger.Info("复机成功", zap.String("iccid", iccid))
+    return nil
+}
+```
+
+#### 查询实名认证状态
+
+```go
+func (s *Service) CheckRealnameStatus(ctx context.Context, iccid string) (string, error) {
+    resp, err := s.gatewayClient.QueryRealnameStatus(ctx, &gateway.CardStatusReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        return "", errors.Wrap(errors.CodeGatewayError, err, "查询实名状态失败")
+    }
+
+    return resp.Status, nil
+}
+```
+
+#### 获取实名认证链接
+
+```go
+func (s *Service) GetRealnameLink(ctx context.Context, iccid string) (string, error) {
+    resp, err := s.gatewayClient.GetRealnameLink(ctx, &gateway.CardStatusReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        return "", errors.Wrap(errors.CodeGatewayError, err, "获取实名链接失败")
+    }
+
+    return resp.Link, nil
+}
+```
+
+### 3. 设备管理
+
+#### 查询设备信息
+
+```go
+func (s *Service) GetDeviceInfo(ctx context.Context, imei string) (*gateway.DeviceInfoResp, error) {
+    resp, err := s.gatewayClient.GetDeviceInfo(ctx, &gateway.DeviceInfoReq{
+        DeviceID: imei,
+    })
+    if err != nil {
+        return nil, errors.Wrap(errors.CodeGatewayError, err, "查询设备信息失败")
+    }
+
+    return resp, nil
+}
+```
+
+#### 查询设备卡槽信息
+
+```go
+func (s *Service) GetDeviceSlots(ctx context.Context, imei string) ([]gateway.SlotInfo, error) {
+    resp, err := s.gatewayClient.GetSlotInfo(ctx, &gateway.DeviceInfoReq{
+        DeviceID: imei,
+    })
+    if err != nil {
+        return nil, errors.Wrap(errors.CodeGatewayError, err, "查询卡槽信息失败")
+    }
+
+    return resp.Slots, nil
+}
+```
+
+#### 设置设备限速
+
+```go
+func (s *Service) SetDeviceSpeed(ctx context.Context, imei string, uploadKBps, downloadKBps int) error {
+    err := s.gatewayClient.SetSpeedLimit(ctx, &gateway.SpeedLimitReq{
+        DeviceID:      imei,
+        UploadSpeed:   uploadKBps,
+        DownloadSpeed: downloadKBps,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "设置限速失败")
+    }
+
+    s.logger.Info("设置限速成功",
+        zap.String("imei", imei),
+        zap.Int("upload", uploadKBps),
+        zap.Int("download", downloadKBps),
+    )
+    return nil
+}
+```
+
+#### 设置设备 WiFi
+
+```go
+func (s *Service) ConfigureWiFi(ctx context.Context, imei, ssid, password string, enabled bool) error {
+    enabledInt := 0
+    if enabled {
+        enabledInt = 1
+    }
+
+    err := s.gatewayClient.SetWiFi(ctx, &gateway.WiFiReq{
+        DeviceID: imei,
+        SSID:     ssid,
+        Password: password,
+        Enabled:  enabledInt,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "设置WiFi失败")
+    }
+
+    return nil
+}
+```
+
+#### 设备切换卡
+
+```go
+func (s *Service) SwitchDeviceCard(ctx context.Context, imei, targetICCID string) error {
+    err := s.gatewayClient.SwitchCard(ctx, &gateway.SwitchCardReq{
+        DeviceID:    imei,
+        TargetICCID: targetICCID,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "切换卡失败")
+    }
+
+    s.logger.Info("切换卡成功",
+        zap.String("imei", imei),
+        zap.String("targetICCID", targetICCID),
+    )
+    return nil
+}
+```
+
+#### 设备重启
+
+```go
+func (s *Service) RebootDevice(ctx context.Context, imei string) error {
+    err := s.gatewayClient.RebootDevice(ctx, &gateway.DeviceOperationReq{
+        DeviceID: imei,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "重启设备失败")
+    }
+
+    s.logger.Info("重启设备成功", zap.String("imei", imei))
+    return nil
+}
+```
+
+#### 设备恢复出厂设置
+
+```go
+func (s *Service) ResetDevice(ctx context.Context, imei string) error {
+    err := s.gatewayClient.ResetDevice(ctx, &gateway.DeviceOperationReq{
+        DeviceID: imei,
+    })
+    if err != nil {
+        return errors.Wrap(errors.CodeGatewayError, err, "恢复出厂设置失败")
+    }
+
+    s.logger.Info("恢复出厂设置成功", zap.String("imei", imei))
+    return nil
+}
+```
+
+## 错误处理
+
+### 统一错误码
+
+Gateway 客户端使用统一的错误码系统（`pkg/errors/codes.go`）：
+
+| 错误码 | 说明 |
+|-------|------|
+| `1110` | Gateway 连接失败 |
+| `1111` | Gateway 请求超时 |
+| `1112` | Gateway 业务错误 |
+| `1113` | Gateway 响应解析失败 |
+| `1114` | Gateway 签名验证失败 |
+
+### 错误处理最佳实践
+
+```go
+func (s *Service) ProcessCard(ctx context.Context, iccid string) error {
+    resp, err := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        s.logger.Error("查询卡状态失败",
+            zap.String("iccid", iccid),
+            zap.Error(err),
+        )
+        
+        return errors.Wrap(errors.CodeGatewayError, err, "查询卡状态失败")
+    }
+
+    return nil
+}
+```
+
+### 错误分类处理
+
+```go
+func (s *Service) HandleGatewayError(err error) {
+    switch {
+    case strings.Contains(err.Error(), "超时"):
+        s.logger.Warn("Gateway 请求超时，请稍后重试")
+    case strings.Contains(err.Error(), "业务错误"):
+        s.logger.Error("Gateway 业务处理失败", zap.Error(err))
+    case strings.Contains(err.Error(), "连接失败"):
+        s.logger.Error("Gateway 连接失败，请检查网络", zap.Error(err))
+    default:
+        s.logger.Error("Gateway 未知错误", zap.Error(err))
+    }
+}
+```
+
+## 高级用法
+
+### 自定义超时时间
+
+```go
+client := gateway.NewClient(baseURL, appID, appSecret).
+    WithTimeout(60 * time.Second)
+
+resp, err := client.QueryCardStatus(ctx, &gateway.CardStatusReq{
+    CardNo: iccid,
+})
+```
+
+### 使用扩展字段（广电国网）
+
+部分 API 支持 `extend` 扩展字段用于特殊参数：
+
+```go
+err := s.gatewayClient.StopCard(ctx, &gateway.CardOperationReq{
+    CardNo: iccid,
+    Extend: "special_param=value",
+})
+```
+
+### Context 传递
+
+所有 API 方法都支持 `context.Context`，可以传递超时、取消信号等：
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+resp, err := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+    CardNo: iccid,
+})
+```
+
+## 最佳实践
+
+### 1. 空值检查
+
+```go
+func (s *Service) SafeCall(ctx context.Context) error {
+    if s.gatewayClient == nil {
+        return errors.New(errors.CodeGatewayError, "Gateway 客户端未配置")
+    }
+
+}
+```
+
+### 2. 日志记录
+
+```go
+func (s *Service) CallWithLogging(ctx context.Context, iccid string) error {
+    s.logger.Info("开始查询卡状态", zap.String("iccid", iccid))
+    
+    resp, err := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+        CardNo: iccid,
+    })
+    if err != nil {
+        s.logger.Error("查询失败", zap.String("iccid", iccid), zap.Error(err))
+        return err
+    }
+    
+    s.logger.Info("查询成功",
+        zap.String("iccid", resp.ICCID),
+        zap.String("status", resp.CardStatus),
+    )
+    return nil
+}
+```
+
+### 3. 重试机制
+
+```go
+func (s *Service) QueryWithRetry(ctx context.Context, iccid string) (*gateway.CardStatusResp, error) {
+    maxRetries := 3
+    var lastErr error
+    
+    for i := 0; i < maxRetries; i++ {
+        resp, err := s.gatewayClient.QueryCardStatus(ctx, &gateway.CardStatusReq{
+            CardNo: iccid,
+        })
+        if err == nil {
+            return resp, nil
+        }
+        
+        lastErr = err
+        s.logger.Warn("重试查询",
+            zap.Int("attempt", i+1),
+            zap.String("iccid", iccid),
+            zap.Error(err),
+        )
+        
+        time.Sleep(time.Second * time.Duration(i+1))
+    }
+    
+    return nil, errors.Wrap(errors.CodeGatewayError, lastErr, "重试失败")
+}
+```
+
+### 4. 批量处理
+
+```go
+func (s *Service) BatchSyncStatus(ctx context.Context, iccids []string) error {
+    for _, iccid := range iccids {
+        if err := s.SyncCardStatus(ctx, iccid); err != nil {
+            s.logger.Error("同步失败", zap.String("iccid", iccid), zap.Error(err))
+            continue
+        }
+    }
+    return nil
+}
+```
+
+## 测试
+
+### 单元测试
+
+Gateway 客户端提供完整的单元测试覆盖（88.8%）：
+
+```bash
+go test -v ./internal/gateway
+go test -cover ./internal/gateway
+```
+
+### 集成测试
+
+使用 `-short` 标志跳过集成测试：
+
+```bash
+go test -v ./internal/gateway -short
+```
+
+运行集成测试（需要真实 Gateway 环境）：
+
+```bash
+source .env.local && go test -v ./internal/gateway
+```
+
+## 故障排查
+
+### 常见问题
+
+#### 1. Gateway 客户端未配置
+
+**错误**: `Gateway 客户端未配置`
+
+**原因**: 环境变量未设置或 Bootstrap 初始化失败
+
+**解决方案**:
+```bash
+export JUNHONG_GATEWAY_BASE_URL=https://lplan.whjhft.com/openapi
+export JUNHONG_GATEWAY_APP_ID=your_app_id
+export JUNHONG_GATEWAY_APP_SECRET=your_app_secret
+```
+
+#### 2. 请求超时
+
+**错误**: `Gateway 请求超时`
+
+**原因**: 网络延迟或 Gateway 服务响应慢
+
+**解决方案**:
+```go
+client := client.WithTimeout(60 * time.Second)
+```
+
+#### 3. 业务错误
+
+**错误**: `业务错误: code=500, msg=xxx`
+
+**原因**: Gateway 服务端业务逻辑错误
+
+**解决方案**: 检查请求参数是否正确，查看日志中的 `TraceID` 联系 Gateway 服务提供方
+
+#### 4. 签名验证失败
+
+**错误**: `签名验证失败`
+
+**原因**: `AppSecret` 配置错误
+
+**解决方案**: 检查 `JUNHONG_GATEWAY_APP_SECRET` 环境变量是否正确
+
+## 相关文档
+
+- [Gateway API 参考](./gateway-api-reference.md) - 完整的 API 接口文档
+- [错误处理指南](./003-error-handling/使用指南.md) - 统一错误处理规范
+- [测试连接管理规范](./testing/test-connection-guide.md) - 测试规范和最佳实践