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

#region DashboardScenarioUi.Research [C:4] [TYPE ADR] [SEMANTICS research,ux,scenario,workspace,svelte] @BRIEF Phase 0 decisions for dashboard entry, composed scenario workspace model, parameters, baselines, drafts, and approvals. @RELATION DEPENDS_ON -> [DashboardScenarioUi.Spec] @RELATION DEPENDS_ON -> [AgentRuns.Model] @RELATION DEPENDS_ON -> [ScenarioGraph.Api] @RATIONALE 039 is a typed consumer of 036–038 contracts; duplicating lifecycle or validation in components would create conflicting truth. @REJECTED A wizard that asks users to choose Playwright, SQL, or XLSX — rejected because the compiler chooses a cross-tool business scenario.

1. Existing Frontend Fact Check

• Dashboard detail is model-first: DashboardDetailModel.svelte.ts plus thin +page.svelte.
• DashboardHeader.svelte already has an ordinary AI link carrying dashboard UIContext v1.
• /agent uses AgentChatModel.svelte.ts and Gradio stream processing.
• Shared UI components and semantic tokens are mandatory; current dashboard page has some legacy raw buttons that this feature must not copy into new components.
• Existing Gradio submit already places serialized UIContext last.

2. Entry Action

• Decision: Add a distinct Button/link labelled “Создать сценарий тестирования” in DashboardHeader.
• It routes to /agent with objectType=dashboard, id/name/env/route, contextVersion=2, and intent=build_dashboard_test_scenario.
• Existing ordinary AI chat remains available as a separate general-purpose action.
• Missing environment opens/focuses environment selection and does not start a run.
• RBAC denial is visible before or at run creation; no speculative workspace.

3. Workspace Composition

• Decision: DashboardScenarioWorkspaceModel.svelte.ts composes/references AgentRunModel and typed 037/038 API client.
• AgentRunModel owns transport/run recovery, stages, drafts, and gates.
• WorkspaceModel owns scenario response, selected step/phase, parameter drafts, baseline summaries, preview selection, and domain-derived readiness.
• Components read one workspace model; none parses chat prose or recomputes graph validity.

4. State Machine

States: unavailable, bootstrapping, analyzing, needs_parameters, scenario_ready, generating, draft_ready, waiting_approval, saved, failed, disconnected.

Transitions are driven by structured AgentRun events and authoritative ScenarioResponse/DraftPack. A sequence gap delegates recovery to AgentRunModel.

5. Parameters

• Local type/required validation gives immediate feedback.
• Apply sends only declared resolution changes with base revision hash.
• Unaffected step ids/order remain; no full analysis restart.
• Reset returns to server-provided defaults/source, not empty values blindly.
• Baseline choice is a typed parameter linked to 037 statuses.

6. Scenario Presentation

• Summary and phase/step table are primary.
• A visual dependency graph is supplementary; the table provides complete accessible semantics.
• Tool categories are visible for trust but not user-selected.
• All 19 checklist cases remain visible in coverage, including manual/unsupported/needs-context.
• Superset metric steps state “Superset chart API”; source-mart steps state “validated immutable SQL Lab evidence” with their hash and limits.

7. Draft and Approval

• File tree shows intended relative paths, validation, warnings, and unresolved markers.
• Preview/download use 036 opaque URLs and do not mutate repository.
• Save is disabled for preview_only or invalid drafts.
• Non-delegated repository actions and baseline approval reuse the 036 inline ActionApprovalGate card, including exact paths/hash/warnings and mandatory baseline reason. Delegated scenario-revision save is recorded as AgentAction instead.

8. Responsive and Accessibility

• Target: no collapse at 1366px for 15+ steps; below large breakpoint use stacked panels.
• Keyboard: entry, phase/step navigation, parameter form, file tree, preview, confirmation.
• Focus moves to first invalid parameter/finding and returns to the persistent workspace after an inline card action.
• Status uses text/icon and ARIA, never color alone.

9. Data Source Decision (amended 2026-08-07)

• Primary path (as-built): agent events only — WorkspaceModel consumes 036 agent_run_started/scenario_progress/draft_artifacts/evidence_captured through AgentChat StreamProcessor; no fetch in the model.
• Gap: frontend/src/lib/api/dashboard-testing.ts (compile/validate/resolve + verification history/detail) is not imported anywhere; without a live agent the scenario cannot be rebuilt and evidence/VLM cannot be re-run.
• Decision: add a REST fallback path (T054–T056) so preview refresh and evidence/VLM review work without an agent stream; keep the event path primary. Pipeline views (badge/history/StructureDiff) require 037 T080/T081 (deploy-hook triggers + GET read-API) before they can bind to real data (T057–T058).
• Alternative rejected: agent-only as final state for scenario construction — it makes 039 unusable after stream loss and contradicts AGUI-FR-004 (preview) independence.
• Impact: Phase 9 tasks; quickstart step 6+ remains agent-gated until REST fallback merges.

#endregion DashboardScenarioUi.Research