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

Draft: Gateway Integration 实施计划

需求确认（已完成）

用户目标

实现 Gateway API 统一封装,提供 14 个物联网卡和设备管理接口的类型安全封装,支持复杂的认证机制(AES-128-ECB 加密 + MD5 签名)。

核心需求

1. 加密/签名机制: AES-128-ECB 加密(密钥: MD5(appSecret),填充: PKCS5,编码: Base64) + MD5 签名(参数字母序拼接 + 大写十六进制)
2. API 封装: 流量卡 API(7个) + 设备 API(7个)
3. 配置集成: GatewayConfig + 环境变量覆盖 + Bootstrap 依赖注入
4. 错误处理: 定义错误码 1110-1119,统一错误包装和日志
5. 测试覆盖: 单元测试覆盖率 ≥ 90%,集成测试验证真实 Gateway API

技术约束

• 禁止跳过 tasks.md 中的61个任务
• 禁止合并或简化任务
• 所有注释必须使用中文
• 遵循项目代码规范(AGENTS.md)

文档已读取

OpenSpec 文档

• ✅ proposal.md - 提案概述和验收标准
• ✅ design.md - 详细设计文档(加密流程、请求流程、错误处理)
• ✅ tasks.md - 完整的61个任务清单(禁止跳过或简化)

规范文档

• ✅ specs/gateway-crypto/spec.md - 加密/签名规范(AES-ECB、MD5、PKCS5Padding)
• ✅ specs/gateway-config/spec.md - 配置集成规范(环境变量、验证逻辑)
• ✅ specs/gateway-client/spec.md - 客户端规范(14个API、DTO定义、并发安全)

背景调研（已完成 2/3）

✅ 已完成的调研

1. 项目架构模式 (bg_2a5fab13)

Bootstrap依赖注入模式:

• 6步初始化顺序: Stores → GORM Callbacks → Services → Admin → Middlewares → Handlers
• Dependencies结构: DB, Redis, Logger, JWT, Token, Verification, Queue, Storage
• 新增客户端模式: Dependencies结构 → main.go初始化 → Service注入

Config管理模式:

• 配置结构: 层级嵌套 + mapstructure标签
• 环境变量: JUNHONG_{SECTION}_{KEY} 格式
• 验证逻辑: ValidateRequired() + Validate()
• 添加配置节: struct定义 → defaults/config.yaml → bindEnvVariables → Validate

Error处理模式:

• 错误码范围: 1000-1999(4xx) + 2000-2999(5xx)
• 错误码必须在codes.go中注册: allErrorCodes + errorMessages
• 使用方式: errors.New(code) 或 errors.Wrap(code, err)
• 自动映射: 错误码 → HTTP状态码 + 日志级别

Service集成模式:

• Store初始化: NewXxxStore(deps.DB, deps.Redis)
• Service构造器: 接收stores + 外部clients
• 方法错误处理: 验证用New(), 系统错误用Wrap()

2. 测试模式和规范 (bg_6413c883)

testutils核心函数:

• NewTestTransaction(t): 自动回滚的事务
• GetTestRedis(t): 全局Redis连接
• CleanTestRedisKeys(t, rdb): 自动清理Redis键

集成测试环境:

• integ.NewIntegrationTestEnv(t): 完整测试环境
• 认证方法: AsSuperAdmin(), AsUser(account)
• 请求方法: Request(method, path, body)

测试执行:

• 必须先加载环境变量: source .env.local && go test
• 覆盖率要求: Service层 ≥ 90%

3. AES-ECB加密最佳实践 (bg_f36926a0) ✅

核心发现:

• AES-ECB必须手动实现(Go标准库不提供)
• 生产级参考: TiDB的实现(~50行代码)
• PKCS5 = PKCS7(8字节块)
• MD5密钥派生: crypto/md5.Sum()返回[16]byte
• Base64编码: encoding/base64.StdEncoding

安全注意:

• ECB模式不推荐(外部系统强制要求)
• 必须验证所有填充字节,不只是最后一个
• MD5已被破解(仅用于遗留系统)

任务依赖分析（初步）

Phase分析

基于tasks.md的5个Phase:

Phase 1: 基础结构搭建 (4个任务, 30min)

• Task 1.1: 创建目录结构 ✅ 独立
• Task 1.2: 加密/签名工具 ⏸️ 需等AES-ECB调研
• Task 1.3: Client基础结构 ⚠️ 依赖1.2
• Task 1.4: DTO定义 ✅ 独立

Phase 2: API接口封装 (3个任务, 40min)

• Task 2.1: 流量卡API(7个) ⚠️ 依赖1.3
• Task 2.2: 设备API(7个) ⚠️ 依赖1.3
• Task 2.3: 单元测试 ⚠️ 依赖2.1+2.2

Phase 3: 配置和错误码 (2个任务, 20min)

• Task 3.1: Gateway配置 ✅ 可与Phase 1并行
• Task 3.2: Gateway错误码 ✅ 可与Phase 1并行

Phase 4: 依赖注入和集成 (2个任务, 20min)

• Task 4.1: Bootstrap初始化 ⚠️ 依赖3.1+1.3
• Task 4.2: Service层集成 ⚠️ 依赖4.1

Phase 5: 集成测试和文档 (2个任务, 10min)

• Task 5.1: 集成测试 ⚠️ 依赖4.2
• Task 5.2: 更新文档 ✅ 可在最后并行

并行执行波次（初步）

Wave 1 (可立即并行):

• Task 1.1: 创建目录
• Task 1.4: DTO定义
• Task 3.1: Gateway配置
• Task 3.2: Gateway错误码

Wave 2 (依赖AES-ECB调研):

• Task 1.2: 加密/签名工具

Wave 3 (依赖Wave 2):

• Task 1.3: Client基础结构

Wave 4 (依赖Wave 3):

• Task 2.1: 流量卡API
• Task 2.2: 设备API
• Task 4.1: Bootstrap初始化

Wave 5 (依赖Wave 4):

• Task 2.3: 单元测试
• Task 4.2: Service集成

Wave 6 (依赖Wave 5):

• Task 5.1: 集成测试
• Task 5.2: 文档更新

关键路径识别

1.2(加密工具) → 1.3(Client结构) → 2.1/2.2(API封装) → 2.3(单元测试) → 4.2(Service集成) → 5.1(集成测试)

风险点

1. AES-ECB实现复杂度: 等待bg_f36926a0调研结果
2. 签名算法兼容性: 需要端到端集成测试验证
3. Gateway响应格式: 需要mock测试 + 真实API测试
4. 配置验证逻辑: 需要仔细测试必填项和格式验证

下一步

等待bg_f36926a0完成AES-ECB调研,然后生成完整的执行计划。