d2c6937665
Updated all spec-kit documents to document the implemented configuration management features (User Story 12): Changes: - spec.md: Added User Story 12 with implementation status and functional requirements (FR-039 through FR-045) - plan.md: Added Phase 2 (Configuration Management) as completed, updated phase status and last updated date - data-model.md: Added GCoreServer entity with schema, validation rules, CRUD status, and critical implementation details - tasks.md: Added Phase 13 for User Story 12 with implementation summary, updated task counts and dependencies - tasks-revised-mvp.md: Added configuration management completion notice Implementation Highlights: - G-Core Server CRUD (CREATE, READ, DELETE working; UPDATE has known bug) - Action Mapping CRUD (all operations working) - SetupClient integration for .set file operations - Critical cascade deletion bug fix (delete in reverse order) - Comprehensive test scripts and verification tools Documentation: SERVER_CRUD_IMPLEMENTATION.md, CRITICAL_BUG_FIX_DELETE.md 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
438 lines
16 KiB
Markdown
438 lines
16 KiB
Markdown
# Tasks: Geutebruck Cross-Switching API (Revised MVP)
|
|
|
|
**Scope**: Cross-switching REST API with authentication, focusing on GeViSet-compatible configuration
|
|
**MVP Goal**: Control GSCView viewers via cross-switching, no UI needed
|
|
**Future Expansion**: GeViSet configuration management, action mapping, CSV import/export
|
|
|
|
---
|
|
|
|
## MVP User Stories
|
|
|
|
### US1: Authentication & Connection
|
|
Connect to GeViServer, authenticate users, maintain sessions
|
|
|
|
### US2: Camera Discovery
|
|
List all video inputs (cameras) with metadata
|
|
|
|
### US3: Monitor Discovery
|
|
List all video outputs (GSCView viewers/monitors) with status
|
|
|
|
### US4: Cross-Switching Operations
|
|
Route cameras to viewers, clear viewers, query routing state
|
|
|
|
---
|
|
|
|
## Revised Data Model (Simplified)
|
|
|
|
```
|
|
User:
|
|
- id, username, password_hash, role (viewer/operator/admin)
|
|
|
|
Camera:
|
|
- id (channel), name, description, has_ptz, has_video_sensor, status
|
|
|
|
Monitor:
|
|
- id (output channel), name, is_active, current_camera_id
|
|
|
|
CrossSwitchRoute:
|
|
- id, camera_id, monitor_id, switched_at, switched_by_user_id
|
|
|
|
AuditLog:
|
|
- id, user_id, action, target, timestamp, details
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 1: Foundation (Setup & Core Infrastructure)
|
|
|
|
**Purpose**: Project structure, dependencies, SDK bridge foundation
|
|
|
|
- [ ] T001 Create project structure (src/api, src/sdk-bridge, tests, docs, scripts)
|
|
- [ ] T002 Create .gitignore for Python and C#
|
|
- [ ] T003 Create requirements.txt with FastAPI, SQLAlchemy, Redis, grpcio, PyJWT, pytest
|
|
- [ ] T004 Create SDK Bridge .csproj with .NET 8.0, Grpc.AspNetCore, GeViScope SDK reference
|
|
- [ ] T005 Create .env.example with config variables (DB, Redis, JWT secret, GeViServer host/credentials)
|
|
- [ ] T006 Create alembic.ini for database migrations
|
|
- [ ] T007 [P] Create pyproject.toml with ruff, black, mypy configuration
|
|
- [ ] T008 [P] Create scripts/setup_dev_environment.ps1 (install dependencies, setup DB, start services)
|
|
- [ ] T009 [P] Create scripts/start_services.ps1 (start Redis, SDK Bridge, FastAPI)
|
|
- [ ] T010 [P] Create docs/architecture.md documenting system design
|
|
|
|
**Checkpoint**: Project structure complete, dependencies defined
|
|
|
|
---
|
|
|
|
## Phase 2: SDK Bridge Foundation (C# gRPC Service)
|
|
|
|
**Purpose**: Wrap GeViScope SDK with gRPC for Python consumption
|
|
|
|
### gRPC Protocol Definitions
|
|
|
|
- [ ] T011 Define common.proto (Status, Error, Timestamp, Empty messages)
|
|
- [ ] T012 Define camera.proto (ListCamerasRequest/Response, CameraInfo with channel, name, has_ptz)
|
|
- [ ] T013 Define monitor.proto (ListMonitorsRequest/Response, MonitorInfo with channel, name, current_camera)
|
|
- [ ] T014 Define crossswitch.proto (CrossSwitchRequest, ClearMonitorRequest, GetRoutingStateRequest/Response)
|
|
|
|
### SDK Wrapper Implementation
|
|
|
|
- [ ] T015 Create GeViDatabaseWrapper.cs (Create, RegisterCallback, Connect, Disconnect, error handling)
|
|
- [ ] T016 Implement connection lifecycle with retry logic (3 attempts, exponential backoff)
|
|
- [ ] T017 Create StateQueryHandler.cs for GetFirst/GetNext enumeration pattern
|
|
- [ ] T018 Implement EnumerateCameras() using CSQGetFirstVideoInput / CSQGetNextVideoInput
|
|
- [ ] T019 Implement EnumerateMonitors() using CSQGetFirstVideoOutput / CSQGetNextVideoOutput
|
|
- [ ] T020 Create ErrorTranslator.cs to map Windows error codes to gRPC status codes
|
|
- [ ] T021 Create ActionDispatcher.cs for sending SDK actions (CrossSwitch, ClearVideoOutput)
|
|
|
|
### gRPC Service Implementation
|
|
|
|
- [ ] T022 Create CameraService.cs implementing camera.proto with ListCameras RPC
|
|
- [ ] T023 Create MonitorService.cs implementing monitor.proto with ListMonitors RPC
|
|
- [ ] T024 Create CrossSwitchService.cs with ExecuteCrossSwitch, ClearMonitor, GetRoutingState RPCs
|
|
- [ ] T025 Create Program.cs gRPC server with Serilog logging, service registration
|
|
- [ ] T026 Add configuration loading from appsettings.json (GeViServer host, port, credentials)
|
|
|
|
**Checkpoint**: SDK Bridge can connect to GeViServer, enumerate resources, execute cross-switch
|
|
|
|
---
|
|
|
|
## Phase 3: Python API Foundation
|
|
|
|
**Purpose**: FastAPI application structure, configuration, database setup
|
|
|
|
### Core Setup
|
|
|
|
- [ ] T027 Create main.py with FastAPI app, CORS middleware, exception handlers
|
|
- [ ] T028 Create config.py loading settings from environment (Pydantic BaseSettings)
|
|
- [ ] T029 Setup PostgreSQL connection with SQLAlchemy async engine in models/__init__.py
|
|
- [ ] T030 Create initial Alembic migration for users and audit_logs tables
|
|
- [ ] T031 Setup Redis client with connection pooling in clients/redis_client.py
|
|
- [ ] T032 Create gRPC SDK Bridge client in clients/sdk_bridge_client.py with connection pooling
|
|
- [ ] T033 [P] Create JWT utilities in utils/jwt_utils.py (encode, decode, verify)
|
|
- [ ] T034 [P] Create error translation utilities in utils/error_translation.py (gRPC → HTTP status)
|
|
- [ ] T035 Implement global error handler middleware in middleware/error_handler.py
|
|
|
|
### Database Models
|
|
|
|
- [ ] T036 [P] Create User model in models/user.py (id, username, password_hash, role, created_at)
|
|
- [ ] T037 [P] Create AuditLog model in models/audit_log.py (id, user_id, action, target, timestamp)
|
|
- [ ] T038 Run alembic upgrade head to create tables
|
|
|
|
**Checkpoint**: Python API can start, connect to DB/Redis, communicate with SDK Bridge via gRPC
|
|
|
|
---
|
|
|
|
## Phase 4: Authentication (User Story 1)
|
|
|
|
**Purpose**: JWT-based authentication with role-based access control
|
|
|
|
### Tests (TDD - Write FIRST, Ensure FAIL)
|
|
|
|
- [ ] T039 [P] Write contract test for POST /api/v1/auth/login in tests/api/contract/test_auth.py (should FAIL)
|
|
- [ ] T040 [P] Write contract test for POST /api/v1/auth/logout in tests/api/contract/test_auth.py (should FAIL)
|
|
- [ ] T041 [P] Write unit test for AuthService in tests/api/unit/test_auth_service.py (should FAIL)
|
|
|
|
### Implementation
|
|
|
|
- [ ] T042 [P] Create auth schemas in schemas/auth.py (LoginRequest, TokenResponse, UserInfo)
|
|
- [ ] T043 Implement AuthService in services/auth_service.py (login, logout, validate_token, hash_password)
|
|
- [ ] T044 Implement JWT token generation (access: 1hr, refresh: 7 days) with Redis session storage
|
|
- [ ] T045 Implement authentication middleware in middleware/auth_middleware.py (verify JWT, extract user)
|
|
- [ ] T046 Implement role checking decorator in utils/permissions.py (@require_role("operator"))
|
|
- [ ] T047 Create auth router in routers/auth.py with POST /auth/login, POST /auth/logout
|
|
- [ ] T048 Add audit logging for authentication attempts (success and failures)
|
|
|
|
**Verify**: Run tests T039-T041 - should now PASS
|
|
|
|
**Checkpoint**: Can login with credentials, receive JWT token, use token for authenticated requests
|
|
|
|
---
|
|
|
|
## Phase 5: Camera Discovery (User Story 2)
|
|
|
|
**Purpose**: List all cameras (video inputs) from GeViServer
|
|
|
|
### Tests (TDD - Write FIRST, Ensure FAIL)
|
|
|
|
- [ ] T049 [P] Write contract test for GET /api/v1/cameras in tests/api/contract/test_cameras.py (should FAIL)
|
|
- [ ] T050 [P] Write unit test for CameraService in tests/api/unit/test_camera_service.py (should FAIL)
|
|
|
|
### Implementation
|
|
|
|
- [ ] T051 [P] Create camera schemas in schemas/camera.py (CameraInfo, CameraList)
|
|
- [ ] T052 Implement CameraService in services/camera_service.py (list_cameras via gRPC to SDK Bridge)
|
|
- [ ] T053 Create cameras router in routers/cameras.py with GET /cameras
|
|
- [ ] T054 Add permission check: authenticated users only
|
|
- [ ] T055 Add caching in Redis (cache camera list for 60 seconds to reduce SDK Bridge load)
|
|
|
|
**Verify**: Run tests T049-T050 - should now PASS
|
|
|
|
**Checkpoint**: GET /api/v1/cameras returns list of all cameras from GeViServer
|
|
|
|
---
|
|
|
|
## Phase 6: Monitor Discovery (User Story 3)
|
|
|
|
**Purpose**: List all monitors/viewers (video outputs) from GeViServer
|
|
|
|
### Tests (TDD - Write FIRST, Ensure FAIL)
|
|
|
|
- [ ] T056 [P] Write contract test for GET /api/v1/monitors in tests/api/contract/test_monitors.py (should FAIL)
|
|
- [ ] T057 [P] Write unit test for MonitorService in tests/api/unit/test_monitor_service.py (should FAIL)
|
|
|
|
### Implementation
|
|
|
|
- [ ] T058 [P] Create monitor schemas in schemas/monitor.py (MonitorInfo, MonitorList)
|
|
- [ ] T059 Implement MonitorService in services/monitor_service.py (list_monitors via gRPC to SDK Bridge)
|
|
- [ ] T060 Create monitors router in routers/monitors.py with GET /monitors
|
|
- [ ] T061 Add permission check: authenticated users only
|
|
- [ ] T062 Add caching in Redis (cache monitor list for 60 seconds)
|
|
|
|
**Verify**: Run tests T056-T057 - should now PASS
|
|
|
|
**Checkpoint**: GET /api/v1/monitors returns list of all monitors/viewers from GeViServer
|
|
|
|
---
|
|
|
|
## Phase 7: Cross-Switching Operations (User Story 4)
|
|
|
|
**Purpose**: Execute cross-switch, clear monitors, query routing state
|
|
|
|
### Tests (TDD - Write FIRST, Ensure FAIL)
|
|
|
|
- [ ] T063 [P] Write contract test for POST /api/v1/crossswitch in tests/api/contract/test_crossswitch.py (should FAIL)
|
|
- [ ] T064 [P] Write contract test for DELETE /api/v1/monitors/{id} in tests/api/contract/test_crossswitch.py (should FAIL)
|
|
- [ ] T065 [P] Write contract test for GET /api/v1/routing/state in tests/api/contract/test_crossswitch.py (should FAIL)
|
|
- [ ] T066 [P] Write integration test for cross-switch workflow in tests/api/integration/test_crossswitch.py (should FAIL)
|
|
|
|
### Implementation
|
|
|
|
- [ ] T067 [P] Create crossswitch schemas in schemas/crossswitch.py (CrossSwitchRequest, RoutingState, ClearMonitorRequest)
|
|
- [ ] T068 Create CrossSwitchRoute model in models/crossswitch_route.py (id, camera_id, monitor_id, switched_at, user_id)
|
|
- [ ] T069 Create Alembic migration for crossswitch_routes table
|
|
- [ ] T070 Implement CrossSwitchService in services/crossswitch_service.py:
|
|
- execute_crossswitch(camera_id, monitor_id, mode=0) → gRPC to SDK Bridge
|
|
- clear_monitor(monitor_id) → gRPC ClearVideoOutput
|
|
- get_routing_state() → query current routes
|
|
- [ ] T071 Create crossswitch router in routers/crossswitch.py:
|
|
- POST /crossswitch (requires operator or admin role)
|
|
- DELETE /monitors/{id} (requires operator or admin role)
|
|
- GET /routing/state (all authenticated users)
|
|
- [ ] T072 Add audit logging for all cross-switch operations
|
|
- [ ] T073 Add validation: camera_id and monitor_id must exist
|
|
- [ ] T074 Store routing state in database for history/tracking
|
|
|
|
**Verify**: Run tests T063-T066 - should now PASS
|
|
|
|
**Checkpoint**: Can execute cross-switch via API, clear monitors, query current routing
|
|
|
|
---
|
|
|
|
## Phase 8: MVP Polish & Documentation
|
|
|
|
**Purpose**: Complete MVP with documentation and deployment readiness
|
|
|
|
- [ ] T075 [P] Create API documentation in docs/api-usage.md with curl examples
|
|
- [ ] T076 [P] Create deployment guide in docs/deployment.md (Windows Server setup, service installation)
|
|
- [ ] T077 [P] Add Prometheus metrics endpoint at /metrics (request count, latency, active connections)
|
|
- [ ] T078 [P] Create health check endpoint GET /health (SDK Bridge connectivity, DB, Redis status)
|
|
- [ ] T079 [P] Add request logging with correlation IDs
|
|
- [ ] T080 Create README.md with project overview, quick start, architecture diagram
|
|
- [ ] T081 Update OpenAPI specification to include only MVP endpoints
|
|
- [ ] T082 Create Postman collection for API testing
|
|
- [ ] T083 Run full integration tests with actual GeViServer connection
|
|
- [ ] T084 Security audit: Remove stack traces in production, sanitize logs
|
|
|
|
**Checkpoint**: MVP complete - REST API for cross-switching with authentication
|
|
|
|
---
|
|
|
|
## Phase 9: Future - GeViSet Configuration Management (Phase 2)
|
|
|
|
**Purpose**: GeViSet-like functionality via API (action mapping configuration)
|
|
|
|
**Note**: These tasks will be detailed after MVP is complete and working
|
|
|
|
### High-Level Tasks:
|
|
|
|
- [ ] T085 Research GeViSet configuration file format and action mapping structure
|
|
- [ ] T086 Implement GET /api/v1/config/actions to retrieve action mappings from GeViServer
|
|
- [ ] T087 Implement PUT /api/v1/config/actions to push action mappings to GeViServer
|
|
- [ ] T088 Implement POST /api/v1/config/actions/export to export configuration to CSV
|
|
- [ ] T089 Implement POST /api/v1/config/actions/import to import configuration from CSV
|
|
- [ ] T090 Add validation for action mapping syntax and constraints
|
|
- [ ] T091 Add versioning for configuration changes (track who changed what, when)
|
|
- [ ] T092 Add backup/restore functionality for configurations
|
|
|
|
**Checkpoint**: GeViSet configuration management available via API
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
```
|
|
Phase 1 (Setup)
|
|
↓
|
|
Phase 2 (SDK Bridge Foundation) ← BLOCKS all Python API work
|
|
↓
|
|
Phase 3 (Python API Foundation) ← BLOCKS all feature work
|
|
↓
|
|
Phase 4 (Authentication) ← BLOCKS all protected endpoints
|
|
↓
|
|
Phases 5, 6, 7 can proceed in parallel (after Phase 4)
|
|
↓
|
|
Phase 8 (Polish & Documentation)
|
|
↓
|
|
Phase 9 (Future - GeViSet config) ← After MVP validated
|
|
```
|
|
|
|
### Critical Path (Sequential)
|
|
|
|
1. Setup → SDK Bridge → Python API → Authentication
|
|
2. Then parallel: Camera Discovery + Monitor Discovery + Cross-Switching
|
|
3. Then: Polish & Documentation
|
|
4. Finally: GeViSet configuration (Phase 2)
|
|
|
|
### Parallel Opportunities
|
|
|
|
- Phase 2: T020 (ErrorTranslator) parallel with T017-T019 (StateQuery implementation)
|
|
- Phase 3: T033-T034, T036-T037 can run in parallel
|
|
- Phase 4: T039-T041 tests can run in parallel
|
|
- Phase 5-7: These entire phases can run in parallel after Phase 4 completes
|
|
- Phase 8: T075-T082 can run in parallel
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### Week 1: Foundation
|
|
- Days 1-2: Phase 1 (Setup)
|
|
- Days 3-5: Phase 2 (SDK Bridge)
|
|
|
|
### Week 2: API Core
|
|
- Days 1-3: Phase 3 (Python API Foundation)
|
|
- Days 4-5: Phase 4 (Authentication)
|
|
|
|
### Week 3: Cross-Switching
|
|
- Days 1-2: Phase 5 (Camera Discovery)
|
|
- Days 2-3: Phase 6 (Monitor Discovery)
|
|
- Days 4-5: Phase 7 (Cross-Switching Operations)
|
|
|
|
### Week 4: Polish & Validation
|
|
- Days 1-3: Phase 8 (Polish, Documentation)
|
|
- Days 4-5: Integration testing with real GeViServer, bug fixes
|
|
|
|
**MVP Delivery**: End of Week 4
|
|
|
|
### Week 5+: Phase 2 Features
|
|
- GeViSet configuration management
|
|
- Action mapping CRUD
|
|
- CSV import/export
|
|
|
|
---
|
|
|
|
## Task Summary
|
|
|
|
**MVP Total**: 84 tasks
|
|
|
|
**By Phase**:
|
|
- Phase 1 (Setup): 10 tasks
|
|
- Phase 2 (SDK Bridge): 16 tasks
|
|
- Phase 3 (API Foundation): 12 tasks
|
|
- Phase 4 (Authentication): 10 tasks
|
|
- Phase 5 (Camera Discovery): 7 tasks
|
|
- Phase 6 (Monitor Discovery): 7 tasks
|
|
- Phase 7 (Cross-Switching): 12 tasks
|
|
- Phase 8 (Polish): 10 tasks
|
|
|
|
**Phase 2 (Future)**: 8+ tasks (detailed after MVP)
|
|
|
|
**Tests**: 12 test tasks (TDD approach)
|
|
**Parallel Tasks**: 20+ tasks marked [P]
|
|
|
|
**Estimated Timeline**:
|
|
- MVP: 3-4 weeks (1 developer, focused work)
|
|
- Phase 2 (GeViSet config): +1-2 weeks
|
|
|
|
---
|
|
|
|
## MVP Endpoints Summary
|
|
|
|
```
|
|
# Authentication
|
|
POST /api/v1/auth/login # Get JWT token
|
|
POST /api/v1/auth/logout # Invalidate token
|
|
|
|
# Cameras
|
|
GET /api/v1/cameras # List all cameras
|
|
|
|
# Monitors
|
|
GET /api/v1/monitors # List all monitors/viewers
|
|
|
|
# Cross-Switching
|
|
POST /api/v1/crossswitch # Execute cross-switch
|
|
Body: { camera_id: 7, monitor_id: 3, mode: 0 }
|
|
|
|
DELETE /api/v1/monitors/{id} # Clear monitor (stop video)
|
|
|
|
GET /api/v1/routing/state # Get current routing state
|
|
|
|
# System
|
|
GET /api/v1/health # Health check (SDK Bridge, DB, Redis)
|
|
GET /metrics # Prometheus metrics
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Strategy
|
|
|
|
### TDD Approach
|
|
1. Write contract test (should FAIL)
|
|
2. Write unit tests (should FAIL)
|
|
3. Implement feature
|
|
4. Run tests (should PASS)
|
|
5. Refactor if needed
|
|
6. Commit
|
|
|
|
### Test Coverage Goal
|
|
- Minimum 70% coverage for MVP
|
|
- 100% coverage for authentication and cross-switching logic
|
|
|
|
### Manual Testing
|
|
- Test with Postman collection
|
|
- Test with curl commands
|
|
- Integration test with actual GeViServer
|
|
|
|
---
|
|
|
|
**Generated**: 2025-12-08
|
|
**Updated**: 2025-12-16 (Configuration Management implemented)
|
|
**Scope**: Cross-switching MVP with authentication + GeViSet configuration management ✅
|
|
**Architecture**: Python FastAPI + C# gRPC Bridge + GeViScope SDK
|
|
|
|
---
|
|
|
|
## UPDATE: Configuration Management (2025-12-16) ✅ COMPLETED
|
|
|
|
**Status**: Phase 9 (GeViSet Configuration Management) has been implemented ahead of schedule
|
|
|
|
**Implemented Features**:
|
|
- ✅ G-Core Server CRUD operations (CREATE, READ, DELETE working; UPDATE has known bug)
|
|
- ✅ Action Mapping CRUD operations (all CRUD operations working)
|
|
- ✅ SetupClient integration for configuration file operations
|
|
- ✅ Configuration tree parsing and navigation
|
|
- ✅ Critical bug fixes (cascade deletion prevention)
|
|
|
|
**API Endpoints Added**:
|
|
- `GET/POST/PUT/DELETE /api/v1/configuration/servers` - G-Core server management
|
|
- `GET/POST/PUT/DELETE /api/v1/configuration/action-mappings` - Action mapping management
|
|
|
|
**Documentation**:
|
|
- [SERVER_CRUD_IMPLEMENTATION.md](../../SERVER_CRUD_IMPLEMENTATION.md)
|
|
- [CRITICAL_BUG_FIX_DELETE.md](../../CRITICAL_BUG_FIX_DELETE.md)
|
|
|
|
See Phase 9 section below for original planned tasks.
|
|
|
|
---
|