# Requirements Checklist: Maintenance Banner for Dashboards

**Purpose**: Validate specification completeness against the feature requirements template and project standards.
**Created**: 2026-05-21
**Feature**: [spec.md](../spec.md)

## Functional Scope

- [x] CHK001 All user-facing actions have defined acceptance scenarios (US1–US5 have Given/When/Then)
- [x] CHK002 Feature scope is bounded — clear what IS and IS NOT included (no dashboard content modification beyond adding/removing markdown chart)
- [x] CHK003 Both API and UI interaction paths are defined
- [x] CHK004 External system (ETL tool) integration contract is specified (API request/response shapes)
- [x] CHK005 Both dataset types (table-based and virtual/SQL) are addressed in requirements

## Data Model & Persistence

- [x] CHK006 All new entities are listed in Key Entities (MaintenanceEvent, MaintenanceDashboardState, MaintenanceSettings)
- [x] CHK007 Entity relationships are clear (MaintenanceEvent → MaintenanceDashboardState via maintenance_event_id; Dashboard → Dataset → Table via Superset)
- [x] CHK008 Status lifecycle is defined (active → completed/failed, active → removed/removal_failed)
- [x] CHK009 Data retention / cleanup requirements are implicit (history is kept, no auto-deletion)

## Interaction & Usability

- [x] CHK010 Happy path is documented with narrative and API examples
- [x] CHK011 Error scenarios have recovery paths (5 scenarios: table not found, missing dashboard, timeout, conflict, permissions)
- [x] CHK012 UX states are enumerated (`@UX_STATE`: idle, loading, action_in_progress, error, empty)
- [x] CHK013 UX feedback mechanisms are defined (toast notifications, badges, tooltips)
- [x] CHK014 Tone & voice consistent with project terminology

## Non-Functional Qualities

- [x] CHK015 Performance targets are set (SC-001: <30s find, SC-002: <60s banner, SC-003: <30s remove)
- [x] CHK016 Error handling strategy is defined (partial success with 207, idempotent operations)
- [x] CHK017 RBAC enforcement is specified (FR-014: operator/admin roles)
- [x] CHK018 Logging and audit trail requirements are implicit (maintenance event history in local DB)

## Integration & Dependencies

- [x] CHK019 Superset API dependency is acknowledged (markdown chart creation, dashboard import/export)
- [x] CHK020 Existing codebase patterns are respected (SupersetClient, RBAC patterns from ADR-0005)
- [x] CHK021 Frontend architecture constraints are noted (Svelte 5 runes per ADR-0006)

## Edge Cases & Constraints

- [x] CHK022 Concurrent maintenance events on one dashboard handled
- [x] CHK023 Empty dashboards (no datasets) handled
- [x] CHK024 Table in multiple datasets within one dashboard handled
- [x] CHK025 Network failures with Superset handled
- [x] CHK026 Large table lists (100+) considered
- [x] CHK027 Dashboard deletion race condition considered
- [x] CHK028 Complex SQL parsing for virtual datasets considered
- [x] CHK029 Excluded vs forced dashboard priority resolved
- [x] CHK030 Timezone handling specified

## Completion Signals

- [x] CHK031 All FR items are testable (each FR has at least one acceptance scenario or success criterion)
- [x] CHK032 Success criteria are measurable (SC-001 to SC-007 all have quantifiable metrics)
- [x] CHK033 No `[NEEDS CLARIFICATION]` markers remain in spec
- [x] CHK034 Feature branch matches convention (031-maintenance-banner)

## Notes

- SQL parsing accuracy at ≥95% (SC-004) will require a dedicated test corpus of real Superset virtual dataset queries.
- The markdown chart placement at "position (0,0)" in Superset depends on Superset's dashboard layout API capabilities — the plan phase should research the exact mechanism (export-import cycle vs direct chart creation + position patching).
- Timezone formatting in the banner text should be configurable (UTC by default, but "MSK" shown in examples). This is an implementation detail for the plan phase.
