> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Dashboards — verified Dashboard API handoff

**Source review:** `main` branch of `alalmiyalhura/outlet`: [routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Dashboards/Routes/api.php), [DashboardController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Dashboards/Interfaces/Http/Controllers/DashboardController.php), [HomeController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Dashboards/Interfaces/Http/Controllers/HomeController.php), [DashboardService](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Dashboards/Application/DashboardService.php), [HomeScreen](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Dashboards/Application/HomeScreen.php). Reviewed against source, **not** captured from a live server. All paths use `/api/v1`.

## Common request and access

All three endpoints require `Authorization: Bearer <sanctum_token>` and permission `dashboards.view`. Use `Accept: application/json`. No request body. `/dashboards/{dashboard}` and `/admin/home` have `throttle:60,1` (60 requests/minute); `/dashboards` does not have that route-specific throttle. Data is localized to request locale. Response convention is `{"data": ...}` via `ApiResponse::ok`.

The two detail endpoints accept the same period query:

| Field | Type | Required | Validation / behavior |
|---|---|---|---|
| `period` | string | No | Max 10 characters; recognized presets: `today`, `yesterday`, `7d`, `30d`, `90d`, `mtd`, `qtd`, `ytd`; defaults to `30d` |
| `from` | string | With `to` | Exactly 10 characters; business period parser checks date/range |
| `to` | string | With `from` | Exactly 10 characters; business period parser checks date/range |

`from` and `to` take precedence over `period`. Use ISO dates `YYYY-MM-DD`. The `period` response is `{from: string, to: string, days: integer}`; `to` is inclusive in the JSON even though the internal period end is exclusive. The controller's initial validator only checks lengths for explicit dates; the domain period parser enforces further constraints.

## 1. `GET /api/v1/dashboards`

**Screen:** Dashboard selector/navigation. **Permission:** `dashboards.view`.

No query or body parameters. Returns only dashboard IDs for which the current user can see at least one widget. Dashboard identifiers are dynamic, supplied by installed modules/registry; do not hardcode an exhaustive list.

| Response path | Type | Meaning |
|---|---|---|
| `data` | `string[]` | Visible dashboard identifiers; may be empty |

Illustrative response (identifier is an example, not a confirmed registry value):

```json
{"data":["example_dashboard"]}
```

## 2. `GET /api/v1/dashboards/{dashboard}`

**Screen:** Selected dashboard. **Permission:** `dashboards.view`. **Throttle:** 60/min.

| Request field | Type | Validation |
|---|---|---|
| `dashboard` (path) | string | Regex `[a-z0-9_-]+`; must have at least one widget visible to user |
| `period`, `from`, `to` (query) | see common table | Optional period selection |

Example: `GET /api/v1/dashboards/example_dashboard?period=7d`.

| Response path | Type | Meaning |
|---|---|---|
| `data.dashboard` | string | Requested dashboard key |
| `data.period.from` | string | Inclusive `YYYY-MM-DD` |
| `data.period.to` | string | Inclusive `YYYY-MM-DD` |
| `data.period.days` | integer | Days in interval |
| `data.widgets` | `WidgetTile[]` | Widgets visible to caller only |
| `data.widgets[].key` | string | Stable widget key |
| `data.widgets[].title` | string | Localized title |
| `data.widgets[].data` | object or null | Widget-specific data, not one universal schema |
| `data.widgets[].error` | string or null | `widget_failed` on isolated widget failure |
| `data.widgets[].cached` | boolean | Whether widget result came from cache |
| `data.widgets[].ms` | integer | Server computation duration in milliseconds |

Illustrative structure (dates and widget values are placeholders):

```json
{
  "data": {
    "dashboard": "example_dashboard",
    "period": {"from": "2026-11-01", "to": "2026-11-07", "days": 7},
    "widgets": [
      {"key": "users.active", "title": "المستخدمون النشطون", "data": {"value": 20}, "error": null, "cached": false, "ms": 12}
    ]
  }
}
```

**Rules:** Unknown dashboard and dashboard with zero authorized widgets are intentionally indistinguishable (not found). Individual widget failures do **not** fail the whole HTTP response: the affected widget has `data: null`, `error: "widget_failed"`, `cached: false`. Widget payload shape depends on its owning module. UI should render each tile independently and support an error state per tile.

## 3. `GET /api/v1/admin/home`

**Screen:** Main dashboard home KPIs. **Permission:** `dashboards.view`, with extra widget-level permissions applied individually. **Throttle:** 60/min.

