csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
6c8308731963fc187a621b123b871cd74e60ddd8
junhong_cmp_fiber/.sisyphus/plans/add-gateway-admin-api.md

13 KiB
Raw Blame History

新增 Gateway 后台管理接口

TL;DR

Quick Summary: 将 Gateway 层已封装的 14 个第三方能力（卡状态查询、流量查询、停复机、设备控制等）暴露为后台管理 API，供平台用户和代理商使用。

Deliverables:

  • 6 个卡相关 Gateway 接口
  • 7 个设备相关 Gateway 接口
  • 对应的路由注册和 OpenAPI 文档

Estimated Effort: Medium Parallel Execution: YES - 2 waves Critical Path: 依赖注入 → 卡接口 → 设备接口

Context

Original Request

为 Gateway 层已封装的第三方能力提供后台管理接口，让前端可以对接卡和设备的实时查询、操作功能。

Interview Summary

Key Discussions:

  • 接口归属：集成到现有 iot-cards 和 devices 路径下
  • 业务逻辑：简单透传，仅做权限校验
  • 权限控制：平台 + 代理商（自动数据权限过滤）
  • ICCID = CardNo，IMEI = DeviceID，直接透传

Research Findings:

  • Gateway Client 已完整实现（internal/gateway/flow_card.go, internal/gateway/device.go）
  • 现有 Handler 结构清晰，可直接扩展
  • 路由注册使用 Register() 函数，自动生成 OpenAPI 文档

Work Objectives

Core Objective

将 Gateway 层封装的 13 个第三方能力暴露为后台管理 RESTful API。

Concrete Deliverables

  • internal/handler/admin/iot_card.go 扩展 6 个方法
  • internal/handler/admin/device.go 扩展 7 个方法
  • internal/routes/iot_card.go 注册 6 个路由
  • internal/routes/device.go 注册 7 个路由
  • internal/bootstrap/handlers.go 注入 Gateway Client 依赖
  • 13 个接口的集成测试

Definition of Done

  • 所有 13 个接口可通过 HTTP 调用
  • 代理商只能操作自己店铺的卡/设备（权限校验生效）
  • OpenAPI 文档自动生成
  • 集成测试覆盖所有接口

Must Have

  • 卡状态查询、流量查询、实名查询、停机、复机接口
  • 设备信息查询、卡槽查询、限速设置、WiFi 设置、切卡、重启、恢复出厂接口
  • 权限校验（先查数据库确认归属）

Must NOT Have (Guardrails)

  • 不添加额外业务逻辑（简单透传）
  • 不修改 Gateway 层代码
  • 不添加异步任务处理（同步调用）
  • 不添加缓存层

Verification Strategy

Test Decision

  • Infrastructure exists: YES (go test)
  • User wants tests: YES (集成测试)
  • Framework: go test + testutils

Automated Verification

# 运行集成测试
source .env.local && go test -v ./tests/integration/... -run TestGateway

# 检查 OpenAPI 文档生成
go run cmd/gendocs/main.go && cat docs/openapi.yaml | grep gateway

Execution Strategy

Parallel Execution Waves

Wave 1 (Start Immediately):
├── Task 1: 修改 Bootstrap 注入 Gateway Client
└── Task 2: 创建 OpenSpec proposal.md（可选，文档记录）

Wave 2 (After Wave 1):
├── Task 3: 扩展 IotCardHandler（6个接口）
├── Task 4: 扩展 DeviceHandler（7个接口）
└── Task 5: 注册路由

Wave 3 (After Wave 2):
└── Task 6: 添加集成测试

Critical Path: Task 1 → Task 3/4 → Task 6

