clienthub/.planning/ROADMAP.md

# Roadmap: ClientHub — v2.1 (chiuso) → v2.2 Sales Loop

## Overview

**v2.0 (Phases 1–10, Complete)**: ClientHub è una suite operativa completa — catalogo servizi unificato, offerte con fasi, preventivo pubblico (`/quote/[token]`), CRM pipeline lead con activity log. Archiviato in `.planning/milestones/v2.0-ROADMAP.md`.

**v2.1 (Phases 11–17) — PARZIALE / CHIUSO dal reset 2026-06-19**: ha consegnato Offer Studio (Phase 11 catalogo database-view + Phase 12 offer editor tier A/B/C) e CRM Attio-style (Phase 14). Le fasi residue **13/15/16/17 sono congelate/abbandonate/ri-scopate** (vedi sotto).

**v2.2 (Phases 18–22, Sales Loop) — ATTIVO**: dopo che l'utente ha articolato il flusso commerciale reale (piano `.claude/plans/glittery-sprouting-pudding.md`), il focus diventa il **loop di vendita**: cleanup dei doppioni → pipeline CRM Kanban (Pipedrive-style) → knowledge base transcript per cliente → agente AI che genera il preventivo → pagina pubblica `/preventivo/[slug]` + email. Numerazione GSD continua: v2.2 parte da Phase 18. Le fasi R1–R5 mappano su Phase 18–22.

## Phases

- [x] **Phase 11: Catalog Database-View UX & Legacy Consolidation** - Catalogo `services` come tabella con inline edit, tag multi-select, quick-add, ricerca istantanea; consolidamento `service_catalog`/`offer_services` → `services`
- [x] **Phase 12: Offer Editor — Tier A/B/C, Tag & Prezzo Pubblico** - Editor offerte completo: lista filtrabile + 3 tier (A/B/C) via matrice checkbox sui servizi `services`, totale live per tier, prezzo pubblico manuale, tag multi-dimensione, promessa di trasformazione (completed 2026-06-18)
- [~] **Phase 13: Workspace — Servizi Attivi** - ❌ CONGELATA (reset 2026-06-19): tocca il post-vendita lasciato invariato; ripescabile in futuro
- [x] **Phase 14: CRM Attio-style & Fix** - Redesign `/admin/leads` stile Attio/Pipedrive (inline edit + tag), fix FollowUpWidget IT / LeadForm types / SendQuoteModal rami irraggiungibili (completed 2026-06-14)
- [~] **Phase 15: Dashboard Revenue Stats** - ❌ ABBANDONATA (reset 2026-06-19): mockup mai arrivato; analytics confluisce nella dashboard via CLEAN-03
- [~] **Phase 16: Proposal AI — Data Foundations & Auto-Provisioning** - ❌ RI-SCOPATA in v2.2; Stripe Payment Link + auto-provisioning → backlog post-R5
- [~] **Phase 17: Proposal AI — Builder, Pagina Pubblica & Email** - ❌ RI-SCOPATA in v2.2 (Phase 21/22 con transcript + flusso chiaro)
- [ ] **Phase 18 (R1): Cleanup & Consolidamento** - Rimuovi Forecast + quote builder manuale; fondi `/admin/analytics` nella dashboard; archivia fasi residue v2.1
- [ ] **Phase 19 (R2): Pipeline CRM Kanban** - Board lead stile Pipedrive con colonne per stage + drag-drop; vinto/perso come cambio-colonna manuale
- [ ] **Phase 20 (R3): Knowledge Base Cliente (transcript)** - Schema additivo + UI per incollare transcript datati multipli per lead/cliente
- [ ] **Phase 21 (R4): Agente AI — generazione preventivo** - Builder: admin sceglie cliente+offerta, l'AI (Claude) legge transcript + offerta e genera bozza preventivo; admin revisiona
- [ ] **Phase 22 (R5): Pagina pubblica `/preventivo/[slug]` + email** - Pagina pubblica HTML/CSS, accept/reject → CRM, invio link via email (Resend)

## Phase Details

