clienthub/.planning/HANDOFF.md

Handoff

Living document — update at the end of each session so the next one can resume without re-deriving context. Overwrite stale sections; keep it short and actionable.

---

2026-06-12 — Nuova direzione: "Offer Studio" + "Proposal AI" (decisa, da pianificare)

Contesto della decisione

L'utente ha mostrato due riferimenti:

1. Diagramma architettura del suo amico (OMC): più app indipendenti (Hub, AI Agents, Content Marketing Tool, New Tool) che condividono UN database (Supabase), deploy da GitHub. Concetto: "compartimenti stagni" — aggiungere un'app non rompe le altre.
2. Il suo Notion attuale per le offerte (Offer Builder): DB Attività/Servizi con tag+prezzi, DB Offerte con sezioni (panoramica, strategia, scala valore, promessa, psicologia, pricing, vendita, rating, performance). Lo usa oggi ma vuole portare il flusso dentro ClientHub.

Problema dichiarato

Il catalogo/offerte che abbiamo costruito è "lento e macchinoso" rispetto a Notion: creare un'offerta, taggarla, metterci servizi è scomodo. L'utente chiedeva se servisse un DB esterno o import da Excel.

Decisioni prese (vincolanti per la pianificazione)

1. NO database esterno, NO Excel come fonte dati. Postgres resta l'unica fonte di verità (lezione del 2026-06-11: mai due fonti disallineate). Il problema è il layer UX, non il dato.
2. Rifare la UX di catalogo + offerte in stile "database view" Notion/Airtable, su misura:
   • tabella con inline editing (click su cella → edit → invio)
   • tag multi-select colorati con creazione al volo
   • quick-add (riga vuota in fondo, nome + invio)
   • filtri/ricerca istantanei
   • composizione offerta: apri offerta → spunti/trascini servizi dal catalogo a lato → totale live (@dnd-kit già nel progetto)
   • import CSV una tantum solo per seedare i pacchetti esistenti (porta d'ingresso, non fonte di verità)
3. Complessità Notion NON replicata in v1: solo servizi (tag/prezzo/costo), offerte (tag/pricing/stato), composizione. Sezioni analitiche (psicologia, rating, performance) dopo.
4. Architettura a compartimenti stagni = quello che già facciamo, formalizzato: un'unica app Next.js, moduli isolati (route group + service layer propri) su DB condiviso; migrations SOLO additive. Niente deploy separati per ora; se un modulo cresce, si stacca con deploy proprio sullo stesso DB (modello OMC).
5. Pipeline finale: Catalogo servizi → Offer Builder → Preventivo Builder AI (pesca cliente + offerta + info extra fornite dall'utente, genera proposta) → pagina pubblica HTML/CSS (base già live su /quote/[token]) → link pagamento in fondo (Stripe Payment Link come campo dell'offerta).
6. Ordine: prima la UX veloce del dato ("Offer Studio", che assorbe anche i fix CRM/design segnalati ieri), poi l'AI ("Proposal AI"). L'AI è l'ultimo miglio.

Feedback utente raccolto e triagiato (2026-06-12)

BUG (diagnosticato e FIXATO, commit ea20685 — DA PUSHARE):

• /admin/leads/[id] non caricava → in Next.js 16 params è una Promise, la pagina lo usava sincrono → id undefined → 500. Fix: await params. Build verificata. Controllare che non rientri lo stesso pattern in pagine future.

Decisioni strutturali (vanno nella fase "Offer Studio", non fix isolati):

1. Eliminare la tab "Preventivo" dal workspace progetto (vecchio sistema quote_items per cliente, vedi screenshot sessione 2026-06-12) — è un doppione: il Preventivo Builder app è l'unico flusso, anche per nuovi preventivi a già clienti. ⚠️ ATTENZIONE: solo rimozione UI — la tabella quote_items NON si tocca (storico + LOCKED constraints); capire dove finisce l'editing di clients.accepted_total (oggi sta in quella tab) — probabilmente settato dal flusso di accettazione quote o dalla nuova tab.
2. Nuova tab "Servizi attivi" al suo posto: offerte attive del cliente — alcune one-shot, altre ricorrenti mensili. La tab "Offerte" esistente probabilmente si ingloba qui (l'utente è aperto: "la teniamo o la inglobiamo") — motivo: sui già clienti si attivano offerte senza passare dal preventivo.
3. Eliminare la tab "Forecast" dalla sidebar; le statistiche di revenue mensile vanno nella Dashboard.
4. CRM: copiare Attio come riferimento UX (tabelle veloci, inline editing, tag, viste). Tutto custom in casa, NESSUN tool esterno. (Confermato dopo discussione Pipedrive/GoHighLevel/Attio: Attio = benchmark, non acquisto.)

Backlog dichiarato:

• Tracking incassi per mese sulle offerte ricorrenti (in che mese è stata incassata ogni fattura) → statistiche fatturato mese per mese. Da progettare nello schema di "Servizi attivi" (campo/tabella incassi) anche se la UI arriva dopo.

Fix minori noti (da assorbire quando si tocca l'area): FollowUpWidget in inglese (resto app in italiano), LeadForm 365 righe con type-relaxation su react-hook-form, SendQuoteModal logic flow sistemato in fretta.

Prossima sessione (l'utente passa a Sonnet per l'esecuzione)

1. Pushare il fix ea20685 se non già fatto (serve conferma utente per push su main).
2. Ripianificare la roadmap GSD: milestone/fasi "Offer Studio" (catalogo+offerte UX Attio-like, ristrutturazione tab progetti di cui sopra, CRM rifinito) e "Proposal AI" (builder AI → pagina pubblica → link pagamento). Le vecchie Phase 11 auto-provisioning e 12 Resend vanno ricollocate — far decidere all'utente.
3. L'utente vuole fornire un suo design/mockup per le dashboard — chiederglielo prima di disegnare la UI; usarlo come contratto UI (/gsd-ui-phase).

---

2026-06-11 (sera) — Phase 10 redo COMPLETATO, root cause risolta (storico)

• Root cause del crash post-deploy Phase 10: il DB prod non aveva NESSUNA migration dopo la 0000 (mancavano services, leads, offer_phases, quotes…). Catalogo e quote già rotti prima di Phase 10; il deploy Phase 10 ha aggiunto il crash dashboard (FollowUpWidget→leads). NON era un problema di piattaforma (l'app è Gitea→Coolify, non Vercel).
• Fix: migrations 0001+0003+0004+0005 applicate atomicamente al DB prod via ssh root@178.104.27.55 → docker exec -i xwkk0040w0kk0gsgcgog8owk psql (porta 54321 firewallata dall'esterno, si passa da SSH). Dati protetti verificati intatti (4 clients / 5 projects / 13 payments / 6 phases).
• Redo Phase 10 deployato: commit 5aa6614 (deps+UI primitives) e 008a434 (modulo CRM completo). Utente conferma pagine visibili in prod.
• REGOLA: le migration qui sono manuali — applicare al DB prod PRIMA di pushare codice che usa il nuovo schema. Pattern: cat migration.sql | ssh root@178.104.27.55 "docker exec -i xwkk0040w0kk0gsgcgog8owk sh -c 'psql -U \$POSTGRES_USER -d clienthub -v ON_ERROR_STOP=1 --single-transaction'" (verificare prima che sia additive-only).
• Branch phase10-wip (= 8e2752a) cancellabile quando il redo è considerato definitivo. Dangling ancora recuperabile: 5d75752 (sidebar App shortcuts).
• Script riusabile: scripts/push-phase10-migration.ts (solo dal server o con tunnel).