Solar Guard — PRD

Project Requirements Document

Solar Guard — Produktanforderungsdokument (PRD)

Version: 1.1
Aktualisiert: 07.10.2026
Produkt-URL: https://solarguard.io
Plattform: Base44 (Backend-as-a-Service)


Inhaltsverzeichnis

  1. Zusammenfassung
  2. Problemstellung
  3. Zielgruppen & Rollen
  4. Systemarchitektur
  5. Kernfunktionen
  6. Datenmodell
  7. Hardware-Integration
  8. Backend-Funktionen & Workflows
  9. Bezahlung & Lizenzen
  10. Mehrsprachigkeit (i18n)
  11. Nicht-funktionale Anforderungen
  12. Wichtige Designentscheidungen
  13. Bekannte Probleme & Roadmap

1. Zusammenfassung

Solar Guard ist eine Überwachungsplattform für Photovoltaikanlagen, die Ertragsverluste frühzeitig erkennt. Das System prüft Anlagen mehrfach täglich und vergleicht jede Messung mit ähnlichen Anlagen in der Region. Im Gegensatz zu herkömmlichen Monitoring-Portalen, die nur Wechselrichter-Ereignisse weiterleiten, filtert, klassifiziert und priorisiert Solar Guard Probleme — sodass Installateure nur das sehen, was tatsächlich Handlungsbedarf erfordert.

Bestandteile der Plattform

| Bestandteil | Beschreibung | |-------------|--------------| | Solar Guard Bridge | ESP32-P4-Hardware-Gateway, neben dem Wechselrichter installiert. Verbindet ihn sicher über Ethernet/WLAN mit der Cloud. | | Cloud-Plattform | Web-Anwendung (React + Tailwind) mit rollenbasierten Dashboards für Installateure, Anlagenbesitzer und Admins. | | KI-Diagnose-Engine | Regelbasierte und KI-gestützte Diagnosen: erkennt MPPT-Imbalance, String-Unterleistung, Wechselrichter-Ausfälle und schleichende Verschlechterung. | | Stripe-Shop | Einmalige Hardware-Bestellung + jährliche Softwarelizenz, gestaffelt nach Anlagengröße (kWp). |


2. Problemstellung

Eine typische Privat-PV-Anlage erzeugt jährlich Strom im Wert von tausenden Euro. Dennoch können Verschmutzung, Verschattung, defekte Module oder Wechselrichterprobleme den Ertrag Monat für Monat mindern — oft unbemerkt bis zur nächsten Zählerablesung.

Schwächen bestehender Monitoring-Portale

  • Leiten rohe Wechselrichter-Ereignisse ungefiltert weiter → Alarm-Überflutung
  • Erkennen keine Probleme, die keinen Fehlercode auslösen (z. B. schleichende String-Verschlechterung)
  • Sind herstellerspezifisch → kein herstellerübergreifender Vergleich
  • Erfordern manuelle Prüfung hunderte Anlagen

Die Solar Guard-Lösung

| Maßnahme | Wirkung | |----------|---------| | 24h-Beobachtung | Neue Fehler werden 24h beobachtet, bevor sie gemeldet werden → keine Fehlalarme bei kurzfristigen Störungen | | String/MPPT-Ebene | Unterleistung wird auf String- oder MPPT-Ebene erkannt — bevor der Wechselrichter alarmiert | | Herstellerübergreifend | Fronius, Huawei, SMA werden auf einer normalisierten Datenbasis verglichen | | Automatische Priorisierung | Probleme werden automatisch nach Ertragsauswirkung priorisiert |


3. Zielgruppen & Rollen

3.1 Rollenübersicht

| Rolle | Beschreibung | Hauptfunktionen | |-------|--------------|-----------------| | Admin | Solar Guard-Betreiber | Vollzugriff: Benutzer, Anlagen, Geräte, Firmware, Diagnosen, Shop, Umsatz, KI-Training, Warteliste, Funnel-Analytics | | Installateur | PV-Installationsfirma | Flotten-Dashboard, Anlagen-Einrichtungsassistent, Bridge-Fernkonfiguration, Service-Tickets, Diagnose-Prüfung, Kundeneinladungen | | User (Anlagenbesitzer) | Endkunde | Dashboard für die eigene Anlage, Live-Produktionsdaten, Ertragsverlauf, Alarme, Einkäufe |