> **Reset 2026-06-19**: i dettagli delle fasi 13/15/16/17 sotto sono conservati per storico ma quelle fasi sono **cancellate/congelate** (vedi checklist Phases sopra e Progress sotto). Le fasi attive sono **18–22 (R1–R5)**, in fondo a questa sezione.

### Phase 11: Catalog Database-View UX & Legacy Consolidation
**Goal**: L'utente vede ed edita il catalogo servizi come una tabella stile database (Notion-like) — inline editing, tag multi-select, quick-add, ricerca istantanea — su un'unica tabella `services` consolidata senza perdita di dati legacy
**Mode:** migration + ui
**Depends on**: Phase 10 (CRM Pipeline, ultima fase v2.0)
**Requirements**: OFFER-07, OFFER-08, OFFER-09, OFFER-10, OFFER-13
**Success Criteria** (what must be TRUE):
  1. L'utente edita inline ogni cella del catalogo `services` (click sulla cella → edit → invio salva) senza apertura di modali
  2. L'utente assegna tag multi-select a servizi/offerte, creando nuovi tag al volo senza uscire dalla tabella
  3. L'utente aggiunge un nuovo servizio tramite riga vuota in fondo alla tabella (nome + invio)
  4. L'utente filtra/cerca servizi e offerte istantaneamente (ricerca client-side, nessun reload)
  5. I dati legacy di `service_catalog` e `offer_services` sono consolidati in `services` senza perdita (migration additiva, audit trail `migrated_from`/`migrated_id`)
**Plans**: 4 plans
**Plan list**:
  - [x] 11-01-PLAN.md
  - [x] 11-02-PLAN.md
  - [x] 11-03-PLAN.md
  - [x] 11-04-PLAN.md
**UI hint**: yes
**Status**: ✅ Complete (2026-06-13) — migration 0007 (`services.fase`) applicata in prod, commit pushato su `gitea/main`

### Phase 12: Offer Editor — Tier A/B/C, Tag & Prezzo Pubblico
**Goal**: L'admin crea e modifica offerte complete da una lista filtrabile: editor con 3 tier (A/B/C) composti via matrice di checkbox dai servizi del catalogo unificato `services`, totale servizi live per tier, prezzo pubblico manuale per tier, tag multi-dimensione (categoria/ticket/tipo/obiettivo) e promessa di trasformazione strutturata. I servizi disponibili nella matrice sono filtrati per categoria offerta (entry/signature/retainer), designazione già impostata sul servizio a livello di catalogo.
**Mode:** ui + schema
**Depends on**: Phase 11 (tabella `services` unificata + sistema tag polimorfico)
**Requirements**: OFFER-11, OFFER-15, OFFER-16, OFFER-17, OFFER-18
**Success Criteria** (what must be TRUE):
  1. L'admin compone un'offerta a 3 tier (A/B/C) assegnando i servizi del catalogo `services` tramite matrice di checkbox; il totale servizi di ogni tier si aggiorna live
  2. Ogni offerta ha tag su 4 dimensioni (categoria, ticket, tipo, obiettivo) creabili al volo, riusando il sistema tag di Phase 11
  3. Per ogni tier l'admin imposta un "prezzo pubblico" manuale, distinto e indipendente dal totale dei servizi
  4. Ogni offerta ha una promessa di trasformazione strutturata (Cliente Ideale / Risultato / tempo / Pain / Metodo)
  5. La lista offerte è filtrabile per categoria e supporta l'archiviazione (mostra/nascondi archiviate)
**Note**: Import CSV/Notion (ex OFFER-12) spostato a fase futura su decisione utente (2026-06-14, "per ora saltiamo") — vedi REQUIREMENTS.md
**Plans**: 5 plans
**Plan list**:
**Wave 1**
  - [x] 12-01-PLAN.md — Schema: offer_macros/offer_micros additive columns (category, ticket, is_archived, transformation promise, tier_letter, public_price) + offer_tier_services junction table, migration 0008 + idempotent push script
**Wave 2** *(blocked on Wave 1 completion)*
  - [x] 12-02-PLAN.md — BLOCKING checkpoint: apply migration 0008 to production database (SSH+docker exec, manual)
