feat: FTP-Spiegel fuer externe 3D-Assets

- --publish laedt Workbench-Dateien per FTPS hoch und verifiziert sie
  durch Rueckdownload und SHA-256
- --sync laedt fehlende Assets vom Server, wenn die Workbench fehlt
- Manifest um remote-Pfad ergaenzt, Manifest-Test auf 53 Assertions
- Doku, Architektur (D13) und Roadmap aktualisiert
This commit is contained in:
torsten 2026-10-31 12:39:30 +01:00
parent 8861cbae92
commit 697274ce1b
7 changed files with 494 additions and 104 deletions

View file

@ -37,27 +37,88 @@ tools/sync_assets.sh
`library/` legen (`..._v001.glb`, `..._v002.glb`).
3. Die bearbeitbare Quelle (`.blend`, Rig, Referenzvideo) nach `source/`.
4. Eintrag in `rinkplanner/assets/asset_manifest.json` ergänzen:
ID, Quelle, Ziel, SHA-256, Größe, Platzierung, Rig, Animationen.
ID, Quelle, Ziel, FTP-Pfad, SHA-256, Größe, Platzierung, Rig, Animationen.
5. `./tools/sync_assets.sh --sync` kopiert und importiert.
6. Vor dem Commit `./tools/sync_assets.sh --check` laufen lassen.
6. Bei geänderter Datei `./tools/sync_assets.sh --publish` für den Spiegel.
7. Vor dem Commit `./tools/sync_assets.sh --check` laufen lassen.
### Befehle
```bash
./tools/sync_assets.sh --check # Standard: nur prüfen
./tools/sync_assets.sh --sync # fehlende Dateien kopieren + Godot-Import
./tools/sync_assets.sh --check # Standard: nur lokal prüfen
./tools/sync_assets.sh --sync # kopieren/laden + Godot-Import
./tools/sync_assets.sh --sync --force # abweichendes Ziel überschreiben
./tools/sync_assets.sh --publish # Workbench-Dateien auf den FTP-Spiegel laden
```
Umgebungsvariablen:
`--sync` arbeitet in dieser Reihenfolge:
1. Ziel in `assets/external/` ist vorhanden und hat den Manifest-Hash → OK.
2. Workbench-Quelle ist vorhanden → kopieren.
3. Sonst vom FTP-Spiegel laden.
Damit funktioniert ein frischer Checkout auf einem Rechner ohne
Workbench-Archiv, sofern die FTP-Zugangsdaten vorliegen.
### FTP-Spiegel
Der vorhandene FTP-Server der Kür-Synchronisation dient als
Verteilungskopie. Die Dateien liegen dort unterhalb des App-Verzeichnisses:
```
<FTP_DIRECTORY>/assets/<remote>
# z. B. rinkplanner/assets/characters/skater_figure_rigged_deform_v002.glb
```
`FTP_DIRECTORY` ist das Verzeichnis aus `docs/credentials.txt` (aktuell
`rinkplanner`). Der Unterordner `assets` wird beim ersten Upload automatisch
angelegt (`--ftp-create-dirs`).
Zugangsdaten kommen aus `docs/credentials.txt` (gitignored) oder aus
`RINKPLANNER_FTP_*`-Umgebungsvariablen. Das Format ist dasselbe wie für die
App:
```
FTP_URL=<host>
FTP_USER=<benutzer>
FTP_PASSWORD=<passwort>
FTP_DIRECTORY=rinkplanner
```
Optional:
| Schlüssel | Bedeutung |
| :--- | :--- |
| `FTP_ASSET_DIRECTORY` | überschreibt `<FTP_DIRECTORY>/assets` |
| `FTP_VERIFY=1` | TLS-Zertifikat prüfen (Standard: 0) |
Der Server verwendet explizites FTPS (`AUTH TLS`, Port 21). Sein Zertifikat
hat keinen passenden Hostnamen, deshalb ist die Prüfung standardmäßig aus.
Die Integrität hängt nicht am Zertifikat, sondern am SHA-256 aus dem
Manifest: Nach jedem Upload wird die Datei zurückgeladen und gehasht; nach
jedem Download wird vor dem Verschieben gehasht.
`--publish` ist bewusst ein eigener Befehl. Ein normaler `--sync` lädt nichts
hoch und überschreibt keine Serverdatei.
Auf einem neuen Rechner:
```bash
cp /pfad/zu/credentials.txt docs/credentials.txt
./tools/sync_assets.sh --sync
```
Weitere Umgebungsvariablen:
| Variable | Standard | Zweck |
| :--- | :--- | :--- |
| `RINKPLANNER_WORKBENCH` | `~/Documents/workbench_rinkplanner` | Archivpfad |
| `RINKPLANNER_CREDENTIALS` | `<repo>/docs/credentials.txt` | FTP-Konfiguration |
| `GODOT` | `/opt/godot/Godot_v4.7.2-stable_linux.x86_64` | Import-Binary |
Das Skript prüft **Quelle und Ziel** gegen den Hash aus dem Manifest. Eine
still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
Das Skript prüft beim Kopieren, Laden und Veröffentlichen die jeweilige
Datei gegen den Hash aus dem Manifest. `--check` prüft nur das lokale Ziel;
eine still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
## Manifest
@ -69,6 +130,7 @@ still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
"format": "glb",
"source": "library/characters/skater_figure_rigged_deform_v002.glb",
"target": "assets/external/characters/skater_figure_rigged_deform_v002.glb",
"remote": "characters/skater_figure_rigged_deform_v002.glb",
"sha256": "1c1f0646…",
"bytes": 8345424,
"source_scene": "source/characters/skater/skater_rig_v002.blend",
@ -95,6 +157,7 @@ still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
| `version` | Zähler der kuratierten Fassung |
| `source` | Pfad relativ zum Workbench-Archiv |
| `target` | Pfad relativ zum Godot-Projekt, immer unter `assets/external/` |
| `remote` | Pfad relativ zum FTP-Asset-Verzeichnis |
| `sha256` / `bytes` | Integritätsprüfung |
| `source_scene` | bearbeitbare Quelle (`.blend`) für Rig/Animation |
| `placement` | Up-Achse, Blickrichtung, Pivot und Höhe für die 3D-Szene |
@ -155,6 +218,7 @@ Details und Messwerte: `docs/findings-2026-10-31-arp-rig.md`.
## Tests
`tests/run_asset_manifest_tests.gd` prüft Schema, Pfade, Hashes und – falls
synchronisiert – Größe und SHA-256 der Zieldatei. Fehlt das Asset (z. B. in
CI), wird der Dateicheck übersprungen, der Schema-Test bleibt aktiv.
`tests/run_asset_manifest_tests.gd` prüft Schema, Pfade, FTP-Pfade, Hashes
und – falls synchronisiert – Größe und SHA-256 der Zieldatei. Fehlt das
Asset (z. B. in CI), wird der Dateicheck übersprungen, der Schema-Test bleibt
aktiv. Aktuell: 53 Assertions.