3.2 Authentifizierung

  • E-Mail/Passwort mit OTP-E-Mail-Verifizierung
  • Google OAuth
  • Rollenzuweisung bei der Registrierung (Installateur = Firmendaten erforderlich; Privatkunde = Anlagen-Zuordnung erforderlich)
  • Passwort-zurücksetzen-Flow mit E-Mail-Link
  • Integrierte Benutzerverwaltung (Admins laden Benutzer ein; Benutzer können nicht direkt erstellt werden)

4. Systemarchitektur

4.1 Architekturdiagramm

┌─────────────────────────────────────────────────────┐
│                    Frontend (React)                    │
│  Landing · Funnel · Shop · Dashboard · Admin · Setup   │
└──────────────┬──────────────────────────┬──────────────┘
               │                          │
               │  Base44 SDK (REST/WS)     │  Stripe SDK
               ▼                          ▼
┌──────────────────────────────────┐  ┌─────────────────────────┐
│   Base44 Backend                  │  │   Stripe (Zahlungen)     │
│  · Entities (MongoDB)             │  │  · Checkout Sessions     │
│  · Backend Functions              │  │  · Subscriptions         │
│  · Workflows (Scheduler)           │  │  · Webhook → DB-Sync     │
│  · RLS (Zeilensicherheit)          │  └─────────────────────────┘
│  · Realtime Subscriptions          │
└──────────┬────────────────────────┘
           │  HTTPS (REST)
           ▼
┌──────────────────────────────────┐
│  Solar Guard Bridge               │
│  (ESP32-P4 Firmware)              │
│  · Heartbeat (30s)                │
│  · Wechselrichter-Polling (30s)    │
│  · OTA-Firmware-Updates           │
│  · Netzwerk-Scan (automatisch)     │
│  · Modbus TCP (Huawei)             │
│  · Fronius Solar API               │
└──────────┬────────────────────────┘
           │  Lokales Netzwerk (LAN)
           ▼
┌──────────────────────────────────┐
│  PV-Wechselrichter                │
│  Fronius · Huawei · SMA           │
│  (Smart Dongle / Logger)           │
└──────────────────────────────────┘

4.2 Technologie-Stack

| Ebene | Technologien | |-------|--------------| | Frontend | React 18, Tailwind CSS, shadcn/ui, Recharts, React Leaflet, Framer Motion, react-hook-form | | Backend | Base44-Plattform (Serverless Functions in TypeScript/Deno, MongoDB-Entities, Workflow-Scheduler) | | Hardware | ESP32-P4-NANO (Arduino C++-Firmware, Ethernet, Modbus TCP, Fronius Solar API) | | Zahlungen | Stripe (Checkout Sessions, Subscriptions, Webhooks) | | KI | Base44 InvokeLLM (GPT-5, Gemini, Claude) für Diagnosen und Trainingsfragen | | i18n | Eigenes System (DE/IT/EN) mit Browser-Erkennung und localStorage |


5. Kernfunktionen

5.1 Öffentliches Marketing & Funnel

| Funktion | Beschreibung | |----------|--------------| | Landing Page | Hero, Vorteile, Monitoring-Details, 28-Punkte-Tagesprüfung, Hardware-Kompatibilität, Installateur-Programm, Showcase, Preise | | 4-Stufen-Click-Funnel | Landing → Bridge-Info → Lizenz-Auswahl (nach kWp) → Stripe-Checkout. Trackt FunnelEvent bei jedem Schritt mit UTM-Parametern | | Shop | Bridge-Hardware (einmalig) + Jahreslizenz (nach kWp gestaffelt). Stripe-Checkout mit Test-/Live-Modus | | Getting-Started-Wizard | Öffentliche Seite: Anlagengröße → Wechselrichter-Marke → Ergebnis (Ertragswert, Investition, Paket). Warteliste für nicht unterstützte Marken | | Rechtsseiten | Impressum, Datenschutz, Cookie-Richtlinie |

5.2 Authentifizierung & Onboarding

| Funktion | Beschreibung | |----------|--------------| | Registrierung | Rollenauswahl (Installateur vs. Privatkunde). Installateure geben Firmendaten an (Name, Ansprechpartner, Adresse, USt-IdNr.) | | E-Mail-Verifizierung | OTP-Code nach Registrierung; Benutzer muss vor erstem Login verifizieren | | Setup-Wizard | 4 Schritte: (1) Anlagendaten + Marken-Auswahl → (2) Bridge-Aktivierung + Firmware-Check → (3) Automatischer Wechselrichter-Scan → (4) String/MPPT-Konfiguration | | Geräte-Aktivierung | QR-Code-Scan oder manuelle Seriennummer + 6-stelliger Aktivierungscode. Bridge registriert sich beim Einschalten automatisch in der Cloud |

