# Tasks: Unified Task Reports by Type **Input**: Design documents from [`/specs/020-task-reports-design/`](specs/020-task-reports-design) **Prerequisites**: [`plan.md`](specs/020-task-reports-design/plan.md), [`spec.md`](specs/020-task-reports-design/spec.md), [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md), [`research.md`](specs/020-task-reports-design/research.md), [`data-model.md`](specs/020-task-reports-design/data-model.md), [`contracts/`](specs/020-task-reports-design/contracts) **Tests**: Include contract/integration/UI tests for independent story validation. **Organization**: Tasks are grouped by user story to enable independent implementation and testing. ## Format: `[ID] [P?] [Story] Description` --- ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Prepare report feature scaffolding and shared fixtures. - [x] T001 Create reports feature folder placeholders in `backend/src/services/reports/` and `frontend/src/lib/components/reports/` - [x] T002 [P] Add report fixture set `mixed_task_reports` and `unknown_type_partial_payload` in `backend/tests/fixtures/reports/fixtures_reports.json` - [x] T003 [P] Add frontend mock payload fixtures for report states in `frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js` - [x] T004 Register i18n key placeholders for reports UI text in `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/ru.json` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Build core report domain and API foundations used by all stories. - [x] T005 Implement canonical report schemas (`TaskReport`, `ReportQuery`, `ReportCollection`, `ReportDetailView`) in `backend/src/models/report.py` - [x] T006 [P] Implement report type profile registry and unknown fallback mapping in `backend/src/services/reports/type_profiles.py` - [x] T007 Implement report normalization service in `backend/src/services/reports/normalizer.py` - [x] T008 Implement aggregation/query service with server-side filtering + pagination in `backend/src/services/reports/report_service.py` - [x] T009 Add reports API route module with list/detail endpoints in `backend/src/api/routes/reports.py` (CRITICAL: PRE: authenticated/authorized request; POST: returns `{items,total,page,page_size,has_next,applied_filters}` and detail with diagnostics/next_actions; UX_STATE support via deterministic error payloads) - [x] T010 Wire reports router into API registration in `backend/src/api/routes/__init__.py` and `backend/src/app.py` - [x] T011 Create frontend reports API client using existing wrapper methods (no native fetch) in `frontend/src/lib/api/reports.js` (CRITICAL: PRE: valid auth context; POST: parsed payload or structured error for UI-state mapping) - [x] T011a Verify `contracts/modules.md` alignment with `spec.md` requirements and ensure all [DEF] anchors are ready. **Checkpoint**: Foundational layer complete; user stories can proceed. --- ## Phase 3: User Story 1 - View all task reports in one place (Priority: P1) 🎯 MVP **Goal**: Provide one consolidated report center that lists all task types in one view. **Independent Test**: Open reports page with mixed task fixtures and verify LLM/backup/migration/documentation reports are visible in one unified list. ### Tests for User Story 1 - [x] T012 [P] [US1] Add backend contract tests for `GET /api/reports` pagination/filter defaults in `backend/src/api/routes/__tests__/test_reports_api.py` - [x] T013 [P] [US1] Add frontend integration test for unified mixed-type rendering in `frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js` - frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js ### Implementation for User Story 1 - [x] T014 [US1] Implement reports list endpoint handler in `backend/src/api/routes/reports.py` (CRITICAL: PRE: validated query params; POST: normalized deterministic ordering and canonical minimum fields) - [x] T015 [P] [US1] Implement reports page route container in `frontend/src/routes/reports/+page.svelte` - [x] T016 [P] [US1] Implement reports list component and row/card composition in `frontend/src/lib/components/reports/ReportsList.svelte` (CRITICAL: Include @UX_STATE Idle/Loading/Error and @TEST_DATA anchors) - [x] T016a [US1] Implement grouping logic (by date/type) in `ReportsList.svelte` to satisfy FR-008. - [x] T017 [US1] Implement loading/no-data/error UI states in reports page using UX reference in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE Loading/NoData/Error preserved) - [x] T018 [US1] Add navigation entry to reports page in `frontend/src/lib/components/layout/Sidebar.svelte` - [x] T019 [US1] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) **Checkpoint**: US1 independently functional and demo-ready as MVP. --- ## Phase 4: User Story 2 - Recognize report type by distinct design (Priority: P2) **Goal**: Ensure each report type has a distinct and consistent visual design + explicit label. **Independent Test**: Render one report per type and confirm each has unique style profile and explicit task-type label. ### Tests for User Story 2 - [x] T020 [P] [US2] Add frontend visual/state tests for type profile mapping and fallback in `frontend/src/lib/components/reports/__tests__/report_type_profiles.test.js` - [x] T021 [P] [US2] Add backend normalization tests for unknown type fallback mapping in `backend/src/services/reports/__tests__/test_report_normalizer.py` - backend/src/services/reports/__tests__/test_report_normalizer.py (Coverage: 100% fallback logic) ### Implementation for User Story 2 - [x] T022 [US2] Implement frontend report type profile registry in `frontend/src/lib/components/reports/reportTypeProfiles.js` (CRITICAL: PRE: known/unknown type input; POST: one fallback profile always returned) - [x] T023 [US2] Apply type-specific badges, variants, and emphasis rules in `frontend/src/lib/components/reports/ReportCard.svelte` - [x] T024 [US2] Add explicit textual type labels and accessibility labels in `frontend/src/lib/components/reports/ReportCard.svelte` - [x] T025 [US2] Implement filtered-empty UX state with one-click reset action in `frontend/src/routes/reports/+page.svelte` (CRITICAL: UX_STATE FilteredEmpty preserved) - [x] T026 [US2] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) **Checkpoint**: US2 independently functional with distinct visual semantics. --- ## Phase 5: User Story 3 - Understand report details and outcomes quickly (Priority: P3) **Goal**: Add detailed report drill-down with clear outcome context and next actions. **Independent Test**: Open success and failed reports and confirm status, summary, timing, diagnostics, and actionable guidance are immediately visible. ### Tests for User Story 3 - [x] T027 [P] [US3] Add backend contract tests for `GET /api/reports/{report_id}` in `backend/src/api/routes/__tests__/test_reports_detail_api.py` - [x] T028 [P] [US3] Add frontend detail-panel integration test for failed report recovery guidance in `frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js` - frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js ### Implementation for User Story 3 - [x] T029 [US3] Implement report detail endpoint in `backend/src/api/routes/reports.py` (CRITICAL: PRE: auth + report_id exists; POST: normalized detail + diagnostics + next_actions) - [x] T030 [US3] Implement report detail service assembly in `backend/src/services/reports/report_service.py` (CRITICAL: POST: failed/partial include actionable context when available) - [x] T031 [P] [US3] Implement report detail panel/page component in `frontend/src/lib/components/reports/ReportDetailPanel.svelte` - [x] T032 [US3] Integrate list-to-detail interaction and context-preserving navigation in `frontend/src/routes/reports/+page.svelte` - [x] T033 [US3] Implement partial-data placeholders and failed-report action hints in `frontend/src/lib/components/reports/ReportDetailPanel.svelte` (CRITICAL: UX_RECOVERY preserved) - [x] T034 [US3] Verify implementation matches [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) (Happy Path & Errors) **Checkpoint**: US3 independently functional with complete detail and recovery guidance. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final consistency, performance, and documentation updates across all stories. - [x] T035 [P] Add API contract conformance checks against `specs/020-task-reports-design/contracts/reports-api.openapi.yaml` in `backend/src/api/routes/__tests__/test_reports_openapi_conformance.py` (CRITICAL: Verify @UX_STATE and @TEST_DATA metadata compliance) - [x] T036 [P] Add frontend performance guard test for filter responsiveness in `frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js` - [x] T036a [P] Implement virtualization or pagination optimization for large lists (>1000 items) in `ReportsList.svelte` to satisfy FR-011. - [x] T037 Update operational docs for reports usage and troubleshooting in `docs/settings.md` and `docs/design/resource_centric_layout.md` - [x] T038 Run end-to-end quickstart validation and capture results in `specs/020-task-reports-design/quickstart.md` - [x] T039 Run semantic compliance protocol (`python3 generate_semantic_map.py`) and resolve critical parsing errors from latest report - [x] T040 Remove deprecated tasks page route and redirect UI navigation entry points to reports (`frontend/src/routes/tasks/+page.svelte`, `frontend/src/lib/components/layout/TaskDrawer.svelte`, `frontend/src/components/Navbar.svelte`) - [x] T041 Fix reports list sorting/filtering for mixed offset-naive and offset-aware datetimes to prevent `GET /api/reports` 500 during active migration (`backend/src/services/reports/report_service.py`, `backend/src/api/routes/__tests__/test_reports_api.py`) - [x] T042 Add frontend submit-guard for dashboard migration/backup modal actions to prevent duplicate task creation on repeated clicks (`frontend/src/routes/dashboards/+page.svelte`) - [x] T043 Update semantic map generator to ignore few-shot examples under `.ai/shots/` (`generate_semantic_map.py`) --- ## Dependencies & Execution Order ### Phase Dependencies - Phase 1 → no dependencies. - Phase 2 depends on Phase 1 and blocks all user stories. - Phase 3 (US1) depends on Phase 2. - Phase 4 (US2) depends on Phase 2; can proceed after US1 baseline route/list exists. - Phase 5 (US3) depends on Phase 2 and uses US1 list interaction. - Phase 6 depends on completion of selected user stories. ### User Story Dependency Graph - **US1 (P1)**: first deliverable (MVP). - **US2 (P2)**: extends US1 presentation semantics. - **US3 (P3)**: extends US1 with detail drill-down and diagnostics. Graph: `US1 -> {US2, US3}` ### Parallel Opportunities - Setup fixture/i18n tasks: T002, T003, T004. - Foundational tasks: T006 and T011 parallel with model scaffolding once T005 is done. - US1 tests T012/T013 in parallel. - US2 tests T020/T021 in parallel. - US3 tests T027/T028 and UI detail task T031 in parallel after endpoint contract is stable. - Cross-cutting checks T035/T036 parallel in Phase 6. --- ## Parallel Example: User Story 1 ```bash Task: "T012 [US1] Add backend contract tests in backend/src/api/routes/__tests__/test_reports_api.py" Task: "T013 [US1] Add frontend integration test in frontend/src/lib/components/reports/__tests__/reports_page.integration.test.js" Task: "T015 [US1] Implement reports route in frontend/src/routes/reports/+page.svelte" Task: "T016 [US1] Implement list component in frontend/src/lib/components/reports/ReportsList.svelte" ``` ## Parallel Example: User Story 3 ```bash Task: "T027 [US3] Add backend detail contract tests in backend/src/api/routes/__tests__/test_reports_detail_api.py" Task: "T028 [US3] Add frontend detail integration test in frontend/src/lib/components/reports/__tests__/report_detail.integration.test.js" Task: "T030 [US3] Implement detail service assembly in backend/src/services/reports/report_service.py" Task: "T031 [US3] Implement report detail panel in frontend/src/lib/components/reports/ReportDetailPanel.svelte" ``` --- ## Implementation Strategy ### MVP First (Recommended) 1. Complete Phase 1 + Phase 2. 2. Complete Phase 3 (US1) and validate independent test. 3. Demo/deploy MVP unified report list. ### Incremental Delivery 1. Add US2 for visual differentiation after MVP list stability. 2. Add US3 for diagnostics/detail depth. 3. Finish Phase 6 polish and conformance. ### UX Preservation Rule No task in this plan intentionally degrades the UX defined in [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md). Each user story contains a mandatory UX verification task: T019, T026, T034.