195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
# 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/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`
|
|
|
|
### 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/tests/test_report_normalizer.py`
|
|
|
|
### 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/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`
|
|
|
|
### 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/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`
|
|
|
|
---
|
|
|
|
## 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/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/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. |