14893e62a5
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>
553 lines
14 KiB
Markdown
553 lines
14 KiB
Markdown
# 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
|