#region SupersetBaselineEngine.UxReference [C:3] [TYPE ADR] [SEMANTICS ux,reference,superset,baseline]
@BRIEF UX reference for Superset-native baseline execution and comparison results.

**Feature Branch**: `037-superset-baseline-engine`
**Created**: 2026-07-07 | **Status**: Draft

## 1. User Persona & Context

* **Who is the user?**: QA engineer or dashboard owner validating reference metric values through Superset-native execution.
* **What is their goal?**: See whether a dashboard metric under specific filters matches approved baseline values without running direct SQL.
* **Context**: Agent workspace or later scenario UI displays inspection, execution, normalization, baseline, and comparison states.

## 2. Happy Path Narrative

The user asks the agent to validate a metric for a dashboard and filter set. The system inspects the dashboard query model, executes the related Superset chart or dataset query, normalizes the result, compares it with an approved baseline, and displays a source-aware comparison. The UI explicitly states that no direct SQL was executed.

## 3. Interface Mockups

### Query Model Summary

```text
┌──────────────────── Dashboard query model ──────────────────────────────────┐
│ Dashboard: FI-0080 | env=ss-dev                                             │
│ Charts: 7 | Datasets: 3 | Native filters: 4                                 │
│ Capabilities: chart_data ✓ dataset_query ✓ xlsx_export ✓                    │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Metric Comparison

```text
┌──────────────────── Metric validation ───────────────────────────────────────┐
│ Metric: Просроченная ДЗ                                                      │
│ Chart: Итого просроченная ДЗ | Dataset: dataset_finance_debt                │
│ Filters: Дата=2026-05-29, Контрагент=АСК                                     │
│                                                                             │
│ Source                 Value          Status                                 │
│ Superset API           1 234 567.89   ✓ matches baseline                     │
│ Approved baseline      1 234 567.89   approved                               │
│                                                                             │
│ No direct SQL was executed.                                                  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Baseline Candidate

```text
┌──────────────────── Baseline candidate ─────────────────────────────────────┐
│ No approved baseline found.                                                  │
│ Candidate from Superset execution: 1 234 567.89                              │
│ Provenance: chart_id=128, dataset_id=77, filters_hash=sha256:...             │
│                                                                             │
│ [Approve baseline] [Keep draft] [Discard]                                    │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 4. Error Experience

### Scenario A: Superset API Permission Denied

* **System Response**: Comparison card shows `403 permission denied`, target chart/dataset, and required action.
* **Recovery**: User can switch environment, request access, or skip that check.

### Scenario B: Stale Baseline

* **System Response**: Baseline status becomes warning-tone with fingerprint diff category.
* **Recovery**: User can run discovery and submit a new baseline candidate for approval.

### Scenario C: Inconclusive Normalization

* **System Response**: UI shows raw value and reason normalization failed.
* **Recovery**: User can mark as manual checkpoint or adjust metric mapping in a later planning phase.

## 5. Tone & Voice

* **Style**: Precise, source-aware, explicit about no direct SQL.
* **Terminology**: Use "Superset API", "query model", "baseline", "candidate", "stale", "fingerprint".

#endregion SupersetBaselineEngine.UxReference