mehmed/teOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
068446fbbfe87949425d144d24ea4bb0c6041350
teOS/README.md
Flexomatic81 068446fbbf 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

459 lines
14 KiB
Markdown
Raw Blame History

# 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
- [Überblick](#überblick)
- [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)
---
## Überblick
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) |
---
## Projektstruktur
```
tOS/
├── apps/
│ ├── web/ # Next.js 14 Frontend (Port 3000)
│ │ ├── src/
│ │ │ ├── app/[locale]/ # App Router mit i18n
│ │ │ │ ├── (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 Übersetzungen (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
│ │ │ ├── user-preferences/ # Benutzereinstellungen
│ │ │ └── audit/ # Audit-Logging
│ │ └── common/ # Filter, Interceptors, Pipes
│ └── prisma/ # Schema, Migrations, Seed
│
├── packages/
│ └── shared/ # Gemeinsame Typen & Utilities
│
├── docs/
│ └── integrations/ # API-Dokumentationen (z.B. PlentyONE Swagger)
│
├── 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
# 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 benötigten 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 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;"
```
### 6. Datenbank-Schema anwenden
```bash
pnpm db:push
```
### 7. Datenbank mit Stammdaten befüllen
```bash
pnpm db:seed
```
Erstellt Rollen (admin, hr-manager, team-lead, employee), Abteilungen und einen Entwickler-Admin-Benutzer.
### 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
```
| 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-Prüfung |
| `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 ausführen |
| `pnpm db:seed` | Stammdaten einspielen |
| `pnpm db:studio` | Prisma Studio öffnen |
### Docker
| Script | Beschreibung |
|--------|-------------|
| `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 zurücksetzen |
---
## Architektur
### Authentifizierung
```
Browser → Next.js (NextAuth) → Keycloak (OAuth2/OIDC)
│
▼
Browser → Next.js → NestJS API (JWT Guard) → Keycloak (Token-Validierung)
```
- **Frontend:** NextAuth mit Keycloak-Provider, automatische Weiterleitung zum Keycloak-Login
- **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` | 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 über die Datenbank angepasst werden kann.
### Frontend-Architektur
- **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
---
## Module
### Dashboard
Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfügbare Widgets:
| Widget | Beschreibung |
|--------|-------------|
| Welcome | Begrüßung mit Benutzerinfo |
| Clock | Digitale Uhr |
| Stats | KPI-Statistiken |
| Quick Actions | Schnellzugriff auf häufige Aktionen |
| Calendar | Kalenderübersicht |
| Activity | Aktivitätsfeed |
| 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, Übersichten pro Mitarbeiter
- **Abwesenheiten** - Anträge, Genehmigungen, Kalenderansicht
- **Organigramm** - Visuelle Unternehmensstruktur
### LEAN-Modul
- **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
### Integrations-Modul
7 externe Systeme mit einheitlicher Connector-Architektur:
| System | Typ | Funktionen |
|--------|-----|-----------|
| **PlentyONE** | ERP | Bestellungen, Artikel, Kontakte |
| **Zulip** | Chat | Nachrichten, Streams, Präsenz |
| **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 verfügbar:
```
http://localhost:3001/api/docs
```
Authentifizierung erfolgt über 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-Übersicht
| 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
```
Öffnet 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-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
**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-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-Schlüssel (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-Signaturschlüssel |
| `KEYCLOAK_CLIENT_ID` | Frontend-Client-ID |
| `KEYCLOAK_CLIENT_SECRET` | Frontend-Client-Secret |
| `KEYCLOAK_ISSUER` | Keycloak Issuer-URL |
Vollständige Beispiele befinden sich in den jeweiligen `.env.example`-Dateien.
---
## Lizenz
Proprietary - Tradeo GmbH. Alle Rechte vorbehalten.
Reference in New Issue View Git Blame Copy Permalink