CapaKraken/docs/assistant-capability-gap-analysis.md

Assistant Capability Gap Analysis

Zielbild

Der AI Assistant soll grundsaetzlich alles lesen und ausfuehren koennen, was ein eingeloggter Nutzer gemaess seiner Rolle, Permission-Overrides und Objekt-Sichtbarkeit auch kann. Er darf weder weniger fachlich relevante Informationen sehen als die UI noch mehr Rechte erhalten als der Nutzer selbst.

Ist-Zustand

Der Assistant ist bereits relativ breit aufgestellt:

• Er haengt an packages/api/src/router/assistant.ts.
• Er exponiert aktuell 88 Function-Calling-Tools aus packages/api/src/router/assistant-tools.ts.
• Er deckt viele Kernbereiche bereits ab: Ressourcen, Projekte, Allokationen, Urlaub, Feiertagsabfragen, Staffing, Demand, Dashboard, einfache Insights, Kommentare, Notifications, Tasks, Reporting, Szenario-Simulation und Navigation.

Trotzdem ist die Paritaet zur eigentlichen App/API noch nicht erreicht. Die groessten Luecken liegen nicht bei "gar nichts vorhanden", sondern bei:

• fehlenden Admin- und Konfigurationsfaehigkeiten,
• fehlenden tiefen Fach-Readmodels,
• inkonsistentem Permission-Gating,
• fehlender serverseitiger Absicherung fuer schreibende AI-Aktionen,
• und einigen objektbezogenen Sichtbarkeitsfehlern.

Architektur des Assistants

Routing und Tool-Aufruf

• assistant.chat baut den System Prompt, filtert die verfuegbaren Tools und laesst das Modell Tools aufrufen.
• Der eigentliche Datenzugriff liegt fast komplett in executeTool(...) und den executors in packages/api/src/router/assistant-tools.ts.
• Fuer Chargeability Report und Computation Graph nutzt der Assistant jetzt dieselben tRPC-Readmodels wie die eigentlichen Fachrouter, statt eine zweite Query-Logik zu pflegen.

Permission-Gating

Es gibt aktuell vier Permission-/Scope-Ebenen:

1. Tool-Sichtbarkeit vor dem Modellaufruf in assistant.ts

• TOOL_PERMISSION_MAP blendet bestimmte Schreib-Tools aus.
• COST_TOOLS blendet kostenrelevante Tools ohne viewCosts aus.

2. Laufzeit-Guards in einzelnen Tool-Executors

• Viele Mutationen nutzen assertPermission(...).

3. Objekt-/Ownership-Checks in einzelnen Tools

• Beispiel: update_task_status und execute_task_action pruefen, ob das Task dem Nutzer gehoert.

4. Normale DB-/TRPC-Semantik der zugrunde liegenden Queries

• Diese ist aber im Assistant nicht automatisch identisch mit den eigentlichen Routern, weil die Assistant-Tools oft eigene DB-Queries verwenden.

Assistant Capability Matrix

Bereits gut abgedeckt

• Ressourcen lesen und teilweise verwalten
• Projekte lesen und teilweise verwalten
• Allokationen lesen sowie erstellen/stornieren/status aendern
• Vacation-Grundfaelle: erstellen, genehmigen, ablehnen, stornieren, Balance, Overlap, Pending Approvals
• Feiertage aufgeloest nach Region oder Ressource lesen
• Staffing/Demand-Grundfaelle
• Dashboard-Detailabfragen auf grober Ebene
• Basis-Insights
• Kommentare lesen/anlegen/resolve
• Notifications und Tasks in Grundzuegen
• Szenario-Simulation read-only
• Navigation in die UI

Teilweise abgedeckt

• Timeline/Disposition read-only:
  • get_timeline_entries_view
  • get_timeline_holiday_overlays
  • get_project_timeline_context
  • preview_project_shift
  • basiert bereits auf denselben Timeline-Readmodels/Shift-Preview-Helfern wie die UI
