# 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