TODOs

  • 1. 修改 Bootstrap 注入 Gateway Client 依赖

    What to do:

    • 修改 internal/bootstrap/handlers.go，为 IotCardHandler 和 DeviceHandler 注入 gateway.Client
    • 修改 Handler 构造函数签名，接收 gateway.Client 参数
    • 同时注入 IotCardStore 和 DeviceStore 用于权限校验

    Must NOT do:

    • 不修改 Gateway Client 本身
    • 不修改其他不相关的 Handler

    Recommended Agent Profile:

    • Category: quick
    • Skills: [api-routing]

    Parallelization:

    • Can Run In Parallel: NO
    • Blocks: Task 3, Task 4
    • Blocked By: None

    References:

    • internal/bootstrap/handlers.go - 现有 Handler 初始化模式
    • internal/bootstrap/types.go - Handlers 结构体定义
    • internal/gateway/client.go - Gateway Client 定义
    • internal/handler/admin/iot_card.go - 现有 Handler 结构

    Acceptance Criteria:

    • IotCardHandler 构造函数接收 gatewayClient *gateway.Client 参数
    • DeviceHandler 构造函数接收 gatewayClient *gateway.Client 参数
    • go build ./cmd/api 编译通过

    Commit: YES

    • Message: feat(bootstrap): 为 IotCardHandler 和 DeviceHandler 注入 Gateway Client
    • Files: internal/bootstrap/handlers.go, internal/handler/admin/iot_card.go, internal/handler/admin/device.go

  • 2. 扩展 IotCardHandler 添加 6 个 Gateway 接口方法

    What to do:

    • 在 internal/handler/admin/iot_card.go 中添加以下方法：
      • GetGatewayStatus(c *fiber.Ctx) error - 查询卡实时状态
      • GetGatewayFlow(c *fiber.Ctx) error - 查询流量使用
      • GetGatewayRealname(c *fiber.Ctx) error - 查询实名状态
      • GetRealnameLink(c *fiber.Ctx) error - 获取实名链接
      • StopCard(c *fiber.Ctx) error - 停机
      • StartCard(c *fiber.Ctx) error - 复机
    • 每个方法先查数据库校验权限，再调用 Gateway

    Must NOT do:

    • 不添加额外业务逻辑
    • 不修改现有方法

    Recommended Agent Profile:

    • Category: quick
    • Skills: [api-routing]

    Parallelization:

    • Can Run In Parallel: YES (with Task 3)
    • Parallel Group: Wave 2
    • Blocks: Task 5
    • Blocked By: Task 1

    References:

    • internal/handler/admin/iot_card.go - 现有 Handler 结构和模式
    • internal/gateway/flow_card.go - Gateway 方法定义
    • internal/gateway/models.go:CardStatusReq - 请求结构
    • internal/store/postgres/iot_card_store.go:GetByICCID - 权限校验方法

    Acceptance Criteria:

    • 6 个新方法已添加
    • 每个方法包含权限校验（调用 GetByICCID）
    • 使用 errors.New(errors.CodeNotFound, "卡不存在或无权限访问") 处理权限错误
    • go build ./cmd/api 编译通过

    Commit: YES

    • Message: feat(handler): IotCardHandler 新增 6 个 Gateway 接口方法
    • Files: internal/handler/admin/iot_card.go

  • 3. 扩展 DeviceHandler 添加 7 个 Gateway 接口方法

    What to do:

    • 在 internal/handler/admin/device.go 中添加以下方法：
      • GetGatewayInfo(c *fiber.Ctx) error - 查询设备信息
      • GetGatewaySlots(c *fiber.Ctx) error - 查询卡槽信息
      • SetSpeedLimit(c *fiber.Ctx) error - 设置限速
      • SetWiFi(c *fiber.Ctx) error - 设置 WiFi
      • SwitchCard(c *fiber.Ctx) error - 切换卡
      • RebootDevice(c *fiber.Ctx) error - 重启设备
      • ResetDevice(c *fiber.Ctx) error - 恢复出厂
    • 每个方法先查数据库校验权限，再调用 Gateway
    • 使用 c.Params("imei") 获取 IMEI 参数

    Must NOT do:

    • 不添加额外业务逻辑
    • 不修改现有方法

    Recommended Agent Profile:

    • Category: quick
    • Skills: [api-routing]

    Parallelization:

    • Can Run In Parallel: YES (with Task 2)
    • Parallel Group: Wave 2
    • Blocks: Task 5
    • Blocked By: Task 1

    References:

    • internal/handler/admin/device.go - 现有 Handler 结构和模式
    • internal/gateway/device.go - Gateway 方法定义
    • internal/gateway/models.go - 请求/响应结构（DeviceInfoReq, SpeedLimitReq, WiFiReq 等）
    • internal/store/postgres/device_store.go:GetByDeviceNo - 权限校验方法

    Acceptance Criteria:

    • 7 个新方法已添加
    • 每个方法包含权限校验（调用 GetByDeviceNo）
    • go build ./cmd/api 编译通过

    Commit: YES

    • Message: feat(handler): DeviceHandler 新增 7 个 Gateway 接口方法
    • Files: internal/handler/admin/device.go

  • 4. 注册卡 Gateway 路由（6个）

    What to do:

    • 在 internal/routes/iot_card.go 的 registerIotCardRoutes 函数中添加： 
      Register(cards, doc, groupPath, "GET", "/:iccid/gateway-status", h.GetGatewayStatus, RouteSpec{...})
Register(cards, doc, groupPath, "GET", "/:iccid/gateway-flow", h.GetGatewayFlow, RouteSpec{...})
Register(cards, doc, groupPath, "GET", "/:iccid/gateway-realname", h.GetGatewayRealname, RouteSpec{...})
Register(cards, doc, groupPath, "GET", "/:iccid/realname-link", h.GetRealnameLink, RouteSpec{...})
Register(cards, doc, groupPath, "POST", "/:iccid/stop", h.StopCard, RouteSpec{...})
Register(cards, doc, groupPath, "POST", "/:iccid/start", h.StartCard, RouteSpec{...})
    • 使用 gateway.CardStatusResp 等作为 Output 类型
    • Tags 使用 ["IoT卡管理"]

    Must NOT do:

    • 不修改现有路由

    Recommended Agent Profile:

    • Category: quick
    • Skills: [api-routing]

    Parallelization:

    • Can Run In Parallel: YES (with Task 5)
    • Parallel Group: Wave 2 (after handlers)
    • Blocks: Task 6
    • Blocked By: Task 2

    References:

    • internal/routes/iot_card.go - 现有路由注册模式
    • internal/routes/registry.go:RouteSpec - 路由规格结构
    • internal/gateway/models.go - 响应结构定义

    Acceptance Criteria:

    • 6 个新路由已注册
    • RouteSpec 包含 Summary、Tags、Input、Output、Auth
    • go build ./cmd/api 编译通过
    • go run cmd/gendocs/main.go 生成文档成功

    Commit: YES

    • Message: feat(routes): 注册 6 个卡 Gateway 路由
    • Files: internal/routes/iot_card.go

  • 5. 注册设备 Gateway 路由（7个）

    What to do:

    • 在 internal/routes/device.go 的 registerDeviceRoutes 函数中添加： 
      Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-info", h.GetGatewayInfo, RouteSpec{...})
