simone
6e97a53b73
- getDashboardStats() in dashboard-queries.ts - RSC dashboard at /admin with 4 KPI cards + activity feed - npm run build passes
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
---
|
|
plan: "06-02"
|
|
phase: 6
|
|
subsystem: admin-dashboard
|
|
tags: [dashboard, kpi, activity-feed, rsc, drizzle]
|
|
dependency_graph:
|
|
requires: [06-01]
|
|
provides: [getDashboardStats, /admin dashboard page]
|
|
affects: [src/app/admin/page.tsx, src/lib/dashboard-queries.ts]
|
|
tech_stack:
|
|
added: []
|
|
patterns: [RSC async server component, Promise.all parallel DB fetch, Intl.NumberFormat/DateTimeFormat]
|
|
key_files:
|
|
created:
|
|
- src/lib/dashboard-queries.ts
|
|
modified:
|
|
- src/app/admin/page.tsx
|
|
decisions:
|
|
- "isNotNull() used instead of not(isNull()) — isNotNull is the correct Drizzle-orm helper for nullable timestamp WHERE clauses"
|
|
- "Promise.all for the 4 activity feed queries — parallel fetch reduces latency"
|
|
- "Type guard filters (.filter with type predicate) used for nullable approved_at and ended_at before mapping — avoids non-null assertion operator"
|
|
- "revalidate=0 on dashboard page — always fresh data, no stale cache"
|
|
metrics:
|
|
duration: "~10 minutes"
|
|
completed: "2026-05-31"
|
|
tasks_completed: 3
|
|
tasks_total: 3
|
|
---
|
|
|
|
# Phase 6 Plan 02: Dashboard page — KPI cards + activity feed at /admin Summary
|
|
|
|
Real admin dashboard at /admin with 4 KPI cards (clienti attivi, revenue totale, progetti in corso, pagamenti in sospeso) and an activity feed showing the last 10 events across clients, projects, deliverables, and time entries. Page is a pure RSC — no client component directive. Data layer extracted into `src/lib/dashboard-queries.ts`.
|
|
|
|
## Tasks Completed
|
|
|
|
| Task | Name | Commit | Files |
|
|
|------|------|--------|-------|
|
|
| 1 | Create dashboard-queries.ts with getDashboardStats() | a304328 | src/lib/dashboard-queries.ts |
|
|
| 2 | Build dashboard page at /admin | 40162e0 | src/app/admin/page.tsx |
|
|
| 3 | Verify build and TypeScript | 40162e0 | — |
|
|
|
|
## What Was Built
|
|
|
|
**dashboard-queries.ts** — server-only query module with:
|
|
- 4 KPI queries: `count()` of non-archived clients, `sum()` of non-archived projects.accepted_total, `sum()` of payments with status `da_saldare` + `inviata`, `count()` of non-archived projects
|
|
- Activity feed: 4 parallel queries via `Promise.all` fetching the 5 most recent events from clients, projects, deliverables (approved), time_entries (stopped). Merged and sorted by timestamp descending, sliced to 10.
|
|
- `isNotNull()` used for nullable timestamp columns (approved_at, ended_at) — correct Drizzle-orm helper
|
|
|
|
**admin/page.tsx** — RSC async server component with:
|
|
- `KpiCard` sub-component (inline RSC, no "use client")
|
|
- 4-column grid KPI cards with Lucide icons (Users, Euro, FolderOpen, Clock)
|
|
- Activity feed list with emoji icons per event type
|
|
- `Intl.DateTimeFormat` for Italian locale timestamps, `Intl.NumberFormat` for EUR currency formatting
|
|
- `revalidate = 0` for always-fresh data
|
|
|
|
## Deviations from Plan
|
|
|
|
**1. [Rule 1 - Bug] Replaced `not(isNull())` with `isNotNull()`**
|
|
- **Found during:** Task 1 implementation
|
|
- **Issue:** Plan code used `not(isNull(deliverables.approved_at))` but `not` is not an ergonomic Drizzle-orm filter helper for this pattern — `isNotNull()` is the correct dedicated helper
|
|
- **Fix:** Used `isNotNull()` from drizzle-orm directly, matching the pattern used in `admin-queries.ts`
|
|
- **Files modified:** src/lib/dashboard-queries.ts
|
|
|
|
**2. [Rule 2 - Correctness] Added type guard filters for nullable fields**
|
|
- **Found during:** Task 1 implementation
|
|
- **Issue:** Mapping `approved_at` and `ended_at` after the WHERE clause still required TypeScript type narrowing (Drizzle returns nullable types regardless of WHERE)
|
|
- **Fix:** Added `.filter((d): d is ... & { approved_at: Date }` type predicates before mapping — avoids non-null assertions and is type-safe
|
|
- **Files modified:** src/lib/dashboard-queries.ts
|
|
|
|
**3. [Rule 2 - Performance] Parallel fetch for activity queries**
|
|
- **Found during:** Task 1 implementation
|
|
- **Issue:** Plan code had 4 sequential activity queries; `Promise.all` reduces latency
|
|
- **Fix:** Wrapped all 4 activity queries in `Promise.all([...])`
|
|
- **Files modified:** src/lib/dashboard-queries.ts
|
|
|
|
## Verification
|
|
|
|
- `npx tsc --noEmit`: PASSED — no errors
|
|
- `npm run build`: PASSED — 22 routes compiled, /admin shows as dynamic (ƒ) server-rendered route
|
|
- /admin no longer redirects — renders real Dashboard page
|
|
- Page is RSC — no "use client" directive in page.tsx
|
|
- KpiCard and fmt/fmtEur helpers are plain functions (not client components)
|
|
|
|
## Known Stubs
|
|
|
|
None — all KPI values and activity items come from live DB queries. If the database is empty, cards show 0/€0,00 and activity feed shows "Nessuna attività recente" — intentional, not a stub.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- [x] src/lib/dashboard-queries.ts — created (a304328)
|
|
- [x] src/app/admin/page.tsx — updated, no redirect, full dashboard RSC (40162e0)
|
|
- [x] npx tsc --noEmit passes
|
|
- [x] npm run build passes — /admin is ƒ (dynamic)
|
|
- [x] No "use client" in page.tsx
|