junhong_cmp_fiber/.sisyphus/notepads/add-gateway-admin-api/learnings.md

Learnings - add-gateway-admin-api

Plan Overview

• Goal: Expose 13 Gateway third-party capabilities as admin management APIs
• Deliverables: 6 IoT card endpoints + 7 device endpoints
• Effort: Medium
• Parallel Execution: YES - 2 waves

Execution Strategy

Wave 1: Task 1 (Bootstrap dependency injection)
Wave 2: Task 2 + Task 3 (Parallel - Card handlers + Device handlers)  
Wave 3: Task 4 + Task 5 (Parallel - Register routes)
Wave 4: Task 6 (Integration tests)

Critical Dependencies

• Task 1 BLOCKS Task 2, 3
• Task 2 BLOCKS Task 4
• Task 3 BLOCKS Task 5
• Task 4, 5 BLOCK Task 6

Key Files

• internal/bootstrap/handlers.go - Dependency injection for handlers
• internal/handler/admin/iot_card.go - Card handler (6 new methods)
• internal/handler/admin/device.go - Device handler (7 new methods)
• internal/routes/iot_card.go - Card routes registration
• internal/routes/device.go - Device routes registration
• internal/gateway/flow_card.go - Gateway card methods
• internal/gateway/device.go - Gateway device methods
• tests/integration/iot_card_gateway_test.go - Card integration tests
• tests/integration/device_gateway_test.go - Device integration tests

API Design Principles

1. Simple passthrough - no additional business logic
2. Permission validation: Query DB to confirm ownership before calling Gateway
3. Error handling: Use errors.New(errors.CodeNotFound, "卡不存在或无权限访问")
4. Tags: Use ["IoT卡管理"] for cards, ["设备管理"] for devices

Route Patterns

Card routes (base: /api/admin/iot-cards):

• GET /:iccid/gateway-status
• GET /:iccid/gateway-flow
• GET /:iccid/gateway-realname
• GET /:iccid/realname-link
• POST /:iccid/stop
• POST /:iccid/start

Device routes (base: /api/admin/devices):

• GET /by-imei/:imei/gateway-info
• GET /by-imei/:imei/gateway-slots
• PUT /by-imei/:imei/speed-limit
• PUT /by-imei/:imei/wifi
• POST /by-imei/:imei/switch-card
• POST /by-imei/:imei/reboot
• POST /by-imei/:imei/reset

Verification Commands

# Build check
go build ./cmd/api

# OpenAPI docs generation
go run cmd/gendocs/main.go

# Integration tests
source .env.local && go test -v ./tests/integration/... -run TestGateway

Important Notes

• Do NOT modify Gateway Client itself
• Do NOT add extra business logic (simple passthrough only)
• Do NOT add async task processing
• Do NOT add caching layer
• All handlers must validate permissions first before calling Gateway