rinkplanner/docs/findings-2026-10-31-asset-ftp.md

108 lines
3.4 KiB
Markdown
Raw Normal View History

# 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.