simone/clienthub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(planning): v2.1 milestone setup + Phase 11 context/patterns

Browse Source 
- Archive v2.0 phases (07-10) under .planning/milestones/
- v2.1 REQUIREMENTS/ROADMAP (Phases 11-17: Offer Studio + Proposal AI)
- DESIGN-SYSTEM.md (database-view UI contract for Phases 11-14)
- Phase 11 CONTEXT, DISCUSSION-LOG, PATTERNS

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Simone Cavalli
2026-06-13 15:07:06 +02:00
parent 857af5c182
commit 03898f2a59
29 changed files with 8758 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+81 -139
View File
@@ -1,173 +1,115 @@
# Requirements — ClientHub v2.0 Business Operations Suite
# Requirements — ClientHub v2.1 Offer Studio + Proposal AI
## Dashboard Cliente (v1)
**Defined:** 2026-06-13
**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
v2.0 (Phases 7–10) ha consegnato catalogo unificato, offerte con fasi, preventivo pubblico e CRM pipeline (vedi MILESTONES.md, REQUIREMENTS.md archiviato in `.planning/milestones/v2.0-REQUIREMENTS.md`). v2.1 rifà la UX di catalogo/offerte in stile database-view, ristruttura il workspace progetto, ricostruisce il CRM in stile Attio e chiude il loop commerciale con un builder preventivi AI.
## Offer Studio — Catalogo & Offerte (v1)
| ID | Requirement | Status |
|----|-------------|--------|
| DASH-01 | Ogni cliente ha un URL segreto univoco (nessun login richiesto) | Pending |
| DASH-02 | La dashboard mostra nome cliente, nome brand, brief del progetto e stato attuale | Pending |
| DASH-03 | Il piano è strutturato per fasi con milestone e task all'interno di ogni fase | Pending |
| DASH-04 | I task hanno stato visibile (da fare / in corso / fatto) | Pending |
| DASH-05 | Il cliente può approvare i deliverable dalla sua area | Pending |
| DASH-06 | Il cliente può lasciare commenti su task e deliverable | Pending |
| DASH-07 | Il cliente vede solo il totale del preventivo accettato (non i prezzi dei singoli servizi) | Pending |
| DASH-08 | Il cliente vede lo stato dei pagamenti: acconto 50% (da saldare / inviata / saldato) e saldo 50% (da saldare / inviata / saldato) | Pending |
| DASH-09 | Link a documenti e file (Google Drive, PDF, deliverable) | Pending |
| DASH-10 | Storico note e decisioni prese nel tempo | Pending |
| OFFER-07 | L'utente vede ed edita il catalogo `services` come tabella con inline editing (click su cella → edit → invio salva) | Pending |
| OFFER-08 | L'utente assegna tag multi-select a servizi/offerte, creando nuovi tag al volo senza uscire dalla tabella | Pending |
| OFFER-09 | L'utente aggiunge un nuovo servizio/offerta tramite riga vuota in fondo alla tabella (nome + invio) | Pending |
| OFFER-10 | L'utente filtra/cerca servizi e offerte istantaneamente (ricerca client-side, nessun reload) | Pending |
| OFFER-11 | L'utente compone un'offerta trascinando servizi dal catalogo (`@dnd-kit`), con totale live aggiornato durante il drag | Pending |
| OFFER-12 | L'utente importa un CSV one-shot per popolare servizi/offerte esistenti (solo seed iniziale, non sync continuo) | Pending |
| OFFER-13 | I dati legacy di `service_catalog` e `offer_services` sono consolidati in `services` senza perdita (migration additiva) | Pending |
## Area Amministratore (v1)
## Workspace Progetto — Servizi Attivi (v1)
| ID | Requirement | Status |
|----|-------------|--------|
| ADMIN-01 | Vista di tutti i clienti con stato sintetico | Pending |
| ADMIN-02 | Gestione completa di ogni cliente: fasi, task, documenti, pagamenti | Pending |
| ADMIN-03 | Preventivo completo con dettaglio servizi (non visibile al cliente) | Pending |
| PROJ-06 | La tab "Preventivo" è rimossa dal workspace progetto (solo UI — `quote_items` resta intatta, `accepted_total` resta editabile via tab Pagamenti) | Pending |
| PROJ-07 | La tab "Offerte" diventa "Servizi attivi": mostra tutte le offerte assegnate al progetto (`project_offers`) | Pending |
| PROJ-08 | L'utente marca ogni "servizio attivo" come one-shot o ricorrente mensile | Pending |
| PROJ-09 | Per i servizi ricorrenti, l'utente registra in quali mesi è stata incassata la fattura (schema nuovo, additivo — UI può essere minimale) | Pending |
| PROJ-10 | La pagina "Forecast" e la relativa voce di sidebar sono rimosse | Pending |
## Catalogo Servizi (v1)
## CRM Custom Attio-style (v1)
| ID | Requirement | Status |
|----|-------------|--------|
| CAT-01 | File/database dei servizi con prezzi e cosa è incluso | Pending |
| CAT-02 | Usato come base per la generazione assistita dei preventivi | Pending |
| CRM-08 | La tabella lead (`/admin/leads`) supporta inline editing dei campi principali (status, next_action, ecc.) senza apertura modale | Pending |
| CRM-09 | L'utente assegna tag multi-select ai lead, creando nuovi tag al volo | Pending |
| CRM-10 | Il `FollowUpWidget` è in italiano, coerente col resto dell'app | Pending |
| CRM-11 | Il form lead (`LeadForm`) valida i campi senza workaround di type-relaxation su react-hook-form | Pending |
| CRM-12 | Il flusso `SendQuoteModal` (preventivo esistente vs nuovo) non contiene rami di codice irraggiungibili | Pending |
## Progetti Multi-Project (Phase 4)
## Dashboard — Revenue Stats (v1, bloccato su mockup utente)
| ID | Requirement | Status |
|----|-------------|--------|
| PROJ-01 | Ogni cliente può avere N progetti; ogni progetto ha workspace indipendente (fasi, pagamenti, preventivo, timer) | Pending |
| PROJ-02 | La dashboard cliente mostra tabs per 2+ progetti; con 1 progetto mostra direttamente il workspace senza selettore | Pending |
| PROJ-03 | La pagina /admin/projects elenca tutti i progetti con €/h reale e timer; /admin/projects/[id] è il workspace progetto | Pending |
| PROJ-04 | Il link cliente supporta slug personalizzabile (/c/mario-rossi) con fallback al token esistente | Pending |
| PROJ-05 | Analytics profittabilità per progetto: ore lavorate, accepted_total, €/h reale vs target_hourly_rate globale | Pending |
| DASH-11 | La Dashboard admin mostra le statistiche di revenue mensile (ex `/admin/forecast`, calcolate da `project_offers`) | Blocked — attesa mockup dashboard utente |
## Offer System (Phase 5)
## Proposal AI (v1)
| ID | Requirement | Status |
|----|-------------|--------|
| OFFER-01 | Admin può creare macro-offerte (es. Entry Offer, Signature Offer, Retainer) con nome interno, nome pubblico e promessa di trasformazione macro | Pending |
| OFFER-02 | Ogni macro-offerta ha micro-offerte figlie (es. Entry A/B/C) con nome interno, nome pubblico, promessa di trasformazione micro e durata in mesi | Pending |
| OFFER-03 | Admin può creare servizi con nome, prezzo e descrizione della trasformazione; ogni servizio è assegnabile a più micro-offerte via multi-select (many-to-many) | Pending |
| OFFER-04 | Admin può assegnare una o più micro-offerte a un progetto; admin vede le offerte attive per ogni progetto e cliente | Pending |
| OFFER-05 | La dashboard cliente mostra le offerte attive con nome pubblico, prezzo cumulativo dei servizi inclusi e prezzo finale accettato in evidenza; se ha più offerte le vede tutte | Pending |
| OFFER-06 | Admin ha una vista revenue forecast dei 12 mesi successivi basata su offerte attive, durata e accepted_total; breakdown mensile con totale fatturato per mese | Pending |
| PROP-01 | L'admin avvia un builder AI che genera una proposta a partire da cliente + offerta(e) selezionata(e) + note extra fornite manualmente | Pending |
| PROP-02 | La pagina pubblica `/quote/[token]` è ridisegnata (HTML/CSS) per presentare la proposta generata | Pending |
| PROP-03 | Ogni offerta/preventivo ha un campo "link di pagamento" (Stripe Payment Link) mostrato come CTA nella pagina pubblica | Pending |
| PROP-04 | All'accettazione del preventivo, il sistema crea automaticamente cliente + progetto, copia le fasi dall'offerta e configura 1-4 pagamenti (ex-Phase 11 WIN-01..06) | Pending |
| PROP-05 | Il sistema invia via email (Resend) il link della proposta pubblica al lead (ex-Phase 12) | Pending |
## Catalogo Unificato & Offer Builder (Phase 7–8)
## v2 Requirements (Deferred)
| ID | Requirement | Status |
|----|-------------|--------|
| CAT-U-01 | Un'unica tabella `services` unifica `service_catalog` + `offer_services`; migrazione zero data loss con audit trail (`migrated_from`) | Phase 7 |
| CAT-U-02 | Admin `/admin/catalog` list/add/edit/soft-delete per i servizi singoli (nome, prezzo_unitario, attivo) | Phase 7 |
| OFFER-B-01 | Offer = nome + tag tipo (Entry/Signature/Retainer/custom) + fasi ordinate; fasi indipendenti l'una dall'altra (es. Signature A/B/C non ereditate) | Phase 8 |
| OFFER-B-02 | `/admin/offers/[id]/edit` two-column builder: left colonna servizi (ricerca), right colonna fasi con drag&drop tra fasi e dentro fase (reorder) | Phase 8 |
| OFFER-B-03 | Drag&drop salva per singolo drop con optimistic update client-side + validazione server; versioning previene race condition da multi-tab edit | Phase 8 |
### Catalogo Avanzato
## Quote Builder & Public Proposal Pages (Phase 9)
- **OFFER-14**: Sezioni analitiche stile Notion per le offerte (psicologia, rating, performance)
| ID | Requirement | Status |
|----|-------------|--------|
| QUOTE-01 | `/admin/quotes/new`: select cliente + 1-3 offerte + override prezzo per ciascuna offerta + genera link pubblico `/quote/[token]` | Phase 9 |
| QUOTE-02 | Public `/quote/[token]` pagina multistep (Zod validazione): Step 1 (overview) → Step 2 (tier A/B/C selection + prezzi + fasi) → Step 3 (summary + accept/decline) | Phase 9 |
| QUOTE-03 | Accept CTA → POST `/api/public/quote/accept?token=X` con cattura email (opzionale) + note opzionali; registra timestamp accepted_at immutabile | Phase 9 |
| QUOTE-04 | Quote token: nanoid 21 char (~122 bits), unico, validato in proxy come `/client/[token]` (nessun login sessione); rate limit 3 views/min per IP | Phase 9 |
| QUOTE-05 | Mai esporre `quote_items` (prezzi per servizio) via public API; client API vede solo `accepted_total` (server-side ClientView type enforces) | Phase 9 |
### Accesso Cliente
## CRM Pipeline & Activity Logging (Phase 10)
- **AUTH-OTP-01**: Accesso dashboard cliente via OTP email (design pronto, vedi memoria `project_clienthub_otp_access`)
| ID | Requirement | Status |
|----|-------------|--------|
| CRM-01 | Lead CRUD: `/admin/leads` list table (name, email, company, status, last_contact_date, next_action) con create/edit/delete | Phase 10 |
| CRM-02 | Lead detail page `/admin/leads/[id]`: full profilo, activity log (reverse chronological), quote(s) sent, actions menu (log activity, send quote, mark won) | Phase 10 |
| CRM-03 | Pipeline stages: Contacted → Qualified → Proposal Sent → Negotiating → Won / Lost; transizioni via dropdown (manual di default) | Phase 10 |
| CRM-04 | Activity logging: tipi (call, email, meeting, note); ogni attività: type, date, durata (opz), notes; auto-aggiorna lead.last_contact_date | Phase 10 |
| CRM-05 | "Log activity" modal: <10 sec UX (type dropdown, date picker, notes textarea, save) — bassa tolleranza per data entry lunghi | Phase 10 |
| CRM-06 | Follow-up reminders widget in dashboard: "Follow up today" (leads dove last_contact_date < oggi - 7 giorni); click → jump lead detail | Phase 10 |
| CRM-07 | "Send Quote" button in lead detail: select existing quote o crea nuovo; update lead.last_quote_sent + status → "Proposal Sent" | Phase 10 |
### Architettura
## Auto-Onboarding on Win (Phase 11)
- **ARCH-01**: Split di un modulo "compartimento stagno" in deploy separato (solo se il modulo cresce abbastanza da giustificarlo)
| ID | Requirement | Status |
|----|-------------|--------|
| WIN-01 | "Mark as Won" button in lead detail (o auto-triggered da public quote accept); idempotency: call 2 volte = idempotent, stesso client token | Phase 11 |
| WIN-02 | winLead(leadId, quoteId): crea client (name da lead, token = nanoid), crea project (name = company/offer name), copia offer fasi → project fasi | Phase 11 |
| WIN-03 | 1-4 pagamenti: user sceglie split template (50/50, 3-part, 4-part, custom); registra importo accepted_total da quote | Phase 11 |
| WIN-04 | Generate client dashboard link (`/client/[token]`), invia via email al lead (copy-paste OK, email automation deferred Phase 12+) | Phase 11 |
| WIN-05 | Quote accept da public link `/quote/[token]` auto-aggiorna lead.status → "Proposal Sent" + trigga win (auto-onboarding) | Phase 11 |
| WIN-06 | Copy offer phases → project phases: tutte le fasi copiate con status = "upcoming", le fasi modificabili dopo (template immutabile, instance editable) | Phase 11 |
## Out of Scope
## Flusso Claude (v3 — deferred to Phase 13+)
| ID | Requirement | Status |
|----|-------------|--------|
| CLAUDE-01 | Onboarding guidato step-by-step via chat per aggiungere un nuovo cliente | Deferred |
| CLAUDE-02 | Generazione del piano a fasi basato dal brief | Deferred |
| CLAUDE-03 | Generazione preventivo assistita (Claude suggerisce struttura offerta, tu approvi) | Deferred |
## Out of Scope (v2.0)
- Fatturazione e invio fatture (solo stato pagamenti)
- App mobile nativa (solo web responsive)
- Multi-utente con team (solo admin singolo)
- Prezzi singoli visibili al cliente (solo totale accettato)
- Email automation (manual copy-paste OK per MVP)
- Lead scoring / predictive analytics
- Team collaboration
- Lead de-duplication (manual link on Win)
- Proposal expiry logic (open indefinitely)
- BullMQ persistent reminders (in-app computed, persistent deferred Phase 12+)
| Feature | Reason |
|---------|--------|
| Fatturazione e invio fatture | Solo stato pagamenti, gestione contabile fuori |
| App mobile nativa | Solo web responsive |
| Multi-utente con team | Solo admin singolo per ora |
| Prezzi singoli visibili al cliente | Vede solo il totale accettato (vincolo LOCKED) |
| File hosting | Documenti solo come URL esterni (vincolo v1, ancora valido) |
| Database esterno o Excel come fonte dati | Postgres unica fonte di verità — il problema è la UX, non il dato |
| Notion-clone completo (sezioni psicologia/rating/performance) | Troppo complesso per v1, vedi v2 Requirements |
| Deploy separati per modulo (architettura OMC multi-app) | Non finché un modulo non cresce abbastanza da giustificarlo |
## Traceability
Popolata dal roadmapper durante la creazione della roadmap.
| Requirement | Phase | Status |
|-------------|-------|--------|
| DASH-01 | Phase 1 | Pending |
| DASH-02 | Phase 1 | Pending |
| DASH-03 | Phase 1 | Pending |
| DASH-04 | Phase 1 | Pending |
| DASH-07 | Phase 1 | Pending |
| DASH-08 | Phase 1 | Pending |
| DASH-09 | Phase 1 | Pending |
| DASH-10 | Phase 1 | Pending |
| ADMIN-01 | Phase 2 | Pending |
| ADMIN-02 | Phase 2 | Pending |
| DASH-05 | Phase 2 | Pending |
| DASH-06 | Phase 2 | Pending |
| CAT-01 | Phase 3 | Pending |
| CAT-02 | Phase 3 | Pending |
| ADMIN-03 | Phase 3 | Pending |
| PROJ-01 | Phase 4 | Pending |
| PROJ-02 | Phase 4 | Pending |
| PROJ-03 | Phase 4 | Pending |
| PROJ-04 | Phase 4 | Pending |
| PROJ-05 | Phase 4 | Pending |
| OFFER-01 | Phase 5 | Pending |
| OFFER-02 | Phase 5 | Pending |
| OFFER-03 | Phase 5 | Pending |
| OFFER-04 | Phase 5 | Pending |
| OFFER-05 | Phase 5 | Pending |
| OFFER-06 | Phase 5 | Pending |
| CAT-U-01 | Phase 7 | Phase 7 |
| CAT-U-02 | Phase 7 | Phase 7 |
| OFFER-B-01 | Phase 8 | Phase 8 |
| OFFER-B-02 | Phase 8 | Phase 8 |
| OFFER-B-03 | Phase 8 | Phase 8 |
| QUOTE-01 | Phase 9 | Phase 9 |
| QUOTE-02 | Phase 9 | Phase 9 |
| QUOTE-03 | Phase 9 | Phase 9 |
| QUOTE-04 | Phase 9 | Phase 9 |
| QUOTE-05 | Phase 9 | Phase 9 |
| CRM-01 | Phase 10 | Phase 10 |
| CRM-02 | Phase 10 | Phase 10 |
| CRM-03 | Phase 10 | Phase 10 |
| CRM-04 | Phase 10 | Phase 10 |
| CRM-05 | Phase 10 | Phase 10 |
| CRM-06 | Phase 10 | Phase 10 |
| CRM-07 | Phase 10 | Phase 10 |
| WIN-01 | Phase 11 | Phase 11 |
| WIN-02 | Phase 11 | Phase 11 |
| WIN-03 | Phase 11 | Phase 11 |
| WIN-04 | Phase 11 | Phase 11 |
| WIN-05 | Phase 11 | Phase 11 |
| WIN-06 | Phase 11 | Phase 11 |
| CLAUDE-01 | Phase 13 (v3) | Deferred |
| CLAUDE-02 | Phase 13 (v3) | Deferred |
| CLAUDE-03 | Phase 13 (v3) | Deferred |
| OFFER-07 | Phase 11 | Pending |
| OFFER-08 | Phase 11 | Pending |
| OFFER-09 | Phase 11 | Pending |
| OFFER-10 | Phase 11 | Pending |
| OFFER-13 | Phase 11 | Pending |
| OFFER-11 | Phase 12 | Pending |
| OFFER-12 | Phase 12 | Pending |
| PROJ-06 | Phase 13 | Pending |
| PROJ-07 | Phase 13 | Pending |
| PROJ-08 | Phase 13 | Pending |
| PROJ-09 | Phase 13 | Pending |
| PROJ-10 | Phase 13 | Pending |
| CRM-08 | Phase 14 | Pending |
| CRM-09 | Phase 14 | Pending |
| CRM-10 | Phase 14 | Pending |
| CRM-11 | Phase 14 | Pending |
| CRM-12 | Phase 14 | Pending |
| DASH-11 | Phase 15 | Blocked |
| PROP-03 | Phase 16 | Pending |
| PROP-04 | Phase 16 | Pending |
| PROP-01 | Phase 17 | Pending |
| PROP-02 | Phase 17 | Pending |
| PROP-05 | Phase 17 | Pending |
---
*Requirements defined: 2026-06-13*
*Last updated: 2026-06-13 after milestone v2.1 kickoff*