**Wave 3** *(blocked on Wave 2 — prod migration applied before schema-dependent code)*
  - [x] 12-03-PLAN.md — Query layer (getOfferEditorData/getOfferListCards/getOfferFieldOptions) + server actions (saveOfferEditor/toggleOfferArchived/tag CRUD/createOfferMacro)
**Wave 4** *(blocked on Wave 3 completion)*
  - [x] 12-04-PLAN.md — Offer list page redesign: category filter chips, archive toggle, card grid, "+ Nuova Offerta" CTA
  - [x] 12-05-PLAN.md — Offer editor detail page: tags (4 dimensions), services matrix (tier A/B/C checkboxes + live totals), prezzo pubblico, promessa di trasformazione, Salva/Annulla/Archivia
**UI hint**: yes — riferimento mockup utente 2026-06-14 (lista card per categoria + editor con matrice servizi×tier)
**Status**: Planned (2026-06-14) — ready for `/gsd-execute-phase 12`

### Phase 13: Workspace — Servizi Attivi
**Goal**: Il workspace progetto sostituisce le tab "Preventivo"/"Offerte"/"Forecast" con un'unica tab "Servizi attivi" che traccia servizi one-shot e ricorrenti con incassi mensili, senza perdere `accepted_total`/`quote_items`
**Mode:** ui + schema
**Depends on**: Phase 5 (`project_offers`), Phase 9 (flusso `accepted_total` via quote)
**Requirements**: PROJ-06, PROJ-07, PROJ-08, PROJ-09, PROJ-10
**Success Criteria** (what must be TRUE):
  1. La tab "Preventivo" è rimossa dal workspace progetto (solo UI — `quote_items` resta intatta, `accepted_total` resta editabile via tab Pagamenti)
  2. La tab "Offerte" diventa "Servizi attivi" e mostra tutte le offerte assegnate al progetto (`project_offers`)
  3. L'utente marca ogni "servizio attivo" come one-shot o ricorrente mensile
  4. Per i servizi ricorrenti, l'utente registra in quali mesi è stata incassata la fattura (schema nuovo, additivo)
  5. La pagina "Forecast" e la relativa voce di sidebar sono rimosse
**Plans**: TBD
**UI hint**: yes
**Status**: Pending planning

### Phase 14: CRM Attio-style & Fix
**Goal**: La tabella lead (`/admin/leads`) è ridisegnata in stile Attio/Pipedrive — inline editing dei campi principali e tag multi-select — e i bug residui del modulo CRM (FollowUpWidget non in italiano, LeadForm con type-relaxation, SendQuoteModal con rami irraggiungibili) sono risolti
**Mode:** ui
**Depends on**: Phase 10 (CRM Pipeline base)
**Requirements**: CRM-08, CRM-09, CRM-10, CRM-11, CRM-12
**Success Criteria** (what must be TRUE):
  1. La tabella lead supporta inline editing dei campi principali (status, next_action, ecc.) senza apertura di modale
  2. L'utente assegna tag multi-select ai lead, creando nuovi tag al volo
  3. Il `FollowUpWidget` è interamente in italiano, coerente col resto dell'app
  4. Il form lead (`LeadForm`) valida i campi senza workaround di type-relaxation su react-hook-form
  5. Il flusso `SendQuoteModal` (preventivo esistente vs nuovo) non contiene rami di codice irraggiungibili
**Plans:** 5/5 plans complete
Plans:
**Wave 1**
- [x] 14-01-PLAN.md — Data-layer foundation: getLeadsWithTags/getLeadFieldOptions query helpers + updateLeadField/addLeadTag/removeLeadTag/renameLeadTag server actions (requireAdmin-guarded)
- [x] 14-03-PLAN.md — Bug fixes: FollowUpWidget Italian translation (CRM-10), LeadForm typed useForm (CRM-11), SendQuoteModal dead branch removal (CRM-12)

