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>
This commit is contained in:
kevin-asprec
@@ -5,23 +5,23 @@
|
||||
See: .planning/PROJECT.md (updated 2026-03-04)
|
||||
|
||||
**Core value:** ISP owners can see exactly where their money is — who owes what, what's been collected, what's been spent, and what the business actually looks like financially — in real time.
|
||||
**Current focus:** Phase 4 complete (all 5 plans). Ready for Phase 5.
|
||||
**Current focus:** Phase 5 in progress — Visibility and Client Portal.
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 4 of 5 (Inventory, Expenses, and Financial Reports)
|
||||
Plan: 5 of 5 in phase 4 (23/23 total complete)
|
||||
Status: Phase 4 complete. All plans done: 04-01, 04-02, 04-03, 04-04, 04-05.
|
||||
Last activity: 2026-03-05 — Completed 04-04-PLAN.md (Expense Reports and Audit Trail — 9 tests, category/vendor reports, ACCT-08 audit trail)
|
||||
Phase: 5 of 5 (Visibility and Client Portal)
|
||||
Plan: 1 of 5 in phase 5 (24/28 total complete)
|
||||
Status: In progress. 05-01 complete (Dashboard Metrics API).
|
||||
Last activity: 2026-03-05 — Completed 05-01-PLAN.md (Dashboard Metrics API — 6 tests, revenue/overdue/subscriber/cashflow/collector metrics)
|
||||
|
||||
Progress: [███████████████████████] 100% (23/23 plans across all phases)
|
||||
Progress: [████████████████████████░░░░] 86% (24/28 plans across all phases)
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 16
|
||||
- Average duration: 10.9 min
|
||||
- Total execution time: 175 min
|
||||
- Total plans completed: 17
|
||||
- Average duration: 10.3 min
|
||||
- Total execution time: 178 min
|
||||
|
||||
**By Phase:**
|
||||
|
||||
@@ -31,10 +31,11 @@ Progress: [███████████████████████
|
||||
| 02-subscriber-and-billing-core | 5/5 complete | 57 min | 11.4 min |
|
||||
| 03-operational-modules | 5/5 complete | ~65 min | ~13 min |
|
||||
| 04-inventory-expenses-reports | 5/5 complete | 71 min | 14.2 min |
|
||||
| 05-visibility-and-client-portal | 1/5 complete | 3 min | 3 min |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 10 plans: 03-01 (15 min), 03-02 (11 min), 03-04 (6 min), 03-05 (9 min), 04-01 (16 min), 04-03 (17 min), 04-05 (10 min), 04-02 (8 min), 04-04 (20 min)
|
||||
- Trend: stable — 04-04 all 9 tests passed first run, clean execution
|
||||
- Last 10 plans: 03-02 (11 min), 03-04 (6 min), 03-05 (9 min), 04-01 (16 min), 04-03 (17 min), 04-05 (10 min), 04-02 (8 min), 04-04 (20 min), 05-01 (3 min)
|
||||
- Trend: 05-01 fastest plan yet — pure service + API + tests, no schema changes
|
||||
|
||||
*Updated after each plan completion*
|
||||
|
||||
@@ -142,6 +143,10 @@ Recent decisions affecting current work:
|
||||
- [04-04]: Expense aggregation done in JS after findMany -- same pattern as outstanding reports, collector balances (acceptable for ISP scale)
|
||||
- [04-04]: AuditTrailService queries JEs by referenceType+referenceId -- works for all sources (Invoice, Payment, Expense, Collection, etc.)
|
||||
- [04-04]: Expense report cleanup order: expenses -> vendors -> expenseCategories (custom) -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> subscribers -> servicePlans -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant
|
||||
- [05-01]: Dashboard revenue metrics use Payment.createdAt (not paymentDate) for today/month filtering
|
||||
- [05-01]: Cash flow uses same approach as FinancialReportService — POSTED JE lines on revenue (4xxx) and expense (5xxx) accounts with normal balance logic
|
||||
- [05-01]: getDashboardSummary runs all 5 metric methods in parallel via Promise.all
|
||||
- [05-01]: Dashboard cleanup order: expenses -> vendors -> expenseCategories (custom) -> collectionAllocations -> collections -> remittances -> paymentAllocations -> payments -> invoiceLines -> invoices -> journalEntryLines -> null reversesEntryId -> journalEntries -> zoneAssignments -> subscribers -> zones -> servicePlans -> accountingPeriods -> accounts -> ticketCategories -> expenseCategories (system) -> users -> tenant
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -159,6 +164,6 @@ None.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-03-05T06:55:00Z
|
||||
Stopped at: Completed 04-04-PLAN.md (Expense Reports and Audit Trail — 9 tests). Phase 4 fully complete.
|
||||
Last session: 2026-03-05T09:23:00Z
|
||||
Stopped at: Completed 05-01-PLAN.md (Dashboard Metrics API — 6 tests, all passing).
|
||||
Resume file: None
|
||||
|
||||
@@ -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*
|
||||
Reference in New Issue
Block a user