From f2ab815f46d08a2785ee27adbcb62e4e62fd0eb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christopher=20M=C3=BChl?= <toki@toph.so>
Date: Thu, 9 Apr 2026 21:46:12 +0200
Subject: [PATCH] docs(08-02): complete controller endpoints plan

---
 .../08-02-SUMMARY.md                          | 112 ++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 .planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md

diff --git a/.planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md b/.planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md
new file mode 100644
index 0000000..f3fda7f
--- /dev/null
+++ b/.planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md
@@ -0,0 +1,112 @@
+---
+phase: 08-backend-aggregation-filtering
+plan: 02
+subsystem: api
+tags: [symfony, controller, php, typescript, rest-api]
+
+requires:
+  - phase: 08-backend-aggregation-filtering-01
+    provides: "HeatmapService with hourly, day/hour aggregation and entity list methods"
+provides:
+  - "Controller mode dispatch (daily/hourly/dayhour) with filter params"
+  - "Cascade endpoints: /customers, /projects, /activities"
+  - "TypeScript types for HourlyData and DayHourData response shapes"
+affects: [09-renderer-modes, 10-entity-pickers]
+
+tech-stack:
+  added: []
+  patterns: ["match() dispatch for API mode selection", "cascade entity endpoints for picker data"]
+
+key-files:
+  created: []
+  modified:
+    - Controller/HeatmapController.php
+    - Service/HeatmapService.php
+    - Tests/Controller/HeatmapControllerTest.php
+    - assets/src/types.ts
+
+key-decisions:
+  - "Extended getUserProjects with optional customerId param for cascade filtering"
+
+patterns-established:
+  - "Mode dispatch via match() on query string param with safe default"
+  - "Filter params use getInt() with ?: null for type-safe nullable integers"
+
+requirements-completed: [API-01, API-02, FILT-02, FILT-03, TEST-03]
+
+duration: 4min
+completed: 2026-04-09
+---
+
+# Phase 8 Plan 02: Controller Mode Dispatch & Cascade Endpoints Summary
+
+**Controller mode dispatch (daily/hourly/dayhour), filter param passthrough, and cascade entity endpoints for customer/project/activity pickers**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-04-09T19:41:25Z
+- **Completed:** 2026-04-09T19:45:20Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Extended data() action with mode dispatch (daily/hourly/dayhour) via match() expression
+- Added customer, activity filter params alongside existing project filter
+- Added cascade endpoints: /customers, /projects (with customer filter), /activities (with project filter)
+- Added TypeScript types HourEntry, DayHourEntry, HourlyData, DayHourData matching API contracts
+- 9 controller tests all passing (21 total suite)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Extend HeatmapController with mode dispatch and cascade endpoints**
+   - `86e7d5f` (test: failing tests for mode dispatch and cascade endpoints)
+   - `f8b22da` (feat: mode dispatch, filter params, and cascade endpoints)
+2. **Task 2: Add TypeScript types for new API response shapes** - `0691567` (feat)
+
+## Files Created/Modified
+- `Controller/HeatmapController.php` - Mode dispatch, filter params, 3 new cascade actions
+- `Service/HeatmapService.php` - Extended getUserProjects with optional customerId param
+- `Tests/Controller/HeatmapControllerTest.php` - 8 new tests for mode dispatch and cascade endpoints
+- `assets/src/types.ts` - HourEntry, DayHourEntry, HourlyData, DayHourData interfaces
+
+## Decisions Made
+- Extended getUserProjects(User, ?int customerId) rather than adding a separate method -- keeps cascade filtering consistent with how getUserActivities already accepts projectId
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Extended getUserProjects with optional customerId parameter**
+- **Found during:** Task 1 (controller projects() endpoint)
+- **Issue:** Plan's projects() action passes customerId to getUserProjects, but service method only accepted User
+- **Fix:** Added optional `?int $customerId = null` param with customer join/filter when non-null
+- **Files modified:** Service/HeatmapService.php
+- **Verification:** Full test suite passes (21 tests, 56 assertions)
+- **Committed in:** f8b22da (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Necessary service extension to support cascade project filtering. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All mode dispatch and cascade endpoints ready for Phase 9 renderer consumption
+- TypeScript types ready for Phase 9 frontend integration
+- Phase 10 entity pickers can consume /customers, /projects, /activities endpoints
+
+## Self-Check: PASSED
+
+All 4 files verified present. All 3 commits verified in history. All acceptance criteria spot checks passed.
+
+---
+*Phase: 08-backend-aggregation-filtering*
+*Completed: 2026-04-09*