5.3 Installateur-Portal (Kontrollzentrum)

| Funktion | Beschreibung | |----------|--------------| | Flotten-Dashboard | Alle Kundenanlagen auf einen Blick: Status, Live-Produktion, Handlungsbedarf-Panel, Beobachtungs-Panel, wöchentliche Event-Filterung | | Anlagen-Liste | Einfache Listenansicht mit Klick-Navigation zur Anlagendetailseite. Suche/Filter nach Status | | Anlagen-Detail | Tabs: Übersicht, Statistik, Datenquellen, Strings, Ereignisse. Live-Kacheln (DC-Produktion, Tagesertrag, Batterie, Wetter). 5-Punkte-Gesundheitschecks. Wartungshistorie. Kunde einladen | | Service-Tickets | CRUD mit Priorität (niedrig/mittel/hoch/kritisch) und Status (offen/geplant/in Bearbeitung/erledigt) | | Service-Kalender | Monatskalender mit geplanten Wartungsterminen | | Vergleich | Regionaler Benchmark: Flotteneffizienz, spezifischer Ertrag (kWh/kWp), Anomalie-Erkennung (>5% unter Regionalwert) | | Bridge-Fernsteuerung | Neustart, Werkseinstellung, OTA-Firmware-Update, Log-Upload, Netzwerk-Scan — alles über Heartbeat-Befehle | | Diagnosen | KI- + regelbasierte Diagnosen mit Schweregrad, Konfidenz, geschätztem Verlust, Empfehlung. Installateur kann bestätigen/ablehnen/quittieren |

5.4 Anlagenbesitzer-Dashboard

| Funktion | Beschreibung | |----------|--------------| | Live-Übersicht | Aktuelle Leistung, Tagesertrag, Batterie-SOC, Energiefluss-Animation | | Produktions-Charts | Tageskurve, monatliches gestapeltes Balkendiagramm (pro Gerät vs. Erwartung) | | Alarme-Feed | Aktive Warnungen und kritische Ereignisse für die eigene Anlage | | Einkäufe | Aktive Abonnements und Einzelkäufe mit Stripe-Rechnungslinks |

5.5 Admin-Panel

| Funktion | Beschreibung | |----------|--------------| | Dashboard | KPIs: Benutzer gesamt, Anlagen, Geräte, Warnungen, aktive User, tägliche aktive User, neue User/Anlagen/Geräte. Zeitraum-Filter (heute/Woche/Monat/Jahr) | | Benutzer | Liste, einladen, bearbeiten, Rollenverwaltung. Suche nach Name/E-Mail | | Anlagen | Liste mit zugeordneten Bridges, Leistung, Status. Löschen mit Kaskade | | Geräte | ESP32-Bridges: Status, Firmware, Befehle (Neustart/OTA/Logs/Scan). Nicht zugeordnete Geräte. Etiketten-Druck | | Diagnose-Übersicht | Flottenweite Diagnose-Statistiken | | Statistik | Plattformweite Analysen | | Anlagen-Karte | Geografische Karte aller Anlagen mit Koordinaten | | Lizenzen | Lizenzstatus pro Anlage (aktiv/abgelaufen/gekündigt) | | Shop/Preise | Lizenzstufen und Preise konfigurieren | | Warteliste | Benutzer, die auf nicht unterstützte Marken warten | | Funnel-Analytics | Konversionsraten pro Funnel-Schritt, UTM-Quelle/Medium/Kampagne | | Umsatz | MRR, Abonnements, Einzelumsatz | | Firmware-Manager | Firmware-Images hochladen, freigeben, archivieren. Entwürfe stufen → manuelle Admin-Freigabe | | Updates-Tab | Bridge-Script-Updates (Entwurf vorbereiten → freigeben) | | KI-Training | Diagnosen bewerten (korrekt/Fehlalarm/behoben), Wissensbasis verwalten, tägliche KI-Trainingsfragen beantworten |

5.6 Gesundheitsüberwachung

Solar Guard führt einen 5-Punkte-Gesundheitscheck pro Anlage durch:

| Check | Beschreibung | |-------|--------------| | plant_online | Wechselrichter erreichbar und sendet Daten | | strings_producing | Alle Strings liefern DC-Leistung | | battery_online | Batteriespeicher verbunden und funktionsfähig | | mppt_performance | MPP-Tracker arbeiten im optimalen Bereich | | no_error_codes | Wechselrichter meldet keine aktiven Fehler | | string_config_complete | Alle erkannten MPPTs mit Details konfiguriert (Ausrichtung, Module) |

