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
305
geutebruck-api/docs/api-reference.md
Normal file
305
geutebruck-api/docs/api-reference.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Geutebruck Cross-Switching API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
REST API for Geutebruck GeViScope/GeViSoft cross-switching control. Route cameras to monitors via simple HTTP endpoints.
|
||||
|
||||
**Base URL**: `http://localhost:8000`
|
||||
**API Version**: 1.0.0
|
||||
**Authentication**: JWT Bearer tokens
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **Interactive Docs**: http://localhost:8000/docs (Swagger UI)
|
||||
- **Alternative Docs**: http://localhost:8000/redoc (ReDoc)
|
||||
- **Health Check**: http://localhost:8000/health
|
||||
- **Metrics**: http://localhost:8000/metrics
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### POST /api/v1/auth/login
|
||||
|
||||
Authenticate and receive JWT tokens.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 3600,
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"role": "administrator"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/logout
|
||||
|
||||
Logout (blacklist token).
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"message": "Successfully logged out"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/auth/me
|
||||
|
||||
Get current user information.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
|
||||
---
|
||||
|
||||
## Cameras
|
||||
|
||||
### GET /api/v1/cameras
|
||||
|
||||
List all cameras.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"cameras": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Entrance Camera",
|
||||
"description": "Main entrance",
|
||||
"has_ptz": true,
|
||||
"has_video_sensor": true,
|
||||
"status": "online"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/cameras/{camera_id}
|
||||
|
||||
Get camera details.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
---
|
||||
|
||||
## Monitors
|
||||
|
||||
### GET /api/v1/monitors
|
||||
|
||||
List all monitors.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"monitors": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Control Room Monitor 1",
|
||||
"description": "Main display",
|
||||
"status": "active",
|
||||
"current_camera_id": 5
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/monitors/filter/available
|
||||
|
||||
Get available (idle) monitors for cross-switching.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
---
|
||||
|
||||
## Cross-Switching (Core Functionality)
|
||||
|
||||
### POST /api/v1/crossswitch
|
||||
|
||||
**Execute cross-switch**: Route camera to monitor.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: **Operator+** (NOT Viewer)
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"mode": 0
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully switched camera 1 to monitor 1",
|
||||
"route": {
|
||||
"id": "uuid",
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"executed_at": "2025-12-09T12:00:00Z",
|
||||
"executed_by": "uuid",
|
||||
"executed_by_username": "operator",
|
||||
"is_active": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/crossswitch/clear
|
||||
|
||||
**Clear monitor**: Remove camera from monitor.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: **Operator+**
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"monitor_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully cleared monitor 1",
|
||||
"monitor_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/crossswitch/routing
|
||||
|
||||
Get current routing state (active camera-to-monitor mappings).
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"routes": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"executed_at": "2025-12-09T12:00:00Z",
|
||||
"executed_by_username": "operator",
|
||||
"is_active": true
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/crossswitch/history
|
||||
|
||||
Get routing history with pagination.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Query Parameters:**
|
||||
- `limit`: Max records (1-1000, default: 100)
|
||||
- `offset`: Skip records (default: 0)
|
||||
- `camera_id`: Filter by camera (optional)
|
||||
- `monitor_id`: Filter by monitor (optional)
|
||||
|
||||
---
|
||||
|
||||
## Authorization Roles
|
||||
|
||||
| Role | Cameras | Monitors | Cross-Switch | Clear Monitor | View Routing |
|
||||
|------|---------|----------|--------------|---------------|--------------|
|
||||
| **Viewer** | ✅ Read | ✅ Read | ❌ | ❌ | ✅ Read |
|
||||
| **Operator** | ✅ Read | ✅ Read | ✅ Execute | ✅ Execute | ✅ Read |
|
||||
| **Administrator** | ✅ Read | ✅ Read | ✅ Execute | ✅ Execute | ✅ Read |
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
### 401 Unauthorized
|
||||
```json
|
||||
{
|
||||
"error": "Unauthorized",
|
||||
"message": "Authentication required"
|
||||
}
|
||||
```
|
||||
|
||||
### 403 Forbidden
|
||||
```json
|
||||
{
|
||||
"error": "Forbidden",
|
||||
"message": "Requires operator role or higher"
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
```json
|
||||
{
|
||||
"error": "Not Found",
|
||||
"detail": "Camera with ID 999 not found"
|
||||
}
|
||||
```
|
||||
|
||||
### 500 Internal Server Error
|
||||
```json
|
||||
{
|
||||
"error": "Internal Server Error",
|
||||
"detail": "Cross-switch operation failed: SDK Bridge connection timeout"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Currently not implemented in MVP. Consider adding in production.
|
||||
|
||||
---
|
||||
|
||||
## Caching
|
||||
|
||||
- **Cameras**: Cached for 60 seconds in Redis
|
||||
- **Monitors**: Cached for 60 seconds in Redis
|
||||
- **Routing State**: Not cached (real-time from database)
|
||||
|
||||
Use `use_cache=false` query parameter to bypass cache.
|
||||
|
||||
---
|
||||
|
||||
## Audit Logging
|
||||
|
||||
All operations are logged to the `audit_logs` table:
|
||||
- Authentication attempts (success/failure)
|
||||
- Cross-switch executions
|
||||
- Monitor clear operations
|
||||
|
||||
Query audit logs via database or add dedicated endpoint in future.
|
||||
Reference in New Issue
Block a user