diff --git a/.planning/phases/01-foundation-client-dashboard/01-CONTEXT.md b/.planning/phases/01-foundation-client-dashboard/01-CONTEXT.md new file mode 100644 index 0000000..745fe97 --- /dev/null +++ b/.planning/phases/01-foundation-client-dashboard/01-CONTEXT.md @@ -0,0 +1,126 @@ +# Phase 1: Foundation & Client Dashboard - Context + +**Gathered:** 2026-05-13 +**Status:** Ready for planning + + +## Phase Boundary + +Costruire il DB schema, il token API e la dashboard cliente read-only. Al termine di questa fase, un link segreto è condivisibile con un cliente reale che può aprirlo su mobile o desktop e vedere lo stato completo del suo progetto — senza login, senza admin, senza interazione. L'admin area (CRUD, auth, commenti, approvazioni) è Phase 2. + + + + +## Implementation Decisions + +### Database & Infrastruttura + +- **D-01: Database su Coolify (Hetzner)** — Postgres istanza gestita da Coolify sul server Hetzner già pagato. Zero costo aggiuntivo. Neon è scartato in favore del self-hosting già disponibile. +- **D-02: ORM invariato** — Drizzle ORM con driver `postgres-js` (invece di `neon-http`). Schema e migrazioni identici, solo il driver di connessione cambia. +- **D-03: DNS in Phase 1** — Configurare `welcomeclient.iamcavalli.net` come CNAME verso Vercel nella Phase 1, non alla fine. Propagazione va verificata subito. + +### Brand & Visual Design + +- **D-04: Brand hardcoded in Phase 1** — Colori e logo iamcavalli fissi nel codice. La personalizzazione admin (tabella `brand_settings`, pannello colori/logo) è demandata a Phase 2. +- **D-05: Stile light & clean** — Sfondo chiaro, typography forte, layout professionale e leggibile su mobile. +- **D-06: Header dashboard** — Logo iamcavalli piccolo in un angolo (es. top-right o top-left), nome del brand cliente (`brand_name`) in primo piano e prominente. Non il nome del cliente, il nome del suo brand. + +### Layout Fasi e Task + +- **D-07: Timeline laterale per le fasi** — Indicatore temporale/progressione a sinistra, contenuto fase sulla destra. Trasmette senso di avanzamento sequenziale del progetto. +- **D-08: Barra progresso per fase** — In cima a ogni fase, una barra % calcolata dai task completati. Sotto la barra, lista dei task. +- **D-09: Barra progresso globale in cima** — Progress bar globale del progetto nella parte alta della dashboard, derivata dal totale dei task completati su tutti i task. Il cliente vede subito "sei al X%". + +### Stato Pagamenti + +- **D-10: Pagamenti sempre visibili** — Sezione pagamenti sempre in vista nella dashboard (non nascosta in accordion). Mostra: totale accettato + stato acconto 50% + stato saldo 50%. +- **D-11: Stati pagamento** — Tre stati per ogni payment row: `da_saldare` / `inviata` / `saldato`. Mai i prezzi singoli dei servizi — solo `accepted_total`. + +### Storico Decisioni (DASH-10) + +- **D-12: Admin scrive, cliente legge** — Le note/decisioni del log storico sono scritte solo dall'admin. Il cliente le vede in sola lettura nella sua dashboard. La UI per scrivere note è in Phase 2 (admin area). In Phase 1 il campo `body` è in schema e la visualizzazione lato cliente è già presente; sarà vuota finché Phase 2 non porta l'admin. + +### Primo Cliente (Testing) + +- **D-13: Seed script** — Uno script TypeScript (`scripts/seed.ts`) per inserire il primo cliente reale con dati completi (fasi, task, pagamenti, documenti). Eseguibile una volta con `npx tsx scripts/seed.ts`. Nessun form admin o SQL manuale necessario per Phase 1. + +### Claude's Discretion + +- Scelta del componente UI specifico per la timeline laterale (build custom vs. shadcn primitives) +- Struttura CSS delle card fasi e task (spaziatura, bordi, hover state) +- Schema colori specifico light & clean (bianco puro, grigi, quale accent color in attesa del brand panel) + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Progetto & Requisiti + +- `.planning/PROJECT.md` — Contesto progetto, Core Value, decisioni chiave e vincoli +- `.planning/REQUIREMENTS.md` — REQ-IDs Phase 1: DASH-01 through DASH-04, DASH-07 through DASH-10 +- `.planning/ROADMAP.md` — Success criteria Phase 1 + +### Ricerca tecnica + +- `.planning/research/STACK.md` — Stack raccomandato (nota: database cambiato da Neon a Coolify Postgres) +- `.planning/research/ARCHITECTURE.md` — Data model completo, component boundaries, build order +- `.planning/research/PITFALLS.md` — Pitfall critici: token-as-PK, ClientView enforcement, data model day-one decisions + +### Istruzioni progetto + +- `CLAUDE.md` — Architectural constraints LOCKED (token separato dalla PK, accepted_total denormalizzato, approved_at immutabile, due path auth isolati) + +No external specs beyond the above — requirements fully captured in decisions above. + + + + +## Existing Code Insights + +### Reusable Assets + +- Nessun codice esistente — progetto greenfield. + +### Established Patterns + +- Next.js 15 App Router: Server Components per la dashboard read-only (zero client-side waterfalls per rendering dati) +- Drizzle ORM con `postgres-js` invece di `neon-http` (Coolify Postgres connection string via env var `DATABASE_URL`) +- nanoid per generazione token: `nanoid()` → 21 char, URL-safe, ~126 bit di entropia + +### Integration Points + +- Dashboard cliente: route `/c/[token]` — Middleware valida token → 404 se mancante → Server Component legge DB e renderizza +- Seed script: `scripts/seed.ts` — inserisce dati cliente reale, genera token, stampa URL condivisibile +- DNS: CNAME `welcomeclient.iamcavalli.net` → `cname.vercel-dns.com` (da configurare su domain registrar) + + + + +## Specific Ideas + +- Il portale deve sembrare professionale e in linea con il brand iamcavalli — light & clean, non un SaaS generico +- Logo iamcavalli piccolo in corner + nome brand cliente prominente nell'header +- Progress bar globale del progetto in cima alla dashboard (percentuale) +- Timeline laterale per le fasi (non accordion, non card flat) — trasmette sequenzialità e avanzamento +- Barra progresso per singola fase, calcolata da task completati +- Personalizzazione colori/logo dal pannello admin è demandata a Phase 2 — in Phase 1 brand hardcoded + + + + +## Deferred Ideas + +- **Brand customization panel** (colori background, testi, logo upload dall'admin) → Phase 2, da aggiungere come requisito nell'area admin +- **Three.js / animazioni 3D** → Non necessario per questo tipo di portale. UI curata con Tailwind è sufficiente. +- **Commenti e approvazioni cliente** → Phase 2 (DASH-05, DASH-06) +- **Auth admin** → Phase 2 + + + +--- + +*Phase: 1-Foundation & Client Dashboard* +*Context gathered: 2026-05-13* diff --git a/.planning/phases/01-foundation-client-dashboard/01-DISCUSSION-LOG.md b/.planning/phases/01-foundation-client-dashboard/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..a15fb7c --- /dev/null +++ b/.planning/phases/01-foundation-client-dashboard/01-DISCUSSION-LOG.md @@ -0,0 +1,128 @@ +# Phase 1: Foundation & Client Dashboard - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-05-13 +**Phase:** 1 - Foundation & Client Dashboard +**Areas discussed:** Database, Three.js, Brand & visual design, Layout fasi e task, Primo cliente, Storico decisioni + +--- + +## Database + +| Option | Description | Selected | +|--------|-------------|----------| +| Postgres su Coolify | Zero costo extra — istanza Postgres su Hetzner già pagato | ✓ | +| Neon free tier | Postgres serverless gestito, 0.5 GB gratis, dipendenza esterna | | +| Oracle Cloud Free Tier | ARM 4vCPU 24GB RAM gratuito, richiede configurazione | | + +**User's choice:** Postgres su Coolify (Hetzner) +**Notes:** L'utente ha già un server Hetzner con Coolify attivo (usato per SparklingOrbit). Preferisce zero dipendenze esterne a pagamento e mantenere i dati nella propria infrastruttura. + +--- + +## Three.js + +| Option | Description | Selected | +|--------|-------------|----------| +| Animazioni sottili | Effetti di sfondo leggeri (particelle, gradienti animati) | | +| Elemento hero visivo | Shape 3D animata nella parte alta della dashboard | | +| Ripensaci | UI curata con Tailwind è sufficiente, niente 3D | ✓ | + +**User's choice:** Ripensaci — niente three.js +**Notes:** L'utente aveva menzionato three.js inizialmente ma dopo riflessione ha preferito concentrarsi su un'UI curata senza 3D. + +--- + +## Brand & Visual Design + +| Option | Description | Selected | +|--------|-------------|----------| +| Brand hardcoded in Phase 1 | Colori/logo iamcavalli fissi, personalizzazione in Phase 2 | ✓ | +| Già configurabile in Phase 1 | Tabella brand_settings e pannello già in Phase 1 | | + +**Brand hardcoded:** ✓ — pannello personalizzazione rimandato a Phase 2 + +| Stile visual | Description | Selected | +|--------------|-------------|----------| +| Dark & premium | Sfondo scuro, accenti brillanti | | +| Light & clean | Sfondo chiaro, typography forte | ✓ | +| Decido dal pannello | Nessuna preferenza ora | | + +**Stile:** Light & clean + +| Header | Description | Selected | +|--------|-------------|----------| +| Solo logo + nome progetto | Logo iamcavalli + nome progetto | | +| Solo nome brand cliente | brand_name in grande, nessun logo | | +| Entrambi | Logo piccolo in corner + brand_name cliente in primo piano | ✓ | + +**Header:** Logo iamcavalli piccolo in un angolo + nome brand cliente prominente + +--- + +## Layout Fasi e Task + +| Layout fasi | Description | Selected | +|-------------|-------------|----------| +| Accordion verticale | Fasi impilate, espandibili | | +| Card separate | Card per fase, task sempre visibili | | +| Timeline laterale | Indicatore temporale a sinistra, contenuto a destra | ✓ | + +**Layout fasi:** Timeline laterale + +| Task status | Description | Selected | +|-------------|-------------|----------| +| Badge colorato | Pallino/badge per stato | | +| Icona + testo | Icona con etichetta | | +| Barra progresso fase | Barra % per fase + lista task | ✓ | + +**Task status:** Barra progresso in cima a ogni fase + +| Avanzamento globale | Description | Selected | +|--------------------|-------------|----------| +| Sì, in cima | % completamento totale in cima alla dashboard | ✓ | +| No, solo per fase | Progresso solo per singola fase | | +| No progress bar | Solo stati task | | + +**Progress bar globale:** Sì, in cima alla dashboard + +--- + +## Primo Cliente + +| Option | Description | Selected | +|--------|-------------|----------| +| Seed script | TypeScript script, `npx tsx scripts/seed.ts` | ✓ | +| Form admin minimale | Form no-auth per creare primo cliente | | +| SQL diretto Coolify | INSERT manuale via console Coolify | | + +**User's choice:** Seed script +**Notes:** Lo script inserisce un cliente reale con fasi, task, pagamenti, documenti e stampa l'URL condivisibile. + +--- + +## Storico Decisioni (DASH-10) + +| Option | Description | Selected | +|--------|-------------|----------| +| Solo admin scrive | Admin aggiunge note, cliente legge in sola lettura | ✓ | +| Visibile solo in Phase 2 | UI mostrata solo con admin area | | + +**User's choice:** Admin scrive, cliente legge +**Notes:** In Phase 1 lo schema è già presente e il cliente vede le note (sezione vuota inizialmente). La UI per aggiungere note arriva con l'area admin in Phase 2. + +--- + +## Claude's Discretion + +- Scelta componente UI specifico per timeline laterale (shadcn primitives vs. custom) +- CSS dettagliato delle card fasi e task (spaziatura, bordi, hover) +- Accent color provvisorio per Phase 1 (in attesa del brand panel in Phase 2) + +## Deferred Ideas + +- **Brand customization panel** (colori, logo upload dall'admin) → Phase 2 +- **Three.js / animazioni 3D** → Scartato +- **Commenti e approvazioni** → Phase 2 (DASH-05, DASH-06)