Gesundheitsstatus: optimal (alle OK) → beobachtung (1 Problem) → eingriff (mehrere Probleme, eskaliert nach Grace-Period).

Nacht-Bewusstheit: Statuswarnungen für inaktive Wechselrichter werden nachts unterdrückt — basierend auf Anlagenkoordinaten und Sonnenstand.

5.7 Diagnose-Engine

Regelbasierte Diagnose (automatisch, alle 30 Min)

  • MPPT-Ausfall-Erkennung: Einzelne MPPT-Eingänge mit Null-Produktion, während andere aktiv sind
  • String-Imbalance-Erkennung: DC-Leistungsabweichung zwischen Strings desselben Wechselrichters über dem Schwellwert
  • 24-Stunden-Beobachtung: Neue Probleme werden 24h beobachtet, bevor sie als handlungsrelevant gemeldet werden
  • Auto-Auflösung: Wenn ein Problem ohne Eingriff verschwindet, wird die Diagnose automatisch aufgelöst

KI-gestützte Diagnose (täglich, Flotte)

  • Nutzt InvokeLLM mit Wetterkontext, Peer-Vergleich und Wissensbasis-Einträgen
  • Erkennt: Verschmutzung, Verschattung, Moduldefekt, Kabelproblem, Schnee, Hotspot, Batterieprobleme, Wechselrichterfehler, PID-Effekt, Hagelschaden, Datenqualität
  • Liefert: Schweregrad, Konfidenz %, geschätzter Verlust %, Empfehlungstext
  • Wetter-bereinigte Analyse: Schlechte Produktion wird gegen aktuelles Wetter und Einstrahlung geprüft

Diagnose-Lebenszyklus

offen → in_bearbeitung → bestaetigt / abgelehnt → erledigt

Installateure können die Ursache bestätigen, Alarm-Priorität setzen (wichtig/standard/ignoriert) und Wärme-/RGB-Bilder anhängen.

5.8 KI-Lern-Loop

| Komponente | Beschreibung | |------------|--------------| | Wissensbasis (KnowledgeEntry) | Manuell erstellte oder aus Feedback abgeleitete Wissenseinträge. Kategorisiert (anlagenverhalten, fehlermuster, konfiguration, wartung). Getaggt für Matching. Aktive Einträge werden in KI-Diagnose-Prompts einbezogen | | Trainingsfragen (TrainingQuestion) | KI generiert tägliche Fragen zu unklaren Mustern in Flottendaten. Admins antworten → Antwort wird KnowledgeEntry. Dedup-Key verhindert Duplikate pro Tag | | Diagnose-Feedback | Bewertete Diagnosen (korrekt/Fehlalarm/behoben) fließen in die Wissensbasis zurück | | Hilfe-Bot | In-App-KI-Assistent für Installateure. Beantwortet Fragen zu Anlagen, Wechselrichtern, Fehlercodes. Erstellt Support-Tickets für ungelöste Probleme |


6. Datenmodell

6.1 Kern-Entities

