Claude: Reorganzie

2026-06-08 21:29:02 +02:00
parent 90f60f9d5d
commit 658a1b3ee3
5 changed files with 313 additions and 39 deletions
--- a/README.md
+++ b/README.md
@@ -1,49 +1,105 @@
 # appRobotHoming

-`appRobotHoming` ist eine browserbasierte Benutzeroberfläche für die
-WebCam-gestützte Ermittlung der Roboterpose. Der Einstieg bleibt als einfaches
-Frontend erhalten, während die Auswertung künftig an den BodyTracker weitergeleitet
-wird.
+`appRobotHoming` ist die browserbasierte Bedienoberfläche für die WebCam-gestützte
+Ermittlung der Roboterpose. Das Frontend bleibt der Einstieg; die eigentliche
+Bildverarbeitung läuft hinter der Firewall auf eigenen Services (WebCam,
+BodyTracker), die der Homing-Backend als schlanker Proxy anspricht.

-## Was das Projekt jetzt macht
- Holt aus der WebCam alle 3 bis 10 Bilder ab (siehe `doc/README_WebCam.md`).
- Zeigt ausgewählte Bilder und die zugehörigen `.npz`-Daten in einer Auswertungsansicht.
- Übergibt diese Daten an den BodyTracker (`doc/README_BodyTracker.md`).
- Ermittelt daraus die Roboterpose und gibt sie aus.
+## Architektur im Überblick

-## Aktueller Fokus
- Benutzeroberfläche bleibt der Einstieg.
- Bildanzeige und Poseausgabe sind zentral.
- Der alte HTTPS/WSS-Server wurde entfernt.
- `certs/`, `scripts/` und `server/` sind nicht mehr Teil des aktuellen Projekts.
+```
+Browser ──HTTPS──▶ Reverse-Proxy ──HTTPS/WSS──▶ appRobotHoming-Backend
+(statisches UI)    (öffentliches TLS)           (server/server.js, Port 2093)
+                                                       │
+                                  intern (hinter der Firewall, HTTP):
+                                                       ├──▶ WebCam-Service     (Bilder)
+                                                       ├──▶ BodyTracker-Service (Pose)
+                                                       └──▶ … weitere Schritte (später)
+```

