# MOSAIC FTP-Manager

## Zweck

Der FTP-Manager dient dem projektgebundenen Transfer eines MOSAIC-Projekts auf einen Zielserver.

Die zentrale Datei ist:

- `_pgm/admin/ftp_manager.php`

Pro Projekt gibt es genau eine verschluesselte FTP-Konfiguration:

- `<projekt>/<projekt>.ftp`

Beispiel fuer `argos`:

- `argos/argos.ftp`

Die Datei enthaelt Host, Port, Protokoll, Benutzer, verschluesseltes Passwort, passiven Modus und Zielverzeichnis.

## Uebersetzungen

Alle sichtbaren Ausgaben des FTP-Managers muessen ueber `deepl_translate` laufen.

Das gilt fuer:

- Labels
- Buttons
- Hilfetexte
- Warnungen
- Fehlermeldungen
- Statusmeldungen
- Logmeldungen
- JSON/API-Meldungen im Feld `message`
- SSE-Meldungen im Feld `msg`

Im PHP-Code sollen dafuer die vorhandenen Helfer verwendet werden:

- `ht()` fuer HTML-Ausgaben
- `jt()` fuer JavaScript-Strings
- `ftp_manager_translate()` fuer zentrale Meldungstexte

Neue direkte Klartextausgaben im HTML oder in API-Antworten sind zu vermeiden.

## Grundprinzip

Der FTP-Manager arbeitet aus Sicht eines MOSAIC-Projekts.

Ein Projekt liegt parallel zu `_pgm` im MOSAIC-Root:

```text
iss/
  _pgm/
  argos/
  svsb/
  admin_password.lic
  web.config
```

Wenn das Zielverzeichnis im FTP-Dialog `argos` ist, gilt:

- `argos` ist der Projektordner.
- `_pgm` liegt parallel dazu im uebergeordneten MOSAIC-Root.
- Projektdateien werden nach `/argos/...` uebertragen.
- Runtime-Dateien aus `_pgm` werden nach `/_pgm/...` uebertragen.

Der Eintrag im Feld `Zielverzeichnis (Server, Projektpfad)` ist also der Projektpfad, nicht zwingend der physische Windows-Pfad des IIS.

## Pfadregeln

Alle FTP-Pfade werden intern normalisiert:

- Backslashes werden zu Slashes.
- Mehrfache Slashes werden bereinigt.
- `.` und `..` werden entfernt.
- FTP/FTPS bekommt transportseitig relative Pfade ohne fuehrenden Slash.
- SFTP arbeitet mit absoluten Pfaden.

Die logischen Browser-Pfade sind immer MOSAIC-Pfade, keine lokalen Windows-Pfade.

Beispiel:

```text
Anzeige: /argos
FTP-Abfrage: argos

Anzeige: /_pgm
FTP-Abfrage: _pgm
```

Bei Servern, die den Login bereits im MOSAIC-Root starten, ist `/` im Filebrowser der MOSAIC-Root.

## Transferumfang

Aus dem Projektordner werden rekursiv alle relevanten Dateien uebertragen.

Ausgeschlossen sind:

- `.lic`
- `.ftp`
- `.lock`
- temporaere Projektordner wie `_file_store`, `_tmp_charts`, `_tmp_dashboard`

Aus `_pgm` werden nicht pauschal alle Unterordner uebertragen. Der Runtime-Anteil ist bewusst begrenzt:

- `_pgm/css`
- `_pgm/fpdf`
- `_pgm/PHPMailer`
- `_pgm/admin/security`
- ausgewaehlte Sprachpakete unter `_pgm/admin/_deepl_cache/<SPRACHE>`
- definierte Admin-Dateien aus der Include-Liste in `ftp_manager.php`

`admin_password.lic` wird als MOSAIC-Root-Datei behandelt und nur angelegt, wenn sie auf dem Ziel fehlt.

## Sprachpakete

Die Option fuer zentrale Admin-Sprachdateien zeigt eine Auswahl aller lokal vorhandenen MOSAIC-Sprachen aus:

```text
_pgm/admin/_deepl_cache/
```

Es werden nur die angehakten Sprachpakete uebertragen.

Die Auswahl zeigt nicht nur den technischen Sprachcode, sondern einen lesbaren Namen an.
Der sichtbare Name laeuft ueber `deepl_translate`.
Der technische Sprachcode bleibt sichtbar, damit der Entwickler eindeutig erkennt, welches Paket uebertragen wird.

Beispiel:

```text
Englisch (USA) (EN-US)
Franzoesisch (FR)
Portugiesisch (Brasilien) (PT-BR)
```

Der Entwickler muss keine Sprachpakete mehr vor dem Transfer manuell loeschen.

## Filebrowser

Der FTP-Manager enthaelt einen Filebrowser fuer den Zielserver.

Der Filebrowser erlaubt:

- Ordner anzeigen
- Ordner anlegen
- Ordner loeschen
- Dateien anzeigen
- Dateien anlegen
- Dateien bearbeiten
- Dateien hochladen
- Dateien herunterladen
- Dateien oder Ordner umbenennen

Die Anzeige erfolgt tabellarisch.

Nach Schreiboperationen wird die aktuelle Ansicht neu geladen.

