20 — Reporting, Analytics & BI

Status: Not Started Depends On: Every prior numbered step whose data it reports on (this step is a read-only aggregation layer, not a new source of truth)

Goal

Covers mainPlan.md §14 in full. This step deliberately reads data other steps already own — it does not introduce new mutable entities.

Background / Context

Individual dashboards are already referenced piecemeal elsewhere (getRegionDashboard in 10_region_management.md, getStoreSalesDashboard in 12_store_management.md, getWarehouseKpis in 04_loading_event.md/07_ride_reconciliation.md context). This step is the role-aware, cross-cutting dashboard/report layer that sits above all of them.

Data Model Changes

None expected — this step reads existing tables. If a specific report proves too expensive to compute live, a cached/materialized summary table may be added per-report, decided when that report is actually built.

API Endpoints

Function reference	Endpoint intent
`getDashboardData(role, scope)`	`GET /api/dashboard?scope=...` — role taken from the authenticated user, not a request param
`generateKpiReport(kpiType, filters)`	`GET /api/reports/{kpiType}?filters=...`
`getPredictiveAlert(type, scope)`	`GET /api/alerts/predictive?type=...&scope=...` — explicitly flagged below as the highest-risk item in this step

Business Rules

getDashboardData must respect the same scope rules (IScopeAccessService) as every other endpoint — a dashboard is not an exception to region/route/store scoping.

Open Questions

getPredictiveAlert implies a forecasting/ML component that doesn't exist anywhere in this codebase today — is this in scope at all for the near term, or should it be dropped from this step until a concrete predictive use case and data volume exist to justify it?
Which specific KPIs matter first (fill rate, OOS%, credit risk are mentioned in the reference — confirm the actual priority list with the user before building generateKpiReport)?

Implementation Notes

Fill this section in during planning discussion before writing any code.

2.3 KiB Raw Blame History