feat: complete tOS project with HR, LEAN, Dashboard and Integrations modules

Full enterprise web operating system including: - Next.js 14 frontend with App Router, i18n (DE/EN), shadcn/ui - NestJS 10 backend with Prisma, JWT auth, Swagger docs - Keycloak 24 SSO with role-based access control - HR module (employees, time tracking, absences, org chart) - LEAN module (3S planning, morning meeting SQCDM, skill matrix) - Integrations module (PlentyONE, Zulip, Todoist, FreeScout, Nextcloud, ecoDMS, GembaDocs) - Dashboard with customizable drag & drop widget grid - Docker Compose infrastructure (PostgreSQL 16, Redis 7, Keycloak 24) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 19:37:55 +01:00
parent a2b6612e9e
commit fe305f6fc8
509 changed files with 81111 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,455 @@
-# tOS
+# tOS - Enterprise Web Operating System
+
+![Next.js](https://img.shields.io/badge/Next.js-14.2-black?logo=next.js)
+![NestJS](https://img.shields.io/badge/NestJS-10.3-red?logo=nestjs)
+![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-blue?logo=postgresql)
+![Keycloak](https://img.shields.io/badge/Keycloak-24-blue?logo=keycloak)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue?logo=typescript)
+![License](https://img.shields.io/badge/License-Proprietary-gray)
+
+Ein webbasiertes Enterprise-Dashboard, das verschiedene Unternehmenssysteme integriert und einen zentralen LEAN-Management-Bereich bietet.
+
+---
+
+## Inhaltsverzeichnis
+
+- [Ueberblick](#ueberblick)
+- [Tech-Stack](#tech-stack)
+- [Projektstruktur](#projektstruktur)
+- [Voraussetzungen](#voraussetzungen)
+- [Installation & Setup](#installation--setup)
+- [Scripts](#scripts)
+- [Architektur](#architektur)
+- [Module](#module)
+- [API-Dokumentation](#api-dokumentation)
+- [Datenbank](#datenbank)
+- [Keycloak](#keycloak)
+- [Umgebungsvariablen](#umgebungsvariablen)
+- [Lizenz](#lizenz)
+
+---
+
+## Ueberblick
+
+tOS ist ein modulares Enterprise Operating System mit folgenden Kernbereichen:
+
+- **Dashboard** - Anpassbares Widget-Dashboard mit Drag & Drop
+- **HR** - Mitarbeiterverwaltung, Zeiterfassung, Abwesenheiten, Organigramm
+- **LEAN** - 3S-Planung, Morning Meeting (SQCDM), Skill Matrix
+- **Integrations** - Anbindung an 7 externe Systeme
+- **Admin** - Benutzer-, Abteilungs- und Systemverwaltung
+
+---
+
+## Tech-Stack
+
+| Bereich | Technologien |
+|---------|-------------|
+| **Frontend** | Next.js 14, React 18, TanStack Query, Zustand, Tailwind CSS, shadcn/ui, Framer Motion |
+| **Backend** | NestJS 10, Prisma 5, Passport JWT, Swagger |
+| **Datenbank** | PostgreSQL 16, Redis 7 |
+| **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) |
+
+---
+
+## Projektstruktur
+
+```
+tOS/
+├── apps/
+│   ├── web/                    # Next.js 14 Frontend (Port 3000)
+│   │   ├── src/
+│   │   │   ├── app/[locale]/   # App Router mit i18n
+│   │   │   │   ├── (auth)/     # Geschuetzte Routen
+│   │   │   │   └── login/      # Oeffentliche 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)
+│   │
+│   └── api/                    # NestJS 10 Backend (Port 3001)
+│       ├── src/
+│       │   ├── auth/           # JWT Guards, Rollen, Permissions
+│       │   ├── modules/
+│       │   │   ├── hr/         # Mitarbeiter, Abwesenheiten, Zeiterfassung
+│       │   │   ├── lean/       # Skill Matrix, Morning Meeting, 3S-Planung
+│       │   │   ├── integrations/ # 7 API-Connectoren + Sync
+│       │   │   ├── dashboard/  # Widget-Daten & Statistiken
+│       │   │   ├── departments/# Abteilungsverwaltung
+│       │   │   └── audit/      # Audit-Logging
+│       │   └── common/         # Filter, Interceptors, Pipes
+│       └── prisma/             # Schema, Migrations, Seed
+│
+├── packages/
+│   └── shared/                 # Gemeinsame Typen & Utilities
+│
+├── docker/
+│   ├── docker-compose.yml      # PostgreSQL, Redis, Keycloak
+│   ├── keycloak/               # Realm-Export & Config
+│   └── .env.example
+│
+└── turbo.json                  # Turborepo Build-Pipeline
+```
+
+---
+
+## Voraussetzungen
+
+| Software | Version |
+|----------|---------|
+| **Node.js** | >= 20.0.0 |
+| **pnpm** | >= 9.0.0 |
+| **Docker** | >= 24.0 |
+| **Docker Compose** | >= 2.20 |
+
+---
+
+## Installation & Setup
+
+### 1. Repository klonen
+
+```bash
+git clone https://github.com/Tradeo-GmbH/tOS.git
+cd tOS
+```
+
+### 2. Dependencies installieren
+
+```bash
+pnpm install
+```
+
+### 3. Environment-Variablen einrichten
+
+```bash
+# Root
+cp .env.example .env
+
+# Docker
+cp docker/.env.example docker/.env
+
+# Backend
+cp apps/api/.env.example apps/api/.env
+
+# Frontend
+cp apps/web/.env.example apps/web/.env
+```
+
+Die `.env.example`-Dateien enthalten alle benoetigten Variablen mit Entwicklungs-Standardwerten.
+
+### 4. Docker-Services starten
+
+```bash
+pnpm docker:up
+```
+
+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`:
+
+```bash
+docker exec -it tos-postgres psql -U tos_user -d tos_db -c "CREATE DATABASE tos_app;"
+```
+
+### 6. Datenbank-Schema anwenden
+
+```bash
+pnpm db:push
+```
+
+### 7. Datenbank mit Stammdaten befuellen
+
+```bash
+pnpm db:seed
+```
+
+Erstellt Rollen (admin, hr-manager, team-lead, employee), Abteilungen und einen Entwickler-Admin-Benutzer.
+
+### 8. Entwicklungsserver starten
+
+```bash
+pnpm dev
+```
+
+| Service | URL |
+|---------|-----|
+| **Frontend** | http://localhost:3000 |
+| **Backend API** | http://localhost:3001/api |
+| **Swagger Docs** | http://localhost:3001/api/docs |
+| **Keycloak Admin** | http://localhost:8080 (admin/admin) |
+
+---
+
+## Scripts
+
+### Entwicklung
+
+| Script | Beschreibung |
+|--------|-------------|
+| `pnpm dev` | Alle Apps im Dev-Modus starten |
+| `pnpm dev:web` | Nur Frontend starten |
+| `pnpm dev:api` | Nur Backend starten |
+| `pnpm build` | Alle Apps bauen |
+| `pnpm typecheck` | TypeScript-Pruefung |
+| `pnpm lint` | Code-Linting |
+| `pnpm format` | Code-Formatierung |
+
+### Datenbank
+
+| Script | Beschreibung |
+|--------|-------------|
+| `pnpm db:generate` | Prisma Client generieren |
+| `pnpm db:push` | Schema in die Datenbank pushen |
+| `pnpm db:migrate` | Migrationen ausfuehren |
+| `pnpm db:seed` | Stammdaten einspielen |
+| `pnpm db:studio` | Prisma Studio oeffnen |
+
+### Docker
+
+| Script | Beschreibung |
+|--------|-------------|
+| `pnpm docker:up` | Container starten |
+| `pnpm docker:down` | Container stoppen |
+| `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 |
+
+---
+
+## Architektur
+
+### Authentifizierung
+
+```
+Browser -> Next.js (NextAuth) -> Keycloak (OAuth2/OIDC)
+                                      |
+                                      v
+Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung)
+```
+
+- **Frontend:** NextAuth mit Keycloak-Provider (JWT-Strategie)
+- **Backend:** Passport-JWT mit globalem Guard (`@Public()` zum Deaktivieren)
+- **Guard-Kette:** JWT -> Rollen -> Permissions
+
+### Rollen-System
+
+| Rolle | Beschreibung |
+|-------|-------------|
+| `admin` | Vollzugriff auf alle Bereiche |
+| `hr-manager` | HR-Verwaltung + LEAN-Zugriff |
+| `manager` | Abteilungsuebergreifende 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.
+
+### Frontend-Architektur
+
+- **App Router** mit `[locale]` Segment fuer 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
+
+---
+
+## Module
+
+### Dashboard
+
+Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
+
+| Widget | Beschreibung |
+|--------|-------------|
+| Welcome | Begruessung mit Benutzerinfo |
+| Clock | Digitale Uhr |
+| Stats | KPI-Statistiken |
+| Quick Actions | Schnellzugriff auf haeufige Aktionen |
+| Calendar | Kalenderuebersicht |
+| Activity | Aktivitaetsfeed |
+| Orders | PlentyONE Bestellungen |
+| Chat | Zulip Nachrichten |
+| Tasks | Todoist Aufgaben |
+| Tickets | FreeScout Tickets |
+| Files | Nextcloud Dateien |
+| Documents | ecoDMS Dokumente |
+| GembaDocs | Audit-Dokumente |
+
+### HR-Modul
+
+- **Mitarbeiterverwaltung** - CRUD, Detailansicht, Neuanlage
+- **Zeiterfassung** - Stempeluhr, Uebersichten pro Mitarbeiter
+- **Abwesenheiten** - Antraege, Genehmigungen, Kalenderansicht
+- **Organigramm** - Visuelle Unternehmensstruktur
+
+### LEAN-Modul
+
+- **3S-Planung** - Seiri (Sortieren), Seiton (Systematisieren), Seiso (Saeubern)
+- **Morning Meeting** - SQCDM-Board (Safety, Quality, Cost, Delivery, Morale)
+- **Skill Matrix** - Kompetenzerfassung und -bewertung pro Abteilung
+
+### Integrations-Modul
+
+7 externe Systeme mit einheitlicher Connector-Architektur:
+
+| System | Typ | Funktionen |
+|--------|-----|-----------|
+| **PlentyONE** | ERP | Bestellungen, Artikel, Kontakte |
+| **Zulip** | Chat | Nachrichten, Streams, Praesenz |
+| **Todoist** | Tasks | Aufgaben, Projekte |
+| **FreeScout** | Helpdesk | Tickets, Konversationen |
+| **Nextcloud** | Cloud | Dateien, Ordner, Freigaben |
+| **ecoDMS** | DMS | Dokumente, Klassifizierung |
+| **GembaDocs** | Audit | Audits, Findings, Compliance |
+
+### Admin-Bereich
+
+- **Benutzerverwaltung** - Rollen zuweisen, Benutzer verwalten
+- **Abteilungen** - Abteilungsstruktur pflegen
+- **Integrations-Admin** - Credentials und Sync-Jobs verwalten
+
+---
+
+## API-Dokumentation
+
+Die interaktive API-Dokumentation ist via Swagger UI verfuegbar:
+
+```
+http://localhost:3001/api/docs
+```
+
+Authentifizierung erfolgt ueber Bearer JWT-Token. Die API ist in folgende Bereiche unterteilt:
+
+- `auth` - Authentifizierung
+- `users` - Benutzerverwaltung
+- `departments` - Abteilungen
+- `hr/*` - HR-Endpunkte (Mitarbeiter, Abwesenheiten, Zeiterfassung)
+- `lean/*` - LEAN-Endpunkte (3S, Morning Meeting, Skill Matrix)
+- `integrations/*` - Integrations-Endpunkte (pro Connector)
+- `dashboard` - Dashboard-Daten
+
+---
+
+## Datenbank
+
+### Zwei-Datenbanken-Setup
+
+| Datenbank | Verwendung |
+|-----------|-----------|
+| `tos_db` | Keycloak (wird automatisch erstellt) |
+| `tos_app` | Anwendungsdaten (muss manuell erstellt werden) |
+
+Beide laufen auf derselben PostgreSQL-Instanz.
+
+### Schema-Uebersicht
+
+| Bereich | Modelle |
+|---------|---------|
+| **Core** | User, Department, Role, UserRole |
+| **HR** | Employee, TimeEntry, Absence, EmployeeReview, OnboardingTask |
+| **LEAN** | S3Plan, S3Category, S3Status, MorningMeeting, MorningMeetingTopic, MorningMeetingAction, Skill, SkillMatrixEntry |
+| **Integrations** | IntegrationCredential, IntegrationSyncHistory |
+| **System** | UserPreference, AuditLog |
+
+### Prisma Studio
+
+```bash
+pnpm db:studio
+```
+
+Oeffnet eine Web-UI zur direkten Datenbank-Inspektion unter http://localhost:5555.
+
+---
+
+## Keycloak
+
+### Realm-Konfiguration
+
+Der Realm `tOS` wird beim Start automatisch aus `docker/keycloak/realm-export.json` importiert.
+
+### Clients
+
+| Client | Typ | Verwendung |
+|--------|-----|-----------|
+| `tos-frontend` | Confidential | NextAuth (Frontend-Authentifizierung) |
+| `tos-backend` | Confidential | NestJS (Service-Account, Token-Validierung) |
+
+### Rollen & Gruppen
+
+**Realm-Rollen:** admin, hr-manager, manager, department_head, team-lead, employee
+
+**Gruppen:** Administrators, Management, sowie Abteilungen (Sales, Accounting, Warehouse, Logistics, Engineering, IT, Executive, HR, Procurement)
+
+### Admin-Konsole
+
+```
+http://localhost:8080
+Benutzer: admin
+Passwort: admin
+```
+
+---
+
+## Umgebungsvariablen
+
+### Docker (`docker/.env`)
+
+| Variable | Beschreibung | Standard |
+|----------|-------------|----------|
+| `POSTGRES_USER` | Datenbankbenutzer | `tos_user` |
+| `POSTGRES_PASSWORD` | Datenbankpasswort | `tos_secret_password` |
+| `POSTGRES_DB` | Keycloak-Datenbank | `tos_db` |
+| `KEYCLOAK_ADMIN` | Keycloak-Admin | `admin` |
+| `KEYCLOAK_ADMIN_PASSWORD` | Keycloak-Admin-Passwort | `admin` |
+
+### Backend (`apps/api/.env`)
+
+| Variable | Beschreibung |
+|----------|-------------|
+| `DATABASE_URL` | PostgreSQL Connection String (tos_app) |
+| `PORT` | API-Port (3001) |
+| `JWT_SECRET` | JWT-Signaturschluessel |
+| `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) |
+| `SWAGGER_ENABLED` | Swagger UI aktivieren |
+| `ENABLE_SYNC_JOBS` | Integrations-Sync aktivieren |
+
+### Frontend (`apps/web/.env`)
+
+| Variable | Beschreibung |
+|----------|-------------|
+| `NEXT_PUBLIC_API_URL` | Backend-API-URL |
+| `NEXT_PUBLIC_APP_URL` | Frontend-URL |
+| `NEXTAUTH_URL` | NextAuth-Callback-URL |
+| `NEXTAUTH_SECRET` | NextAuth-Signaturschluessel |
+| `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.
+
+---
+
+## Lizenz
+
+Proprietary - Tradeo GmbH. Alle Rechte vorbehalten.