docs(v2.0): finalize roadmap + requirements — phases 7-11 approved for planning

- Upgrade PROJECT.md: v2.0 Business Operations Suite (unified catalog, offers with phases, public quotes, CRM pipeline, auto-provisioning)
- Create REQUIREMENTS.md sections: CAT-U, OFFER-B, QUOTE, CRM, WIN requirements for phases 7-11
- Extend ROADMAP.md: 5-phase structure (7-11), 14-19 days total, risk/flag registry
- Archive v1.0 milestone (phases 1-6, complete)
- Switch STATE.md to v2.0, status=planning
- Create research documents: STACK.md, FEATURES_v2.0.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md

Ready for: /gsd-plan-phase 7

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -1,8 +1,10 @@
-# Roadmap: ClientHub
+# Roadmap: ClientHub v2.0 Business Operations Suite
 
 ## Overview
 
-ClientHub si costruisce dall'esterno verso l'interno: prima la dashboard che un cliente reale può aprire su mobile, poi l'area admin per creare e gestire i dati, poi il catalogo servizi e il preventivo interno. Il flusso Claude AI è v2 e dipende da CRUD stabile e catalogo completo. Ogni fase consegna una capacità end-to-end verificabile.
+**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
 
@@ -12,12 +14,20 @@ ClientHub si costruisce dall'esterno verso l'interno: prima la dashboard che un
 
 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
-- [ ] **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
+- [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
-- [ ] **Phase 6: Claude AI Onboarding (v2)** - Flusso guidato step-by-step per onboarding cliente e generazione assistita del piano/preventivo
+- [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
 
@@ -138,23 +148,94 @@ Decimal phases appear between their surrounding integers in numeric order.
 **UI hint**: yes
 **Status**: Planning complete
 
-### Phase 7: Claude AI Onboarding (v2)
-**Goal**: L'admin può usare un flusso chat guidato per onboardare un nuovo cliente e generare un piano a fasi e un preventivo assistito da Claude
-**Mode:** mvp
-**Depends on**: Phase 6
-**Requirements**: CLAUDE-01, CLAUDE-02, CLAUDE-03
+### 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. L'admin avvia il flusso Claude inserendo il brief del cliente; Claude guida step-by-step la raccolta delle informazioni necessarie
-  2. Al termine del flusso, Claude propone un piano strutturato per fasi che l'admin può accettare o modificare prima di salvarlo
-  3. Claude suggerisce un preventivo basato sul catalogo servizi; l'admin approva o modifica le voci prima della finalizzazione
-**Plans**: TBD
-**UI hint**: yes
-**Status**: Pending planning (v2 — may defer indefinitely)
+  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**: 1 (schema migration + admin page)
+**Durata**: 3–4 giorni
+**Status**: Pending planning
+**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
 
-**Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
+**v1.0 Execution (Complete):**
+Phases 1 → 2 → 3 → 4 → 5 executed in order. Phase 6 (UX Overhaul) executed May 31.
 
 | Phase | Plans | Status | Completed |
 |-------|-------|--------|-----------|
@@ -163,5 +244,20 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
 | 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 | 0/2 | Pending | - |
-| 7. Claude AI Onboarding (v2) | 0/TBD | Pending | - |
+| 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 | 1 | Pending planning | 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)