simone/clienthub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
23a9f8ad8c68cf827b573aceccc03fa69d5c8b7c
clienthub/.planning/ROADMAP.md
T
simone bdcdd26f17 docs(07): create phase plan for Unified Service Catalog 
Two-plan, two-wave migration: schema + backfill (07-01) then admin
catalog CRUD rewire (07-02), per CAT-U-01/CAT-U-02 and the
expand-contract pattern from PITFALLS_V2 Pitfall 1.
2026-06-11 06:14:05 +02:00

17 KiB
Raw Blame History

Roadmap: ClientHub v2.0 Business Operations Suite

Overview

v1.0 (Phases 1–5, Complete): ClientHub si costruisce dall'esterno verso l'interno: prima la dashboard cliente, poi l'area admin CRUD, poi catalogo servizi, progetti multi-progetto e sistema offerte.

v2.0 (Phases 7–11, Planning): Trasformazione da portale clienti a suite operativa completa. Catalogo servizi unificato → template offerte con fasi → generazione preventivi pubblici in 2 ore → CRM pipeline lead → auto-onboarding Won leads con copiat fasi e pagamenti. Obiettivo: delivery completa di proposta, accettazione, e provisioning in workflow continuo.

Phases

Phase Numbering:

  • Integer phases (1, 2, 3): Planned milestone work
  • Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

v1.0 (Completed):

  • Phase 1: Foundation & Client Dashboard - DB schema, token API, dashboard read-only per il cliente con link segreto condivisibile
  • Phase 2: Admin Area & Interactive Features - Auth admin, CRUD completo clienti/fasi/task/deliverable/pagamenti, approvazioni e commenti
  • Phase 3: Service Catalog & Quote Builder - Catalogo servizi riutilizzabile e costruttore preventivi (admin-only, cliente vede solo il totale)
  • Phase 4: Progetti — Multi-Project per Cliente - Modello dati multi-progetto per cliente; dashboard con tabs; /admin/projects; slug link; analytics €/h
  • Phase 5: Offer System - Catalogo macro/micro offerte con servizi assegnabili, assegnazione offerte a progetti, dashboard cliente con offerte attive e revenue forecast 12 mesi per l'admin
  • Phase 6: UX Overhaul - Admin sidebar + dashboard operativa con KPI e activity feed

v2.0 (Planning):

  • Phase 7: Unified Service Catalog - Migrazione service_catalog + offer_services → unica tabella services; zero data loss, audit trail per rollback
  • Phase 8: Offer Phases & Quote Templates - Tabelle offer_phases, quotes, offer_phase_services; struttura hierarchica offer (macro → micro → phase → services)
  • Phase 9: Quote Builder & Public Routes - Builder preventivi (select offer + override prezzi); /quote/[token] pagina pubblica multistep; accettazione
  • Phase 10: CRM Pipeline - Lead CRUD, attività, follow-up reminders; pipeline stages (5 step); activity log per lead
  • Phase 11: Auto-Provisioning on Win - Lead → quote accept → auto-crea client + progetto (copia fasi) + 1-4 pagamenti; launch client dashboard

Phase Details

Phase 1: Foundation & Client Dashboard

Goal: Un cliente reale può aprire il suo link segreto su mobile o desktop e vedere lo stato del suo progetto, senza login Mode: mvp Depends on: Nothing (first phase) Requirements: DASH-01, DASH-02, DASH-03, DASH-04, DASH-07, DASH-08, DASH-09, DASH-10 Success Criteria (what must be TRUE):

  1. Aprendo /c/[token] su mobile, il cliente vede nome cliente, brand, brief e fase corrente senza alcun login
  2. Le fasi del progetto sono visibili con i task annidati e il loro stato (da fare / in corso / fatto)
  3. Il cliente vede il totale preventivo accettato e lo stato dei due pagamenti (acconto 50% e saldo 50%), mai i prezzi singoli
  4. I link a documenti esterni (Google Drive, PDF) sono cliccabili dalla dashboard
  5. Il log decisioni/note è visibile nella dashboard del cliente Plans: 5 plans Plan list:
  • 01-01-PLAN.md — Walking Skeleton: Next.js bootstrap + DB connection
  • 01-02-PLAN.md — Database schema (11 tables) + Drizzle + drizzle-kit push
  • 01-03-PLAN.md — Middleware token validation + ClientView type + data fetching
  • 01-04-PLAN.md — Client dashboard UI (header, progress, phases, payments, documents, notes)
  • 01-05-PLAN.md — Seed script + DNS CNAME configuration UI hint: yes Status: ✅ Complete (Phase 1 execution required)

Phase 2: Admin Area & Interactive Features

