SRV-25 — Analytics, reports & exports
KPI and chart queries with permission-aware filters, daily aggregates, the essential report catalogue and async PDF/XLSX/CSV exports.
| Field | Details |
|---|---|
| Task code | SRV-25 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 1.25 person-day(s) planned · 6 from scratch · size S |
| Area · app | Server · server |
| Depends on | SRV-16, SRV-21 |
| Unblocks | DSH-02, DSH-11 |
| Milestones | — |
Summary
KPI and chart queries with permission-aware filters, daily aggregates, the essential report catalogue and async PDF/XLSX/CSV exports.
Description
Direction and managers steer the business from dashboards and reports (cahier §1.4, §4, §4.1, §9; ANA-01…ANA-05). This task implements permission-aware KPI and chart queries (admin.dashboard.kpis, admin.dashboard.charts/{chartKey}) with the filters of ANA-02 (date, wilaya, commune, delegate, brand, category), role-configurable layouts (DashboardLayout), daily aggregates maintained by a job and refreshed from events, the essential report catalogue (admin.reports.list/run: revenue by period, zone, delegate, reseller, brand and product; conversion and first orders; stock-outs and slow movers; pending, late, cancelled and returned orders), the success KPIs of §1.4 (adoption, digitalisation share by channel, field conversion, tour performance, operational quality) and asynchronous PDF/XLSX/CSV exports (ExportJob). Days are bucketed in Africa/Algiers. Out of scope: dashboard and report pages (DSH-02, DSH-11) and advanced analytics (V2, SRV-38).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Metric definitions (revenue on validated vs delivered orders, active/new/inactive resellers, conversion, average basket, digitalisation share) documented and agreed | Anis |
| 2 | Daily aggregate tables (orders × day × wilaya × delegate × brand, visits, sign-ups, stock-outs, returns) built by a nightly job and incremental event consumers | Anis |
| 3 | admin.dashboard.kpis and charts with ANA-02 filters, permission-aware widgets (finance KPIs need finance.view) | Anis |
| 4 | DashboardLayout per role: admin.dashboard.layout.get/update | Anis |
| 5 | Report catalogue with parameter schemas and totals: revenue reports, conversion and first orders by delegate, stock-outs and slow movers, order quality (pending, late, cancelled, returned) | Anis |
| 6 | KPI set of cahier §1.4 for the pilot (adoption, digitalisation share, field conversion, tour performance, operational quality) | Anis |
| 7 | Export jobs: admin.exports.create/list/get, PDF/XLSX/CSV writers in the worker, row limits, signed download URL valid 7 days, EXPORT audit entry | Anis |
| 8 | Cache of KPI responses per filter hash (60 s) invalidated by relevant events | Anis |
Deliverables
- apps/server/src/modules/analytics/{metrics.ts,aggregates.job.ts,consumers.ts,dashboard.router.ts,reports/,router.ts}
- apps/server/src/modules/analytics/exports/{xlsx,csv,pdf}.ts
- Metrics glossary section in /docs/srs/business-rules
Acceptance criteria
- KPI values on a seeded dataset equal hand-computed expected values for revenue, orders by status, average basket and conversion (ANA-01)
- A user without finance.view receives no finance KPIs (ANA-02, ACL-04)
- Each report of the catalogue runs with its filters and returns totals that match the detail rows (ANA-03)
- A 50 000-row XLSX export completes in the worker and is downloadable from the export centre; the action is audited (ANA-05)
- Day boundaries follow Africa/Algiers: an order at 23:30 UTC on 31 Dec counts on 1 Jan
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| ANA-01 | General dashboard: revenue, orders by status, average basket, active/new/inactive resellers, delegates on tour, visits, conversion, best sellers, stock alerts, expected payments, credit used, unpaid | V1 |
| ANA-02 | Dashboard filters (date, wilaya, commune, delegate, brand, category), role-configurable cards, permission-aware, refreshed after events | V1 |
| ANA-03 | Essential reports: revenue by period/zone/delegate/reseller/brand/product, conversion and first orders, stock-outs and slow movers, pending/late/cancelled/returned orders | V1 |
| ANA-04 | Success KPIs tracked: adoption, field conversion, digitalisation share, tour performance, loyalty, operational quality | V1 |
| ANA-05 | PDF and Excel/CSV exports of authorised lists and reports | V1 |
API surface
| Endpoint group | Operations |
|---|---|
| Dashboards & KPIs | 4 |
| Reports & exports | 5 |
Test measures
- DB tests with a fixed seeded dataset and expected KPI fixtures
- Unit tests for Africa/Algiers bucketing
- Load check of the heaviest report on a production-sized synthetic dataset
Risks
- Metric definitions disputed by HOCO after launch — glossary agreed in QA-01 and shown as tooltips on the dashboards
KPI
- Delivered by Mon 19 Oct 2026 within 1.25 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
SRV-40 — Smart notification triggers & jobs (V1 types, caps, priority, merge)
Rule-based triggers for the V1 smart notifications of document 03 — new arrival, back in stock, limited quantity, flash sale, price drop, commercial push, new catalogue, trending, abandoned cart, reorder reminder, complementary product — plus the anti-fatigue layer (weekly cap, priority, merge, per-product cool-down, group opt-out) and action labels.
SRV-27 — Data imports — products, resellers, users, stock
Excel/CSV import jobs with templates, dry-run validation report, idempotent apply and error rows export.