docs: 新增 Gateway 集成和微信公众号支付集成的 OpenSpec 规划文档
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 43s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 43s
This commit is contained in:
173
openspec/changes/gateway-integration/tasks.md
Normal file
173
openspec/changes/gateway-integration/tasks.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 任务清单：Gateway API 统一封装
|
||||
|
||||
## Phase 1: 基础结构搭建（30min）
|
||||
|
||||
### Task 1.1: 创建 Gateway 包目录结构
|
||||
- [ ] 创建 `internal/gateway/` 目录
|
||||
- [ ] 创建占位文件：`client.go`、`crypto.go`、`models.go`
|
||||
- **验证**：目录结构创建成功
|
||||
|
||||
### Task 1.2: 实现加密/签名工具函数
|
||||
- [ ] 在 `crypto.go` 中实现 `aesEncrypt` 函数（AES-128-ECB + PKCS5Padding + Base64）
|
||||
- [ ] 在 `crypto.go` 中实现 `generateSign` 函数（MD5 签名，大写输出）
|
||||
- [ ] 添加单元测试验证加密/签名正确性
|
||||
- **验证**：
|
||||
```bash
|
||||
go test -v ./internal/gateway -run TestAESEncrypt
|
||||
go test -v ./internal/gateway -run TestGenerateSign
|
||||
```
|
||||
|
||||
### Task 1.3: 实现 Gateway 客户端基础结构
|
||||
- [ ] 在 `client.go` 中定义 `Client` 结构体
|
||||
- [ ] 实现 `NewClient` 构造函数
|
||||
- [ ] 实现 `WithTimeout` 配置方法
|
||||
- [ ] 实现 `doRequest` 统一请求方法（加密、签名、HTTP 请求、响应解析）
|
||||
- **验证**：编译通过，无 LSP 错误
|
||||
|
||||
### Task 1.4: 定义请求/响应 DTO
|
||||
- [ ] 在 `models.go` 中定义 `GatewayResponse` 通用响应结构
|
||||
- [ ] 定义流量卡相关 DTO（`CardStatusReq`、`CardStatusResp`、`FlowQueryReq`、`FlowUsageResp` 等）
|
||||
- [ ] 定义设备相关 DTO（`DeviceInfoReq`、`DeviceInfoResp` 等）
|
||||
- [ ] 添加 JSON 标签和验证标签
|
||||
- **验证**：编译通过，结构体定义完整
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: API 接口封装（40min）
|
||||
|
||||
### Task 2.1: 实现流量卡 API（7个接口）
|
||||
- [ ] 在 `flow_card.go` 中实现 `QueryCardStatus`（流量卡状态查询）
|
||||
- [ ] 实现 `QueryFlow`（流量使用查询）
|
||||
- [ ] 实现 `QueryRealnameStatus`（实名认证状态查询）
|
||||
- [ ] 实现 `StopCard`（流量卡停机）
|
||||
- [ ] 实现 `StartCard`（流量卡复机）
|
||||
- [ ] 实现 `GetRealnameLink`（获取实名认证跳转链接）
|
||||
- [ ] 预留 `BatchQuery`（批量查询，未来扩展）
|
||||
- **验证**：编译通过，方法签名正确
|
||||
|
||||
### Task 2.2: 实现设备 API（7个接口）
|
||||
- [ ] 在 `device.go` 中实现 `GetDeviceInfo`（获取设备信息）
|
||||
- [ ] 实现 `GetSlotInfo`（获取设备卡槽信息）
|
||||
- [ ] 实现 `SetSpeedLimit`（设置设备限速）
|
||||
- [ ] 实现 `SetWiFi`（设置设备 WiFi）
|
||||
- [ ] 实现 `SwitchCard`（设备切换卡）
|
||||
- [ ] 实现 `ResetDevice`（设备恢复出厂设置）
|
||||
- [ ] 实现 `RebootDevice`（设备重启）
|
||||
- **验证**：编译通过，方法签名正确
|
||||
|
||||
### Task 2.3: 添加单元测试
|
||||
- [ ] 在 `client_test.go` 中添加加密/签名单元测试
|
||||
- [ ] 添加 `doRequest` 的 mock 测试
|
||||
- [ ] 验证错误处理逻辑（超时、网络错误、响应格式错误）
|
||||
- **验证**：
|
||||
```bash
|
||||
go test -v ./internal/gateway -cover
|
||||
```
|
||||
覆盖率 ≥ 90%
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: 配置和错误码集成（20min）
|
||||
|
||||
### Task 3.1: 添加 Gateway 配置
|
||||
- [ ] 在 `pkg/config/config.go` 中添加 `GatewayConfig` 结构体
|
||||
- [ ] 在 `Config` 中添加 `Gateway GatewayConfig` 字段
|
||||
- [ ] 在 `pkg/config/defaults/config.yaml` 中添加 gateway 配置项
|
||||
- [ ] 添加配置验证逻辑（必填项检查）
|
||||
- **验证**：
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export JUNHONG_GATEWAY_BASE_URL=https://lplan.whjhft.com/openapi
|
||||
export JUNHONG_GATEWAY_APP_ID=60bgt1X8i7AvXqkd
|
||||
export JUNHONG_GATEWAY_APP_SECRET=BZeQttaZQt0i73moF
|
||||
|
||||
# 启动应用验证配置加载
|
||||
go run cmd/api/main.go
|
||||
```
|
||||
|
||||
### Task 3.2: 添加 Gateway 错误码
|
||||
- [ ] 在 `pkg/errors/codes.go` 中添加 Gateway 错误码常量（1110-1119）
|
||||
- [ ] 在 `allErrorCodes` 数组中注册新错误码
|
||||
- [ ] 在 `errorMessages` 映射表中添加中文错误消息
|
||||
- [ ] 运行错误码验证测试
|
||||
- **验证**：
|
||||
```bash
|
||||
go test -v ./pkg/errors -run TestErrorCodes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: 依赖注入和集成（20min）
|
||||
|
||||
### Task 4.1: Bootstrap 初始化 Gateway 客户端
|
||||
- [ ] 在 `internal/bootstrap/bootstrap.go` 的 `Dependencies` 中添加 `GatewayClient *gateway.Client` 字段
|
||||
- [ ] 在 `Bootstrap` 函数中初始化 Gateway 客户端
|
||||
- [ ] 将 Gateway 客户端注入到需要的 Service
|
||||
- **验证**：编译通过，依赖注入正确
|
||||
|
||||
### Task 4.2: Service 层集成示例
|
||||
- [ ] 选择一个 Service（如 `iot_card`）集成 Gateway 客户端
|
||||
- [ ] 添加 `SyncCardStatus` 方法示例
|
||||
- [ ] 添加错误处理和日志记录
|
||||
- **验证**：编译通过，方法签名正确
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: 集成测试和文档（10min）
|
||||
|
||||
### Task 5.1: 编写集成测试
|
||||
- [ ] 在 `client_test.go` 中添加集成测试（需要真实 Gateway 环境）
|
||||
- [ ] 测试至少 2 个接口（如 `QueryCardStatus`、`StopCard`）
|
||||
- [ ] 验证加密/签名与 Gateway 文档一致
|
||||
- **验证**：
|
||||
```bash
|
||||
# 设置测试环境变量
|
||||
source .env.local
|
||||
|
||||
# 运行集成测试
|
||||
go test -v ./internal/gateway -run TestIntegration
|
||||
```
|
||||
|
||||
### Task 5.2: 更新文档
|
||||
- [ ] 在 `docs/` 目录下创建 `gateway-client-usage.md`
|
||||
- [ ] 添加 Gateway 客户端使用示例
|
||||
- [ ] 添加错误码说明
|
||||
- [ ] 更新 `README.md` 添加 Gateway 模块说明
|
||||
- **验证**：文档完整，示例代码可运行
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 所有 14 个 Gateway API 接口成功封装
|
||||
- [ ] 加密/签名验证通过（与 Gateway 文档一致）
|
||||
- [ ] 错误处理覆盖所有异常场景
|
||||
- [ ] 单元测试覆盖率 ≥ 90%
|
||||
- [ ] 集成测试验证真实 Gateway API 调用
|
||||
- [ ] 配置通过环境变量成功加载
|
||||
- [ ] 依赖注入到 Service 层成功
|
||||
- [ ] 文档完整（使用示例、错误码说明）
|
||||
- [ ] 无 LSP 错误，编译通过
|
||||
- [ ] 符合项目代码规范（中文注释、Go 命名规范）
|
||||
|
||||
---
|
||||
|
||||
## 任务执行规范
|
||||
|
||||
**⚠️ 重要提醒**：
|
||||
- ❌ 禁止跳过任务
|
||||
- ❌ 禁止合并任务或简化执行
|
||||
- ❌ 禁止自作主张优化流程
|
||||
- ✅ 必须按顺序逐项完成
|
||||
- ✅ 每个任务完成后标记 `[x]`
|
||||
- ✅ 如需调整任务，先询问用户确认
|
||||
|
||||
**任务依赖关系**：
|
||||
- Phase 1 → Phase 2：基础结构完成后再实现 API
|
||||
- Phase 3 → Phase 4：配置和错误码完成后再集成
|
||||
- Phase 4 → Phase 5：依赖注入完成后再测试
|
||||
|
||||
**并行执行机会**：
|
||||
- Task 1.2（加密函数）和 Task 1.4（DTO 定义）可并行
|
||||
- Task 2.1（流量卡 API）和 Task 2.2（设备 API）可并行
|
||||
- Task 3.1（配置）和 Task 3.2（错误码）可并行
|
||||
Reference in New Issue
Block a user