Dashboards & KPIs

These four operations feed the general dashboard and the four business dashboards of the back-office (BO-04 to BO-08). They answer cahier §4.1: revenue per day, month and year, orders by status and average basket, active / new / inactive resellers, delegates on tour, visits and conversion, best sellers, stock alerts, expected payments, credit used and unpaid invoices — filtered by date, wilaya, commune, delegate, brand and category, permission-aware and refreshed after business events (ANA-01, ANA-02). Since the 17 Oct 2026 decisions every order waits for a person, so the dashboards also carry the orders to confirm card (ORD-14).

Who uses it. Every back-office role opens a dashboard after sign-in: the Super administrateur and the Administrateur commercial (general and sales dashboards), the Responsable stock (stock dashboard), the Responsable finance (finance dashboard), the Responsable livraison (orders to prepare and ship) and the Direction (read-only KPIs). The cards each user receives are the intersection of their role's layout and their permissions.

Freshness. KPIs are computed from aggregates that the worker updates from OutboxEvents (order, visit, tour, stock, invoice and payment events) — typically within seconds; dataAsOf says how fresh they are. Snapshot cards (orders to confirm, delegates on tour, stock alerts, unpaid) read live tables. After an event that changes cards, the SSE stream sends dashboard.invalidated (at most one per 10 s per user) with the keys of the affected cards; the dashboard re-fetches only those. Nothing here is polled faster than once a minute.

Audit. Reads are not journaled. A layout change writes an AuditLog row UPDATE on DashboardLayout with the before/after card list.

Conventions: amounts are integer centimes of DZD, rates are basis points (1250 = 12,5 %); dates in filters are YYYY-MM-DD in Africa/Algiers; revenue is HT, net of discounts, without delivery fees. Shared schemas (UserSummary, Price, Totals, FileRef…) are on the API index; 401, 429 and 500 apply everywhere and are not repeated.

Card catalogueCopy Anchor Link

Every card has a stable key. The table gives its formula (the server computes exactly this; reports use the same definitions), the extra permission (any one of the listed keys, in addition to dashboard.view), and whether the period filter applies or the card is a snapshot of "now".

Filter applicability. Filters narrow the population each card counts; a filter that has no meaning for a card is ignored for it and listed in that card's ignoredFilters.

GET /admin/dashboard/kpisCopy Anchor Link

admin.dashboard.kpis · Permission dashboard.view (+ per card) · Apps BO · Release V1 · Requirements ANA-01 · ANA-02 · ORD-14

Purpose. Returns the KPI cards of a dashboard for a period and a set of filters, each with its value, comparison and breakdown.

Request

Response 200 OK

