docs(planning): v2.1 milestone setup + Phase 11 context/patterns
- Archive v2.0 phases (07-10) under .planning/milestones/ - v2.1 REQUIREMENTS/ROADMAP (Phases 11-17: Offer Studio + Proposal AI) - DESIGN-SYSTEM.md (database-view UI contract for Phases 11-14) - Phase 11 CONTEXT, DISCUSSION-LOG, PATTERNS Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,122 @@
|
||||
# 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*
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
# Phase 11: Catalog Database-View UX & Legacy Consolidation - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-06-13
|
||||
**Phase:** 11-catalog-database-view-ux-legacy-consolidation
|
||||
**Areas discussed:** Consolidamento offer_services — portata, Architettura sistema tag, Destino del campo 'category', Tabella database-view — colonne e comportamenti
|
||||
|
||||
---
|
||||
|
||||
## Consolidamento offer_services — portata
|
||||
|
||||
Investigazione preliminare: `offer_services`/`offer_micro_services` non sono solo "legacy morti" — alimentano attivamente `/admin/offers` e la sezione `OffersSection` lato cliente (prezzo cumulativo). Questo ha cambiato la portata della domanda rispetto all'assunzione iniziale ("consolidamento semplice").
|
||||
|
||||
### Portata del consolidamento
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Solo copia dati (audit trail) | Migrazione additiva: copia righe in `services` con `migrated_from`/`migrated_id` (pattern Phase 7), zero behavior change a `/admin/offers` e `OffersSection` | ✓ |
|
||||
| Rewiring completo | `/admin/offers` e `OffersSection` leggono/scrivono direttamente da `services` in questa fase | |
|
||||
|
||||
**User's choice:** Solo copia dati (audit trail)
|
||||
**Notes:** Coerente con Data Safety LOCKED + "compartimenti stagni" + lezione Phase 10 (crash da disallineamento sorgenti dati). Il rewiring completo è deferito a Phase 12.
|
||||
|
||||
### Tag automatico, status quo /admin/offers, verifica migrazione (batch di 3 domande)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Sì, tag automatico | Le righe migrate da `offer_services` ricevono il tag "Offerta" per distinguerle nel catalogo unificato | ✓ |
|
||||
| No tag | Nessuna marcatura delle righe migrate da `offer_services` | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Status quo (legacy) | `/admin/offers` continua a scrivere in `offer_services`/`offer_micro_services` come oggi | ✓ |
|
||||
| Rewire subito | `/admin/offers` viene aggiornato in questa fase per usare `services` | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Solo verifica one-shot | Conteggio righe via script/log durante la migrazione (come Phase 7), nessun indicatore permanente | ✓ |
|
||||
| Badge UI permanente | Indicatore visibile in `/admin/catalog` che mostra lo stato della migrazione | |
|
||||
|
||||
**User's choice:** Tag automatico "Offerta" + status quo su `/admin/offers` + verifica one-shot
|
||||
**Notes:** Il tag "Offerta" sarà un tag normale del pool (vedi area successiva), non un marcatore di sistema.
|
||||
|
||||
---
|
||||
|
||||
## Architettura sistema tag
|
||||
|
||||
Investigazione preliminare: OFFER-08 (Phase 11, tag catalogo) e CRM-09 (Phase 14, tag lead) richiedono entrambi "tag multi-select con creazione al volo". La tabella `comments` (`entity_type`/`entity_id` polimorfico) è un precedente diretto per una junction riusabile.
|
||||
|
||||
### Tabella tags condivisa ora vs solo catalogo
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Condiviso ora (tags + junction polimorfica) | Nuova tabella `tags` + junction `entity_type`/`entity_id` (pattern `comments`), riusabile da Phase 14 senza rifare lo schema | ✓ |
|
||||
| Solo catalogo | Tabella `service_tags` dedicata, da generalizzare eventualmente in Phase 14 | |
|
||||
|
||||
**User's choice:** Condiviso ora (tags + junction polimorfica)
|
||||
**Notes:** Build-once-reuse-later — schema pronto ora, UI lead arriva in Phase 14.
|
||||
|
||||
### Namespace tag, colore badge, protezione tag "Offerta" (batch di 3 domande)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Scoped per entity_type | I tag del catalogo (`services`) e i tag dei lead (futuro) sono pool separati, anche su tabella `tags` condivisa | ✓ |
|
||||
| Pool globale unico | Tutti i tag condivisi tra tutte le entity_type, nessuna separazione | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Derivato dal nome (no DB) | Colore badge calcolato via hash nome→palette fissa (6-8 colori pastello da DESIGN-SYSTEM.md), nessuna colonna `color` | ✓ |
|
||||
| Colonna color in tags | Colore scelto/salvato esplicitamente per ogni tag | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Tag normale | Il tag "Offerta" (auto-applicato alle righe migrate) è un tag normale del pool, rinominabile/eliminabile come ogni altro | ✓ |
|
||||
| Tag protetto/system | Il tag "Offerta" non può essere rinominato/eliminato dall'utente | |
|
||||
|
||||
**User's choice:** Scoped per entity_type + colore derivato dal nome + tag "Offerta" normale
|
||||
**Notes:** Nessuna colonna extra su `tags` oltre a nome/entity_type — palette e hashing sono dettagli di implementazione (Claude's Discretion).
|
||||
|
||||
---
|
||||
|
||||
## Destino del campo 'category'
|
||||
|
||||
### Relazione tra category e tags
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Campo separato | `services.category` resta testo libero indipendente, accanto ai tag multi-select — due dimensioni di classificazione | ✓ |
|
||||
| Migrato/fuso nei tag | `category` viene convertito in tag e la colonna rimossa | |
|
||||
|
||||
**User's choice:** Campo separato
|
||||
**Notes:** Categoria primaria + tag flessibili sono concetti distinti, entrambi utili nella tabella.
|
||||
|
||||
### Servizi senza category
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Nessun tag di default | Servizi senza `category` restano senza tag corrispondente | ✓ |
|
||||
| Tag automatico "Senza categoria"/"Generale" | Creato e applicato automaticamente ai servizi senza categoria | |
|
||||
|
||||
**User's choice:** Nessun tag di default
|
||||
**Notes:** Evita di popolare il pool tag con un tag "rumore" che non aggiunge informazione.
|
||||
|
||||
---
|
||||
|
||||
## Tabella database-view — colonne e comportamenti
|
||||
|
||||
### Colonna "Descrizione"
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Colonna piena, click-to-edit inline | Testo troncato con ellipsis, click espande in textarea inline, stesso pattern `EditableCell` delle altre colonne | ✓ |
|
||||
| Spostata fuori riga | Descrizione visibile solo in un dettaglio/modal separato | |
|
||||
|
||||
**User's choice:** Colonna piena, click-to-edit inline
|
||||
**Notes:** Coerente con lo stile Notion/Airtable — nessuna riga secondaria o modal.
|
||||
|
||||
### Quick-add row (OFFER-09)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Nome + invio → riga editabile con prezzo €0,00 | Scrivere solo il nome e premere invio crea il servizio con `unit_price = 0`; la riga diventa subito normale ed editabile, prezzo corretto inline dopo | ✓ |
|
||||
| Form esteso prima del salvataggio | La quick-add row richiede tutti i campi minimi prima di creare la riga | |
|
||||
|
||||
**User's choice:** Nome + invio → riga editabile con prezzo €0,00
|
||||
**Notes:** Minimizza l'attrito di inserimento, coerente con "no modali".
|
||||
|
||||
### Servizi disattivati (active=false)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Visibili attenuati, in fondo sotto divisore | Restano nella tabella con opacità ridotta (comportamento attuale), ma ordinati sotto una riga divisoria che li separa dai servizi attivi | ✓ |
|
||||
| Nascosti di default con filtro toggle | Non mostrati a meno che l'utente non attivi un filtro "mostra inattivi" | |
|
||||
|
||||
**User's choice:** Visibili attenuati, in fondo sotto divisore
|
||||
**Notes:** Mantiene visibilità storica senza nascondere dati, separazione visiva chiara.
|
||||
|
||||
### Colonna "azioni"
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Nessuna colonna azioni — stato come cella inline | Attivo/disattivo diventa toggle/checkbox cliccabile inline; tutte le modifiche via click-to-edit, zero bottoni per riga | ✓ |
|
||||
| Colonna azioni con bottoni | Bottoni espliciti (edit/toggle/elimina) per riga | |
|
||||
|
||||
**User's choice:** Nessuna colonna azioni — stato come cella inline
|
||||
**Notes:** Stile Notion/Airtable puro, coerente con DESIGN-SYSTEM.md (nessuna "azione riga-per-riga" salvo bulk in Phase 12+).
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Implementazione esatta dei componenti `EditableCell` e `TagMultiSelect` (DESIGN-SYSTEM.md ne definisce il comportamento, non il codice)
|
||||
- Mapping esatto dei campi nella migrazione `offer_services` → `services` (`price`→`unit_price`, `transformation_description`→`description`)
|
||||
- Verifica/eventuale fix del JOIN `quote_items` ↔ `service_catalog` in `admin-queries.ts` — flag per il researcher, non bloccante
|
||||
- Palette colori esatta (6-8 pastello) e algoritmo hash nome→colore per i badge tag
|
||||
- Posizionamento/stile esatto del divisore "inattivi"
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Rewiring completo di `/admin/offers` + `OffersSection` per leggere da `services` → Phase 12
|
||||
- Riuso della tabella `tags`/junction polimorfica per i lead (CRM-09) → Phase 14
|
||||
- Fix del JOIN `quote_items` ↔ `service_catalog` se risulta rotto → bugfix separato, non Phase 11
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user