114 lines
4.2 KiB
Markdown
114 lines
4.2 KiB
Markdown
# Requirements: Kimai Heatmap Plugin
|
|
|
|
**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 Requirements
|
|
|
|
Requirements for initial release. Each maps to roadmap phases.
|
|
|
|
### Dev Environment
|
|
|
|
- [x] **DEV-01**: Nix flake/devshell provides a running local Kimai instance
|
|
- [ ] **DEV-02**: Local Kimai has a seeded database with realistic time entry data
|
|
- [ ] **DEV-03**: Plugin is loadable in the local Kimai instance for manual testing
|
|
|
|
### Plugin Scaffold
|
|
|
|
- [ ] **PLUG-01**: Plugin is a valid Symfony bundle discoverable by Kimai
|
|
- [ ] **PLUG-02**: Plugin registers a dashboard widget visible on the Kimai dashboard
|
|
- [x] **PLUG-03**: Plugin ships a backend API endpoint returning aggregated daily time data
|
|
|
|
### Heatmap Core
|
|
|
|
- [ ] **HEAT-01**: Widget renders a d3.js calendar heatmap (weeks x days grid)
|
|
- [ ] **HEAT-02**: Cell color intensity reflects hours tracked per day (darker = more)
|
|
- [ ] **HEAT-03**: Hovering a cell shows tooltip with date, hours, and entry count
|
|
- [ ] **HEAT-04**: Day-of-week labels (Mon/Wed/Fri) on Y-axis
|
|
- [ ] **HEAT-05**: Month labels along the top showing month boundaries
|
|
- [ ] **HEAT-06**: Empty days render with a distinct "no data" color
|
|
- [x] **HEAT-07**: Clicking a day cell navigates to Kimai timesheet view filtered to that date
|
|
- [ ] **HEAT-08**: Color scheme uses Kimai's theme CSS variables
|
|
|
|
### Interactivity
|
|
|
|
- [x] **INTR-01**: Dropdown filter to view heatmap for a specific project or activity
|
|
|
|
### Polish
|
|
|
|
- [ ] **POLI-01**: Streak indicator showing current consecutive days with tracked time
|
|
- [ ] **POLI-02**: Summary stats row (total hours, average hours/day, busiest day)
|
|
- [ ] **POLI-03**: Visual distinction for weekend days (subtle border or opacity)
|
|
|
|
### Testing
|
|
|
|
- [x] **TEST-01**: PHPUnit tests for the data aggregation service (timezone-correct day grouping)
|
|
- [x] **TEST-02**: PHPUnit tests for the API endpoint (response format, filtering)
|
|
- [ ] **TEST-03**: JavaScript tests for d3 heatmap rendering (grid structure, color mapping)
|
|
- [x] **TEST-04**: JavaScript tests for tooltip and click interaction behavior
|
|
|
|
## v2 Requirements
|
|
|
|
Deferred to future release. Tracked but not in current roadmap.
|
|
|
|
### Interactivity
|
|
|
|
- **INTR-02**: Toggle between hours-per-day and entry-count display modes
|
|
- **INTR-03**: Configurable time range selector (3 months, 6 months, year, custom)
|
|
|
|
### Polish
|
|
|
|
- **POLI-04**: 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 |
|
|
| Hour-of-day matrix | Different visualization, scope creep |
|
|
| Drill-down charts in widget | Click-through to Kimai views instead |
|
|
| Multi-user comparison | Personal tracking tool |
|
|
| Goal setting / targets | Streak indicator covers motivation simply |
|
|
| Animated transitions | Complexity for near-zero utility |
|
|
| Mobile-specific layout | Desktop Kimai dashboard only |
|
|
| Custom color theme picker | Kimai theme integration is sufficient |
|
|
|
|
## Traceability
|
|
|
|
Which phases cover which requirements. Updated during roadmap creation.
|
|
|
|
| Requirement | Phase | Status |
|
|
|-------------|-------|--------|
|
|
| DEV-01 | Phase 1 | Complete |
|
|
| DEV-02 | Phase 1 | Pending |
|
|
| DEV-03 | Phase 1 | Pending |
|
|
| PLUG-01 | Phase 2 | Pending |
|
|
| PLUG-02 | Phase 2 | Pending |
|
|
| PLUG-03 | Phase 2 | Complete |
|
|
| TEST-01 | Phase 2 | Complete |
|
|
| TEST-02 | Phase 2 | Complete |
|
|
| HEAT-01 | Phase 3 | Pending |
|
|
| HEAT-02 | Phase 3 | Pending |
|
|
| HEAT-03 | Phase 3 | Pending |
|
|
| HEAT-04 | Phase 3 | Pending |
|
|
| HEAT-05 | Phase 3 | Pending |
|
|
| HEAT-06 | Phase 3 | Pending |
|
|
| HEAT-08 | Phase 3 | Pending |
|
|
| TEST-03 | Phase 3 | Pending |
|
|
| HEAT-07 | Phase 4 | Complete |
|
|
| INTR-01 | Phase 4 | Complete |
|
|
| TEST-04 | Phase 4 | Complete |
|
|
| POLI-01 | Phase 5 | Pending |
|
|
| POLI-02 | Phase 5 | Pending |
|
|
| POLI-03 | Phase 5 | Pending |
|
|
|
|
**Coverage:**
|
|
- v1 requirements: 22 total
|
|
- Mapped to phases: 22
|
|
- Unmapped: 0
|
|
|
|
---
|
|
*Requirements defined: 2026-04-08*
|
|
*Last updated: 2026-04-08 after roadmap creation*
|