CapaKraken/plan.md

Activity History System — Detailed Plan

Anforderungsanalyse

Ziel: Ein lueckenloses Aenderungsprotokoll, das jede Mutation im System erfasst und ueber UI und AI Assistant abfragbar macht. Nutzer sollen fragen koennen: "Wer hat die Buchung von Person X geaendert?" oder "Was ist in den letzten Tagen bei Projekt Y passiert?"

Ist-Zustand:

• AuditLog-Modell existiert (entityType, entityId, action, userId, changes JSONB, createdAt)
• 10 von 36 Routern loggen Aenderungen (44% Abdeckung)
• userId wird nur in ~60% der Faelle erfasst
• Kein Query-Endpoint (write-only)
• Keine UI zum Anzeigen der Historie
• AI Assistant kann keine Historie abfragen
• Inkonsistente before/after Snapshots

Soll-Zustand:

• 100% Mutation-Abdeckung ueber alle Router
• Konsistente before/after Snapshots mit User-Attribution
• Query-API mit Filtern (entityType, entityId, userId, dateRange, action)
• Admin-UI: /admin/activity-log mit suchbarer, filterbarer Timeline
• Entity-Detail-Seiten: "History"-Tab/-Drawer auf Project/Resource/Allocation
• AI Assistant Tool: query_change_history fuer natuerlichsprachliche Abfragen
• Change-Source Tracking: UI vs API vs AI vs Import

---

Architektur-Entscheidungen

1. Audit Middleware statt manuelle Calls

Entscheidung: tRPC Middleware die automatisch vor/nach jeder Mutation auditiert Grund: Eliminiert vergessene auditLog.create() Calls, garantiert 100% Abdeckung Umsetzung: Middleware auf protectedProcedure die:

• Vor der Mutation: Entity-Snapshot speichert (before)
• Nach der Mutation: Neuen Snapshot speichert (after)
• Diff berechnet und AuditLog-Entry erstellt

2. Standardisiertes Changes-Format

interface AuditChanges {
  before?: Record<string, unknown>;  // Snapshot vor der Aenderung
  after?: Record<string, unknown>;   // Snapshot nach der Aenderung
  diff?: Record<string, { old: unknown; new: unknown }>;  // Nur geaenderte Felder
  metadata?: {
    source: "ui" | "api" | "ai" | "import" | "cron";  // Wer hat die Aenderung ausgeloest
    reason?: string;   // Optionaler Kommentar
    ip?: string;       // Request IP (optional)
    batchId?: string;  // Fuer Bulk-Operationen
  };
}

3. Schema-Erweiterungen

model AuditLog {
  // Existierende Felder behalten
  id         String      @id @default(cuid())
  entityType String
  entityId   String
  action     AuditAction
  userId     String?
  user       User?       @relation(fields: [userId], references: [id])
  changes    Json        @db.JsonB
  createdAt  DateTime    @default(now())

  // NEU: Zusaetzliche Felder
  source     String?     // "ui" | "api" | "ai" | "import" | "cron"
  entityName String?     // Menschenlesbarer Name (z.B. "Porsche Taycan Project")
  summary    String?     // Einzeiler: "Changed status from DRAFT to ACTIVE"

  @@index([entityType, entityId])
  @@index([userId])
  @@index([createdAt])
  @@index([entityType, createdAt])  // NEU: Fuer sortierte Timeline-Queries
}

---

Betroffene Pakete & Dateien

Paket	Dateien	Art der Aenderung
packages/db	prisma/schema.prisma	edit — AuditLog um source, entityName, summary erweitern
packages/api	src/lib/audit.ts	create — createAuditEntry() Helper + auditMiddleware
packages/api	src/router/audit-log.ts	create — Query-Router (list, getByEntity, getTimeline)
packages/api	src/router/index.ts	edit — auditLog Router registrieren
packages/api	src/router/assistant-tools.ts	edit — query_change_history Tool hinzufuegen
packages/api	26 Router-Dateien	edit — fehlende audit Calls nachruesten
apps/web	src/app/(app)/admin/activity-log/page.tsx	create — Activity Log Seite
apps/web	src/components/admin/ActivityLogClient.tsx	create — Suchbare Timeline
apps/web	src/components/ui/EntityHistory.tsx	create — Wiederverwendbare History-Komponente
apps/web	src/components/layout/AppShell.tsx	edit — Nav-Link fuer Activity Log

