# 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.