{
  "period": { "from": "2026-11-01", "to": "2026-11-15", "timezone": "Africa/Algiers" },
  "filters": { "wilayaCode": ["31"], "communeId": [], "delegateId": [], "brandId": [], "categoryId": [] },
  "generatedAt": "2026-11-15T09:30:04Z",
  "dataAsOf": "2026-11-15T09:29:58Z",
  "cards": {
    "revenue.today": {
      "unit": "MONEY", "value": 18450000, "previous": 16120000, "deltaBps": 1445,
      "comparison": "SAME_WEEKDAY_PREVIOUS_WEEK", "ordersCount": 9, "ignoredFilters": []
    },
    "revenue.month": {
      "unit": "MONEY", "value": 214380000, "previous": 197550000, "deltaBps": 851,
      "comparison": "PREVIOUS_MONTH_SAME_DAYS", "ordersCount": 118, "ignoredFilters": []
    },
    "revenue.year": {
      "unit": "MONEY", "value": 3958120000, "previous": null, "deltaBps": null,
      "comparison": "PREVIOUS_YEAR_TO_DATE", "ordersCount": 2264, "ignoredFilters": []
    },
    "orders.toConfirm": {
      "unit": "COUNT", "value": 14,
      "breakdown": { "new": 9, "onHold": 3, "assisted": 2 },
      "overdue": 2, "oldestSubmittedAt": "2026-11-14T07:41:00Z", "ignoredFilters": []
    },
    "orders.byStatus": {
      "unit": "COUNT",
      "open": { "SUBMITTED": 9, "PENDING": 5, "VALIDATED": 11, "PREPARING": 6, "READY": 4, "SHIPPED": 17 },
      "period": { "DELIVERED": 92, "REFUSED": 3, "CANCELLED": 6, "RETURNED": 1 },
      "ignoredFilters": []
    },
    "orders.averageBasket": { "unit": "MONEY", "value": 1816780, "previous": 1752700, "deltaBps": 366, "ignoredFilters": [] },
    "orders.firstOrders": { "unit": "COUNT", "value": 7, "assisted": 4, "previous": 5, "deltaBps": 4000, "ignoredFilters": [] },
    "resellers.active": { "unit": "COUNT", "value": 286, "total": 412, "windowDays": 60, "ignoredFilters": [] },
    "resellers.new": { "unit": "COUNT", "value": 12, "signups": 15, "previous": 9, "deltaBps": 3333, "ignoredFilters": [] },
    "resellers.inactive": { "unit": "COUNT", "value": 94, "neverOrdered": 32, "windowDays": 60, "ignoredFilters": [] },
    "field.delegatesOnTour": { "unit": "COUNT", "value": 6, "withTourToday": 8, "activeDelegates": 11, "ignoredFilters": [] },
    "field.visits": { "unit": "COUNT", "value": 214, "planned": 251, "notDone": 29, "rateBps": 8526, "ignoredFilters": [] },
    "field.prospectConversion": {
      "unit": "BPS", "value": 1667, "prospects": 42, "accountsCreated": 19, "firstOrders": 7, "ignoredFilters": []
    },
    "catalog.bestSellers": {
      "unit": "COUNT",
      "items": [
        { "variantId": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "sku": "HC-X14-CC-1M-BK", "productName": "Câble USB-C vers USB-C 60 W 1 m", "brandName": "HOCO", "units": 1840, "revenueHt": 64400000 },
        { "variantId": "0192b215-7a8b-7c9d-8e0f-1a2b3c4d5e6f", "sku": "AF-A29-50W-WH", "productName": "Chargeur GaN 50 W 2 ports", "brandName": "ACEFAST", "units": 310, "revenueHt": 61380000 }
      ],
      "ignoredFilters": []
    },
    "stock.alerts": { "unit": "COUNT", "value": 23, "out": 8, "low": 15, "ignoredFilters": ["wilayaCode"] },
    "finance.expectedPayments": { "unit": "MONEY", "value": 48620000, "invoicesDue": 31, "codToCollect": 9874600, "ignoredFilters": [] },
    "finance.creditUsed": { "unit": "MONEY", "value": 162400000, "limitTotal": 450000000, "utilisationBps": 3609, "accountsOverLimit": 3, "ignoredFilters": [] },
    "finance.unpaid": {
      "unit": "MONEY", "value": 21730000, "invoices": 17,
      "aging": { "1-30": 12480000, "31-60": 6150000, "61-90": 2100000, "90+": 1000000 },
      "ignoredFilters": []
    },
    "finance.pendingDeclarations": { "unit": "MONEY", "value": 5390000, "count": 6, "ignoredFilters": [] },
    "afterSales.open": { "unit": "COUNT", "value": 5, "claims": 3, "returns": 2, "ignoredFilters": [] }
  }
}

Field notes.

• cards is an object keyed by card key; a card the caller may not see is absent (not null). The Direction role, for example, typically gets no finance.pendingDeclarations.
• unit is MONEY (centimes), COUNT or BPS. deltaBps = (value − previous) ÷ previous in basis points, null when previous is 0 or unavailable (no data for the comparison period, as for the first year above).
• comparison is one of SAME_WEEKDAY_PREVIOUS_WEEK, PREVIOUS_MONTH_SAME_DAYS, PREVIOUS_YEAR_TO_DATE, PREVIOUS_PERIOD.
• catalog.bestSellers returns items instead of value; product names are data and returned as stored.

Errors

Rules & side effects

