ss-tools/specs/031-maintenance-banner/quickstart.md

Quickstart: Maintenance Banner for Dashboards

Feature Branch: 031-maintenance-banner Created: 2026-05-21

Prerequisites

• Python 3.13+ with virtualenv (backend/.venv/)
• Node.js 18+ with npm (frontend/node_modules/)
• PostgreSQL 16 running (local or Docker)
• Superset instance configured in superset-tools environments

Backend Verification

# 1. Activate virtual environment
cd backend && source .venv/bin/activate

# 2. Apply database migrations (Alembic)
alembic upgrade head

# 3. Run maintenance-specific tests
python -m pytest tests/test_maintenance_service.py -v
python -m pytest tests/test_sql_table_extractor.py -v
python -m pytest tests/test_maintenance_api.py -v

# 4. Run full test suite
python -m pytest -v

# 5. Lint check
python -m ruff check src/services/maintenance_service.py
python -m ruff check src/api/routes/maintenance/
python -m ruff check src/models/maintenance.py
python -m ruff check src/core/superset_client/_dashboards_write.py

# 6. Full lint
python -m ruff check .

Frontend Verification

# 1. Install dependencies
cd frontend && npm install

# 2. Run component tests
npx vitest run tests/maintenance.test.ts
npx vitest run tests/maintenance-store.test.ts

# 3. Run full test suite
npm run test

# 4. Lint check
npm run lint

# 5. Build check
npm run build

Docker Integration Test

# Start full stack
docker compose up --build

# Wait for services, then:
# 1. Create maintenance event via API
curl -X POST http://localhost:8001/api/maintenance/start \
  -H "Authorization: Bearer $(cat /tmp/test_token)" \
  -H "Content-Type: application/json" \
  -d '{"tables":["test.sample"],"start_time":"2026-05-21T22:00:00Z","end_time":"2026-05-22T02:00:00Z"}'

# 2. Check task status
curl http://localhost:8001/api/tasks/<task_id> \
  -H "Authorization: Bearer $(cat /tmp/test_token)"

# 3. End maintenance
curl -X POST http://localhost:8001/api/maintenance/<maintenance_id>/end \
  -H "Authorization: Bearer $(cat /tmp/test_token)"

# 4. View settings
curl http://localhost:8001/api/maintenance/settings \
  -H "Authorization: Bearer $(cat /tmp/test_token)"

# 5. Open UI
# Frontend: http://localhost:8000/maintenance

Key Files to Verify

File	Purpose	Test File
backend/src/services/maintenance_service.py	Core logic	tests/test_maintenance_service.py
backend/src/services/sql_table_extractor.py	SQL parsing	tests/test_sql_table_extractor.py
backend/src/api/routes/maintenance/_routes.py	API endpoints	tests/test_maintenance_api.py
backend/src/core/superset_client/_dashboards_write.py	Superset API	Integrated with service tests
backend/src/models/maintenance.py	ORM models	Covered by service tests
frontend/src/routes/maintenance/+page.svelte	Management UI	tests/maintenance.test.ts
frontend/src/lib/components/DashboardMaintenanceBadge.svelte	Badge	tests/maintenance.test.ts
frontend/src/lib/stores/maintenance.svelte.js	State store	tests/maintenance-store.test.ts

Common Issues

• "Environment not found": Ensure target_environment_id in maintenance_settings matches an existing Superset environment in config.json.
• "No dashboards found": Verify table name format is schema.table (case-insensitive) and matches datasets in the target environment.
• "Chart creation failed": Check Superset API token validity and permissions (must have chart create rights).
• SQL parsing misses tables: Virtual datasets with complex CTEs or non-standard SQL dialects may need regex fallback; check sql_table_extractor.py test corpus.