# 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](./mainPlan.md#14-reporting-analytics--bi) 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](./10_region_management.md), `getStoreSalesDashboard` in
[12_store_management.md](./12_store_management.md), `getWarehouseKpis` in
[04_loading_event.md](./04_loading_event.md)/[07_ride_reconciliation.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.