ss-tools/specs/039-dashboard-scenario-ui/spec.md

#region DashboardScenarioUi.Spec [C:3] [TYPE ADR] [SEMANTICS spec,requirements,ux,scenario,dashboard-testing] @BRIEF User-facing dashboard test scenario generation experience driven by agent analysis, scenario preview, parameter collection, artifact preview, and HITL save/approval. @RELATION DEPENDS_ON -> [ADR-0001] @RELATION DEPENDS_ON -> [ADR-0005] @RELATION DEPENDS_ON -> [ADR-0006] @RELATION DEPENDS_ON -> [AgentTestStabilization.Spec] @RELATION DEPENDS_ON -> [SupersetBaselineEngine.Spec] @RELATION DEPENDS_ON -> [DashboardScenarioModel.Spec] @RATIONALE Users should approve a business-level dashboard test scenario and required parameters; low-level tool chains are visible for trust but selected by the agent and scenario validator. @REJECTED Dropdowns such as "Playwright UI tests" vs "SQL checks" vs "XLSX checks" — rejected because each dashboard requires a unique cross-tool scenario, and SQL is explicitly out of scope.

Navigation (DSA Indexer keywords)

@SEMANTICS: spec, requirements, feature, ux, agent, scenario, dashboard-testing, artifacts, baseline

Feature Branch: 039-dashboard-scenario-ui
Created: 2026-07-07 | Status: Draft
Input: "Provide the user-facing dashboard test scenario generation experience. From a dashboard page the user starts Create test scenario, the agent analyzes the dashboard, proposes a unique scenario graph, collects missing business parameters, previews generated artifacts and baseline impacts, and requires HITL confirmation before saving files or approving baselines."

User Scenarios

Story 1 — Start Scenario From Dashboard Page (P1)

Why P1: The feature must be discoverable from the dashboard the user wants to test and must carry the correct context into the agent.

Independent Test: On a dashboard page, click "Создать сценарий тестирования" and verify /agent opens with dashboard context and scenario intent.

Acceptance:

1. Given a user is viewing a dashboard When they click "Создать сценарий тестирования" Then /agent opens in Dashboard Test Scenario Agent mode with dashboard id, name, env, route, and intent visible.
2. Given environment context is missing When the user starts the flow Then the UI prompts for environment selection before scenario analysis.
3. Given the user lacks scenario-generation permission When they click the action Then a permission-denied recovery path appears and no agent run starts.

---

Story 2 — Review Proposed Unique Scenario (P1)

Why P1: The user must see the proposed business flow and tool chain before artifact generation.

Independent Test: Feed fixture scenario graph data and verify the UI renders phases, steps, tools, outputs, warnings, blockers, and coverage.

Acceptance:

1. Given the agent analyzes a dashboard When scenario graph is ready Then the UI shows goal, phases, step table, dependency graph, tool categories, expected results, coverage, warnings, and blockers.
2. Given some checklist cases are not automatable When scenario preview renders Then they appear as human checkpoints, unsupported, or needs-context with rationale.
3. Given the scenario includes Superset API metric validation When preview renders Then the UI clearly states Superset-native execution is used and direct SQL is not used.

---

Story 3 — Collect Business Parameters and Baseline Choices (P1)

Why P1: Unique dashboard tests need values such as test date, counterparty, and baseline selection before generation is meaningful.

Independent Test: Scenario preview requests parameters; user fills them; dependent step statuses update from unresolved to ready.

Acceptance:

1. Given a scenario requires parameters When preview renders Then each parameter has label, type, validation message, default/source if available, and affected steps.
2. Given an approved baseline exists for metric+filters When the user selects matching parameters Then baseline match is shown and assertion steps become ready.
3. Given no approved baseline exists When the user proceeds Then the UI offers discovery candidate flow and marks baseline approval as separate HITL action.

---

Story 4 — Preview Generated Artifacts (P2)

Why P2: Users need to inspect generated files, report templates, and warnings before saving.

Independent Test: Generate draft artifacts from a fixture scenario and verify file tree, validation status, warnings, and content preview render.

Acceptance:

