busya
d874a4dca6
Add prototype/openapi/validate/resume commands, wire edge-failure matrix into UX, enforce traceability + validation gates, mandate C4/C5 belief-runtime verification. Rework 038-dashboard-scenario-model artifacts: applicability, structured edge cases, 24-class UX state matrix, interactive HTML prototype, standardized OpenAPI 3.1 (7 ops), full RTM with coverage gate, 56-task backlog, and PASS validation report.
83 lines
5.6 KiB
Markdown
83 lines
5.6 KiB
Markdown
#region DashboardScenarioModel.GraphUx [C:4] [TYPE ADR] [SEMANTICS ux,scenario,graph,coverage]
|
||
@BRIEF Presentation contract for scenario summary, DAG, steps, parameters, coverage, warnings, and blockers.
|
||
@RELATION DEPENDS_ON -> [DashboardScenarioModel.UxReference]
|
||
|
||
## Views
|
||
|
||
- Summary: objective, step count, tool categories, revision, blockers/warnings.
|
||
- Phase graph: stable topological phase lanes; keyboard-accessible step list is the semantic fallback.
|
||
- Step table: title, tool, expected kind, automation status, dependencies, checklist refs.
|
||
- Coverage: all B01–B09/C01–C07/T01–T03 classifications with rationale.
|
||
- Resolution: parameters/selectors/manual conversion only for declared unresolved targets.
|
||
|
||
## Status Semantics
|
||
|
||
ready, needs_context, needs_selector, needs_baseline, manual, unsupported, blocked are never reduced to color alone. Unsupported/manual cases remain visible in coverage.
|
||
|
||
## Edge & Failure State Matrix (per screen)
|
||
|
||
| # | State Class | Applicable? | Visual/Feedback | Recovery |
|
||
|---|-------------|:-----------:|-----------------|----------|
|
||
| NET_01 | Offline | ✅ | Offline banner; disabled actions | Auto-retry on reconnect |
|
||
| NET_02 | Timeout compile/validate | ✅ | Toast + countdown | Retry (3 attempts); Cancel |
|
||
| NET_03 | Retry exhausted | ✅ | Persistent banner + manual retry | Manual retry |
|
||
| VAL_01 | Parameter field validation | ✅ | Inline error on control | Re-type; clear on focus |
|
||
| VAL_02 | Cross-field resolve validation | ✅ | Toast + summary banner | Fix + re-submit |
|
||
| AUTH_01 | 401 | ✅ | Redirect to login; preserve intent | Login → redirect back |
|
||
| AUTH_02 | 403 | ✅ | Full-page explanation; no approval gate | Navigate to dashboard |
|
||
| NF_01 | 404 scenarioId | ✅ | Full-page not found + link to list | Navigate to scenario list |
|
||
| CONF_01 | 409 stale base revision | ✅ | Modal "Scenario changed. Recompile?" | Recompile or snapshot diff |
|
||
| CONF_02 | 409 duplicate pack | ✅ | Return existing DraftPack (idempotent) | Transparent; log event |
|
||
| 422 | Unprocessable compile/resolve | ✅ | Step/field-mapped error detail | Correct input + re-submit |
|
||
| 429 | Rate limited | ✅ | Toast + countdown | Wait Retry-After |
|
||
| 5XX | Server error | ✅ | Error section + retry | Retry button |
|
||
| STALE | Stale baseline | ✅ | Assertion step warning badge | Baseline discovery via 037; mark pending |
|
||
| PARTIAL | Partial graph load | ✅ | Failed steps show placeholder | Per-step retry; reload all |
|
||
| DUP_01 | Duplicate draft-pack submit | ✅ | Button disabled + spinner | Normal completion |
|
||
| DUP_02 | Navigation interruption | ✅ | beforeunload + confirm dialog | Stay or discard |
|
||
| LARGE | >100 steps | ✅ | Virtualized lanes | Pagination/refinement |
|
||
| EMPTY | No applicable cases | ✅ | Empty state + guidance | Accept partial coverage / manual checkpoints |
|
||
| MALFORMED | Malformed VLM response | ✅ | Toast with error ID; step inconclusive | Re-run analysis |
|
||
| A11Y | Screen reader announcements | ✅ (always) | aria-live on compile/validate/load | Built into transitions |
|
||
| RESP | Responsive collapse | ✅ (always) | Lanes stack; step table semantic fallback | Built into layout |
|
||
|
||
## Feedback Mechanisms
|
||
|
||
| Trigger | Feedback | Rationale |
|
||
|---------|----------|-----------|
|
||
| Compile submitted | Button spinner + "compiling…" progress | Long-running deterministic build; user must not double-submit |
|
||
| Validate submitted | Validation pending; then grouped findings | Findings are deterministic; grouping per step/case aids recovery |
|
||
| Resolve changes | Affected controls pending; unrelated ids unchanged | Immutable revisions; partial progress only on affected targets |
|
||
| Draft-pack generate | generate/validate progress; then manifest | Registered 036 artifacts; preview_only/save_eligible explicit |
|
||
| 409 stale revision | Modal with recompile guidance | Never silent merge; user must recompile to see latest graph |
|
||
| VLM finding disposition | Audit event + finding status update | Typed, auditable human decision |
|
||
|
||
## Recovery Paths
|
||
|
||
| From | Action | To |
|
||
|------|--------|-----|
|
||
| NEEDS_SELECTOR step | Provide selector hint / convert to checkpoint / remove step | ready / manual / removed |
|
||
| NEEDS_BASELINE assertion | Run 037 baseline discovery / mark pending | ready / warning-gated |
|
||
| preview_only pack | Resolve blockers / parameters | save_eligible |
|
||
| 409 stale revision | Recompile from latest | new revision |
|
||
| 422 resolve | Correct invalid fields | resolved revision |
|
||
|
||
## Reactivity
|
||
|
||
- Model atoms → component props → DOM (039 renders; 038 supplies DTOs).
|
||
- Compile/validate/resolve results are deterministic server responses; UI holds no derived truth.
|
||
|
||
## UX Tests (minimum: happy, empty, error, edge)
|
||
|
||
| @UX_TEST | Given | When | Then |
|
||
|----------|-------|------|------|
|
||
| Fifteen-plus steps render | Valid 18-step scenario | Load preview | No dependency information loss; lanes/table consistent |
|
||
| Cycle not rendered as executable | Cycle fixture | Load preview | Cycle path shown; no executable graph |
|
||
| Technical cases never show SQL | T01–T03 dashboard | Load preview | Superset API or human checkpoint shown |
|
||
| Parameter resolution updates affected steps only | Resolve one parameter | Apply change | Unrelated step ids/order unchanged; new revision hash |
|
||
| Preview-only pack explains blockers | Invalid/unresolved graph | Generate pack | All save blockers listed; preview_only state explicit |
|
||
| 409 stale revision recovery | Stale base revision | Resolve | Modal with recompile guidance; no silent merge |
|
||
| VLM finding disposition | Unresolved finding | Confirm/dismiss/inconclusive | Typed status; audit event; graph unchanged |
|
||
|
||
#endregion DashboardScenarioModel.GraphUx
|