ss-tools/specs/038-dashboard-scenario-model/ux_reference.md

#region DashboardScenarioModel.UxReference [C:3] [TYPE ADR] [SEMANTICS ux,reference,scenario,dashboard-testing] @BRIEF UX interaction reference — persona, flows, states, recovery paths, and edge/failure matrix for the DashboardTestScenario graph preview.

Feature Branch: 038-dashboard-scenario-model Created: 2026-07-07 | Reworked: 2026-07-31

1. User Persona & Context

• Who is the user?: QA engineer or dashboard owner reviewing the agent's proposed test scenario before execution or artifact generation.
• What is their goal?: Understand what will be tested, which tools each step uses, what parameters are needed, and what cannot be automated.
• Context: Agent workspace shows a scenario graph produced from dashboard metadata, checklist template, and baselines.

2. The "Happy Path" Narrative

The agent proposes a scenario called "Проверка фильтров, метрик и XLSX выгрузки". The user sees phases, steps, dependencies, tool categories, expected outcomes, and missing parameters. The scenario is a business flow, not a menu of technologies, so the user approves the goal and parameters while the graph records tool selection internally. Validation passes, the pack becomes save-eligible, and 036 registers the draft.

3. Interface Mockups

CLI / Operator Interaction (Agent Tools)

$ scenario compile --objective "verify filters, metric, XLSX export" --case-ids B01,C04,C05
[ ] reading query model + baseline catalog...
✅ scenario compiled: 18 steps, 0 blockers, 2 warnings
   - phases: setup → interact → observe → assert → evidence → report
   - parameters required: test_date, counterparty

Scenario Summary

┌──────────────────────── Proposed scenario ──────────────────────────────────┐
│ Goal: проверить фильтры, метрику, XLSX выгрузку и baseline                  │
│ Steps: 18 | Tools: browser, Superset API, XLSX, assertions, report          │
│ Parameters required: test_date, counterparty                                │
│ Blockers: 0 | Warnings: 2                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Scenario Graph

[open_dashboard]
      │
      ▼
[apply_filters] ───────► [execute_superset_metric]
      │                              │
      ▼                              ▼
[download_xlsx] ───────► [parse_xlsx_metric]
      │                              │
      └──────────────► [compare_to_baseline] ──► [generate_report]

Step Table

┌────┬────────────────────────────┬──────────────┬───────────────────────────┐
│ №  │ Step                       │ Tool         │ Expected result           │
├────┼────────────────────────────┼──────────────┼───────────────────────────┤
│ 1  │ Открыть дашборд            │ browser      │ dashboard_loaded          │
│ 2  │ Применить фильтры          │ browser      │ filter_state.normalized   │
│ 3  │ Выполнить chart query      │ Superset API │ metric value returned     │
│ 4  │ Скачать XLSX               │ browser      │ xlsx.file                 │
│ 5  │ Сравнить с baseline        │ assertion    │ pass/fail/inconclusive    │
└────┴────────────────────────────┴──────────────┴───────────────────────────┘

States:

• Idle/Default: No scenario selected; empty state with CTA "Compile from dashboard goal".
• Loading: Skeleton graph + "compiling…" progress; parameters panel skeleton.
• Loaded: DAG with phase lanes, step table, coverage list, parameters.
• Error/Degraded: Blockers grouped per step/case with recovery links.

4. Edge & Failure State Matrix

Semantic Requirement: Every documented failure path maps to @UX_RECOVERY/@UX_FEEDBACK in component contracts and to an error response class in openapi.yaml.

