docs(05-01): complete Dashboard Metrics API plan

Tasks completed: 2/2
- DashboardService with 6 metric aggregation methods
- GET /api/dashboard endpoint and 6 integration tests

SUMMARY: .planning/phases/05-visibility-and-client-portal/05-01-SUMMARY.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/phases/05-visibility-and-client-portal/05-01-SUMMARY.md

@@ -0,0 +1,100 @@
+---
+phase: 05-visibility-and-client-portal
+plan: 01
+subsystem: api
+tags: [dashboard, metrics, prisma, aggregate, revenue, overdue, cash-flow]
+
+# Dependency graph
+requires:
+  - phase: 02-subscriber-and-billing-core
+    provides: Payment, Invoice, Subscriber models and JournalEntryService
+  - phase: 03-operational-modules
+    provides: Collection, Remittance models and collector workflow
+  - phase: 04-inventory-expenses-reports
+    provides: Expense JE patterns and FinancialReportService cash flow approach
+provides:
+  - DashboardService with 6 metric aggregation methods
+  - GET /api/dashboard endpoint returning composite dashboard metrics
+  - Integration tests verifying all metric accuracy
+affects: [05-02 (dashboard UI will consume this API), 05-05 (e2e tests)]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Dashboard metric aggregation via Prisma aggregate/groupBy"
+    - "Parallel Promise.all for independent metric queries"
+
+key-files:
+  created:
+    - src/lib/services/dashboard-service.ts
+    - src/app/api/dashboard/route.ts
+    - src/lib/__tests__/dashboard-service.test.ts
+
+key-decisions:
+  - "Revenue metrics use Payment.createdAt (not paymentDate) for today/month filtering -- createdAt is when the record was created in the system"
+  - "Cash flow uses same approach as FinancialReportService.getIncomeStatement -- POSTED JE lines on revenue (4xxx) and expense (5xxx) accounts with normal balance logic"
+  - "Collector summary uses Collection.createdAt for today filter and Remittance PENDING status for unverified count (SUBMITTED maps to PENDING enum)"
+  - "getDashboardSummary runs all 5 metric methods in parallel via Promise.all for efficiency"
+
+patterns-established:
+  - "Dashboard aggregation pattern: static class methods accepting TenantPrismaClient + tenantId, returning typed metric interfaces"
+
+# Metrics
+duration: 3min
+completed: 2026-03-05
+---
+
+# Phase 5 Plan 1: Dashboard Metrics API Summary
+
+**DashboardService aggregating revenue, overdue, subscriber status, cash flow, and collector metrics via Prisma aggregate/groupBy with GET /api/dashboard endpoint**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-05T09:20:10Z
+- **Completed:** 2026-03-05T09:23:23Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- DashboardService with 6 methods covering DASH-01 through DASH-04 plus collector summary
+- GET /api/dashboard returns all metrics in a single response, with optional date range for cash flow
+- 6 integration tests all passing first run, verifying metric accuracy against seeded data
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: DashboardService with metric aggregation** - `7fabb77` (feat)
+2. **Task 2: Dashboard API route and integration tests** - `5b1b4ee` (feat)
+
+## Files Created/Modified
+- `src/lib/services/dashboard-service.ts` - DashboardService with getRevenueMetrics, getOverdueMetrics, getSubscriberMetrics, getCashFlowSummary, getCollectorSummary, getDashboardSummary
+- `src/app/api/dashboard/route.ts` - GET endpoint with read Report permission, optional startDate/endDate params
+- `src/lib/__tests__/dashboard-service.test.ts` - 6 integration tests with comprehensive seeded data and cleanup
+
+## Decisions Made
+- Revenue metrics query Payment.createdAt for today/month ranges (system timestamp, not economic paymentDate)
+- Cash flow follows FinancialReportService pattern: POSTED JE lines on leaf revenue/expense accounts with normal balance direction
+- Collector summary uses PENDING remittance status (the Prisma enum for unverified remittances)
+- All 5 metric methods run in parallel via Promise.all in getDashboardSummary for optimal performance
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Dashboard API ready for frontend consumption in 05-02
+- All metric methods are independently callable for future widget/chart endpoints
+- No blockers for next plan
+
+---
+*Phase: 05-visibility-and-client-portal*
+*Completed: 2026-03-05*