busya
d9669698b8
Spec: 5 user stories (P1-P3), 17 FRs, 7 SCs, 12 edge cases, RBAC matrix Plan: 7 research decisions, 15 semantic contracts (C1-C4) Data: 4 SQLAlchemy models (Banner entity enforces one-chart-per-dashboard) UX: async-only API, banner template with optional variables, admin settings UI Tasks: 64 tasks across 8 phases, 12 reused frontend components Workflow: component reuse scan mandated in speckit.plan/tasks + semantics-svelte Constitution: filled with 7 architecture principles from ADRs
3.6 KiB
3.6 KiB
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 ss-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_idinmaintenance_settingsmatches an existing Superset environment inconfig.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.pytest corpus.