docs(planning): v2.1 milestone setup + Phase 11 context/patterns
- Archive v2.0 phases (07-10) under .planning/milestones/ - v2.1 REQUIREMENTS/ROADMAP (Phases 11-17: Offer Studio + Proposal AI) - DESIGN-SYSTEM.md (database-view UI contract for Phases 11-14) - Phase 11 CONTEXT, DISCUSSION-LOG, PATTERNS Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
+1
-278
@@ -1,278 +1 @@
|
||||
# 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):**
|
||||
- [x] **Phase 1: Foundation & Client Dashboard** - DB schema, token API, dashboard read-only per il cliente con link segreto condivisibile
|
||||
- [x] **Phase 2: Admin Area & Interactive Features** - Auth admin, CRUD completo clienti/fasi/task/deliverable/pagamenti, approvazioni e commenti
|
||||
- [x] **Phase 3: Service Catalog & Quote Builder** - Catalogo servizi riutilizzabile e costruttore preventivi (admin-only, cliente vede solo il totale)
|
||||
- [x] **Phase 4: Progetti — Multi-Project per Cliente** - Modello dati multi-progetto per cliente; dashboard con tabs; /admin/projects; slug link; analytics €/h
|
||||
- [x] **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
|
||||
- [x] **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**:
|
||||
- [x] 01-01-PLAN.md — Walking Skeleton: Next.js bootstrap + DB connection
|
||||
- [x] 01-02-PLAN.md — Database schema (11 tables) + Drizzle + drizzle-kit push
|
||||
- [x] 01-03-PLAN.md — Middleware token validation + ClientView type + data fetching
|
||||
- [x] 01-04-PLAN.md — Client dashboard UI (header, progress, phases, payments, documents, notes)
|
||||
- [x] 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**:
|
||||
- [x] 02-01-PLAN.md — Auth.js v4 setup + middleware admin guard (/admin/* session check)
|
||||
- [x] 02-02-PLAN.md — Admin client list (/admin) + create client form + two payment stubs
|
||||
- [x] 02-03-PLAN.md — Admin client workspace: tabs for phases/tasks, payments, documents, comments
|
||||
- [x] 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**:
|
||||
- [x] 03-01-PLAN.md — Schema changes (service_id nullable, custom_label) + drizzle-kit push [BLOCKING]
|
||||
- [x] 03-02-PLAN.md — Service Catalog: /admin/catalog page + CRUD actions + ServiceTable + NavBar link
|
||||
- [x] 03-03-PLAN.md — Quote Builder: QuoteTab + quote-actions + client detail page wiring
|
||||
- [x] 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**:
|
||||
- [x] 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]
|
||||
- [x] 05-02-PLAN.md — Offer catalog admin CRUD: /admin/offers page + offer-queries.ts + actions.ts + ServiceCheckboxList + NavBar update
|
||||
- [x] 05-03-PLAN.md — Project offer assignment: OffersTab in /admin/projects/[id] + admin-queries extension + project-actions extension
|
||||
- [x] 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**:
|
||||
- [x] 07-01-PLAN.md — Schema: services table (audit trail) + backfill + zero-data-loss validation
|
||||
- [x] 07-02-PLAN.md — Admin catalog CRUD rewired to services table + e2e verification
|
||||
**Durata**: 3–4 giorni
|
||||
**Status**: ✅ Planning complete (execution in progress)
|
||||
**Risk**: SQL deduplication logic; validate on staging before prod
|
||||
|
||||
### Phase 8: Offer Phases & Quote Templates
|
||||
**Goal**: Struttura hierarchica offer (macro → micro → phase → services) per quote builder e auto-provisioning
|
||||
**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 può visualizzare offer micro suddivisa in fasi, ogni fase con servizi unificati assegnati
|
||||
3. Quote sono record header separati da line items (quote_items)
|
||||
4. Quote pages possono copiare struttura offer per mostrare fasi + servizi ai lead
|
||||
**Plans**: 1 plan (schema foundation for Phases 9-11)
|
||||
**Plan list**:
|
||||
- [ ] 08-01-PLAN.md — Schema: offer_phases, offer_phase_services, quotes + FKs + query layer + types
|
||||
**Durata**: 1–2 giorni
|
||||
**Status**: ✅ Planning complete
|
||||
**Notes**: Schema-only phase (no UI in Phase 8). UI builder in Phase 9.
|
||||
|
||||
### 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/3 ✅ DONE
|
||||
**Plan list**:
|
||||
- [x] 09-01-PLAN.md — Quote Validators & Service Layer (DONE 2026-06-11)
|
||||
- [x] 09-02-PLAN.md — Admin Quote Builder: /admin/quotes/new form + createQuote action + two-column preview (DONE 2026-06-11)
|
||||
- [x] 09-03-PLAN.md — Public Quote Page: /quote/[token] multistep form + acceptQuote + rate limiting (DONE 2026-06-11)
|
||||
**Durata**: 1.5 ore (esecuzione concentrata)
|
||||
**Status**: ✅ Execution complete
|
||||
**Risk**: In-memory rate limit resets on serverless cold start (OK for MVP, upgrade to Upstash Redis in Phase 10+)
|
||||
|
||||
|
||||
### 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
|
||||
**Plan list**:
|
||||
- [ ] 10-01-PLAN.md — Schema foundation (leads, activities, reminders tables + query layer)
|
||||
- [ ] 10-02-PLAN.md — Lead CRUD UI (/admin/leads list + detail page + forms)
|
||||
- [ ] 10-03-PLAN.md — Activity logging + send quote + follow-up reminders widget
|
||||
**Status**: ✅ Planning complete
|
||||
|
||||
### 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 (In Progress):**
|
||||
Phases 7 → 8 → 9 → 10 → 11 planned for sequential execution. Phase 7-9 under execution; Phase 10-11 planning complete.
|
||||
|
||||
| Phase | Plans | Status | Estimated Duration | Completed |
|
||||
|-------|-------|--------|-------------------|-----------|
|
||||
| 7. Unified Service Catalog | 2/2 | ✅ Done | 3–4 giorni | 2026-06-10 |
|
||||
| 8. Offer Phases & Quote Templates | 1/1 | ✅ Done | 1–2 giorni | 2026-06-11 |
|
||||
| 9. Quote Builder & Public Routes | 3/3 | ✅ Done | 4–5 giorni | 2026-06-11 |
|
||||
| 10. CRM Pipeline & Activity Logging | 3 | ✅ Planning complete | 3–4 giorni | — |
|
||||
| 11. Auto-Provisioning on Win | 2 | ✅ Planning complete | 2–3 giorni | — |
|
||||
| **Total v2.0 MVP** | **11** | 6/11 Complete | **13–18 giorni** | — |
|
||||
|
||||
**v2.0 Deferred (Phase 12+):**
|
||||
- Phase 12: Email Automation & Polish
|
||||
- Phase 13: Claude AI Onboarding (v3)
|
||||
PLACEHOLDER
|
||||
Reference in New Issue
Block a user