feat: Geutebruck GeViScope/GeViSoft Action Mapping System - MVP
This MVP release provides a complete full-stack solution for managing action mappings in Geutebruck's GeViScope and GeViSoft video surveillance systems. ## Features ### Flutter Web Application (Port 8081) - Modern, responsive UI for managing action mappings - Action picker dialog with full parameter configuration - Support for both GSC (GeViScope) and G-Core server actions - Consistent UI for input and output actions with edit/delete capabilities - Real-time action mapping creation, editing, and deletion - Server categorization (GSC: prefix for GeViScope, G-Core: prefix for G-Core servers) ### FastAPI REST Backend (Port 8000) - RESTful API for action mapping CRUD operations - Action template service with comprehensive action catalog (247 actions) - Server management (G-Core and GeViScope servers) - Configuration tree reading and writing - JWT authentication with role-based access control - PostgreSQL database integration ### C# SDK Bridge (gRPC, Port 50051) - Native integration with GeViSoft SDK (GeViProcAPINET_4_0.dll) - Action mapping creation with correct binary format - Support for GSC and G-Core action types - Proper Camera parameter inclusion in action strings (fixes CrossSwitch bug) - Action ID lookup table with server-specific action IDs - Configuration reading/writing via SetupClient ## Bug Fixes - **CrossSwitch Bug**: GSC and G-Core actions now correctly display camera/PTZ head parameters in GeViSet - Action strings now include Camera parameter: `@ PanLeft (Comment: "", Camera: 101028)` - Proper filter flags and VideoInput=0 for action mappings - Correct action ID assignment (4198 for GSC, 9294 for G-Core PanLeft) ## Technical Stack - **Frontend**: Flutter Web, Dart, Dio HTTP client - **Backend**: Python FastAPI, PostgreSQL, Redis - **SDK Bridge**: C# .NET 8.0, gRPC, GeViSoft SDK - **Authentication**: JWT tokens - **Configuration**: GeViSoft .set files (binary format) ## Credentials - GeViSoft/GeViScope: username=sysadmin, password=masterkey - Default admin: username=admin, password=admin123 ## Deployment All services run on localhost: - Flutter Web: http://localhost:8081 - FastAPI: http://localhost:8000 - SDK Bridge gRPC: localhost:50051 - GeViServer: localhost (default port) Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Administrator
552
geutebruck-api/specs/001-flutter-app/spec.md
Normal file
552
geutebruck-api/specs/001-flutter-app/spec.md
Normal file
@@ -0,0 +1,552 @@
|
||||
# Geutebruck API Flutter App - Functional Specification
|
||||
|
||||
## Overview
|
||||
|
||||
A mobile application for managing Geutebruck video surveillance systems through the REST API. The app provides administrators with full control over server configurations, action mappings, cameras, monitors, and cross-switching operations.
|
||||
|
||||
## Target Users
|
||||
|
||||
- **System Administrators**: Configure and manage Geutebruck servers
|
||||
- **Security Operators**: Monitor and control video surveillance systems
|
||||
- **Technicians**: Set up action mappings and camera configurations
|
||||
|
||||
## User Stories
|
||||
|
||||
### Epic 1: Authentication & Authorization
|
||||
|
||||
#### US-1.1: User Login
|
||||
**As a** system administrator
|
||||
**I want to** log in with my username and password
|
||||
**So that** I can securely access the system
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Login screen with username and password fields
|
||||
- Secure credential storage using flutter_secure_storage
|
||||
- JWT token received and stored on successful authentication
|
||||
- Error message displayed for invalid credentials
|
||||
- "Remember me" option to persist login
|
||||
- Password visibility toggle
|
||||
- Loading indicator during authentication
|
||||
|
||||
**API Endpoint:** `POST /api/v1/auth/login`
|
||||
|
||||
---
|
||||
|
||||
#### US-1.2: Automatic Token Refresh
|
||||
**As a** logged-in user
|
||||
**I want** my session to remain active without re-logging in
|
||||
**So that** I don't lose access during normal usage
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Access token automatically refreshed before expiration
|
||||
- Refresh token used to obtain new access token
|
||||
- User redirected to login if refresh fails
|
||||
- Silent refresh (no UI disruption)
|
||||
|
||||
**API Endpoint:** `POST /api/v1/auth/refresh`
|
||||
|
||||
---
|
||||
|
||||
#### US-1.3: User Logout
|
||||
**As a** logged-in user
|
||||
**I want to** log out of the application
|
||||
**So that** I can secure my session when done
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Logout button in app drawer/menu
|
||||
- All tokens cleared from secure storage
|
||||
- User redirected to login screen
|
||||
- Confirmation dialog before logout
|
||||
|
||||
---
|
||||
|
||||
### Epic 2: Server Management
|
||||
|
||||
#### US-2.1: View All Servers
|
||||
**As a** system administrator
|
||||
**I want to** see a list of all configured servers (G-Core and GeViScope)
|
||||
**So that** I can manage my infrastructure
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Combined list showing both G-Core and GeViScope servers
|
||||
- Display: alias, host, type (G-Core/GeViScope), enabled status
|
||||
- Search/filter by alias or host
|
||||
- Pull-to-refresh to update list
|
||||
- Server count displayed (total, G-Core, GeViScope)
|
||||
- Visual indicator for enabled/disabled servers
|
||||
- Tap to view details
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/servers`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.2: View G-Core Servers
|
||||
**As a** system administrator
|
||||
**I want to** view only G-Core servers
|
||||
**So that** I can focus on G-Core management
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Filtered list showing only G-Core servers
|
||||
- Display: ID, alias, host, user, enabled status
|
||||
- Search and filter capabilities
|
||||
- Sort by ID, alias, or host
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/servers/gcore`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.3: View GeViScope Servers
|
||||
**As a** system administrator
|
||||
**I want to** view only GeViScope servers
|
||||
**So that** I can focus on GeViScope management
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Filtered list showing only GeViScope servers
|
||||
- Display: ID, alias, host, user, enabled status, dialup settings
|
||||
- Search and filter capabilities
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/servers/geviscope`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.4: View Server Details
|
||||
**As a** system administrator
|
||||
**I want to** view detailed information about a specific server
|
||||
**So that** I can review its configuration
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- All server properties displayed
|
||||
- Connection status indicator
|
||||
- Edit button to modify settings
|
||||
- Delete button to remove server
|
||||
- Test connection button
|
||||
|
||||
**API Endpoints:**
|
||||
- `GET /api/v1/configuration/servers/gcore/{id}`
|
||||
- `GET /api/v1/configuration/servers/geviscope/{id}`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.5: Create G-Core Server
|
||||
**As a** system administrator
|
||||
**I want to** add a new G-Core server
|
||||
**So that** I can expand my managed infrastructure
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Form with fields: alias, host, user, password
|
||||
- Optional fields: enabled, deactivate_echo, deactivate_live_check
|
||||
- Input validation (required fields, valid IP/hostname)
|
||||
- Server ID auto-generated
|
||||
- Success/error feedback
|
||||
- Return to server list on success
|
||||
|
||||
**API Endpoint:** `POST /api/v1/configuration/servers/gcore`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.6: Create GeViScope Server
|
||||
**As a** system administrator
|
||||
**I want to** add a new GeViScope server
|
||||
**So that** I can manage GeViScope systems
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Form with standard fields plus dialup settings
|
||||
- All dialup configuration options available
|
||||
- Input validation
|
||||
- Success/error feedback
|
||||
|
||||
**API Endpoint:** `POST /api/v1/configuration/servers/geviscope`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.7: Update Server
|
||||
**As a** system administrator
|
||||
**I want to** modify an existing server's configuration
|
||||
**So that** I can keep settings current
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Pre-populated form with current values
|
||||
- Editable fields (except ID)
|
||||
- Validation before saving
|
||||
- Confirmation dialog for changes
|
||||
- Success/error feedback
|
||||
|
||||
**API Endpoints:**
|
||||
- `PUT /api/v1/configuration/servers/gcore/{id}`
|
||||
- `PUT /api/v1/configuration/servers/geviscope/{id}`
|
||||
|
||||
---
|
||||
|
||||
#### US-2.8: Delete Server
|
||||
**As a** system administrator
|
||||
**I want to** remove a server from the system
|
||||
**So that** I can clean up unused configurations
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Delete button with confirmation dialog
|
||||
- Warning message about permanent deletion
|
||||
- Success feedback
|
||||
- Return to server list
|
||||
- Server removed from list immediately
|
||||
|
||||
**API Endpoints:**
|
||||
- `DELETE /api/v1/configuration/servers/gcore/{id}`
|
||||
- `DELETE /api/v1/configuration/servers/geviscope/{id}`
|
||||
|
||||
---
|
||||
|
||||
### Epic 3: Action Mapping Management
|
||||
|
||||
#### US-3.1: View Action Mappings
|
||||
**As a** system administrator
|
||||
**I want to** see all configured action mappings
|
||||
**So that** I can understand the automation rules
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- List of all action mappings with caption, ID
|
||||
- Display input action parameters
|
||||
- Display output action count
|
||||
- Search by caption
|
||||
- Pull-to-refresh
|
||||
- Tap to view details
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/action-mappings`
|
||||
|
||||
---
|
||||
|
||||
#### US-3.2: View Action Mapping Details
|
||||
**As a** system administrator
|
||||
**I want to** see detailed information about an action mapping
|
||||
**So that** I can understand its configuration
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Display mapping caption and ID
|
||||
- List all input action parameters with values
|
||||
- List all output actions with:
|
||||
- Action name
|
||||
- Caption
|
||||
- Server
|
||||
- Parameters
|
||||
- Edit and delete buttons
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/action-mappings/{id}`
|
||||
|
||||
---
|
||||
|
||||
#### US-3.3: Create Action Mapping
|
||||
**As a** system administrator
|
||||
**I want to** create a new action mapping
|
||||
**So that** I can automate system responses
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Form with mapping caption
|
||||
- Dynamic input parameter builder
|
||||
- Output action builder with:
|
||||
- Action dropdown (GscAction/GCoreAction)
|
||||
- Server selection
|
||||
- Parameter configuration
|
||||
- PTZ head selection for camera actions
|
||||
- Add multiple output actions
|
||||
- Validation of all fields
|
||||
- Success/error feedback
|
||||
|
||||
**API Endpoint:** `POST /api/v1/configuration/action-mappings`
|
||||
|
||||
---
|
||||
|
||||
#### US-3.4: Update Action Mapping
|
||||
**As a** system administrator
|
||||
**I want to** modify an existing action mapping
|
||||
**So that** I can adjust automation rules
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Pre-populated form with current values
|
||||
- Edit caption, input parameters, output actions
|
||||
- Add/remove output actions
|
||||
- Validation
|
||||
- Success/error feedback
|
||||
|
||||
**API Endpoint:** `PUT /api/v1/configuration/action-mappings/{id}`
|
||||
|
||||
---
|
||||
|
||||
#### US-3.5: Delete Action Mapping
|
||||
**As a** system administrator
|
||||
**I want to** remove an action mapping
|
||||
**So that** I can clean up unused automations
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Delete button with confirmation
|
||||
- Warning about permanent deletion
|
||||
- Success feedback
|
||||
- Removed from list immediately
|
||||
|
||||
**API Endpoint:** `DELETE /api/v1/configuration/action-mappings/{id}`
|
||||
|
||||
---
|
||||
|
||||
### Epic 4: Camera Management
|
||||
|
||||
#### US-4.1: View Camera List
|
||||
**As a** security operator
|
||||
**I want to** see all available cameras
|
||||
**So that** I can select cameras for viewing or control
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- List of all cameras with ID and name
|
||||
- Visual indicator for online/offline status
|
||||
- Search by camera name
|
||||
- Filter by status
|
||||
- Pull-to-refresh
|
||||
|
||||
**API Endpoint:** `GET /api/v1/cameras`
|
||||
|
||||
---
|
||||
|
||||
#### US-4.2: View Camera Details
|
||||
**As a** security operator
|
||||
**I want to** see detailed camera information
|
||||
**So that** I can understand its configuration
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Camera ID, name, description
|
||||
- Connection status
|
||||
- Server assignment
|
||||
- PTZ capabilities indicator
|
||||
- Quick action buttons (if PTZ supported)
|
||||
|
||||
**API Endpoint:** `GET /api/v1/cameras/{id}`
|
||||
|
||||
---
|
||||
|
||||
#### US-4.3: Control PTZ Camera
|
||||
**As a** security operator
|
||||
**I want to** control PTZ camera movements
|
||||
**So that** I can direct camera focus
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- PTZ control pad (Pan Left/Right, Tilt Up/Down)
|
||||
- Zoom In/Out buttons
|
||||
- Focus Near/Far buttons
|
||||
- Stop button for all movements
|
||||
- Speed control slider
|
||||
- Preset position selector
|
||||
- Save preset button
|
||||
- Visual feedback during movement
|
||||
|
||||
**API Endpoints:**
|
||||
- Pan: Actions like PanLeft, PanRight, PanStop
|
||||
- Tilt: TiltUp, TiltDown
|
||||
- Zoom: ZoomIn, ZoomOut, ZoomStop
|
||||
- Focus: FocusNear, FocusFar, FocusStop
|
||||
- Presets: PrePosSave, PrePosCall
|
||||
|
||||
---
|
||||
|
||||
### Epic 5: Monitor Management
|
||||
|
||||
#### US-5.1: View Monitor List
|
||||
**As a** security operator
|
||||
**I want to** see all available monitors
|
||||
**So that** I can manage video displays
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- List of monitors with ID and description
|
||||
- Status indicator
|
||||
- Search and filter
|
||||
- Tap to view details
|
||||
|
||||
**API Endpoint:** `GET /api/v1/monitors`
|
||||
|
||||
---
|
||||
|
||||
#### US-5.2: View Monitor Details
|
||||
**As a** security operator
|
||||
**I want to** see monitor configuration details
|
||||
**So that** I can understand its setup
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Monitor ID, description, layout
|
||||
- Current camera assignments
|
||||
- Quick actions (clear, assign camera)
|
||||
|
||||
**API Endpoint:** `GET /api/v1/monitors/{id}`
|
||||
|
||||
---
|
||||
|
||||
### Epic 6: Cross-Switching
|
||||
|
||||
#### US-6.1: Assign Camera to Monitor
|
||||
**As a** security operator
|
||||
**I want to** connect a camera to a monitor
|
||||
**So that** I can view live video
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Camera selector (dropdown or search)
|
||||
- Monitor selector
|
||||
- Preview of current assignments
|
||||
- Connect button
|
||||
- Success/error feedback
|
||||
- Live video preview (optional)
|
||||
|
||||
**API Endpoint:** `POST /api/v1/crossswitch/connect`
|
||||
|
||||
---
|
||||
|
||||
#### US-6.2: Clear Monitor
|
||||
**As a** security operator
|
||||
**I want to** disconnect all cameras from a monitor
|
||||
**So that** I can reset the display
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Monitor selector
|
||||
- Confirmation dialog
|
||||
- Clear button
|
||||
- Success feedback
|
||||
|
||||
**API Endpoint:** `POST /api/v1/crossswitch/clear`
|
||||
|
||||
---
|
||||
|
||||
### Epic 7: Configuration Management
|
||||
|
||||
#### US-7.1: Export Configuration
|
||||
**As a** system administrator
|
||||
**I want to** export the complete system configuration
|
||||
**So that** I can back it up or migrate it
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Export button in settings
|
||||
- JSON format export
|
||||
- Save to device storage
|
||||
- Share option (email, cloud)
|
||||
- Export includes all servers, action mappings, etc.
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/export`
|
||||
|
||||
---
|
||||
|
||||
#### US-7.2: View Configuration Tree
|
||||
**As a** system administrator
|
||||
**I want to** browse the raw configuration structure
|
||||
**So that** I can troubleshoot or verify settings
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Expandable tree view
|
||||
- Search/filter nodes
|
||||
- Display node types and values
|
||||
- Read-only view
|
||||
|
||||
**API Endpoint:** `GET /api/v1/configuration/tree`
|
||||
|
||||
---
|
||||
|
||||
### Epic 8: User Interface & Navigation
|
||||
|
||||
#### US-8.1: App Navigation
|
||||
**As a** user
|
||||
**I want** intuitive navigation between app sections
|
||||
**So that** I can efficiently access features
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Bottom navigation bar with:
|
||||
- Servers
|
||||
- Action Mappings
|
||||
- Cameras
|
||||
- Monitors
|
||||
- Side drawer with:
|
||||
- Configuration
|
||||
- Settings
|
||||
- About
|
||||
- Logout
|
||||
- Back button support
|
||||
- Clear visual hierarchy
|
||||
|
||||
---
|
||||
|
||||
#### US-8.2: Settings Screen
|
||||
**As a** user
|
||||
**I want to** configure app preferences
|
||||
**So that** I can customize my experience
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- API base URL configuration
|
||||
- Theme selection (Light/Dark/System)
|
||||
- Language selection
|
||||
- Notification preferences
|
||||
- Cache management
|
||||
- About section with version info
|
||||
|
||||
---
|
||||
|
||||
#### US-8.3: Error Handling
|
||||
**As a** user
|
||||
**I want** clear error messages and recovery options
|
||||
**So that** I understand what went wrong and how to proceed
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Network error: Retry button, offline indicator
|
||||
- Authentication error: Redirect to login
|
||||
- Validation error: Field-specific messages
|
||||
- Server error: Error details with support contact
|
||||
- Snackbar notifications for temporary messages
|
||||
- Error logging for debugging
|
||||
|
||||
---
|
||||
|
||||
#### US-8.4: Loading States
|
||||
**As a** user
|
||||
**I want** visual feedback during operations
|
||||
**So that** I know the app is working
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Shimmer loading for lists
|
||||
- Progress indicators for long operations
|
||||
- Pull-to-refresh animation
|
||||
- Button loading state (disabled with spinner)
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
- App launch time: < 3 seconds on modern devices
|
||||
- List scrolling: 60 FPS
|
||||
- API response time: Visual feedback within 100ms
|
||||
- Image loading: Progressive rendering with placeholders
|
||||
|
||||
### Security
|
||||
- All data transmission over HTTPS
|
||||
- Tokens stored in secure storage
|
||||
- Auto-logout after 30 minutes of inactivity
|
||||
- No sensitive data in logs
|
||||
|
||||
### Compatibility
|
||||
- Android 8.0 (API level 26) and above
|
||||
- iOS 12.0 and above
|
||||
- Support for phones and tablets
|
||||
|
||||
### Accessibility
|
||||
- Screen reader support
|
||||
- Minimum touch target size: 48x48 dp
|
||||
- Contrast ratio: 4.5:1 for text
|
||||
- Semantic labels for all interactive elements
|
||||
|
||||
### Offline Support
|
||||
- Cache server lists, action mappings
|
||||
- Queue operations when offline
|
||||
- Sync when connection restored
|
||||
- Offline indicator in UI
|
||||
|
||||
## Review & Acceptance Checklist
|
||||
|
||||
- [ ] All user stories implemented with acceptance criteria met
|
||||
- [ ] Unit test coverage ≥ 80%
|
||||
- [ ] Widget tests for all screens
|
||||
- [ ] Integration tests for critical flows
|
||||
- [ ] API integration tested against live backend
|
||||
- [ ] Performance metrics validated
|
||||
- [ ] Security review completed
|
||||
- [ ] Accessibility tested with screen reader
|
||||
- [ ] User acceptance testing completed
|
||||
- [ ] Documentation updated
|
||||
Reference in New Issue
Block a user