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:

• weiterhin fehlenden tiefen Fach-Readmodels und Spezialworkflows,
• noch nicht vollstaendiger Router-/Objektscope-Paritaet,
• fehlender Approval-/Governance-UX ausserhalb des Chats,
• und einigen verbleibenden 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
• Import/Export / Dispo:
  • export_resources_csv
  • export_projects_csv
  • import_csv_data
  • list_dispo_import_batches
  • get_dispo_import_batch
  • stage_dispo_import_batch
  • validate_dispo_import_batch
  • cancel_dispo_import_batch
  • list_dispo_staged_resources
  • list_dispo_staged_projects
  • list_dispo_staged_assignments
  • list_dispo_staged_vacations
  • list_dispo_staged_unresolved_records
  • resolve_dispo_staged_record
  • commit_dispo_import_batch
  • damit sind CSV-Export, CSV-Import sowie die operativen Dispo-Import-Workflows jetzt ueber echte Router-Pfade verfuegbar
• Admin-/Systemsteuerung:
  • get_system_settings
  • update_system_settings
  • test_ai_connection
  • test_smtp_connection
  • test_gemini_connection
  • get_ai_configured
  • list_system_role_configs
  • update_system_role_config
  • list_webhooks
  • get_webhook
  • create_webhook
  • update_webhook
  • delete_webhook
  • test_webhook
  • Settings/Webhooks laufen ueber die echten Router; Secrets werden in Assistant-Antworten maskiert
• Estimates:
  • Suche
  • Detail / Weekly Phasing / Commercial Terms auf Controller-/Manager-/Admin-Niveau
  • zentrale Lifecycle-Mutationen inkl. Revision, Export und Planning Handoff
  • Restluecke: fachlich tiefere Unterobjekte und Spezialworkflows ausserhalb der bereits angebundenen Router-Operationen
• 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:
  • vereinfachte History-Abfragen
  • echte Audit-API fuer Liste, Detail, Entity-History, Timeline und Activity Summary
  • Governance-Workbench ausserhalb des Chats bleibt offen
• Notification/Tasking:
  • Self-Service-Reads und Reminder-Verwaltung vorhanden
  • Manager-/Admin-Lifecycle fuer Notification-, Task- und Broadcast-Workflows vorhanden
  • Restluecke: weitere Spezialfaelle ausserhalb der bereits exponierten Router-Operationen
• Country-/Location-Stammdaten: nur lesend und auch dort nur flach
• Insights: Summary-Ebene vorhanden, Drilldowns fehlen
• Rollen-/Client-/Org-Unit-Stammdaten:
  • Kernmutationen fuer Rollen, Clients und Org-Units laufen jetzt ueber die echten Router-Pfade statt ueber Assistant-Sonderlogik
  • Restluecke: weitere Readmodels und Lifecycle-Faelle ausserhalb der bereits exponierten Router-Operationen

Vollstaendig fehlend oder fachlich nicht ausreichend

• Country- und Metro-City-Administration ausserhalb der bereits vorhandenen Kernmutationen
• Governance-/Approval-Workspace ausserhalb des Chats

Kritische Inkonsistenzen und Risiken

Stand 2026-03-29: Die frueheren P0s bei Notification-Scoping, list_users, Mutation-Audit und reinen Permission-Texten sind behoben. Zusaetzlich sind User-Self-Service/Admin-Paritaet im Tool-Visibility-Layer, Manager-Notification-Lifecycle und die wichtigsten Estimate-Lifecycle-/Readmodel-Gates jetzt an die Router-Rollen angenaehert. Holiday-Calendar-Lesezugriffe sowie Admin-Mutationen fuer Kalender und Entries sind ebenfalls 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
• Weitere Admin-Stammdatenbereiche mit direkten Assistant-Queries, vor allem Resource-/Project-/Vacation-Spezialfaelle, brauchen weiterhin Router-Paritaet

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) jetzt auf Basis von auditLogRouter.list
• Entity-History (get_entity_timeline) jetzt auf Basis von auditLogRouter.getByEntity
• vollstaendige Audit-Readmodel-Paritaet:
  • list_audit_log_entries
  • get_audit_log_entry
  • get_audit_log_timeline
  • get_audit_activity_summary

Fehlend:

• dedizierte Governance-/Approval-Oberflaechen ausserhalb des Chats
• eine eigenstaendige Revisions-Workbench fuer offene Freigaben und operative Nachverfolgung

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

Aktuell im Assistant vorhanden:

• System Settings lesen/aktualisieren
• AI-/SMTP-/Gemini-Connection-Tests
• AI-Konfigurationsstatus lesen
• System-Role-Configs lesen/aktualisieren
• Webhooks lesen/anlegen/aendern/loeschen/testen

Restluecke:

• eigenstaendige Admin-Oberflaechen und mehrschrittige Governance-Workflows ausserhalb des Chats

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:

• Die wichtigsten Self-Service-Bausteine sind inzwischen vorhanden; offen bleiben vor allem tiefere persoenliche Einstellungs- und Spezialflows ausserhalb der bereits exponierten Router-Prozeduren.

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

Aktuell im Assistant vorhanden:

• Suche
• Detail / Weekly Phasing / Commercial Terms
• Anlegen, Klonen, Draft-Update, Submit, Approve, Revision, Export, Planning Handoff

Fehlend:

• tiefere Unterobjekt- und Spezialworkflows jenseits der bereits angebundenen Router-Prozeduren

Notifications, Tasks und Reminder

Vorhanden:

• Listen, Unread Count, Task-Detail, Task Counts, Statuswechsel
• Reminder anlegen, listen, aktualisieren, loeschen
• generische Notification-Erstellung, Task fuer User anlegen, Task zuweisen, Broadcast senden/listen

Fehlend:

• weitere Spezialfaelle ausserhalb der bereits exponierten Notification-Router-Prozeduren

Capability Gaps nach Router

Komplett fehlende Router-Paritaet

• derzeit keine in den zuvor priorisierten Admin-/Audit-/Import-Bereichen

Deutlich unvollstaendige Router-Paritaet

• importExport
• timeline (Kern-Readmodels und wichtigste Write-Paritaet vorhanden, Spezial-Workflows fehlen)
• vacation
• user
• estimate
• notification
• country
• insights
• scenario
• resource
• project
• comment

Nahe an brauchbarer Grundabdeckung, aber nicht vollstaendig

• resource
• project
• staffing
• report
• dashboard
• settings
• systemRoleConfig
• webhook
• importExport
• dispo

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
• Status: Kern-Read/Write-Pfad und Preview sind umgesetzt; offen bleiben nur weitergehende Editor-/Governance-Flows.

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
• Status: die zentralen Readmodels sind umgesetzt; offen bleibt vor allem breitere Reuse-Tiefe in weiteren Spezialansichten.

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.