Bei laengeren Loeschvorgaengen zeigt die Oberflaeche einen Busy-Zustand und sperrt den Loeschbutton.

## Erlaubter Zugriff im Filebrowser

Der Filebrowser ist fuer Entwicklerzugriff auf den MOSAIC-Zielbereich gedacht.

Erlaubte Einstiegspunkte:

- `MOSAIC-Root`
- `Projektordner`
- `_pgm`

Projektgeschwister im MOSAIC-Root duerfen angezeigt werden, weil sie dort technisch parallel zum aktuellen Projekt liegen.

Nicht erlaubt ist der Zugriff oberhalb des MOSAIC-Roots oder in fremde Serverbereiche ausserhalb dieses Root-Kontexts.

## Navigation

Ein Klick auf einen Ordner oeffnet diesen Ordner.

Der Filebrowser speichert fuer jede Zeile den kanonischen Pfad. Dadurch darf ein erneuter Klick auf `argos` nicht zu Pfaden wie diesem fuehren:

```text
/iss/argos/argos/argos
```

Solche Wiederholungen werden auf den bekannten Projektpfad normalisiert.

Beispiel:

```text
/iss/argos/argos/argos
```

wird logisch zu:

```text
/argos
```

Die gleiche Regel gilt fuer `_pgm`.

## Besonderheit IIS / pftp.exe

Einige Windows-FTP-Server, insbesondere pftp.exe oder IIS-nahe Setups, liefern bei `rawlist` nicht immer das erwartete Verzeichnis.

Beobachtete Effekte:

- `rawlist('/argos')` kann die MOSAIC-Root-Liste liefern.
- `rawlist('/argos/*')` liefert dagegen die richtigen Inhalte von `argos`.
- `chdir('argos')` kann erfolgreich sein, waehrend `rawlist('.')` leer oder unbrauchbar ist.

Deshalb nutzt der Filebrowser mehrere Fallbacks:

1. Standardlisting per `chdir` und `rawlist('.')`
2. direktes Listing ohne `chdir`
3. `nlist`
4. Wildcard-Listing mit `/*`

Wenn eine Serverantwort offensichtlich wie die Root-Liste aussieht, wird die Wildcard-Liste bevorzugt.

Diese Fallbacks sind bewusst allgemein gehalten und nicht nur fuer Windows gebaut.

## UNIX-Kompatibilitaet

Der Filebrowser und Transfer muessen auch auf UNIX-FTP-Servern funktionieren.

Darum bleibt die Reihenfolge:

1. zuerst normales UNIX-kompatibles Listing
2. danach erst Fallbacks fuer spezielle FTP-Server

Der pftp/IIS-Fallback darf das normale UNIX-Verhalten nicht ersetzen.

## Protokolle

Unterstuetzt werden:

- FTP
- FTPS
- SFTP

SFTP benoetigt die PHP-Erweiterung `ssh2`.

FTP und FTPS verwenden die PHP-FTP-Funktionen.

## Sicherheit

Der FTP-Manager ist admin-geschuetzt.

Wichtige Schutzregeln:

- Zugriff nur nach Admin-Guard.
- Schreibaktionen verwenden CSRF-Token.
- Projektname und DB-Name werden validiert.
- FTP-Konfiguration wird verschluesselt gespeichert.
- Der Filebrowser validiert Pfade gegen erlaubte Roots.
- Loeschen der Root-Einstiegspunkte selbst ist gesperrt.

## Entwicklungsregeln

Alle neu eingebauten Texte muessen uebersetzbar sein.

Keine neuen festen Ausgaben dieser Art einbauen:

```php
echo "Fehler";
json_response(['message' => 'Fehler']);
```

Stattdessen die bestehenden Uebersetzungswege verwenden:

```php
echo ht('Fehler');
json_response(['message' => 'Fehler']);
```

`json_response()` uebersetzt das Feld `message` zentral.

Bei Aenderungen am FTP-Manager immer pruefen:

```powershell
php -l C:\xampp\htdocs\iss\_pgm\admin\ftp_manager.php
```

Bei Navigationsthemen testen:

- Klick auf `MOSAIC-Root`
- Klick auf `Projektordner`
- Klick auf `_pgm`
- mehrfacher Klick auf denselben Projektordner
- Wechsel in Unterordner und wieder nach oben
- Loeschen einer Datei mit anschliessender Aktualisierung

Bei Serverkompatibilitaet testen:

- FTP auf Windows/pftp.exe
- FTP auf UNIX
- passive Verbindung
- Pfade mit und ohne fuehrenden Slash

## Typische Zielkonfiguration

Wenn der Zielserver physisch so aufgebaut ist:

```text
D:\inetpub\wwwroot\iss\
  _pgm\
  argos\
```

und der FTP-Benutzer nach dem Login bereits in `D:\inetpub\wwwroot\iss\` landet, dann ist fuer das Projekt `argos` das Zielverzeichnis:

```text
argos
```

Nicht eintragen:

```text
D:\inetpub\wwwroot\iss\argos
```

Der physische Serverpfad bleibt Sache des FTP-Servers. MOSAIC arbeitet mit dem FTP-sichtbaren Projektpfad.