1. Given draft artifacts are generated When preview opens Then the UI lists scenario file, generated runner/check files, report template, baseline candidate files, and validation status.
2. Given an artifact has unresolved markers When preview renders Then save is warning-gated and unresolved markers are visible.
3. Given user downloads draft artifacts When download completes Then repository state remains unchanged.

---

Story 5 — Save or Approve With HITL (P2)

Why P2: Saving test packs and approving baselines have durable effects and must require explicit user approval.

Independent Test: Trigger save and baseline approval actions and verify confirmation cards include target, risk, warnings, and approval reason where required.

Acceptance:

1. Given the user requests save When generated artifacts target repository paths Then confirmation shows target paths, files, warnings, and risk before saving.
2. Given baseline approval is requested When confirmation appears Then the user must provide a reason and can inspect provenance/diff.
3. Given the user denies either action When denial is submitted Then no save or approval occurs and the run records cancellation.

---

Edge Cases

• Agent analysis fails due to Superset API error → UI shows retry, switch environment, or manual-only scenario recovery.
• Scenario has unresolved blockers → generation can continue only for safe preview; executable save is blocked until resolved or converted to human checkpoint.
• Baseline is stale → UI warns and offers discovery candidate flow, not silent update.
• XLSX export is unavailable → UI shows coverage gap and alternate Superset API/UI checks.
• User navigates away during generation → run id allows returning to latest draft state from 036.

Requirements

Functional

• AGUI-FR-001: Dashboard pages MUST expose a single business-level action labeled "Создать сценарий тестирования"; UI MUST NOT present low-level artifact/tool choices as the primary entry point.
• AGUI-FR-002: /agent MUST show Dashboard Test Scenario Agent mode when opened with scenario intent from 036.
• AGUI-FR-003: The UI MUST render structured progress stages from agent metadata: context, inspect, scenario, parameters, generate, validate, save.
• AGUI-FR-004: The scenario preview MUST show business goal, phases, step list, tool category per step, dependency graph, coverage, warnings, blockers, and expected results.
• AGUI-FR-005: Parameter collection MUST support typed required parameters and update dependent scenario readiness without restarting the full flow.
• AGUI-FR-006: Baseline UI MUST show approved baseline matches, stale warnings, missing baselines, and draft candidate approval paths.
• AGUI-FR-007: Generated artifact preview MUST show file tree, file content preview, validation status, unresolved markers, and warnings before save.
• AGUI-FR-008: Saving generated files and approving baselines MUST go through HITL confirmation from 036; baseline approval requires a reason.
• AGUI-FR-009: The UI MUST explicitly communicate that metric validation uses Superset-native execution and does not execute direct SQL.
• AGUI-FR-010: All new UI state MUST follow Svelte 5 runes/model-first conventions and remain accessible by keyboard for confirmations, parameter forms, and previews.

Key Entities

• ScenarioEntryAction: Dashboard-page action that launches /agent with dashboard scenario intent.
• ScenarioWorkspaceState: Frontend state machine for context, progress, scenario preview, parameter collection, artifact preview, and confirmation states.
• ScenarioPreviewCard: UI representation of DashboardTestScenario from 038.
• ParameterPanel: Form for scenario business parameters and validation feedback.
• BaselineImpactPanel: UI section showing approved, stale, missing, and candidate baseline statuses.
• ArtifactPreviewPanel: UI file tree/content preview for draft generated artifacts.
• ScenarioConfirmationCard: HITL card for save and baseline approval actions.

Success Criteria

• SC-001: Users can launch scenario generation from a dashboard page in one click and see correct context in /agent in frontend tests.
• SC-002: Scenario preview renders at least 15-step fixture graphs with phases, tools, warnings, and blockers without layout collapse at 1366px width.
• SC-003: Parameter updates resolve dependent scenario readiness within 200ms in model tests.
• SC-004: Artifact preview blocks save when unresolved markers are present in fixture data.
• SC-005: 100% of save and baseline approval flows require confirmation; baseline approval cannot submit without reason.
• SC-006: UX copy never presents direct SQL as a validation path for this feature.

#endregion DashboardScenarioUi.Spec