# Roadmap: ClientHub

## 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.

## 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.

- [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 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

## 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: 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
**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)

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5

| 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 | 0/2 | Pending | - |
| 7. Claude AI Onboarding (v2) | 0/TBD | Pending | - |