• Estimates: nur Suche, Detail und Anlegen, aber kein voller Lifecycle
• Reports: run_report ist flexibel, deckt aber nicht die spezialisierten Report-/Analyse-Readmodels ab
• Chargeability / Transparenz:
  • get_chargeability_report
  • get_resource_computation_graph
  • get_project_computation_graph
  • damit sind die wichtigsten tiefen Herleitungen fuer Chargeability, SAH, Feiertagsabzuege und Projektkalkulation jetzt auch im Assistant verfuegbar
• Audit/History: nur einfache History-Abfragen, keine volle Audit-API
• Notification/Tasking: Kernfaelle vorhanden, aber keine volle Reminder-/Task-/Notification-Paritaet
• Country-/Location-Stammdaten: nur lesend und auch dort nur flach
• Insights: Summary-Ebene vorhanden, Drilldowns fehlen

Vollstaendig fehlend oder fachlich nicht ausreichend

• Webhook-Administration
• System Settings / AI / SMTP / Image-Provider Administration
• System Role Config Administration
• Import/Export-Flows
• User Self-Service und Preferences
• Country- und Metro-City-Administration
• Voller Estimate-Lifecycle
• Dispo-/Import-spezifische Flows

Kritische Inkonsistenzen und Risiken

Stand 2026-03-29: Die frueheren P0s bei Notification-Scoping, list_users, Mutation-Audit und reinen Permission-Texten sind behoben. Holiday-Calendar-Lesezugriffe sowie Admin-Mutationen fuer Kalender und Entries sind jetzt im Assistant vorhanden. Die folgenden Punkte bleiben relevant.

P0: Human-in-the-Loop ist serverseitig persistiert, aber noch nicht als vollwertiger Approval-Workspace ausgebaut

Der Assistant blockiert Mutation-Tools serverseitig, legt dafuer persistente assistantApproval-Eintraege pro Nutzer und conversationId an und fuehrt die Aktion erst nach expliziter Bestaetigung in derselben Konversation aus.

Die aktuelle Chat-UI persistiert die conversationId bereits im Browser-Session-Kontext und rendert Approval-Karten im Verlauf. Damit ist der grundlegende End-to-End-Fluss zwischen Frontend und Backend konsistent.

Aktuell noch offen:

• keine eigene Approval-Inbox / Uebersicht fuer mehrere offene Freigaben
• keine dedizierte Verwaltungs-UI ausserhalb des Chatverlaufs
• Timeout-/Ablauf-Handling ist funktional vorhanden, aber noch nicht als eigenstaendige Nutzerfuehrung sichtbar

Konsequenz:

• Die zentrale Governance-Regel ist nicht mehr nur Prompt-Disziplin, sondern serverseitig gebunden.
• Fuer komplexe Mehrschritt-Workflows waere eine explizite Approval-Oberflaeche trotzdem robuster als reine Chat-Karten.

P1: Rechte-Paritaet zur Gesamt-App ist noch nicht vollstaendig

Die groben Tool-Guards sind deutlich konsistenter, aber der Assistant nutzt weiterhin in vielen Faellen eigene Queries statt die Readmodels der Fachrouter.

Konsequenz:

• Objekt-Sichtbarkeit und Detailtiefe koennen in Randfaellen noch von der UI abweichen.
• Besonders Timeline-, Admin- und Spezial-Readmodels brauchen weiterhin dedizierte Assistant-Pendants.

P1: Fehlende tiefe Fach-Readmodels und Write-Paritaet bleiben die groesste funktionale Luecke

Der Assistant kann viele Kernfaelle, aber noch nicht denselben Arbeitsmodus wie spezialisierte Oberflaechen.

Konsequenz:

• Timeline-Readmodel- und die wichtigsten Timeline-Write-Paritaetsfaelle sind jetzt ueber dieselben Router-/Readmodel-Pfade verfuegbar, aber Audit-, Admin-, Import- und Estimate-Workflows bleiben teilweise unvollstaendig
• tiefe Erklaerungen fuer Herleitungen und Governance sind noch nicht auf UI-Niveau

Was der Assistant heute noch nicht "weiss"

