97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# AGENTS.md
|
|
|
|
## Projektueberblick
|
|
|
|
Mood ist ein dateibasierter Stimmungstracker fuer klassische PHP/LAMP-Deployments ohne Datenbank.
|
|
Die App rendert serverseitig PHP-Templates und speichert Nutzer-, Einstellungs- und Trackingdaten unter `storage/`.
|
|
|
|
## Einstiegspunkte
|
|
|
|
- `index.php`: Front-Controller, bootet die App.
|
|
- `src/bootstrap.php`: laedt Dateien, initialisiert Session und stellt `storage/` sicher.
|
|
- `src/App.php`: zentrales Routing und Grossteil der Anwendungslogik.
|
|
|
|
## Wichtige Struktur
|
|
|
|
- `src/Domain/`: dateibasierte Repositories und Fachlogik.
|
|
- `src/Support/`: Auth, View, Verschluesselung, OpenAI, Web Push.
|
|
- `templates/layout.php`: globales Layout.
|
|
- `templates/pages/`: serverseitige Seiten.
|
|
- `assets/css/app.css`: gesamtes Styling.
|
|
- `assets/js/app.js`: Frontend-Logik fuer Charts, Formulare, Archiv, Push und PWA.
|
|
- `storage/system/`: globale Systemdaten wie Nutzer, Throttle, Notifications, Key-Dateien.
|
|
- `storage/users/<user>/`: Nutzerdaten, Einstellungen, Tage, Zusammenfassungen und Push-Status.
|
|
|
|
## Routing
|
|
|
|
Die App nutzt keinen Router von aussen. Routen werden direkt in `App::run()` per `switch ($path)` behandelt.
|
|
|
|
Wichtige Routen:
|
|
|
|
- `/setup`
|
|
- `/login`
|
|
- `/logout`
|
|
- `/`
|
|
- `/track`
|
|
- `/archive`
|
|
- `/options`
|
|
- `/push/subscribe`
|
|
- `/push/unsubscribe`
|
|
- `/push/test`
|
|
- `/reminders/run`
|
|
|
|
## Datenmodell
|
|
|
|
- Nutzer stehen in `storage/system/users.json`.
|
|
- Einstellungen pro Nutzer in `storage/users/<user>/settings.json`.
|
|
- Tagesdaten in `storage/users/<user>/days/YYYY-MM-DD.txt`.
|
|
- Wochen- und Monatszusammenfassungen unter `storage/users/<user>/summaries/`.
|
|
- Push-Subscriptions und Reminder-State liegen ebenfalls pro Nutzer unter `storage/users/<user>/`.
|
|
|
|
Tagesdateien und Zusammenfassungen koennen serverseitig verschluesselt gespeichert werden. Die Logik liegt in `src/Support/EntryCrypto.php`.
|
|
|
|
## Sicherheitsrelevante Regeln
|
|
|
|
- Form-POSTs nutzen CSRF-Token via `csrf_field()` und `App::enforceCsrf()`.
|
|
- JSON-POSTs nutzen `App::enforceRequestCsrf()`.
|
|
- Auth-Logik liegt in `src/Support/Auth.php`.
|
|
- Security-Header werden zentral in `App::sendSecurityHeaders()` gesetzt.
|
|
- Aendere keine Auth-, Cookie-, CSRF- oder Reminder-Token-Logik leichtfertig.
|
|
|
|
## Arbeitsregeln fuer Aenderungen
|
|
|
|
- Bevorzuge kleine, lokale Aenderungen. Die App ist bewusst simpel und frameworkfrei.
|
|
- Ziehe bestehende Hilfsfunktionen in `src/helpers.php` vor, statt neue Utility-Dateien einzufuehren.
|
|
- Wenn moeglich dem bestehenden Muster folgen: Daten lesen/schreiben in Repositories, Seiten in `App`, Ausgabe in Templates.
|
|
- Fuehre keine grossen Architekturumbauten ohne konkreten Bedarf ein. `src/App.php` ist zentral und gewollt monolithisch.
|
|
- Beruehre `storage/` nur, wenn die Aufgabe das wirklich erfordert. Dort koennen echte Nutzerdaten liegen.
|
|
- Fuehre keine Massenformatierung oder kosmetische Grossumbauten ohne Anlass durch.
|
|
|
|
## Frontend-Hinweise
|
|
|
|
- Das UI ist servergerendert; JavaScript erweitert nur interaktive Teile.
|
|
- Neue UI-Logik moeglichst in `assets/js/app.js` integrieren, statt neue Build-Schritte einzufuehren.
|
|
- Externe CDNs oder Frontend-Frameworks nicht einfuehren.
|
|
|
|
## KI- und Push-Integrationen
|
|
|
|
- OpenAI-Zusammenfassungen laufen ueber `src/Support/OpenAiSummaryService.php`.
|
|
- Web Push und VAPID laufen ueber `src/Support/WebPushService.php` und `src/Domain/NotificationRepository.php`.
|
|
- Bei Aenderungen in diesen Bereichen besonders auf Datenschutz, Fehlerbehandlung und Rueckwaertskompatibilitaet der gespeicherten Daten achten.
|
|
|
|
## Lokale Checks
|
|
|
|
Es gibt aktuell keine sichtbare Composer- oder PHPUnit-Konfiguration im Projekt.
|
|
|
|
Sinnvolle manuelle Checks:
|
|
|
|
- PHP-Syntax fuer geaenderte Dateien pruefen: `php -l <datei>`
|
|
- Setup/Login/Tracken/Archiv/Optionen im Browser kurz durchklicken
|
|
- Falls Push oder Reminder betroffen sind: relevante Endpunkte gezielt testen
|
|
|
|
## Deployment-Annahmen
|
|
|
|
- Ziel ist klassisches Apache/LAMP bzw. Cloudron.
|
|
- `.htaccess` und Schreibrechte auf `storage/` sind wichtig.
|
|
- Die App erwartet keinen Datenbankserver und keinen JS-Buildprozess.
|