Dashboards, KPIs & reports

This area covers the back-office's dashboards, reports and exports (cahier §4, §4.1, §1.4, §9 Exports, §14.2). Apps: back-office and API. Server module: analytics (KPI queries, daily aggregates refreshed from outbox events, report catalogue, export jobs). Money is in centimes of DZD and shown in DA; dates are cut in Africa/Algiers.

ID	Requirement	Release	Priority	Source	Apps
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	MUST	§4.1	BO · API
ANA-02	Dashboard filters (date, wilaya, commune, delegate, brand, category), role-configurable cards, permission-aware, refreshed after events	V1	MUST	§4.1	BO · API
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	MUST	§4	BO · API
ANA-04	Success KPIs tracked: adoption, field conversion, digitalisation share, tour performance, loyalty, operational quality	V1	SHOULD	§1.4	BO · API
ANA-05	PDF and Excel/CSV exports of authorised lists and reports	V1	MUST	§9	BO · API
ANA-06	Advanced analytics (cohorts, forecasting, delegate benchmarking)	V2	COULD	§14.2	BO · API

ANA-01 — General dashboardCopy Anchor Link

Statement — The back-office shall show a general dashboard with the KPIs below, each computed with one written definition.

Rules

1. KPI definitions (period = selected date range):

   KPI	Definition
   Revenue (day, month, year)	sum of order totals TTC of orders confirmed (VALIDATED) in the period and not CANCELLED, REFUSED or RETURNED
   Orders by status	count of orders per current OrderStatus, created in the period; à confirmer = SUBMITTED + PENDING
   Average basket	revenue ÷ number of orders counted in revenue
   Active / new / inactive resellers	active: ≥ 1 confirmed order in the last 60 days (crm.inactivityDays); new: accounts created in the period; inactive: at least one past order, none in 60 days
   Delegates on tour	tours IN_PROGRESS now
   Visits done / planned	DONE visits ÷ planned stops of the period
   Conversion	prospects visited that reached Compte créé or later (FLD-05)
   Best sellers	top 10 variants by quantity confirmed
   Stock alerts	variants at or below threshold, and out of stock (back-office only quantities)
   Expected payments	unpaid invoice balances due in the next 30 days
   Credit used, unpaid	sum of used credit; balances of OVERDUE invoices

2. Each card shows the value, the variation versus the previous equal period and links to the filtered list.

Acceptance criteria

• With 3 confirmed orders of 100 000, 200 000 and 300 000 centimes today and 1 cancelled, revenue shows 6 000,00 DA and average basket 2 000,00 DA.
• Clicking Commandes à confirmer opens the orders-to-confirm queue with the same count.

Data — Order, Reseller, Tour, Visit, StockLevel, Invoice, CreditAccount, DashboardLayout.

Interfaces

• Screens: BO-04 General dashboard · BO-05 Sales dashboard · BO-08 Finance dashboard
• Endpoints: admin.dashboard.kpis · admin.dashboard.charts

ANA-02 — Filters, role layouts, permissions, refreshCopy Anchor Link

Statement — Dashboards shall be filterable, configurable per role, limited to the user's permissions and refreshed after business events.

Rules

1. Filters: date range (today, 7 days, 30 days, this month, this year, custom up to 3 years), wilaya, commune, delegate, brand, category (with sub-categories). Brand and category apply to revenue and product KPIs; other cards show « filtre non applicable ».
2. Card layout per role (DashboardLayout), edited with settings.administer; a user sees only cards whose module they may view (finance cards need finance.view; purchase prices and margins never appear without the financial permission — ACL-04).
3. Freshness: counters refresh within 60 seconds of an event (outbox-driven aggregates, back-office stream); history recomputed nightly at 01:00.
4. KPI and chart queries answer in under 2 seconds p95 for a 12-month range.

Acceptance criteria

• A stock manager's dashboard shows no revenue or credit cards; filtering Oran changes revenue and visits.
• A new confirmed order changes today's revenue card within 60 seconds without reload.

Data — DashboardLayout, aggregates, Role.

Interfaces

• Screens: BO-04 General dashboard
• Endpoints: admin.dashboard.kpis · admin.dashboard.layout.get · admin.dashboard.layout.update

ANA-03 — Essential reportsCopy Anchor Link

Statement — The back-office shall provide the essential reports of the cahier with filters, totals and export.

Rules

1. Catalogue (report keys): sales.by_period, sales.by_zone, sales.by_delegate, sales.by_reseller, sales.by_brand, sales.by_product, field.conversion, field.first_orders, stock.outages, stock.slow_movers (no sale for 60 days with stock), orders.pending (SUBMITTED / PENDING older than 24 h), orders.late (confirmed and not shipped after 48 h), orders.cancelled, orders.returned.
2. Each report: filters, paginated rows, totals row, drill-down links; visible with reports.view plus the module's view permission; first page in under 3 seconds for 12 months of data.
3. Delegate performance uses the field definitions (FLD-02).

Acceptance criteria

• sales.by_delegate for last month equals the sum of the delegates' revenue on BO-17.
• A user without reports.view gets 403 PERMISSION_DENIED.

Data — Order, OrderItem, Product, StockLevel, Visit, Reseller, ReturnRequest.

Interfaces

• Screens: BO-05 Sales dashboard · BO-17 Delegate detail · BO-59 Reports library
• Endpoints: admin.delegates.performance · admin.reports.list · admin.reports.run

ANA-04 — Success KPIsCopy Anchor Link

Statement — The system shall track the six success indicators of the cahier.

Rules

Baselines are captured during the pilot (LCH-03) and reviewed at the go/no-go.

Acceptance criteria

• The KPI report shows the six indicators for the pilot period with their formulas in tooltips.

Data — aggregates, Invitation, Order, Visit.

Interfaces

• Screens: BO-59 Reports library
• Endpoints: admin.invitations.list · admin.reports.run

ANA-05 — PDF and Excel/CSV exportsCopy Anchor Link

Statement — Authorised users shall export lists and reports as PDF, XLSX or CSV.

Rules

1. Exports are asynchronous ExportJobs (QUEUED → RUNNING → SUCCEEDED / FAILED, then EXPIRED after exports.retentionDays = 7); the file is private (GENERATED_DOCUMENT) and downloaded through a 5-minute signed URL; the user is notified when ready.
2. Limits: 100 000 rows for XLSX/CSV, 2 000 rows for PDF (422 EXPORT_TOO_LARGE).
3. Content follows the user's permissions and scope at request time (no purchase price without the financial permission); CSV is UTF-8 with BOM and ; separator; amounts in DA with two decimals; dates in Africa/Algiers.
4. Every export is audited (EXPORT, filters, row count) and needs the module's export permission.

Acceptance criteria

• Exporting the filtered reseller list produces an XLSX with the same rows; without crm.export → 403 PERMISSION_DENIED; the audit log shows the export.

Data — ExportJob, File, AuditLog.

Interfaces

• Screens: BO-60 Export centre
• Endpoints: admin.resellers.export · admin.products.export · admin.exports.create · admin.exports.list · admin.exports.get

ANA-06 — Advanced analytics (V2)Copy Anchor Link

Statement — The system could provide cohort analysis, demand forecasting by zone, delegate benchmarking and reseller activity scoring.

Rules

1. Monthly sign-up cohorts with order retention; demand trend per category and zone; delegates ranked on comparable KPIs; an activity score per reseller feeding follow-ups.

Acceptance criteria

• The cohort table for a month of sign-ups shows the share ordering in each following month.

Data — aggregates.

Interfaces — none in V1.