84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# 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 <select>
|
|
- [ ] **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*
|