| Entity | Zweck | Schlüsselfelder | |--------|-------|-----------------| | Plant | PV-Anlage | name, owner_name/email/phone, address, lat/lng, capacity_kwp, Modulkonfiguration, inverter_brands, Dach-Ausrichtung/Neigung, Batterie, Wallbox, status, license_status, health_checks, health_status, performance_score | | Inverter | Einzelner Wechselrichter | plant_id, device_id, modbus_unit_id, manufacturer, model, serial, Modulkonfiguration, Live-Daten (Leistung, Ertrag, Spannung, Strom, Frequenz, Temperatur), Batteriedaten, Netzdaten, string_data (JSON), status | | PiDevice (Bridge) | Hardware-Gateway | device_id, platform (esp32_p4), serial_number, passkey, plant_id, installer_id, claimed_by_user_id, firmware_version, status (online/offline/updating/error), pending_command, last_seen, config_override | | DiscoveredDevice | Scan-Ergebnis | pi_device_id, device_id, ip_address, model, manufacturer, plant_id, status (pending/imported/ignored/other_plant), inverter_type, Batterie-Info | | PvArray | Teilfeld | plant_id, label, Dach-Ausrichtung/Neigung, Modulkonfiguration, capacity_kwp, inverter_label | | StringReading | Pro-String Live-Daten | inverter_id, string_index, voltage_v, current_a, power_kw, daily_yield_kwh, module_count, capacity_kwp | | InverterReading | Zeitreihen-Live-Daten | inverter_id, alle Live-Messwerte (gedrosselt) | | DailyProduction | Tagesertrags-Datensätze | plant_id, inverter_id, scope (anlage/wechselrichter/feld), date, yield_kwh, peak_power_kw, specific_yield_kwh_kwp | | Diagnostic | KI-/Regel-Diagnose | plant_id, type, severity, title, description, confidence_percent, estimated_loss_percent, recommendation, status, alarm_source, weather_context, peer_comparison | | PlantEvent | Ereignis-Protokoll | plant_id, category, type, title, description, severity, status (offen/beobachtung/behoben/quittiert), auto_resolved | | InverterAlarm | Roh-Wechselrichter-Alarm | Wechselrichter-Fehlercodes mit Priorität | | ServiceTicket | Service-Anfrage | plant_id, title, priority, status, assigned_to, scheduled_date | | MaintenanceLog | Wartungs-Eintrag | plant_id, date, type, title, description, technician, cost, parts_replaced, next_service_date | | Weather | Wetter pro Anlage | plant_id, lat/lng, temperature, cloudiness, wind, precipitation, humidity, uv_index, solar_radiation |

6.2 Commerce-Entities

| Entity | Zweck | Schlüsselfelder | |--------|-------|-----------------| | Order | Bestelldatensatz | order_number, user_id, items (JSON), total_amount, status, stripe_session_id, stripe_subscription_id | | Subscription | Lizenz-Abo | user_id, plant_id, plan_name, tier_label, annual_fee, billing_cycle, status, Stripe-IDs | | OneTimeRevenue | Einzelkauf | Nicht-wiederkehrende Umsatzdatensätze | | FunnelEvent | Funnel-Tracking | session_id, step, source/medium/campaign (UTM), tier_index, kwp, user_id |

6.3 System-Entities

| Entity | Zweck | Schlüsselfelder | |--------|-------|-----------------| | FirmwareImage | OTA-Firmware | platform, version, board, file_url, sha256, status (draft/released/archived), min_version_to_update, release_notes | | PiConfig | Bridge-Konfiguration | key, value (Script-Inhalt, Konfiguration) | | PiLog | Bridge-Log-Einträge | device_id, level, message, context, script_version | | KnowledgeEntry | KI-Wissensbasis | title, content, category, tags, active, source (manual/feedback) | | TrainingQuestion | KI-Trainings-F&A | question_text, category, status (offen/beantwortet/übersprungen), answer, knowledge_entry_id | | WaitlistEntry | Warteliste für Marken | email, brand, notes |

6.4 Zeilensicherheit (RLS)

Alle Entities haben RLS konfiguriert:

| Rolle | Zugriff | |-------|---------| | Admin | Vollzugriff auf alle Entities | | Installateur | Zugriff eingeschränkt auf installer_id — sieht nur Anlagen/Geräte/Diagnosen, die ihm zugewiesen sind | | User (Anlagenbesitzer) | Zugriff eingeschränkt auf plant_id (auf User-Entity gespeichert) — sieht nur die eigene Anlage | | Öffentliche Übermittlungen (FunnelEvent, WaitlistEntry) | Erstellen offen für alle; Lesen nur für Admin |


7. Hardware-Integration

7.1 Solar Guard Bridge (ESP32-P4)

| Fähigkeit | Beschreibung | |-----------|--------------| | Plattform | ESP32-P4-NANO (RISC-V), Ethernet PHY, USB-Serial | | Heartbeat | Alle 30s (serverseitig anpassbar). Meldet Status, Firmware, IP. Empfängt Befehle | | Wechselrichter-Polling | Alle 30s. Fronius Solar API + Modbus TCP (Huawei) | | Netzwerk-Scan | Automatisch bei Anlagen-Zuweisung. Paralleles Subnetz-Scan (Port 80 für Fronius, Port 502 für Huawei Modbus) | | OTA-Updates | A/B-Partition mit Rollback. Crash-Loop-Erkennung (5 Reboots → Partition wechseln). Pending-Verify benötigt 3 erfolgreiche Heartbeats | | Watchdog | Hardware- + Software-Watchdog. Heartbeat-Watchdog (5 Min kein Heartbeat → Reboot) | | Werkseinstellung | Taste: 3-7s (NVS-Reset), 7-10s (Scan erzwingen), >10s (volle Werkseinstellung) | | Sicherheit | Passkey-Auth mit Brute-Force-Sperre. Geräte-Identität wird per Server-Befehl zugewiesen |

