From 22c007a768faa5c0f61747af0bf0a4f1c36049d5 Mon Sep 17 00:00:00 2001 From: Sebastian Frick Date: Tue, 17 Feb 2026 22:15:35 +0100 Subject: [PATCH] docs: add TUI implementation plan documentation --- frontend/IMPLEMENTATION_PLAN.md | 386 ++++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 frontend/IMPLEMENTATION_PLAN.md diff --git a/frontend/IMPLEMENTATION_PLAN.md b/frontend/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..d6b2f73 --- /dev/null +++ b/frontend/IMPLEMENTATION_PLAN.md @@ -0,0 +1,386 @@ +# Implementation Plan: TypeScript TUI für Effigenix ERP + +**Status:** Phase 1 in Arbeit (50% abgeschlossen) +**Erstellt:** 2026-02-17 +**Letztes Update:** 2026-02-17 + +## Context + +Das Effigenix ERP-System verfügt über ein vollständig implementiertes Backend mit User Management (Authentication, CRUD, Role Management). Um die Backend-Funktionen ausgiebig zu testen, ohne sofort eine vollständige WebUI zu entwickeln, wird zunächst eine **Terminal User Interface (TUI)** in TypeScript erstellt. + +**Ziele:** +- Bequemes Testen aller Backend-Features über ein interaktives Terminal-Interface +- TypeScript-Entwicklung ermöglicht späteren Code-Sharing mit der WebUI +- Moderne, wartbare Architektur mit Fokus auf Wiederverwendbarkeit + +**Umfang (Erster Wurf):** +- ✅ Authentication & JWT-Handling (Login, Auto-Refresh, Logout) +- ✅ User Management (Create, Read, Update, List) +- ✅ Role & Permission Management (Assign/Remove Roles, Lock/Unlock Accounts) +- ✅ Password Management + +--- + +## Technologie-Stack + +| Kategorie | Technologie | Begründung | +|-----------|-------------|------------| +| **Package Manager** | pnpm workspaces | Schnell, effizient, exzellente TypeScript-Unterstützung | +| **UI Framework** | Ink 5 (React für Terminal) | React-Komponenten, Code-Sharing mit zukünftiger WebUI | +| **HTTP Client** | axios | Interceptor-Support für JWT-Handling | +| **Validation** | Zod | Runtime-Validation + TypeScript Type Inference | +| **CLI Framework** | yargs | Powerful CLI arg parsing, subcommands | +| **State Management** | React Context + useReducer | Einfach, keine zusätzlichen Dependencies | +| **Build Tool** | tsup | Schneller, zero-config TypeScript bundler | +| **Testing** | vitest | Vite-powered, Jest-kompatibel | + +--- + +## Monorepo-Struktur + +``` +/home/sebi/git/effigenix/ +├── backend/ # Java Backend +│ ├── src/ +│ ├── pom.xml +│ └── docs/ +│ +└── frontend/ # TypeScript Monorepo + ├── package.json # Root workspace config + ├── pnpm-workspace.yaml # Workspace definition + ├── tsconfig.base.json # Shared TypeScript config + ├── .eslintrc.js # Linting + ├── .prettierrc # Formatting + │ + ├── apps/ + │ └── cli/ # TUI Application + │ ├── src/ + │ │ ├── index.tsx # Entry point + │ │ ├── App.tsx # Root Ink component + │ │ ├── cli.ts # CLI command parser (yargs) + │ │ ├── components/ # UI components + │ │ │ ├── auth/ # LoginScreen, AuthProvider + │ │ │ ├── users/ # UserList, UserCreate, UserDetail, UserTable + │ │ │ ├── roles/ # RoleList, RoleAssign + │ │ │ ├── shared/ # Navigation, ErrorDisplay, LoadingSpinner, FormInput + │ │ │ └── layout/ # MainLayout, Header, StatusBar + │ │ ├── hooks/ # useAuth, useUsers, useRoles, useNavigation + │ │ ├── state/ # React Context (auth, navigation, app) + │ │ └── utils/ # token-storage, error-handler + │ └── package.json + │ + └── packages/ # Shared Packages (wiederverwendbar für WebUI) + ├── api-client/ # HTTP client für Effigenix API + │ ├── src/ + │ │ ├── client.ts # Base axios client + │ │ ├── interceptors/ # auth, error, refresh interceptors + │ │ ├── resources/ # auth.ts, users.ts, roles.ts + │ │ ├── config.ts # Client configuration + │ │ └── errors.ts # Custom error classes + │ └── package.json + │ + ├── types/ # TypeScript interfaces/DTOs ✅ DONE + │ ├── src/ + │ │ ├── generated/ # AUTO-GENERATED from OpenAPI + │ │ ├── auth.ts # LoginRequest, LoginResponse, SessionToken + │ │ ├── user.ts # User, UserDTO, CreateUserRequest, UpdateUserRequest + │ │ ├── role.ts # Role, RoleDTO, Permission, RoleName + │ │ ├── common.ts # ErrorResponse, ValidationError + │ │ └── enums.ts # UserStatus, Permission enum + │ └── package.json + │ + ├── validation/ # Zod schemas für Validation + │ ├── src/ + │ │ ├── schemas/ # auth.ts, user.ts, password.ts + │ │ └── validators.ts # Custom validators + │ └── package.json + │ + └── config/ # Shared configuration + ├── src/ + │ ├── api-config.ts # API base URL, timeouts + │ └── constants.ts # Shared constants + └── package.json +``` + +### Package-Abhängigkeiten + +``` +apps/cli + ↓ + ├── @effigenix/api-client + ├── @effigenix/types + ├── @effigenix/validation + └── @effigenix/config + +@effigenix/api-client + ↓ + ├── @effigenix/types + └── @effigenix/config + +@effigenix/validation + ↓ + └── @effigenix/types +``` + +--- + +## Implementierungsphasen + +### Phase 1: Foundation ⏳ IN PROGRESS (50% abgeschlossen) + +**Ziel:** Monorepo-Setup, Shared Packages, Type Definitions + +**Status:** +- ✅ Task 1: Monorepo initialisiert (pnpm-workspace.yaml, tsconfig.base.json, ESLint/Prettier) +- ✅ Task 2: Package `@effigenix/types` erstellt mit OpenAPI-Generierung +- 📋 Task 3: Package `@effigenix/config` erstellen +- 📋 Task 4: Package `@effigenix/validation` erstellen + +**Commits:** +- ✅ `refactor: restructure repository with separate backend and frontend directories` +- ✅ `feat: initialize frontend monorepo with pnpm workspace and types package` + +--- + +### Phase 2: API Client 📅 GEPLANT + +**Ziel:** Vollständiger HTTP-Client mit JWT-Handling + +**Aufgaben:** +1. Package `@effigenix/api-client` erstellen + - Base axios client mit TypeScript + - Interceptors: + - **AuthInterceptor:** JWT-Token an alle Requests anhängen + - **RefreshInterceptor:** Bei 401-Error automatisch Token refresh via `/api/auth/refresh` + - **ErrorInterceptor:** Backend `ErrorResponse` in `ApiError` umwandeln + +2. API Resource-Module implementieren + - `auth.ts`: `login()`, `logout()`, `refresh()` + - `users.ts`: `list()`, `getById()`, `create()`, `update()`, `lock()`, `unlock()`, `assignRole()`, `removeRole()`, `changePassword()` + - `roles.ts`: `list()` + +3. Custom Error Classes + - `ApiError` (code, message, status, validationErrors) + - `AuthenticationError` + - `NetworkError` + +4. Unit Tests (vitest) + - Mock axios responses + - Test Interceptor-Logik (Token-Refresh-Flow) + - Test Error-Handling + +**Kritische Dateien:** +- `packages/api-client/src/client.ts` +- `packages/api-client/src/interceptors/refresh-interceptor.ts` +- `packages/api-client/src/resources/auth.ts` + +**Geschätzte Dauer:** 1 Woche + +--- + +### Phase 3: TUI Core 📅 GEPLANT + +**Ziel:** Basis-TUI-App mit Authentication + +**Aufgaben:** +1. Package `apps/cli` erstellen + - CLI Entry Point (`src/cli.ts`) mit yargs + - Subcommands: `login`, `interactive` (default) + - Ink App-Struktur (`src/App.tsx`) + - React Context für State Management + +2. Authentication-Flow implementieren + - **LoginScreen Component** (ink-text-input für Username/Password) + - **JWT Storage** (Filesystem: `~/.effigenix/config.json`, Permissions 600) + - **AuthContext Provider** (isAuthenticated, user, loading) + - **Protected Route Wrapper** (redirect zu Login wenn nicht authentifiziert) + +3. Navigation implementieren + - **MainMenu Component** (nach Login) + - **Screen Router** (einfacher State-basierter Router) + - Keyboard Shortcuts (Pfeiltasten, Enter, B für Back) + +**Kritische Dateien:** +- `apps/cli/src/index.tsx` +- `apps/cli/src/components/auth/LoginScreen.tsx` +- `apps/cli/src/utils/token-storage.ts` +- `apps/cli/src/state/auth-context.tsx` + +**Geschätzte Dauer:** 1 Woche + +--- + +### Phase 4: User Management UI 📅 GEPLANT + +**Ziel:** Vollständiges User Management Interface + +**Aufgaben:** +1. **UserListScreen** - Table-View mit Navigation +2. **UserCreateScreen** - Formular mit Validation +3. **UserDetailScreen** - User-Details anzeigen +4. **ChangePasswordScreen** - Passwort ändern + +**Komponenten:** +- `UserListScreen.tsx`, `UserTable.tsx` +- `UserCreateScreen.tsx`, `UserDetailScreen.tsx` +- `LoadingSpinner.tsx`, `ErrorDisplay.tsx`, `FormInput.tsx` +- Hooks: `useUsers.ts` (wrapper um API Client) + +**Geschätzte Dauer:** 1 Woche + +--- + +### Phase 5: Role Management & Polish 📅 GEPLANT + +**Ziel:** Role Management + UX-Verbesserungen + +**Aufgaben:** +1. **RoleListScreen** - Liste aller Rollen +2. **RoleAssignScreen** - Rollen zuweisen/entfernen +3. **UX Improvements** + - Loading States überall + - Success/Error Notifications + - Confirmation Dialogs + - Bessere Error Messages + - StatusBar + +4. **Testing & Dokumentation** + - Integration Tests + - E2E-Flows testen + - User-Dokumentation + - Developer Guide + +**Geschätzte Dauer:** 1 Woche + +--- + +## JWT-Handling: Token-Refresh-Strategie + +### Speicherung +- **Location:** `~/.effigenix/config.json` (File Permissions 600) +- **Struktur:** `{ apiBaseUrl, auth: { accessToken, refreshToken, expiresAt } }` + +### Proaktiver Refresh (vor Ablauf) +```typescript +async getAccessToken() { + const config = await loadConfig(); + const expiresAt = new Date(config.auth.expiresAt); + const timeUntilExpiry = expiresAt.getTime() - Date.now(); + + if (timeUntilExpiry < 5 * 60 * 1000) { // < 5 Minuten + await refreshToken(); + } + return config.auth.accessToken; +} +``` + +### Reaktiver Refresh (bei 401-Error) +```typescript +async onError(error) { + if (error.response?.status === 401) { + const newTokens = await authApi.refresh(refreshToken); + await tokenStorage.saveTokens(newTokens); + return axios.request(error.config); // Retry original request + } +} +``` + +--- + +## Type-Synchronisation Backend ↔ Frontend + +### Ansatz: Automatische Generierung aus OpenAPI Spec + +**Tool: `openapi-typescript`** + +```bash +# Type-Generierung +pnpm openapi-typescript http://localhost:8080/api-docs \ + -o packages/types/src/generated/api.ts +``` + +**Workflow:** +1. Backend startet → OpenAPI Spec wird generiert +2. `pnpm run generate:types` läuft → TypeScript Types werden generiert +3. Handgeschriebene Wrapper-Files (`auth.ts`, `user.ts`) re-exportieren Types +4. Build-Prozess garantiert aktuelle Types + +**Vorteile:** +- ✅ Keine manuelle Pflege +- ✅ Immer synchron mit Backend +- ✅ Compiler-Fehler bei Breaking Changes +- ✅ Autocomplete für alle API-Strukturen + +--- + +## Development Workflow + +### Ersteinrichtung +```bash +cd /home/sebi/git/effigenix/frontend + +# pnpm installieren (falls noch nicht vorhanden) +npm install -g pnpm + +# Dependencies installieren +pnpm install + +# Alle Packages bauen +pnpm run build + +# TUI in Dev-Mode starten (Hot Reload) +pnpm run dev +``` + +### Scripts (Root package.json) +```bash +pnpm run build # Build all packages +pnpm run dev # Run TUI in dev mode +pnpm test # Run all tests +pnpm run typecheck # Type check all packages +pnpm run lint # Lint code +pnpm run format # Format code +``` + +--- + +## Verifikation & Testing + +### Manuelle Tests (E2E) +1. Backend starten: `cd backend && mvn spring-boot:run` +2. TUI starten: `cd frontend && pnpm run dev` +3. Test-Szenarien: + - Login mit `admin` / `admin123` + - User List anzeigen + - Neuen User erstellen + - User-Details anzeigen + - Email ändern + - Rolle zuweisen/entfernen + - User sperren/entsperren + - Passwort ändern + - Logout + - Token-Refresh testen + - Error-Handling + +--- + +## Timeline + +| Phase | Dauer | Status | +|-------|-------|--------| +| Phase 1: Foundation | 1 Woche | ⏳ 50% | +| Phase 2: API Client | 1 Woche | 📅 Geplant | +| Phase 3: TUI Core | 1 Woche | 📅 Geplant | +| Phase 4: User Management UI | 1 Woche | 📅 Geplant | +| Phase 5: Role Management & Polish | 1 Woche | 📅 Geplant | +| **Gesamt** | **5 Wochen** | **10% abgeschlossen** | + +--- + +## Nächste Schritte + +1. ✅ ~~Monorepo initialisieren~~ +2. ✅ ~~@effigenix/types Package erstellen~~ +3. **@effigenix/config Package erstellen** ← NEXT +4. **@effigenix/validation Package erstellen** +5. Phase 2: API Client implementieren