clienthub/.planning/phases/11-catalog-database-view-ux-legacy-consolidation/11-CONTEXT.md

# Phase 11: Catalog Database-View UX & Legacy Consolidation - Context

**Gathered:** 2026-06-13
**Status:** Ready for planning

<domain>
## Phase Boundary

Trasformare `/admin/catalog` (tabella `services`) in una vista database stile Notion/Airtable — inline edit su ogni cella, tag multi-select con creazione al volo, quick-add row, filtro/ricerca istantanei (client-side) — e consolidare i dati storici di `service_catalog` e `offer_services`/`offer_micro_services` dentro `services` in modo additivo, senza perdita (verificabile via conteggio righe).

**Esplicitamente FUORI scope per Phase 11** (deferiti a fasi successive, vedi `<deferred>`):
- Rewiring di `/admin/offers` e `OffersSection` (dashboard cliente) per leggere da `services` — Phase 12
- Composizione drag&drop offerte e import CSV — Phase 12
- Riuso del sistema tag per i lead — Phase 14 (schema pronto ora, UI lead dopo)

</domain>

<decisions>
## Implementation Decisions

### Consolidamento Legacy (service_catalog, offer_services)

- **D-01:** Migrazione **additiva** (pattern Phase 7): copia le righe di `service_catalog` e `offer_services` dentro `services`, popolando `migrated_from`/`migrated_id` per audit trail. **Zero behavior change** a `/admin/offers` e `OffersSection` — quelle UI restano sulle tabelle legacy (`offer_services`/`offer_micro_services`), che NON vengono toccate/droppate.
- **D-02:** Le righe migrate da `offer_services` ricevono automaticamente il tag **"Offerta"** (tag normale, vedi D-08) per distinguerle nella tabella unificata dai servizi a costo interno.
- **D-03:** `/admin/offers` resta **status quo** — continua a creare nuove voci in `offer_services`/`offer_micro_services` come oggi. Il rewiring per leggere/scrivere da `services` è Phase 12 (già dipende da "catalogo unificato e tabellare").
- **D-04:** Verifica "senza perdita" (OFFER-13, conteggio righe) tramite **script/log one-shot** durante la migrazione (come Phase 7) — nessun indicatore permanente in `/admin/catalog`.

### Sistema Tag

- **D-05:** Nuova tabella `tags` + junction **polimorfica** (`entity_type` + `entity_id`, pattern simile a `comments` in `src/db/schema.ts`) — costruita ora per essere riusata da Phase 14 (CRM-09, tag sui lead) senza rifare lo schema.
- **D-06:** Pool di tag **scoped per `entity_type`** — i tag del catalogo (`services`) e i tag dei lead (futuro) sono pool separati, anche se condividono la tabella `tags`. Il dropdown "+" per creare/assegnare un tag mostra solo i tag dell'entity_type corrente.
- **D-07:** Colore badge **derivato deterministicamente** dal nome del tag (hash → palette fissa 6-8 colori pastello, da `.planning/DESIGN-SYSTEM.md`) — **nessuna colonna `color`** in `tags`.
- **D-08:** Il tag "Offerta" (D-02) è un **tag normale** del pool `services` — rinominabile/eliminabile dall'utente come ogni altro tag, nessuna logica di protezione/system-tag.

### Campo `category`

- **D-09:** `services.category` (testo libero, esistente) **resta un campo separato**, accanto ai tag multi-select — due dimensioni di classificazione indipendenti (categoria primaria + tag flessibili). NON viene migrato/fuso nei tag.
- **D-10:** Servizi senza `category` restano senza tag corrispondente — nessun tag di default ("Senza categoria"/"Generale") viene creato.

### Tabella database-view — colonne e comportamenti

- **D-11:** "Descrizione" resta una **colonna piena** della tabella — testo troncato con ellipsis, click-to-edit inline (textarea espansa al click), stesso pattern `EditableCell` delle altre colonne. Non esce dalla riga principale.
- **D-12:** Quick-add row (OFFER-09, "nome + invio"): scrivere solo il nome e premere invio crea il servizio con `unit_price = 0`. La riga diventa immediatamente una riga normale ed editabile — il prezzo (mostrato "€0,00") si corregge inline subito dopo, click sulla cella prezzo.
- **D-13:** Servizi disattivati (`active=false`): restano **visibili, attenuati** (opacità ridotta, comportamento attuale di `ServiceTable.tsx`), ma **ordinati in fondo alla tabella** sotto una riga divisoria che li separa visivamente dai servizi attivi.
- **D-14:** **Nessuna colonna "azioni"** per riga. Lo stato attivo/disattivo diventa una **cella inline** (toggle/checkbox cliccabile, stesso pattern EditableCell). Tutte le modifiche avvengono via click-to-edit sulle celle — stile Notion/Airtable puro, zero bottoni per riga.

### Claude's Discretion