7.2 Unterstützte Wechselrichter-Marken

| Marke | Verbindung | Register-Map | Status | |-------|------------|--------------|--------| | Fronius | Solar REST API (Port 80) | PowerFlow, InverterRealtimeData, StringRealtimeData, StorageData | ✅ Produktion | | Huawei — Smart Dongle | Modbus TCP (Port 502) | FC4/30000 (Modell), FC3/32000 (Echtzeit), FC3/37765 (Batterie) | ✅ Produktion (v1.1.37) | | Huawei — SmartLogger | Modbus TCP (Port 502) | FC3/40500 (Aggregat), FC 0x2B (Geräte-Erkennung), direktes RS485-Routing | ✅ Produktion | | Huawei — EMMA | Modbus TCP (Port 502) | Register 30000+ | ✅ Implementiert | | SMA | — | — | 📋 Geplant |

7.3 Firmware-Versionierung

  • Semantische Versionierung (MAJOR.MINOR.PATCH)
  • Firmware-Images werden vom Admin hochgeladen, als Entwurf gespeichert, nach Freigabe manuell freigegeben
  • min_version_to_update stellt A/B-Partition-Kompatibilität sicher
  • Bridge prüft bei Heartbeat auf Updates; Admin kann Force-Update über Dashboard auslösen
  • ESP32-Firmware-Updates erfolgen nie automatisch — Installateur muss manuell über Banner im Anlagen-Dashboard starten

8. Backend-Funktionen & Workflows

8.1 Backend-Funktionen (~80 gesamt)

| Kategorie | Funktionen | |-----------|------------| | Bridge-Kommunikation | espHeartbeat, piHeartbeat, espLogUpload, piLogUpload, assignEspDevice, claimPiDevice, assignBridgeSerial, replacePiDevice, deletePiDevice | | Datenerfassung | froniusPush, froniusPushV2, froniusPullLocal, huaweiPush, froniusDiscover, manualAddDiscoveredDevice, importDiscoveredDevice, requestNetworkScan | | Diagnosen | runDiagnostics, runAiDiagnosis, checkMpptPerformance, confirmDiagnostic, cleanupDiagnostics, getDiagnosticOverview | | Gesundheit & Performance | checkPlantHealth, computePlantPerformance, computePeerComparison, peerComparison, updatePlantStatus, syncDcPower, fixDcData, fixInverterData, fixDailyYield, runDataSync | | Firmware | firmwareUpload, firmwareRelease, firmwareCheck, checkFirmwareUpdates, checkDeviceFirmware, prepareBridgeUpdate, releaseBridgeUpdate, updateBridgeScript, downloadModule, downloadPiScript, piConfig | | Commerce | createCheckoutSession, stripeWebhook, getStripeBilling, manageStripeCustomer, getPublicPricing, getPublicStats | | Admin | adminApi, adminAuth, adminListUsers, deletePlant, deleteInstallerPlants, updatePlantInstallerIds | | KI-Training | generateTrainingQuestions, generateDailyTrainingQuestions, getDailyQuestions, answerDailyQuestion, manageKnowledge, saveLearnedKnowledge | | Service | createServiceTicket, monthlyReport, testConnection, installerSettings, markOfflineDevices, checkPiOffline, pingPiDevices, checkLicenseExpiry, snapshotDailyProduction, aggregateMonthlyYield, analyzeWeatherFromInverters | | Funnel | trackFunnelEvent, getFunnelAnalytics, submitWaitlistEntry |

8.2 Automatisierte Workflows