Example: `GET /api/v1/admin/home?period=30d`. No path/body parameters. Period query is the common table above.

| Response path | Type | Meaning |
|---|---|---|
| `data.period` | object | `{from:string,to:string,days:integer}` |
| `data.indicators` | `Indicator[]` | Only permitted and installed indicators |
| `data.hidden` | `string[]` | Indicator keys hidden by permissions |
| `data.all_empty` | boolean | True when nonempty indicator list has no nonzero values |
| `data.notice` | string or null | Localized no-data/no-access message |
| `data.restricted_text` | string or null | Financial access restriction message when applicable |
| `indicator.key` | string | Home indicator identifier |
| `indicator.widget` | string | Registered widget key |
| `indicator.scope` | `"now"` or `"period"` | Current snapshot vs period comparison |
| `indicator.scope_label` | string | Localized scope label |
| `indicator.title`, `.description` | string | Localized UI copy |
| `indicator.financial` | boolean | Financial KPI flag |
| `indicator.value` | number/string/null | Widget's value; preserve source numeric representation |
| `indicator.previous` | number/string/null | Previous period value, null for `now` |
| `indicator.unit` | string | Unit label |
| `indicator.change_pct` | number/null | Change percentage, null for `now` |
| `indicator.direction` | string/null | Widget-provided direction, null for `now` |
| `indicator.money`, `.previous_money` | mixed/null | Widget-provided money structures; inspect owning widget for exact schema |
| `indicator.details` | object/null | Additional widget fields excluding core keys |
| `indicator.link` | string/null | Admin list URL only if user has list permission |
| `indicator.empty` | boolean | Non-null widget data and numeric value equals zero |
| `indicator.error` | string/null | `widget_failed` when widget computation fails |
| `indicator.error_text` | string/null | Localized error copy |
| `indicator.empty_text` | string/null | Localized empty copy |
| `indicator.cached` | boolean | Cached widget result |

Illustrative partial response (values not captured live):

```json
{
  "data": {
    "period": {"from": "2026-11-01", "to": "2026-11-30", "days": 30},
    "indicators": [{
      "key": "open_disputes", "widget": "disputes.open", "scope": "now",
      "title": "الشكاوى المفتوحة", "description": "", "scope_label": "حاليًا",
      "financial": false, "value": 3, "previous": null, "unit": "",
      "change_pct": null, "direction": null, "money": null, "previous_money": null,
      "details": null, "link": "/api/v1/admin/disputes?filter[status]=open,under_review",
      "empty": false, "error": null, "error_text": null, "empty_text": null, "cached": false
    }],
    "hidden": [], "all_empty": false, "notice": null, "restricted_text": null
  }
}
```

**Available home indicator keys (when registered and permitted):**

| Key | Widget | Scope | List permission | Financial |
|---|---|---|---|---|
| `active_users` | `users.active` | period | `users.view` | No |
| `published_products` | `catalog.published_products` | now | `products.view` | No |
| `products_pending_review` | `catalog.pending_review` | now | `products.review` | No |
| `new_orders` | `orders.awaiting_shipment` | now | `orders.view` | No |
| `orders_in_progress` | `orders.in_progress` | now | `orders.view` | No |
| `open_disputes` | `disputes.open` | now | `disputes.view` | No |
| `pending_seller_earnings` | `wallet.pending_earnings` | now | `wallets.view` | Yes |
| `platform_commission` | `wallet.commission_earned` | period | `ledger.view` | Yes |

**Security/business behavior:** Seeing an indicator does not grant access to its drill-down list; `link` is null if the list permission is missing. Financial indicators may be hidden altogether based on widget abilities. `now` indicators never have previous-period comparisons. An absent widget registration is omitted (not added to `hidden`). `all_empty` is false when there are zero visible indicators; `notice` then communicates no permitted indicators.

## Error and implementation notes

- `401` unauthenticated, `403` lacking `dashboards.view`, `422` invalid request, `429` throttled, and not-found for inaccessible dashboard are **expected framework/business outcomes**; exact JSON error envelope and status mapping require exception-handler verification.
- Never assume `data.widgets[].data` is a single fixed DTO; each widget owns its schema.
- Do not cache dashboard tiles across users/tenants or locales: backend widget caching keys include period, tenant, optionally user, and locale.
- For live contract validation, capture each endpoint with representative permissions and a widget failure scenario.
