487 lines
17 KiB
Markdown
487 lines
17 KiB
Markdown
# 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.
|