flat-pilot/AGENTS.md

Arbeitsregeln fuer Codex

• Das Repository ist ein npm-Workspace-Monorepo mit apps/frontend, apps/backend und packages/api-client; keine Nx-Einfuehrung.
• TypeScript bleibt strikt. Kein any, keine unnoetigen Non-Null-Assertions.
• Backend-Controller verwenden niemals TypeORM-Repositories direkt, sondern Services.
• Services kapseln Fachlogik; Datenbankzugriffe laufen ueber Repository-Klassen oder klar benannte Persistence-Services.
• Keine UI-Library einsetzen. Angular bleibt mobile-first, mit eigenem HTML und SCSS.
• Neue UI muss die Design Tokens aus apps/frontend/src/styles/_tokens.scss verwenden.
• Keine direkten Hex-Farben in Feature-Komponenten; Farben werden semantisch ueber CSS Custom Properties genutzt.
• Bestehende UI-Komponenten unter apps/frontend/src/app/shared/ui wiederverwenden, bevor neue Abstraktionen entstehen.
• Interaktive UI muss per Tastatur bedienbar sein; Fokuszustaende duerfen nicht entfernt werden.
• Informationen duerfen nicht ausschliesslich ueber Farbe vermittelt werden.
• Kein ::ng-deep, keine unkontrollierten !important-Regeln und keine unnoetigen Utility-Klassen.
• OIDC-Tokens bleiben ausschliesslich im Backend. Der Browser erhaelt nur Session-Cookie und CSRF-Token.
• Sessions liegen serverseitig in MySQL. Session-Cookies enthalten keine Tokens oder sensiblen Daten.
• Permissions sind im Code definiert. Benutzer haben keine direkten Permissions, sondern Rollen.
• Admin-Aktionen duerfen den letzten aktiven Administrator nicht entfernen; entsprechende Benutzer- und Rollen-Aenderungen muessen transaktional abgesichert bleiben.
• Admin-Controller verwenden @RequirePermissions(...) und delegieren an Services; Benutzer, Rollen und Sessions werden nicht direkt aus Controllern ueber Repositories veraendert.
• Benachrichtigungen sind benutzerbezogene Daten. Zugriffe muessen serverseitig ueber den aktuellen Session-Benutzer eingeschraenkt werden; keine normalen Endpunkte mit frei uebergebener userId.
• Benachrichtigungen werden ueber NotificationsService erzeugt, nicht direkt ueber TypeORM-Repositories in Controllern oder fremden Modulen.
• Das Backend ist fuer Authentifizierung, Autorisierung und CSRF verbindlich; Angular nutzt Permissions nur zur Darstellung.
• Migrationen werden niemals automatisch beim normalen App-Start ausgefuehrt. Der Start prueft nur auf fehlende Migrationen.
• Secrets, Session-IDs und Tokens duerfen nicht geloggt oder ins Repository aufgenommen werden.
• Tests muessen Verhalten pruefen; keine trivialen Tests, die nur Existenz testen.
• Keine Auth- oder CSRF-Umgehung fuer Entwicklung oder Tests in Production-Code einbauen.
• Keine WebSockets, Queues, Redis, E-Mail-, SMS- oder Push-Versand fuer In-App-Benachrichtigungen einfuehren, solange dies nicht explizit architektonisch entschieden wurde.
• Vor Abschluss muessen npm run lint, npm run format:check, npm run typecheck, npm test, npm run build und docker build . bestehen.