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