docs(18-02): complete plan — analytics consolidated into admin dashboard

.planning/STATE.md

@@ -4,8 +4,8 @@ milestone: v2.2
 milestone_name: — Sales Loop
 status: executing
 stopped_at: "Phase 12 re-scoped (mockup utente → editor offerte) e pianificata: 5 piani / 4 wave, planner + plan-checker pass. Pronta per /gsd-execute-phase 12"
-last_updated: "2026-06-19T10:19:00.000Z"
+last_updated: "2026-06-19T10:25:00.000Z"
-last_activity: 2026-06-19 -- Phase 18 Plan 01 complete (forecast + quote builder routes removed)
+last_activity: 2026-06-19 -- Phase 18 Plan 02 complete (analytics merged into /admin, /admin/analytics deleted)
 progress:
   total_phases: 12
   completed_phases: 3
@@ -27,11 +27,11 @@ See: .planning/PROJECT.md (updated 2026-06-13)
 ## Current Position
 
 Phase: 18 (R1) Cleanup & Consolidamento
-Plan: 01 complete (02 next)
+Plan: 02 complete (03 next)
 Status: Executing
-Last activity: 2026-06-19 -- Phase 18 Plan 01 complete (forecast + quote builder routes removed)
+Last activity: 2026-06-19 -- Phase 18 Plan 02 complete (analytics merged into /admin, /admin/analytics deleted)
 
-Progress (v2.2): [██░░░░░░░░] 20% — Phase 18 in progress (01 done)
+Progress (v2.2): [██░░░░░░░░] 20% — Phase 18 in progress (01, 02 done)
 
 ### Fasi completate (v2.1, storico)
 
@@ -80,6 +80,8 @@ Recent decisions affecting current work:
 - [Phase 11]: Phase 11 Plan 02: onConflictDoNothing() without explicit target compiles cleanly for tags table (single unique index tags_entity_name_unique) — used as written in plan, no fallback needed — Avoids unnecessary deviation; Drizzle's no-target ON CONFLICT DO NOTHING is correct given the single unique constraint from Plan 01
 - [Phase 11]: Phase 11 Plan 03: removed the plan's prescribed value-sync useEffect (and a follow-up render-time ref-read attempt) from EditableCell — both violate this project's react-hooks lint rules (set-state-in-effect, refs-during-render / React Compiler). tempValue is now only (re)initialized in startEdit()/cancel(), and the toggle display branch reads `value` directly instead of `tempValue` — Rule 1 lint fix, no behavioral change to the 8 spec'd test behaviors
 - [Phase 11]: Phase 11 Plan 04: left `createService`/`serviceSchema` in `src/app/admin/catalog/actions.ts` as unused dead code after deleting `ServiceForm.tsx` (its only consumer) — `actions.ts` was outside this plan's `files_modified` scope and `updateService` still depends on `serviceSchema`; logged to deferred-items.md for future cleanup
+- [Phase 18-02]: fmtEur unified to number version (analytics/page.tsx variant); KPI card callers using DB string values wrapped with parseFloat() — cleaner than maintaining two named variants
+- [Phase 18-02]: /admin/analytics route deleted; YearSelector now routes to /admin?year=Y — single admin entry point for statistics (CLEAN-03)
 
 ### Pending Todos
 
@@ -106,6 +108,6 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-06-19T10:16:00.000Z
+Last session: 2026-06-19T10:25:00.000Z
-Stopped at: Phase 18 Plan 01 complete — CLEAN-01 + CLEAN-02 done. Next: 18-02-PLAN.md
+Stopped at: Phase 18 Plan 02 complete — CLEAN-03 done. Next: 18-03-PLAN.md
-Resume file: .planning/phases/18-cleanup-consolidamento/18-02-PLAN.md
+Resume file: .planning/phases/18-cleanup-consolidamento/18-03-PLAN.md

.planning/phases/18-cleanup-consolidamento/18-02-SUMMARY.md