Die folgende Liste meint: Informationen, die in App/API bereits existieren oder fuer Nutzer sichtbar sind, aber im Assistant heute gar nicht oder nicht in gleichwertiger Tiefe/Struktur verfuegbar sind.

Feiertage und Kalender

• Vollstaendige Holiday-Calendar-Stammdaten:
  • Kalender-Liste mit Scope, Prioritaet, Aktiv-Status, Entry-Count
  • einzelne Kalender inklusive aller Entries
  • Preview der aufgeloesten Feiertage fuer geplante Kalenderaenderungen
• Editierkontext des Holiday-Editors:
  • was global, state-spezifisch oder city-spezifisch konfiguriert ist
  • welche Kalender sich gegenseitig ueberschreiben oder ergaenzen

Aktuell im Assistant vorhanden:

• aufgeloeste Feiertage nach Region oder Ressource
• Holiday-Calendar-Stammdaten:
  • list_holiday_calendars
  • get_holiday_calendar
  • preview_resolved_holiday_calendar
• Holiday-Calendar-Admin:
  • create_holiday_calendar
  • update_holiday_calendar
  • delete_holiday_calendar
  • create_holiday_calendar_entry
  • update_holiday_calendar_entry
  • delete_holiday_calendar_entry

Restluecke:

• Country-/Metro-City-Stammdaten und tiefere Standortregeln sind weiterhin nicht in derselben Pflegebreite wie die eigentliche Admin-Oberflaeche abgedeckt

Timeline und Disposition

Bereits vorhanden:

• get_timeline_entries_view
• get_timeline_holiday_overlays
• get_project_timeline_context
• preview_project_shift
• update_timeline_allocation_inline
• quick_assign_timeline_resource
• batch_quick_assign_timeline_resources
• batch_shift_timeline_allocations
• apply_timeline_project_shift
• Reuse derselben Timeline-Readmodels und Shift-Preview-Helfer wie in timelineRouter
• Reuse derselben Timeline-Mutationen via createCallerFactory(timelineRouter) statt Assistant-Sonderlogik
• identische Manager-/Admin- und manageAllocations-Guards wie im normalen API-Pfad

Noch fehlend:

• Dispo-spezifische Import-/Workbook-Flows

Konsequenz:

• Der Assistant kann die wichtigsten Timeline-/Disposition-Read- und Writefaelle jetzt fachlich und technisch auf derselben Basis wie die UI abbilden.
• Offen bleiben vor allem Import-/Workbook-Flows und weitere Dispo-Spezialworkflows ausserhalb der Kernmutationen.

Transparenz, Herleitungen und Berechnungsgraphen

Bereits vorhanden:

• Vollstaendige Computation-Graph-Daten fuer Resource- und Project-Views:
  • Herleitungsfaktoren
  • Formeln
  • Holiday-/State-/City-Kontext pro Berechnung
  • Node/Link-Zusammenhaenge
• Spezialisierter Chargeability Report:
  • Monatsreihen
  • Org-Unit-, Management-Level- und Country-Filter
  • Gruppenaggregate und Luecken zum Target

Konsequenz:

• Der Assistant kann die wichtigsten Herleitungen jetzt auf derselben fachlichen Basis wie die spezialisierten Analyseansichten liefern.
• Offen bleibt vor allem, diese Tiefe konsequent in weiteren Admin-, Audit- und Workflow-spezifischen Assistentenfaellen auszubauen.

Audit, Verlauf und Governance

• Vollstaendige Audit-API:
  • paginierte Listen
  • Detailansicht mit voller changes-Struktur
  • Timeline-View
  • Activity Summary

Aktuell im Assistant vorhanden:

• vereinfachte History-Suche (query_change_history)
• Entity-History (get_entity_timeline)

Fehlend:

• die vollstaendige Governance-/Revisionstiefe der Audit-Oberflaeche

Admin- und Systemkonfiguration

