busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
4c601fbe06172be28f3312e63c239383ee742655
ss-tools/specs/020-task-reports-design/tasks.md
busya 286167b1d5 generate semantic clean up
2026-02-24 12:51:57 +03:00

13 KiB
Raw Blame History

Tasks: Unified Task Reports by Type

Input: Design documents from /specs/020-task-reports-design/
Prerequisites: plan.md, spec.md, ux_reference.md, research.md, data-model.md, 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.

  • T001 Create reports feature folder placeholders in backend/src/services/reports/ and frontend/src/lib/components/reports/
  • T002 [P] Add report fixture set mixed_task_reports and unknown_type_partial_payload in backend/tests/fixtures/reports/fixtures_reports.json
  • T003 [P] Add frontend mock payload fixtures for report states in frontend/src/lib/components/reports/__tests__/fixtures/reports.fixtures.js
  • 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.

  • T005 Implement canonical report schemas (TaskReport, ReportQuery, ReportCollection, ReportDetailView) in backend/src/models/report.py
  • T006 [P] Implement report type profile registry and unknown fallback mapping in backend/src/services/reports/type_profiles.py
  • T007 Implement report normalization service in backend/src/services/reports/normalizer.py
  • T008 Implement aggregation/query service with server-side filtering + pagination in backend/src/services/reports/report_service.py
  • 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)
  • T010 Wire reports router into API registration in backend/src/api/routes/__init__.py and backend/src/app.py
  • 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)
  • 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

  • T012 [P] [US1] Add backend contract tests for GET /api/reports pagination/filter defaults in backend/src/api/routes/__tests__/test_reports_api.py
  • 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

  • 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)
  • T015 [P] [US1] Implement reports page route container in frontend/src/routes/reports/+page.svelte
  • 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)
  • T016a [US1] Implement grouping logic (by date/type) in ReportsList.svelte to satisfy FR-008.
  • 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)
  • T018 [US1] Add navigation entry to reports page in frontend/src/lib/components/layout/Sidebar.svelte
  • T019 [US1] Verify implementation matches 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

  • 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
  • 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

  • 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)
  • T023 [US2] Apply type-specific badges, variants, and emphasis rules in frontend/src/lib/components/reports/ReportCard.svelte
  • T024 [US2] Add explicit textual type labels and accessibility labels in frontend/src/lib/components/reports/ReportCard.svelte
  • T025 [US2] Implement filtered-empty UX state with one-click reset action in frontend/src/routes/reports/+page.svelte (CRITICAL: UX_STATE FilteredEmpty preserved)
  • T026 [US2] Verify implementation matches 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

  • T027 [P] [US3] Add backend contract tests for GET /api/reports/{report_id} in backend/src/api/routes/__tests__/test_reports_detail_api.py
  • 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

  • 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)
  • T030 [US3] Implement report detail service assembly in backend/src/services/reports/report_service.py (CRITICAL: POST: failed/partial include actionable context when available)
  • T031 [P] [US3] Implement report detail panel/page component in frontend/src/lib/components/reports/ReportDetailPanel.svelte
  • T032 [US3] Integrate list-to-detail interaction and context-preserving navigation in frontend/src/routes/reports/+page.svelte
  • T033 [US3] Implement partial-data placeholders and failed-report action hints in frontend/src/lib/components/reports/ReportDetailPanel.svelte (CRITICAL: UX_RECOVERY preserved)
  • T034 [US3] Verify implementation matches 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.

  • 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)
  • T036 [P] Add frontend performance guard test for filter responsiveness in frontend/src/lib/components/reports/__tests__/reports_filter_performance.test.js
  • T036a [P] Implement virtualization or pagination optimization for large lists (>1000 items) in ReportsList.svelte to satisfy FR-011.
  • T037 Update operational docs for reports usage and troubleshooting in docs/settings.md and docs/design/resource_centric_layout.md
  • T038 Run end-to-end quickstart validation and capture results in specs/020-task-reports-design/quickstart.md
  • T039 Run semantic compliance protocol (python3 generate_semantic_map.py) and resolve critical parsing errors from latest report
  • 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)
  • 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)
  • 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)
  • 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

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

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.
Each user story contains a mandatory UX verification task: T019, T026, T034.