busya
b95df37cd5
- Move agent code from backend/src/agent/ to agent/src/ss_tools/agent/ - Extract shared stdlib-only utilities to shared/src/ss_tools/shared/ - Add #region/#endregion contracts to all ~140 functions (INV_1 compliance) - Update docker files, entrypoint, build scripts for new package layout - Backend now imports ss_tools.shared._llm_health (no gradio/langchain deps) - Add specs for 036-039 feature plans
4.8 KiB
4.8 KiB
#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
┌──────────────────── 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
┌──────────────────── 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
┌──────────────────── 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