# 提案：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 文档、使用示例、错误码说明）