**Wave 2** *(blocked on Wave 1 completion)*
- [x] 14-02-PLAN.md — LeadTable raw-table rewrite (inline edit + status dropdown + tag multi-select), LeadsSearch instant filter, page wiring, LeadDetail tags
**UI hint**: yes — riferimento design Pipedrive/Attio (confermato dall'utente 2026-06-13)
**Status**: ✅ Complete (2026-06-14) — 5/5 success criteria verified, code review 0 critical/6 warnings/3 info

### Phase 15: Dashboard Revenue Stats
**Goal**: La Dashboard admin mostra le statistiche di revenue mensile (ex `/admin/forecast`), calcolate da `project_offers`
**Mode:** ui
**Depends on**: Phase 13 (modello dati Servizi attivi)
**Requirements**: DASH-11
**Success Criteria** (what must be TRUE):
  1. La Dashboard admin mostra un breakdown di revenue mensile calcolato da `project_offers`
**Plans**: TBD
**UI hint**: yes
**Status**: Blocked — attesa mockup dashboard dall'utente (isolata/skippabile, non blocca Phase 16/17)

### Phase 16: Proposal AI — Data Foundations & Auto-Provisioning
**Goal**: Ogni offerta/preventivo ha un campo link di pagamento Stripe mostrato come CTA pubblica, e all'accettazione del preventivo il sistema crea automaticamente cliente + progetto, copia le fasi dall'offerta e configura 1-4 pagamenti
**Mode:** schema + automation
**Depends on**: Phase 9 (flusso accettazione preventivo), Phase 13 (Servizi attivi come target del provisioning)
**Requirements**: PROP-03, PROP-04
**Success Criteria** (what must be TRUE):
  1. Ogni offerta/preventivo ha un campo "link di pagamento" (Stripe Payment Link) mostrato come CTA nella pagina pubblica
  2. All'accettazione del preventivo, il sistema crea automaticamente cliente + progetto, copia le fasi dall'offerta e configura 1-4 pagamenti
**Plans**: TBD
**UI hint**: yes
**Status**: Pending planning

### Phase 17: Proposal AI — Builder, Pagina Pubblica & Email
**Goal**: Un builder AI genera una proposta a partire da cliente + offerta(e) selezionata(e) + note extra; la pagina pubblica `/quote/[token]` è ridisegnata; il link della proposta viene inviato via email (Resend) al lead
**Mode:** ai + ui
**Depends on**: Phase 16
**Requirements**: PROP-01, PROP-02, PROP-05
**Success Criteria** (what must be TRUE):
  1. L'admin avvia un builder AI che genera una proposta a partire da cliente + offerta(e) selezionata(e) + note extra fornite manualmente
  2. La pagina pubblica `/quote/[token]` è ridisegnata (HTML/CSS) per presentare la proposta generata
  3. Il sistema invia via email (Resend) il link della proposta pubblica al lead
**Plans**: TBD
**UI hint**: yes
**Status**: Pending planning

---

## v2.2 — Sales Loop (fasi attive)

### Phase 18 (R1): Cleanup & Consolidamento
**Goal**: Sgomberare il campo dai doppioni e dal peso morto prima di costruire il loop di vendita, senza perdere dati.
**Mode:** ui (solo rimozioni/rotte, nessun drop di tabelle)
**Depends on**: nessuna (può partire subito)
**Requirements**: CLEAN-01, CLEAN-02, CLEAN-03, CLEAN-04
**Success Criteria** (what must be TRUE):
  1. La pagina Forecast (`/admin/forecast`) e la sua voce di sidebar non esistono più
  2. Il quote builder manuale (`/admin/quotes/new`) e il suo entry point non esistono più
  3. Le statistiche annuali di `/admin/analytics` sono visibili nella Dashboard `/admin` come vista unica; la rotta `/admin/analytics` è eliminata (nessun doppione)
  4. Le fasi v2.1 residue (13/15/16/17) sono marcate cancellate/congelate nel planning
**Status**: Pending planning — `/gsd-plan-phase 18`

### Phase 19 (R2): Pipeline CRM Kanban
**Goal**: I lead si gestiscono in una board Kanban stile Pipedrive con drag-drop tra gli stage; vinto/perso è un cambio-colonna manuale.
**Mode:** ui
**Depends on**: Phase 14 (CRM lead esistente). Riusa `@dnd-kit` (pattern KanbanBoard progetti).
**Requirements**: PIPE-01, PIPE-02
**Success Criteria** (what must be TRUE):
  1. I lead sono mostrati in colonne per stage (contacted → qualified → proposal_sent → negotiating → won/lost) con drag-drop che aggiorna `leads.status`
  2. La tabella inline-edit esistente resta disponibile come vista alternativa
  3. Spostare un lead su "Vinto"/"Perso" è l'azione manuale che ne registra l'esito
**Status**: Pending planning — `/gsd-plan-phase 19`

### Phase 20 (R3): Knowledge Base Cliente (transcript)
**Goal**: Memorizzare i transcript datati delle call (multipli per lead/cliente) e mostrarli nel profilo, pronti per essere dati in pasto all'AI.
**Mode:** schema + ui
**Depends on**: Phase 14 (lead) / clienti. Migration a prod via SSH PRIMA del codice dipendente.
**Requirements**: KB-01, KB-02
**Success Criteria** (what must be TRUE):
  1. Esiste uno schema additivo `client_transcripts` (lead_id/client_id, testo, data, titolo/tipo, created_at)
  2. L'admin incolla un transcript con data dal dettaglio lead/cliente
  3. I transcript sono elencati in ordine cronologico nel profilo
**Status**: Pending planning — `/gsd-plan-phase 20`

### Phase 21 (R4): Agente AI — generazione preventivo
**Goal**: L'admin seleziona cliente + offerta; l'agente AI (Claude) legge i transcript + i dati dell'offerta e genera una bozza di preventivo personalizzata, che l'admin può rivedere ed editare.
**Mode:** ai + ui
**Depends on**: Phase 20 (transcript) + DB Offerte (Phase 11/12, fatto)
**Requirements**: AI-01, AI-02
**Success Criteria** (what must be TRUE):
  1. Dal builder l'admin sceglie cliente + offerta e lancia la generazione
  2. L'AI produce una bozza di preventivo che riflette i transcript del cliente e i contenuti dell'offerta
  3. L'admin rivede/edita la bozza prima di pubblicarla
**Note**: decisioni di design AI (modello Claude, prompt, storage output) in fase di planning dedicata
**Status**: Pending planning — `/gsd-plan-phase 21`

### Phase 22 (R5): Pagina pubblica `/preventivo/[slug]` + email
**Goal**: Pubblicare la proposta come pagina pubblica a `/preventivo/[slug]`, con accept/reject che si riflette nel CRM, e inviare il link via email.
**Mode:** ui
**Depends on**: Phase 21 (modello dati proposta). Evolve la meccanica di `/quote/[token]`.
**Requirements**: PUB-01, PUB-02, PUB-03
**Success Criteria** (what must be TRUE):
  1. La proposta generata è visibile come pagina pubblica HTML/CSS a `/preventivo/[slug]`
  2. Il cliente accetta/rifiuta dalla pagina; l'esito è disponibile lato admin per la conferma vinto/perso nel CRM
  3. Il link della proposta viene inviato al lead via email (Resend)
**Status**: Pending planning — `/gsd-plan-phase 22`

## Progress

| Phase | Plans | Status | Completed |
|-------|-------|--------|-----------|
| 11. Catalog Database-View UX & Legacy Consolidation | 4/4 | ✅ Done | 2026-06-13 |
| 12. Offer Editor — Tier A/B/C, Tag & Prezzo Pubblico | 5/5 | ✅ Done | 2026-06-18 |
| 13. Workspace — Servizi Attivi | — | ❌ Congelata (v2.2) | — |
| 14. CRM Attio-style & Fix | 3/3 | ✅ Done | 2026-06-14 |
| 15. Dashboard Revenue Stats | — | ❌ Abbandonata (v2.2) | — |
| 16. Proposal AI — Data Foundations & Auto-Provisioning | — | ❌ Ri-scopata (v2.2) | — |
| 17. Proposal AI — Builder, Pagina Pubblica & Email | — | ❌ Ri-scopata (v2.2) | — |
| 18 (R1). Cleanup & Consolidamento | — | Pending planning | — |
| 19 (R2). Pipeline CRM Kanban | — | Pending planning | — |
| 20 (R3). Knowledge Base Cliente (transcript) | — | Pending planning | — |
| 21 (R4). Agente AI — generazione preventivo | — | Pending planning | — |
| 22 (R5). Pagina pubblica preventivo + email | — | Pending planning | — |