| Workflow | Trigger | Zweck | |----------|---------|-------| | Regelbasierte Diagnose (alle 30 Min) | Zeitplan (alle 30 Min) | MPPT-Ausfall + String-Imbalance-Erkennung flottenweit | | Tägliche KI-Diagnose (Flotte) | Zeitplan (täglich) | KI-gestützte Flottendiagnose mit Wetter- + Peer-Kontext | | Plant Health Check (alle 5 Min) | Zeitplan (alle 5 Min) | Anlagen-Gesundheitsstatus aus Live-Daten aktualisieren | | Plant Performance Score | Zeitplan | Performance-Score berechnen (Ertrag vs. Erwartung, Verfügbarkeit, Alarme) | | MPPT Performance Check | Zeitplan | MPPT-Leistungsabweichung prüfen | | Tägliche Produktions-Snapshots | Zeitplan (täglich) | Tagesproduktion pro Anlage/Wechselrichter/Feld snapshoten | | Monats- und Gesamtertrag berechnen | Zeitplan (monatlich) | Monats- und Gesamtertrag aggregieren | | DC-Power-Sync | Zeitplan | DC-Leistungs-Messwerte synchronisieren | | Pi Offline-Timeout Check | Zeitplan | Bridges erkennen, die über dem Schwellwert offline sind | | Ping Pi Devices | Zeitplan | Aktiver Ping zur Bridge-Konnektivitätsprüfung | | Lizenz-Ablauf-Check (täglich) | Zeitplan (täglich) | Lizenzen nach Ablaufdatum ablaufen lassen | | fixDailyYield — Tagesertrag-Korrektur | Zeitplan | Tagesertrag korrigieren, wenn E_Day null ist | | Tägliche KI-Trainingsfragen | Zeitplan (täglich) | KI-Trainingsfragen aus Flottenmustern generieren | | Inverter-Daten-Korrektur | Entity-Trigger | Wechselrichter-Datenanomalien automatisch korrigieren |


9. Bezahlung & Lizenzen

9.1 Stripe-Integration

  • Modus: Live (echte Zahlungen)
  • Produkte:
    • Solar Guard Bridge — einmaliger Hardware-Kauf (99 €)
    • Solar Guard Lizenz — Jahres-Abo, 9 Stufen nach kWp gestaffelt (150–5.099 €/Jahr)
  • Checkout: Stripe Checkout Sessions (Top-Level-Navigation, iframe-fähig)
  • Webhook: stripeWebhook-Funktion unter https://solar-guard.base44.app/functions/stripeWebhook — synchronisiert Checkout-Abschluss, Abo-Status, Rechnungs-Events in die DB
  • Metadaten: Alle Stripe-Objekte enthalten base44_app_id für Transaktions-Tracking

9.2 Lizenzmodell

| Konzept | Beschreibung | |---------|--------------| | Lizenzstufen | 9 Stufen basierend auf Anlagenkapazität (kWp). Automatisch aus kWp-Eingabe ermittelt | | Lizenzstatus | aktiv (aktiv), abgelaufen (abgelaufen), gekündigt (gekündigt) | | Lizenztyp | standard (kostenpflichtig), kostenlos (gratis, vom Admin zugewiesen) | | Ablauf-Behandlung | Täglicher Workflow prüft license_expires_at. Abgelaufene Lizenzen blockieren Live-Daten, Diagnosen und Statistiken (LicenseBlockedScreen) | | Reaktivierung | Abgelaufene/gekündigte Anlagen erfordern einen neuen Jahres-Abo-Kauf, um die Überwachung wieder zu aktivieren |


10. Mehrsprachigkeit (i18n)

| Aspekt | Beschreibung | |--------|--------------| | Unterstützte Sprachen | Deutsch (DE, Standard), Italienisch (IT), Englisch (EN) | | Erkennung | Browser-Sprache beim ersten Besuch, in localStorage gespeichert | | Umschalter | Manueller Sprachumschalter in der UI | | Struktur | Übersetzungsdateien pro Sprache (src/lib/translations/{de,it,en}.js), nach Modul/Komponente organisiert | | Verwendung | t('key')-Funktion über LanguageProvider-Context | | Audit | check-translations.cjs-Skript prüft Konsistenz, meldet fehlende/unbenutzte Keys, auto-fixt fehlende Einträge | | Dev-Warnungen | Runtime-Warnungen im Dev-Modus für fehlende Übersetzungs-Keys |


11. Nicht-funktionale Anforderungen

11.1 Performance

  • Bridge-Heartbeat alle 30s; Wechselrichter-Polling alle 30s (anpassbar)
  • Live-Daten-Updates über Realtime-Subscriptions (WebSocket)
  • Frontend: Lazy-Loaded-Seiten, React Query für Datenabruf/Caching
  • Wechselrichter-Messwerte gedrosselt, um DB-Überlast zu vermeiden (Push-Throttle über last_reading_at)

11.2 Zuverlässigkeit

  • Bridge: A/B-OTA-Partitionen mit automatischem Rollback bei Crash-Loop
  • Heartbeat-Watchdog: 5 Min kein Heartbeat → Auto-Reboot
  • Boot-Loop-Recovery: 5 Reboots ohne Heartbeat → vorherige Partition
  • Workflows: dauerhaft, überstehen Neustarts (durable waits)
  • Fehlerbehandlung: Backend-Funktionen lassen Fehler durch (keine stillen Catches); nutzerseitige Formulare zeigen Inline-Fehler

