# UI: Dashboard Specification

> Reference for step-03-specify.md — section 3d dashboard KPI and chart capture.

## 3d. Dashboard Specification (if section = dashboard)

When a "dashboard" section is selected, capture structured KPI and chart data **in addition** to the standard ASCII mockup.

1. **Ask client for KPIs** via AskUserQuestion (batch):
   - KPI name and metric description
   - Visualization type: `kpi-card`, `bar`, `line`, `pie`, `area`, `donut`, `stacked-bar`
   - Data source entity
   - Format: `number`, `currency`, `percent`, `duration`
   - Thresholds (warning/critical) if applicable

2. **Ask client for filters:**
   - Date range filter? Default period? (day/week/month/quarter/year)
   - Entity-based filters? (status, category, etc.)

3. **Ask client for refresh mode:**
   - Static (load on page open)
   - Polling (periodic refresh)
   - SignalR (real-time push)

4. **Store in specification.dashboards[]:**

```json
{
  "code": "{module}-dashboard",
  "title": "{Module} Dashboard",
  "description": "Vue d'ensemble des métriques {module}",
  "linkedUCs": ["UC-XXX"],
  "refreshMode": "static",
  "defaultPeriod": "month",
  "kpis": [
    {
      "code": "total-items",
      "label": "Total Items",
      "metric": "COUNT(entity)",
      "format": "number",
      "visualization": "kpi-card",
      "dataSource": "Entity",
      "thresholds": { "warning": 100, "critical": 50 }
    },
    {
      "code": "items-by-status",
      "label": "Items by Status",
      "metric": "COUNT(entity) GROUP BY status",
      "format": "number",
      "visualization": "pie",
      "dataSource": "Entity",
      "dimensions": ["status"]
    }
  ],
  "filters": [
    { "field": "dateRange", "type": "dateRange", "label": "Période" },
    { "field": "status", "type": "multiselect", "label": "Statut" }
  ],
  "permissionsRequired": ["{app}.{module}.read"]
}
```

5. **ALSO generate the standard ASCII mockup** for the dashboard with KPI cards + chart placeholders:

```
╔═══════════════════════════════════════════════════════════════╗
║  {Module} > Dashboard              Période: [Ce mois ▾]     ║
╠═══════════════════════════════════════════════════════════════╣
║  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    ║
║  │ KPI #1   │  │ KPI #2   │  │ KPI #3   │  │ KPI #4   │    ║
║  │  1,234   │  │  567     │  │  89.2%   │  │  12,400  │    ║
║  │  ↑ +12%  │  │  ↓ -3%  │  │  → 0%   │  │  ↑ +5%   │    ║
║  └──────────┘  └──────────┘  └──────────┘  └──────────┘    ║
╠═══════════════════════════════════════════════════════════════╣
║  ┌─────────────────────────┐  ┌─────────────────────────┐    ║
║  │  [Bar Chart]            │  │  [Pie Chart]            │    ║
║  │  Items by Month         │  │  Items by Status        │    ║
║  │  ████                   │  │      ████████           │    ║
║  │  ████ ████              │  │   ███      ███          │    ║
║  │  ████ ████ ████         │  │  ██   42%    ██         │    ║
║  └─────────────────────────┘  └─────────────────────────┘    ║
╚═══════════════════════════════════════════════════════════════╝
```

Store the mockup in specification.wireframes[] AS WELL (for visual reference).
