docs: 新增 Gateway 集成和微信公众号支付集成的 OpenSpec 规划文档

openspec/changes/gateway-integration/proposal.md

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