1. Read-only. Permission filtering happens before computation: a card the caller may not see is never computed, so its existence costs nothing and leaks nothing.
2. Business days and "today" are computed in Africa/Algiers; a validation at 23:30 UTC on 14 Nov counts on 15 Nov.
3. Revenue counts an order once, on its validatedAt (the back-office confirmation), whatever happens later except cancellation or refusal; credit notes (returns, after-sales) are subtracted on their issue date, so returned goods reduce the revenue of the day the credit note is issued.
4. Orders to confirm include every channel — reseller app, web, assisted and back-office — because no order is confirmed automatically (cahier §4.4, ORD-14). The card links to the queue admin.orders.toConfirm.
5. Results for identical parameters are cached 60 s per permission set; an outbox event affecting a card evicts the cache and emits dashboard.invalidated.

Used by BO-04 · BO-05 · BO-06 · BO-07 · BO-08

GET /admin/dashboard/charts/{chartKey}Copy Anchor Link

admin.dashboard.charts · Permission dashboard.view (+ per chart) · Apps BO · Release V1 · Requirements ANA-01

Purpose. Returns the series of one dashboard chart for the same period and filters as the cards.

Request

interface ChartResponse {
  chartKey: string;
  kind: "TIME_SERIES" | "CATEGORICAL" | "FUNNEL";
  unit: "MONEY" | "COUNT" | "BPS";
  granularity?: "DAY" | "WEEK" | "MONTH";     // TIME_SERIES only
  series: {
    key: string;                              // "revenue", "previous", an enum value, a wilaya code…
    label?: string;                           // only for data labels (product, brand, category names) — never for enum values
    points: { x: string; y: number; meta?: Record<string, number | string> }[];
  }[];
  totals?: Record<string, number>;
  period: { from: string; to: string };
  generatedAt: Iso;
}

Response 200 OK — revenue_trend, weekly, with comparison

{
  "chartKey": "revenue_trend",
  "kind": "TIME_SERIES",
  "unit": "MONEY",
  "granularity": "WEEK",
  "series": [
    { "key": "revenue", "points": [
      { "x": "2026-10-25", "y": 58210000 },
      { "x": "2026-11-01", "y": 71460000 },
      { "x": "2026-11-08", "y": 84730000 }
    ] },
    { "key": "previous", "points": [
      { "x": "2026-10-25", "y": 52900000 },
      { "x": "2026-11-01", "y": 66150000 },
      { "x": "2026-11-08", "y": 70020000 }
    ] }
  ],
  "totals": { "revenue": 214400000, "previous": 189070000 },
  "period": { "from": "2026-10-25", "to": "2026-11-14" },
  "generatedAt": "2026-11-15T09:30:05Z"
}

conversion_funnel returns a single series whose points are the steps in order ({ "x": "prospects", "y": 42 }, { "x": "appInstalled", "y": 23 }…). Time points are the first day of each bucket; empty buckets are returned with y: 0 so the client never interpolates.

Errors

Rules & side effects

1. Read-only; same definitions as the cards (revenue on validatedAt, HT net of discounts, credit notes subtracted).
2. Unlike cards, a chart the caller may not see answers 403 — the client only asks for charts of its layout, which is already filtered.
3. Cached 60 s per parameters and permission set; evicted with the cards.

Used by BO-04 · BO-05 · BO-06 · BO-07 · BO-08

GET /admin/dashboard/layoutCopy Anchor Link

admin.dashboard.layout.get · Permission dashboard.view · Apps BO · Release V1 · Requirements ANA-02

Purpose. Returns the cards and charts of the caller's dashboards, as configured for their role and filtered by their permissions.

Request

Response 200 OK

