mirror of
https://github.com/s-frick/effigenix.git
synced 2026-03-28 10:19:35 +01:00
docs(cli): remove implementation plan, add TUI user+dev guide
This commit is contained in:
Sebastian Frick
parent
bbe9e87c33
commit
169f492b76
2 changed files with 77 additions and 386 deletions
|
|
@ -1,386 +0,0 @@
|
|||
# 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
|
||||
77
frontend/apps/cli/README.md
Normal file
77
frontend/apps/cli/README.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Effigenix ERP – Terminal UI
|
||||
|
||||
Interaktive TUI für das Effigenix ERP-Backend. Gebaut mit [Ink](https://github.com/vadimdemedes/ink) (React für Terminal).
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Node.js 20+, pnpm 9+
|
||||
- Backend läuft auf `http://localhost:8080`
|
||||
|
||||
## Starten
|
||||
|
||||
```bash
|
||||
# Im frontend/-Verzeichnis
|
||||
pnpm install
|
||||
pnpm --filter @effigenix/cli dev
|
||||
```
|
||||
|
||||
## Bedienung
|
||||
|
||||
**Navigation:** `↑↓` bewegen, `Enter` auswählen/bestätigen, `Escape`/`Backspace` zurück.
|
||||
|
||||
### Login
|
||||
|
||||
Benutzername und Passwort eingeben, `Tab` zum Feldwechsel, `Enter` auf dem letzten Feld.
|
||||
Die Session wird in `~/.effigenix/config.json` gespeichert und beim nächsten Start wiederhergestellt.
|
||||
|
||||
### Hauptmenü
|
||||
|
||||
| Eintrag | Funktion |
|
||||
|---------|----------|
|
||||
| Benutzerverwaltung | Liste, Anlage, Details, Passwort |
|
||||
| Rollenverwaltung | Liste, Details |
|
||||
| Logout | Session beenden |
|
||||
|
||||
### Benutzerverwaltung
|
||||
|
||||
- **Liste:** `↑↓` navigieren, `Enter` → Detailansicht
|
||||
- **Anlegen:** Formular mit Tab-Navigation; Felder werden per Zod validiert (Inline-Fehler)
|
||||
- **Detailansicht → Aktionen:**
|
||||
- `Sperren/Entsperren` – Bestätigungsdialog (J/N)
|
||||
- `Rolle zuweisen/entfernen` – interaktive Auswahlliste der verfügbaren Rollen
|
||||
- `Passwort ändern` – eigener Screen mit Passwort-Bestätigung
|
||||
- Erfolgreiche Aktionen zeigen eine grüne Box (auto-dismiss nach 3 s)
|
||||
|
||||
### Rollenverwaltung
|
||||
|
||||
Liste aller Rollen mit Berechtigungen; Readonly-Ansicht.
|
||||
|
||||
---
|
||||
|
||||
## Entwicklung
|
||||
|
||||
```bash
|
||||
pnpm --filter @effigenix/cli typecheck # TypeScript-Check
|
||||
pnpm --filter @effigenix/cli test # vitest (15 Tests)
|
||||
pnpm --filter @effigenix/cli build # tsup → dist/
|
||||
```
|
||||
|
||||
### Struktur
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ ├── auth/ # LoginScreen
|
||||
│ ├── layout/ # MainLayout, Header, StatusBar
|
||||
│ ├── roles/ # RoleListScreen, RoleDetailScreen, RoleSelectList
|
||||
│ ├── shared/ # ErrorDisplay, SuccessDisplay, ConfirmDialog, FormInput, LoadingSpinner
|
||||
│ └── users/ # UserListScreen, UserDetailScreen, UserCreateScreen, ChangePasswordScreen
|
||||
├── hooks/ # useUsers, useRoles, useTerminalSize
|
||||
├── state/ # auth-context, navigation-context
|
||||
└── utils/ # api-client, token-storage
|
||||
```
|
||||
|
||||
### Token-Speicherung
|
||||
|
||||
`~/.effigenix/config.json` (chmod 600). Enthält Access-Token, Refresh-Token und Ablaufzeit.
|
||||
Token-Refresh erfolgt proaktiv (< 5 min bis Ablauf) und reaktiv (bei 401).
|
||||
Loading…
Add table
Add a link
Reference in a new issue