ss-tools/specs/034-task-status-center/quickstart.md

#region Quickstart [C:2] [TYPE ADR] [SEMANTICS quickstart, development, setup, task-status-center] @BRIEF Developer quickstart for the Task Status Center feature — setup, verification commands, and key file locations.

Prerequisites

• Docker + Docker Compose (for full stack)
• Python 3.13+ with venv (for backend-only development)
• Node.js 22+ (for frontend-only development)
• Git branch: 034-task-status-center

Quick Start (Docker)

# 1. Switch to feature branch
git checkout 034-task-status-center

# 2. Start full stack
docker compose up -d

# 3. Frontend at http://localhost:5173
# 4. Backend API at http://localhost:8000
# 5. WebSocket at ws://localhost:8000/ws/task-events?token=...

Development Setup (without Docker)

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn src.app:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Verification Gates

# Backend: run all tests
cd backend && source .venv/bin/activate && python -m pytest -v

# Backend: run reports-specific tests
python -m pytest tests/api/routes/test_reports.py -v
python -m pytest tests/services/reports/ -v

# Backend: lint
python -m ruff check .

# Frontend: run all tests
cd frontend && npm run test

# Frontend: run reports-specific tests
npm run test -- src/lib/components/reports/

# Frontend: lint
npm run lint

Key Files

Backend (to create/modify)

File	Change	Purpose
backend/src/api/routes/reports.py	MODIFY	Add /summary endpoint; enhance list_reports with RBAC
backend/src/services/reports/report_service.py	MODIFY	Add get_summary(), _filter_tasks_by_rbac()
backend/src/models/report.py	MODIFY	Add TaskSummary, StatusCounts, TaskTypeSummary schemas
backend/tests/api/routes/test_reports.py	MODIFY	Add summary endpoint tests
backend/tests/services/reports/test_report_service.py	MODIFY	Add RBAC filtering tests

Frontend (to create/modify)

File	Change	Purpose
frontend/src/lib/models/TaskCenterModel.svelte.ts	NEW	Screen Model — state, WebSocket, filtering, actions
frontend/src/types/reports.ts	NEW	TypeScript DTOs matching backend schemas
frontend/src/lib/api/reports.ts	MODIFY	Add getReportsSummary(), add types
frontend/src/routes/reports/+page.svelte	REWRITE	Thin render layer with summary + filters + list
frontend/src/routes/reports/+page.ts	NEW	Load function for URL query param parsing
frontend/src/lib/components/reports/SummaryPanel.svelte	NEW	Summary dashboard grid component
frontend/src/lib/components/reports/FilterBar.svelte	NEW	Filter bar component
frontend/src/lib/components/reports/TaskList.svelte	MODIFY	Add pagination, active-first sort
frontend/src/lib/components/reports/reportTypeProfiles.ts	MODIFY	Add clean_release profile
frontend/tests/lib/components/reports/SummaryPanel.test.ts	NEW	Component UX tests
frontend/tests/lib/components/reports/FilterBar.test.ts	NEW	Component UX tests
frontend/tests/lib/models/TaskCenterModel.test.ts	NEW	Model unit tests

Manual Testing Scenarios

1. Summary Dashboard (US1)

1. Create tasks of different types (migration, backup, validation) via the API/UI.
2. Open /reports — verify summary cards show correct counts.
3. Complete a running task — verify count updates via WebSocket within 2 seconds.

2. Filtering (US2)

1. Click a summary card — verify task list filters to matching type+status.
2. Use multi-select dropdowns — verify combination filtering.
3. Type in search box — verify text filtering.
4. Select time range — verify temporal filtering.

3. Task Drill-Down (US3)

1. Click a FAILED task — verify Task Drawer opens with logs.
2. Click a RUNNING task — verify live log streaming in Drawer.
3. Hover over a task row — verify tooltip with details.

4. RBAC (TSC-FR-009)

1. Login as viewer — verify only own tasks visible.
2. Login as analyst — verify own + system tasks visible.
3. Login as admin — verify all tasks visible.

5. WebSocket Recovery

1. Open /reports with WebSocket connected.
2. Kill backend (docker compose stop backend).
3. Verify: yellow reconnecting indicator → red disconnected indicator.
4. Restart backend — verify auto-reconnect within 5 seconds (SC-005).

Test Data

# Create test tasks via API:
POST /api/tasks
{
  "plugin_id": "superset-migration",
  "action": "migrate_dashboard",
  "params": {"source_env": "prod", "target_env": "staging", "dashboard_id": 42}
}

#endregion Quickstart