Initiales Halloween-Projekt

AGENTS.md

@@ -0,0 +1,93 @@
+# Halloween – Projektregeln
+
+## Ziel und aktueller Auftrag
+
+Interaktives atmendes Grab für Halloween im Vorgarten der Schwester bauen.
+Gewünscht sind ein kräftiger Schreckeffekt, Kamera, Weboberfläche und lokal
+gespeicherte Bilder/Videoclips. Der Nutzer hat nun eine erste Pi-Software mit
+Liveansicht und simuliertem Effektablauf beauftragt; das allgemeine
+Uploadskript und die Blender-Konzeptvorschau wurden ebenfalls freigegeben.
+Hardwarebau und Anschluss echter Aktoren folgen nach Klärung der Mechanik,
+Versorgung und Sicherheit im Plan.
+
+## Arbeitsweise
+
+- Auf Deutsch, klar und knapp kommunizieren.
+- `PLAN.md` als Arbeitsplan pflegen; erledigte Punkte, offene Entscheidungen
+  und verifizierte Ergebnisse getrennt dokumentieren.
+- Vor Änderungen vorhandene Dateien und tatsächliche Hardware prüfen.
+- Vorschläge und Annahmen ausdrücklich kennzeichnen; keine Kameramodelle,
+  Motorleistungen, Anschlüsse, Netzwerkadressen oder Preise erfinden.
+- Klein anfangen: einen vollständigen Effektablauf zuverlässig umsetzen,
+  anschließend zusätzliche Effekte ergänzen.
+- Dokumentation übersichtlich halten; diese Datei unter 400 Zeilen halten.
+- Im lokalen Git Code, Planung und bearbeitbare Blender-Szenen versionieren;
+  Renderdateien, Referenzclip, `.venv` und `data/` bleiben unversioniert.
+
+## Hardware und Architektur
+
+- Vorhanden laut Nutzer: Raspberry Pis 3–5; Pi 5 auf Nutzerfoto bestätigt,
+  RAM vermutlich 8 GB laut Nutzer, noch nicht am Gerät geprüft;
+  außerdem „2mini“ (genaue Geräte unbekannt), Camera Module 3 NoIR
+  (Beschriftung auf Nutzerfoto bestätigt), eventuell Display,
+  LEDs, Servos und Lötwerkzeug. Weitere Teile dürfen vorgeschlagen werden.
+- Vorgeschlagene Aufteilung: Pi 5 für Kamera/WebUI/Ereignisse und Pi 3/4
+  für Effektsteuerung. Noch keine verbindliche Hardwareentscheidung.
+- Für die NoIR-Kamera IR-Beleuchtung bei Dunkelheit und ein passendes
+  Standard-auf-Mini-Kamerakabel für Pi 5 einplanen; vorhandenes Kabel prüfen.
+- GPIOs steuern geeignete Treiber; Motoren, Servos und größere LED-Lasten
+  erhalten eine passend dimensionierte Versorgung.
+- Mechanik erst nach Klärung von Abmessungen, Gewicht, Hub und Bewegungsraum
+  auswählen. Atembewegung und kurzer Schreckimpuls getrennt bewerten.
+
+## Betriebsregeln
+
+- Bewegung bleibt im Grab und außerhalb des Besucherwegs; Quetschstellen
+  abdecken. Leichte bewegte Bauteile und mechanische Anschläge vorsehen.
+- Elektronik für Außeneinsatz geschützt planen; Kleinspannung am Grab,
+  Zugentlastung und geeignete Stromversorgung vorsehen.
+- Bei Start, Verbindungsverlust oder Fehler keine neue Schrecksequenz
+  auslösen; definierte sichere Zustände und lokalen Stopp vorsehen.
+- Sperrzeit und belegten Auslösebereich berücksichtigen.
+- Kinder-/Sanftmodus anbieten. Kamerabasierte Größenhinweise sind unsicher
+  und dürfen nicht als zuverlässige Altersbestimmung gelten.
+- Nutzerwunsch: „voller Schreck“ ist der anfängliche Standard und wird nach
+  neuem gültigem Trigger automatisch ausgelöst, ohne Einzelfreigabe.
+  Modi sind in der WebUI umstellbar; eine gewählte Einstellung soll einen
+  normalen Neustart überdauern. Nach Start erst freien Auslösebereich
+  abwarten; nach Stopp oder Fehler bewusst zurücksetzen. Kamerahinweise
+  gelten nicht als verlässliche Altersentscheidung; automatische Reaktion
+  auf Hinweise zu kleinen Besuchern vor Implementierung abstimmen.
+
+## Kamera, Aufnahmen und Zugriff
+
+- Personen als Ereignisse erkennen, ohne Identitäten zu bestimmen.
+- Keine Gesichtserkennung oder automatische Wiedererkennung konkreter
+  Personen über getrennte Videos hinweg implementieren.
+- Clips mit Zeit, Vorschaubild und Ereignistyp zum manuellen Prüfen anbieten.
+- Aufnahmebereich auf den vorgesehenen privaten Bereich begrenzen;
+  Maskierung, Aufbewahrung und Löschfrist vor Umsetzung festlegen.
+- Tonwiedergabe und Tonaufnahme unterscheiden; Tonaufnahme standardmäßig aus.
+- WebUI zunächst nur im lokalen Netz; keine öffentliche Freigabe ohne
+  ausdrücklichen Auftrag. Zugangsschutz einplanen.
+
+## Erste Softwareversion
+
+- `run.py` startet die FastAPI-WebUI nur auf `127.0.0.1`; Laptop-Zugriff
+  erfolgt per SSH-Tunnel. `--demo` kennzeichnet ein synthetisches Bild.
+- Picamera2 liefert das MJPEG-Livebild; auf dem Entwicklungsrechner wurde
+  nur der Demo-Feed geprüft, nicht die echte Pi-Kamera.
+- Moduswahl und simulierte Sequenz sind implementiert. GPIO, automatische
+  Personenauslösung und Clip-Speicherung sind noch offen.
+- Laufzeitdaten unter `data/` nicht mit dem Uploadskript überschreiben.
+- Optionaler systemd-Autostart der WebUI wird mit `--install-service` beim
+  Upload eingerichtet; auf einem echten Pi noch nicht geprüft.
+
+## Prüfung
+
+- Softwareprüfungen, Hardwaretests und Außentests getrennt berichten.
+- Erst ohne angeschlossene Aktoren simulieren, dann einzelne Aktoren testen,
+  anschließend Gesamtablauf und Fehlerfälle prüfen.
+- Kamera bei tatsächlicher Dunkelheit, Beleuchtung und Verkleidungen testen.
+- Sicheren Zustand bei Netzwerkausfall, Neustart und Stopp verifizieren.
+- Dokumentationsänderungen erfordern keine zusätzlichen Softwaretests.