clienthub/.planning/phases/02-admin-area-interactive-features/02-CONTEXT.md

Phase 2: Admin Area & Interactive Features - Context

Gathered: 2026-05-15 Status: Ready for planning

## Phase Boundary

Costruire l'area admin autenticata e le funzionalità interattive cliente. Al termine di questa fase:

• L'admin accede a /admin con credenziale sicura e gestisce tutti i dati
• Il cliente può approvare deliverable e lasciare commenti dalla sua dashboard L'area admin non è mai accessibile al cliente — path separato con sessione Auth.js. Service catalog e quote builder sono Phase 3. Claude AI è Phase 4.

## Implementation Decisions

Autenticazione Admin

• D-01: Auth.js v4 (next-auth@4) — versione stabile. La v5 è ancora in beta RC al 2026-05-15. Installare next-auth@4 + @auth/drizzle-adapter non è necessario (singolo admin hardcoded, no DB table per utenti).
• D-02: Credenziali admin via env vars — Singolo admin: ADMIN_EMAIL + ADMIN_PASSWORD in .env.local. No tabella users in DB. CredentialsProvider di Auth.js valida contro le env vars, restituisce session con { id: "admin", email: ADMIN_EMAIL }.
• D-03: Sessione JWT — Nessuna tabella session nel DB. JWT stateless firmato, scadenza 30 giorni. Non serve adapter.
• D-04: Protezione route admin — src/proxy.ts già gestisce /c/[token]. Aggiungere matcher /admin/:path* → redirect a /admin/login se no session. Il check sessione avviene nel middleware (getToken da next-auth/jwt) — nessun DB call per ogni request.

Mutation Pattern

• D-05: Server Actions — Next.js 15/16 nativo. Nessuna API route separata per le operazioni admin CRUD. Il form chiama una Server Action → Drizzle scrive DB → revalidatePath aggiorna la pagina. Pattern consistente con l'uso di Server Components già stabilito in Phase 1.
• D-06: API route solo per client interactions — Le approvazioni e i commenti del cliente passano per API routes (non Server Actions) perché il contesto del client non ha session admin. Route pattern: POST /api/client/approve e POST /api/client/comment — validate token via header o cookie custom, non Auth.js.

Admin UI Layout

• D-07: Lista → dettaglio — /admin → lista clienti con badge stato pagamenti. Click su cliente → /admin/clients/[id] con dettaglio completo.
• D-08: Tabs per sezioni cliente — Nella pagina dettaglio cliente, usare tabs: Panoramica | Fasi & Task | Documenti | Pagamenti | Commenti. shadcn non ha tabs installato — aggiungere @radix-ui/react-tabs + componente.
• D-09: Sidebar assente in v1 — Nessuna sidebar globale. Nav minimal: logo + link "Clienti" + pulsante logout. Desktop-first ma responsive.

Client Interactions (DASH-05, DASH-06)

• D-10: Approvazione deliverable — Pulsante "Approva" visibile solo se approved_at è null. Nessun modal di conferma — l'azione è semplice e l'approved_at immutabile basta come audit. POST a /api/client/approve con { deliverableId }, token letto da cookie o URL (il token è già in params nel client route).
• D-11: Commenti inline — Textarea + pulsante "Invia" direttamente sotto task/deliverable. POST a /api/client/comment. Lista commenti sopra il form, ordinati per created_at asc. Autore mostrato come "Tu" (cliente) o "iamcavalli" (admin). No real-time — reload della pagina sufficiente in v1.

Reusable Assets da Phase 1

• Schema DB: completo e non richiede modifiche. comments, deliverables.approved_at, payments già pronti.
• shadcn/ui installati: badge, button, card, input, label, select, table, textarea — usabili as-is.
• Drizzle ORM + postgres-js: pattern stabilito in Phase 1, stesso setup.
• Zod + react-hook-form: già installati, usare per tutti i form admin.
• src/lib/client-view.ts: già applica data isolation — non toccare per questa fase.

Claude's Discretion

• Struttura esatta delle Server Actions (file naming: actions.ts per domain o singolo file)
• Ordine campi nei form admin (quale sequenza per nuovo cliente)
• Icone lucide-react per stati (quale icona per da_saldare / inviata / saldato)
• Colori badge admin (riutilizzare --color-success, --color-warning, --color-info da globals.css)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Progetto & Requisiti

• .planning/PROJECT.md — Contesto progetto e decisioni chiave
• .planning/REQUIREMENTS.md — REQ-IDs Phase 2: ADMIN-01, ADMIN-02, DASH-05, DASH-06
• .planning/ROADMAP.md — Success criteria Phase 2
• CLAUDE.md — Architectural constraints LOCKED (token/PK separati, accepted_total, approved_at immutabile, due path auth)

Codice Esistente

• src/db/schema.ts — Schema completo, nessuna modifica necessaria in Phase 2
• src/proxy.ts — Edge middleware esistente (aggiungere matcher admin)
• src/lib/client-view.ts — Data isolation layer (non toccare)
• src/app/globals.css — Design tokens e @source not directives

Phase 1 Context

• .planning/phases/01-foundation-client-dashboard/01-CONTEXT.md — Decisioni D-04 (brand hardcoded), D-05 (light & clean), D-12 (note admin-only)

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• src/components/ui/: badge, button, card, input, label, progress, select, separator, table, textarea — tutti pronti
• src/db/schema.ts: export types Client, Phase, Task, Deliverable, Comment, Payment, Document, Note — usare as-is
• src/lib/utils.ts: cn() utility da shadcn — riusare ovunque

Pattern Stabiliti

• Server Components per fetch dati (nessun useEffect, nessun client-side waterfall)
• Drizzle query con .innerJoin() e .where(eq(...)) — vedere src/lib/client-view.ts
• revalidatePath dopo mutazioni per aggiornare UI senza client state

Integration Points

• src/proxy.ts: aggiungere '/admin/:path*' al matcher + logica getToken per redirect
• Client approval/comment: POST API routes che leggono token dal path URL del referrer o body request

Package da Aggiungere

• next-auth@4 — Auth.js per admin session
• @radix-ui/react-tabs + shadcn tabs component — per tabs nella pagina dettaglio cliente
• @radix-ui/react-dialog + shadcn dialog — per eventuali modali (confirm delete, ecc.)

</code_context>

## Deferred Ideas

• Brand customization panel (colori, logo admin) → Phase 3+ o post-roadmap
• Sidebar globale → non necessaria con lista→dettaglio in v1
• Real-time commenti (WebSocket/polling) → v2, non v1
• Multi-admin / ruoli → fuori scope (singolo admin in tutta la roadmap)
• Password change UI → non necessaria (env var, admin solo)

---

Phase: 2 — Admin Area & Interactive Features Context gathered: 2026-05-15