docs(phase-03): complete phase execution — service catalog + quote builder verified

2026-05-19 23:12:59 +02:00
parent fe0a65ebeb
commit 67e4483b48
7 changed files with 1796 additions and 14 deletions
@@ -0,0 +1,87 @@
+---
+phase: 3
+title: Service Catalog & Quote Builder
+status: discussed
+date: 2026-05-16
+---
+
+# Phase 3 — Decisions & Context
+
+## Phase Goal
+L'admin può costruire un catalogo servizi riutilizzabile e comporre preventivi da esso; il cliente vede solo il totale accettato (`accepted_total`).
+
+## Key Decisions (LOCKED)
+
+### 1. Service Catalog — Location: /admin/catalog
+- Pagina dedicata `/admin/catalog` con link aggiunto in NavBar (Clienti | Statistiche | Catalogo).
+- Tabella con colonne: Nome, Descrizione, Prezzo unitario, Stato (Attivo/Disattivato).
+- CRUD completo: aggiungi, modifica inline, disattiva (soft delete via `active = false`).
+- Items disattivati restano visibili in elenco (filtro toggle) ma non appaiono nel selettore quote.
+
+### 2. Quote Builder — Location: Tab "Preventivo" in /admin/clients/[id]
+- Nuovo tab nell'admin client detail page, accanto a Fasi, Pagamenti, Documenti.
+- Mostra le voci preventivo del cliente con totale calcolato.
+- L'admin può aggiungere voci dal catalogo (dropdown con `active = true`) o voci libere (nome + prezzo custom).
+- Nessun blocco dopo la finalizzazione — voci sempre editabili.
+
+### 3. Voci Preventivo — Catalogo + Free-form
+- **Da catalogo**: seleziona voce, inserisce quantità; `unit_price` viene snapshotato al momento dell'aggiunta (non segue futuri cambi al catalogo).
+- **Voce libera**: nome testo libero, prezzo unitario, quantità. `service_id` sarà NULL in `quote_items`.
+
+  > **Schema change needed**: `service_id` in `quote_items` deve diventare nullable (attualmente `notNull()`).
+  > Aggiungere campo `custom_label text` a `quote_items` per le voci libere.
+
+### 4. Accepted Total — Admin-controlled, not auto-calculated
+- Il builder mostra la somma calcolata delle voci come riferimento.
+- Esiste un campo separato "Totale accettato dal cliente" (editable input) con pulsante "Salva".
+- Il pulsante scrive il valore (che l'admin può modificare liberamente) su `clients.accepted_total`.
+- **Rationale**: il cliente accetta una cifra commerciale (es. €1.500 tondo) che può differire dalla somma analitica interna. Il preventivo interno è solo uno strumento di stima.
+
+### 5. Pagamenti — Nessun aggiornamento automatico
+- Finalizzare il preventivo NON tocca i record `payments`.
+- L'admin aggiorna manualmente gli importi di acconto e saldo nella tab Pagamenti.
+
+### 6. Constraint già in vigore (IMMUTABLE)
+- `quote_items` non vengono mai esposti dalle API client-facing.
+- `clients.accepted_total` è l'unico valore economico che il cliente vede.
+
+## Schema Changes Required
+
+```sql
+-- quote_items.service_id diventa nullable
+ALTER TABLE quote_items ALTER COLUMN service_id DROP NOT NULL;
+
+-- aggiunta colonna per voci libere
+ALTER TABLE quote_items ADD COLUMN custom_label text;
+```
+
+In Drizzle schema.ts:
+```ts
+service_id: text("service_id").references(() => service_catalog.id, { onDelete: "restrict" }), // removed .notNull()
+custom_label: text("custom_label"), // new field
+```
+
+## Reusable Assets
+
+- `service_catalog` e `quote_items` tables già presenti in schema.ts con relazioni e TS types.
+- Pattern Server Actions già stabilito (vedi `clients/[id]/actions.ts`).
+- Pattern tab UI già stabilito (`tabs/PhasesTab.tsx`, `tabs/PaymentsTab.tsx`, etc.).
+- Pattern inline edit già stabilito (`DocumentRow.tsx`).
+- `fmtEur()` già definita in analytics/page.tsx — estrarre in lib/utils o duplicare.
+
+## Pages & Routes to Create
+
+| Route | Type | Purpose |
+|-------|------|---------|
+| `/admin/catalog` | Server Component page | Lista + CRUD catalogo servizi |
+| `/admin/catalog/actions.ts` | Server Actions | createService, updateService, toggleActive |
+| `src/components/admin/tabs/QuoteTab.tsx` | Client Component | Quote builder UI |
+| `src/app/admin/clients/[id]/quote-actions.ts` | Server Actions | addQuoteItem, removeQuoteItem, updateAcceptedTotal |
+
+## UI Notes
+
+- Stile coerente con tab esistenti (border-b tabs navigation nell'admin client page).
+- Catalogo: tabella simile a admin clients list (bg-white rounded-xl border border-[#e5e7eb]).
+- Quote builder: due colonne su desktop (catalogo disponibile | voci selezionate) o lista unica con selettore.
+- Totale calcolato mostrato in bold come sommario; campo `accepted_total` separato con label chiara.
+- Colore brand: #1A463C per accent, #DEF168 per highlight.