Web-Dashboard¶

Überblick¶

Das Web-Dashboard ist die zentrale Admin-Oberfläche für das Action-Connect-System. Es unterstützt die Überwachung und Steuerung registrierter Geräte sowie den Zugriff auf betriebsrelevante Bereiche wie Einstellungen, Logs und Benutzerverwaltung.

Technisch basiert das Projekt auf React, TypeScript und Vite. Die Oberfläche ist modular aufgebaut und kann um zusätzliche Seiten und Komponenten erweitert werden.

Lokales Setup¶

Die lokale Inbetriebnahme erfolgt in folgenden Schritten:

1. Repository öffnen: Admin-Dashboard/admin-dashboard
2. Abhängigkeiten installieren:

npm install

1. Umgebungsvariablen setzen:

copy .env.example .env

1. Dev-Server starten:

npm run dev

1. Funktionale Prüfung im Browser:

2. Dashboard: http://localhost:5173/

3. Geräte: http://localhost:5173/devices
4. Einstellungen (API-Key): http://localhost:5173/settings

Aufbau¶

Das Projekt folgt einer klaren Struktur:

• src/pages: fachliche Seiten (Dashboard, Geräte, Logs, Users, Settings)
• src/components: wiederverwendbare UI-Bausteine
• src/layout: Shell-Komponenten wie Sidebar und Header
• src/context: globaler Zustand (Theme, Sidebar, Toast)
• src/utils: API-Zugriff, API-Key-Hilfsfunktionen

Visuelle Struktur¶

flowchart TD
    APP[App Shell] --> SID[Sidebar]
    APP --> HDR[Header]
    APP --> PAGE[Pages]
    PAGE --> DEV[Devices]
    PAGE --> SET[Settings]
    PAGE --> LOG[Logs]
    PAGE --> USR[Users]
    PAGE --> DSH[Dashboard]
    PAGE --> CMP[Components]
    CMP --> API[Utils/API]

Wichtige Routen:

• / Dashboard
• /devices Geräteübersicht
• /devices/:uuid Gerätedetailansicht
• /settings API-Key und Systemeinstellungen
• /logs System-Logs
• /users Benutzerverwaltung

Technologie-Stack¶

• React 19
• TypeScript
• Vite
• Tailwind CSS
• React Router
• ApexCharts
• FullCalendar

Codebeispiele aus dem Projekt¶

1) Routing verstehen (src/App.tsx)¶

<Route element={<AppLayout />}>
    <Route index path="/" element={<Home />} />
    <Route path="/devices" element={<Devices />} />
    <Route path="/devices/:uuid" element={<DeviceDetail />} />
    <Route path="/settings" element={<Settings />} />
    <Route path="/logs" element={<Logs />} />
    <Route path="/users" element={<Users />} />
</Route>

Der Ausschnitt zeigt die fachlichen Kernseiten und den zentralen Erweiterungspunkt für neue Routen.

2) Geräte laden (src/utils/api.ts)¶

export async function fetchDevices(): Promise<Device[]> {
    const response = await fetch(`${API_BASE_URL}/api/v1/devices`, {
        method: "GET",
        headers: getHeaders(),
    });

    const result = await handleResponse<ApiResponse<Device[]> | Device[]>(
        response,
        "Geräte konnten nicht geladen werden"
    );

    const data = "data" in result && result.data ? result.data : result;
    return Array.isArray(data) ? data : [];
}

Hinweis: Das Backend kann Daten als { data: [...] } oder direkt als Array zurückgeben.

3) API-Key-Priorität (src/utils/apiKey.ts)¶

export function getApiKey(): string {
    const stored = localStorage.getItem("connecthub_api_key");
    if (stored) return stored;

    return import.meta.env.VITE_API_KEY ?? "";
}

Es gilt folgende Priorität: zuerst gespeicherter Browser-Key, danach .env-Fallback.

Geräte steuern¶

Die Steuerung erfolgt über die Backend-API. Für schreibende Aktionen wird ein gültiger x-api-key benötigt. Der Schlüssel kann über die Settings-Seite im Browser gespeichert werden und hat dann Vorrang gegenüber dem statischen .env-Wert.

Typische Endpunkte:

• GET /devices Geräteliste laden
• GET /devices/:uuid Gerätedetails laden
• GET /devices/:uuid/telemetry/latest letzte Telemetrie abrufen
• POST /devices/:uuid/command Kommando an ein Gerät senden

Ablauf: Gerätekommando¶

sequenceDiagram
    participant User as Admin im Dashboard
    participant UI as Geräte-Seite
    participant API as Backend API
    participant Dev as Gerät

    User->>UI: Aktion auslösen (z. B. Schalter)
    UI->>API: POST /devices/:uuid/command + x-api-key
    API->>Dev: Kommando weiterleiten
    Dev-->>API: Ausführung / Status
    API-->>UI: Response
    UI-->>User: Erfolg oder Fehlermeldung

Beispiel-Request (wie er vom Frontend gesendet wird):

POST /api/v1/devices/{uuid}/command
x-api-key: <api-key>
Content-Type: application/json

{
    "capability": "pump",
    "value": "ON"
}

Schnellübersicht Seiten¶

Lokale Entwicklung¶

Voraussetzungen:

• Node.js 18+ (empfohlen 20+)
• npm

Setup:

npm install
copy .env.example .env
npm run dev

Relevante Skripte:

npm run dev
npm run build
npm run preview
npm run lint

Hinweise¶

• Ohne korrekten API-Key schlagen Steuerbefehle fehl.
• Bei Verbindungsproblemen zuerst Backend-Erreichbarkeit und CORS prüfen.
• Das Dashboard ist als erweiterbare Betriebsoberfläche ausgelegt, nicht nur als UI-Template.

Typische Entwicklungsaufgaben¶

1. Eine neue Seite unter src/pages anlegen und in src/App.tsx routen.
2. Eine bestehende Device-API-Funktion nutzen oder in src/utils/api.ts erweitern.
3. Fehlerfälle testen: 401 (falscher Key), 503 (Gerät offline), 404 (keine Telemetrie).
4. UI-Feedback ergänzen (Toast/Status), damit Backend-Zustände sichtbar sind.