docs(01): capture phase context
This commit is contained in:
Simone Cavalli
@@ -0,0 +1,126 @@
|
||||
# Phase 1: Foundation & Client Dashboard - Context
|
||||
|
||||
**Gathered:** 2026-05-13
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## 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.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## 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)
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## 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.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## 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)
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## 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
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## 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
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 1-Foundation & Client Dashboard*
|
||||
*Context gathered: 2026-05-13*
|
||||
Reference in New Issue
Block a user