---

Task-Liste (atomare Schritte)

Phase 1: Infrastruktur (Basis)

• Task 1: Schema erweitern → packages/db/prisma/schema.prisma

  • source String?, entityName String?, summary String? hinzufuegen
  • Index @@index([entityType, createdAt]) hinzufuegen
  • prisma db push + prisma generate

• Task 2: Audit Helper erstellen → packages/api/src/lib/audit.ts

  • createAuditEntry(db, params) — standardisierter Audit-Entry-Creator
  • Params: { entityType, entityId, entityName, action, userId, before?, after?, source?, summary? }
  • Automatische Diff-Berechnung wenn before + after vorhanden
  • Automatische Summary-Generierung aus Diff (z.B. "Updated name, status, budgetCents")
  • computeDiff(before, after) — gibt nur geaenderte Felder zurueck

• Task 3: Query Router erstellen → packages/api/src/router/audit-log.ts

  • list query (controllerProcedure): paginiert, filterbar nach entityType, entityId, userId, action, dateRange, source
  • getByEntity query: alle Entries fuer eine Entity, chronologisch
  • getTimeline query: globale Timeline aller Aenderungen, gruppierbar nach Tag
  • getActivitySummary query: Zusammenfassung (counts pro entityType, pro action, pro User) fuer einen Zeitraum
  • Registrieren in router/index.ts

Phase 2: Audit-Abdeckung erweitern

• Task 4: Kritische Router nachruesteen (Parallel-fähig, 4 Agents)

  • Agent A: vacation.ts (8 Mutations), entitlement.ts (2), user.ts (9)
  • Agent B: client.ts (5), org-unit.ts (3), country.ts (5), management-level.ts (5)
  • Agent C: rate-card.ts (7), blueprint.ts (6), settings.ts (3), calculation-rules.ts (3)
  • Agent D: webhook.ts (4), comment.ts (3), notification.ts (nur create/task), dispo.ts (4)
  • Jeder Agent: import { createAuditEntry } from "../lib/audit.js" verwenden
  • userId immer aus ctx.dbUser?.id nehmen

• Task 5: Bestehende Audit-Calls standardisieren

  • Alle 37 existierenden auditLog.create Calls auf createAuditEntry() Helper umstellen
  • userId konsistent aus Context nehmen
  • before/after Snapshots wo fehlend ergaenzen
  • source: "ui" als Default setzen

Phase 3: UI

• Task 6: Activity Log Admin-Seite → ActivityLogClient.tsx

  • Globale, suchbare Timeline aller Aenderungen
  • Filter: Entity-Typ (Project/Resource/Allocation/...), User, Action, Datum
  • Jeder Eintrag zeigt: Zeitstempel, User (Avatar + Name), Entity (verlinkt), Action-Badge, Summary
  • Expandierbares Detail: before/after Diff-View (JSON oder tabellarisch)
  • Pagination (50 pro Seite)
  • Sidebar Nav-Link unter Admin: "Activity Log"

• Task 7: Entity History Komponente → EntityHistory.tsx

  • Wiederverwendbar fuer Project/Resource/Allocation Detail-Seiten
  • Props: entityType: string, entityId: string
  • Chronologische Liste der Aenderungen fuer diese Entity
  • Kompakte Darstellung: User, Action, Summary, Zeitstempel
  • Optional: als Tab oder Drawer auf Detail-Seiten einbinden

• Task 8: History-Tab auf Detail-Seiten integrieren

  • /projects/[id] → "History" Tab mit <EntityHistory entityType="project" entityId={id} />
  • /resources/[id] → "History" Tab
  • Optional spaeter: Allocation Detail, Estimate Detail

Phase 4: AI Assistant Integration

