# Quickstart: Unified Task Reports by Type

## Purpose

Implement and validate the unified reports feature defined in:
- Spec: [`spec.md`](specs/020-task-reports-design/spec.md)
- UX reference: [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md)
- Plan: [`plan.md`](specs/020-task-reports-design/plan.md)
- Data model: [`data-model.md`](specs/020-task-reports-design/data-model.md)
- Contracts: [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md), [`contracts/reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml)

## 1) Backend implementation flow

1. Add report API route module under existing API routes structure.
2. Implement report aggregation/normalization service using canonical `TaskReport` envelope + type-specific details.
3. Enforce server-side filtering and pagination according to OpenAPI contract.
4. Ensure unknown task types map to fallback `unknown` and partial payloads are still returned.
5. Keep read-only/non-blocking behavior for report endpoints.

## 2) Frontend implementation flow

1. Add unified reports page route and connect to existing API wrapper layer (no native fetch).
2. Implement list view with type-specific visual profiles and explicit text labels.
3. Implement filter toolbar (type/status/time/search) and empty/error/loading states.
4. Add detail panel/page for selected report with diagnostics and next actions.
5. Ensure all user-facing strings are i18n-ready.

## 3) UX conformance checks (must pass)

- Loading state shows skeleton placeholders.
- No-data state appears when there are no reports at all.
- Filtered-empty state appears for strict filter combinations and supports one-click clear.
- Failed report shows clear reason + suggested next actions.
- Unknown type is visible with neutral fallback style.

## 4) Contract checks (must pass)

- API payloads match [`reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml).
- Canonical minimum fields always present in list and detail.
- Status and task_type values conform to enumerations.
- Pagination metadata (`total`, `has_next`, `applied_filters`) is consistent.

## 5) Suggested validation commands

Backend tests (use project venv convention):
```bash
cd backend && .venv/bin/python3 -m pytest
```

Frontend tests:
```bash
cd frontend && npm test
```

Optional targeted API contract checks:
```bash
cd backend && .venv/bin/python3 -m pytest tests -k reports
```

## 6) Validation execution results (implementation run)

### Backend targeted reports tests

Command:
```bash
cd backend && .venv/bin/python3 -m pytest tests/test_reports_api.py tests/test_report_normalizer.py tests/test_reports_detail_api.py tests/test_reports_openapi_conformance.py -q
```

Result:
- `tests/test_report_normalizer.py`: created and collected in run context.
- API-level tests requiring app import failed at collection in current environment due DB connection:
  - `psycopg2.OperationalError` / `sqlalchemy.exc.OperationalError`
  - connection refused to `localhost:5432`

Interpretation:
- Reports code/tests are in place, but full backend validation in this environment is blocked by unavailable database service.
- Re-run same command in environment with reachable DB to complete final verification.

## 7) Done criteria for planning handoff

- All planning artifacts exist and are internally consistent.
- UX states in [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) are mapped in module contracts.
- OpenAPI contract is stable for backend/frontend parallel implementation.
- Ready to decompose into executable work items via `/speckit.tasks`.