@@ -0,0 +1,113 @@
+---
+phase: 18-cleanup-consolidamento
+plan: "02"
+subsystem: ui
+tags: [nextjs, analytics, dashboard, react, tailwind]
+
+# Dependency graph
+requires:
+  - phase: analytics-queries
+    provides: getAnalyticsByYear, getMonthlyCollected, getAvailableYears, getTimeByClient, getTotalTrackedHours
+provides:
+  - Admin dashboard at /admin integrates annual statistics (MetricCard, MonthlyChart, time tracking per client)
+  - /admin/analytics route deleted — returns 404
+  - YearSelector navigates to /admin?year=Y
+affects: [18-cleanup-consolidamento, admin-ui, analytics]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Server page accepts searchParams for year filtering
+    - Analytics queries co-located with dashboard queries in same async page
+
+key-files:
+  created: []
+  modified:
+    - src/app/admin/page.tsx
+    - src/components/admin/YearSelector.tsx
+  deleted:
+    - src/app/admin/analytics/page.tsx
+
+key-decisions:
+  - "Unified fmtEur to accept number (analytics version); KPI card callers wrapped with parseFloat() for string DB values"
+  - "Two separate awaits in AdminDashboard: getDashboardStats() first, then analytics Promise.all — acceptable for clarity"
+  - "Stale .next cache (OfferSelector.tsx reference) cleared before final build — pre-existing issue, not introduced by this plan"
+
+patterns-established:
+  - "Statistics section appended after activity feed — existing dashboard structure preserved above new section"
+
+requirements-completed:
+  - CLEAN-03
+
+# Metrics
+duration: 15min
+completed: 2026-06-19
+---
+
+# Phase 18 Plan 02: Consolidate Analytics Dashboard Summary
+
+**Merged /admin/analytics statistics (MetricCard, MonthlyChart, per-client time tracking) into /admin dashboard and deleted the duplicate route**
+
+## Performance
+
+- **Duration:** ~15 min
+- **Started:** 2026-06-19T10:04:00Z
+- **Completed:** 2026-06-19T10:19:00Z
+- **Tasks:** 2
+- **Files modified:** 3 (2 modified, 1 deleted)
+
+## Accomplishments
+- AdminDashboard now shows annual statistics section below activity feed: MetricCard economic metrics, MonthlyChart, and per-client time tracking bars
+- /admin/analytics route deleted — navigating there returns 404
+- YearSelector updated to navigate to /admin?year=Y instead of /admin/analytics?year=Y
+- fmtEur unified to number-accepting version (more robust); existing KPI card string values wrapped with parseFloat()
+
+## Task Commits
+
+1. **Task 1: Integra statistiche annuali nella Dashboard** — included in `14bdbab` (feat)
+2. **Task 2: Elimina rotta /admin/analytics** — included in `14bdbab` (feat)
+
+**Plan metadata:** (docs commit below)
+
+## Files Created/Modified
+- `src/app/admin/page.tsx` — Added analytics imports, searchParams, analytics queries, MetricCard, fmtSeconds, fmtEur(number), statistics section
+- `src/components/admin/YearSelector.tsx` — Updated router.push from /admin/analytics to /admin
+- `src/app/admin/analytics/page.tsx` — Deleted
+
+## Decisions Made
+- Unified `fmtEur` to the `number` version from analytics (cleaner, no `parseFloat` internally). Updated the two KPI card callers that received string values from DB to pass `parseFloat(kpi.revenueTotale)` and `parseFloat(kpi.pagamentiInSospeso)`.
+- Used two sequential awaits (getDashboardStats first, then analytics Promise.all) rather than one large combined Promise.all — avoids mixing query concerns and follows plan guidance for acceptable two-await pattern.
+- Preserved all existing dashboard content (FollowUpWidget, KPI cards, activity feed) exactly; statistics section appended at the bottom with `mt-10`.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Cleared stale .next cache referencing deleted OfferSelector.tsx**
+- **Found during:** Build verification after Task 2
+- **Issue:** Stale `.next/tsconfig.tsbuildinfo` incremental cache listed `src/components/admin/quotes/OfferSelector.tsx` as a root file. That file had been deleted in a prior session. TypeScript errored with "File not found — root file specified for compilation." The pre-existing cache was masking this because prior builds hit cached output.
+- **Fix:** Ran `rm -rf .next` to clear the stale incremental cache, then rebuilt clean.
+- **Files modified:** .next/ (cache only — not tracked in git)
+- **Verification:** Clean build passes with TypeScript check and all routes compiled correctly.
+- **Committed in:** n/a (cache not committed)
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 3 - blocking)
+**Impact on plan:** Required to get a clean build. Pre-existing issue unrelated to this plan's scope. .next/ is gitignored so no source changes.
+
+## Issues Encountered
+- Stale `.next` incremental TypeScript cache referenced `OfferSelector.tsx` (deleted in a prior session). Cleared cache, rebuilt clean. Build passes correctly.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- /admin is the single analytics entry point — ready for 18-03 and any future admin UI work
+- No stale routes remain in the analytics path
+- Build is clean
+
+---
+*Phase: 18-cleanup-consolidamento*
+*Completed: 2026-06-19*