Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,65 @@
+# 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.