# DWS SourceTree

Interne Release- & Update-Routine, um den **Develop**-Stand kontrolliert nach
**Productive** zu promoten (Dateien + DB-Änderungen), erreichbar unter
`sourcetree-webservice.datamat-software.de`.

## Was es macht

- **Commits erfassen** (Web-UI): Commit-Typ (`added|changed|deprecated|removed|improved`),
  Beschreibung und beliebig viele SQL-Statements. Statements können optional direkt gegen
  die Develop-DB ausgeführt werden.
- **Release erzeugen**: bündelt alle offenen Commits zu einer neuen Version
  (`Major.Minor.Patch`, Major = Ordnernummer `vN`; Bump = Minor oder Patch) und erzeugt
  automatisch:
  - eine **Migrationsdatei** `migrations/{vN}/{version}__{ts}.sql` – SQL-Statements
    getrennt durch den Separator `##DWS-NEW-SQL##`
  - einen **Changelog** `changelogs/{vN}/{version}.md` (gruppiert nach Commit-Typ)
- **Deploy → Productive**: Backup der Productive-DB, wendet die Migration Statement für
  Statement auf die Productive-DB an (mit Pro-Statement-Tracking, resumierbar), spiegelt
  die Dateien `develop/{vN}` → `productive/{vN}` (ohne `.env`, RSA-Keys,
  `.version_info.json`) und schreibt die neue Version in
  `productive/{vN}/.config/.version_info.json`.

## Architektur

```
sourcetree/
├── bootstrap.php            .env-Parser + Autoloader (kein Composer nötig)
├── .config/.env             eigene DB-Zugangsdaten + Serverpfade + Admin-Login
├── db/bootstrap.sql         SourceTree-DB + Tabellen (MANUELL per PuTTY ausführen)
├── public/index.php         Web-UI + Router (HTTP Basic Auth)
├── src/                     Database, CommitService, ReleaseService, PromotionService, ...
├── migrations/{vN}/         generierte Migrationsdateien
├── changelogs/{vN}/         generierte Changelogs
└── backups/                 mysqldump-Backups vor jedem Deploy (git-ignored)
```

Eigene DB: `DatamatWebServiceSourceTree` mit `tblSourceTreeCommit`,
`tblSourceTreeSqlMigration`, `tblSourceTreeRelease`, `tblSourceTreePromotionStatement`.

## Einrichtung (einmalig)

1. **DB anlegen** – `db/bootstrap.sql` **manuell per PuTTY/SSH** ausführen:
   ```
   mysql -u root -p < /var/www/html/dws/sourcetree/db/bootstrap.sql
   ```
   Danach DB-User anlegen/berechtigen (Beispiel am Ende der Datei).

2. **.env anlegen** – `.config/.env.example` → `.config/.env` kopieren und ausfüllen:
   - `ST_DATABASE_*` – SourceTree-DB
   - `ST_DEVELOP_PATH` / `ST_PRODUCTIVE_PATH` – Serverpfade der Umgebungen
   - `ST_ADMIN_USER` und `ST_ADMIN_PASSWORD_HASH`
     (Hash: `php -r "echo password_hash('DEIN_PASSWORT', PASSWORD_DEFAULT);"`)

3. **VHost** `sourcetree-webservice.datamat-software.de` mit DocumentRoot auf
   `sourcetree/public`. **Zugriff schützen** (die App darf Dateien in `develop/` und
   `productive/` schreiben und auf die Productive-DB zugreifen). Der Webserver-User braucht
   Schreibrechte auf `productive/{vN}` sowie `migrations/`, `changelogs/`, `backups/`.

4. **Deploy** der App per SFTP (Profil `sourcetree` in `.vscode/sftp.json`).

## Ablauf (pro Release)

1. Code lokal ändern → per SFTP nach `develop` (wie gehabt).
2. In der SourceTree-UI die zugehörigen **Commits** (inkl. SQL) anlegen.
3. **Release erzeugen** (Minor oder Patch wählen).
4. **Deploy → Productive** klicken. Bei Fehler in einem SQL-Statement bricht der Deploy ab
   und ist nach dem Fix erneut ausführbar (bereits erfolgreiche Statements werden übersprungen).

## Neue API-Version (z.B. v2)

- `develop/v2` anlegen (Major-Bump, Version startet bei `2.0.0`).
- Die RSA-Keys für `productive/v2/.config/` werden vom **eigenen Keygen-Programm** erzeugt;
  ebenso muss `productive/v2/.config/.env` existieren. Fehlt eines davon, bricht der Deploy
  mit einem entsprechenden Hinweis ab (Keys werden nie kopiert/überschrieben).

## Login-geschützte Dateien (CSS/PDF/Assets)

Die Anmeldung ist **session-basiert** (eigenes Login-Formular, kein Browser-Dialog). Statische
Dateien, die Apache direkt ausliefert, umgehen diese Prüfung – daher gibt es ein
PHP-Auslieferungs-Skript:

- Geschützte Dateien in **`protected/`** ablegen (außerhalb `public/`, per URL **nicht** direkt
  erreichbar). Unterordner sind erlaubt.
- Ausliefern nur über **`file.php?f=<pfad>`** – prüft die Session und streamt die Datei erst
  nach erfolgreichem Login:
  ```html
  <link rel="stylesheet" href="file.php?f=app.css">        <!-- geschützte CSS -->
  <a href="file.php?f=doku/handbuch.pdf">PDF anzeigen</a>   <!-- inline im Browser -->
  <a href="file.php?f=doku/handbuch.pdf&dl=1">Download</a>  <!-- als Datei herunterladen -->
  ```
- Nicht eingeloggte Aufrufe werden auf das Login umgeleitet; Directory-Traversal
  (`?f=../…`) wird geblockt (404). Content-Type wird automatisch gesetzt
  (`&dl=1` erzwingt Download statt Anzeige).
- Zentrale Auth-Logik: [src/Auth.php](src/Auth.php) (`Auth::startSession()` /
  `Auth::isAuthenticated()`), genutzt von `index.php` und `file.php`.

## Hinweise

- `.version_info.json` je Umgebung wird von SourceTree verwaltet (Develop bei Release,
  Productive beim Deploy) – nicht per SFTP überschreiben.
- Backups (`backups/`) sind git-ignored und sollten regelmäßig gesichert/aufgeräumt werden.
- Login ist session-basiert über `ST_ADMIN_USER` / `ST_ADMIN_PASSWORD_HASH`; da Zugangsdaten
  im Klartext gepostet werden, ist **HTTPS Pflicht** (VHost bereits so konfiguriert).