rinkplanner/docs/findings-2026-10-31-asset-ftp.md
torsten 697274ce1b 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
2026-10-31 12:39:30 +01:00

107 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Findings 2026-10-31 – FTP-Spiegel für externe Assets
## Problem
Ein frischer Checkout auf einem anderen Rechner hat kein
Workbench-Archiv und damit keine 3D-Modelle. `assets/external/` ist
gitignored, der Rig und die GLB fehlen.
## Lösung
Der vorhandene FTP-Server der Kür-Synchronisation dient zusätzlich als
Verteilungskopie für die 3D-Assets. Das Repo bleibt die Quelle der Wahrheit
für IDs und Hashes; der Workbench bleibt die Quelle für die Bearbeitung.
```
FTP-Server
└── rinkplanner/ # FTP_DIRECTORY aus credentials.txt
├── ... # Kür-Dateien
└── assets/
└── characters/
└── skater_figure_rigged_deform_v002.glb
```
`FTP_ASSET_DIRECTORY` ist standardmäßig `<FTP_DIRECTORY>/assets` und kann
überschrieben werden. Beim ersten Upload legt curl die Ordner an.
## Ablauf
### Veröffentlichen
```bash
./tools/sync_assets.sh --publish
```
1. Quelle gegen den Manifest-Hash prüfen.
2. Datei per explizitem FTPS hochladen (`AUTH TLS`, Port 21).
3. Datei zurückladen, Größe und SHA-256 prüfen.
4. Erst dann „OK".
`--publish` ist ein eigener Befehl; ein normaler `--sync` lädt nichts hoch.
### Auf einem Rechner ohne Workbench
```bash
cp /pfad/zu/credentials.txt docs/credentials.txt
./tools/sync_assets.sh --sync
```
`--sync` prüft in dieser Reihenfolge:
1. Ziel in `assets/external/` vorhanden und Hash korrekt → OK.
2. Workbench-Quelle vorhanden → kopieren.
3. Sonst FTP-Download nach temporärer Datei, Hash prüfen, verschieben,
Godot-Import anstoßen.
## Zugangsdaten
`docs/credentials.txt` (gitignored) mit den bestehenden Schlüsseln:
```
FTP_URL=<host>
FTP_USER=<benutzer>
FTP_PASSWORD=<passwort>
FTP_DIRECTORY=rinkplanner
```
Optional `FTP_ASSET_DIRECTORY` und `FTP_VERIFY=1`. Alternativ
`RINKPLANNER_FTP_*`-Umgebungsvariablen.
## Sicherheit und Integrität
- Der Server nutzt explizites FTPS. Sein Zertifikat hat keinen passenden
Hostnamen; die Prüfung ist deshalb standardmäßig aus (`FTP_VERIFY=0`).
- Der Vertrauensanker ist nicht das Zertifikat, sondern der SHA-256 aus
`asset_manifest.json`. Jeder Upload wird zurückgelesen und gehasht, jeder
Download vor dem Verschieben geprüft.
- Zugangsdaten liegen ausschließlich in der gitignorierten Datei bzw. in
Umgebungsvariablen. Das Manifest enthält keine Secrets.
- Der FTP-Spiegel ist eine Verteilungskopie. Ohne Workbench kann man Assets
laden, aber keine neuen Versionen erzeugen.
## Test
1. `--publish` lud `skater_figure_rigged_deform_v002.glb` (8.345.424 Bytes)
nach `rinkplanner/assets/characters/` und verifizierte den Rückdownload.
2. Ziel aus `assets/external/` entfernt, `RINKPLANNER_WORKBENCH` auf ein
nicht existierendes Verzeichnis gesetzt.
3. `--sync` lud die Datei per FTP, Hash
`1c1f06461b58b02d9b8332a756fdc88f533ff2d25f65a59d21ca0209b65128cb`,
Godot-Import erfolgreich.
4. `--check` danach grün.
## Tests und Doku
- `tests/run_asset_manifest_tests.gd`: jetzt 53 Assertions (zusätzlich
FTP-Pfad, Relativität, Eindeutigkeit).
- Gesamtsuite: **1128 Assertions**.
- `docs/assets.md` beschreibt Spiegel, Befehle und den Rechner ohne
Workbench.
## Offen
- Aufräumregel für alte Versionen auf dem Server (aktuell sammeln sich
versionierte Dateien).
- Android: 1K-Texturen oder separater Asset-Pack, damit die 8,35 MB nicht
ungeprüft ins APK wandern.
- Optional: `--check --remote`, um die Serverdatei ohne Download zu prüfen.