docs: define v1 requirements
This commit is contained in:
parent
19d03c2baa
commit
096e187d1f
1 changed files with 114 additions and 0 deletions
114
.planning/REQUIREMENTS.md
Normal file
114
.planning/REQUIREMENTS.md
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
# 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
|
||||||
|
|
||||||
|
- [ ] **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
|
||||||
|
- [ ] **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
|
||||||
|
- [ ] **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
|
||||||
|
|
||||||
|
- [ ] **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
|
||||||
|
|
||||||
|
- [ ] **TEST-01**: PHPUnit tests for the data aggregation service (timezone-correct day grouping)
|
||||||
|
- [ ] **TEST-02**: PHPUnit tests for the API endpoint (response format, filtering)
|
||||||
|
- [ ] **TEST-03**: JavaScript tests for d3 heatmap rendering (grid structure, color mapping)
|
||||||
|
- [ ] **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 | TBD | Pending |
|
||||||
|
| DEV-02 | TBD | Pending |
|
||||||
|
| DEV-03 | TBD | Pending |
|
||||||
|
| PLUG-01 | TBD | Pending |
|
||||||
|
| PLUG-02 | TBD | Pending |
|
||||||
|
| PLUG-03 | TBD | Pending |
|
||||||
|
| HEAT-01 | TBD | Pending |
|
||||||
|
| HEAT-02 | TBD | Pending |
|
||||||
|
| HEAT-03 | TBD | Pending |
|
||||||
|
| HEAT-04 | TBD | Pending |
|
||||||
|
| HEAT-05 | TBD | Pending |
|
||||||
|
| HEAT-06 | TBD | Pending |
|
||||||
|
| HEAT-07 | TBD | Pending |
|
||||||
|
| HEAT-08 | TBD | Pending |
|
||||||
|
| INTR-01 | TBD | Pending |
|
||||||
|
| POLI-01 | TBD | Pending |
|
||||||
|
| POLI-02 | TBD | Pending |
|
||||||
|
| POLI-03 | TBD | Pending |
|
||||||
|
| TEST-01 | TBD | Pending |
|
||||||
|
| TEST-02 | TBD | Pending |
|
||||||
|
| TEST-03 | TBD | Pending |
|
||||||
|
| TEST-04 | TBD | Pending |
|
||||||
|
|
||||||
|
**Coverage:**
|
||||||
|
- v1 requirements: 22 total
|
||||||
|
- Mapped to phases: 0
|
||||||
|
- Unmapped: 22 ⚠️
|
||||||
|
|
||||||
|
---
|
||||||
|
*Requirements defined: 2026-04-08*
|
||||||
|
*Last updated: 2026-04-08 after initial definition*
|
||||||
Loading…
Add table
Reference in a new issue