COLSYS/geutebruck
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
geutebruck/geutebruck-api/specs/001-flutter-app/spec.md
Administrator 14893e62a5 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>
2025-12-31 18:10:54 +01:00

14 KiB
Raw Permalink Blame History

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