- Implementazione esatta dei componenti `EditableCell` e `TagMultiSelect` (entrambi previsti in `.planning/DESIGN-SYSTEM.md`, non ancora costruiti — `command`/`popover` shadcn da valutare).
- Mapping esatto dei campi nella migrazione `offer_services` → `services` (es. `price` → `unit_price`, `transformation_description` → `description`).
- Verifica del JOIN `quote_items` ↔ `service_catalog` in `src/lib/admin-queries.ts` (righe 335/343, 531/539) — oggi l'unico consumer rimasto di `service_catalog`, possibile disallineamento con `quote_items.service_id` (che secondo `schema.ts` referenzia `services.id`, non `service_catalog.id`). Il researcher deve verificare se il join è ancora funzionante; se rotto, trattarlo come bugfix separato e a basso rischio, **non bloccante** per i success criteria di Phase 11.
- Palette colori esatta per i badge tag (6-8 pastello, da DESIGN-SYSTEM.md) e algoritmo hash nome→colore.
- Posizionamento/stile esatto della riga divisoria "inattivi" (D-13).

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Requisiti e roadmap
- `.planning/REQUIREMENTS.md` — sezione "Offer Studio — Catalogo & Offerte (v1)": OFFER-07, OFFER-08, OFFER-09, OFFER-10, OFFER-13 sono i requisiti di questa fase
- `.planning/ROADMAP.md` — sezione "Phase 11: Catalog Database-View UX & Legacy Consolidation" per goal e success criteria

### Design contract (UI)
- `.planning/DESIGN-SYSTEM.md` — **vincolante**: direzione ClickUp/Pipedrive flat, token brand invariati (`#1A463C`/`#DEF168`/`#e5e7eb`/etc.), pattern tabella (riga ~40px, inline edit con `ring-1 ring-primary`, badge tag a rotazione colori, quick-add row, header sticky), componenti da costruire (`EditableCell`, `TagMultiSelect`), checklist pre-delivery (contrasto, focus ring, transizioni 150-250ms, responsive)

### Decisioni di progetto
- `.planning/PROJECT.md` — sezione "Key Decisions": ordine Offer Studio→Proposal AI, "Catalogo/Offerte UX = database view custom (non Notion-clone)", catalogo unificato `services` da Phase 7

No external specs beyond questi — requisiti/decisioni catturati sopra.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `src/components/ui/badge.tsx`, `select.tsx`, `input.tsx`, `table.tsx` — base per costruire `EditableCell` e `TagMultiSelect` (DESIGN-SYSTEM.md)
- `src/lib/admin-queries.ts` → `getAllServices()` — query layer esistente su `services`, da estendere con join sulla nuova tabella `tags`
- `src/db/schema.ts` → `comments` table (polimorfico `entity_type`/`entity_id`) — precedente diretto per la junction `tags` (D-05)
- `src/db/schema.ts` → `services.migrated_from`/`migrated_id` (Phase 7) — pattern di audit trail da riusare per la migrazione `service_catalog`/`offer_services` → `services`

### Established Patterns
- `src/app/admin/catalog/actions.ts` (`createService`/`updateService`/`toggleServiceActive`) — pattern `requireAdmin()` + validazione zod + `revalidatePath("/admin/catalog")`, da estendere per inline edit (probabilmente una action per campo o un'action generica `updateServiceField`)
- Migrations manuali via SSH+docker exec, applicate a prod PRIMA del push del codice dipendente (vedi `.planning/HANDOFF.md`)

### Integration Points
- `src/app/admin/catalog/page.tsx` → `ServiceTable`/`ServiceForm` (`src/components/admin/catalog/`) — punto di sostituzione principale per la nuova tabella database-view
- `offer_phase_services` (Phase 8, già esistente) collega `offer_phases` ↔ `services` — riferimento utile per Phase 12 quando comporrà offerte direttamente da `services`
- `src/lib/admin-queries.ts` righe ~250-345 e ~520-545 — JOIN legacy su `service_catalog` per label `quote_items` (vedi Claude's Discretion)

### Tabelle legacy coinvolte (stato attuale)
- `service_catalog` (`src/db/schema.ts:170`) — solo consumer rimasto: JOIN per label `quote_items` legacy in `admin-queries.ts`
- `offer_services` + `offer_micro_services` (`src/db/schema.ts:259-283`) — ATTIVI: usati da `/admin/offers` (`src/app/admin/offers/`, `src/lib/offer-queries.ts`) e da `OffersSection` lato cliente (`src/lib/client-view.ts`, cumulative_price)

</code_context>

<specifics>
## Specific Ideas

- "compartimenti stagni" + Data Safety LOCKED (CLAUDE.md) → ogni migrazione di questa fase è additiva, nessun drop/truncate di `service_catalog`, `offer_services`, `offer_micro_services`
- DESIGN-SYSTEM.md è stato prodotto appositamente per questa fase (e per 12-14) via skill `ui-ux-pro-max` — è il contratto visivo, non solo un suggerimento

</specifics>

<deferred>
## Deferred Ideas

- **Rewiring completo di `/admin/offers` + `OffersSection`** per leggere/scrivere da `services` (invece di `offer_services`/`offer_micro_services`) → **Phase 12** (Offer Composition Drag&Drop & CSV Import), che già dipende dal "catalogo unificato e tabellare" prodotto da questa fase
- **Riuso della tabella `tags`/junction polimorfica per i lead** (CRM-09) → **Phase 14** (CRM Attio-style & Fix) — schema già pronto (D-05/D-06), serve solo la UI lato lead
- **Fix del JOIN `quote_items` ↔ `service_catalog`** se il researcher lo trova rotto → bugfix separato, non parte dei success criteria di Phase 11

None — discussion stayed within phase scope (oltre ai punti sopra, già tracciati per fasi specifiche).

</deferred>

---

*Phase: 11-catalog-database-view-ux-legacy-consolidation*
*Context gathered: 2026-06-13*