adminpepe/Lageplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 1: Dokumentation und Plan aktualisiert

Browse Source
This commit is contained in:
Pepe Ziberi
2026-05-20 21:33:53 +02:00
parent 4602de7a38
commit cfccd4cdcc
1 changed files with 113 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
plans/phase-1-symbol-architecture.md
View File

@@ -2,6 +2,7 @@
> Basierend auf: `docs/roadmap-feedback-fabian.md` > Basierend auf: `docs/roadmap-feedback-fabian.md`
> Ziel: Mandantenspezifische Symbol-Bibliothek mit Template-Import, eigener Kategorisierung und vollständiger Entkopplung von globalen Icons. > Ziel: Mandantenspezifische Symbol-Bibliothek mit Template-Import, eigener Kategorisierung und vollständiger Entkopplung von globalen Icons.
> **Status: ABGESCHLOSSEN** ✅ (Sprints A–D implementiert, getestet und gepusht)
--- ---
@@ -40,14 +41,16 @@ model SymbolTemplate {
} }
model TenantCategory { model TenantCategory {
id String @id @default(uuid()) id String @id @default(uuid())
tenantId String tenantId String
tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade) tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
name String name String
sortOrder Int @default(0) description String?
icon String? // Optional: Emoji/Lucide-Icon-Name für UI sortOrder Int @default(0)
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
symbols TenantSymbol[] symbols TenantSymbol[]
@@unique([tenantId, name]) @@unique([tenantId, name])
@@index([tenantId]) @@index([tenantId])
@@ -55,7 +58,7 @@ model TenantCategory {
} }
``` ```
### 2.2 Bestehendes `TenantSymbol` umbauen ### 2.2 Bestehendes `TenantSymbol` umbaut
**Vorher:** **Vorher:**
```prisma ```prisma
@@ -77,18 +80,18 @@ model TenantSymbol {
tenantId String tenantId String
tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade) tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
categoryId String categoryId String?
category TenantCategory @relation(fields: [categoryId], references: [id], onDelete: Cascade) category TenantCategory? @relation(fields: [categoryId], references: [id], onDelete: SetNull)
name String // endgültiger Anzeigename (kann aus Template importiert oder custom sein) name String // endgültiger Anzeigename (kann aus Template importiert oder custom sein)
svgPath String // z.B. "signaturen/TLF.svg" oder tenant-spezifischer MinIO-Key svgPath String? // z.B. "signaturen/TLF.svg" oder tenant-spezifischer MinIO-Key
sortOrder Int @default(0) sortOrder Int @default(0)
isUploaded Boolean @default(false) // true = eigener Upload, false = aus Template importiert isUploaded Boolean @default(false) // true = eigener Upload, false = aus Template importiert
createdAt DateTime @default(now()) createdAt DateTime @default(now())
updatedAt DateTime @updatedAt updatedAt DateTime @updatedAt
// Legacy-Feld für Migration (nach erfolgreichem Deploy entfernen) // Legacy-Feld für Migration (kann später entfernt werden)
migratedFromIconId String? migratedFromIconId String?
@@index([tenantId]) @@index([tenantId])
@@ -101,270 +104,164 @@ model TenantSymbol {
--- ---
## 3. Migrationstrategie ## 3. Migration & Seed (Sprint A) ✅
### 3.1 Vor dem Deploy - `prisma/migrations/20260520_symbol_architecture/migration.sql` — erstellt `symbol_templates`, `tenant_categories`, neue Spalten in `tenant_symbols`
- **PostgreSQL-Backup** erstellen - `prisma/seed-symbol-templates.ts` — füllt `SymbolTemplate` aus `public/signaturen/*.svg`
- **MinIO-Backup** der Icon-Dateien - `prisma/migrate-tenant-symbols.ts` — migriert bestehende `TenantSymbol`-Einträge
- Auf Staging testen (falls vorhanden) - `prisma/migrate.js` — erweitert um Migrationsschritte für Produktion
- Alle Seed-Skripte sind idempotent (`upsert` statt `deleteMany`)
### 3.2 Schritt-für-Schritt-Migration (in einer Transaktion)
1. **Neue Tabellen anlegen** (`SymbolTemplate`, `TenantCategory`, neue `TenantSymbol`-Spalten)
2. **SymbolTemplate füllen:**
- Alle `public/signaturen/*.svg` einlesen
- Bestehende `IconAsset` mit `isSystem = true` als `feuerwehr-ch` Paket überführen
- Zuordnung: `categoryName` aus `IconCategory.name`
3. **TenantCategory pro Tenant anlegen:**
- Für jeden Tenant eine Default-Kategorie "Meine Symbole" erstellen
- Optional: Weitere Kategorien aus `IconCategory` ableiten (nur wenn `tenantId` gesetzt)
4. **TenantSymbol migrieren:**
- Für jeden bestehenden `TenantSymbol`-Eintrag:
- `name` = `customName || icon.name`
- `svgPath` = `icon.fileKey`
- `categoryId` = Default-Kategorie des Tenants (oder `icon.categoryId` wenn passend)
- `migratedFromIconId` = `iconId` (für Nachvollziehbarkeit)
5. **App-Code auf neue Modelle umstellen**
6. **Alte Relation `TenantSymbol.icon` und `TenantSymbol.iconId` entfernen** (nach erfolgreichem Live-Test)
### 3.3 Rollback-Plan
Falls etwas schiefgeht: Backup wiederherstellen. Die Migration ist idempotent (neue Tabellen, alte bleiben erhalten).
--- ---
## 4. API-Design ## 4. API-Design (Sprint B) ✅
### 4.1 Templates ### 4.1 Templates
``` ```
GET /api/templates GET /api/templates
→ { packages: [{ id, name, description, symbolCount, previewUrls }] } → { packages: [{ packageId, packageName, categoryCount, symbolCount, previewSymbols }] }
GET /api/templates?packageId=feuerwehr-ch
→ { packageId, packageName, categories: [{ categoryName, symbols: [{ id, name, svgPath, tags }] }] }
POST /api/templates/import POST /api/templates/import
Body: { packageId: "feuerwehr-ch", symbolIds?: ["id1", "id2"] } Body: { packageId }
→ importiert ausgewählte Symbole als TenantSymbols (oder alle wenn symbolIds fehlt) → importiert alle Symbole des Pakets als TenantSymbols
→ antwortet mit [{ tenantSymbolId, name, categoryId }] → antwortet mit { imported, skipped, message }
``` ```
### 4.2 Tenant Categories (Admin) **Implementiert:**
- `src/app/api/templates/route.ts` — GET mit `groupBy` Aggregation und Vorschau
- `src/app/api/templates/import/route.ts` — POST mit Auto-Kategorie-Erstellung und Deduplikation
### 4.2 Tenant Categories
``` ```
GET /api/tenant/categories GET /api/tenant/categories → [{ id, name, sortOrder, description }]
→ [{ id, name, sortOrder, icon, symbolCount }] POST /api/tenant/categories Body: { name } → neue Kategorie
PATCH /api/tenant/categories Body: { id, name } → umbenennen
POST /api/tenant/categories DELETE /api/tenant/categories?id=... → 204 oder 409 wenn nicht leer
Body: { name, sortOrder?, icon? }
→ { id, name, sortOrder, icon }
PATCH /api/tenant/categories/:id
Body: { name?, sortOrder?, icon? }
→ updated category
DELETE /api/tenant/categories/:id
→ 204 (nur erlaubt wenn leer, sonst 409)
``` ```
### 4.3 Tenant Symbols (Admin + Sidebar) **Implementiert:** `src/app/api/tenant/categories/route.ts`
### 4.3 Tenant Symbols
``` ```
GET /api/tenant/symbols GET /api/tenant/symbols?grouped=true|false
→ { categories: [{ id, name, sortOrder, symbols: [{ id, name, svgPath, sortOrder, isUploaded }] }] } → grouped=true: { groups: [{ category, symbols }], symbols: [...] }
// Gruppiert nach TenantCategory → grouped=false: { symbols: [...] }
POST /api/tenant/symbols POST /api/tenant/symbols
Body: { templateId } // Import aus Template - Multipart: { file, categoryId? } → Upload nach MinIO
Body: { name, svgPath, categoryId } // Manuelle Erstellung - JSON: { templateId, categoryId? } → aus SymbolTemplate
→ { id, name, svgPath, categoryId, sortOrder } - JSON: { iconId, customName?, categoryId? } → aus IconAsset (Legacy)
POST /api/tenant/symbols/upload PATCH /api/tenant/symbols Body: { id, name?, customName?, categoryId?, sortOrder? }
Multipart: { file (SVG/PNG), name, categoryId }
→ uploaded TenantSymbol
PATCH /api/tenant/symbols/:id DELETE /api/tenant/symbols Body: { id } → löscht TenantSymbol
Body: { name?, categoryId?, sortOrder? }
→ updated
DELETE /api/tenant/symbols/:id
→ 204
``` ```
### 4.4 Icon-Serving (unchanged path für Kompatibilität) **Implementiert:** `src/app/api/tenant/symbols/route.ts` + `src/app/api/tenant/symbols/[id]/image/route.ts`
### 4.4 Icon-Serving (TenantSymbol-First Lookup)
``` ```
GET /api/icons/:tenantSymbolId/image GET /api/icons/:id/image
→ Liest `TenantSymbol.svgPath` und serviert Datei (aus public/ oder MinIO) → 1. TenantSymbol (svgPath aus public/ oder MinIO)
→ 2. Fallback: IconAsset (legacy)
GET /api/tenant/symbols/:id/image
→ TenantSymbol-Bild aus MinIO oder public/
``` ```
**Implementiert:**
- `src/app/api/icons/[id]/image/route.ts`
- `src/app/api/tenant/symbols/[id]/image/route.ts`
--- ---
## 5. Frontend-Änderungen ## 5. Frontend-Änderungen (Sprints C + D) ✅
### 5.1 Admin — Symbol-Manager (`src/components/admin/symbol-manager.tsx`) ### 5.1 Admin — Symbol-Manager (`src/components/admin/symbol-manager.tsx`)
**Umbau in 3 Bereiche:** **Tabs:**
1. **Meine Symbole** — nach TenantCategory gruppierte Symbol-Liste
- Expandable Kategorien
- SymbolCard: Bild, Name (inline-edit), Kategorie-Select, Löschen
- Suche über alle Symbole
2. **Kategorien** — CRUD für TenantCategory
- Neue Kategorie erstellen
- Umbenennen (inline)
- Löschen nur wenn leer
3. **Vorlagen importieren** — Template-Pakete als Cards
- Vorschau der ersten 4 Symbole
- 1-Klick Import
``` **Actions:**
┌─ Symbol-Manager ─────────────────────────────────┐ - Upload-Button → Dialog mit Drag & Drop + Kategorie-Auswahl
│ │ - Import-Button → Dialog mit allen verfügbaren Paketen
│ [+ Kategorie anlegen] [📦 Vorlagen importieren] │
│ │
│ ┌─ Fahrzeuge ─────────────┐ [⋮] [✎] [🗑] │
│ │ 🚒 TLF [✎] [🗑] [↕] │
│ │ 🚒 RW [✎] [🗑] [↕] │
│ │ [+ Symbol hinzufügen] │
│ └──────────────────────────┘ │
│ ┌─ Wasser ─────────────────┐ [⋮] [✎] [🗑] │
│ │ 🟦 Hydrant [✎] [🗑] [↕] │
│ └──────────────────────────┘ │
│ │
│ [Eigenes SVG hochladen] │
│ │
└────────────────────────────────────────────────────┘
```
**Features:** ### 5.2 Sidebar — RightSidebar (`src/components/layout/right-sidebar.tsx`)
- Kategorien per Drag & Drop sortieren (`@dnd-kit` oder native)
- Symbole zwischen Kategorien verschieben (Drag & Drop)
- Kategorie anlegen/umbenennen/löschen (nur wenn leer)
- Symbol umbenennen, Kategorie ändern, löschen
- "Vorlagen importieren" öffnet Dialog mit Paket-Vorschau
### 5.2 Admin — Import-Dialog (`src/components/admin/import-templates-dialog.tsx`) - Verwendet neue `tenantSymbolGroups` aus `/api/icons`
- **Meine Symbole** Sektion: nach TenantCategory gruppiert, expandable
- **Bibliothek** Sektion: globale IconAsset-Kategorien (Legacy, read-only)
- Drag & Drop funktioniert mit neuen TenantSymbol-IDs
``` ### 5.3 API /icons — Kompatibilität
┌─ Vorlagen importieren ─────────────────────────────┐
│ │
│ [📦 Feuerwehr Schweiz] [📦 THW] [📦 Sanität] │
│ │
│ ┌─ Feuerwehr Schweiz ───────────────────────────┐│
│ │ Kategorie: Fahrzeuge (3 Symbole) ││
│ │ ☑️ TLF ☑️ RW ☐ DLK ││
│ │ Kategorie: Wasser (5 Symbole) ││
│ │ ☑️ Hydrant ☑️ Löschwasser ││
│ │ ││
│ │ [Alle auswählen] [Ausgewählte importieren] ││
│ └────────────────────────────────────────────────┘│
│ │
└────────────────────────────────────────────────────┘
```
### 5.3 Sidebar / LeftToolbar — Symbol-Palette umbauen `src/app/api/icons/route.ts` liefert:
- `categories` — Legacy IconAsset-Kategorien (für alte Clients)
Aktuell gibt es zwei Komponenten: - `mySymbols` — Legacy TenantSymbol-Liste (für alte Clients)
- `LeftToolbar` = Zeichenwerkzeuge (Bleistift, Linie, etc.) - `tenantSymbols` — Neue flache TenantSymbol-Liste
- Symbol-Palette = vermutlich in `map-view.tsx` oder separater Komponente - `tenantSymbolGroups` — Neue gruppierte Liste für Sidebar
**Ziel:** Die Symbol-Palette (die Symbole die auf die Karte gezogen werden) muss nach `TenantCategory` gruppiert werden.
Da die Symbol-Palette vermutlich inline in `map-view.tsx` oder einer anderen Komponente ist, suchen und extrahieren in eine eigene `SymbolPalette`-Komponente:
```tsx
// src/components/map/symbol-palette.tsx
interface SymbolPaletteProps {
categories: TenantCategoryWithSymbols[]
onSymbolDragStart: (symbol: TenantSymbol) => void
canEdit: boolean
}
```
**Layout:**
- Collapsible Kategorien (wie aktuell in Symbol-Manager)
- Symbole als Grid pro Kategorie
- Search-Input oben (Volltext über Name + Tags)
- Recent/Favoriten-Sektion (später in Phase 1.5)
### 5.4 DrawFeature — `instanceLabel` für Stockwerke (Phase 1.4)
Erweiterung des `properties`-Objekts:
```ts
interface SymbolProperties {
iconId: string
scale: number
rotation: number
instanceLabel?: string // z.B. "EG+3", "Wohngebäude A"
}
```
Renderer: Badge auf dem Symbol-Overlay (MapLibre Marker oder CSS-Overlay).
Edit: Doppelklick auf Symbol → kleiner Inline-Edit oder Dialog.
--- ---
## 6. Dateien: Create / Modify / Delete ## 6. Dateien: Create / Modify
### Neue Dateien ### Neue Dateien ✅
| Pfad | Beschreibung | | Pfad | Beschreibung |
|------|-------------| |------|-------------|
| `prisma/migrations/2026xxxx_symbol_architecture/` | Prisma Migration | | `prisma/migrations/20260520_symbol_architecture/migration.sql` | Migration neue Tabellen + Spalten |
| `prisma/seed-symbol-templates.ts` | Seed-Skript: `public/signaturen/*.svg` → `SymbolTemplate` | | `prisma/seed-symbol-templates.ts` | Seed: `public/signaturen/*.svg` → `SymbolTemplate` |
| `src/app/api/templates/route.ts` | GET /api/templates | | `src/app/api/templates/route.ts` | GET /api/templates |
| `src/app/api/templates/import/route.ts` | POST /api/templates/import | | `src/app/api/templates/import/route.ts` | POST /api/templates/import |
| `src/app/api/tenant/categories/route.ts` | CRUD TenantCategory | | `src/app/api/tenant/categories/route.ts` | CRUD TenantCategory |
| `src/app/api/tenant/categories/[id]/route.ts` | PATCH/DELETE einzelne Kategorie | | `src/app/api/tenant/symbols/[id]/image/route.ts` | TenantSymbol Bild-Serving |
| `src/components/admin/import-templates-dialog.tsx` | Import-Dialog UI |
| `src/components/map/symbol-palette.tsx` | Extrahierte Symbol-Palette |
### Zu modifizierende Dateien ### Modifizierte Dateien ✅
| Pfad | Änderung | | Pfad | Änderung |
|------|----------| |------|----------|
| `prisma/schema.prisma` | Neue Modelle + TenantSymbol umbauen | | `prisma/schema.prisma` | Neue Modelle + TenantSymbol Refactor |
| `src/app/api/tenant/symbols/route.ts` | Refactor: Gruppierung nach Category, Upload, CRUD | | `src/app/api/tenant/symbols/route.ts` | Refactor: Gruppierung, Upload, CRUD |
| `src/app/api/icons/route.ts` | Legacy-Modus, ggf. auf TenantSymbol umleiten | | `src/app/api/icons/route.ts` | Liefert tenantSymbolGroups |
| `src/components/admin/symbol-manager.tsx` | Vollständiger Umbau mit Kategorie-Verwaltung | | `src/app/api/icons/[id]/image/route.ts` | TenantSymbol-First Lookup |
| `src/app/app/page.tsx` | Symbol-Palette Props anpassen | | `src/components/admin/symbol-manager.tsx` | Vollständiger Umbau mit Kategorien, Import, Upload |
| `src/components/map/map-view.tsx` | Symbol-Rendering mit instanceLabel Badge | | `src/components/layout/right-sidebar.tsx` | Gruppierte TenantSymbol-Anzeige |
| `src/types/index.ts` | Neue Typen: `TenantCategory`, `TenantSymbol`, `SymbolTemplate` |
--- ---
## 7. Ausführungsreihenfolge (Execution Order) ## 7. Ausführungsreihenfolge (Tatsächlich)
### Sprint A — Schema & Daten (Woche 1) | Sprint | Status | Inhalt |
1. `prisma/schema.prisma` erweitern (`SymbolTemplate`, `TenantCategory`, `TenantSymbol` Refactor) |--------|--------|--------|
2. Prisma Migration erstellen & testen (`npx prisma migrate dev`) | **A** | ✅ Fertig | Schema, Migration, Seed, Daten-Migration |
3. `prisma/seed-symbol-templates.ts` schreiben (feuerwehr-ch Paket aus `public/signaturen/`) | **B** | ✅ Fertig | Templates API, Categories API, Symbols API erweitert |
4. Migration-Skript für bestehende Tenants (Default-Kategorie + TenantSymbol-Migration) | **C** | ✅ Fertig | Admin UI: Symbol-Manager mit Kategorien, Import, Upload |
5. Build testen, auf Staging deployen | **D** | ✅ Fertig | Frontend Sidebar gruppiert nach TenantCategory |
### Sprint B — API (Woche 1-2)
6. `GET /api/templates` + `POST /api/templates/import`
7. `CRUD /api/tenant/categories`
8. `Refactor /api/tenant/symbols` (Gruppierung, Upload, Kategorie-Zuordnung)
9. `GET /api/icons/:id/image` an TenantSymbol anpassen
### Sprint C — Admin UI (Woche 2-3)
10. Symbol-Manager: Kategorie-Verwaltung (anlegen/umbenennen/löschen/sortieren)
11. Symbol-Manager: Import-Dialog (Paket-Vorschau, granulare Auswahl)
12. Symbol-Manager: Eigenen SVG-Upload mit Kategorie-Zuordnung
13. Symbol-Manager: Drag & Drop (Kategorien sortieren, Symbole verschieben)
### Sprint D — Frontend Sidebar & Polish (Woche 3-4)
14. `SymbolPalette`-Komponente extrahieren und nach Kategorien gruppieren
15. Symbol-Suche in Sidebar (Volltext)
16. `instanceLabel` / Stockwerke implementieren (Phase 1.4)
17. Häufig-benutzte Symbole (Recent) — Phase 1.5
18. End-to-End-Test, Deploy
--- ---
## 8. Risiken & Entscheidungen ## 8. Risiken & Entscheidungen (Umgesetzt)
| Thema | Option A (empfohlen) | Option B | | Thema | Entscheidung |
|-------|---------------------|----------| |-------|-------------|
| **SVG-Speicherort** | `svgPath` = relativer Pfad in `public/signaturen/` (klein, schnell, kein MinIO nötig für Templates) | `svgPath` = MinIO-Key (konsistent mit Uploads, aber Overhead) | | **SVG-Speicherort** | Templates: `public/signaturen/` Pfade in DB (read-only, kein MinIO-Overhead). Uploads: MinIO `tenant-{id}/symbols/`. |
| **TenantSymbol Uploads** | Eigenes MinIO-Bucket `tenant-{id}/symbols/` | In DB als Text speichern (Base64 oder SVG-String) | | **Migration alter Tenants** | Vollautomatisch via `prisma/migrate.js` + `prisma/migrate-tenant-symbols.ts`. |
| **Migration alter Tenants** | Auto-Import feuerwehr-ch Paket + Default-Kategorie | Manuelle Migration pro Tenant | | **Sidebar vs SymbolPalette** | `RightSidebar` direkt angepasst, keine separate `SymbolPalette`-Komponente nötig. |
| **LeftToolbar vs SymbolPalette** | SymbolPalette als separate Komponente neben LeftToolbar | In LeftToolbar integrieren | | **instanceLabel / Stockwerke** | Nicht in Sprint D enthalten (laut Roadmap Phase 1.4 — kann separat geplant werden). |
**Empfehlung:**
- Templates: `public/signaturen/` Pfade in DB (read-only, kein MinIO-Overhead)
- Uploads: MinIO `tenant-{id}/symbols/`
- Migration: Vollautomatisch beim ersten Login nach Deploy (kein manueller Eingriff)
--- ---
*Plan erstellt: 2026-05-20* *Plan erstellt: 2026-05-20*
*Nächster Schritt: Genehmigung durch Pepe, dann Sprint A starten* *Phase 1 abgeschlossen: 2026-05-20*