toph/kimai-plugin-heatmap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kimai-plugin-heatmap/.planning/REQUIREMENTS.md

3.1 KiB
Raw Blame History

Requirements: Kimai Heatmap Plugin v1.1

Defined: 2026-04-08 Core Value: At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious

v1.1 Requirements

Requirements for Modes & Filtering milestone. Each maps to roadmap phases.

Visualization Modes

  • VIZ-01: Mode switcher UI allows toggling between year, week, day, and combined views
  • VIZ-02: Week-mode renders day-of-week aggregation showing which weekdays are busiest
  • VIZ-03: Day-mode renders time-of-day heatmap showing when during the day work happens
  • VIZ-04: Combined mode renders 7x24 day/hour punchcard matrix
  • VIZ-05: Hours vs entry-count toggle switches color scale metric across all modes

Entity Pickers & Filtering

  • FILT-01: Customer->project->activity cascading TomSelect pickers replace plain FILT-02: Activity filtering narrows heatmap data to a specific activity
  • FILT-03: Customer filtering narrows heatmap data to all projects under a customer

Backend

  • API-01: API endpoint accepts mode param returning hour-level and day/hour aggregation data
  • API-02: API endpoint accepts activity and customer filter params with own controller endpoints

Polish

  • POL-01: Color scale legend gradient bar showing value range for current mode/metric

Testing

  • TEST-01: Vitest tests for mode switcher, each renderer, and display toggle
  • TEST-02: Vitest tests for TomSelect cascade behavior and filter integration
  • TEST-03: PHPUnit tests for hour-level and day/hour aggregation queries

Future Requirements

  • Configurable time range selector (3 months, 6 months, year, custom)
  • Persistent filter/mode state via URL params or localStorage
  • Animated transitions between visualization modes
  • Responsive widget sizing adapting to dashboard column width

Out of Scope

Feature Reason
Billable vs non-billable split Personal time tracking, not client billing
Real-time / live updates Page reload sufficient for daily-granularity data
Export/share heatmap as image No audience for personal use
Multi-user comparison Personal tracking tool
Mobile-specific layout Desktop Kimai dashboard only
Reuse Kimai's KimaiFormSelect.js Coupled to Kimai's plugin container, cannot work in widget context
Reuse Kimai's API routes for pickers Require IsGranted('API') permission, need own endpoints

Traceability

Requirement Phase Status
VIZ-01 Phase 7 Pending
VIZ-02 Phase 7 Pending
VIZ-03 Phase 9 Pending
VIZ-04 Phase 9 Pending
VIZ-05 Phase 7 Pending
FILT-01 Phase 10 Pending
FILT-02 Phase 8 Pending
FILT-03 Phase 8 Pending
API-01 Phase 8 Pending
API-02 Phase 8 Pending
POL-01 Phase 9 Pending
TEST-01 Phase 7 Pending
TEST-02 Phase 10 Pending
TEST-03 Phase 8 Pending

Coverage:

  • v1.1 requirements: 14 total
  • Mapped to phases: 14
  • Unmapped: 0

Requirements defined: 2026-04-08 Traceability updated: 2026-04-08