# 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