Skip to content

W
Web-CoreX
Commit eb4a5c21 authored by Hendrik Garske's avatar Hendrik Garske
Browse files
Options

docs: Umfassende README mit vollständiger Dokumentation

parent c57bc574
Pipeline #13 passed with stages
      in 1 minute and 52 seconds
      Hide whitespace changes
      Inline Side-by-side
      Showing with 390 additions and 87 deletions
      README.md
      View file @ eb4a5c21
      # CoreX Management Dashboard
      Internes Dashboard für CoreX Management Mitarbeiter mit Zeiterfassung und Kundenverwaltung.
      > Internes Management-Dashboard für CoreX Management mit Zeiterfassung und Kundenverwaltung
      [![Next.js](https://img.shields.io/badge/Next.js-16.1.1-black)](https://nextjs.org/)
      [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
      [![Prisma](https://img.shields.io/badge/Prisma-6.19-2D3748)](https://www.prisma.io/)
      [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Latest-336791)](https://www.postgresql.org/)
      ## 📋 Inhaltsverzeichnis
      - [Überblick](#überblick)
      - [Features](#features)
      - [Tech Stack](#tech-stack)
      - [Voraussetzungen](#voraussetzungen)
      - [Installation](#installation)
      - [Konfiguration](#konfiguration)
      - [Datenbank Setup](#datenbank-setup)
      - [Entwicklung](#entwicklung)
      - [Projektstruktur](#projektstruktur)
      - [API Dokumentation](#api-dokumentation)
      - [Deployment](#deployment)
      - [Mitwirken](#mitwirken)
      ## 🎯 Überblick
      Das CoreX Management Dashboard ist eine interne Webanwendung zur Verwaltung von Arbeitszeiten und Kundenbeziehungen. Es bietet Mitarbeitern eine intuitive Oberfläche zur Zeiterfassung und umfassende Funktionen zur Kundenverwaltung.
      ## ✨ Features
      ### Zeiterfassung
      - ⏱️ **Timer-Funktionalität**: Start/Stop/Pause/Weiter
      - 📝 **Manuelle Zeiterfassung**: Direktes Eintragen von Stunden
      - 👥 **Kunden-Zuordnung**: Jeder Zeiteintrag wird einem Kunden zugeordnet
      - 📊 **Filter & Sortierung**: Nach Datum, Kunde, Dauer oder Beschreibung
      - 📈 **Übersicht**: Gesamtstunden und detaillierte Statistiken
      ### Kundenverwaltung
      - ➕ **CRUD-Operationen**: Vollständige Verwaltung von Kundendaten
      - 📧 **Kontaktdaten**: E-Mail, Telefon, Adresse, Unternehmen
      - 📝 **Notizen**: Freitext-Notizen zu jedem Kunden
      - 🔍 **Suche**: Schnelle Suche nach Name, E-Mail, Unternehmen oder Telefon
      - 📊 **Zeitübersicht**: Anzeige aller Zeiteinträge pro Kunde mit Statistiken
      ### Weitere Features
      - 🌓 **Dark Mode**: Automatischer Dark/Light Mode mit Theme-Toggle
      - 📱 **Responsive Design**: Optimiert für Desktop, Tablet und Mobile
      - 🔒 **Sicherheit**: Vorbereitet für SSO-Authentifizierung
      - ⚡ **Performance**: Optimiert mit Next.js App Router
      ## 🛠 Tech Stack
      - **Framework**: [Next.js 16.1.1](https://nextjs.org/) (App Router)
      - **Sprache**: [TypeScript 5.0](https://www.typescriptlang.org/)
      - **Styling**: [Tailwind CSS v4](https://tailwindcss.com/)
      - **Datenbank**: [PostgreSQL](https://www.postgresql.org/)
      - **ORM**: [Prisma 6.19](https://www.prisma.io/)
      - **UI Components**:
      - [Radix UI](https://www.radix-ui.com/)
      - [Lucide Icons](https://lucide.dev/)
      - **State Management**: React Hooks
      - **Theme**: [next-themes](https://github.com/pacocoursey/next-themes)
      ## 📦 Voraussetzungen
      - **Node.js**: Version 20 oder höher
      - **PostgreSQL**: Version 12 oder höher
      - **npm** oder **yarn** oder **pnpm**
      - **Git** (für Clone)
      ## 🚀 Installation
      ### 1. Repository klonen
      ## Features
      - ✅ **Zeiterfassung**: Timer-basierte und manuelle Zeiterfassung
      - ✅ **Kundenverwaltung**: Vollständige CRUD-Funktionalität für Kunden
      - ✅ **Datenbank**: SQLite mit Prisma ORM
      - ✅ **Dark Mode**: Unterstützung für Light/Dark Theme
      - ✅ **Filter & Sortierung**: Erweiterte Filter- und Sortierfunktionen
      ## Tech Stack
      - **Framework**: Next.js 16.1.1 (App Router)
      - **Language**: TypeScript
      - **Styling**: Tailwind CSS v4
      - **Database**: PostgreSQL mit Prisma ORM
      - **UI Components**: Radix UI, Lucide Icons
      ## Getting Started
      ### Voraussetzungen
      - Node.js 20 oder höher
      - npm oder yarn
      ### Installation
      1. Repository klonen:
      ```bash
      git clone https://gitlab.corexmanagement.de/HendrikGarske/web-corex.git
      cd web-corex
      ```
      2. Dependencies installieren:
      ### 2. Dependencies installieren
      ```bash
      npm install
      # oder
      yarn install
      # oder
      pnpm install
      ```
      3. Umgebungsvariablen einrichten:
      ### 3. Umgebungsvariablen konfigurieren
      Erstellen Sie eine `.env` Datei im Root-Verzeichnis:
      ```bash
      cp .env.example .env # Falls vorhanden
      # oder manuell erstellen
      ```
      Fügen Sie folgende Variablen hinzu:
      ```env
      DATABASE_URL="postgresql://username:password@localhost:5432/corex_dashboard?schema=public"
      ```
      **Datenbank einrichten:**
      - Stellen Sie sicher, dass PostgreSQL installiert und laufend ist
      - Erstellen Sie eine neue Datenbank:
      ```sql
      CREATE DATABASE corex_dashboard;
      ```
      ### 4. Datenbank Setup
      Siehe [Datenbank Setup](#datenbank-setup) für detaillierte Anweisungen.
      ### 5. Datenbank initialisieren
      4. Datenbank initialisieren:
      ```bash
      # Prisma Client generieren
      npx prisma generate
      # Migrationen ausführen
      npx prisma migrate dev
      ```
      5. Development Server starten:
      ### 6. Development Server starten
      ```bash
      npm run dev
      ```
      Die Anwendung läuft dann auf [http://localhost:3000](http://localhost:3000)
      Die Anwendung läuft jetzt auf [http://localhost:3000](http://localhost:3000)
      ## ⚙️ Konfiguration
      ### Umgebungsvariablen
      ## Projektstruktur
      | Variable | Beschreibung | Beispiel |
      |----------|--------------|----------|
      | `DATABASE_URL` | PostgreSQL Verbindungs-URL | `postgresql://user:pass@localhost:5432/dbname` |
      ### Datenbank-URL Format
      ```
      ├── app/
      │ ├── api/ # API Routes
      │ │ ├── customers/ # Kunden-API
      │ │ ├── time-entries/ # Zeiterfassungs-API
      │ │ └── users/ # Benutzer-API
      │ ├── kunden/ # Kunden-Verwaltungsseiten
      │ ├── zeiterfassung/ # Zeiterfassungsseite
      │ └── page.tsx # Dashboard-Hauptseite
      ├── components/ # React Komponenten
      │ ├── ui/ # UI-Komponenten (Button, Card, Input, etc.)
      │ └── ...
      ├── lib/ # Utility-Funktionen
      │ ├── prisma.ts # Prisma Client
      │ └── utils.ts # Helper-Funktionen
      └── prisma/ # Datenbank-Schema und Migrations
      └── schema.prisma
      postgresql://[user]:[password]@[host]:[port]/[database]?schema=public
      ```
      ## Scripts
      ## 🗄️ Datenbank Setup
      - `npm run dev` - Development Server starten
      - `npm run build` - Production Build erstellen
      - `npm run start` - Production Server starten
      - `npm run lint` - ESLint ausführen
      - `npx prisma studio` - Prisma Studio öffnen (Datenbank-Viewer)
      ### PostgreSQL Installation
      ## Datenbank
      #### Windows
      1. Laden Sie PostgreSQL von [postgresql.org/download/windows](https://www.postgresql.org/download/windows/)
      2. Führen Sie den Installer aus
      3. Notieren Sie sich das Master-Passwort
      Das Projekt verwendet Prisma ORM mit PostgreSQL. Die Datenbank-Schema-Definitionen befinden sich in `prisma/schema.prisma`.
      #### macOS
      ```bash
      brew install postgresql
      brew services start postgresql
      ```
      ### PostgreSQL Setup
      #### Linux (Ubuntu/Debian)
      ```bash
      sudo apt-get update
      sudo apt-get install postgresql postgresql-contrib
      sudo systemctl start postgresql
      ```
      1. **PostgreSQL installieren** (falls nicht vorhanden):
      - Windows: https://www.postgresql.org/download/windows/
      - macOS: `brew install postgresql`
      - Linux: `sudo apt-get install postgresql`
      ### Datenbank erstellen
      2. **Datenbank erstellen**:
      1. **PostgreSQL Terminal öffnen**:
      ```bash
      # PostgreSQL Terminal öffnen
      psql -U postgres
      ```
      # Datenbank erstellen
      2. **Datenbank erstellen**:
      ```sql
      CREATE DATABASE corex_dashboard;
      ```
      # Benutzer erstellen (optional, aber empfohlen)
      CREATE USER corex_user WITH PASSWORD 'your_secure_password';
      3. **(Optional) Benutzer erstellen** (empfohlen für Produktion):
      ```sql
      CREATE USER corex_user WITH PASSWORD 'ihr_sicheres_passwort';
      GRANT ALL PRIVILEGES ON DATABASE corex_dashboard TO corex_user;
      \q
      ```
      3. **DATABASE_URL in .env setzen**:
      4. **DATABASE_URL in .env aktualisieren**:
      ```env
      DATABASE_URL="postgresql://corex_user:your_secure_password@localhost:5432/corex_dashboard?schema=public"
      DATABASE_URL="postgresql://corex_user:ihr_sicheres_passwort@localhost:5432/corex_dashboard?schema=public"
      ```
      ### Migrationen
      ### Migrationen ausführen
      Neue Migrationen erstellen:
      ```bash
      npx prisma migrate dev --name migration_name
      # Initiale Migration
      npx prisma migrate dev --name init
      # Weitere Migrationen (nach Schema-Änderungen)
      npx prisma migrate dev --name beschreibung_der_aenderung
      ```
      ### Prisma Studio (Datenbank-Viewer)
      ```bash
      npx prisma studio
      ```
      Datenbank zurücksetzen (⚠️ löscht alle Daten):
      Öffnet einen Browser-basierten Datenbank-Viewer auf [http://localhost:5555](http://localhost:5555)
      ## 💻 Entwicklung
      ### Verfügbare Scripts
      ```bash
      # Development Server starten
      npm run dev
      # Production Build erstellen
      npm run build
      # Production Server starten
      npm run start
      # ESLint ausführen
      npm run lint
      # Prisma Client generieren
      npx prisma generate
      # Neue Migration erstellen
      npx prisma migrate dev --name migration_name
      # Datenbank zurücksetzen (⚠️ löscht alle Daten)
      npx prisma migrate reset
      # Prisma Studio öffnen
      npx prisma studio
      ```
      ### Entwicklungsworkflow
      1. **Feature-Branch erstellen**:
      ```bash
      git checkout -b feature/mein-feature
      ```
      2. **Änderungen machen und committen**:
      ```bash
      git add .
      git commit -m "feat: Beschreibung des Features"
      ```
      ## Entwicklung
      3. **Push und Merge Request erstellen**:
      ```bash
      git push origin feature/mein-feature
      ```
      ### Neue Module hinzufügen
      4. **Nach Merge: Branch löschen**:
      ```bash
      git checkout main
      git pull
      git branch -d feature/mein-feature
      ```
      1. Erstellen Sie eine neue Seite in `app/[modul-name]/page.tsx`
      2. Fügen Sie API-Routen in `app/api/[modul-name]/route.ts` hinzu
      3. Aktualisieren Sie das Dashboard in `app/page.tsx` mit einem Link zum neuen Modul
      ### Code-Stil
      ### Authentifizierung
      - TypeScript strict mode aktiviert
      - ESLint für Code-Qualität
      - Prettier (empfohlen) für Code-Formatierung
      Die Authentifizierung/SSO ist noch nicht implementiert. Die Middleware-Struktur ist in `middleware.ts` vorbereitet.
      ## 📁 Projektstruktur
      ## License
      ```
      corex-dashboard/
      ├── app/ # Next.js App Router
      │ ├── api/ # API Routes
      │ │ ├── customers/ # Kunden-API
      │ │ ├── time-entries/ # Zeiterfassungs-API
      │ │ └── users/ # Benutzer-API
      │ ├── kunden/ # Kunden-Verwaltungsseiten
      │ │ └── [id]/ # Kunden-Detailseite
      │ ├── zeiterfassung/ # Zeiterfassungsseite
      │ ├── layout.tsx # Root Layout
      │ ├── page.tsx # Dashboard-Hauptseite
      │ └── globals.css # Globale Styles
      ├── components/ # React Komponenten
      │ ├── ui/ # Wiederverwendbare UI-Komponenten
      │ │ ├── button.tsx
      │ │ ├── card.tsx
      │ │ ├── input.tsx
      │ │ ├── label.tsx
      │ │ ├── select.tsx
      │ │ └── textarea.tsx
      │ ├── Logo.tsx # Logo-Komponente
      │ ├── theme-provider.tsx # Theme-Provider
      │ └── theme-toggle.tsx # Theme-Toggle Button
      ├── lib/ # Utility-Funktionen
      │ ├── prisma.ts # Prisma Client Singleton
      │ └── utils.ts # Helper-Funktionen (cn, etc.)
      ├── prisma/ # Prisma Konfiguration
      │ ├── migrations/ # Datenbank-Migrationen
      │ └── schema.prisma # Datenbank-Schema
      ├── public/ # Statische Assets
      │ ├── branding/ # Logo-Varianten
      │ └── logo.png # Hauptlogo
      ├── .gitignore
      ├── .gitlab-ci.yml # GitLab CI/CD Konfiguration
      ├── next.config.ts # Next.js Konfiguration
      ├── package.json
      ├── tsconfig.json # TypeScript Konfiguration
      └── README.md
      ```
      ## 🔌 API Dokumentation
      ### Kunden API
      #### GET `/api/customers`
      Liste aller Kunden abrufen
      **Query Parameter:**
      - `search` (optional): Suchbegriff für Name, E-Mail oder Unternehmen
      **Response:**
      ```json
      [
      {
      "id": "string",
      "name": "string",
      "email": "string | null",
      "phone": "string | null",
      "company": "string | null",
      "address": "string | null",
      "notes": "string | null",
      "createdAt": "ISO-Date",
      "updatedAt": "ISO-Date",
      "timeEntries": [...]
      }
      ]
      ```
      #### POST `/api/customers`
      Neuen Kunden erstellen
      **Body:**
      ```json
      {
      "name": "string (required)",
      "email": "string (optional)",
      "phone": "string (optional)",
      "company": "string (optional)",
      "address": "string (optional)",
      "notes": "string (optional)"
      }
      ```
      #### GET `/api/customers/[id]`
      Kunde nach ID abrufen
      #### PUT `/api/customers/[id]`
      Kunde aktualisieren
      #### DELETE `/api/customers/[id]`
      Kunde löschen
      ### Zeiterfassungs API
      #### GET `/api/time-entries`
      Zeiteinträge abrufen
      **Query Parameter:**
      - `customerId` (optional): Filter nach Kunden-ID
      - `userId` (optional): Filter nach Benutzer-ID
      #### POST `/api/time-entries`
      Neuen Zeiteintrag erstellen
      **Body:**
      ```json
      {
      "description": "string (required)",
      "startTime": "ISO-Date (required)",
      "endTime": "ISO-Date (required)",
      "duration": "number (required, in seconds)",
      "customerId": "string (required)",
      "userId": "string (required)"
      }
      ```
      #### DELETE `/api/time-entries/[id]`
      Zeiteintrag löschen
      ## 🚢 Deployment
      ### GitLab CI/CD
      Das Projekt verwendet GitLab CI/CD für automatische Builds und Tests.
      **Pipeline Stages:**
      1. **Build**: Kompiliert TypeScript, generiert Prisma Client
      2. **Test**: Führt ESLint aus
      ### Umgebungsvariablen für Deployment
      Stellen Sie sicher, dass folgende Variablen in Ihrer Deployment-Umgebung gesetzt sind:
      - `DATABASE_URL`: PostgreSQL Verbindungs-URL
      - `NODE_ENV`: `production` für Produktion
      ### Build für Produktion
      ```bash
      npm run build
      npm run start
      ```
      ## 🔐 Authentifizierung
      Die Authentifizierung/SSO ist aktuell noch nicht implementiert. Die Middleware-Struktur ist in `middleware.ts` vorbereitet.
      **Geplante Implementierung:**
      - SSO-Integration (z.B. OAuth2, SAML)
      - Session-Management
      - Rollenbasierte Zugriffskontrolle
      ## 🤝 Mitwirken
      ### Pull Request Prozess
      1. Feature-Branch erstellen
      2. Änderungen implementieren
      3. Tests ausführen (`npm run lint`, `npm run build`)
      4. Merge Request in GitLab erstellen
      5. Code Review abwarten
      6. Nach Merge: Branch löschen
      ### Commit-Messages
      Verwenden Sie konventionelle Commit-Messages:
      - `feat:` Neue Funktion
      - `fix:` Bug-Fix
      - `docs:` Dokumentation
      - `style:` Code-Formatierung
      - `refactor:` Code-Refactoring
      - `test:` Tests hinzufügen/ändern
      - `chore:` Build-Prozess, Dependencies
      ## 📝 Lizenz
      Proprietär - CoreX Management
      ## 👥 Kontakt
      Bei Fragen oder Problemen wenden Sie sich bitte an das Entwicklungsteam.
      ---
      **Version**: 0.1.0
      **Letzte Aktualisierung**: 2024
      Markdown is supported
      0% or
      You are about to add 0 people to the discussion. Proceed with caution.
      Finish editing this message first!
      Please register or to comment