docs: README mit Projektübersicht und Architektur #1

Closed
andreas.dinauer wants to merge 1 commits from docs/readme-overview into main
Showing only changes of commit 5fafcb7aba - Show all commits
+73 -53
View File
@@ -1,75 +1,95 @@
# Nuxt Minimal Starter
# r9t Frontend
Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
Schlankes Web-UI für den r9t Object-Storage (S3-kompatibel). Buckets durchsuchen, Objekte anschauen/downloaden/löschen, Dateien per Drag & Drop hochladen — mehr braucht's nicht.
Gebaut mit [Nuxt 4](https://nuxt.com), Vue 3 und Tailwind CSS 4.
## Was das Ding tut
- **Buckets auflisten** – linke Sidebar zeigt alle verfügbaren Buckets.
- **Objekte browsen** – Tabelle mit Key, Größe, Änderungsdatum, sortierbar per Klick auf die Spaltenköpfe, filterbar über die Suchleiste im Header.
- **Objekt-Details** – rechtes Panel mit Metadaten (ETag, Größe, Content-Type-Erkennung anhand der Dateiendung), Vorschau für Text-Dateien, Download- und Lösch-Aktion.
- **Upload** – Drag & Drop oder Dateiauswahl, optionaler Zielpfad-Prefix innerhalb des Buckets, Mehrfach-Upload mit Fortschrittsanzeige pro Datei und Retry für fehlgeschlagene Uploads.
- **Toast-Benachrichtigungen** für Erfolg/Fehler bei Aktionen.
Alle S3-Requests laufen direkt aus dem Browser gegen die API, signiert per AWS SigV4 (siehe unten) — kein eigenes Backend nötig, das Objekte durchreicht.
## Architektur
```
app/
├── app.vue # Root-Komponente, State-Management (Buckets/Objects/Selection)
├── components/
│ ├── BucketList.vue # Sidebar mit Bucket-Auswahl
│ ├── ObjectTable.vue # Objekt-Liste mit Sortierung & Leerzustand
│ ├── SortHeader.vue # Klickbarer Tabellen-Header für Sortierung
│ ├── ObjectDetail.vue # Detail-Panel (Metadaten, Vorschau, Download, Löschen)
│ ├── PathBreadcrumb.vue # Breadcrumb-Anzeige für den Objekt-Pfad
│ ├── FileTypeBadge.vue # Icon/Badge je nach Dateityp
│ ├── CopyField.vue # Feld mit "In Zwischenablage kopieren"-Button
│ ├── FieldLabel.vue # Label-Wrapper für Formularfelder
│ ├── ChunkBar.vue # Fortschrittsbalken (z. B. Storage-Auslastung)
│ ├── AppToast.vue # Toast-Benachrichtigungen
│ └── popup/
│ ├── PopupSlot.vue # Mount-Point für das Popup-System
│ ├── UploadPopup.vue # Upload-Dialog mit Queue & Retry
│ ├── ConfirmPopup.vue # Generischer Bestätigungs-Dialog (z. B. Löschen)
│ └── TextPreviewPopup.vue # Textvorschau für Objektinhalte
├── composables/
│ ├── useS3Client.ts # Zentraler S3-Client: list/get/put/delete, signiert Requests
│ └── usePopup.ts # Kleines Popup-Verwaltungssystem (open/close/callback)
└── utils/
├── sigv4.ts # AWS SigV4 Signing (im Browser via Web Crypto API)
├── s3xml.ts # Parser für S3-XML-Antworten (ListBuckets/ListObjects)
├── format.ts # Formatierungshelfer (Bytes, Datum, etc.)
└── popup.ts # Popup-Builder-API (Popup.component(...).setConfig(...))
```
### S3-Kommunikation
`useS3Client.ts` bündelt alle Operationen gegen den Object-Storage:
- `listBuckets()` / `listObjects(bucket)` — parsen die XML-Antworten der S3-API.
- `downloadObject`, `getObjectText`, `uploadObject`, `deleteObject` — Standard-Objekt-Operationen.
Jeder Request wird client-seitig mit **AWS Signature V4** signiert (`utils/sigv4.ts`, reine Web-Crypto-Implementierung, keine externe Lib). Region ist hart auf `us-east-1` gesetzt, Service `s3`. Access-Key und Secret-Key kommen aus der Runtime-Config (siehe unten) — das ist für ein internes Tool ok, aber **niemals produktive Root-Credentials hier reinpacken**, sondern beschränkte Zugangsdaten für genau diesen Zweck.
Requests laufen über den Nuxt-Dev-Proxy (`/api/*` → `http://localhost:8080`, siehe `nuxt.config.ts`), damit CORS im lokalen Setup kein Thema ist. In Produktion muss das je nach Deployment entsprechend über Reverse-Proxy/Ingress gelöst werden.
## Setup
Make sure to install dependencies:
```bash
# npm
npm install
# pnpm
pnpm install
# yarn
yarn install
# bun
bun install
```
## Development Server
`.env` anlegen (siehe `.env.example`):
Start the development server on `http://localhost:3000`:
```bash
NUXT_PUBLIC_S3_ACCESS_KEY=devkey
NUXT_PUBLIC_S3_SECRET_KEY=devsecret
```
Diese Werte müssen zum S3-kompatiblen Backend passen, das auf Port 8080 lauscht (siehe Proxy-Config in `nuxt.config.ts`).
## Entwicklung
```bash
# npm
npm run dev
# pnpm
pnpm dev
# yarn
yarn dev
# bun
bun run dev
```
## Production
Läuft dann auf `http://localhost:3000`. Erwartet ein S3-kompatibles Backend auf `http://localhost:8080` (per Proxy erreichbar unter `/api`).
Build the application for production:
## Build & Deployment
```bash
# npm
npm run build
# pnpm
pnpm build
# yarn
yarn build
# bun
bun run build
npm run preview # lokale Vorschau des Production-Builds
```
Locally preview production build:
Die Pipeline (`Jenkinsfile`) baut ein Docker-Image (`Dockerfile`, Node 22 Alpine) und pusht es nach `harbor.dinauer.dev/r9t/frontend`. Läuft automatisch über Jenkins bei entsprechendem Trigger.
```bash
# npm
npm run preview
## Bekannte Lücken / offene Punkte
# pnpm
pnpm preview
# yarn
yarn preview
# bun
bun run preview
```
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
- Der "Bucket erstellen"-Button in der Sidebar ist aktuell nur ein Mock (`mockAction()` in `app.vue`) — es gibt noch keine Backend-Anbindung dafür.
- Keine Pagination bei `listObjects` — bei sehr großen Buckets (>1000 Keys, S3-Standardlimit) werden nicht alle Objekte geladen.
- Secret Key liegt in der öffentlichen Runtime-Config (`runtimeConfig.public`) und landet damit im Client-Bundle. Für ein rein internes Tool mit eingeschränkten Credentials akzeptabel, für alles andere nicht.