• System Settings:
  • AI-Provider-Konfiguration
  • SMTP-Konfiguration
  • Image-Provider-Konfiguration
  • Score Weights / Sichtbarkeiten
  • Vacation Defaults
  • Timeline Undo Settings
  • Connection Tests
• System Role Config:
  • Rollenlabels
  • Beschreibungen
  • Farben
  • Default-Permissions
• Webhooks:
  • Liste, Detail, Create, Update, Delete, Test

Konsequenz:

• Ein Admin kann in der UI deutlich mehr Systemsteuerung als der Assistant.

User Self-Service

• user.me
• Dashboard-Layout lesen/speichern
• Favorite Projects lesen/toggeln
• Column Preferences lesen/speichern
• MFA / TOTP aktivieren, pruefen, Status lesen
• einige Nutzerverwaltungsaktionen aus userRouter

Konsequenz:

• Der Assistant kennt den Nutzerkontext nur oberflaechlich, aber nicht dessen persoenliche Einstellungen und Self-Service-Moeglichkeiten.

Stammdaten fuer Laender und Orte

Aktuell im Assistant vorhanden:

• list_countries mit scheduleRules, Aktiv-Status und Metro-Cities
• get_country
• create_country
• update_country
• create_metro_city
• update_metro_city
• delete_metro_city

Restluecke:

• weitere standortbezogene Admin-Bereiche ausserhalb von Country/Metro-City

Estimate-Lifecycle und Fachobjekte unterhalb des Estimates

• volle Estimate-Listen-/Detail-Paritaet
• Versionen, Scope Items, Demand Lines, Locking, Freigaben, weiterfuehrende Mutationen

Aktuell im Assistant vorhanden:

• Suche
• Baseline-Detail
• Anlegen

Fehlend:

• der eigentliche Arbeitsprozess auf Estimate-Ebene

Notifications, Tasks und Reminder

Vorhanden:

• Listen, Task-Detail, Statuswechsel, Reminder anlegen, Task fuer User anlegen, Broadcast senden

Fehlend:

• Reminder-Liste
• Reminder-Update/Delete
• Unread Count
• Task Counts
• generische Notification-Erstellung mit derselben Tiefe wie notificationRouter

Capability Gaps nach Router

Komplett fehlende Router-Paritaet

• importExport
• chargeabilityReport
• computationGraph
• settings
• systemRoleConfig
• webhook
• dispo

Deutlich unvollstaendige Router-Paritaet

• timeline (read-only Kernfaelle vorhanden, Write-Paritaet fehlt)
• vacation
• estimate
• notification
• user
• country
• auditLog
• insights
• scenario
• resource
• project
• comment

Nahe an brauchbarer Grundabdeckung, aber nicht vollstaendig

• resource
• project
• staffing
• report
• dashboard

System Prompt: offensichtliche Uebertreibungen / Irrefuehrungen

Der Prompt suggeriert an mehreren Stellen mehr Paritaet, als technisch heute vorhanden ist.

Problematische Aussagen

• "Notifications anzeigen" ist fuer die Basisfaelle inzwischen sauberer gescoped, deckt aber weiterhin nicht die volle Notification-/Reminder-Paritaet der App ab.
• "Dashboard-Details abrufen" stimmt nur fuer einen Teil der Dashboard-/Analysewelt.
• "Den User zu relevanten Seiten navigieren" stimmt, ersetzt aber keine echte Daten-/Aktionsparitaet in Timeline, Holiday Editor oder Admin-Bereichen.
• "Ressourcenplanung und Projektmanagement" klingt umfassender, als die reale Tool-Abdeckung in spezialisierten Subsystemen ist.

Wichtigste Prompt-Luecke

Die Human-in-the-Loop-Regel ist inzwischen serverseitig erzwungen. Der Prompt sollte trotzdem nicht so formulieren, als gaebe es bereits eine vollwertige Approval-Workbench oder vollstaendige Workflow-Paritaet.

Was getan werden muss, damit der Assistant wirklich dieselben Nutzerfaehigkeiten hat

P0: Sicherheits- und Governance-Hardening

1. Serverseitige Confirm-Policy fuer alle schreibenden Assistant-Tools einziehen.

