修改 Bootstrap 注入 Gateway Client 依赖到 IotCardHandler 和 DeviceHandler

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

@@ -0,0 +1,75 @@
+# 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