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
583
geutebruck-api/specs/001-flutter-app/quickstart.md
Normal file
583
geutebruck-api/specs/001-flutter-app/quickstart.md
Normal file
@@ -0,0 +1,583 @@
|
||||
# Geutebruck API Flutter App - Quick Start Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following installed:
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **Flutter SDK 3.24+**
|
||||
- Download from: https://flutter.dev/docs/get-started/install
|
||||
- Add to PATH: `C:\Users\{username}\develop\flutter\bin`
|
||||
|
||||
2. **Git for Windows**
|
||||
- Download from: https://git-scm.com/downloads/win
|
||||
|
||||
3. **Code Editor**
|
||||
- Recommended: Visual Studio Code with Flutter extension
|
||||
- Alternative: Android Studio
|
||||
|
||||
### Platform-Specific Requirements
|
||||
|
||||
#### For Android Development
|
||||
|
||||
1. **Android Studio**
|
||||
- Download from: https://developer.android.com/studio
|
||||
- Install Android SDK
|
||||
- Install Android SDK Build-Tools
|
||||
- Install Android Emulator
|
||||
|
||||
2. **Java JDK 11+**
|
||||
- Download from: https://www.oracle.com/java/technologies/downloads/
|
||||
|
||||
#### For iOS Development (macOS only)
|
||||
|
||||
1. **Xcode 14+**
|
||||
- Download from Mac App Store
|
||||
- Install Xcode Command Line Tools
|
||||
|
||||
2. **CocoaPods**
|
||||
```bash
|
||||
sudo gem install cocoapods
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Verify Flutter Installation
|
||||
|
||||
```bash
|
||||
flutter doctor
|
||||
```
|
||||
|
||||
Expected output should show checkmarks for:
|
||||
- Flutter (Channel stable)
|
||||
- Android toolchain
|
||||
- Chrome (for web development)
|
||||
- Visual Studio Code
|
||||
- Connected device
|
||||
|
||||
### 2. Clone the Repository
|
||||
|
||||
```bash
|
||||
cd C:\DEV\COPILOT
|
||||
git clone <repository-url> geutebruck_app
|
||||
cd geutebruck_app
|
||||
```
|
||||
|
||||
### 3. Install Dependencies
|
||||
|
||||
```bash
|
||||
flutter pub get
|
||||
```
|
||||
|
||||
### 4. Generate Code
|
||||
|
||||
The app uses code generation for models, BLoCs, and dependency injection:
|
||||
|
||||
```bash
|
||||
flutter pub run build_runner build --delete-conflicting-outputs
|
||||
```
|
||||
|
||||
For continuous code generation during development:
|
||||
|
||||
```bash
|
||||
flutter pub run build_runner watch --delete-conflicting-outputs
|
||||
```
|
||||
|
||||
### 5. Configure API Endpoint
|
||||
|
||||
Edit the API configuration file:
|
||||
|
||||
**File:** `lib/core/constants/api_constants.dart`
|
||||
|
||||
```dart
|
||||
class ApiConstants {
|
||||
static const String baseUrl = 'http://localhost:8000'; // Change to your API URL
|
||||
static const Duration timeout = Duration(seconds: 30);
|
||||
}
|
||||
```
|
||||
|
||||
## Running the App
|
||||
|
||||
### On Android Emulator
|
||||
|
||||
1. Start Android emulator:
|
||||
```bash
|
||||
flutter emulators --launch <emulator_id>
|
||||
```
|
||||
|
||||
2. Run the app:
|
||||
```bash
|
||||
flutter run
|
||||
```
|
||||
|
||||
### On iOS Simulator (macOS only)
|
||||
|
||||
1. Start iOS simulator:
|
||||
```bash
|
||||
open -a Simulator
|
||||
```
|
||||
|
||||
2. Run the app:
|
||||
```bash
|
||||
flutter run
|
||||
```
|
||||
|
||||
### On Physical Device
|
||||
|
||||
1. Enable USB debugging on your device (Android)
|
||||
- Settings → About Phone → Tap Build Number 7 times
|
||||
- Settings → Developer Options → Enable USB Debugging
|
||||
|
||||
2. Connect device via USB
|
||||
|
||||
3. Verify device is detected:
|
||||
```bash
|
||||
flutter devices
|
||||
```
|
||||
|
||||
4. Run the app:
|
||||
```bash
|
||||
flutter run
|
||||
```
|
||||
|
||||
### Hot Reload During Development
|
||||
|
||||
While the app is running:
|
||||
- Press `r` to hot reload
|
||||
- Press `R` to hot restart
|
||||
- Press `q` to quit
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Feature Development
|
||||
|
||||
Follow this workflow for each feature:
|
||||
|
||||
1. **Write Tests First (TDD)**
|
||||
```bash
|
||||
# Create test file
|
||||
test/domain/use_cases/servers/get_servers_test.dart
|
||||
|
||||
# Run test (will fail)
|
||||
flutter test test/domain/use_cases/servers/get_servers_test.dart
|
||||
|
||||
# Implement feature
|
||||
lib/domain/use_cases/servers/get_servers.dart
|
||||
|
||||
# Run test (should pass)
|
||||
flutter test test/domain/use_cases/servers/get_servers_test.dart
|
||||
```
|
||||
|
||||
2. **Generate Code**
|
||||
```bash
|
||||
flutter pub run build_runner build
|
||||
```
|
||||
|
||||
3. **Run App**
|
||||
```bash
|
||||
flutter run
|
||||
```
|
||||
|
||||
### 2. Code Generation
|
||||
|
||||
The app uses several code generators:
|
||||
|
||||
#### Freezed (Immutable Models)
|
||||
|
||||
```dart
|
||||
// Define model
|
||||
@freezed
|
||||
class Server with _$Server {
|
||||
const factory Server({
|
||||
required String id,
|
||||
required String alias,
|
||||
}) = _Server;
|
||||
|
||||
factory Server.fromJson(Map<String, dynamic> json) =>
|
||||
_$ServerFromJson(json);
|
||||
}
|
||||
|
||||
// Generate with:
|
||||
flutter pub run build_runner build
|
||||
```
|
||||
|
||||
#### Injectable (Dependency Injection)
|
||||
|
||||
```dart
|
||||
// Annotate class
|
||||
@injectable
|
||||
class ServerRepository {
|
||||
final ServerRemoteDataSource remoteDataSource;
|
||||
|
||||
ServerRepository(this.remoteDataSource);
|
||||
}
|
||||
|
||||
// Register in injection.dart:
|
||||
@InjectableInit()
|
||||
void configureDependencies() => getIt.init();
|
||||
|
||||
// Generate with:
|
||||
flutter pub run build_runner build
|
||||
```
|
||||
|
||||
### 3. Testing
|
||||
|
||||
#### Run All Tests
|
||||
|
||||
```bash
|
||||
flutter test
|
||||
```
|
||||
|
||||
#### Run Specific Test File
|
||||
|
||||
```bash
|
||||
flutter test test/domain/use_cases/servers/get_servers_test.dart
|
||||
```
|
||||
|
||||
#### Run Tests with Coverage
|
||||
|
||||
```bash
|
||||
flutter test --coverage
|
||||
```
|
||||
|
||||
View coverage report:
|
||||
```bash
|
||||
genhtml coverage/lcov.info -o coverage/html
|
||||
open coverage/html/index.html
|
||||
```
|
||||
|
||||
#### Widget Tests
|
||||
|
||||
```dart
|
||||
testWidgets('ServerListScreen displays servers', (tester) async {
|
||||
await tester.pumpWidget(
|
||||
MaterialApp(home: ServerListScreen()),
|
||||
);
|
||||
|
||||
expect(find.text('Servers'), findsOneWidget);
|
||||
});
|
||||
```
|
||||
|
||||
#### Integration Tests
|
||||
|
||||
```bash
|
||||
flutter test integration_test/app_test.dart
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
lib/
|
||||
├── core/ # Core utilities and configurations
|
||||
│ ├── constants/
|
||||
│ ├── errors/
|
||||
│ ├── network/
|
||||
│ └── theme/
|
||||
├── data/ # Data layer
|
||||
│ ├── models/ # JSON serializable models
|
||||
│ ├── repositories/ # Repository implementations
|
||||
│ └── data_sources/ # Remote and local data sources
|
||||
├── domain/ # Domain layer
|
||||
│ ├── entities/ # Business entities
|
||||
│ ├── repositories/ # Repository interfaces
|
||||
│ └── use_cases/ # Business logic
|
||||
├── presentation/ # Presentation layer
|
||||
│ ├── blocs/ # BLoC state management
|
||||
│ ├── screens/ # Full-page screens
|
||||
│ └── widgets/ # Reusable widgets
|
||||
├── injection.dart # Dependency injection setup
|
||||
└── main.dart # App entry point
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Run app in debug mode
|
||||
flutter run
|
||||
|
||||
# Run app in profile mode (for performance testing)
|
||||
flutter run --profile
|
||||
|
||||
# Run app in release mode
|
||||
flutter run --release
|
||||
|
||||
# Clean build artifacts
|
||||
flutter clean
|
||||
|
||||
# Update dependencies
|
||||
flutter pub upgrade
|
||||
|
||||
# Check for outdated packages
|
||||
flutter pub outdated
|
||||
|
||||
# Analyze code
|
||||
flutter analyze
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Build Android APK
|
||||
flutter build apk --release
|
||||
|
||||
# Build Android App Bundle (for Play Store)
|
||||
flutter build appbundle --release
|
||||
|
||||
# Build iOS (macOS only)
|
||||
flutter build ipa --release
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
```bash
|
||||
# Run with DevTools
|
||||
flutter run --devtools
|
||||
|
||||
# Attach debugger to running app
|
||||
flutter attach
|
||||
|
||||
# Get device logs
|
||||
flutter logs
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Development Environment
|
||||
|
||||
**File:** `lib/core/config/env_config.dart`
|
||||
|
||||
```dart
|
||||
enum Environment { development, staging, production }
|
||||
|
||||
class EnvConfig {
|
||||
static Environment currentEnv = Environment.development;
|
||||
|
||||
static String get apiBaseUrl {
|
||||
switch (currentEnv) {
|
||||
case Environment.development:
|
||||
return 'http://localhost:8000';
|
||||
case Environment.staging:
|
||||
return 'https://staging-api.geutebruck.com';
|
||||
case Environment.production:
|
||||
return 'https://api.geutebruck.com';
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Switch environments:
|
||||
|
||||
```dart
|
||||
// In main.dart
|
||||
void main() {
|
||||
EnvConfig.currentEnv = Environment.production;
|
||||
runApp(MyApp());
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Flutter Doctor Issues
|
||||
|
||||
```bash
|
||||
flutter doctor -v
|
||||
```
|
||||
|
||||
Common fixes:
|
||||
- **Android license not accepted**: `flutter doctor --android-licenses`
|
||||
- **Xcode not configured**: `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
|
||||
|
||||
### Build Runner Issues
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
flutter clean
|
||||
flutter pub get
|
||||
flutter pub run build_runner clean
|
||||
flutter pub run build_runner build --delete-conflicting-outputs
|
||||
```
|
||||
|
||||
### Dependency Conflicts
|
||||
|
||||
```bash
|
||||
# Clear pub cache
|
||||
flutter pub cache repair
|
||||
|
||||
# Clean and reinstall
|
||||
flutter clean
|
||||
rm pubspec.lock
|
||||
flutter pub get
|
||||
```
|
||||
|
||||
### Hot Reload Not Working
|
||||
|
||||
- Try hot restart (press `R`)
|
||||
- Check for syntax errors
|
||||
- Some changes require full restart (native code, assets)
|
||||
|
||||
### Emulator Performance
|
||||
|
||||
For better Android emulator performance:
|
||||
1. Enable hardware acceleration (Intel HAXM or AMD Hypervisor)
|
||||
2. Allocate more RAM to emulator (4GB+)
|
||||
3. Use x86/x64 system images (not ARM)
|
||||
|
||||
## IDE Setup
|
||||
|
||||
### Visual Studio Code
|
||||
|
||||
Install extensions:
|
||||
1. Flutter
|
||||
2. Dart
|
||||
3. Flutter Intl (for internationalization)
|
||||
4. Error Lens
|
||||
5. GitLens
|
||||
|
||||
**Settings (.vscode/settings.json):**
|
||||
|
||||
```json
|
||||
{
|
||||
"dart.lineLength": 120,
|
||||
"editor.formatOnSave": true,
|
||||
"dart.debugExternalPackageLibraries": false,
|
||||
"dart.debugSdkLibraries": false,
|
||||
"[dart]": {
|
||||
"editor.formatOnSave": true,
|
||||
"editor.formatOnType": true,
|
||||
"editor.rulers": [120],
|
||||
"editor.selectionHighlight": false,
|
||||
"editor.suggest.snippetsPreventQuickSuggestions": false,
|
||||
"editor.suggestSelection": "first",
|
||||
"editor.tabCompletion": "onlySnippets",
|
||||
"editor.wordBasedSuggestions": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Android Studio
|
||||
|
||||
Install plugins:
|
||||
1. Flutter
|
||||
2. Dart
|
||||
|
||||
Configure:
|
||||
- File → Settings → Languages & Frameworks → Flutter
|
||||
- Set Flutter SDK path
|
||||
|
||||
## API Testing
|
||||
|
||||
Before running the app, ensure the backend API is running:
|
||||
|
||||
```bash
|
||||
# Start API server
|
||||
cd C:\DEV\COPILOT\geutebruck-api
|
||||
python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000
|
||||
|
||||
# Verify API is accessible
|
||||
curl http://localhost:8000/api/v1/health
|
||||
```
|
||||
|
||||
Test authentication:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"admin123"}'
|
||||
```
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
**File:** `.github/workflows/flutter.yml`
|
||||
|
||||
```yaml
|
||||
name: Flutter CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main, develop ]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Setup Flutter
|
||||
uses: subosito/flutter-action@v2
|
||||
with:
|
||||
flutter-version: '3.24.0'
|
||||
channel: 'stable'
|
||||
|
||||
- name: Install dependencies
|
||||
run: flutter pub get
|
||||
|
||||
- name: Generate code
|
||||
run: flutter pub run build_runner build --delete-conflicting-outputs
|
||||
|
||||
- name: Analyze
|
||||
run: flutter analyze
|
||||
|
||||
- name: Run tests
|
||||
run: flutter test --coverage
|
||||
|
||||
- name: Upload coverage
|
||||
uses: codecov/codecov-action@v3
|
||||
with:
|
||||
files: ./coverage/lcov.info
|
||||
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
needs: test
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Setup Flutter
|
||||
uses: subosito/flutter-action@v2
|
||||
|
||||
- name: Build APK
|
||||
run: flutter build apk --release
|
||||
|
||||
- name: Upload APK
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: app-release.apk
|
||||
path: build/app/outputs/flutter-apk/app-release.apk
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review Specifications**
|
||||
- Read `constitution.md` for coding standards
|
||||
- Review `spec.md` for user stories
|
||||
- Study `plan.md` for architecture
|
||||
|
||||
2. **Start Development**
|
||||
- Begin with Phase 1 tasks in `tasks.md`
|
||||
- Follow TDD approach (tests first)
|
||||
- Use code generation for models and DI
|
||||
|
||||
3. **Join the Team**
|
||||
- Set up development environment
|
||||
- Clone repository
|
||||
- Create feature branch
|
||||
- Start with assigned tasks
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Check Flutter documentation: https://flutter.dev/docs
|
||||
- BLoC documentation: https://bloclibrary.dev
|
||||
- Project-specific questions: See team lead
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding! 🚀**
|
||||
Reference in New Issue
Block a user