• Status: im Kern erledigt.
• Weiter offen:
  • Approval-UX ausserhalb des Chatverlaufs
  • bessere Sichtbarkeit mehrerer offener Freigaben
  • explizitere Admin-/Audit-Auswertung offener/abgelaufener Freigaben

2. Assistant-Tools auf denselben Objekt-Scope wie die eigentlichen Router bringen.

• Besonders:
  • Notifications
  • Tasks
  • User-Liste
  • alle personenbezogenen oder sensitiven Admin-Daten

3. Permission-Quellen vereinheitlichen.

• Ein zentraler Capability-/Policy-Registry sollte festlegen:
  • welches Tool welche Permission braucht,
  • ob Objekt-Ownership gilt,
  • ob viewCosts zusaetzlich erforderlich ist,
  • ob Human Confirmation erforderlich ist.

P1: Fachliche Paritaet fuer die wichtigsten Nutzer-Workflows

1. Holiday-Calendar-Assistant-Strang bauen

• list_holiday_calendars
• get_holiday_calendar
• create_holiday_calendar
• update_holiday_calendar
• delete_holiday_calendar
• create_holiday_entry
• update_holiday_entry
• delete_holiday_entry
• preview_resolved_holidays

2. Timeline-Assistant-Strang bauen

• Read:
  • Status: fuer die zentralen read-only Faelle umgesetzt
• Write:
  • update_allocation_inline
  • apply_project_shift
  • quick_assign
  • batch_quick_assign
  • batch_shift_allocations

3. Analyse-/Transparenz-Paritaet bauen

• get_chargeability_report
• get_resource_computation_graph
• get_project_computation_graph

P2: Admin- und Stammdaten-Paritaet

1. Settings-Admin-Tools

• lesen
• aktualisieren
• Connection Tests

2. SystemRoleConfig-Tools

• listen
• update

3. Country-/City-Tools

• Status: umgesetzt fuer Country-Detail, Country-Create/Update und City-Create/Update/Delete
• offen bleiben nur weitergehende standortbezogene Admin-Readmodels ausserhalb dieses Stammdatenkerns

4. Webhook-Tools

• list/get/create/update/delete/test

P3: Self-Service- und Workflow-Paritaet

1. User-Tools

• get_me
• Dashboard-Layout lesen/schreiben
• Favoriten lesen/toggeln
• Column Preferences lesen/schreiben
• MFA-Status / TOTP-Flows

2. Notification-/Reminder-Paritaet

• Reminder listen/update/delete
• unreadCount
• taskCounts

3. Estimate-Lifecycle vertiefen

• Versionen
• Scope Items
• Demand Lines
• Status-/Locking-/Approval-Flows

Empfohlene Umsetzungsreihenfolge

Stream A: Safety / Policy

• Approval-UX / Inbox / Lifecycle auf die persistente Server-Approval-Logik aufsetzen
• Ownership-/Permission-Fixes
• Mutation-Audit vervollstaendigen

Stream B: Holiday + Timeline Parity

• Holiday-Calendar-Editor-Tools
• Timeline-Write-Aktionen
• Timeline-Shift-/Assign-Aktionen

Stream C: Explainability / Analytics

• Chargeability Report
• Computation Graph
• Audit Summary

Stream D: Admin / Ops

• Settings
• System Role Config
• Webhooks
• Import/Export

Kurzfazit

Der Assistant ist bereits breit genug, um viele operative Fragen und Standardaktionen abzudecken. Er ist aber noch nicht in dem Zustand, dass man sagen kann: "Alles, was der Nutzer kann, kann auch der Assistant."

Die drei groessten Blocker dafuer sind:

1. fehlende vollwertige Approval-UX trotz bereits vorhandener serverseitiger Persistenz und Durchsetzung,
2. unvollstaendige fachliche Paritaet in Holiday/Timeline/Analytics/Admin-Bereichen,
3. inkonsistente oder zu schwache Permission- und Ownership-Pruefungen in einzelnen Tools.