76 lines
2.5 KiB
Markdown
76 lines
2.5 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|