105 lines
7.7 KiB
Markdown
105 lines
7.7 KiB
Markdown
# AgentHub Board v2 — Redesign (Spec)
|
||
|
||
Datum: 2026-07-20
|
||
Status: freigegeben durch User (Mockup-Iterationen v2 → v2.5 im Visual Companion)
|
||
|
||
## Ziel
|
||
|
||
Die Board-Seite (`/board`) sieht aus wie ein echtes, modernes Dashboard: Glas-Optik (Richtung „Modern SaaS / Glass"), dezente Animationen, mehr Daten-Leben (Charts, Live-Feed), Logo + Splash Screen. **Alle vorhandenen Funktionen bleiben erhalten** (KPIs, Drag & Drop, Agent-Zuweisung, Live-Konsole in Karten, Modals, Token-Budget, SSE). Die Team-Seite bleibt unverändert.
|
||
|
||
## Nicht-Ziele (Out of Scope)
|
||
|
||
- Multi-Projekt-Architektur (Projekt anlegen/wechseln per Dropdown) → separater v3-Spec. In v2 nur visuell vorbereitet: Projektname im Header mit Chevron (`▾`), ohne Funktion.
|
||
- Verlaufs-Charts auf der Activity-Page (später).
|
||
- Kein Frontend-Framework (bewusste Entscheidung: Fastify + String-Templates + Vanilla JS + SSE, kein Build-Step).
|
||
|
||
## Architektur-Entscheidung
|
||
|
||
`src/server/board.ts` (aktuell ~2100 Zeilen, monolithisch, nutzt `ui-shared.ts` nicht) wird in Module zerlegt, ohne das Serving-Modell zu ändern (Fastify rendert HTML-String beim Start, Daten via `/tasks`, `/agents`, `/budget`, SSE `/events`):
|
||
|
||
```
|
||
src/server/board/
|
||
index.ts — renderBoardHtml(projectName), orchestriert Module
|
||
styles.ts — v2 Design-Tokens + Glass-CSS + Animations-Keyframes
|
||
header.ts — Header (Logo, Projektzelle mit Chevron, Nav, New-Task, SSE-Dot)
|
||
kpis.ts — KPI-Reihe (Markup + Update-JS)
|
||
columns.ts — Spalten + Task-Karten + Drag&Drop + Live-Konsole
|
||
sidebar.ts — Budget-Card (Tabs) + Live-Feed
|
||
splash.ts — Splash-Screen (Markup + CSS + JS)
|
||
modals.ts — New-Task / Delete / Task-Detail (unveränderte Logik, neues Styling)
|
||
assets/
|
||
logo.svg — AgentHub-Logo (Hexagon-Gradient, Cyan #38bdf8 → Violett #8b5cf6)
|
||
```
|
||
|
||
Design-Tokens werden an `ui-shared.ts` angeglichen (gleiche Farbwerte, Glass-Surface als `--surface` etc.), damit Board und die übrigen Seiten konsistent bleiben. Team-Page wird nicht angefasst.
|
||
|
||
## Layout (wie Mockup v2.5)
|
||
|
||
Dunkler Gradient-Hintergrund (`radial-gradient`, #1c2547 → #0e1226 → #090c18). Glass-Surfaces: `rgba(255,255,255,.045)`, Border `rgba(255,255,255,.09)`, Radius 12px.
|
||
|
||
### Header
|
||
- Logo (neu, SVG, Hexagon-Gradient), `agenthub` Wortmarke
|
||
- Projektzelle `/ <projektname> ▾` (nur Optik; Dropdown-Funktion kommt mit v3)
|
||
- Nav: Board (aktiv) / Team / Activity / Decisions
|
||
- Rechts: `+ New task` Button (Indigo→Violett-Gradient), SSE-Live-Dot (grün, ping-Animation)
|
||
|
||
### KPI-Reihe (4 Karten, nur über dem Board-Bereich, nicht über Sidebar)
|
||
1. **Open** — Zahl `/ gesamt`, Mini-Area-Chart (Backlog-Verlauf, 14 Tage, aus `/tasks` abgeleitet), Grau
|
||
2. **In Progress** — Zahl, Agent-Chips: max. 3 sichtbar, dann `+n`-Chip; jeder Chip: Avatar (Agent-Farbe), Live-Punkt (pulsierend), Laufzeit
|
||
3. **Review** — Zahl, gleiche Chip-Darstellung (Reviewer), max. 3 + `+n`
|
||
4. **Done** — Zahl `/ gesamt`, Progress-Bar (Anteil erledigt, Grün-Gradient, animierter Fill), Beschreibung („63% · +5 diese Woche") klein rechtsbündig direkt über dem Bar-Ende
|
||
|
||
Karten erscheinen gestaffelt (rise-Animation, 70ms Versatz).
|
||
|
||
### Board-Spalten (unveränderte Funktion)
|
||
3 Spalten (Open / In Progress / Review) als Glass-Panels, Header mit Status-Punkt + Count-Pill. Task-Karten: Glass, Hover-Lift, Status-Farbe am linken Rand (dezent), Agent-Tag, Reviewer-Badge, Timer, Glow (`rgba(56,189,248,.35)` Border + Shadow) auf aktiv bearbeiteten Karten. **In-Progress-Karten zeigen einen Progress-Ring** (SVG-Radial, Füllung = verstrichene Zeit / geschätzte Dauer, Mitte = tickende verstrichene Zeit). Schätzung = Median der realen Bearbeitungsdauer der letzten erledigten Tasks (`claimedAt`→`updatedAt`, clientseitig aus `/tasks`); Fallback = Zeit-Kappe analog `MAX_LIVE_ESTIMATE_MIN_PER_TASK` aus `budgetService`. Über der Schätzung kippt der Ring von Cyan nach Amber. (Änderung gegenüber Mockup: ersetzt den dortigen Fantasie-Prozentbalken — ein echter Prozentwert existiert in den Daten nicht.) Drag&Drop (Status) + Agent-Chip-Drop (Zuweisung) + Live-Konsole bleiben funktional identisch.
|
||
|
||
### Sidebar rechts
|
||
**Budget-Card** mit zwei Ebenen, immer genau ein Chart sichtbar:
|
||
- Über-Tabs: `Token Insights` (Default) | `Verlauf`
|
||
- Token Insights: Sub-Tabs `Token` | `Kosten`, Session/Total-Segmented-Control und **Reset-Button** wie v1
|
||
- Token: Half-Donut (animierter Arc) + Per-Agent-Bars (Agent-Farben, animierter Fill)
|
||
- Kosten: Half-Donut + Firmen-Legende (Anthropic/OpenAI/Moonshot mit Farbpunkten)
|
||
- Verlauf: Area-Chart (Tokens, 14 Tage) mit Sollwert-Zeile („Ø x/Tag")
|
||
- Tab-Persistenz in `localStorage`
|
||
|
||
**Live-Feed-Card** darunter: letzte ~5 Events aus SSE `/events` (kompakte Zeilen, pulsierender Punkt beim neuesten).
|
||
|
||
### Splash Screen
|
||
Beim Laden von `/board`: Fullscreen-Overlay im Hintergrund-Gradient, zentriertes Logo mit Einblend-/Puls-Animation + „agenthub" Schriftzug; nach DOMContentLoaded + erstem Daten-Fetch (oder max. ~1,2s) smooth ausfaden und Dashboard einblenden. Kein Blockieren der eigentlichen Daten-Requests.
|
||
|
||
### Logo
|
||
`assets/logo.svg`: Hexagon mit Cyan→Violett-Verlauf, ausgestanzter Kern (Knoten-Metapher, passt zum Agenten-Netzwerk). Verwendet in Header, Splash, Favicon.
|
||
|
||
## Animationen (dezent, respektiert `prefers-reduced-motion`)
|
||
- `rise` (opacity + translateY 8px, 0,5–0,6s) für Karten beim ersten Render — nicht bei SSE-/Poll-Updates (wie bisher nur `.card-new`)
|
||
- `fill` (width 0 → Ziel) für Bars, `draw` (stroke-dashoffset) für Charts/Arcs
|
||
- `ping` für Live-Dot, `blink` für Status-Punkte
|
||
- KPI-Wertänderung: kurzer Flash (bestehendes `metric-flash`-Verhalten beibehalten)
|
||
- Keine Animation bei `prefers-reduced-motion: reduce`
|
||
|
||
## Datenfluss
|
||
Unverändert: initiales `refresh()` (`GET /tasks`, `/agents`, `/budget`), SSE `/events` für Live-Updates, `task-log` SSE für Karten-Konsole, 3s-Polling für Budget. Neu abgeleitet aus vorhandenen Daten:
|
||
- Backlog-Mini-Area (Open): Open-Count pro Tag der letzten 14 Tage aus Task-`createdAt`/Status-Historie — falls nicht aus den vorhandenen Endpunkten ableitbar, aus `/tasks` (created/status/updated) clientseitig approximiert; kein neuer Endpunkt in v2 (Fallback: flache Linie mit aktuellem Wert).
|
||
- Verlauf-Area-Chart (Tokens/Tag): aus `/budget`-Historie, falls vorhanden; sonst gleiche Fallback-Strategie. Implementierung klärt, was `/budget` tatsächlich liefert.
|
||
- „+5 diese Woche" bei Done: aus `/tasks` (done + `updatedAt` in den letzten 7 Tagen).
|
||
|
||
## Fehlerbehandlung
|
||
- SSE-Reconnect-Verhalten wie v1 (Verbindungs-Dot im Header).
|
||
- Wenn Budget-Endpunkt leer/fehlschlägt: Sidebar-Panels zeigen vorhandene v1-Leerzustände.
|
||
- Splash hat harte Obergrenze (~1,5s), damit er nie blockiert.
|
||
|
||
## Testing
|
||
- Bestehende Tests (`tests/`) müssen grün bleiben (Board-Rendering ist String-basiert; Snapshot-/String-Assertions ggf. anpassen).
|
||
- Neue Unit-Tests für: `kpis.ts` (Chip-Kappung 3+`+n`, Prozent-Berechnung Done, „+diese Woche"), `sidebar.ts` (Tab-Default, Reset-Button-Markup), `splash.ts` (Overlay-Markup, reduced-motion Guard), Logo-Einbettung im Header.
|
||
- Manueller Check: `agenthub server start` → `/board` im Browser (Splash, Tabs, Drag&Drop, Live-Updates).
|
||
|
||
## Entscheidungen (Log aus dem Brainstorming)
|
||
- Design-Richtung: „Glass / Modern SaaS" (Basis B), kein Nuxt/Vue (Overkill, widerspricht Simplicity-Ziel)
|
||
- Active/Open zu einer Karte „Open" verschmolzen (Kanban-Struktur: Open / In Progress / Review / Done)
|
||
- Sparklines verworfen zugunsten: Mini-Area (Open), Progress-Bar (Done), Chips (In Progress/Review)
|
||
- Chips statt Avatar-Stacks, gekappt bei 3 + `+n`
|
||
- Verschachtelte Tabs rechts (Token Insights default), Reset-Button wie v1
|
||
- Verlaufs-Charts später ggf. auf Activity-Page
|
||
- Multi-Projekt = v3 (eigener Spec)
|