Goal: L'admin può creare e gestire clienti, fasi, task, deliverable e pagamenti; il cliente può commentare e approvare i deliverable Mode: mvp Depends on: Phase 1 Requirements: ADMIN-01, ADMIN-02, DASH-05, DASH-06 Success Criteria (what must be TRUE):

  1. L'admin accede a /admin con credenziale sicura e vede la lista di tutti i clienti con stato sintetico e badge pagamenti
  2. L'admin può creare un nuovo cliente (con generazione automatica del link segreto), aggiungere fasi, task, documenti e aggiornare lo stato dei pagamenti
  3. Il cliente può approvare un deliverable dalla sua dashboard; l'approvazione persiste con timestamp immutabile e l'admin la vede
  4. Il cliente può lasciare un commento su un task o deliverable e l'admin vede i commenti nella workspace admin Plans: 4 plans Plan list:
  • 02-01-PLAN.md — Auth.js v4 setup + middleware admin guard (/admin/* session check)
  • 02-02-PLAN.md — Admin client list (/admin) + create client form + two payment stubs
  • 02-03-PLAN.md — Admin client workspace: tabs for phases/tasks, payments, documents, comments
  • 02-04-PLAN.md — Client interactions: deliverable approval + inline comments API + dashboard wiring UI hint: yes Status: Planned — ready for execution

Phase 3: Service Catalog & Quote Builder

Goal: L'admin può costruire un catalogo servizi riutilizzabile e comporre preventivi da esso; il cliente vede solo il totale accettato Mode: mvp Depends on: Phase 2 Requirements: CAT-01, CAT-02, ADMIN-03 Success Criteria (what must be TRUE):

  1. L'admin può aggiungere, modificare e disattivare voci nel catalogo servizi (nome, descrizione, prezzo unitario)
  2. L'admin può comporre un preventivo per un cliente selezionando voci dal catalogo; il sistema calcola il totale
  3. Dopo la finalizzazione del preventivo, accepted_total è scritto sulla riga cliente e la dashboard del cliente mostra il totale corretto; i quote_items non sono mai esposti al cliente Plans: 4 plans Plan list:
  • 03-01-PLAN.md — Schema changes (service_id nullable, custom_label) + drizzle-kit push [BLOCKING]
  • 03-02-PLAN.md — Service Catalog: /admin/catalog page + CRUD actions + ServiceTable + NavBar link
  • 03-03-PLAN.md — Quote Builder: QuoteTab + quote-actions + client detail page wiring
  • 03-04-PLAN.md — E2E verification: catalog CRUD, quote round-trip, accepted_total, security check UI hint: yes Status: Planned — ready for execution

Phase 4: Progetti — Multi-Project per Cliente

Goal: Ogni cliente può avere N progetti indipendenti; l'admin gestisce i progetti separatamente; la dashboard cliente mostra tabs per progetti multipli; analytics di profittabilità per progetto Mode: mvp Depends on: Phase 3 Requirements: PROJ-01, PROJ-02, PROJ-03, PROJ-04, PROJ-05 Success Criteria (what must be TRUE):

  1. L'admin può creare più progetti per un cliente; ogni progetto ha il proprio workspace (fasi, pagamenti, preventivo, timer) accessibile da /admin/projects/[id]
  2. La dashboard cliente mostra tabs per 2+ progetti; con 1 solo progetto mostra direttamente il workspace senza selettore
  3. La pagina /admin/projects elenca tutti i progetti con €/h calcolato e bottone timer play/stop
  4. Il link cliente supporta slug personalizzato (/c/mario-rossi) con fallback al token; slug impostabile da /admin/clients/[id]/edit
  5. Il tab Timer di ogni progetto mostra analytics profittabilità: ore lavorate, accepted_total, €/h reale vs target_hourly_rate globale Plans: 5 plans Plan list:
  • 04-00-PLAN.md — Infra: Postgres su Coolify + /c/ → /client/ rename + Dockerfile + hub.iamcavalli.net [RUN FIRST]
  • 04-01-PLAN.md — Schema migration (projects, slug, settings, FK migration) + drizzle-kit push + query layer
  • 04-02-PLAN.md — Admin projects list (/admin/projects) + ProjectRow + client detail project cards
  • 04-03-PLAN.md — Admin project workspace (/admin/projects/[id]) + TimerTab + ProfitabilityCard + /admin/impostazioni
  • 04-04-PLAN.md — Slug resolution middleware + client dashboard multi-project + slug edit UI hint: yes Status: Planning complete

Phase 5: Offer System

Goal: L'admin può gestire un catalogo di macro/micro offerte con servizi assegnabili; le offerte vengono assegnate ai progetti; il cliente vede le sue offerte attive; l'admin ha un revenue forecast 12 mesi Mode: mvp Depends on: Phase 4 Requirements: OFFER-01, OFFER-02, OFFER-03, OFFER-04, OFFER-05, OFFER-06 Success Criteria (what must be TRUE):

  1. L'admin può creare macro-offerte (es. Entry Offer) con micro-offerte figlie (es. Entry A/B/C) — nome interno, nome pubblico, promessa di trasformazione, durata in mesi
  2. L'admin può creare servizi con nome, prezzo e descrizione trasformazione; ogni servizio è assegnabile a più micro-offerte via multi-select
  3. L'admin può assegnare una micro-offerta a un progetto; la lista clienti/progetti mostra le offerte attive
  4. Il cliente vede nella dashboard le sue offerte attive (nome pubblico), il prezzo cumulativo dei servizi e il prezzo finale accettato in evidenza
  5. L'admin ha una pagina revenue forecast con breakdown mensile per i 12 mesi successivi basato su offerte attive e durate Plans: 4 plans Plan list:
  • 05-01-PLAN.md — Schema migration: 5 new offer tables (offer_macros, offer_micros, offer_services, offer_micro_services, project_offers) + drizzle-kit push [BLOCKING]
  • 05-02-PLAN.md — Offer catalog admin CRUD: /admin/offers page + offer-queries.ts + actions.ts + ServiceCheckboxList + NavBar update
  • 05-03-PLAN.md — Project offer assignment: OffersTab in /admin/projects/[id] + admin-queries extension + project-actions extension
  • 05-04-PLAN.md — Client dashboard OffersSection + /admin/forecast revenue forecast page (12 months) UI hint: yes Status: ✅ Complete (2026-05-30)

Phase 6: UX Overhaul — Sidebar + Dashboard

Goal: L'admin apre l'app e vede subito una dashboard con la situazione aziendale; la navigazione è una sidebar persistente a sinistra invece dell'header Mode: mvp Depends on: Phase 5 Requirements: UX-01, UX-02, UX-03 Success Criteria (what must be TRUE):

  1. Tutte le pagine admin usano un layout con sidebar sinistra persistente — nessun header nav
  2. /admin mostra una dashboard con: clienti attivi + revenue totale, progetti in corso, pagamenti in sospeso, attività recente
  3. La lista clienti è accessibile da /admin/clients; i link esistenti continuano a funzionare Plans: 2 plans Plan list:
  • 06-01-PLAN.md — Sidebar layout: AdminSidebar component + AppShell + move client list to /admin/clients
  • 06-02-PLAN.md — Dashboard page: KPI cards (revenue, clienti, progetti, pagamenti) + activity feed UI hint: yes Status: Planning complete

Phase 7: Unified Service Catalog

Goal: Consolidare service_catalog + offer_services in un'unica tabella services; fondazione per offer builder e quote generator Mode: migration Depends on: Phase 5 (offer_services exists) Requirements: CAT-U-01, CAT-U-02 Success Criteria (what must be TRUE):

  1. Una sola tabella services con nome, prezzo_unitario, attivo, created_at
  2. Migrazione zero data loss: campi audit (migrated_from, migrated_id) abilitano rollback sicuro
  3. /admin/catalog list/add/edit/soft-delete funzionante con nuova tabella
  4. Query vecchie servizi falliscono esplicitamente (no silent fallback) Plans: 2 plans Plan list:
  • 07-01-PLAN.md — Schema: services table (audit trail) + backfill + zero-data-loss validation
  • 07-02-PLAN.md — Admin catalog CRUD rewired to services table + e2e verification Durata: 3–4 giorni Status: Planning complete Risk: SQL deduplication logic; validate on staging before prod

Phase 8: Offer Phases & Quote Templates

Goal: Struttura hierarchica offer (macro → micro → phase → services) con drag&drop builder Mode: schema + ui Depends on: Phase 7 Requirements: OFFER-B-01, OFFER-B-02, OFFER-B-03 Success Criteria (what must be TRUE):

  1. Nuove tabelle: offer_phases, quotes, offer_phase_services
  2. /admin/offers/[id]/edit builder two-column: left servizi (ricerca), right fasi con drag&drop
  3. Drag&drop tra fasi e dentro fase (reorder); salva per singolo drop con optimistic update
  4. Versioning previene race condition da multi-tab edit (409 Conflict su version mismatch) Plans: 2 (schema + builder UI) Durata: 2–3 giorni Status: Pending planning

Phase 9: Quote Builder & Public Routes

Goal: Generazione preventivi 2-click (select offer → override prezzi → link pubblico); pagina multistep pubblico per lead Mode: UI + routes Depends on: Phase 8 Requirements: QUOTE-01, QUOTE-02, QUOTE-03, QUOTE-04, QUOTE-05 Success Criteria (what must be TRUE):

  1. /admin/quotes/new: select cliente + 1-3 offerte + override prezzi → genera /quote/[token] link pubblico
  2. Pagina pubblica /quote/[token] multistep (Step 1 overview → Step 2 tier selection → Step 3 summary + accept)
  3. Accept CTA → /api/public/quote/accept?token=X con cattura email + note
  4. Token: nanoid 21 char, unico, rate limit 3 views/min per IP
  5. Mai esporre quote_items (prezzi per servizio) via public API Plans: 3 (quote builder + public routes + security) Durata: 4–5 giorni Status: Pending planning Risk: RHF + React 19 compatibility (dev test prima del merge); PDF generation approach TBD

Phase 10: CRM Pipeline & Activity Logging

Goal: Lead CRUD, activity log, follow-up reminders, quote assignment; pipeline stages Mode: UI + CRUD Depends on: Phase 5 (project_offers) + Phase 9 (quotes) Requirements: CRM-01 through CRM-07 Success Criteria (what must be TRUE):

  1. /admin/leads list (name, email, company, status, last_contact_date, next_action)
  2. /admin/leads/[id] detail: profilo, activity log reverse-chronological, quote(s) sent, action menu
  3. Activity types: call, email, meeting, note; auto-aggiorna lead.last_contact_date
  4. Pipeline stages: Contacted → Qualified → Proposal Sent → Negotiating → Won / Lost
  5. Follow-up widget in dashboard: "Follow up today" (leads dove last_contact_date < oggi - 7 giorni)
  6. "Log activity" modal: <10 sec UX (type dropdown, date picker, notes, save)
  7. "Send Quote" button: select/create quote → update lead.status → "Proposal Sent" Plans: 3 (lead CRUD + activity logging + follow-up widget) Durata: 3–4 giorni Status: Pending planning

Phase 11: Auto-Provisioning on Win

Goal: Lead → quote accept → auto-crea client + progetto (copia fasi) + 1-4 pagamenti; lancia dashboard cliente Mode: automation + integration Depends on: Phase 9 (quotes) + Phase 10 (CRM) Requirements: WIN-01 through WIN-06 Success Criteria (what must be TRUE):

  1. "Mark as Won" button in lead detail; idempotency: call 2x = stesso client token
  2. winLead(leadId, quoteId): create client (token=nanoid) + project (name=company) + copy offer phases → project.phases
  3. 1-4 pagamenti: user sceglie split template (50/50, 3-part, 4-part, custom); registra accepted_total
  4. Generate client link + email (copy-paste MVP; email automation deferred Phase 12+)
  5. Quote accept da public /quote/[token] auto-trigga win (auto-onboarding)
  6. Copy offer phases: status="upcoming", phases modificabili dopo (template immutabile, instance editable) Plans: 2 (win action + email + BullMQ optional) Durata: 2–3 giorni Status: Pending planning Risk: Idempotency key implementation; Redis + BullMQ ops (persistent reminders optional MVP)

Phase 12+: Deferred Features (Future Milestones)

  • Phase 12: Email Automation & Polish — Send quote link via email, email reminders, lead de-duplication UI
  • Phase 13: Claude AI Onboarding (v3) — Chat-guided client onboarding, assisted quote generation, plan suggestion

Progress

v1.0 Execution (Complete): Phases 1 → 2 → 3 → 4 → 5 executed in order. Phase 6 (UX Overhaul) executed May 31.

Phase Plans Status Completed
1. Foundation & Client Dashboard 5/5 ✅ Done 2026-05-14
2. Admin Area & Interactive Features 4/4 ✅ Done 2026-05-15
3. Service Catalog & Quote Builder 4/4 ✅ Done 2026-05-19
4. Progetti — Multi-Project per Cliente 5/5 ✅ Done 2026-05-23
5. Offer System 4/4 ✅ Done 2026-05-30
6. UX Overhaul — Sidebar + Dashboard 2/2 ✅ Done 2026-05-31

v2.0 Execution (Planning): Phases 7 → 8 → 9 → 10 → 11 planned for sequential execution. Research complete (2026-06-11), requirements/roadmap finalized. Ready for phase-by-phase planning + execution.

Phase Plans Status Estimated Duration Blocking?
7. Unified Service Catalog 2 Planning complete 3–4 giorni Foundation
8. Offer Phases & Quote Templates 2 Pending planning 2–3 giorni Foundation
9. Quote Builder & Public Routes 3 Pending planning 4–5 giorni RHF compat test
10. CRM Pipeline & Activity Logging 3 Pending planning 3–4 giorni No
11. Auto-Provisioning on Win 2 Pending planning 2–3 giorni BullMQ ops (optional)
Total v2.0 MVP 11 Pending 14–19 giorni —

v2.0 Deferred (Phase 12+):

  • Phase 12: Email Automation & Polish
  • Phase 13: Claude AI Onboarding (v3)
Reference in New Issue View Git Blame Copy Permalink