Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P28h.md
T

109 lines
5.2 KiB
Markdown

# VA-P28h · Admin Sales Reporting & Dashboard
| | |
|---|---|
| **Plane** | `HIVEGRID-196` · Parent `HIVEGRID-190` |
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P28 — Admin Sales Workspace |
| **Cycle/Fenster** | Backlog · nach den fachlichen Sales-Event-Verträgen |
| **Status** | geplant |
> **Owner-Änderung 2026-07-24:** Raffael übernimmt die Delivery. Working-ID, Scope, Status,
> Termine, DoD und Abhängigkeiten bleiben unverändert.
>
> **Dependency-Nachzug 2026-07-24:** Auch `VA-P28b` liegt jetzt bei Raffael; sämtliche
> Event-/KPI-Quellverträge sowie `blocked-by`/`blocks` bleiben unverändert.
## Abhängigkeiten & Parallelität
- **Blocked by:** `VA-P28b`; KPI-spezifisch zusätzlich `VA-P28c`, `VA-P28d`, `VA-P28e`, `VA-P28f`
und `VA-P28g`; außerdem `VR-P28a-RBAC` für Rollen-, Own-/All-Scope- und
serverseitigen Widget-Allowlist-Vertrag.
- **Blocks:** —
- **Design:** `VD-P28`, nach AD-28 kein Dev-Blocker.
- **Hardgrenze:** ausschließlich Admin-Sales-Daten; Tenant-Betriebs-KPIs aus `AK-P19` bleiben getrennt.
## Was wir bauen
Einen dokumentierten Admin-Sales-KPI-Vertrag, belastbare Aggregate, Ziele/Leaderboard, konfigurierbare
Dashboards und geplanten Reportversand für Vertriebsleitung und Geschäftsführung.
## Story-Ownership — 13/117
- `REPORT-01` Gewichteten Pipeline-Forecast sehen.
- `REPORT-02` Konversion je Stufe sehen.
- `REPORT-03` Verteilung der Verlustgründe sehen.
- `REPORT-04` Aktivität je Mitarbeiter sehen.
- `REPORT-05` Umsatz- und Abschlussziele je Nutzer setzen und verfolgen.
- `REPORT-06` Ziele je Team setzen.
- `REPORT-07` Leaderboard sehen.
- `REPORT-08` Durchschnittliche Zykluszeit/Sales-Velocity sehen.
- `REPORT-09` Win-Rate sehen.
- `REPORT-10` MRR und ARR auswerten.
- `REPORT-11` Churn auswerten.
- `REPORT-12` Reports planen und automatisch versenden.
- `REPORT-13` Dashboard mit eigenen Kacheln zusammenstellen.
## Benötigte Screens
| Screen [Admin-Host-Route] | Kern-Inhalt |
|---|---|
| Dashboard [`/sales/dashboard`] | frei angeordnete, registrierte KPI-Kacheln |
| Pipeline [`/sales/reports/pipeline`] | Forecast, Conversion, Loss, Velocity, Win-Rate |
| Aktivität [`/sales/reports/activity`] | Calls, Mails, Meetings, Tasks und Deals je Mitarbeiter |
| Revenue [`/sales/reports/revenue`] | Bookings, MRR, ARR, Renewal und Churn |
| Ziele [`/sales/goals`] | Nutzer-/Teamziele und Leaderboard |
| Schedules [`/sales/reports/schedules`] | Report, Filter, Empfänger, Frequenz, letzte Zustellung |
## Definition of Done
- [ ] Jede Kennzahl besitzt eine versionierte, dokumentierte Formel mit Zeitbezug, Zeitzone, Währung,
Filterbasis, Ein-/Ausschlüssen und deterministischen Fixtures.
- [ ] Forecast, Stage-Conversion, Verlustgründe, Sales-Velocity und Win-Rate basieren auf
`AdminDealStageHistory`/Events statt nur auf aktuellem Zustand.
- [ ] Aktivitätsauswertung trennt Call, Mail, Meeting, Task und Deal je AdminUser und respektiert
Rollen-/Sichtbarkeitsrechte.
- [ ] Nutzer-/Teamziele, Fortschritt und Leaderboard sind perioden- und währungsfest; Zieländerungen werden
historisiert und auditiert.
- [ ] MRR/ARR basieren auf Revenue-Schedules/Subscription-Link; Churn basiert auf verknüpftem Subscription-
Status und dokumentierter Churn-Formel.
- [ ] Dashboard Builder verwendet ausschließlich eine registrierte Tile-Allowlist mit sicheren Filtern;
keine freie Query, kein freies HTML und keine Codeausführung.
- [ ] Geplante Reports speichern Definition/Empfänger/Frequenz, berechnen Berechtigungen zum Ausführungszeitpunkt
neu und versenden über zentralen Notification-/Mail-Pfad mit Delivery-Historie.
- [ ] Aggregate sind idempotent neu aufbaubar, beobachten Lag/Fehler und stimmen per Contract-Test mit
Source-Events überein.
- [ ] Admin-RBAC, Audit, i18n, Empty/Loading/Error/404, VM-/Action-Layer sowie Unit-/DB-/Aggregate-/Smoke-/
Hot-Swap-/Visual- und Scheduled-Delivery-Tests sind grün.
**Fortschritt:** **0/9 DoD = 0 % done**.
## Technische Bausteine
- **Schema:** `prisma/schema/adminSalesReporting.prisma`.
- **Modelle:** `AdminSalesGoal`, `AdminSalesTeam`, `AdminSalesTeamMember`, `AdminDashboard`,
`AdminDashboardTile`, `AdminReportDefinition`, `AdminReportSchedule`, `AdminReportDelivery` plus
versionierte Aggregate/Materialisierungen.
- **KPI Registry:** zentrale ID, Formelversion, benötigte Permission, Filter-/Drilldown-Schema und Renderer-VM.
- **Wiederverwendung:** Dashboard-Registry/Chart-Komponenten dürfen extrahiert werden; keine Tenant-Queries
oder Tenant-KPI-Tabellen als Admin-Source-of-Truth.
## Slices und Rollback
KPI-Verträge/Aggregate → Pipeline/Activity/Revenue → Goals/Leaderboard → Dashboard Builder →
Scheduled Delivery. Jede Formelversion bleibt reproduzierbar; Rollback setzt Tile/Report auf letzte stabile
Version und löscht keine historischen Aggregate.
## Quellen
- Ticket-Docs `VA-P28b` bis `VA-P28g`, `VD-P28`
- `docs/ARCHITECTURE-DECISIONS.md` — AD-27/AD-28
- AGENTS.md — Reporting-/Notification-/VM-/Test-Verträge
## Dev-Nachzug
- [ ] KPI-Formeln, Goal-Perioden und Leaderboard-Sichtbarkeit in der Block-Review bestätigen.
- [ ] Berichtsempfänger/Dateiformat/Retention festschreiben.
- [ ] Davids `VD-P28`-Delta integrieren und Visual-Baselines erneuern.