---
phase: "03"
plan: "03"
subsystem: "quote-builder"
tags: [quote, admin, server-actions, drizzle, security]
dependency_graph:
  requires: ["03-01"]
  provides: ["quote-tab-ui", "quote-actions", "admin-quote-queries"]
  affects: ["src/lib/admin-queries.ts", "src/app/admin/clients/[id]/page.tsx"]
tech_stack:
  added: []
  patterns: ["Server Actions with requireAdmin guard", "useTransition for optimistic UI", "COALESCE SQL for label resolution", "leftJoin for optional catalog ref"]
key_files:
  created:
    - src/app/admin/clients/[id]/quote-actions.ts
    - src/components/admin/tabs/QuoteTab.tsx
  modified:
    - src/lib/admin-queries.ts
    - src/app/admin/clients/[id]/page.tsx
decisions:
  - "QuoteTab is a Client Component (useTransition + useRouter) — actions called via startTransition, router.refresh() for revalidation"
  - "updateAcceptedTotal in quote-actions.ts is separate from the one in actions.ts — scoped to quote tab, adds requireAdmin guard"
  - "Service price pre-filled in catalog mode but editable — allows overriding price at quote time (snapshot semantics)"
metrics:
  duration: "~15 min"
  completed_date: "2026-05-17T09:45:11Z"
  tasks_completed: 2
  tasks_total: 2
  files_created: 2
  files_modified: 2
---

# Phase 03 Plan 03: Quote Builder Tab Summary

**One-liner:** Admin quote builder tab with catalog dropdown, freeform toggle, items table with calculated total, and accepted_total editor — all backed by Zod-validated Server Actions with requireAdmin guard.

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Server Actions + extend getClientFullDetail | db81829 | quote-actions.ts, admin-queries.ts |
| 2 | QuoteTab component + wire into client detail page | 48f81e7 | QuoteTab.tsx, page.tsx |

## What Was Built

**Task 1 — Server Actions + Query Layer**

- `src/app/admin/clients/[id]/quote-actions.ts`: Three Server Actions exported:
  - `addQuoteItem(clientId, formData)` — Zod validates service_id/custom_label, quantity, unit_price; computes subtotal; inserts into `quote_items`
  - `removeQuoteItem(quoteItemId, clientId)` — deletes by item ID
  - `updateAcceptedTotal(clientId, formData)` — writes to `clients.accepted_total` only (no payment row splitting — that stays in `actions.ts`)
  - All three call `requireAdmin()` (getServerSession check) before any DB operation
- `src/lib/admin-queries.ts`:
  - Added `QuoteItemWithLabel` type (COALESCE resolved label, snapshotted unit_price)
  - Extended `ClientFullDetail` with `quoteItems: QuoteItemWithLabel[]` and `activeServices: ServiceCatalog[]`
  - Added two queries in `getClientFullDetail()`: leftJoin for quote items with COALESCE label; active services ordered by name
  - Security comment enforces that `client-view.ts` must never query `quote_items` (verified: 0 functional references)

**Task 2 — UI Component + Page Wiring**

- `src/components/admin/tabs/QuoteTab.tsx` (`"use client"`) — three sections:
  - **Add items**: catalog dropdown (pre-fills unit_price on selection, editable) + freeform toggle (custom_label + price + qty)
  - **Items table**: label, qty, unit_price, subtotal columns; "Rimuovi" button per row; "Totale calcolato" in bold footer
  - **Accepted total**: editable numeric input with "Salva" button + helper text clarifying client sees only this value
- `src/app/admin/clients/[id]/page.tsx`:
  - Import `QuoteTab`
  - Destructure `quoteItems`, `activeServices` from `getClientFullDetail` result
  - Added 5th `TabsTrigger value="quote"` with label "Preventivo"
  - Added 5th `TabsContent value="quote"` rendering `<QuoteTab>`

## Security Verification

| Constraint | Status |
|------------|--------|
| T-03-03-01: requireAdmin on all Server Actions | Done — all three actions call `await requireAdmin()` first |
| T-03-03-02: Zod validation on formData numbers | Done — `quoteItemSchema` validates quantity + unit_price as `z.coerce.number().min(0.01)` |
| T-03-03-03: quote_items not in client-facing routes | Done — client-view.ts has 0 functional references to quote_items (only comments) |
| T-03-03-04: IDOR on removeQuoteItem | Mitigated by requireAdmin; future multi-admin scenario noted for future hardening |
| T-03-03-05: XSS in custom_label | Accepted — React JSX auto-escapes, no dangerouslySetInnerHTML used |
| T-03-03-06: calculated_total vs accepted_total confusion | Accepted — visual design enforces separation |

## Deviations from Plan

**1. [Rule 3 - Blocking] Build required DATABASE_URL env var not present in worktree**
- **Found during:** Task 2 build verification
- **Issue:** Worktree has no `.env.local`; build fails with "DATABASE_URL env var is required" at runtime collection phase
- **Fix:** Ran build with `DATABASE_URL=$(grep DATABASE_URL /path/.env.local ...)` from main repo — build passed clean
- **Impact:** None on code quality; worktree environment limitation only

**2. [Rule 1 - Architecture] updateAcceptedTotal in quote-actions.ts does NOT update payment rows**
- **Found during:** Task 1 implementation
- **Rationale:** The existing `updateAcceptedTotal` in `actions.ts` splits the total 50/50 between payment rows. The quote tab version intentionally only writes to `clients.accepted_total` — this is the quote builder's domain. Payment row updates remain in the payments tab action. This preserves clean separation of concerns.

## Known Stubs

None — all three sections are fully wired to real Server Actions and real DB queries.

## Threat Flags

None — all new surface is admin-only, guarded by `requireAdmin()`, and consistent with the plan's threat model.

## Self-Check: PASSED

- `src/app/admin/clients/[id]/quote-actions.ts` exists and exports 3 Server Actions
- `src/components/admin/tabs/QuoteTab.tsx` exists and exports QuoteTab
- `src/lib/admin-queries.ts` modified with QuoteItemWithLabel type + quoteItems/activeServices in return
- `src/app/admin/clients/[id]/page.tsx` modified with Preventivo tab
- Commits db81829 and 48f81e7 verified in git log
- TypeScript: no errors
- Build: passes (with DATABASE_URL)
- client-view.ts: 0 functional references to quote_items