таски готовы

specs/020-task-reports-design/quickstart.md

@@ -0,0 +1,84 @@
+# 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`.