Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P04-files-tasks.md
2026-07-08 16:15:37 +02:00

55 lines
7.3 KiB
Markdown

# Designer-Brief · P4 — Files & Tasks
**Phase:** 4/21 · **Module:** M23 (Files) · M26 (Tasks) · **Owner-Dev:** Akeshan (AK-P4a/b) · **Designer:** David (D-P4)
**Quellen:** `ROADMAP.md` §Phase 4 · `SCREEN-MAP.md` §2-Anhang (Files-Browser / Upload-View / File-Detail / Task-Liste / Task-Detail) · `REQUIREMENTS.md` Modul 23/26 (REQ-files-datenmodell, -upload-preview, -tasks-datenmodell, -tasks-reminder-archivierung) · `ENTITY-MODEL.md` Domäne 3 (File, FileChunk, FileUploadProgress, FileEntityLink, Task, TaskWatcher) · `_bmad-output/specs/M23-files.md`, `M26-tasks.md`
**Subframe:** Pflicht je Route. Archetypen aus D0 (A2 Liste, A3 Detail, A4 Form + Dropzone, A5 Modal).
> ⚙️ **Scope-Hinweis (Scope-Schnitt 12.06.):** Files v1 ohne **Versionierung / Office-/Video-Previews / Resume-Upload / OCR** (→ v2) — **HEIC→JPG-Konvertierung bleibt Pflicht** (iPhone-Monteur-Fotos). Kein Versions-Verlauf-Sub-View in v1. Tasks: Kommentare als reine Notiz-Activity, Watcher minimal. **Task-Liste ist als wiederverwendbare Komponente zu bauen** — P12/P14/P16 betten sie ein, und sie erscheint eingebettet in allen Entity-Detail-Views (Kontakt/Firma/Lead/Projekt) als Tasks-Tab.
## Was dieses Modul tut (Kurzfassung)
Liefert die nutzerseitigen Plattform-Primitive. Files: chunked Upload (TUS) mit RLS auf Storage-Pfaden (Hetzner S3-kompatibel), Preview-Generierung (PDF→PNG, Bild→WebP, **HEIC→JPG Pflicht**), Anhängen an jede Entität über `FileEntityLink` (polymorph), Tags, Archiv-Flag; Customer-Portal-Upload ist vorbereitet. Tasks: leichtgewichtiges, querliegendes Aufgaben-Modul mit Status/Priorität/Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Projekt), Watcher, Reminder via `notify()` (24h vor / bei / 24h nach Deadline) und Auto-Archivierung erledigter Tasks nach 30 Tagen per Cron. Tasks entstehen manuell, aus Chat, aus Form-Submission und aus Automation-Actions.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| Files-Browser [`/files`] | Tabelle/Grid-Umschalter: Name, Größe, Datum, Tags, verknüpfte Entität, Thumbnail · Filter: Entität, MIME-Gruppe, Tags, Verantwortlicher · Bulk: Tag/Verknüpfen/Archiv/ZIP · Inline-Schnell-Vorschau (Hover/Single-Klick) · Archiviert-Toggle (keine Versions-Spalte v1) | A2 |
| Upload-View + Datei-Dropzone [`/files/upload`] | Drag&Drop, Multi-Datei-Queue mit Fortschritt je Datei, Fehler+Retry · **HEIC-Hinweis „wird zu JPG konvertiert"** | A4 |
| File-Detail [`/files/:id`] | Stammdaten · **Vorschau (Bild mit Zoom / PDF; HEIC→JPG)** mit Fallback-Klartext + Download bei not_supported · Tags · Notizen · verknüpfte Entitäten mit Rolle · Activity (Upload/Verknüpfungs-Änderungen/Downloads) · Download, Ersetzen, Archiv, Vorschau-neu-generieren bei failed (kein Versionsverlauf v1) | A3 |
| Task-Liste [`/tasks`] | Titel, Prioritäts-Marker, Fälligkeit (überfällig rot, relativ ≤7 Tage), verknüpfte Entität, Assignee (Person/Gruppe), Status, Quelle-Hinweis · Presets: Meine/Erstellt/Alle (Alle nur mit tasks.read_all) · Such-Funktion · Filter (Status/Priorität/Deadline-Range/Verknüpfungs-Typ/Quelle) · Archiviert-Toggle · Bulk (Status/Priorität/Assignee/Archiv/Löschen) · Inline-Quick-Actions (done/Priorität/Deadline) | A2 — **wiederverwendbare Komponente** |
| Task-Detail + Anlage-Modal [`/tasks/:id`, `/tasks/new`] | Titel, Beschreibung (Markdown), Status/Priorität/Fälligkeit inline, Assignee-Picker (Person↔Gruppe), Verknüpfungs-Picker (Auto-Complete Contact/Company/Lead/Projekt), Watcher, Quelle (manuell/Chat/Form/Automation mit Link), Activity-Stream der Task, Aktionen (Erledigen/Wieder-öffnen/Duplizieren/Löschen) · Klartext-Banner (überfällig / Assignee deaktiviert / „wird in 30 Tagen archiviert") | A3+A5 |
**Eingebettet (kein eigener Screen, aber zu designen):**
- Files-Browser vorgefiltert als Sub-Sektion in Entity-Detail-Views
- Tasks-Tab/Section mit verknüpften Tasks + „Aufgabe anlegen" (Pre-Fill) in jeder Entity-Detail-View
## Geplante Features (muss abgedeckt sein)
- [ ] Chunked Upload (TUS) mit RLS auf Storage-Pfaden (Hetzner Object Storage, ADR-009); Multi-Datei-Queue mit Per-Datei-Progress + Retry
- [ ] Preview-Generierung PDF→PNG, Bild→WebP, **HEIC→JPG (Pflicht)** mit Status (pending/generating/ready/failed/not_supported) + Klartext-Fallback
- [ ] Datei-Anhängen über FileEntityLink (polymorph) an jede Entität + Rollen-Label; Tags; Archiv-Flag; Bulk-ZIP; Customer-Portal-Upload vorbereitet
- [ ] Files-Browser server-side-Filter (Entität/MIME-Gruppe/Tags/Verantwortlicher), Tabelle/Grid-Umschalter, Inline-Schnell-Vorschau
- [ ] Tasks mit Status/Priorität/Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Projekt), Person- oder Gruppen-Zuweisung (Constraint: genau eines, Default = Ersteller), Watcher
- [ ] Task-Erstellungs-Quellen: manuell, Chat („Mark as Task"), Form-Submission, Automation-Action — je mit Quelle-Marker + Link
- [ ] Reminder via notify() (24h vor / bei / 24h nach Deadline, Eskalation Email) an Assignee/Gruppe/Watcher; Auto-Archivierung erledigter Tasks nach 30 Tagen per Cron
- [ ] Permission-Bundle tasks.* (read_own mit Owner-Check / read_all / write / admin) — fremde Tasks 404 statt 403, Action-Buttons permission-aware ausgeblendet/ausgegraut
- [ ] *(→ v2)* ~~FileVersion + Versions-Verlauf, Office-/Video-Previews, Resume-Upload, OCR~~
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Daten-Tabelle mit Tabelle/Grid-Umschalter, Vorschau-Thumbnail, sortierbaren Spalten, Filter-Bar (Entität/MIME-Gruppe/Tags/Verantwortlicher), Bulk-Action-Bar (Tag/Verknüpfen/Archiv/ZIP), Archiviert-Toggle, Inline-Schnell-Vorschau (Hover/Single-Klick); Datei-Dropzone mit Drag&Drop + Multi-Datei-Upload-Queue mit Per-Datei-Fortschrittsbalken, Fehler-Zustand + Retry, HEIC→JPG-Klartext-Hinweis; Vorschau-Komponente (Bild-Viewer mit Zoom, PDF-Viewer) mit not_supported-Fallback (Klartext + Download) + „Vorschau neu generieren"-Aktion bei failed; File-Detail-Panel mit Stammdaten, Tags-Zeile, Notiz-Feld, verknüpfte-Entitäten-Liste mit Rollen-Label, Activity-Timeline, Aktions-Buttons (Download/Ersetzen/Archiv); Task-Liste (als wiederverwendbare Komponente, embeddable) mit Prioritäts-Marker, Fälligkeits-Anzeige (relativ/absolut, überfällig rot), Quelle-Marker, Scope-Preset-Switcher (Meine/Erstellt/Alle), Such-Feld, Filter (Status/Priorität/Deadline-Range-Presets/Verknüpfungs-Typ/Quelle), Bulk-Auswahl + Bulk-Actions, Inline-Quick-Actions (done/Priorität/Deadline); Task-Detail/-Anlage mit Markdown-Editor, Status-Wechsler, Date-Picker, Assignee-Picker (Person↔Gruppe umschaltbar), Verknüpfungs-Auto-Complete-Picker, Watcher-Verwaltung, Quelle-Anzeige mit Link, Activity-Stream, Aktions-Buttons (Erledigen/Wieder-öffnen/Duplizieren/Löschen mit Klartext-Warnung); Klartext-Banner (überfällig / Assignee deaktiviert / Auto-Archivierungs-Hinweis / gelöschte Verknüpfung); Empty-/Loading-/Permission-Denied-/Fehler-States (Klartext, z. B. „Keine offenen Aufgaben — schöne Sache").
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (AK-P4a/b) aktualisiert: