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

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 个（保留但不作为实施任务）