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.