support_frontend/specs/002-reporting-dashboards-ui/tasks.md

description

description
Task list for 002-reporting-dashboards-ui

Tasks: Reporting and Analytics Dashboards UI

Input: Design documents from specs/002-reporting-dashboards-ui/

Organization: Tasks are grouped by user story (US1 = P1 Management, US2 = P1 Product, US3 = P2 Support, US4 = P2 AI), sharing one Foundational phase (types, format helpers, the four new components/ui primitives, the shared date-range control).

Format: [ID] [P?] [Story] Description

All file paths are relative to supporthub-web/ (repo root).

---

Phase 1: Foundational (Blocking Prerequisites)

• T001 [P] Add lib/api/types/reports.ts per data-model.md's four DTO interfaces
• T002 [P] Add lib/format/duration.ts — formatDurationSeconds, formatRate, formatCount (depends on nothing — pure functions)
• T003 [P] Add components/ui/stat-tile.tsx — label/value/optional-delta contract per dataviz marks-and-anatomy.md's "figures" section; sans semibold value, sentence-case label
• T004 [P] Add components/ui/ranked-bar-list.tsx — takes RankedBarListItem[], renders each as a label + proportional bar (single sequential hue = primary) + value, sorted as given (backend already sorts), truncating long labels with a title tooltip
• T005 [P] Add components/ui/status-distribution.tsx — takes StatusDistributionSegment[], renders a segmented bar (2px surface gaps between segments per dataviz marks-and-anatomy.md) plus a visible legend row (label + swatch + value for each segment — never color alone)
• T006 [P] Add components/ui/meter.tsx — a single-ratio track/fill pair (SLA compliance rate), fill tone success/warning/destructive by value, unfilled track a lighter step of the same tone
• T007 Export T003-T006 from components/ui/index.ts
• T008 Add features/reports/date-range-control.tsx — two date inputs + an explicit "Apply" action (plan.md: no fetch-per-keystroke), shared by Management/Product/AI
• T009 Add lib/api/reports.ts — getManagementDashboard(range), getProductDashboard(externalProductId, range), getSupportDashboard(), getAiDashboard(range), each a thin typed wrapper over apiClient per Constitution Principle IV (depends on T001)

Checkpoint: Primitives and typed client in place. Each dashboard can now be built independently.

---

Phase 2: User Story 1 - Management dashboard (Priority: P1)

• T010 [US1] Add features/reports/management-dashboard.tsx — useQuery + getQueryState, stat tiles (T003) for totals, Meter (T006) for SLA compliance, formatDurationSeconds for the two averages, DateRangeControl (T008) wired to queryKey (depends on T003, T006, T008, T009)
• T011 [US1] Unit tests: formatDurationSeconds/formatRate null -> "No data" guard, a real-value case each, in tests/unit/lib/format/duration.test.ts (depends on T002)
• T012 [US1] Component test: Management dashboard renders loading/empty/error/ready correctly against a mocked query client, in tests/unit/features/reports/management-dashboard.test.tsx (depends on T010)

Checkpoint: Quickstart Scenario 1 passes against a real backend.

---

Phase 3: User Story 2 - Product dashboard (Priority: P1)

• T013 [US2] Add a product picker reusing the existing GET /admin/products list (spec.md Assumptions) — check for an existing products-list hook/component from 012-admin-list-views' own admin/products page before adding a new one
• T014 [US2] Add features/reports/product-dashboard.tsx — RankedBarList (T004) for problem categories and top errors, stat tiles for support volume/rates, wired to T013's picker + DateRangeControl (depends on T004, T008, T009, T013)
• T015 [US2] Component test: switching products fully replaces the rendered figures, an unknown-product error state renders correctly, in tests/unit/features/reports/product-dashboard.test.tsx (depends on T014)

Checkpoint: Quickstart Scenario 2 passes against a real backend.

---

Phase 4: User Story 3 - Support dashboard (Priority: P2)

• T016 [US3] Add features/reports/support-dashboard.tsx — RankedBarList (T004) for per-agent workload, stat tiles for at-risk/breached/escalation count and performance averages — no date-range control (current-state, per data-model.md) (depends on T003, T004, T009)
• T017 [US3] Component test: at-risk and breached render as visually distinct figures, in tests/unit/features/reports/support-dashboard.test.tsx (depends on T016)

Checkpoint: Quickstart Scenario 3 passes against a real backend.

---

Phase 5: User Story 4 - AI dashboard (Priority: P2)

• T018 [US4] Add features/reports/ai-dashboard.tsx — stat tiles for the four rates, StatusDistribution (T005) for confidence bands and tool invocations, DateRangeControl (depends on T003, T005, T008, T009)
• T019 [US4] Component test: confidence/tool distributions map to the correct tone per data-model.md's fixed mapping table, in tests/unit/features/reports/ai-dashboard.test.tsx (depends on T018)

Checkpoint: Quickstart Scenario 4 passes against a real backend.

---

Phase 6: Polish & Cross-Cutting Concerns

• T020 Wire all four dashboards into app/(admin)/admin/reports/page.tsx as tabs (components/ui/tabs) alongside the existing SLA Monitor/Escalation Matrix sections (depends on T010, T014, T016, T018)
• T021 Playwright E2E: tab-switching, date-range change, and product-selection flow against a real running backend + frontend pair, in tests/e2e/reports-dashboards.spec.ts (depends on T020)
• T022 Manually verify Quickstart Scenario 5 (responsive + dark mode) directly in a browser
• T023 Update specs/002-reporting-dashboards-ui/checklists/requirements.md Notes with any implementation-time findings
• T024 npm run typecheck/npm run lint clean; full existing Vitest + Playwright suite re-run to confirm no regression in 001-agent-admin-ui's own coverage

---

Dependencies & Execution Order

• Foundational (Phase 1): No dependencies — BLOCKS all four user stories
• User Stories 2-5: Each depends only on Foundational — independent of each other
• Polish (Phase 6): Depends on all four user stories