11.3 Sicherheit

  • RLS auf allen Entities (Admin/Installateur/User-Scoping)
  • Bridge-Auth: Passkey + Brute-Force-Sperre (failed_attempts, locked_until)
  • Admin-Panel: separates Passwort (ADMIN_PANEL_PASSWORD)
  • Automation-Secrets: AUTOMATION_SECRET / AUTOMATION_SECRET_V2 für Workflow-getriggerte Funktionen
  • Stripe-Webhook-Signatur-Verifizierung
  • Keine PII in Analytics-Events

11.4 Skalierbarkeit

  • Serverless-Backend-Funktionen (Auto-Skalierung)
  • MongoDB-Entities mit indizierten Abfragen
  • Bridge-Polling ist verteilt (jede Bridge pollt ihre eigenen Wechselrichter)
  • Bulk-Operationen für Massen-Updates (bulkCreate, bulkUpdate, updateMany, deleteMany)

11.5 Responsivität

  • Mobile + Desktop responsives Design
  • Tailwind CSS mit token-basiertem Design-System
  • Touch-freundliche Steuerelemente für den Vor-Ort-Einsatz des Installateurs
  • Druck-optimierter Etiketten-Druck für Geräte-Labels

12. Wichtige Designentscheidungen

  1. Bridge-Script-Updates werden als Entwürfe gestuft — nie automatisch freigegeben. Admin muss im Updates-Tab manuell freigeben.
  2. Wechselrichter-Konfiguration nur in der Anlagen-Detailansicht — nicht in der zentralen Wechselrichter-Liste.
  3. Netzwerk-Scan erfolgt automatisch bei Bridge-Aktivierung/Zuweisung — kein manueller Start erforderlich.
  4. Anlagen-Liste ist eine einfache Listenansicht mit Klick-Navigation (kein Karten-Raster).
  5. Nacht-Bewusstheit — Wechselrichter-Offline-Warnungen werden nachts unterdrückt (basierend auf Anlagenkoordinaten und Sonnenstand).
  6. Setup-Wizard ist vereinfacht — technische Details werden aus Anlagendaten vorausgefüllt; nur die Modul-Anzahl erfordert manuelle Eingabe.
  7. ESP32-Firmware-Updates erfolgen nie automatisch — Installateur muss manuell über ein Banner im Anlagen-Dashboard starten.
  8. Huawei-Integration unterstützt drei Modi — Smart Dongle (direkter Modbus), SmartLogger (RS485-Gateway), EMMA (SmartHEMS).
  9. Regelbasierte Diagnosen laufen alle 30 Minuten ohne LLM — kosteneffizient, deterministisch. KI-Diagnosen laufen täglich für tiefere Analysen.
  10. 24-Stunden-Beobachtungszeitraum für neue Fehler vor Meldung — eliminiert Fehlalarme durch kurzfristige Störungen.

13. Bekannte Probleme & Roadmap

13.1 Bekannte Probleme

  • Wechselrichter device_id-Kollision, wenn Seriennummern in der API fehlen (mehrere Wechselrichter defaulten auf '1')
  • SmartLogger Modbus TCP-Forwarding an RS485-Units 12-14 funktioniert nicht transparent (Timeouts)
  • Remapped-Modus (51000+) liefert nur Aggregatwerte, keine pro-MPPT-Daten
  • Intermittierende Wechselrichter-Konnektivität (mögliche lokale Netzwerk-/Hardware-Instabilität)
  • Tagesertrags-Diskrepanzen zwischen Dashboard und PV-Portal durch Messlatenz

13.2 Roadmap

| Priorität | Funktion | |----------|----------| | Hoch | SMA-Wechselrichter-Unterstützung — nächste Marken-Integration | | Hoch | Generische Modbus-Architektur — markenunabhängige Register-Mapping für schnelleres Marken-Onboarding | | Mittel | SolarEdge, KOSTAL, GoodWe — zusätzliche Marken-Unterstützung | | Mittel | Mobile Push-Benachrichtigungen — native iOS/Android-App mit Push-Credentials | | Niedrig | Erweiterte Degradationsanalyse — langfristige Trend-Erkennung über Monate/Jahre | | Niedrig | Wärmebild-Integration — Upload und KI-Analyse von Wärmebild-Drohne/Boden |