{
  "board": "GENERAL",
  "roleKey": "COMMERCIAL_ADMIN",
  "source": "ROLE",
  "updatedAt": "2026-11-02T10:14:00Z",
  "cards": [
    { "key": "orders.toConfirm", "size": "M", "row": 0, "col": 0 },
    { "key": "revenue.today", "size": "S", "row": 0, "col": 4 },
    { "key": "revenue.month", "size": "S", "row": 0, "col": 7 },
    { "key": "orders.averageBasket", "size": "S", "row": 0, "col": 10 },
    { "key": "resellers.active", "size": "S", "row": 1, "col": 0 },
    { "key": "field.delegatesOnTour", "size": "S", "row": 1, "col": 3 },
    { "key": "field.prospectConversion", "size": "S", "row": 1, "col": 6 },
    { "key": "orders.firstOrders", "size": "S", "row": 1, "col": 9 }
  ],
  "charts": [
    { "key": "revenue_trend", "size": "L", "row": 2, "col": 0 },
    { "key": "conversion_funnel", "size": "M", "row": 2, "col": 8 }
  ],
  "defaultFilters": { "period": "MONTH_TO_DATE" }
}

Field notes.

• Grid: 12 columns; size S = 3 columns, M = 4, L = 8, XL = 12; rows are 1 unit high for cards and 3 units for charts.
• source is ROLE (a configured DashboardLayout) or DEFAULT (the built-in default below).
• A user holding several roles gets the layout of their highest role in this order: SUPER_ADMIN, COMMERCIAL_ADMIN, FINANCE_MANAGER, STOCK_MANAGER, DELIVERY_MANAGER, DIRECTION; cards and charts they may not see are removed (the remaining ones keep their positions).
• defaultFilters.period: TODAY, WEEK_TO_DATE, MONTH_TO_DATE, YEAR_TO_DATE.

Built-in defaults of the GENERAL board (used until a role is configured):

Errors

Rules & side effects

1. Read-only; the layout is cached per role and board and evicted by admin.dashboard.layout.update.
2. The response never contains cards for permissions the caller lacks, so the client renders it as is.

Used by BO-03 · BO-04 · BO-05 · BO-06 · BO-07 · BO-08

PUT /admin/dashboard/layout/{roleKey}Copy Anchor Link

admin.dashboard.layout.update · Permission settings.administer · Apps BO · Release V1 · Requirements ANA-02

Purpose. Replaces the cards and charts of one board for one role (cahier §4.1 « Les cartes du tableau de bord doivent être configurables par rôle »).

Request

interface UpdateDashboardLayoutBody {
  board: "GENERAL" | "SALES" | "FIELD" | "STOCK" | "FINANCE";
  cards: { key: string; size: "S" | "M" | "L" | "XL"; row: number; col: number }[];   // 1–16 cards
  charts: { key: string; size: "M" | "L" | "XL"; row: number; col: number }[];        // 0–6 charts
  defaultFilters?: { period: "TODAY" | "WEEK_TO_DATE" | "MONTH_TO_DATE" | "YEAR_TO_DATE" };
  resetToDefault?: boolean;          // true: delete the role's layout and fall back to the built-in default (cards/charts ignored)
  version?: number;
}

{
  "board": "FINANCE",
  "cards": [
    { "key": "finance.unpaid", "size": "M", "row": 0, "col": 0 },
    { "key": "finance.expectedPayments", "size": "M", "row": 0, "col": 4 },
    { "key": "finance.pendingDeclarations", "size": "M", "row": 0, "col": 8 },
    { "key": "finance.creditUsed", "size": "M", "row": 1, "col": 0 }
  ],
  "charts": [{ "key": "receivables_aging", "size": "L", "row": 2, "col": 0 }],
  "defaultFilters": { "period": "MONTH_TO_DATE" },
  "version": 3
}

Response 200 OK — the stored layout, same shape as admin.dashboard.layout.get with "source": "ROLE", "roleKey": "FINANCE_MANAGER" and "version": 4.

Errors

Rules & side effects

1. A layout may contain cards whose permission the role does not hold today; they are kept (the role may get the permission later) and filtered at read time. The response lists them in warnings: [{ key, missingPermission }].
2. Writes one DashboardLayout row per role and board; AuditLog UPDATE (entity DashboardLayout, label FINANCE_MANAGER/FINANCE) with the before/after lists.
3. SSE: dashboard.invalidated with layout: true to the connected users of that role, who reload their layout.
4. No notification.

Used by BO-04 (edit mode) · BO-64