mehmed/teOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README.md and add PlentyONE API spec

Browse Source 
- 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>
This commit is contained in:
Flexomatic81
2026-02-12 15:56:48 +01:00
parent 35cc24c5ec
commit 068446fbbf
2 changed files with 57 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@@ -13,7 +13,7 @@ Ein webbasiertes Enterprise-Dashboard, das verschiedene Unternehmenssysteme inte
## Inhaltsverzeichnis ## Inhaltsverzeichnis
- [Ueberblick](#ueberblick) - [Überblick](#überblick)
- [Tech-Stack](#tech-stack) - [Tech-Stack](#tech-stack)
- [Projektstruktur](#projektstruktur) - [Projektstruktur](#projektstruktur)
- [Voraussetzungen](#voraussetzungen) - [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: 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 | | **Auth** | Keycloak 24, NextAuth 4 |
| **Infrastruktur** | Docker Compose, pnpm 9, Turborepo | | **Infrastruktur** | Docker Compose, pnpm 9, Turborepo |
| **Sprachen** | TypeScript 5.6, i18n via next-intl (DE/EN) | | **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) │ ├── web/ # Next.js 14 Frontend (Port 3000)
│ │ ├── src/ │ │ ├── src/
│ │ │ ├── app/[locale]/ # App Router mit i18n │ │ │ ├── app/[locale]/ # App Router mit i18n
│ │ │ │ ├── (auth)/ # Geschuetzte Routen │ │ │ │ ├── (auth)/ # Geschützte Routen
│ │ │ │ └── login/ # Oeffentliche Login-Seite │ │ │ │ └── login/ # Öffentliche Login-Seite
│ │ │ ├── components/ # React-Komponenten (ui, layout, dashboard, hr, lean) │ │ │ ├── components/ # React-Komponenten (ui, layout, dashboard, hr, lean)
│ │ │ ├── hooks/ # Custom Hooks (hr, lean, integrations) │ │ │ ├── hooks/ # Custom Hooks (hr, lean, integrations)
│ │ │ ├── lib/ # Utilities, API-Client, Auth-Config │ │ │ ├── lib/ # Utilities, API-Client, Auth-Config
│ │ │ ├── stores/ # Zustand State Management │ │ │ ├── stores/ # Zustand State Management
│ │ │ └── types/ # TypeScript-Typen │ │ │ └── types/ # TypeScript-Typen
│ │ └── messages/ # i18n Uebersetzungen (de.json, en.json) │ │ └── messages/ # i18n Übersetzungen (de.json, en.json)
│ │ │ │
│ └── api/ # NestJS 10 Backend (Port 3001) │ └── api/ # NestJS 10 Backend (Port 3001)
│ ├── src/ │ ├── src/
@@ -81,6 +80,7 @@ tOS/
│ │ │ ├── integrations/ # 7 API-Connectoren + Sync │ │ │ ├── integrations/ # 7 API-Connectoren + Sync
│ │ │ ├── dashboard/ # Widget-Daten & Statistiken │ │ │ ├── dashboard/ # Widget-Daten & Statistiken
│ │ │ ├── departments/# Abteilungsverwaltung │ │ │ ├── departments/# Abteilungsverwaltung
│ │ │ ├── user-preferences/ # Benutzereinstellungen
│ │ │ └── audit/ # Audit-Logging │ │ │ └── audit/ # Audit-Logging
│ │ └── common/ # Filter, Interceptors, Pipes │ │ └── common/ # Filter, Interceptors, Pipes
│ └── prisma/ # Schema, Migrations, Seed │ └── prisma/ # Schema, Migrations, Seed
@@ -88,6 +88,9 @@ tOS/
├── packages/ ├── packages/
│ └── shared/ # Gemeinsame Typen & Utilities │ └── shared/ # Gemeinsame Typen & Utilities
│ │
├── docs/
│ └── integrations/ # API-Dokumentationen (z.B. PlentyONE Swagger)
│
├── docker/ ├── docker/
│ ├── docker-compose.yml # PostgreSQL, Redis, Keycloak │ ├── docker-compose.yml # PostgreSQL, Redis, Keycloak
│ ├── keycloak/ # Realm-Export & Config │ ├── keycloak/ # Realm-Export & Config
@@ -127,9 +130,6 @@ pnpm install
### 3. Environment-Variablen einrichten ### 3. Environment-Variablen einrichten
```bash ```bash
# Root
cp .env.example .env
# Docker # Docker
cp docker/.env.example docker/.env 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 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 ### 4. Docker-Services starten
@@ -152,7 +152,7 @@ Startet PostgreSQL (5432), Redis (6379) und Keycloak (8080).
### 5. Anwendungs-Datenbank erstellen ### 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 ```bash
docker exec -it tos-postgres psql -U tos_user -d tos_db -c "CREATE DATABASE tos_app;" 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 pnpm db:push
``` ```
### 7. Datenbank mit Stammdaten befuellen ### 7. Datenbank mit Stammdaten befüllen
```bash ```bash
pnpm db:seed pnpm db:seed
@@ -172,7 +172,15 @@ pnpm db:seed
Erstellt Rollen (admin, hr-manager, team-lead, employee), Abteilungen und einen Entwickler-Admin-Benutzer. 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 ```bash
pnpm dev pnpm dev
@@ -197,7 +205,7 @@ pnpm dev
| `pnpm dev:web` | Nur Frontend starten | | `pnpm dev:web` | Nur Frontend starten |
| `pnpm dev:api` | Nur Backend starten | | `pnpm dev:api` | Nur Backend starten |
| `pnpm build` | Alle Apps bauen | | `pnpm build` | Alle Apps bauen |
| `pnpm typecheck` | TypeScript-Pruefung | | `pnpm typecheck` | TypeScript-Prüfung |
| `pnpm lint` | Code-Linting | | `pnpm lint` | Code-Linting |
| `pnpm format` | Code-Formatierung | | `pnpm format` | Code-Formatierung |
@@ -207,9 +215,9 @@ pnpm dev
|--------|-------------| |--------|-------------|
| `pnpm db:generate` | Prisma Client generieren | | `pnpm db:generate` | Prisma Client generieren |
| `pnpm db:push` | Schema in die Datenbank pushen | | `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:seed` | Stammdaten einspielen |
| `pnpm db:studio` | Prisma Studio oeffnen | | `pnpm db:studio` | Prisma Studio öffnen |
### Docker ### Docker
@@ -217,16 +225,9 @@ pnpm dev
|--------|-------------| |--------|-------------|
| `pnpm docker:up` | Container starten | | `pnpm docker:up` | Container starten |
| `pnpm docker:down` | Container stoppen | | `pnpm docker:down` | Container stoppen |
| `pnpm docker:ps` | Container-Status anzeigen |
| `pnpm docker:logs` | Container-Logs anzeigen | | `pnpm docker:logs` | Container-Logs anzeigen |
| `pnpm docker:reset` | Container + Volumes zuruecksetzen | | `pnpm docker:reset` | Container + Volumes zurücksetzen |
### Tests
| Script | Beschreibung |
|--------|-------------|
| `pnpm test` | Alle Tests ausfuehren |
| `pnpm test:watch` | Tests im Watch-Modus |
| `pnpm test:e2e` | End-to-End-Tests |
--- ---
@@ -235,15 +236,15 @@ pnpm dev
### Authentifizierung ### Authentifizierung
``` ```
Browser -> Next.js (NextAuth) -> Keycloak (OAuth2/OIDC) Browser → Next.js (NextAuth) → Keycloak (OAuth2/OIDC)
| │
v ▼
Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung) 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) - **Backend:** Passport-JWT mit globalem Guard (`@Public()` zum Deaktivieren)
- **Guard-Kette:** JWT -> Rollen -> Permissions - **Guard-Kette:** JWT → Rollen → Permissions
### Rollen-System ### Rollen-System
@@ -251,19 +252,19 @@ Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung)
|-------|-------------| |-------|-------------|
| `admin` | Vollzugriff auf alle Bereiche | | `admin` | Vollzugriff auf alle Bereiche |
| `hr-manager` | HR-Verwaltung + LEAN-Zugriff | | `hr-manager` | HR-Verwaltung + LEAN-Zugriff |
| `manager` | Abteilungsuebergreifende Sicht | | `manager` | Abteilungsübergreifende Sicht |
| `department_head` | Abteilungsleitung | | `department_head` | Abteilungsleitung |
| `team-lead` | Teamleitung mit direkten Reports | | `team-lead` | Teamleitung mit direkten Reports |
| `employee` | Standard-Mitarbeiterzugriff | | `employee` | Standard-Mitarbeiterzugriff |
### Permissions ### 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 ### Frontend-Architektur
- **App Router** mit `[locale]` Segment fuer i18n - **App Router** mit `[locale]` Segment für i18n
- **Server/Client Split:** `page.tsx` (Server) -> `*-content.tsx` (Client) - **Server/Client Split:** `page.tsx` (Server) → `*-content.tsx` (Client)
- **State Management:** Zustand (UI-State), TanStack Query (Server-State) - **State Management:** Zustand (UI-State), TanStack Query (Server-State)
- **Component Library:** shadcn/ui auf Radix UI Basis - **Component Library:** shadcn/ui auf Radix UI Basis
@@ -273,16 +274,16 @@ Feingranulare Berechtigungen pro Modul (z.B. `EMPLOYEES_VIEW`, `ABSENCES_APPROVE
### Dashboard ### Dashboard
Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets: Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfügbare Widgets:
| Widget | Beschreibung | | Widget | Beschreibung |
|--------|-------------| |--------|-------------|
| Welcome | Begruessung mit Benutzerinfo | | Welcome | Begrüßung mit Benutzerinfo |
| Clock | Digitale Uhr | | Clock | Digitale Uhr |
| Stats | KPI-Statistiken | | Stats | KPI-Statistiken |
| Quick Actions | Schnellzugriff auf haeufige Aktionen | | Quick Actions | Schnellzugriff auf häufige Aktionen |
| Calendar | Kalenderuebersicht | | Calendar | Kalenderübersicht |
| Activity | Aktivitaetsfeed | | Activity | Aktivitätsfeed |
| Orders | PlentyONE Bestellungen | | Orders | PlentyONE Bestellungen |
| Chat | Zulip Nachrichten | | Chat | Zulip Nachrichten |
| Tasks | Todoist Aufgaben | | Tasks | Todoist Aufgaben |
@@ -294,13 +295,13 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
### HR-Modul ### HR-Modul
- **Mitarbeiterverwaltung** - CRUD, Detailansicht, Neuanlage - **Mitarbeiterverwaltung** - CRUD, Detailansicht, Neuanlage
- **Zeiterfassung** - Stempeluhr, Uebersichten pro Mitarbeiter - **Zeiterfassung** - Stempeluhr, Übersichten pro Mitarbeiter
- **Abwesenheiten** - Antraege, Genehmigungen, Kalenderansicht - **Abwesenheiten** - Anträge, Genehmigungen, Kalenderansicht
- **Organigramm** - Visuelle Unternehmensstruktur - **Organigramm** - Visuelle Unternehmensstruktur
### LEAN-Modul ### 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) - **Morning Meeting** - SQCDM-Board (Safety, Quality, Cost, Delivery, Morale)
- **Skill Matrix** - Kompetenzerfassung und -bewertung pro Abteilung - **Skill Matrix** - Kompetenzerfassung und -bewertung pro Abteilung
@@ -311,7 +312,7 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
| System | Typ | Funktionen | | System | Typ | Funktionen |
|--------|-----|-----------| |--------|-----|-----------|
| **PlentyONE** | ERP | Bestellungen, Artikel, Kontakte | | **PlentyONE** | ERP | Bestellungen, Artikel, Kontakte |
| **Zulip** | Chat | Nachrichten, Streams, Praesenz | | **Zulip** | Chat | Nachrichten, Streams, Präsenz |
| **Todoist** | Tasks | Aufgaben, Projekte | | **Todoist** | Tasks | Aufgaben, Projekte |
| **FreeScout** | Helpdesk | Tickets, Konversationen | | **FreeScout** | Helpdesk | Tickets, Konversationen |
| **Nextcloud** | Cloud | Dateien, Ordner, Freigaben | | **Nextcloud** | Cloud | Dateien, Ordner, Freigaben |
@@ -328,13 +329,13 @@ Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:
## API-Dokumentation ## 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 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 - `auth` - Authentifizierung
- `users` - Benutzerverwaltung - `users` - Benutzerverwaltung
@@ -357,7 +358,7 @@ Authentifizierung erfolgt ueber Bearer JWT-Token. Die API ist in folgende Bereic
Beide laufen auf derselben PostgreSQL-Instanz. Beide laufen auf derselben PostgreSQL-Instanz.
### Schema-Uebersicht ### Schema-Übersicht
| Bereich | Modelle | | Bereich | Modelle |
|---------|---------| |---------|---------|
@@ -373,7 +374,7 @@ Beide laufen auf derselben PostgreSQL-Instanz.
pnpm db:studio 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 | | Client | Typ | Verwendung |
|--------|-----|-----------| |--------|-----|-----------|
| `tos-frontend` | Confidential | NextAuth (Frontend-Authentifizierung) | | `tos-nextauth` | Confidential | NextAuth (Frontend-Authentifizierung) |
| `tos-backend` | Confidential | NestJS (Service-Account, Token-Validierung) | | `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 ### Rollen & Gruppen
**Realm-Rollen:** admin, hr-manager, manager, department_head, team-lead, employee **Realm-Rollen:** admin, hr-manager, manager, department_head, team-lead, employee
@@ -424,13 +427,13 @@ Passwort: admin
|----------|-------------| |----------|-------------|
| `DATABASE_URL` | PostgreSQL Connection String (tos_app) | | `DATABASE_URL` | PostgreSQL Connection String (tos_app) |
| `PORT` | API-Port (3001) | | `PORT` | API-Port (3001) |
| `JWT_SECRET` | JWT-Signaturschluessel | | `JWT_SECRET` | JWT-Signaturschlüssel |
| `KEYCLOAK_URL` | Keycloak-URL | | `KEYCLOAK_URL` | Keycloak-URL |
| `KEYCLOAK_REALM` | Realm-Name (tOS) | | `KEYCLOAK_REALM` | Realm-Name (tOS) |
| `KEYCLOAK_CLIENT_ID` | Backend-Client-ID | | `KEYCLOAK_CLIENT_ID` | Backend-Client-ID |
| `KEYCLOAK_CLIENT_SECRET` | Backend-Client-Secret | | `KEYCLOAK_CLIENT_SECRET` | Backend-Client-Secret |
| `REDIS_HOST` / `REDIS_PORT` | Redis-Verbindung | | `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 | | `SWAGGER_ENABLED` | Swagger UI aktivieren |
| `ENABLE_SYNC_JOBS` | Integrations-Sync aktivieren | | `ENABLE_SYNC_JOBS` | Integrations-Sync aktivieren |
@@ -441,12 +444,12 @@ Passwort: admin
| `NEXT_PUBLIC_API_URL` | Backend-API-URL | | `NEXT_PUBLIC_API_URL` | Backend-API-URL |
| `NEXT_PUBLIC_APP_URL` | Frontend-URL | | `NEXT_PUBLIC_APP_URL` | Frontend-URL |
| `NEXTAUTH_URL` | NextAuth-Callback-URL | | `NEXTAUTH_URL` | NextAuth-Callback-URL |
| `NEXTAUTH_SECRET` | NextAuth-Signaturschluessel | | `NEXTAUTH_SECRET` | NextAuth-Signaturschlüssel |
| `KEYCLOAK_CLIENT_ID` | Frontend-Client-ID | | `KEYCLOAK_CLIENT_ID` | Frontend-Client-ID |
| `KEYCLOAK_CLIENT_SECRET` | Frontend-Client-Secret | | `KEYCLOAK_CLIENT_SECRET` | Frontend-Client-Secret |
| `KEYCLOAK_ISSUER` | Keycloak Issuer-URL | | `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.
--- ---

1
docs/integrations/plentymarkets-api.json Normal file
View File

File diff suppressed because one or more lines are too long