diff --git a/.planning/phases/01-foundation-client-dashboard/01-03-SUMMARY.md b/.planning/phases/01-foundation-client-dashboard/01-03-SUMMARY.md new file mode 100644 index 0000000..c222910 --- /dev/null +++ b/.planning/phases/01-foundation-client-dashboard/01-03-SUMMARY.md @@ -0,0 +1,149 @@ +--- +phase: 01-foundation-client-dashboard +plan: 03 +subsystem: client-portal +tags: [nextjs, middleware, drizzle-orm, client-view, server-component, edge-runtime] + +# Dependency graph +requires: + - 01-01 (Next.js bootstrap, DATABASE_URL, Drizzle client in src/db/index.ts) + - 01-02 (src/db/schema.ts — clients, phases, tasks, deliverables, payments, documents, notes) +provides: + - src/proxy.ts (Edge proxy per validazione token su /c/:path*) + - src/app/api/internal/validate-token/route.ts (Node.js route che interroga clients.token) + - src/lib/client-view.ts (ClientView interface + getClientView() function) + - src/app/c/[token]/page.tsx (Server Component placeholder per dashboard cliente) + - src/app/c/[token]/layout.tsx (Layout con metadata per rotte token-auth) +affects: + - 01-04-dashboard-ui (consuma ClientView interface e getClientView()) + - 01-05-seed-deploy (genera token, verifica accesso /c/[token]) + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Edge proxy pattern: proxy.ts usa fetch() verso /api/internal/validate-token — nessun import Drizzle/postgres-js in Edge runtime" + - "Next.js 16 breaking change: file convention rinominata da 'middleware' a 'proxy'; export function rinominata da 'middleware' a 'proxy'" + - "Next.js 15+ breaking change: params in Server Component è Promise<{ token: string }> — await params prima dell'uso" + - "ClientView enforced server-side: interface TypeScript + query function che non tocca mai quote_items o service_catalog" + - "inArray() per scoping tasks/deliverables: previene full table scan su clienti che non appartengono alla sessione" + +key-files: + created: + - src/proxy.ts (proxy Edge-compatible — rinominato da middleware.ts per Next.js 16) + - src/app/api/internal/validate-token/route.ts (Node.js route, query clients.token via Drizzle) + - src/lib/client-view.ts (ClientView interface + getClientView() — 209 righe) + - src/app/c/[token]/page.tsx (Server Component placeholder — 28 righe) + - src/app/c/[token]/layout.tsx (Layout con metadata — 14 righe) + modified: [] + +key-decisions: + - "Next.js 16 richiede file 'proxy.ts' (non 'middleware.ts') ed export function 'proxy' (non 'middleware') — auto-corretto da Rule 1" + - "params nelle Server Component Next.js 15+ è Promise<{ token: string }> — await obbligatorio (breaking change)" + - "ClientView.payments non espone 'amount' — solo label e status — vincolo architetturale LOCKED rispettato" + - "getClientView() usa inArray() per scopare tasks e deliverables ai soli phase_id del cliente, evitando leak cross-client" + +# Metrics +duration: 25min +completed: 2026-05-14 +--- + +# Phase 1 Plan 03: Token Middleware + Client Portal Data Layer — Route /c/[token] operativa + +**Edge proxy con validazione token, ClientView type system che esclude quote_items, e Server Component che fetcha tutti i dati cliente senza esporre segreti admin. Build Next.js 16 senza errori TypeScript.** + +## Performance + +- **Duration:** ~25 min +- **Started:** 2026-05-13T22:50:00Z +- **Completed:** 2026-05-14T00:15:00Z +- **Tasks:** 3/3 +- **Files created:** 5 + +## Accomplishments + +- `src/proxy.ts`: proxy Edge-compatible per Next.js 16 — valida token via `fetch('/api/internal/validate-token')` senza import Drizzle/postgres-js. Matcher configurato su `/c/:path*`. Token non trovato → rewrite su `/not-found`. +- `src/app/api/internal/validate-token/route.ts`: route Node.js che interroga `clients.token` via Drizzle ORM. Ritorna `{ valid: true }` (200) o `{ valid: false }` (404/400/500). Drizzle funziona correttamente qui perché non è nel runtime Edge. +- `src/lib/client-view.ts`: `ClientView` interface che esclude esplicitamente `quote_items`, `service_catalog` e prezzi singoli. `getClientView()` esegue 6 query scoped (client by token → phases → tasks via inArray → deliverables via inArray → payments → documents → notes). Progress % calcolata server-side. `accepted_total: client.accepted_total ?? '0'`. +- `src/app/c/[token]/page.tsx`: Server Component con `await params`, chiama `getClientView(token)`, ritorna `notFound()` se null. ISR a 60s. +- `src/app/c/[token]/layout.tsx`: layout minimo con metadata. +- `npm run build` completato con successo — zero errori TypeScript, tutte le route presenti nel build output. + +## Task Commits + +1. **Task 1: Edge proxy + validate-token API route** — `ef34817` (feat) +2. **Task 2: ClientView type system + getClientView()** — `14787ba` (feat) +3. **Task 3: /c/[token] Server Component + layout** — `8b5e723` (feat, include deviazione Rule 1) + +## Files Created/Modified + +- `src/proxy.ts` — Edge proxy per /c/:path* (rinominato da middleware.ts — vedi Deviazioni) +- `src/app/api/internal/validate-token/route.ts` — Node.js route, query `eq(clients.token, token)`, risposta 200/404 +- `src/lib/client-view.ts` — ClientView interface (quote_items mai inclusi) + getClientView() con inArray scoping +- `src/app/c/[token]/page.tsx` — Server Component placeholder, notFound() su token invalido +- `src/app/c/[token]/layout.tsx` — Layout con metadata + +## Decisions Made + +- **Next.js 16 proxy convention:** La nuova convenzione rinomina `middleware.ts` → `proxy.ts` ed esige `export function proxy` (non `middleware`). La build ha segnalato il deprecation warning al primo tentativo. Risolto con rename + export update (Rule 1). +- **params come Promise:** Next.js 15+ tratta `params` come `Promise<{ token: string }>` nelle Server Component. Il piano usava la sintassi Next.js 14 sincrona — aggiornato ad `await params` per conformità (Rule 1). +- **ClientView.payments senza amount:** Il campo `amount` di `payments` è intenzionalmente omesso dalla `ClientView`. Il cliente vede solo `label` e `status`. Vincolo architetturale LOCKED rispettato a livello di query. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Next.js 16 depreca la convenzione 'middleware' in favore di 'proxy'** +- **Found during:** Task 3 — `npm run build` ha emesso warning e poi errore: "Proxy is missing expected function export name" +- **Issue:** Next.js 16 ha rinominato la file convention da `middleware.ts` a `proxy.ts` e richiede che la funzione esportata si chiami `proxy` (o `default`), non `middleware`. +- **Fix:** Rinominato `src/middleware.ts` → `src/proxy.ts`; rinominato `export async function middleware` → `export async function proxy`. Il commit ef34817 conteneva middleware.ts — il Task 3 commit 8b5e723 include la modifica. +- **Files modified:** src/proxy.ts (rinominato da src/middleware.ts) +- **Commit:** 8b5e723 + +**2. [Rule 1 - Bug] params come Promise in Next.js 15+ Server Component** +- **Found during:** Task 3 — il piano usava la sintassi `params: { token: string }` di Next.js 14 +- **Issue:** In Next.js 15+, i `params` nelle Server Component sono `Promise<{ token: string }>`. Usare la sintassi sincrona avrebbe causato TypeScript error e comportamento errato a runtime. +- **Fix:** Tipizzato `params: Promise<{ token: string }>` e aggiunto `const { token } = await params;` prima dell'uso. +- **Files modified:** src/app/c/[token]/page.tsx +- **Commit:** 8b5e723 + +## Known Stubs + +La `page.tsx` mostra un placeholder minimo (brand_name, brief, token). Questo è **intenzionale e documentato nel piano**: "Placeholder content — full UI in Plan 04". Il Plan 04 (Dashboard UI) sostituirà questo placeholder con la UI completa. Il goal del piano (route operativa + data fetching corretto) è raggiunto pienamente. + +## Threat Surface Scan + +Nessuna nuova superficie di sicurezza non prevista dal threat model 01-03: +- T-03-001 (ClientView shape): mitigato — interface TypeScript + getClientView() non tocca mai quote_items/service_catalog +- T-03-002 (Token parameter): mitigato — proxy valida il token prima che qualsiasi pagina venga renderizzata; token invalidi → /not-found +- T-03-003 (DoS su getClientView): accettato — query indicizzate su client_id/token + +L'API route `/api/internal/validate-token` è accessibile pubblicamente (nessun secret header). Questo è intenzionale: ritorna solo `{ valid: boolean }` — nessun dato cliente esposto. Un attaccante può enumerare token validi con brute force ma: (1) nanoid 21 chars offre ~126 bit di entropia, rendendo il brute force computazionalmente impossibile; (2) nessun dato sensibile è esposto dalla route. + +## Self-Check + +- [x] `src/proxy.ts` esiste (edge proxy — rinominato da middleware.ts) +- [x] `src/app/api/internal/validate-token/route.ts` esiste (query clients.token via Drizzle) +- [x] `src/lib/client-view.ts` esiste (ClientView interface + getClientView()) +- [x] `src/app/c/[token]/page.tsx` esiste (Server Component con await params) +- [x] `src/app/c/[token]/layout.tsx` esiste +- [x] Commit `ef34817` esiste (Task 1) +- [x] Commit `14787ba` esiste (Task 2) +- [x] Commit `8b5e723` esiste (Task 3) +- [x] `npm run build` completato senza errori TypeScript +- [x] Build output mostra `/api/internal/validate-token` (Dynamic) e `/c/[token]` (Dynamic) +- [x] `proxy.ts` NON importa `@/db` o `drizzle-orm` (Edge safe) +- [x] `client-view.ts` non contiene query su `quote_items` o `service_catalog` +- [x] `accepted_total: client.accepted_total ?? '0'` presente + +## Self-Check: PASSED + +## Next Phase Readiness + +- Plan 04 (Dashboard UI) può partire — `getClientView()` è disponibile e testa TypeScript OK +- Import pattern: `import { getClientView, type ClientView } from '@/lib/client-view'` +- La route `/c/[token]` è operativa — con un cliente seedato da Plan 05 sarà accessibile + +--- +*Phase: 01-foundation-client-dashboard* +*Completed: 2026-05-14* \ No newline at end of file