huang
62708892ec
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m2s
147 lines
5.5 KiB
Markdown
147 lines
5.5 KiB
Markdown
# 提案：Gateway API 统一封装
|
||
|
||
## Why
|
||
|
||
当前项目需要调用外部 Gateway API 来实现物联网卡和设备的生命周期管理功能（状态查询、停复机、设备控制等）。Gateway API 具有以下特点：
|
||
|
||
1. **复杂的认证机制**：需要 AES-128-ECB 加密 + MD5 签名
|
||
2. **多个接口**：14 个 API（流量卡 7 个 + 设备 7 个）
|
||
3. **多场景调用**：Handler 层业务逻辑 + Asynq 定时任务批量同步
|
||
4. **缺乏统一封装**：调用逻辑分散，加密签名重复实现
|
||
|
||
本变更旨在**封装 Gateway API 为统一的能力模块**，提供类型安全的接口、统一的错误处理和配置管理，供 Service 层和 Asynq 任务调用。
|
||
|
||
## What Changes
|
||
|
||
### 1. Gateway 客户端封装
|
||
- 新增 `internal/gateway/` 包，提供 Gateway API 的统一封装
|
||
- 实现 AES-128-ECB 加密 + MD5 签名机制
|
||
- 封装 14 个 API 接口（流量卡 7 个 + 设备 7 个）
|
||
- 提供类型安全的请求/响应结构体
|
||
|
||
### 2. 配置集成
|
||
- 在 `pkg/config/config.go` 中添加 `GatewayConfig` 配置结构
|
||
- 支持环境变量配置：`JUNHONG_GATEWAY_BASE_URL`、`JUNHONG_GATEWAY_APP_ID`、`JUNHONG_GATEWAY_APP_SECRET`
|
||
- 配置项包括：BaseURL、AppID、AppSecret、Timeout
|
||
|
||
### 3. 错误处理
|
||
- 在 `pkg/errors/codes.go` 中定义 Gateway 相关错误码（1110-1119）
|
||
- 统一错误处理：加密失败、签名失败、请求超时、响应格式错误
|
||
|
||
### 4. 依赖注入
|
||
- 在 `internal/bootstrap/` 中初始化 Gateway 客户端
|
||
- 注入到需要调用 Gateway API 的 Service
|
||
|
||
### 5. 测试覆盖
|
||
- 单元测试：加密/签名函数验证
|
||
- 集成测试：实际调用 Gateway API 验证
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `gateway-client`: Gateway API 统一客户端，提供 14 个接口的类型安全封装
|
||
- `gateway-crypto`: AES-128-ECB 加密 + MD5 签名工具函数
|
||
|
||
### Modified Capabilities
|
||
|
||
- `config-management`: 添加 Gateway 配置支持
|
||
- `error-handling`: 添加 Gateway 相关错误码
|
||
- `dependency-injection`: 在 bootstrap 中初始化 Gateway 客户端
|
||
|
||
## Impact
|
||
|
||
### 代码变更
|
||
|
||
| 文件/目录 | 变更类型 | 说明 |
|
||
|-----------|----------|------|
|
||
| `internal/gateway/client.go` | 新增 | Gateway 客户端主体（Client 结构体 + doRequest） |
|
||
| `internal/gateway/crypto.go` | 新增 | AES 加密 + MD5 签名函数 |
|
||
| `internal/gateway/flow_card.go` | 新增 | 流量卡 7 个 API 方法封装 |
|
||
| `internal/gateway/device.go` | 新增 | 设备 7 个 API 方法封装 |
|
||
| `internal/gateway/models.go` | 新增 | 请求/响应 DTO 定义 |
|
||
| `internal/gateway/client_test.go` | 新增 | 单元测试和集成测试 |
|
||
| `pkg/config/config.go` | 修改 | 添加 GatewayConfig 结构体 |
|
||
| `pkg/errors/codes.go` | 修改 | 添加 Gateway 错误码（1110-1119） |
|
||
| `internal/bootstrap/bootstrap.go` | 修改 | 初始化 Gateway 客户端 |
|
||
|
||
### Gateway API 接口列表
|
||
|
||
**流量卡 API（7个）**：
|
||
1. `/flow-card/status` - 流量卡状态查询
|
||
2. `/flow-card/flow` - 流量使用查询
|
||
3. `/flow-card/realname-status` - 实名认证状态查询
|
||
4. `/flow-card/cardStop` - 流量卡停机
|
||
5. `/flow-card/cardStart` - 流量卡复机
|
||
6. `/flow-card/realname-link` - 获取实名认证跳转链接
|
||
7. `/flow-card/batch-query` - 批量查询（未来扩展）
|
||
|
||
**设备 API（7个）**：
|
||
1. `/device/info` - 获取设备信息
|
||
2. `/device/slot-info` - 获取设备卡槽信息
|
||
3. `/device/speed-limit` - 设置设备限速
|
||
4. `/device/wifi` - 设置设备 WiFi
|
||
5. `/device/switch-card` - 设备切换卡
|
||
6. `/device/reset` - 设备恢复出厂设置
|
||
7. `/device/reboot` - 设备重启
|
||
|
||
### 配置变更
|
||
|
||
**新增环境变量**：
|
||
```bash
|
||
JUNHONG_GATEWAY_BASE_URL=https://lplan.whjhft.com/openapi
|
||
JUNHONG_GATEWAY_APP_ID=60bgt1X8i7AvXqkd
|
||
JUNHONG_GATEWAY_APP_SECRET=BZeQttaZQt0i73moF
|
||
JUNHONG_GATEWAY_TIMEOUT=30
|
||
```
|
||
|
||
### 依赖
|
||
|
||
- 无新增外部依赖
|
||
- 使用标准库：`crypto/aes`、`crypto/md5`、`encoding/base64`、`net/http`
|
||
|
||
## 预期收益
|
||
|
||
| 指标 | 变更前 | 变更后 |
|
||
|------|--------|--------|
|
||
| Gateway 调用代码重复 | 每次调用重复加密签名 | 统一封装，零重复 |
|
||
| 错误处理一致性 | 不一致 | 统一错误码 |
|
||
| 类型安全 | 手动序列化，易出错 | 强类型 DTO，编译时检查 |
|
||
| 测试覆盖率 | 0% | 90%+ |
|
||
| 配置管理 | 硬编码 | 统一配置 |
|
||
|
||
## 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|---------|
|
||
| AES-ECB 模式安全性 | 低（外部系统要求） | 文档注明，无法改变 |
|
||
| 签名算法兼容性 | 中（签名不匹配导致认证失败） | 先实现端到端测试验证签名 |
|
||
| Gateway 响应格式变更 | 中（解析失败） | 统一错误处理，兼容性版本 |
|
||
|
||
## 后续计划
|
||
|
||
1. **阶段 1（本次变更）**：
|
||
- 实现 Gateway 客户端基础封装
|
||
- 支持同步模式（14 个接口）
|
||
- 集成到 Service 层
|
||
|
||
2. **阶段 2（未来优化）**：
|
||
- 实现异步模式回调接口
|
||
- 添加批量查询接口
|
||
- 实现请求重试和超时控制
|
||
|
||
3. **阶段 3（性能优化）**：
|
||
- 添加响应缓存（Redis）
|
||
- 实现请求限流（防止 Gateway 过载）
|
||
- 监控和告警集成
|
||
|
||
## 验收标准
|
||
|
||
- [ ] Gateway 客户端成功调用所有 14 个 API 接口
|
||
- [ ] 加密/签名验证通过（与 Gateway 文档一致）
|
||
- [ ] 错误处理覆盖所有异常场景（网络错误、响应格式错误等）
|
||
- [ ] 单元测试覆盖率 ≥ 90%
|
||
- [ ] 集成测试验证真实 Gateway API 调用
|
||
- [ ] 配置通过环境变量成功加载
|
||
- [ ] 文档完整（API 文档、使用示例、错误码说明）
|