• Task 9: AI Tool erstellen → assistant-tools.ts
  • query_change_history Tool:
    • Input: { entityType?, entityId?, userId?, search?, daysBack?, limit? }
    • Ruft auditLog.list mit Filtern auf
    • Formatiert Ergebnis menschenlesbar:

      [2026-03-22 14:30] admin@planarchy.dev UPDATED Project "Porsche Taycan"
        → Changed status from DRAFT to ACTIVE
        → Changed budgetCents from 500000 to 750000
      

  • get_entity_timeline Tool:
    • Input: { entityType, entityId, limit? }
    • Gibt chronologische History fuer eine Entity zurueck
  • Beide Tools mit Permission VIEW_PROJECTS oder VIEW_RESOURCES je nach entityType

---

Abhaengigkeiten

Task 1 (Schema) ──► Task 2 (Helper) ──► Task 3 (Query Router)
                                    └──► Task 4a-d (Parallel: 26 Router)
                                    └──► Task 5 (Bestehende Calls)
                    Task 3 ──► Task 6 (UI: Activity Log)
                           ──► Task 7 (UI: Entity History)
                           ──► Task 9 (AI Tools)
                    Task 7 ──► Task 8 (Integration in Detail-Seiten)

• Tasks 4a-d koennen parallel ausgefuehrt werden (unterschiedliche Dateien)
• Tasks 6, 7, 9 koennen parallel nach Task 3
• Task 8 benoetigt Task 7

---

Akzeptanzkriterien

• pnpm --filter @planarchy/web exec tsc --noEmit — keine neuen Errors
• pnpm test:unit — alle Tests gruen
• 100% Mutation-Abdeckung: Jede Mutation in jedem Router erzeugt einen AuditLog-Entry
• Konsistente userId: Jeder Entry hat den ausfuehrenden User
• before/after: UPDATE-Actions haben immer before + after Snapshots
• Query-API: trpc.auditLog.list liefert paginierte, filterbare Ergebnisse
• Admin UI: /admin/activity-log zeigt globale Timeline mit Filtern
• Entity History: Project/Resource Detail-Seiten zeigen Aenderungs-Historie
• AI Assistant: "Wer hat die Buchung von Person X geaendert?" wird korrekt beantwortet
• AI Assistant: "Was ist bei Projekt Y in den letzten Tagen passiert?" liefert Ergebnis

---

Risiken & offene Fragen

Risiken

• Performance: Audit-Middleware auf jeder Mutation koennte Latenz erhoehen → Mitigation: Audit-Writes fire-and-forget (non-blocking), oder nach Response
• Storage: JSONB Snapshots koennen gross werden → Mitigation: Nur geaenderte Felder in diff speichern, nicht volle Snapshots
• Migration: 37 bestehende Calls umstellen birgt Regressions-Risiko → Mitigation: Schrittweise, mit Tests pro Router

Offene Fragen

1. Retention: Wie lange sollen Audit-Logs aufbewahrt werden? (Vorschlag: 2 Jahre)
2. Granularitaet: Sollen READ-Zugriffe geloggt werden? (Vorschlag: Nein, nur Mutations)
3. DSGVO: Muessen Audit-Logs bei User-Loeschung anonymisiert werden?
4. Notifications: Sollen bestimmte Aenderungen (z.B. Projekt-Status) automatisch Notifications ausloesen?
5. Middleware vs Manual: Soll der Audit-Helper manuell oder als tRPC-Middleware eingebaut werden? → Empfehlung: Manuell mit Helper-Funktion, da Middleware die Entity-Snapshots nicht automatisch kennt

---

Geschaetzter Aufwand

Phase	Aufwand	Parallelisierbar
Phase 1: Infrastruktur	1 Tag	Nein (sequenziell)
Phase 2: Audit-Abdeckung	1 Tag	Ja (4 Agents parallel)
Phase 3: UI	1 Tag	Ja (2 Agents parallel)
Phase 4: AI Integration	0.5 Tag	Ja (mit Phase 3)
Gesamt	~3.5 Tage