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.

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

1. Ripianificare la roadmap GSD: definire milestone/fasi "Offer Studio" e "Proposal AI" (sostituiscono/ridefiniscono le vecchie Phase 11 auto-provisioning e 12 Resend — da ridiscutere dove collocarle). Usare /gsd-new-milestone o ridefinire le fasi correnti — far decidere all'utente.
2. Raccogliere dall'utente l'elenco puntuale dei problemi CRM visti il 2026-06-11 (design + funzionali + strutturali) e incorporarli nel ridisegno, NON fixarli in isolamento.
3. L'utente vuole fornire un suo design/mockup per le dashboard ("belle e utili") — chiederglielo prima di disegnare la UI; usarlo come contratto UI della fase (/gsd-ui-phase).
4. Candidati fix già noti da ieri (se si toccano quelle aree): FollowUpWidget in inglese (resto app in italiano), LeadForm 365 righe con type-relaxation su react-hook-form, SendQuoteModal logic flow sistemato in fretta.

---

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