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.

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: nur indirekt ueber Navigation und Allokations-Basisabfragen
• Estimates: nur Suche, Detail und Anlegen, aber kein voller Lifecycle
• Reports: run_report ist flexibel, deckt aber nicht die spezialisierten Report-/Analyse-Readmodels ab
• 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

• Holiday-Calendar-Admin und Editor-Funktionen
• Computation Graph fuer vollstaendige Herleitungen
• Chargeability Report Readmodel
• 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
• Volle Timeline-Readmodels und Timeline-Mutationen
• Voller Estimate-Lifecycle
• Dispo-/Import-spezifische Flows

Kritische Inkonsistenzen und Risiken

P0: Human-in-the-Loop nur im Prompt, nicht serverseitig erzwungen

Der System Prompt fordert bestaetigte Freigabe vor jeder schreibenden Aktion. Technisch wird das aber nicht serverseitig erzwungen. Wenn das Modell direkt ein Mutation-Tool aufruft, wird es ausgefuehrt.

Betroffene Stellen:

• packages/api/src/router/assistant.ts
• packages/api/src/router/assistant-tools.ts

Konsequenz:

• Die wichtigste Governance-Regel ist aktuell nur Prompt-Disziplin, keine technische Policy.

P0: Notification-Scoping im Assistant ist fachlich/sicherheitsseitig falsch

Die dedizierte notificationRouter scoped strikt auf den aktuellen Nutzer. Die Assistant-Tools tun das in list_notifications und mark_notification_read nicht.

Assistant-Verhalten:

• list_notifications listet Notifications ohne userId-Filter.
• mark_notification_read markiert per ID ohne Ownership-Check.

Konsequenz:

• Der Assistant kann Informationen sehen oder veraendern, die der Nutzer in der normalen Notification-UI nicht sehen duerfte.

P0: list_users ist als admin-only beschrieben, aber nicht effektiv admin-only

Der Tool-Text sagt "Requires admin permission", aber es gibt weder einen Eintrag in TOOL_PERMISSION_MAP noch einen assertPermission(...) im Executor.

Konsequenz:

• Jeder Nutzer mit Assistant-Zugriff kann potenziell die User-Liste lesen, obwohl die normale App dies ueber userRouter.list nur Admins gibt.

P1: Permission-Beschreibungen und technische Guards sind nicht konsistent

Beispiele:

• create_estimate

  • Beschreibung: "Requires manageEstimates permission"
  • Technik: TOOL_PERMISSION_MAP und Executor verlangen manageProjects

• create_org_unit / update_org_unit

  • Beschreibung: "Requires admin permission"
  • Technik: manageResources

• send_broadcast

  • Beschreibung: "Requires manager permission"
  • Technik: manageProjects

Konsequenz:

• Der Assistant ist fuer Nutzer und fuer uns selbst schwer vorhersehbar.
• Ein sauberer Rechteabgleich "User kann X in UI, also Assistant auch" ist dadurch nicht belastbar.

P1: Nicht alle Assistant-Mutationen sind als Mutation-Typ sauber nachverfolgbar

MUTATION_TOOLS dient dem Logging von AI-Mutationen. Nicht jede schreibende Aktion ist dort gleich gut abgebildet.

Beispiel:

• mark_notification_read aendert Daten, ist aber nicht in MUTATION_TOOLS.

Konsequenz:

• Luecken im AI-spezifischen Audit-Trail.

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

Fehlend:

• die eigentlichen Kalenderobjekte und deren Pflegekontext

Timeline und Disposition

• Vollstaendiges Timeline-Readmodel:
  • getEntriesView
  • Projekt-/Demand-/Assignment-Kontext in derselben Struktur wie die UI
  • Holiday-Overlays der Timeline
  • Projektkontext fuer Drag/Shift/Panel-Interaktionen
• Timeline-spezifische Vorschau-/Validierungsdaten:
  • previewShift
  • genaue Konflikte, Kosten-Delta, Auswirkungen vor Commit
• Batch- und Inline-Operationen der Timeline:
  • updateAllocationInline
  • quickAssign
  • batchQuickAssign
  • batchShiftAllocations
  • applyShift
• Dispo-spezifische Import-/Workbook-Flows

Konsequenz:

• Der Assistant kann heute nicht denselben Timeline-Arbeitsmodus wie ein Nutzer in der UI abbilden.

Transparenz, Herleitungen und Berechnungsgraphen

• 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 zwar Teilantworten zu Chargeability/Budget geben, aber noch nicht dieselbe Erklaerungstiefe wie die spezialisierten Analyseansichten.

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

• Country-Details inklusive scheduleRules
• Metro-City-Verwaltung
• Country-/City-CRUD

Aktuell im Assistant vorhanden:

• list_countries mit relativ flachem Output

Fehlend:

• volle fachliche Pflege und die tieferen Standortregeln, die fuer Feiertage, SAH und Forecasts relevant sind

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

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

Deutlich unvollstaendige Router-Paritaet

• timeline
• 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

• "Urlaub, Feiertage" ist fuer Leseabfragen ok, aber nicht fuer Holiday-Calendar-Administration.
• "Notifications anzeigen" stimmt nur eingeschraenkt, weil das Assistant-Tooling aktuell nicht sauber auf den aktuellen Nutzer scoped.
• "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 wird als harte Pflicht formuliert, ist technisch aber nicht hart erzwungen.

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.

• Schreibende Tool-Calls duerfen ohne bestaetigten Confirmation-Token nicht ausgefuehrt werden.
• Diese Policy darf nicht nur im Prompt stehen.

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:
  • get_timeline_entries_view
  • get_timeline_holiday_overlays
  • get_timeline_project_context
  • preview_project_shift
• 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

• Country-Detail
• Country-Create/Update
• City-Create/Update/Delete

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

• serverseitige Confirmation-Gates
• Ownership-/Permission-Fixes
• Mutation-Audit vervollstaendigen

Stream B: Holiday + Timeline Parity

• Holiday-Calendar-Editor-Tools
• Timeline-Readmodels
• 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 serverseitige Absicherung fuer schreibende AI-Aktionen,
2. unvollstaendige fachliche Paritaet in Holiday/Timeline/Analytics/Admin-Bereichen,
3. inkonsistente oder zu schwache Permission- und Ownership-Pruefungen in einzelnen Tools.