7.4 KiB
7.4 KiB
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) |
- Gearbeitet wird auf
developoder auffeature/*-Branches, die indevelopmünden. Nie direkt aufmain. - Nie auf
mainpushen, nie nachmainmergen und keinen Pull Request nachmainfreigeben. Ein Push aufmainlöst sofort ein Produktiv-Deployment aus. Der Mergedevelop→mainist 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. - Nie
--force/--force-with-leaseaufdevelopodermain. Keingit reset --hardauf geteilten Branches. - Vor einem Push auf
developprüfen, dass die Tests lokal bzw. im Feature-Branch grün waren. Fehlgeschlagene Tests blockieren das Deployment (needs: test); sie nicht umgehen oder deaktivieren. - Claude deployt nie von Hand. Keine
docker compose-,deploy.sh- odersystemctl-Aufrufe auf den Servern. Deployments entstehen ausschließlich durch die Gitea-Workflows. - 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:
- Gate vor dem Deploy (
scripts/ci-test.sh, Wegwerf-Container, Pint undphp artisan test). Gilt fürfeature/**,developundmainund blockiert jedes Deployment. - 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 vondeploy-test.yml. Wird mit U0 angelegt.
- Gate vor dem Deploy (
- 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:freshoderDatabaseTruncationgegenluf-test, solange die Instanz nicht ausdrücklich dafür vorgesehen ist. Laravel-Env-Werte aus dem Container (DB_CONNECTION=pgsql) überschreiben die SQLite-Vorgabe derphpunit.xml. Ein Lauf vonphp artisan testim 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 gegenluf-testoderluf-prod. Diese Instanz ist inscripts/ci-test.shnoch nicht eingebaut und wird mit U0 ergänzt. - Ein Commit auf
developohne grüne Suite ist nicht zulässig. Wer die Suite nicht lokal oder auf einem Feature-Branch laufen lassen kann, sagt das, statt trotzdem aufdevelopzu 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 indeploy-test.yml). - Secrets liegen nur in
/etc/luf/test.envund/etc/luf/prod.envauf 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, Prodluf_media. Mountpunkte/srv/luf/test/mediaund/srv/luf/prod/media. Die Umgebungen dürfen nie auf den Bestand der anderen zeigen. - Im Container:
/media/originals,/media/derived,/media/public. Der Web-Prozess hat keinen Zugriff auforiginals/und liestderived/undpublic/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:
.gitattributeserzwingt LF (lokal istcore.autocrlf=truegesetzt). 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.ymlundscripts/deploy.shwirken direkt auf Test und Prod. Sie werden nur gezielt und mit Begründung geändert und indocs/betrieb/DEPLOYMENT.mdnachgeführt. - Nicht verifizierte Aussagen zu Servern oder Kapazitäten werden als solche gekennzeichnet. Nichts erfinden (Ports, Hostnamen, Pfade, Zugangsdaten).