docs: update README.md and add PlentyONE API spec

- Fix all ASCII umlauts (ue/ae/oe) to proper Unicode (ü/ä/ö/ß) - Add missing setup step: build shared package before first start - Add docs/integrations/ with PlentyONE Swagger spec to project structure - Add user-preferences module and docker:ps script - Fix Keycloak client name to tos-nextauth (actual config) - Add note about manual tos-nextauth client creation - Remove non-existent test section (no tests yet) - Remove unnecessary root .env.example copy step Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 15:56:48 +01:00
parent 35cc24c5ec
commit 068446fbbf
2 changed files with 57 additions and 53 deletions
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Ein webbasiertes Enterprise-Dashboard, das verschiedene Unternehmenssysteme inte

 ## Inhaltsverzeichnis

- [Ueberblick](#ueberblick)
+- [Überblick](#überblick)
 - [Tech-Stack](#tech-stack)
 - [Projektstruktur](#projektstruktur)
 - [Voraussetzungen](#voraussetzungen)
@@ -29,7 +29,7 @@ Ein webbasiertes Enterprise-Dashboard, das verschiedene Unternehmenssysteme inte

 ---

-## Ueberblick
+## Überblick

 tOS ist ein modulares Enterprise Operating System mit folgenden Kernbereichen:

@@ -51,7 +51,6 @@ tOS ist ein modulares Enterprise Operating System mit folgenden Kernbereichen:
 | **Auth** | Keycloak 24, NextAuth 4 |
 | **Infrastruktur** | Docker Compose, pnpm 9, Turborepo |
 | **Sprachen** | TypeScript 5.6, i18n via next-intl (DE/EN) |
-| **Testing** | Vitest (Frontend), Jest (Backend) |

 ---

@@ -63,14 +62,14 @@ tOS/
 │   ├── web/                    # Next.js 14 Frontend (Port 3000)
 │   │   ├── src/
 │   │   │   ├── app/[locale]/   # App Router mit i18n
-│   │   │   │   ├── (auth)/     # Geschuetzte Routen
-│   │   │   │   └── login/      # Oeffentliche Login-Seite
+│   │   │   │   ├── (auth)/     # Geschützte Routen
+│   │   │   │   └── login/      # Öffentliche Login-Seite
 │   │   │   ├── components/     # React-Komponenten (ui, layout, dashboard, hr, lean)
 │   │   │   ├── hooks/          # Custom Hooks (hr, lean, integrations)
 │   │   │   ├── lib/            # Utilities, API-Client, Auth-Config
 │   │   │   ├── stores/         # Zustand State Management
 │   │   │   └── types/          # TypeScript-Typen
-│   │   └── messages/           # i18n Uebersetzungen (de.json, en.json)
+│   │   └── messages/           # i18n Übersetzungen (de.json, en.json)
 │   │
 │   └── api/                    # NestJS 10 Backend (Port 3001)
 │       ├── src/
@@ -81,6 +80,7 @@ tOS/
 │       │   │   ├── integrations/ # 7 API-Connectoren + Sync
 │       │   │   ├── dashboard/  # Widget-Daten & Statistiken
 │       │   │   ├── departments/# Abteilungsverwaltung
+│       │   │   ├── user-preferences/ # Benutzereinstellungen
 │       │   │   └── audit/      # Audit-Logging
 │       │   └── common/         # Filter, Interceptors, Pipes
 │       └── prisma/             # Schema, Migrations, Seed
@@ -88,6 +88,9 @@ tOS/
 ├── packages/
 │   └── shared/                 # Gemeinsame Typen & Utilities
 │
+├── docs/
+│   └── integrations/           # API-Dokumentationen (z.B. PlentyONE Swagger)
+│
 ├── docker/
 │   ├── docker-compose.yml      # PostgreSQL, Redis, Keycloak
 │   ├── keycloak/               # Realm-Export & Config
@@ -127,9 +130,6 @@ pnpm install
 ### 3. Environment-Variablen einrichten

 ```bash
-# Root
-cp .env.example .env
-
 # Docker
 cp docker/.env.example docker/.env

@@ -140,7 +140,7 @@ cp apps/api/.env.example apps/api/.env
 cp apps/web/.env.example apps/web/.env
 ```

-Die `.env.example`-Dateien enthalten alle benoetigten Variablen mit Entwicklungs-Standardwerten.
+Die `.env.example`-Dateien enthalten alle benötigten Variablen mit Entwicklungs-Standardwerten.

 ### 4. Docker-Services starten

@@ -152,7 +152,7 @@ Startet PostgreSQL (5432), Redis (6379) und Keycloak (8080).

 ### 5. Anwendungs-Datenbank erstellen

-Keycloak verwendet die Datenbank `tos_db`. Die Anwendung benoetigt eine separate Datenbank `tos_app`:
+Keycloak verwendet die Datenbank `tos_db`. Die Anwendung benötigt eine separate Datenbank `tos_app`:

 ```bash
 docker exec -it tos-postgres psql -U tos_user -d tos_db -c "CREATE DATABASE tos_app;"
@@ -164,7 +164,7 @@ docker exec -it tos-postgres psql -U tos_user -d tos_db -c "CREATE DATABASE tos_
 pnpm db:push
 ```

-### 7. Datenbank mit Stammdaten befuellen
+### 7. Datenbank mit Stammdaten befüllen

 ```bash
 pnpm db:seed
@@ -172,7 +172,15 @@ pnpm db:seed

 Erstellt Rollen (admin, hr-manager, team-lead, employee), Abteilungen und einen Entwickler-Admin-Benutzer.

-### 8. Entwicklungsserver starten
+### 8. Shared Package bauen
+
+```bash
+pnpm --filter @tos/shared build
+```
+
+Das Shared Package muss vor dem ersten Start gebaut werden, da API und Web die kompilierten Typen benötigen.
+
+### 9. Entwicklungsserver starten

 ```bash
 pnpm dev
@@ -197,7 +205,7 @@ pnpm dev
 | `pnpm dev:web` | Nur Frontend starten |
 | `pnpm dev:api` | Nur Backend starten |
 | `pnpm build` | Alle Apps bauen |
-| `pnpm typecheck` | TypeScript-Pruefung |
+| `pnpm typecheck` | TypeScript-Prüfung |
 | `pnpm lint` | Code-Linting |
 | `pnpm format` | Code-Formatierung |

@@ -207,9 +215,9 @@ pnpm dev
 |--------|-------------|
 | `pnpm db:generate` | Prisma Client generieren |
 | `pnpm db:push` | Schema in die Datenbank pushen |
-| `pnpm db:migrate` | Migrationen ausfuehren |
+| `pnpm db:migrate` | Migrationen ausführen |
 | `pnpm db:seed` | Stammdaten einspielen |
-| `pnpm db:studio` | Prisma Studio oeffnen |
+| `pnpm db:studio` | Prisma Studio öffnen |

 ### Docker

@@ -217,16 +225,9 @@ pnpm dev
 |--------|-------------|
 | `pnpm docker:up` | Container starten |
 | `pnpm docker:down` | Container stoppen |
+| `pnpm docker:ps` | Container-Status anzeigen |
 | `pnpm docker:logs` | Container-Logs anzeigen |
-| `pnpm docker:reset` | Container + Volumes zuruecksetzen |
-
-### Tests
-
-| Script | Beschreibung |
-|--------|-------------|
-| `pnpm test` | Alle Tests ausfuehren |
-| `pnpm test:watch` | Tests im Watch-Modus |
-| `pnpm test:e2e` | End-to-End-Tests |
+| `pnpm docker:reset` | Container + Volumes zurücksetzen |

 ---

@@ -235,15 +236,15 @@ pnpm dev
 ### Authentifizierung

 ```
-Browser -> Next.js (NextAuth) -> Keycloak (OAuth2/OIDC)
-                                      |
-                                      v
-Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung)
+Browser → Next.js (NextAuth) → Keycloak (OAuth2/OIDC)
+                                      │
+                                      ▼
+Browser → Next.js → NestJS API (JWT Guard) → Keycloak (Token-Validierung)
 ```

- **Frontend:** NextAuth mit Keycloak-Provider (JWT-Strategie)
+- **Frontend:** NextAuth mit Keycloak-Provider, automatische Weiterleitung zum Keycloak-Login
 - **Backend:** Passport-JWT mit globalem Guard (`@Public()` zum Deaktivieren)
- **Guard-Kette:** JWT -> Rollen -> Permissions
+- **Guard-Kette:** JWT → Rollen → Permissions

 ### Rollen-System

@@ -251,19 +252,19 @@ Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung)
 |-------|-------------|
 | `admin` | Vollzugriff auf alle Bereiche |
 | `hr-manager` | HR-Verwaltung + LEAN-Zugriff |
-| `manager` | Abteilungsuebergreifende Sicht |
+| `manager` | Abteilungsübergreifende Sicht |
 | `department_head` | Abteilungsleitung |
 | `team-lead` | Teamleitung mit direkten Reports |
 | `employee` | Standard-Mitarbeiterzugriff |

 ### Permissions

-Feingranulare Berechtigungen pro Modul (z.B. `EMPLOYEES_VIEW`, `ABSENCES_APPROVE`, `INTEGRATIONS_MANAGE`). Jede Rolle hat ein vorkonfiguriertes Permission-Set, das ueber die Datenbank angepasst werden kann.
+Feingranulare Berechtigungen pro Modul (z.B. `EMPLOYEES_VIEW`, `ABSENCES_APPROVE`, `INTEGRATIONS_MANAGE`). Jede Rolle hat ein vorkonfiguriertes Permission-Set, das über die Datenbank angepasst werden kann.

 ### Frontend-Architektur

- **App Router** mit `[locale]` Segment fuer i18n
- **Server/Client Split:** `page.tsx` (Server) -> `*-content.tsx` (Client)
+- **App Router** mit `[locale]` Segment für i18n
+- **Server/Client Split:** `page.tsx` (Server) → `*-content.tsx` (Client)
 - **State Management:** Zustand (UI-State), TanStack Query (Server-State)
 - **Component Library:** shadcn/ui auf Radix UI Basis

@@ -273,16 +274,16 @@ Feingranulare Berechtigungen pro Modul (z.B. `EMPLOYEES_VIEW`, `ABSENCES_APPROVE

 ### Dashboard

-Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
+Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfügbare Widgets:

 | Widget | Beschreibung |
 |--------|-------------|
-| Welcome | Begruessung mit Benutzerinfo |
+| Welcome | Begrüßung mit Benutzerinfo |
 | Clock | Digitale Uhr |
 | Stats | KPI-Statistiken |
-| Quick Actions | Schnellzugriff auf haeufige Aktionen |
-| Calendar | Kalenderuebersicht |
-| Activity | Aktivitaetsfeed |
+| Quick Actions | Schnellzugriff auf häufige Aktionen |
+| Calendar | Kalenderübersicht |
+| Activity | Aktivitätsfeed |
 | Orders | PlentyONE Bestellungen |
 | Chat | Zulip Nachrichten |
 | Tasks | Todoist Aufgaben |
@@ -294,13 +295,13 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
 ### HR-Modul

 - **Mitarbeiterverwaltung** - CRUD, Detailansicht, Neuanlage
- **Zeiterfassung** - Stempeluhr, Uebersichten pro Mitarbeiter
- **Abwesenheiten** - Antraege, Genehmigungen, Kalenderansicht
+- **Zeiterfassung** - Stempeluhr, Übersichten pro Mitarbeiter
+- **Abwesenheiten** - Anträge, Genehmigungen, Kalenderansicht
 - **Organigramm** - Visuelle Unternehmensstruktur

 ### LEAN-Modul

- **3S-Planung** - Seiri (Sortieren), Seiton (Systematisieren), Seiso (Saeubern)
+- **3S-Planung** - Seiri (Sortieren), Seiton (Systematisieren), Seiso (Säubern)
 - **Morning Meeting** - SQCDM-Board (Safety, Quality, Cost, Delivery, Morale)
 - **Skill Matrix** - Kompetenzerfassung und -bewertung pro Abteilung

@@ -311,7 +312,7 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
 | System | Typ | Funktionen |
 |--------|-----|-----------|
 | **PlentyONE** | ERP | Bestellungen, Artikel, Kontakte |
-| **Zulip** | Chat | Nachrichten, Streams, Praesenz |
+| **Zulip** | Chat | Nachrichten, Streams, Präsenz |
 | **Todoist** | Tasks | Aufgaben, Projekte |
 | **FreeScout** | Helpdesk | Tickets, Konversationen |
 | **Nextcloud** | Cloud | Dateien, Ordner, Freigaben |
@@ -328,13 +329,13 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:

 ## API-Dokumentation

-Die interaktive API-Dokumentation ist via Swagger UI verfuegbar:
+Die interaktive API-Dokumentation ist via Swagger UI verfügbar:

 ```
 http://localhost:3001/api/docs
 ```

-Authentifizierung erfolgt ueber Bearer JWT-Token. Die API ist in folgende Bereiche unterteilt:
+Authentifizierung erfolgt über Bearer JWT-Token. Die API ist in folgende Bereiche unterteilt:

 - `auth` - Authentifizierung
 - `users` - Benutzerverwaltung
@@ -357,7 +358,7 @@ Authentifizierung erfolgt ueber Bearer JWT-Token. Die API ist in folgende Bereic

 Beide laufen auf derselben PostgreSQL-Instanz.

-### Schema-Uebersicht
+### Schema-Übersicht

 | Bereich | Modelle |
 |---------|---------|
@@ -373,7 +374,7 @@ Beide laufen auf derselben PostgreSQL-Instanz.
 pnpm db:studio
 ```

-Oeffnet eine Web-UI zur direkten Datenbank-Inspektion unter http://localhost:5555.
+Öffnet eine Web-UI zur direkten Datenbank-Inspektion unter http://localhost:5555.

 ---

@@ -387,9 +388,11 @@ Der Realm `tOS` wird beim Start automatisch aus `docker/keycloak/realm-export.js

 | Client | Typ | Verwendung |
 |--------|-----|-----------|
-| `tos-frontend` | Confidential | NextAuth (Frontend-Authentifizierung) |
+| `tos-nextauth` | Confidential | NextAuth (Frontend-Authentifizierung) |
 | `tos-backend` | Confidential | NestJS (Service-Account, Token-Validierung) |

+> **Hinweis:** Der Client `tos-nextauth` muss einmalig manuell in der Keycloak Admin-Konsole angelegt werden. Der Realm-Export enthält nur `tos-frontend` und `tos-backend`. Siehe `apps/web/.env` für die benötigten Client-Einstellungen.
+
 ### Rollen & Gruppen

 **Realm-Rollen:** admin, hr-manager, manager, department_head, team-lead, employee
@@ -424,13 +427,13 @@ Passwort: admin
 |----------|-------------|
 | `DATABASE_URL` | PostgreSQL Connection String (tos_app) |
 | `PORT` | API-Port (3001) |
-| `JWT_SECRET` | JWT-Signaturschluessel |
+| `JWT_SECRET` | JWT-Signaturschlüssel |
 | `KEYCLOAK_URL` | Keycloak-URL |
 | `KEYCLOAK_REALM` | Realm-Name (tOS) |
 | `KEYCLOAK_CLIENT_ID` | Backend-Client-ID |
 | `KEYCLOAK_CLIENT_SECRET` | Backend-Client-Secret |
 | `REDIS_HOST` / `REDIS_PORT` | Redis-Verbindung |
-| `ENCRYPTION_KEY` | AES-256-Schluessel (32 Bytes) |
+| `ENCRYPTION_KEY` | AES-256-Schlüssel (32 Bytes) |
 | `SWAGGER_ENABLED` | Swagger UI aktivieren |
 | `ENABLE_SYNC_JOBS` | Integrations-Sync aktivieren |

@@ -441,12 +444,12 @@ Passwort: admin
 | `NEXT_PUBLIC_API_URL` | Backend-API-URL |
 | `NEXT_PUBLIC_APP_URL` | Frontend-URL |
 | `NEXTAUTH_URL` | NextAuth-Callback-URL |
-| `NEXTAUTH_SECRET` | NextAuth-Signaturschluessel |
+| `NEXTAUTH_SECRET` | NextAuth-Signaturschlüssel |
 | `KEYCLOAK_CLIENT_ID` | Frontend-Client-ID |
 | `KEYCLOAK_CLIENT_SECRET` | Frontend-Client-Secret |
 | `KEYCLOAK_ISSUER` | Keycloak Issuer-URL |

-Vollstaendige Beispiele befinden sich in den jeweiligen `.env.example`-Dateien.
+Vollständige Beispiele befinden sich in den jeweiligen `.env.example`-Dateien.

 ---