# 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调研,然后生成完整的执行计划。