Files
laraundfelix/CLAUDE.md
T
LarsandCursor 463851d402
Deploy Test / test (push) Successful in 11s
Deploy Test / deploy (push) Successful in 15s
Binde die Medien im Container unter demselben Pfad wie auf dem Host ein.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-15 08:43:42 +01:00

62 lines
7.5 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.
# Lara & Felix (LUF) – Arbeitsregeln für Claude
Stack: Laravel 13, PHP 8.4, Filament 5, PostgreSQL, Docker Compose. Repository: Gitea `Lars/laraundfelix` (`git@192.168.2.144:Lars/laraundfelix.git`).
Dokumentation: `docs/` (Architektur, Spezifikation), Betrieb: `docs/betrieb/DEPLOYMENT.md` und `docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md`.
## Branches und Deployment (verbindlich)
| Branch | Zweck | Wirkung eines Pushs |
|---|---|---|
| `feature/**` | Einzelne Änderungen | Nur Tests (`ci-feature.yml`) |
| `develop` | **Arbeits- und Integrationsbranch** | Tests, dann Deploy auf **Test** (`deploy-test.yml`, Port 3011) |
| `main` | **Produktion** | Tests, dann Deploy auf **Prod** (`deploy-prod.yml`, Port 3010) |
1. **Gearbeitet wird auf `develop` oder auf `feature/*`-Branches, die in `develop` münden.** Nie direkt auf `main`.
2. **Nie auf `main` pushen, nie nach `main` mergen und keinen Pull Request nach `main` freigeben.** Ein Push auf `main` löst sofort ein Produktiv-Deployment aus. Der Merge `develop` → `main` ist ein **manueller Schritt von Lars** (Pull Request in Gitea, nach Prüfung des Teststands). Claude bereitet höchstens vor: Zusammenfassung der Änderungen seit dem letzten Merge, Stand der Tests, offene Migrationen.
3. Nie `--force`/`--force-with-lease` auf `develop` oder `main`. Kein `git reset --hard` auf geteilten Branches.
4. Vor einem Push auf `develop` prüfen, dass die Tests lokal bzw. im Feature-Branch grün waren. Fehlgeschlagene Tests blockieren das Deployment (`needs: test`); sie nicht umgehen oder deaktivieren.
5. **Claude deployt nie von Hand.** Keine `docker compose`-, `deploy.sh`- oder `systemctl`-Aufrufe auf den Servern. Deployments entstehen ausschließlich durch die Gitea-Workflows.
6. Ein roter Workflow wird behoben, nicht überbrückt. Der Rollback im Deploy-Skript setzt nur den Code zurück, nicht die Datenbank.
## Tests
- **Jede Änderung am Verhalten bringt Tests mit** (Feature-Tests für Abläufe, Berechtigungen und Lizenzlogik, Unit-Tests für reine Logik). Fehler werden erst durch einen fehlschlagenden Test reproduziert, dann behoben.
- Es gibt zwei Stufen, beide als eigene Gitea-Jobs:
1. **Gate vor dem Deploy** (`scripts/ci-test.sh`, Wegwerf-Container, Pint und `php artisan test`). Gilt für `feature/**`, `develop` und `main` und blockiert jedes Deployment.
2. **Suite auf der Test-Instanz** (wie bei Shinkan, eigener Workflow nach dem Deploy auf `develop`): Integrations- und Browser-Tests gegen die laufende Test-Instanz (`luf-test`). Eigener Workflow, nicht Teil von `deploy-test.yml`. Wird mit U0 angelegt.
- **Tests laufen nie gegen Prod** (`luf-prod`): nicht gegen deren Datenbank, Volumes oder Medien-Mounts, nicht in deren Containern, nicht gegen deren URL. Prod prüfen allein das Gate und die Health-Checks des Deploys. (Bei Shinkan hätten Integrationstests nach einem Prod-Deploy in die Prod-Datenbank geschrieben.)
- **Auf der Test-Instanz** dürfen Tests Daten in der Test-Datenbank anlegen, aber nie die Schemas zurücksetzen: kein `RefreshDatabase`, `migrate:fresh` oder `DatabaseTruncation` gegen `luf-test`, solange die Instanz nicht ausdrücklich dafür vorgesehen ist. Laravel-Env-Werte aus dem Container (`DB_CONNECTION=pgsql`) überschreiben die SQLite-Vorgabe der `phpunit.xml`. Ein Lauf von `php artisan test` im Test-Container würde sonst die Test-Datenbank leeren. Deshalb die Instanz-Suite über HTTP (Pest-Browser/Playwright) oder in einem eigenen Container mit eigener Wegwerf-Datenbank laufen lassen.
- Tests dürfen keine Netzwerkaufrufe an echte Dienste machen (Mail, Zahlung, externe APIs). Dafür Fakes verwenden (`Mail::fake()`, `Http::fake()`, `Storage::fake()`).
- **Ein roter Test wird behoben, nicht umgangen.** Kein `skip`, `markTestSkipped`, Löschen oder Abschwächen von Assertions und kein Deaktivieren von Pint, nur um grün zu werden. Ist ein Test fachlich überholt, wird er bewusst geändert und im Commit begründet.
- Tests sind deterministisch: keine Abhängigkeit von Reihenfolge, Uhrzeit oder Zufall ohne feste Werte (`Carbon::setTestNow`, Seeds).
- **Datenbank in der Suite:** Standard ist die SQLite-In-Memory-Konfiguration aus `phpunit.xml`. Tests, die PostgreSQL-spezifisches Verhalten brauchen (JSONB, Constraints, Migrationen), laufen gegen eine eigene Wegwerf-PostgreSQL-Instanz, nicht gegen `luf-test` oder `luf-prod`. Diese Instanz ist in `scripts/ci-test.sh` noch nicht eingebaut und wird mit U0 ergänzt.
- Ein Commit auf `develop` ohne grüne Suite ist nicht zulässig. Wer die Suite nicht lokal oder auf einem Feature-Branch laufen lassen kann, sagt das, statt trotzdem auf `develop` zu pushen.
## Migrationen
- Migrationen müssen **abwärtskompatibel** sein (erst ergänzen, später entfernen), weil der Rollback nur den Code zurücksetzt.
- Keine Migration, die Daten löscht oder umbenennt, ohne vorherige Freigabe von Lars und ein bestätigtes Backup.
## Server und Umgebungen
- Test und Prod laufen vorerst **beide auf `llm-node` (192.168.2.144)**, getrennt durch Compose-Projekt (`luf-test`, `luf-prod`), Verzeichnis, Env-Datei, Volumes und Zugangsdaten. Der Raspberry Pi ist als späteres Testsystem vorgesehen (Umzug über die Variablen in `deploy-test.yml`).
- Secrets liegen nur in `/etc/luf/test.env` und `/etc/luf/prod.env` auf dem Server. **Keine Secrets, Passwörter, Keys oder `.env`-Dateien ins Repo, in Commits, Logs oder Chat-Ausgaben.**
- **Auf Servern wird nur nach ausdrücklicher Freigabe geschrieben.** Rein lesende Abfragen über vorhandene SSH-Zugänge sind erlaubt. Keine SSH-Schlüssel, Benutzer, Firewall-, Proxy- oder Runner-Änderungen. Andere Anwendungen auf den Servern (Shinkan, Gitea, mindnet, qdrant, …) dürfen nicht verändert werden.
- Ports werden nicht geraten: Vor jedem neuen Host-Port die tatsächliche Belegung prüfen (`ss`, `docker ps`). Aktuell vorgesehen: Test 3011, Prod 3010 (Stand 2026-11-15). Datenbank und PHP-FPM veröffentlichen keine Host-Ports.
- Der Reverse Proxy (Synology NAS) wird von Lars verwaltet.
- Shell-Zugriff auf llm-node: `ssh -T llmadmin@192.168.2.144 '<befehl>' </dev/null`, nur lesend und nur mit vorhandenem Key.
## Medien
- Medien liegen auf dem NAS (NFS), je Umgebung eigener Bestand: Test `luf_media_dev`, Prod `luf_media`. Mountpunkte `/srv/luf/test/media` und `/srv/luf/prod/media`. Die Umgebungen dürfen nie auf den Bestand der anderen zeigen.
- Im Container gilt derselbe Pfad wie auf dem Host (`/srv/luf/test/media` bzw. `/srv/luf/prod/media`, Unterordner `originals/`, `derived/`, `public/`). **Der Web-Prozess hat keinen Zugriff auf `originals/`** und liest `derived/` und `public/` nur. Nur die Hintergrundverarbeitung (`queue`) schreibt. Diese Trennung (Architektur 03 und 08) nicht aufweichen, auch nicht „vorübergehend“.
- Private Medien werden nie über einen statischen öffentlichen Pfad ausgeliefert, sondern nur nach Berechtigungsentscheidung über kurzlebige Signaturen.
- Mounts am Server (fstab) und NFS-Freigaben auf dem NAS ändert Lars. Claude liefert die Zeilen, schreibt sie aber nicht.
## Entwicklung
- Zeilenenden: `.gitattributes` erzwingt LF (lokal ist `core.autocrlf=true` gesetzt). Shell-Skripte nie mit CRLF committen.
- Commits: kurze, deutsche oder englische Betreffzeile im Imperativ, ein logischer Schritt pro Commit.
- Änderungen an `.gitea/workflows/`, `Dockerfile`, `docker-compose.yml` und `scripts/deploy.sh` wirken direkt auf Test und Prod. Sie werden nur gezielt und mit Begründung geändert und in `docs/betrieb/DEPLOYMENT.md` nachgeführt.
- Nicht verifizierte Aussagen zu Servern oder Kapazitäten werden als solche gekennzeichnet. Nichts erfinden (Ports, Hostnamen, Pfade, Zugangsdaten).