#	State Class	Trigger	Applicable?	Visual/Feedback	Recovery	Test Ownership
NET_01	Network offline	navigator.onLine == false	✅	Offline banner; disabled actions	Auto-retry on reconnect	L2
NET_02	Timeout (>30s)	AbortController timeout	✅	Toast + progress countdown	Retry (3 attempts); Cancel	L1+L2
NET_03	Retry exhaustion	3 failed retries	✅	Persistent banner + manual retry	Manual retry	L1+L2
VAL_01	Field validation (parameter)	On submit	✅	Inline error on parameter control	Re-type; clear on focus	L1+L2
VAL_02	Cross-field (resolve changes)	On submit	✅	Toast + summary banner	Fix + re-submit	L1+L2
AUTH_01	401 Unauthorized	Expired token	✅	Redirect to login; preserve intent	Login → redirect back	L1
AUTH_02	403 Forbidden	Wrong role	✅	Full-page explanation; no approval gate	Navigate to dashboard	L1+L2
NF_01	404 scenarioId	Deleted/unknown scenario	✅	Full-page not found + link to list	Navigate to scenario list	L1+L2
CONF_01	409 Stale base revision	Version mismatch on resolve	✅	Modal: "Scenario changed. Recompile?"	Recompile or snapshot diff	L1+L2
CONF_02	409 Duplicate pack registration	Same revision hash re-posted	✅	Return existing DraftPack (idempotent)	Transparent; log event	L1
422	422 Unprocessable (compile/resolve)	Invalid canonical inputs	✅	Step/field-mapped error detail	Correct input + re-submit	L1+L2
429	429 Rate Limited + Retry-After	Too many compile/validate	✅	Toast + countdown on action	Wait Retry-After; disable during countdown	L1+L2
5XX	500/502/503 Server Error	Backend failure	✅	Error section + retry	Retry button	L1+L2
STALE	Stale baseline fingerprint	Baseline updated in 037	✅	Assertion step warning badge	Run baseline discovery; mark pending	L1+L2
PARTIAL	Partial graph load	Some steps failed to compile	✅	Failed steps show placeholder	Per-step retry; "Reload all"	L1+L2
DUP_01	Duplicate submit (draft-pack)	Rapid double-click	✅	Button disabled + spinner	Normal completion	L2
DUP_02	Navigation interruption (dirty resolution)	Route change with unsaved resolution	✅	beforeunload + confirm dialog	Stay or discard	L2
LARGE	Large dataset (>100 steps)	Big scenario graph	✅	Virtualized lanes; "Showing 100 of 200"	Pagination/refinement	L2
EMPTY	Empty result (no cases applicable)	Dashboard has no mapped cases	✅	Empty state + guidance	Accept partial coverage / manual checkpoints	L1+L2
MALFORMED	Malformed VLM response	Backend/LLM bug	✅	Toast with error ID; step inconclusive	Re-run analysis; note error ID	L1
A11Y	Screen reader state announcements	State change	✅ (always)	aria-live announces compile/validate/load	Built into transitions	L2
RESP	Responsive breakpoint collapse	Viewport < 768px	✅	Lanes stack; step table is semantic fallback	Built into layout	L2

5. Error Experience

Scenario A: Missing Selector

• System Response: Step marked NEEDS_SELECTOR; executable generation for that step blocked.
• Recovery: User provides selector hint, converts to human checkpoint, or removes the step.

Scenario B: Stale Baseline

• System Response: Assertion step shows warning + stale fingerprint category.
• Recovery: User runs baseline discovery through 037 or marks the check as pending.

Scenario C: Unsupported Checklist Case

• System Response: Case listed under unsupported/manual-only with rationale.
• Recovery: User accepts partial coverage or adds manual checkpoint instructions.

Scenario D: Stale Revision on Resolve (409)

• System Response: Modal "Scenario changed since your base revision. Recompile to see the latest graph."
• Recovery: User recompiles; stale edits are rejected, never auto-merged.

6. Tone & Voice

• Style: Goal-oriented, explicit about confidence and blockers.
• Terminology: Use "scenario", "step", "tool", "parameter", "baseline ref", "human checkpoint", "preview_only", "save_eligible".

#endregion DashboardScenarioModel.UxReference