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