87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# tOS – Claude Code Guide
|
||
|
||
## Projekt
|
||
Enterprise Web Operating System: Next.js 14 + NestJS 10 + Prisma + PostgreSQL 16 + Keycloak 24.
|
||
pnpm-Monorepo mit Turbo (`apps/web`, `apps/api`, `packages/shared`).
|
||
|
||
## Dev-Befehle
|
||
|
||
```bash
|
||
# Infrastruktur starten (PostgreSQL, Redis, Keycloak)
|
||
cd docker && docker compose up -d
|
||
|
||
# Apps starten
|
||
pnpm dev # alle Apps
|
||
pnpm dev:api # nur Backend
|
||
pnpm dev:web # nur Frontend
|
||
|
||
# Datenbank
|
||
pnpm db:push # Schema anwenden (dev)
|
||
pnpm db:seed # Default-Daten (Rollen, SystemSettings)
|
||
|
||
# TypeScript-Check
|
||
pnpm --filter @tos/api exec tsc --noEmit
|
||
pnpm --filter @tos/web exec tsc --noEmit
|
||
```
|
||
|
||
## Ports
|
||
| Service | Port |
|
||
|------------|------|
|
||
| Frontend | 3000 |
|
||
| Backend | 3001 |
|
||
| Keycloak | 8080 |
|
||
| PostgreSQL | 5432 |
|
||
| Redis | 6379 |
|
||
|
||
## Datenbanken
|
||
- `tos_db` – Keycloak (wird automatisch erstellt)
|
||
- `tos_app` – Anwendung (wird via `docker/postgres/init.sql` automatisch erstellt)
|
||
- Beide in derselben PostgreSQL-Instanz
|
||
|
||
## Keycloak (Dev)
|
||
- Admin-UI: http://localhost:8080 → admin / admin123
|
||
- Realm: `tOS`
|
||
- Frontend-Client: `tos-nextauth` (NextAuth)
|
||
- Backend-Client: `tos-backend` (NestJS)
|
||
|
||
## Architektur
|
||
|
||
**Auth:**
|
||
- Keycloak SSO → NextAuth (Frontend-Session) + passport-jwt RS256 via JWKS (Backend)
|
||
- JWT wird über Keycloak JWKS-Endpoint validiert – KEIN symmetrischer JWT_SECRET
|
||
- Global Guard Chain: JWT → Roles → Permissions, `@Public()` für opt-out
|
||
|
||
**API-Kommunikation:**
|
||
- Backend wickelt alle Responses in `{success, data, timestamp}` (TransformInterceptor)
|
||
- Frontend-`api.ts` unwrappt diesen Envelope automatisch
|
||
- `NEXT_PUBLIC_API_URL` enthält bereits `/api/v1` (z.B. `http://localhost:3001/api/v1`)
|
||
|
||
**Konfiguration:**
|
||
- Integration-Credentials und SystemSettings liegen in der DB, nicht in `.env`
|
||
- `.env` enthält nur Bootstrap-Variablen (DB-URL, Secrets, Keycloak-Koordinaten)
|
||
|
||
## Code-Konventionen
|
||
- **Route-Pattern:** `page.tsx` (Server Component) importiert `*-content.tsx` (Client Component)
|
||
- **Routen:** `[locale]/(auth)/...` = geschützt, `[locale]/(setup)/...` = public, `/login` = public
|
||
- **State:** Zustand für UI-State, TanStack Query für Server-State
|
||
- **i18n:** ASCII-Umlaute in JSON-Keys (`oe`, `ae`, `ue` statt `ö`, `ä`, `ü`)
|
||
- **Installer-API-Calls:** direktes `fetch()` mit `x-setup-token` Header (kein Bearer-Token)
|
||
|
||
## Deployment
|
||
|
||
```bash
|
||
# Lokaler Full-Stack-Test (identisch zu Prod, vor Commit)
|
||
cd docker && docker compose -f docker-compose.local.yml up --build
|
||
# → http://localhost:3000/setup?token=local-setup-token-for-testing
|
||
|
||
# Produktions-Installation (interaktiv)
|
||
./install.sh
|
||
# → fragt Domain + SSL-Modus, generiert Secrets, startet docker-compose.prod.yml
|
||
# → SSL via Let's Encrypt (Caddy, --profile ssl) oder externer Reverse Proxy
|
||
```
|
||
|
||
## Bekannte Issues / TODOs
|
||
- HR-Hooks nutzen noch Mock-Daten (nicht an Backend angebunden)
|
||
- Morning Meeting Endpoints nutzen `DASHBOARD_VIEW` Permission (Security-Gap)
|
||
- `apps/api/integrations.backup/` – deaktivierte Integrations-Module (via .gitignore ignoriert)
|