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
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|