-## Integration
- Die WebCam- und BodyTracker-Aufrufe laufen über das Backend, nicht direkt aus dem Browser.
- Das Frontend lädt Snapshot-Daten über `/api/latest-snapshot`.
- Der Browser sendet Pose-Anfragen an `/api/estimate`.
- Das Backend kann dann auf interne Docker-Container zugreifen, z. B. auf den WebCam-Service und den BodyTracker-Service.
- Als Fallback verwendet das Backend lokale `public/snapshots`, wenn keine externe WebCam verfügbar ist.
- Konfigurierbare Umgebungsvariablen:
-  - `WEBCAM_URL` – Basis-URL des internen Webcam-Services.
-  - `BODYTRACKER_URL` – Basis-URL des internen BodyTracker-Services.
+- **Frontend (`public/`)** – statische Seite: zeigt Infos, Buttons und die
+  Rückmeldungen (Result als JSON + Tree-View, Snapshot-Tabelle, Bilder). Kein
+  direkter Zugriff auf die internen Services.
+- **Backend (`server/server.js`)** – BFF-Proxy. Liefert das statische Frontend
+  aus und stellt eine kleine API bereit, über die das UI an die internen
+  Services kommt. Läuft auf **HTTPS, Port 2093**.
+
+## Ablauf
+
+1. Das UI lädt den aktuellen Stand über `GET /api/latest-snapshot`.
+2. **Bilder und Kamera-Intrinsics kommen vom WebCam-Service** (eigener Server
+   hinter der Firewall; die Kamera ist Source of Truth ihrer eigenen Kalibrierung).
+3. Auf Knopfdruck schickt das UI eine Pose-Anfrage an `POST /api/estimate`.
+4. Der Backend reicht **Bilder + Intrinsics** zur Verarbeitung an den
+   **BodyTracker** weiter und erhält die Roboterpose zurück.
+5. Das Ergebnis wird im UI ausgegeben (JSON, Tree, Tabelle, annotierte Bilder).
+6. **Eventuell folgen weitere Schritte** (z. B. Pose an `appRobotDriver` geben).
+
+Fällt der BodyTracker aus, rechnet das Frontend ersatzweise lokal mit
+`public/calculateAngles.js`.
+
+## HTTPS (bewusste Entscheidung)
+
+Der Backend läuft selbst auf **HTTPS** – auch wenn davor schon ein Reverse-Proxy
+die öffentliche TLS-Terminierung übernimmt. Grund: **WebSocket-Verbindungen (WSS)
+kommen nur sauber durch den Proxy, wenn auch der Backend-Hop TLS spricht.**
+
+- Das verwendete Zertifikat ist **self-signed** (`https/`, Passphrase `abcd`).
+  Das ist Absicht: Dieser Hop ist nur **Proxy ↔ Backend**, nie öffentlich. Die
+  vertrauenswürdige Kette stellt der vorgelagerte Reverse-Proxy bereit.
+- Zugriff im internen Netz z. B. über `https://thinkcentre.local:2093/`.
+
+## API (Backend)
+
+| Endpoint | Methode | Zweck |
+|---|---|---|
+| `/api/health` | GET | Status + konfigurierte Service-URLs |
+| `/api/latest-snapshot` | GET | Aktuelle Bilder/Daten (vom WebCam-Service bzw. lokalem Fallback) |
+| `/api/estimate` | POST | Bilder an BodyTracker geben → Pose zurück |
+
+## Konfiguration (Umgebungsvariablen)
+
+| Variable | Bedeutung |
+|---|---|
+| `HTTPS_PORT` | Port des Backends (Default `2093`) |
+| `WEBCAM_URL` | Basis-URL des internen WebCam-Services |
+| `BODYTRACKER_URL` | Basis-URL des internen BodyTracker-Services |
+| `HTTPS_KEY_PATH` / `HTTPS_CERT_PATH` / `HTTPS_PASSPHRASE` | self-signed Cert für den Proxy-Hop |
+
+Ist `WEBCAM_URL` nicht gesetzt, nutzt der Backend lokale Dateien aus
+`public/snapshots` als Fallback (Entwicklung ohne Kamera).
+
+## Dateien & Struktur
+
+- `public/` – statisches Frontend (UI, Client-Logik, Anzeige).
+- `server/server.js` – HTTPS-Backend / BFF-Proxy.
+- `https/` – self-signed Zertifikate für den Proxy-Hop (nicht eingecheckt).
+- `doc/README_WebCam.md` – WebCam-Service (Bildquelle).
+- `doc/README_BodyTracker.md` – BodyTracker-Service (Pose-Ermittlung).
+- `doc/ToDo.md` – offene Punkte & nächste Umsetzungsschritte.
+- `test/` – Tests für Berechnung und Auswertung.
+
+## Nutzung
+
+```bash
+npm install
+npm test
+npm start          # startet den HTTPS-Backend auf Port 2093
+```
+
+Danach im internen Netz `https://<host>:2093/` öffnen (self-signed → einmalige
+Zertifikatswarnung im Browser bestätigen).
+
+> Hinweis: Das Frontend ist auf den Backend angewiesen – `/api/latest-snapshot`
+> und `/api/estimate` funktionieren **nicht**, wenn man `index.html` rein
+> statisch öffnet. Immer über `npm start` (bzw. den Container) laufen lassen.

 ## Geplante Erweiterungen
+
 1. Pose an `appRobotDriver` weitergeben.
 2. Wenn die Hand nicht erkannt wird: Vorschlag für eine bessere Arm-/Foto-Position.
 3. Manuelle Eingabe von `x, y, z, a, b, c, e`.
-4. Erkennungsergebnis und erkannte Pose klar im UI ausgeben.
+4. Erkennungsergebnis und Pose klarer im UI ausgeben.

-## Dateien & Struktur
- `public/` – Frontend, UI, Client-Logik und Anzeige.
- `doc/README_WebCam.md` – Details zur Webcam-Architektur und Bildabholung.
- `doc/README_BodyTracker.md` – BodyTracker-Integration und Poseermittlung.
- `test/` – bestehende Tests für die Berechnung und Auswertung.
-
-## Nutzung
-1. `npm install`
-2. `npm test`
-3. Öffne `public/index.html` im Browser oder nutze einen beliebigen statischen Server.
-
-> Hinweis: Die Anwendung ist aktuell als Frontend/Analyse-UI aufgebaut. Die
-> Backend-Serverlogik aus früheren Versionen wurde bereinigt, um das Projekt zu
-> fokussieren.
+Konkrete nächste Schritte und offene Schnittstellen-Fragen: siehe
+[`doc/ToDo.md`](doc/ToDo.md).