# 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.