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

.sisyphus/drafts/gateway-integration-plan.md

@@ -0,0 +1,118 @@
+# Draft: Gateway Integration 工作计划
+
+## 用户需求确认
+
+**目标**: 封装 Gateway API 为统一的能力模块，提供类型安全的接口、统一的错误处理和配置管理。
+
+**核心交付物**:
+- Gateway 客户端封装（`internal/gateway/` 包）
+- 14 个 API 接口（流量卡 7 个 + 设备 7 个）
+- AES-128-ECB 加密 + MD5 签名机制
+- 配置集成（环境变量）
+- 错误码定义（1110-1119）
+- 依赖注入（Bootstrap）
+- 完整测试覆盖
+
+**总任务数**: 51 个实施任务 + 10 个验收标准
+
+## 初步任务分组
+
+### Phase 1: 基础结构搭建（13 个任务）
+- 目录结构创建
+- 加密/签名工具实现
+- 客户端基础结构
+- DTO 定义
+
+### Phase 2: API 接口封装（17 个任务）
+- 流量卡 API（7 个接口）
+- 设备 API（7 个接口）
+- 单元测试
+
+### Phase 3: 配置和错误码集成（7 个任务）
+- Gateway 配置
+- Gateway 错误码
+
+### Phase 4: 依赖注入和集成（6 个任务）
+- Bootstrap 初始化
+- Service 层集成
+
+### Phase 5: 集成测试和文档（8 个任务）
+- 集成测试
+- 文档更新
+
+## 用户决策（已确认）
+
+### 1. Gateway 测试环境配置 ✅
+- **BaseURL**: `https://lplan.whjhft.com/openapi`
+- **AppID**: `60bgt1X8i7AvXqkd`
+- **AppSecret**: `BZeQttaZQt0i73moF`
+- **测试 ICCID**: `8986062580006141710`
+- **设备测试**: 不需要测试
+
+### 2. 加密/签名算法验证 ✅
+- **文档来源**: Apifox 文档（https://omp5mq28pq.apifox.cn/7819761m0）
+- **加密方案**: AES-128-ECB + PKCS5Padding + Base64（密钥为 AppSecret 的 MD5）
+- **签名方案**: MD5(排序参数&key=AppSecret)，大写输出
+- **安全警告**: ⚠️ 遗留系统，添加安全警告注释（ECB 模式泄漏 + MD5 碰撞风险）
+
+### 3. Service 层集成范围 ✅
+- **集成位置**: `internal/service/iot_card/service.go`（已存在）
+- **集成方法**: 新增 `SyncCardStatus(ctx, iccid)` 方法作为示例
+- **范围**: 仅提供一个集成示例
+
+### 4. 批量查询接口 ✅
+- **决定**: ❌ 完全不实施（连预留接口都不需要）
+- **理由**: 用户明确表示"根本就不会有批量查询接口"
+
+### 5. 错误处理策略 ✅
+- **重试逻辑**: ✅ 需要自动重试（最多 3 次，指数退避：1s, 2s, 4s）
+- **降级策略**: ❌ 不需要
+- **超时处理**: 超时错误不重试，直接返回
+- **实现方式**: 在 `doRequest` 内置简单循环重试（无需第三方库）
+
+## 研究发现
+
+### 项目现有架构
+- **分层结构**: Handler → Service → Store → Model（严格分离）
+- **依赖注入**: Bootstrap 按顺序初始化（Stores → Services → Handlers）
+- **配置管理**: Viper 加载，支持环境变量覆盖（前缀 `JUNHONG_`）
+- **错误处理**: 统一错误码系统（1000-1999: 4xx, 2000-2999: 5xx）
+- **测试模式**: Table-driven tests + testutils（全局单例 DB/Redis）
+- **HTTP 客户端参考**: `/pkg/sms/` 使用接口 + 依赖注入模式
+
+### 加密/签名安全警告
+- **AES-128-ECB**: ⚠️ 密码学上已被破解（模式泄漏），仅用于遗留系统
+- **MD5 签名**: ⚠️ 存在碰撞攻击漏洞，建议使用 HMAC-SHA256
+- **理由**: 如果 Gateway API 是遗留系统且无法更改，则必须使用 ECB + MD5
+
+### 最佳实践建议
+1. **HTTP 客户端**: 使用 `http.Transport` 精细配置超时（Dial、TLS、ResponseHeader）
+2. **API 客户端**: 导出接口而非具体类型（可测试性）
+3. **集成测试**: 使用真实 Gateway 环境 + 测试 ICCID
+4. **错误处理**: 区分超时错误 vs 其他网络错误
+5. **重试策略**: 内置简单循环重试（无需第三方库）
+
+### 现有代码结构
+- **iot_card Service**: 已存在于 `internal/service/iot_card/service.go`
+  - 当前方法: ListStandalone, GetByICCID, AllocateCards, RecallCards, BatchSetSeriesBinding
+  - 新增方法: SyncCardStatus（Gateway 集成示例）
+- **HTTP 客户端参考**: `pkg/sms/http_client.go`（无重试逻辑，使用 context 超时）
+- **重试模式**: 项目使用 Asynq 任务队列重试（常量：`DefaultRetryMax = 5`）
+
+## 任务调整
+
+### 删除任务
+- **Task 20**: "预留 BatchQuery（批量查询，未来扩展）" → ❌ 删除
+
+### 新增任务
+- **Task 1.5**: "在 doRequest 中实现 HTTP 重试逻辑（3 次，指数退避）"
+- **Task 4.3**: "在 iot_card Service 中新增 SyncCardStatus 方法"
+
+### 修改任务
+- **Task 5.1**: 使用真实配置进行集成测试（测试 ICCID: `8986062580006141710`）
+- **Task 2.1**: 移除 BatchQuery 实现
+- **Task 2.2**: 设备 API 只实现方法签名（测试时跳过真实调用）
+
+### 调整后任务数
+- **实施任务**: 51 个（原 51 - 1 个删除 + 1 个新增 = 51）
+- **验收标准**: 10 个（保留但不作为实施任务）