From 0116af5d40523b02caf5da4649c8d5b8e9827813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Wed, 8 Apr 2026 12:50:48 +0200 Subject: [PATCH] docs(02-01): complete HeatmapService plan summary Co-Authored-By: Claude Opus 4.6 --- .planning/REQUIREMENTS.md | 12 ++--- .planning/STATE.md | 34 +++++++------- .planning/phase-2/02-01-SUMMARY.md | 71 ++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 21 deletions(-) create mode 100644 .planning/phase-2/02-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 4e52336..89e4853 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -17,7 +17,7 @@ Requirements for initial release. Each maps to roadmap phases. - [ ] **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 +- [x] **PLUG-03**: Plugin ships a backend API endpoint returning aggregated daily time data ### Heatmap Core @@ -42,8 +42,8 @@ Requirements for initial release. Each maps to roadmap phases. ### 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) +- [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) - [ ] **TEST-04**: JavaScript tests for tooltip and click interaction behavior @@ -86,9 +86,9 @@ Which phases cover which requirements. Updated during roadmap creation. | DEV-03 | Phase 1 | Pending | | PLUG-01 | Phase 2 | Pending | | PLUG-02 | Phase 2 | Pending | -| PLUG-03 | Phase 2 | Pending | -| TEST-01 | Phase 2 | Pending | -| TEST-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 | diff --git a/.planning/STATE.md b/.planning/STATE.md index fa32094..7c42cdb 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,8 +3,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: executing -stopped_at: Completed 01-01-PLAN.md -last_updated: "2026-04-08T09:13:33.896Z" +stopped_at: Completed 02-01-PLAN +last_updated: "2026-04-08T10:50:36.592Z" last_activity: 2026-04-08 progress: total_phases: 5 @@ -21,30 +21,30 @@ progress: See: .planning/PROJECT.md (updated 2026-04-08) **Core value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious -**Current focus:** Phase 1: Dev Environment +**Current focus:** Phase 2: Plugin Scaffold + Data Layer ## Current Position -Phase: 1 of 5 (Dev Environment) +Phase: 2 of 5 (Plugin Scaffold + Data Layer) Plan: 1 of 2 in current phase Status: Ready to execute Last activity: 2026-04-08 -Progress: [░░░░░░░░░░] 0% +Progress: [██░░░░░░░░] 20% ## Performance Metrics **Velocity:** -- Total plans completed: 0 -- Average duration: - -- Total execution time: 0 hours +- Total plans completed: 2 +- Average duration: ~15min +- Total execution time: ~30min **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| - | - | - | - | +| Phase 1 | 2 | ~30min | ~15min | **Recent Trend:** @@ -52,7 +52,7 @@ Progress: [░░░░░░░░░░] 0% - Trend: - *Updated after each plan completion* -| Phase 01 P01 | 2min | 2 tasks | 5 files | +| Phase 2 P02-01 | 5min | 5 tasks | 8 files | ## Accumulated Context @@ -65,8 +65,13 @@ Recent decisions affecting current work: - [Roadmap]: Nix dev environment is Phase 1 prerequisite; everything else depends on it - [Research]: Use Vitest + jsdom for JS tests (d3 v7 is ESM-only, Jest struggles) - [Research]: Ship prebuilt JS in Resources/public/, do not hook into Kimai's Webpack Encore -- [Phase 01]: x86_64-linux only for Nix flake (NixOS-only project) -- [Phase 01]: MariaDB 11.4.9 on port 3307, Kimai on port 8010 +- [Phase 1]: x86_64-linux only for Nix flake (NixOS-only project) +- [Phase 1]: MariaDB 11.4.9 on port 3307, Kimai on port 8010 +- [Phase 1]: Plugin needs DI extension + services.yaml to register as tagged PluginInterface service +- [Phase 1]: Kimai's autoloader needs exclude-from-classmap for recursive plugin symlink +- [Phase 1]: PHP memory_limit=1G required for Kimai cache warmup +- [Phase 1]: process-compose API server disabled (-p 0) to avoid port 8080 conflict +- [Phase 2]: Removed final from HeatmapService to allow PHPUnit mocking ### Pending Todos @@ -75,10 +80,9 @@ None yet. ### Blockers/Concerns - [Research]: Kimai widget API (WidgetInterface, DI tags) needs verification against target Kimai version -- [Research]: Nix + PHP dev environment can consume days if not timeboxed -- 1 day timebox recommended ## Session Continuity -Last session: 2026-04-08T09:13:33.894Z -Stopped at: Completed 01-01-PLAN.md +Last session: 2026-04-08T10:50:36.590Z +Stopped at: Completed 02-01-PLAN Resume file: None diff --git a/.planning/phase-2/02-01-SUMMARY.md b/.planning/phase-2/02-01-SUMMARY.md new file mode 100644 index 0000000..dc605e8 --- /dev/null +++ b/.planning/phase-2/02-01-SUMMARY.md @@ -0,0 +1,71 @@ +--- +phase: 2 +plan: "02-01" +subsystem: backend +tags: [service, controller, tests, api] +dependency_graph: + requires: [phase-1] + provides: [heatmap-service, heatmap-api, phpunit-config] + affects: [services.yaml] +tech_stack: + added: [phpunit] + patterns: [mocked-repository, unit-test] +key_files: + created: + - Service/HeatmapService.php + - Controller/HeatmapController.php + - Resources/config/routes.yaml + - Tests/phpunit.xml + - Tests/bootstrap.php + - Tests/Service/HeatmapServiceTest.php + - Tests/Controller/HeatmapControllerTest.php + modified: + - Resources/config/services.yaml +decisions: + - Removed final from HeatmapService to allow PHPUnit mocking in controller tests +metrics: + duration: ~5min + completed: "2026-04-08" +--- + +# Phase 2 Plan 01: HeatmapService, PHPUnit Tests, and API Endpoint Summary + +Data aggregation service querying t.date for timezone-correct daily grouping, JSON API controller at /heatmap/data, PHPUnit tests with mocked TimesheetRepository. + +## What Was Built + +1. **services.yaml** -- Added _defaults with autowire/autoconfigure, resource scanning for Controller/Service/Widget/EventSubscriber directories +2. **HeatmapService** -- Queries TimesheetRepository grouping by DATE(t.date), sums duration, counts entries, filters by user/date range/optional project, excludes running timesheets +3. **PHPUnit infrastructure** -- phpunit.xml config, bootstrap.php with dual autoloader path resolution (plugin root vs symlinked) +4. **HeatmapController** -- GET /heatmap/data returning JSON with days array and range object, IsGranted auth +5. **Controller test** -- Mocked service and user via container/token storage + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed bootstrap autoloader paths** +- **Found during:** Task 3 verification +- **Issue:** Plan's bootstrap paths used `../../dev/kimai/` from Tests/ dir, resolving one level too high +- **Fix:** Changed to `/../dev/kimai/` (single parent from Tests/) +- **Files modified:** Tests/bootstrap.php +- **Commit:** 7060cfc + +**2. [Rule 3 - Blocking] Removed final from HeatmapService** +- **Found during:** Task 5 verification +- **Issue:** PHPUnit cannot mock final classes; controller test failed with ClassIsFinalException +- **Fix:** Changed `final class HeatmapService` to `class HeatmapService` +- **Files modified:** Service/HeatmapService.php +- **Commit:** 7060cfc + +## Verification + +``` +PHPUnit 10.5.63 -- OK (4 tests, 15 assertions) +``` + +## Commits + +| Hash | Message | +|------|---------| +| 7060cfc | feat: add HeatmapService, API controller, and PHPUnit tests |