Register(devices, doc, groupPath, "GET", "/by-imei/:imei/gateway-slots", h.GetGatewaySlots, RouteSpec{...})
Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/speed-limit", h.SetSpeedLimit, RouteSpec{...})
Register(devices, doc, groupPath, "PUT", "/by-imei/:imei/wifi", h.SetWiFi, RouteSpec{...})
Register(devices, doc, groupPath, "POST", "/by-imei/:imei/switch-card", h.SwitchCard, RouteSpec{...})
Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reboot", h.RebootDevice, RouteSpec{...})
Register(devices, doc, groupPath, "POST", "/by-imei/:imei/reset", h.ResetDevice, RouteSpec{...})
    • Tags 使用 ["设备管理"]

    Must NOT do:

    • 不修改现有路由

    Recommended Agent Profile:

    • Category: quick
    • Skills: [api-routing]

    Parallelization:

    • Can Run In Parallel: YES (with Task 4)
    • Parallel Group: Wave 2 (after handlers)
    • Blocks: Task 6
    • Blocked By: Task 3

    References:

    • internal/routes/device.go - 现有路由注册模式
    • internal/routes/registry.go:RouteSpec - 路由规格结构
    • internal/gateway/models.go - 请求/响应结构定义

    Acceptance Criteria:

    • 7 个新路由已注册
    • RouteSpec 包含 Summary、Tags、Input、Output、Auth
    • go build ./cmd/api 编译通过
    • go run cmd/gendocs/main.go 生成文档成功

    Commit: YES

    • Message: feat(routes): 注册 7 个设备 Gateway 路由
    • Files: internal/routes/device.go

  • 6. 添加集成测试

    What to do:

    • 创建或扩展 tests/integration/iot_card_gateway_test.go：
      • 测试 6 个卡 Gateway 接口
      • 测试权限校验（代理商不能操作其他店铺的卡）
      • Mock Gateway 响应
    • 创建或扩展 tests/integration/device_gateway_test.go：
      • 测试 7 个设备 Gateway 接口
      • 测试权限校验
      • Mock Gateway 响应

    Must NOT do:

    • 不调用真实第三方服务

    Recommended Agent Profile:

    • Category: unspecified-low
    • Skills: []

    Parallelization:

    • Can Run In Parallel: NO
    • Parallel Group: Wave 3 (final)
    • Blocks: None
    • Blocked By: Task 4, Task 5

    References:

    • tests/integration/iot_card_test.go - 现有集成测试模式
    • tests/integration/device_test.go - 现有设备测试模式
    • internal/testutils/ - 测试工具函数

    Acceptance Criteria:

    • 卡 Gateway 接口测试覆盖 6 个端点
    • 设备 Gateway 接口测试覆盖 7 个端点
    • 权限校验测试通过
    • source .env.local && go test -v ./tests/integration/... -run TestGateway 通过

    Commit: YES

    • Message: test(integration): 添加 Gateway 接口集成测试
    • Files: tests/integration/iot_card_gateway_test.go, tests/integration/device_gateway_test.go

Commit Strategy

After Task Message Files
1 feat(bootstrap): 为 IotCardHandler 和 DeviceHandler 注入 Gateway Client handlers.go, iot_card.go, device.go
2 feat(handler): IotCardHandler 新增 6 个 Gateway 接口方法 iot_card.go
3 feat(handler): DeviceHandler 新增 7 个 Gateway 接口方法 device.go
4 feat(routes): 注册 6 个卡 Gateway 路由 iot_card.go
5 feat(routes): 注册 7 个设备 Gateway 路由 device.go
6 test(integration): 添加 Gateway 接口集成测试 *_gateway_test.go

Success Criteria

Verification Commands

# 编译检查
go build ./cmd/api

# 生成 OpenAPI 文档
go run cmd/gendocs/main.go

# 运行集成测试
source .env.local && go test -v ./tests/integration/... -run TestGateway

Final Checklist

  • 所有 13 个接口可访问
  • 权限校验生效
  • OpenAPI 文档包含新接口
  • 集成测试通过
Reference in New Issue View Git Blame Copy Permalink