Compare commits
47 Commits
5177a3700a
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 simone
|
9ce6f02ee4 | ||
|
simone
|
614eb00040 | ||
|
simone
|
d71fede4e4 | ||
|
simone
|
41530b556a | ||
|
simone
|
817a8cd5d1 | ||
|
simone
|
bec7e039d7 | ||
|
simone
|
4403b39e63 | ||
|
simone
|
fe767899b9 | ||
|
simone
|
15b01e3e05 | ||
|
simone
|
8b54f48afd | ||
|
simone
|
2e9bd2ab60 | ||
|
simone
|
c3d2afa61f | ||
|
simone
|
94f4a54248 | ||
|
simone
|
0d7186ba03 | ||
|
simone
|
ac74a81a72 | ||
|
simone
|
53f1758f52 | ||
|
simone
|
d14f95c80d | ||
|
simone
|
44be190631 | ||
|
simone
|
7e58031528 | ||
|
simone
|
4666fc4058 | ||
|
simone
|
c9855d58ce | ||
|
simone
|
4e3907d382 | ||
|
simone
|
1fa8e1ab5e | ||
|
simone
|
b49d4bfaaa | ||
|
simone
|
df4671236a | ||
|
simone
|
330749a883 | ||
|
simone
|
9a57e450fc | ||
|
simone
|
5547e555bd | ||
|
simone
|
3fcb10dac6 | ||
|
simone
|
97cc6460a0 | ||
|
simone
|
19ed377214 | ||
|
simone
|
d6d3be00f4 | ||
|
simone
|
8f2b3255ab | ||
|
simone
|
1115bb2265 | ||
|
simone
|
d6e95ef66a | ||
|
simone
|
a9358da96f | ||
|
simone
|
4b135ce67f | ||
|
simone
|
571f58bff8 | ||
|
simone
|
8000d562dc | ||
|
simone
|
24213e7251 | ||
|
simone
|
08b0a60bae | ||
|
simone
|
31237da11c | ||
|
simone
|
ee47f35e97 | ||
|
simone
|
0aad9caf46 | ||
|
simone
|
f7eb7eec23 | ||
|
simone
|
187550fedf | ||
|
simone
|
09a5b1ff4f |
@@ -0,0 +1,77 @@
|
||||
# `.claude/` — la cartella di configurazione di ClientHub
|
||||
|
||||
Questo file si carica quando si lavora **dentro `.claude/`**. Spiega cosa va dove, e basta.
|
||||
|
||||
**Per il progetto comanda [`../CLAUDE.md`](../CLAUDE.md)**: stack, vincoli LOCKED, procedura
|
||||
di deploy, accesso al DB, design system. Qui non si duplica niente di quello — una seconda
|
||||
copia è il modo più veloce per averne due che si contraddicono.
|
||||
|
||||
## Cosa va in ogni cartella
|
||||
|
||||
| Cartella | Cosa ci va | Cosa **non** ci va |
|
||||
|---|---|---|
|
||||
| `rules/` | Regole caricate per contesto. Oggi: `memory-discipline.md`, importata da `../CLAUDE.md` | Documentazione di feature — quella sta in `STATUS.md` |
|
||||
| `skills/` | **Solo** skill specifiche di ClientHub: `preventivo/`, `audit/` | Le skill globali (`/seo-audit`, `/copywriting`, `/docx`…) — stanno in `~/.claude/skills/` |
|
||||
| `agents/` | **Solo** agenti specifici di ClientHub. Oggi vuota: quello dell'audit nasce col motore | I 18 agenti globali di `~/.claude/agents/` |
|
||||
| `hooks/` | Script eseguibili richiamati da `settings.json` | Logica di prodotto |
|
||||
| `plans/` | I piani delle milestone, versionati | Piani usa-e-getta di una singola sessione |
|
||||
| `commands/`, `workflows/`, `projects/` | Vuote per ora, sono lo scheletro | — |
|
||||
| `memory/` | Appunti di lavoro versionati nel repo | **La memoria persistente. Non è qui** → vedi sotto |
|
||||
| `worktrees/` | Generata dagli strumenti | — |
|
||||
|
||||
### Agenti e skill globali non si copiano qui
|
||||
|
||||
Regola già fissata in [`../../CLAUDE.md`](../../CLAUDE.md): agenti e skill che valgono per
|
||||
tutti i progetti vivono in `~/.claude/` e si invocano da qualunque cartella. Copiarne uno qui
|
||||
crea due file destinati a divergere, e il primo a cambiare vince a caso.
|
||||
|
||||
In locale ci va solo ciò che **senza questo repo non ha senso**: le due skill qui sotto.
|
||||
|
||||
### `.claude/memory/` ≠ memoria persistente
|
||||
|
||||
Due posti diversi con lo stesso nome, e confonderli fa perdere il lavoro:
|
||||
|
||||
- **`.claude/memory/`** (questa cartella) — appunti versionati nel repo, li vede chiunque
|
||||
faccia clone.
|
||||
- **`~/.claude/projects/-Users-simonecavalli-Vault-IAMCAVALLI-hub/memory/`** — la memoria
|
||||
persistente vera, un file per fatto più `MEMORY.md` come indice. Sta fuori dal repo, non
|
||||
si committa, e viene iniettata in automatico a inizio sessione.
|
||||
|
||||
Ci va quello che **non si deduce dal repo**: perché una decisione è stata presa, un vincolo
|
||||
operativo, una cosa provata che non funziona. Regole complete in
|
||||
[`rules/memory-discipline.md`](rules/memory-discipline.md).
|
||||
|
||||
## Le skill del progetto
|
||||
|
||||
- **`/preventivo`** — l'attrezzo per lavorare sulla pipeline che genera i preventivi
|
||||
(`src/lib/proposal/`) senza romperla. Non contiene un prompt di generazione: quello vive
|
||||
in `agent.ts` ed è l'unico.
|
||||
- **`/audit`** — fa girare le cinque fonti di `src/lib/audit/sources/` su un URL e dice cosa
|
||||
è stato **misurato** e cosa no. Le fonti sono in produzione ma inerti: nessuna route le
|
||||
chiama ancora.
|
||||
|
||||
## Gli hook attivi
|
||||
|
||||
Tutti e tre in [`settings.json`](settings.json). Si provano a mano prima di fidarsi.
|
||||
|
||||
| Hook | Quando | Cosa fa |
|
||||
|---|---|---|
|
||||
| Promemoria memoria | `Stop` | Se `src/` o `.planning/` hanno modifiche non committate, ricorda di aggiornare `STATE.md`. Non blocca |
|
||||
| [`guardia-migration.sh`](hooks/guardia-migration.sh) | `PreToolUse` su Write/Edit in `src/db/migrations/` | **Blocca** l'SQL che cancella dati dalle entità protette (`clients`, `projects`, `payments`, `phases`). È il vincolo Data Safety LOCKED fatto rispettare dalla macchina |
|
||||
| [`guardia-token.sh`](hooks/guardia-token.sh) | `PostToolUse` su `.tsx`/`.css` | **Avvisa** se compaiono classi Tailwind grezze o hex letterali. Non blocca: le eccezioni sanzionate esistono e stanno nella whitelist dello script |
|
||||
|
||||
Per provarli senza passare da Claude:
|
||||
|
||||
```bash
|
||||
echo '{"tool_input":{"file_path":"src/db/migrations/9999_x.sql","content":"DROP TABLE payments;"}}' \
|
||||
| .claude/hooks/guardia-migration.sh; echo "exit=$?" # atteso: 2
|
||||
|
||||
echo '{"tool_input":{"file_path":"src/x.tsx","content":"<div className=\"bg-slate-100\"/>"}}' \
|
||||
| .claude/hooks/guardia-token.sh; echo "exit=$?" # atteso: 0 + avviso
|
||||
```
|
||||
|
||||
## I piani
|
||||
|
||||
`plans/` contiene i piani della milestone v2.5, portati dentro il repo il 2026-08-26 perché
|
||||
stavano solo in `~/.claude/plans/` e `STATE.md` avvertiva che senza quelli la milestone non
|
||||
era ricostruibile. Dettaglio in [`plans/README.md`](plans/README.md).
|
||||
Executable
+61
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env bash
|
||||
# PreToolUse su Write/Edit — vincolo Data Safety (LOCKED) di ../../CLAUDE.md.
|
||||
#
|
||||
# Blocca la scrittura di una migration che cancella dati dalle entita' protette.
|
||||
# Non e' una prova: e' una rete. Un DROP scritto in modo esotico puo' passare —
|
||||
# la revisione a occhio dell'SQL resta obbligatoria.
|
||||
#
|
||||
# exit 0 = passa · exit 2 = bloccato, il messaggio su stderr torna a Claude.
|
||||
set -uo pipefail
|
||||
|
||||
INPUT=$(cat)
|
||||
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
|
||||
|
||||
# Fuori da src/db/migrations/ questo hook non ha voce in capitolo.
|
||||
case "$FILE" in
|
||||
*src/db/migrations/*) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
# Write porta `content`, Edit porta `new_string`. MultiEdit porta un array.
|
||||
SQL=$(printf '%s' "$INPUT" | jq -r '
|
||||
[ .tool_input.content?,
|
||||
.tool_input.new_string?,
|
||||
(.tool_input.edits? // [] | .[].new_string?)
|
||||
] | map(select(. != null)) | join("\n")
|
||||
')
|
||||
[ -z "$SQL" ] && exit 0
|
||||
|
||||
PROTETTE='clients|projects|payments|phases'
|
||||
|
||||
# Via i commenti, tutto minuscolo, una riga per statement: cosi' "DROP" e il nome
|
||||
# della tabella devono stare nella STESSA istruzione per far scattare il blocco.
|
||||
PULITO=$(printf '%s' "$SQL" \
|
||||
| sed -E 's/--.*$//' \
|
||||
| tr '\n' ' ' \
|
||||
| sed -E 's;/\*[^*]*\*+([^/*][^*]*\*+)*/; ;g' \
|
||||
| tr '[:upper:]' '[:lower:]' \
|
||||
| tr ';' '\n')
|
||||
|
||||
COLPEVOLI=$(printf '%s\n' "$PULITO" \
|
||||
| grep -E 'drop[[:space:]]+table|drop[[:space:]]+column|truncate|delete[[:space:]]+from' \
|
||||
| grep -E "\\b($PROTETTE)\\b" || true)
|
||||
|
||||
if [ -n "$COLPEVOLI" ]; then
|
||||
{
|
||||
echo "BLOCCATO — Data Safety (LOCKED, ../CLAUDE.md)."
|
||||
echo
|
||||
echo "Questa migration cancella dati da un'entita' protetta (clients, projects,"
|
||||
echo "payments, phases). Le migration sono additive: si aggiungono colonne e"
|
||||
echo "tabelle, non si tolgono righe."
|
||||
echo
|
||||
echo "Istruzioni incriminate:"
|
||||
printf '%s\n' "$COLPEVOLI" | sed 's/^[[:space:]]*/ · /'
|
||||
echo
|
||||
echo "Se la rimozione serve davvero, e' una decisione da confermare a voce con"
|
||||
echo "l'utente prima di scriverla — non da aggirare qui."
|
||||
} >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
exit 0
|
||||
Executable
+59
@@ -0,0 +1,59 @@
|
||||
#!/usr/bin/env bash
|
||||
# PostToolUse su .tsx/.css — regola cardinale del design system:
|
||||
# solo token semantici (bg-card, text-muted-foreground, border-border).
|
||||
#
|
||||
# AVVISA, non blocca: le eccezioni sanzionate esistono (vedi WHITELIST) e il
|
||||
# debito storico e' gia' di ~450 occorrenze. Bloccare renderebbe l'hook un
|
||||
# ostacolo da disattivare invece di un promemoria da leggere.
|
||||
#
|
||||
# exit 0 sempre. Il messaggio su stderr arriva a Claude come contesto.
|
||||
set -uo pipefail
|
||||
|
||||
INPUT=$(cat)
|
||||
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
|
||||
|
||||
case "$FILE" in
|
||||
*.tsx|*.css) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
|
||||
# Eccezioni sanzionate da ../CLAUDE.md § Design System:
|
||||
# - StatusBadge: i colori di stato usano la palette con variante dark: esplicita
|
||||
# - AdminShell: il verde brand della sidebar
|
||||
# - mailer.ts / .html: l'HTML delle email non puo' usare variabili CSS
|
||||
# - globals.css: e' il posto dove i token vengono *definiti*
|
||||
# - design-reference/: i mock precedono la regola, si traducono non si copiano
|
||||
case "$FILE" in
|
||||
*StatusBadge*|*AdminShell*|*mailer*|*globals.css|*design-reference/*) exit 0 ;;
|
||||
esac
|
||||
|
||||
TESTO=$(printf '%s' "$INPUT" | jq -r '
|
||||
[ .tool_input.content?,
|
||||
.tool_input.new_string?,
|
||||
(.tool_input.edits? // [] | .[].new_string?)
|
||||
] | map(select(. != null)) | join("\n")
|
||||
')
|
||||
[ -z "$TESTO" ] && exit 0
|
||||
|
||||
PALETTE='slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose'
|
||||
GREZZE=$(printf '%s\n' "$TESTO" \
|
||||
| grep -oE "\\b(bg|text|border|ring|from|to|via|fill|stroke|divide|outline|shadow|accent|decoration|placeholder)-($PALETTE)-[0-9]{2,3}\\b" \
|
||||
| sort -u | head -12 || true)
|
||||
HEX=$(printf '%s\n' "$TESTO" \
|
||||
| grep -oE '#[0-9a-fA-F]{3,8}\b' | sort -u | head -6 || true)
|
||||
|
||||
if [ -n "$GREZZE" ] || [ -n "$HEX" ]; then
|
||||
{
|
||||
echo "AVVISO design system — token semantici, non palette grezza."
|
||||
echo "File: $FILE"
|
||||
[ -n "$GREZZE" ] && { echo " classi grezze: $(printf '%s ' $GREZZE)"; }
|
||||
[ -n "$HEX" ] && { echo " hex letterali: $(printf '%s ' $HEX)"; }
|
||||
echo
|
||||
echo "Usa bg-card / text-muted-foreground / border-border: e' quello che fa"
|
||||
echo "funzionare chiaro e scuro sul solo toggle della classe .dark."
|
||||
echo "Riferimento: design-reference/DESIGN-SYSTEM.md"
|
||||
echo "Eccezione sanzionata? Aggiungi il file alla WHITELIST di questo hook."
|
||||
} >&2
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -0,0 +1,17 @@
|
||||
# Piani
|
||||
|
||||
I piani delle milestone, **dentro il repo**. Ci sono arrivati il 2026-08-26: prima
|
||||
stavano solo in `~/.claude/plans/`, con nomi generati a caso, e `STATE.md` avvertiva
|
||||
che senza quei file v2.5 non era ricostruibile. Un piano che vive solo sul portatile
|
||||
di chi l'ha scritto non e' documentazione, e' un ricordo.
|
||||
|
||||
| File | Cosa contiene | Origine |
|
||||
|---|---|---|
|
||||
| `v2.5-audit-documento.md` | Il documento di audit: tre livelli (Radiografia / Prima-Dopo / Rotta) come configurazioni di un unico documento su `/audit/[slug]` | `dovremmo-fare-una-cosa-woolly-puddle.md` |
|
||||
| `v2.5-audit-motore.md` | Il motore: raccolta in parallelo, quattro sub-agent, sintetizzatore. Il vincolo che regge tutto — **un numero entra solo se misurato** | `vorrei-solo-farti-capire-radiant-valley.md` |
|
||||
| `v2.5-modifiche-hub.md` | I blocchi A/B/C delle modifiche all'hub chieste il 2026-08-18 | `sei-arrivato-qua-search-recursive-kettle.md` |
|
||||
|
||||
Sono **piani, non stato**: dicono cosa era stato deciso di fare, non cosa e' fatto.
|
||||
Per quello ci sono `STATUS.md` (narrativa) e `.planning/STATE.md` (digest).
|
||||
Passati al setaccio per credenziali prima del commit: dentro compaiono nomi di
|
||||
variabili d'ambiente, mai i loro valori.
|
||||
@@ -0,0 +1,413 @@
|
||||
# Audit — documento di restituzione
|
||||
|
||||
## Context
|
||||
|
||||
iamcavalli vende un servizio di analisi sito in tre livelli (La Radiografia / Il Prima-Dopo / La Rotta). Il deliverable è un documento di restituzione presentato in una call da 40 minuti. Oggi si fa a mano fuori dall'hub.
|
||||
|
||||
Il servizio si chiama **audit** → rotta `/audit/[slug]`. Il nome del livello acquistato compare **solo in copertina**.
|
||||
|
||||
```
|
||||
acquisto Whop ──┐
|
||||
├─► audit creato ─► intake dati ─► agent: analisi profonda
|
||||
creazione manuale ┘ │
|
||||
▼
|
||||
call (fissata a mano) ◄── consegna ◄── revisione + redesign (manuale)
|
||||
```
|
||||
|
||||
Il redesign lo prepari tu mentre gli agent lavorano. **Deve essere possibile creare un cliente e far partire l'audit in manuale, senza acquisto.**
|
||||
|
||||
Volume: ~50 audit/anno. Overhead non-analitico sotto i 10 minuti per audit. Regola guida: *tu scrivi solo analisi e redesign, tutto il resto si popola*.
|
||||
|
||||
### Documento canonico
|
||||
|
||||
La **Spec V1** (blocchi, copy fisso, campi) è il documento canonico. L'Excel *Ecommerce Growthlist* è **rubrica interna del motore di analisi**, non struttura del documento — vedi §4.
|
||||
|
||||
### Verdetto di fattibilità
|
||||
|
||||
Fattibile. Tre pezzi da costruire da zero: **motore di analisi**, **PDF**, **hosting immagini**. Il resto ha precedenti diretti in casa.
|
||||
|
||||
### Conflitti risolti a favore del progetto
|
||||
|
||||
| Spec V1 | Qui | Perché |
|
||||
|---|---|---|
|
||||
| Supabase | Neon + Drizzle | Lo stack è quello |
|
||||
| `uuid` | `text` + `nanoid()` | Convenzione di tutte le tabelle in `schema.ts` |
|
||||
| PDF serverless headless | Print CSS | Deploy Docker su Coolify, non serverless. Stesso risultato, zero infra |
|
||||
| `/r/[slug]?k=[token]`, slug = nome cliente | `/audit/[slug]`, slug nanoid nel path | **Sicurezza** (sotto) |
|
||||
|
||||
**Sullo slug.** `teckell-2026` è indovinabile: la segretezza si sposterebbe tutta sul token in query string, e i parametri di query finiscono nei log d'accesso e nei referrer molto più facilmente di un path. Il `Referrer-Policy: strict-origin-when-cross-origin` già presente mitiga in parte, ma la convenzione collaudata qui è **nanoid non indovinabile nel path, niente query** (`/preventivo/[slug]`, `/quote/[token]`). Un audit nomina un'azienda reale e ne elenca le debolezze: è il contenuto più sensibile che il portale pubblicherà.
|
||||
|
||||
**Due correzioni ad altre premesse:**
|
||||
|
||||
1. **I `gsd-audit-*` non c'entrano.** Verificato: `gsd-audit-milestone` verifica una milestone GSD, `gsd-audit-uat` raccoglie i test in sospeso, `gsd-audit-fix` sistema i finding nel *tuo* codebase. Auditano il progetto, non il sito del cliente. Motore custom; il precedente è `src/lib/proposal/agent.ts`.
|
||||
2. **Il deck dei preventivi non è riusabile come layout.** `ProposalDeck.tsx:151` monta solo la slide corrente e `:133` imposta `body.overflow = "hidden"`: stamparlo produce una pagina sola. Il documento è **a scorrimento**. Si riusa schema e macchina a stati, non il guscio visivo.
|
||||
|
||||
### Decisioni prese
|
||||
|
||||
| Punto | Decisione |
|
||||
|---|---|
|
||||
| Motore | In-app, background, polling dall'admin (§5) |
|
||||
| "La direzione" (blocco 8) | Manuale, foglio bianco, **con il materiale grezzo a fianco** |
|
||||
| PDF | Print CSS — stesso DOM, vincolo "una sola fonte" per costruzione |
|
||||
| Immagini | Volume persistente. **Modifica il vincolo LOCKED #5** (§9) |
|
||||
| Redesign | Immagini caricate **e** link Figma, con ruoli distinti (§6) |
|
||||
| Miglioramento nel tempo | Template versionato: tocca gli audit futuri, mai i consegnati (§3) |
|
||||
| Copertina | Titolo = nome del livello acquistato |
|
||||
| Scadenza | Nessuna. Depubblicazione manuale reversibile |
|
||||
| Tracking | Prima apertura, ultima apertura, conteggio |
|
||||
|
||||
---
|
||||
|
||||
## 1 · Spike sul motore — si parte da qui
|
||||
|
||||
È la parte più incerta e quella su cui si regge tutto il resto. Se la qualità dell'analisi non regge, meglio scoprirlo prima di costruirci sopra schema, editor e documento.
|
||||
|
||||
**Non tocca il database, non tocca l'hub.** Uno script isolato, `scripts/spike-audit.ts`, sul sito di un cliente attuale, che stampa l'output grezzo.
|
||||
|
||||
Deve dimostrare che:
|
||||
- Il fetch delle pagine chiave e l'estrazione del testo reggono su un sito reale
|
||||
- La verifica delle voci di checklist è **affidabile e ripetibile** (§4)
|
||||
- I problemi sono **concreti, non generici** — "il messaggio non è chiaro" non vale niente, "l'headline non nomina il destinatario" sì
|
||||
- La conseguenza per il business è specifica
|
||||
|
||||
Da riusare subito: la protezione da prompt injection di `src/lib/proposal/agent.ts:32-35` (blocco SICUREZZA che dichiara il contenuto come dati, non istruzioni) e `:49` (neutralizzazione dei tag di chiusura). Con HTML scrapato da un sito esterno serve **più** che con le trascrizioni: è contenuto di terzi e può contenere istruzioni ostili.
|
||||
|
||||
> Il resto si esegue **dopo** esito positivo dello spike.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Il documento
|
||||
|
||||
Un solo documento ben progettato; i tre livelli sono **configurazioni** di quello.
|
||||
|
||||
| # | Blocco | Radiografia | Prima/Dopo | Rotta |
|
||||
|---|---|:--:|:--:|:--:|
|
||||
| 1 | Copertina | ● | ● | ● |
|
||||
| 2 | Sintesi | ● | ● | ● |
|
||||
| 2b | **Cosa funziona già** | ● | ● | ● |
|
||||
| 3 | Stato di fatto | ● | ● | ● |
|
||||
| 4 | I problemi, per impatto | ● | ● | ● |
|
||||
| 5 | Analisi per area | ● | ● | ● |
|
||||
| 6 | Il redesign | — | ● | ● |
|
||||
| 6b | **Cosa il redesign non risolve** | — | ● | ● |
|
||||
| 7 | Le ottimizzazioni | — | — | ● |
|
||||
| 8 | La direzione | ● | ● | ● |
|
||||
| 9 | Come si prosegue | ● | ● | ● |
|
||||
|
||||
I blocchi non pertinenti **non esistono nel DOM**, non sono nascosti via CSS.
|
||||
|
||||
Il **copy fisso** di ogni blocco è quello della Spec V1, riportato integralmente in `template/v1.ts` (§3). Nel blocco 9 le *fasi già completate* si derivano dal livello acquistato, e il credito riconosciuto è `importo_pagato`.
|
||||
|
||||
**I due blocchi 2b e 6b sono aggiunte del prototipo Giojello, non della Spec V1**, e vanno tenute:
|
||||
- *Cosa funziona già* costruisce credibilità prima di criticare, e dichiara cosa non va toccato
|
||||
- *Cosa il redesign non risolve* è onesto e commercialmente più efficace della vendita: apre al progetto completo senza promettere
|
||||
|
||||
Campi: `punti_forza` (lista) e `redesign_limiti` (testo).
|
||||
|
||||
### Il prototipo Giojello è il riferimento del template v1
|
||||
|
||||
Il file HTML prodotto per Giojello **non è il documento: è la fonte di `template/v1.ts`** — copy, tipografia, gerarchia. Va spacchettato in componenti alimentati dal record. Quattro difetti da NON portarsi dietro:
|
||||
|
||||
1. **Contenuto cablato nel markup** (699€, 8,0s, 500€, le date). Viola il vincolo "un record → una pagina → un PDF": tutto viene dal DB
|
||||
2. **Google Fonts via `<link>`** — la CSP del progetto è `font-src 'self' data:` e `style-src 'self' 'unsafe-inline'`: verrebbe **bloccato** e il documento cadrebbe sui font di sistema. **Font self-hostati** (Instrument Serif / Inter / IBM Plex Mono, se si conferma quel trio in luogo di Plus Jakarta Sans — è una deroga consapevole a DESIGN-SYSTEM.md, giustificabile perché è un documento pubblico, non la UI admin)
|
||||
3. **Print CSS di sei righe.** Nasconde la legenda interna ma **non i colori che la legenda spiega**: i bordi e i testi rossi/blu dei blocchi di lavorazione finiscono stampati senza più nulla che li spieghi. I marcatori di lavorazione non devono esistere nel documento consegnato
|
||||
4. **Colore come unico portatore di informazione nelle metriche** — `3,4 s` rosso e `1,0 s` verde diventano identici in scala di grigi. Serve un secondo canale (glifo, peso, etichetta)
|
||||
|
||||
⚠️ **Tassonomia degli impatti.** Il prototipo usa cinque valori ("medio-alto", "basso-medio"…), lo schema ne prevede tre. Con cinque l'ordinamento automatico su tre non funziona. Decisione: si resta a **tre valori**, e la sfumatura sta nell'ordine dentro il gruppo (`sort_order`).
|
||||
|
||||
### Regola di collocazione: finding vs analisi
|
||||
|
||||
Il prototipo v2 ha aggiunto una sezione discorsiva "Interfaccia" con otto paragrafi che contengono almeno quattro **veri finding** — contrasto insufficiente sulla CTA della hero, riflesso che mangia il 40% dell'immagine prodotto, titoli troncati, e soprattutto il carrello (spedizione assicurata 39,90€ contro 6,13€ con la non assicurata preselezionata). Quest'ultimo è da primi cinque ed era in coda a una sezione discorsiva.
|
||||
|
||||
**Regola per il motore e per l'editor:** se una cosa ha un impatto e una conseguenza, è un finding — va nel blocco 4, prende un numero e viene ordinata. Il blocco 5 resta discorsivo e resta a **tre aree** (struttura / messaggio / conversione). Nessuna quarta area.
|
||||
|
||||
Motivo: il documento promette "non un elenco di quaranta punti", e una seconda lista non ordinata dopo quella ordinata annulla la promessa. La forza del documento è la **selezione**.
|
||||
|
||||
### Disciplina sui numeri — vincolo del motore
|
||||
|
||||
Confronto con un audit parallelo dello stesso sito prodotto da un altro modello: conteneva "~65% abbandono stimato" e "+60% velocità mobile immediata". **Nessuno dei due è misurato**: sono congetture presentate come rilevazioni.
|
||||
|
||||
Il prototipo Claude è disciplinato su questo — dice "una parte importante del traffico" proprio perché non può quantificarla. **Quella disciplina va imposta nel prompt di sistema del motore**: un numero compare nel documento solo se proviene da una rilevazione (PageSpeed, conteggio DOM, peso pagina, dati del sito). Mai stime di conversione o di guadagno percentuale. In un deliverable premium basta un cliente che verifichi per bruciare tutta la credibilità.
|
||||
|
||||
Voce di verifica: nessun numero nel documento consegnato è privo di fonte in `audit_runs.raw`.
|
||||
|
||||
### Contributi da assorbire dall'audit parallelo
|
||||
|
||||
- **La misura/taglia nella griglia prodotti** — su pezzi unici rigenerati è criterio di scelta primario e non compare da nessuna parte. Si aggancia al finding sull'unicità e apre a un servizio ("messa a misura disponibile"). Va nella checklist profilo `ecommerce` come voce
|
||||
- **Conteggio dei nodi DOM** — quantifica il problema di peso meglio dei MB. Da aggiungere alle rilevazioni di `fetch.ts`
|
||||
- **Stime in giornate** — alimentano la colonna *Impegno* del blocco 7
|
||||
|
||||
### Estensione opzionale — allegato tecnico (NON in fase 1)
|
||||
|
||||
Il blocco 9 promette *"il documento resta tuo e puoi darlo a chiunque lavorerà sul sito"*, ma consegna prosa da imprenditore a uno sviluppatore.
|
||||
|
||||
Un **allegato tecnico generato dallo stesso record** — stessi finding, registro da sviluppatore, con selettori, file coinvolti e stime — renderebbe quella promessa molto più preziosa. È una seconda vista sugli stessi dati, quindi non viola il vincolo della fonte unica e non richiede contenuto aggiuntivo. Da valutare dopo il primo audit consegnato.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Versionamento del template
|
||||
|
||||
Requisito: migliorare il documento deve toccare gli audit **successivi**, mai quelli già consegnati.
|
||||
|
||||
Precedente in casa: `proposals.content` congela profilo e prezzi alla generazione, così modificarli dopo non retro-cambia un preventivo pubblicato.
|
||||
|
||||
Copy fisso e configurazione dei blocchi vivono in **moduli TS versionati**, non nel database:
|
||||
|
||||
```
|
||||
src/lib/audit/template/
|
||||
v1.ts copy fisso di ogni blocco + ordine + mappa livello→blocchi
|
||||
index.ts registry versione→modulo + LATEST_TEMPLATE_VERSION
|
||||
```
|
||||
|
||||
- `audits.template_version` impostata alla versione corrente **alla creazione**
|
||||
- Un audit **consegnato resta congelato** sulla sua versione, per sempre
|
||||
- Migliorare il documento = aggiungere `v2.ts` e alzare `LATEST_TEMPLATE_VERSION`. Nessuna migration, nessun backfill, storia completa in git
|
||||
- Le **bozze** si portano all'ultima versione con un bottone esplicito, mai in automatico
|
||||
|
||||
---
|
||||
|
||||
## 4 · La checklist come rubrica del motore
|
||||
|
||||
L'Excel ha 264 voci su 7 step di funnel, con scoring ICE e peso di importanza per sezione. Serve al **motore**, non al documento.
|
||||
|
||||
**Perché è preziosa:** ogni voce è un'asserzione binaria e verificabile ("Il checkout consente l'acquisto come ospite"). Verificare 264 affermazioni falsificabili è molto più affidabile che chiedere a un modello "analizza questo sito": trasforma l'analisi da generativa a **verificativa**, controllabile voce per voce. E lo scoring ICE risolve gratis l'ordinamento del blocco 4 e le priorità del blocco 7.
|
||||
|
||||
**Tre vincoli emersi dalla lettura del file:**
|
||||
|
||||
1. **È al 73% ecommerce.** Generale (50) e Homepage (21) valgono per qualsiasi sito; Categoria, Scheda Prodotto, Carrello, Checkout, Ringraziamento — **193 voci su 264** — presuppongono un carrello. Servono **due profili**: `ecommerce` e `servizi`. Il secondo va scritto, non esiste nel file.
|
||||
2. **Misura la conformità, non l'adeguatezza.** Un sito può fare 250/264 e continuare a descrivere un'azienda che non esiste più. Nessuna voce chiede se il posizionamento dichiarato corrisponde a quello che vendi oggi, o se le prove sono della fascia di cliente giusta. La checklist è il **pavimento** (guasti meccanici, li trova l'agent); lo scarto strategico è il **soffitto** e resta analisi tua. Se il documento diventa il rendering della checklist, torna a sembrare un audit automatico gratuito.
|
||||
3. **Molte voci sono tattiche da ecommerce a volume** — scarsità, urgenza, countdown, popup di social proof. Su un brand premium **danneggiano**: abbassano il segnale di prezzo mentre tu vendi il contrario. Ogni voce porta quindi un campo `registro` (`volume` / `premium` / `neutro`) e l'audit di un brand premium non propone mai i trigger da discount.
|
||||
|
||||
⚠️ Note tecniche sul file: il foglio *Algoritmo* ha errori **`#REF!`**, e la colonna *Facilità* è **1.0 su tutte le righe** — non compilata, quindi lo Score attuale è di fatto solo Impatto × Confidenza. Da sistemare prima di seminarne i default.
|
||||
|
||||
Il foglio *Best Ecommerce List* (88 siti per settore) alimenta confronti concreti: "il tuo checkout chiede 11 campi, i riferimenti del settore ne chiedono 6".
|
||||
|
||||
**Nel documento** la checklist non compare come elenco. Il blocco 3 mostra al massimo il grado di conformità **per step di funnel** (una barra per step), accanto alle metriche di performance. I problemi del blocco 4 sono una **selezione curata** — voci non conformi ad alto impatto più lo scarto strategico — non il dump delle non conformità.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Migration `0017_audits.sql`
|
||||
|
||||
Additiva e idempotente. Template di stile: `src/db/migrations/0016_retainer_lifecycle.sql` (header in italiano che spiega il *perché*, `ADD COLUMN IF NOT EXISTS`, `CHECK ... NOT VALID` dentro `DO $$ ... pg_constraint`, `CREATE INDEX IF NOT EXISTS`).
|
||||
|
||||
Convenzioni da `src/db/schema.ts`: id `text` con `$defaultFn(() => nanoid())`, **nessun `pgEnum`** (text + CHECK in SQL + tupla `as const` in TS + Zod nell'action), timestamp `withTimezone: true`, `updated_at` bumpato a mano nell'action.
|
||||
|
||||
**`audits`** — colonne scalari, non jsonb: non c'è snapshot da congelare (ci pensa `template_version`) e l'editor mappa 1:1.
|
||||
|
||||
- Identità: `id`, `slug` unique nanoid, `lead_id` → `leads` SET NULL, `client_id` → `clients` SET NULL (nullable entrambi, come `proposals`)
|
||||
- Config: `livello` CHECK `('radiografia','prima_dopo','rotta')`, `template_version`, `profilo` CHECK `('ecommerce','servizi')`, `cliente_nome`, `cliente_referente`, `sito_url`, `importo_pagato numeric(10,2)`, `data_consegna date`
|
||||
- Origine: `origin` CHECK `('manuale','whop')` default `'manuale'`, `external_ref` — predispone Whop senza costruirlo
|
||||
- Stato: `state` CHECK `('draft','published')` default `'draft'` (etichettati *Bozza* / *Consegnata* nella UI), `published_at`
|
||||
- Tracking: `first_viewed_at`, `last_viewed_at`, `view_count integer default 0`
|
||||
- Rilevazioni (blocco 3): `perf_mobile`, `perf_desktop`, `lcp numeric(6,2)`, `cls numeric(5,3)`, `inp`, `pagine_indicizzate`, `screenshot_desktop_url`, `screenshot_mobile_url`, `measured_at`
|
||||
- Contenuto (blocchi 2/2b/5/8): `sintesi`, `punti_forza jsonb` (lista, blocco 2b), `analisi_struttura`, `analisi_messaggio`, `analisi_conversione`, `direzione`
|
||||
- Redesign (blocchi 6/6b): `redesign_sezione`, `redesign_prima_url`, `redesign_dopo_url`, `redesign_razionale`, `redesign_limiti`, `redesign_figma_url`
|
||||
- Intake: `intake jsonb` — i dati che il cliente condivide, forma ancora da definire
|
||||
|
||||
**Tutti i campi di contenuto sono nullable.** È ciò che rende possibile "si salva sempre, anche a metà": la validazione di completezza scatta solo alla consegna.
|
||||
|
||||
**`audit_findings`** (blocco 4) — `audit_id` CASCADE, `titolo`, `impatto` CHECK `('alto','medio','basso')`, `area` CHECK `('struttura','messaggio','conversione','performance')`, `descrizione`, `conseguenza`, `screenshot_url`, `sort_order integer default 0`, `origin` CHECK `('agent','manuale')`
|
||||
|
||||
**`audit_optimizations`** (blocco 7) — `audit_id` CASCADE, `intervento`, `priorita` CHECK `('alta','media','bassa')`, `motivazione`, `impegno`, `sort_order integer default 0`
|
||||
|
||||
**`checklist_items`** (rubrica, versionata come il template) — `profilo`, `step`, `focus`, `testo`, `impatto_default`, `confidenza_default`, `registro` CHECK `('volume','premium','neutro')`, `sort_order`
|
||||
|
||||
**`audit_checklist_results`** — `audit_id` CASCADE, `item_id`, `esito` CHECK `('conforme','non_conforme','non_rilevante')`, `note`, `evidenza`, `origin` CHECK `('agent','manuale')`
|
||||
|
||||
**`audit_runs`** (§6) — `audit_id` CASCADE, `status` CHECK `('queued','running','done','error')`, `step`, `started_at`, `finished_at`, `heartbeat_at`, `error`, `raw jsonb` (output grezzo: materiale per il blocco 8)
|
||||
|
||||
Indici: unique su `slug`; index su `client_id`, `lead_id`, `(audit_id, sort_order)` per le figlie, `(audit_id, started_at desc)` per le run, `(audit_id, item_id)` unique per i risultati.
|
||||
|
||||
**Ordinamento automatico** (blocchi 4 e 7): la query ordina per rango di impatto/priorità con `sort_order` come spareggio *dentro* il gruppo. Tu non ordini niente.
|
||||
|
||||
> ⚠️ **Checkpoint bloccante.** Migration applicata in produzione **prima** di pushare il codice schema-dipendente (regola CLAUDE.md "Ordering"), via SSH/docker-exec. Aggiornare `src/db/schema.ts` a mano in parallelo — `drizzle-kit generate` è rotto.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Motore di analisi
|
||||
|
||||
`src/lib/audit/` modellato su `src/lib/proposal/` ma multi-step:
|
||||
|
||||
```
|
||||
src/lib/audit/
|
||||
pipeline.ts funzione pura: (auditId) => risultato. Non conosce chi la chiama
|
||||
agent.ts chiamate Anthropic, una per step di funnel
|
||||
schema.ts validazione Zod dell'output
|
||||
fetch.ts recupero pagine + estrazione testo + PageSpeed
|
||||
```
|
||||
|
||||
**Passi:** recupero pagine chiave → metriche PageSpeed → verifica delle voci di checklist del profilo → sintesi dei problemi con impatto+area+descrizione+conseguenza.
|
||||
|
||||
Tutto l'output è **bozza**: finisce in `audit_checklist_results` e in `audit_findings` con `origin='agent'`. Tu rivedi e correggi prima di consegnare. Si automatizza il meccanico, **il giudizio resta tuo**.
|
||||
|
||||
**Il blocco 8 "La direzione" resta manuale, foglio bianco.** L'editor mostra a lato il materiale grezzo — problemi ad alto impatto e temi ricorrenti, da `audit_runs.raw`. Nessun testo proposto, nessun template. È il blocco che giustifica il prezzo: se diventa formula, il cliente lo sente.
|
||||
|
||||
**Esecuzione: in-app, background, con polling.**
|
||||
- "Avvia analisi" → riga `audit_runs` con `status='queued'`, lancia la pipeline
|
||||
- L'admin fa polling e mostra `step` corrente e avanzamento
|
||||
- Progresso scritto a ogni passo: un'interruzione non perde il lavoro fatto
|
||||
|
||||
> ⚠️ **Rischio da mettere in conto.** Con `output: "standalone"` su singolo container Coolify, un redeploy **uccide un job in corso** e lascia una riga bloccata su `running`. Mitigazione: `heartbeat_at` aggiornato a ogni passo, le run senza heartbeat da N minuti vanno in `error`, e "Rilancia" riparte dall'ultimo passo completato. Non è un sistema a code: è deliberatamente il minimo che regge 50 audit/anno.
|
||||
|
||||
`pipeline.ts` è una **funzione pura riusabile**: oggi la chiama il bottone, domani il webhook Whop. Nessuna riscrittura.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Storage immagini e redesign
|
||||
|
||||
Servono: 2 screenshot home, N screenshot dei problemi, 2 immagini redesign. Con URL esterni incollati a mano il budget dei 10 minuti non regge, e un URL morto uccide il documento del cliente.
|
||||
|
||||
**Volume persistente, non servizio esterno.** Nessuna dipendenza npm nuova, nessun account terzo, nessuna credenziale.
|
||||
|
||||
- Volume Coolify montato su `/app/uploads`
|
||||
- Upload via **server action** che riceve `File` da `FormData`. Niente upload diretto dal browser: la CSP ha `connect-src 'self'`, un POST verso un host esterno sarebbe bloccato — passare dal nostro origin è l'unica strada e va bene così
|
||||
- Validazione: whitelist MIME `image/png|jpeg|webp`, max 5MB, nome file `nanoid()` (mai l'originale)
|
||||
- Lettura via `src/app/api/uploads/[...path]/route.ts` con guardia sul path traversal e `Cache-Control` lungo
|
||||
- CSP invariata: serviamo dal nostro origin, coperto da `img-src 'self'`
|
||||
|
||||
> ⚠️ **Checkpoint bloccante.** Volume creato in Coolify prima del deploy, altrimenti gli upload si perdono a ogni redeploy.
|
||||
|
||||
Nuovo componente `ImageUploadField` — in tutto `src/` non c'è un solo `<input type="file">`.
|
||||
|
||||
**Il redesign usa entrambi i formati, con ruoli distinti:**
|
||||
- **Immagini caricate** — rappresentazione canonica, quelle che si vedono nello slider e **le uniche che finiscono nel PDF**
|
||||
- **Link Figma** — opzionale, "apri il redesign interattivo", nuova scheda
|
||||
|
||||
Perché non embeddare Figma: la CSP ha `default-src 'self'` senza `frame-src`, quindi l'iframe sarebbe bloccato; e un iframe **in stampa non produce nulla**, rompendo il vincolo "una sola fonte" proprio sul blocco che vale di più.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Pagina pubblica e PDF
|
||||
|
||||
`/audit/[slug]`, modellata su `src/app/preventivo/[slug]/page.tsx`: `export const revalidate = 0`, fetch by slug, `notFound()` se assente.
|
||||
|
||||
**Differenze deliberate dal preventivo:**
|
||||
- **Documento a scorrimento.** Nessun `h-screen`, nessun `overflow-hidden`, nessuna manipolazione di `body.style`
|
||||
- **Rate limit**: aggiungere `/audit` al matcher di `src/proxy.ts` riusando `src/lib/rate-limit.ts`. Il preventivo non ce l'ha — non ereditare quell'omissione
|
||||
- **noindex**: `X-Robots-Tag: noindex, nofollow` in `next.config.ts` più `metadata.robots`
|
||||
- **Anteprima admin**: con `state === 'draft'` mostrare comunque il documento se `getServerSession` restituisce una sessione admin, altrimenti il placeholder. Non tocca LOCKED #4, che riguarda `/client/*`
|
||||
- **Tracking**: alla prima render non-admin aggiornare `first_viewed_at` / `last_viewed_at` / `view_count`
|
||||
|
||||
Nuovi componenti in `src/components/public/audit/`, uno per blocco, server components salvo slider e bottone stampa. **Non riusare** le 20 sezioni di `public/proposal/sections/`: sono saldate a `ProposalContent` con copy hard-coded.
|
||||
|
||||
Da riusare: **`RichText.tsx`** per ogni testo libero (obbligatorio su output del modello — mai `dangerouslySetInnerHTML`), e le convenzioni visive esistenti (eyebrow `text-xs font-mono tracking-widest uppercase`, headline `text-5xl font-light`, card `border border-border rounded-xl p-8`).
|
||||
|
||||
⚠️ Il deck preventivi è light-only (`bg-white` hard-coded in `ProposalDeck.tsx:139,141,156`, `PricingSection.tsx:46`) e viola la regola dei token in due punti (`TimelineSection.tsx:5-9`, `ClosingSection.tsx:20,34`). **Non replicare quei difetti**: solo token semantici, dual light/dark.
|
||||
|
||||
**Leggibilità in B/N**: il livello di impatto non può dipendere dal colore. Etichetta + glifo — `●●● alto` / `●●○ medio` / `●○○ basso`.
|
||||
|
||||
### PDF via print CSS
|
||||
|
||||
Stessa pagina, stesso DOM, stesso record: il vincolo "una sola fonte" è soddisfatto per costruzione.
|
||||
|
||||
In `src/app/globals.css` — oggi **zero regole print** in 218 righe — un blocco `@media print`:
|
||||
- Palette chiara forzata, `print-color-adjust: exact` dove serve
|
||||
- `break-inside: avoid` su ogni card problema e riga della tabella; `break-before: page` sui blocchi maggiori
|
||||
- Nascosti: bottone stampa, nav, controllo dello slider
|
||||
- **Slider prima/dopo**: a schermo interattivo, in stampa due immagini impilate con etichetta. Tecnica: entrambe le `<img>` **sempre** nel DOM, clippate in overlay via CSS a schermo; in `@media print` si toglie il clip e si impila. Nessun ramo JS, nessuna divergenza possibile
|
||||
- Bottone "Scarica PDF" sticky in alto a destra = client island con `window.print()`
|
||||
|
||||
---
|
||||
|
||||
## 9 · Admin
|
||||
|
||||
Mutazioni come Server Actions colocate in `actions.ts` (niente REST per l'admin).
|
||||
|
||||
- `src/app/admin/audit/page.tsx` — lista. Riusare `PageHeader`, `SearchInput`, badge di stato
|
||||
- `src/app/admin/audit/nuovo/` — **creazione manuale**: cliente o lead, livello, profilo, URL, importo → redirect all'editor
|
||||
- `src/app/admin/audit/[id]/edit/page.tsx` — RSC sottile + client component
|
||||
- `src/components/admin/audit/AuditEditor.tsx`
|
||||
- `src/app/admin/audit/actions.ts`
|
||||
- Voce in `AdminSidebar.tsx`
|
||||
|
||||
**Pattern editor: `saveOfferEditor` + `OfferEditorClient`** (`src/app/admin/offers/actions.ts:177-274`, `src/components/admin/offers/OfferEditorClient.tsx`) — unico precedente di salvataggio a payload intero con array di figli:
|
||||
|
||||
- Zod annidato con `z.array(findingSchema)` / `z.array(optimizationSchema)`, `id` opzionale sui figli
|
||||
- Nell'action: update degli scalari, loop sui figli con **upsert per presenza di `id`**, delete delle righe sparite, `sort_order: index` assegnato server-side
|
||||
- Client: array in `useState`, update immutabili via `.map`, `startTransition` + try/catch → `setSaveError`
|
||||
- ⚠️ **Il re-sync degli id dopo il primo salvataggio** (`OfferEditorClient.tsx:93-98`): senza, i figli appena creati vengono re-inseriti invece che aggiornati al salvataggio successivo. È il bug più facile da introdurre qui
|
||||
|
||||
**Aggiungi / rimuovi / riordina righe**: non esiste nel codebase — `sort_order` oggi è write-once. `@dnd-kit/sortable` è già in `package.json` e usato in `KanbanBoard.tsx`: riusarlo, con l'indice dell'array che diventa `sort_order` al salvataggio.
|
||||
|
||||
**Campi condizionali**: redesign e ottimizzazioni non si renderizzano se il livello non li prevede.
|
||||
|
||||
**Bozza**: niente autosave (non esiste nel codebase, complessità sproporzionata). "Salva bozza" esplicito + avviso all'uscita con modifiche pendenti. Tutti i campi nullable. La **validazione di completezza scatta solo su "Consegna"**, sui soli blocchi pertinenti.
|
||||
|
||||
**Consegna / Ritira**: transizioni guardate `WHERE id = ? AND state = ?` come `publishProposal` (`src/app/admin/preventivi/actions.ts:117-127`). Entrambe reversibili.
|
||||
|
||||
**Automatismi** (budget 10 minuti): credito = `importo_pagato`, fasi già completate derivate dal livello, date da `published_at`/`measured_at`, ordinamento dei blocchi 4 e 7, analisi draftata dagli agent.
|
||||
|
||||
---
|
||||
|
||||
## 10 · Ingresso: manuale ora, Whop dopo
|
||||
|
||||
Fase 1 = **solo creazione manuale**, che resta comunque un requisito permanente.
|
||||
|
||||
Predisposto senza costruirlo: `origin` + `external_ref` sulla tabella, e `pipeline.ts` chiamabile da un webhook. L'intake del cliente è **ancora da definire** — la colonna `intake jsonb` accoglie qualunque forma prenderà, senza migration aggiuntive.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Modifica al vincolo LOCKED #5 — richiede approvazione
|
||||
|
||||
`CLAUDE.md` oggi: `5. No file hosting v1 — documenti come URL esterni`
|
||||
|
||||
Nuova versione proposta:
|
||||
|
||||
```
|
||||
5. No file hosting per i documenti — restano URL esterni.
|
||||
Deroga (Phase 27, 2026-08-16): le immagini dell'audit (screenshot e
|
||||
redesign) sono caricate su volume persistente e servite da
|
||||
/api/uploads/[...path], con whitelist MIME e limite di dimensione.
|
||||
Non estendere l'upload ad altre entità senza modificare questo vincolo.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12 · GSD e memoria di progetto
|
||||
|
||||
**Non c'è niente da costruire**: state file, roadmap e checkpoint automatico esistono già. `.planning/STATE.md` è il digest che comanda i comandi `/gsd-*`, `.planning/ROADMAP.md` traccia la posizione, `execute-plan.md` aggiorna STATE.md **dopo ogni piano**, e `.claude/rules/memory-discipline.md` è la regola scritta.
|
||||
|
||||
Due difetti reali:
|
||||
|
||||
1. **`.planning/config.json` non ha la chiave `hooks`.** Verificato: entrambi gli hook globali (`gsd-session-state.sh`, `gsd-phase-boundary.sh`) escono a vuoto senza `"hooks": { "community": true }`. Aggiungerla riattiva l'iniezione di STATE.md all'avvio sessione e il promemoria a ogni scrittura in `.planning/`. Una riga.
|
||||
2. **`gsd-sdk` e `gsd-tools` non sono nel PATH** (verificato: `not found`). Le mutazioni automatiche di STATE.md in `execute-plan.md` non hanno backend e ricadono su edit manuali — è il motivo per cui le fasi 13 e 26 hanno SUMMARY ricostruiti a posteriori.
|
||||
|
||||
L'hook `Stop` in `.claude/settings.json` è solo advisory (`echo`) e guarda solo `src` e `.planning`: non nota modifiche a `STATUS.md` o `CLAUDE.md`.
|
||||
|
||||
**Inquadramento**: nuovo milestone **v2.5 — Audit** via `/gsd-new-milestone`. Numerazione progressiva e mai riusata (l'ultima è 26 ⇒ si parte da **27**), come impone `.planning/PROJECT.md`.
|
||||
|
||||
Da aggiornare a fine lavoro: `.planning/STATE.md`, `.planning/ROADMAP.md`, `STATUS.md`, `CLAUDE.md`.
|
||||
|
||||
---
|
||||
|
||||
## 13 · File toccati
|
||||
|
||||
**Nuovi** — `scripts/spike-audit.ts` · `src/db/migrations/0017_audits.sql` · `src/lib/audit/{pipeline,agent,schema,fetch}.ts` · `src/lib/audit/template/{v1,index}.ts` · `src/lib/audit-queries.ts` · `src/lib/audit-view.ts` · `src/app/audit/[slug]/page.tsx` · `src/components/public/audit/*` · `src/app/admin/audit/**` · `src/components/admin/audit/AuditEditor.tsx` · `src/components/ui/ImageUploadField.tsx` · `src/app/api/uploads/[...path]/route.ts`
|
||||
|
||||
**Modificati** — `src/db/schema.ts` · `src/proxy.ts` · `next.config.ts` · `src/app/globals.css` · `src/components/admin/AdminSidebar.tsx` · `CLAUDE.md` · `.planning/config.json` · `Dockerfile` + volume Coolify
|
||||
|
||||
---
|
||||
|
||||
## 14 · Verifica
|
||||
|
||||
Non esiste test suite (nessun vitest/jest/playwright, nessuno script `test`). **`npm run build` è la verifica di riferimento** — fa il typecheck. `npm run lint` è `eslint` nudo.
|
||||
|
||||
**Fase 1 (spike)** — gira su un sito reale, i problemi sono concreti e verificabili, la valutazione delle voci di checklist è ripetibile. È un giudizio tuo, non un test automatico.
|
||||
|
||||
**Dopo:**
|
||||
1. `npm run build` — typecheck e compilazione
|
||||
2. Migration applicata in prod **prima** del push; verificare che le sei tabelle esistano
|
||||
3. Un audit di prova per ciascuno dei tre livelli, su entrambi i profili: i blocchi condizionali compaiono e spariscono correttamente
|
||||
4. Salvare a metà, ricaricare, nulla si perde. Salvare due volte di fila: i figli si aggiornano e **non si duplicano** (test del re-sync degli id)
|
||||
5. Riordinare i problemi, salvare, ricaricare: l'ordine regge
|
||||
6. Avviare un'analisi e **riavviare il container a metà**: la run va in `error` e "Rilancia" riparte senza perdere i passi completati
|
||||
7. Upload di un'immagine → redeploy → l'immagine è ancora lì (prova del volume)
|
||||
8. Slug consegnato in incognito: si apre. Bozza in incognito: placeholder. Bozza da admin loggato: si vede
|
||||
9. `X-Robots-Tag: noindex, nofollow` presente nella risposta
|
||||
10. **Stampa**: Cmd+P sul documento consegnato → interruzioni di pagina corrette, slider impilato in due immagini, nessun marcatore di lavorazione (bordi/testi colorati) sopravvissuto, e in **scala di grigi** sia i livelli di impatto sia i valori delle metriche restano distinguibili
|
||||
10b. **Rete disattivata dopo il primo caricamento**: i font restano quelli giusti (prova che sono self-hostati e che nessuna risorsa esterna è rimasta)
|
||||
11. Il tracking apertura si incrementa da visitatore e **non** dalla preview admin
|
||||
12. Consegnato un audit su `v1`, alzare `LATEST_TEMPLATE_VERSION` a `v2`: il consegnato continua a rendere `v1`, uno nuovo nasce `v2`
|
||||
13. Un audit su brand premium **non** propone mai voci con `registro='volume'`
|
||||
|
||||
⚠️ Playwright non funziona contro `npm run dev` (la CSP blocca `eval`, i client component non si idratano). Per E2E usare il build di produzione.
|
||||
@@ -0,0 +1,200 @@
|
||||
# Audit — motore multi-agente, rilevazioni e tracciamento
|
||||
|
||||
## Context
|
||||
|
||||
Il piano approvato il 2026-08-16 (`dovremmo-fare-una-cosa-woolly-puddle.md`) resta in vigore per struttura del documento, versionamento del template, rubrica checklist, editor admin, pagina pubblica e print CSS. **Questo file ne sostituisce tre parti** — §6 (motore), §7 (immagini) e il tracciamento in §5/§8 — e non tocca il resto.
|
||||
|
||||
Cosa è successo da allora:
|
||||
|
||||
- **Lo spike è girato su giojello.com** e ha prodotto un audit di buona qualità. Ma `psi: {}` — le rilevazioni PageSpeed sono fallite tutte per quota anonima esaurita. Quell'audit è stato scritto **con zero misurazioni**, solo HTML statico.
|
||||
- **Il 52% della checklist non è verificabile da HTML statico** (204 voci → 107 non verificabili; lo step `generale` 40 su 50). Barra di ricerca, widget carrello, hover, animazioni, banner cookie esistono solo a runtime.
|
||||
- **Il VPS non può ospitare Chromium**: 1.492 MB di RAM disponibili su 3.819, 736 MB già in swap, 2 vCPU, con Coolify/n8n/Gitea/Vaultwarden sopra. Il disco invece è libero (21 GB su 38). Immagine `node:20-alpine`, non supportata da Playwright.
|
||||
- **Il processo bersaglio è: incolli un URL, il motore fa ricerche incrociate con le API gratuite, esce un documento pronto da inoltrare.** Tu carichi a mano solo due immagini: hero prima e hero dopo, JPG ≤ 0,5 MB.
|
||||
|
||||
### Decisioni
|
||||
|
||||
| Punto | Decisione | Data |
|
||||
|---|---|---|
|
||||
| Renderer headless | **Nessuno, da nessuna parte.** Motore 100% in-app, self-service | 2026-08-18 |
|
||||
| Buco a runtime | Coperto da audit Lighthouse completi + screenshot renderizzato letto in visione + CrUX + Wayback | 2026-08-18 |
|
||||
| Immagini manuali | Solo le due del redesign, JPG ≤ 0,5 MB | 2026-08-18 |
|
||||
| Screenshot stato di fatto | Automatici, da PageSpeed | 2026-08-18 |
|
||||
| Tracciamento | Registro delle singole visite + evento stampa | 2026-08-18 |
|
||||
|
||||
**Due decisioni del 2026-08-17 sono superate da questa revisione** e vanno corrette prima di eseguire (§8): il renderer locale sul Mac e la frase "la copia master è la cartella di cattura locale" scritta in `CLAUDE.md` — non esiste più nessuna cattura locale.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisito bloccante — chiave PageSpeed e verifica dell'ipotesi
|
||||
|
||||
Tutto il resto poggia su un'ipotesi **non ancora verificata**: la quota anonima risponde `429` e senza chiave non si prova. Primo passo, prima di scrivere codice:
|
||||
|
||||
1. Creare un progetto Google Cloud, abilitare *PageSpeed Insights API* e *Chrome UX Report API*, generare una chiave (gratuita, nessuna carta). In `.env.local` e in Coolify come `PAGESPEED_API_KEY`.
|
||||
2. Una chiamata a mano, e **verificare che esistano davvero**:
|
||||
- `lighthouseResult.fullPageScreenshot.screenshot.data` → `data:image/jpeg;base64,…` a pagina intera
|
||||
- `lighthouseResult.audits` → l'insieme completo (~150 voci), non i 10 scalari che lo spike estrae oggi
|
||||
|
||||
**Se lo screenshot a pagina intera non c'è**, ripiego su `lighthouseResult.audits["final-screenshot"]` (solo viewport, quindi di fatto l'hero — che è comunque il blocco più importante). **Se non c'è nemmeno quello**, l'analisi visiva esce dalla fase 1 e gli screenshot dello stato di fatto tornano manuali: cambia §5 di questo piano, non il resto.
|
||||
|
||||
> ⚠️ Non costruire il sub-agent visivo prima di aver visto quel campo con i tuoi occhi.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Le fonti — "tutte le api gratuite che servono"
|
||||
|
||||
| Fonte | Cosa dà | Chiave | Alimenta |
|
||||
|---|---|---|---|
|
||||
| **PageSpeed Insights v5** (mobile + desktop) | ~150 audit Lighthouse, punteggi, screenshot renderizzato a pagina intera | sì, gratuita | blocco 3, finding tecnici, sub-agent visivo |
|
||||
| **CrUX API** | LCP/INP/CLS **p75 di utenti reali**, per origin e per URL | stessa chiave | blocco 3 — la distinzione lab/campo |
|
||||
| **Wayback CDX** | storico degli snapshot, diff del testo hero rispetto a 1/3/5 anni fa | no | la tesi "l'azienda è cresciuta, il sito no" |
|
||||
| **RDAP** (`rdap.org`) | età del dominio | no | contesto in blocco 3 |
|
||||
| **Mozilla HTTP Observatory** | voto sugli header di sicurezza | no | segnali di fiducia |
|
||||
| **Fetch diretto** | `robots.txt`, `sitemap.xml` (→ `pagine_indicizzate`), JSON-LD, `hreflang`, impronta della piattaforma | no | blocco 3, finding tecnici |
|
||||
| **Le pagine del sito** | già nello spike: home + fino a 3 pagine per profilo | no | verifica checklist |
|
||||
|
||||
**Perché questo elenco e non altro:** ognuna di queste è una **rilevazione**, non una stima. È esattamente ciò che impone la disciplina sui numeri del piano approvato — un numero entra nel documento solo se misurato. CrUX in particolare porta dati di utenti veri, la cosa più difendibile che si possa scrivere in un audit.
|
||||
|
||||
**Il guadagno più grande è già in casa e viene buttato via:** lo spike chiama PageSpeed e ne estrae 10 numeri. Gli audit Lighthouse coprono da soli una fetta consistente del 52% non verificabile — `color-contrast`, `tap-targets`, `font-size`, `image-alt`, `link-text`, `crawlable-anchors`, `structured-data`, `unsized-images`, `errors-in-console`, `viewport`, `canonical`. Sono verifiche fatte **sul DOM renderizzato**, cioè proprio quello che l'HTML statico non vede.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Il motore
|
||||
|
||||
`src/lib/audit/`, modellato su `src/lib/proposal/` ma multi-step e con fan-out:
|
||||
|
||||
```
|
||||
src/lib/audit/
|
||||
pipeline.ts orchestratore: (auditId) => risultato. Non sa chi lo chiama
|
||||
sources/ raccolta dati, nessun LLM
|
||||
fetch.ts pagine + estrazione testo (dallo spike, quasi invariato)
|
||||
pagespeed.ts PSI: audit completi + screenshot + estrazione scalari
|
||||
crux.ts dati di campo
|
||||
history.ts Wayback CDX + diff
|
||||
signals.ts RDAP, header, robots/sitemap/JSON-LD
|
||||
agents/ un file per sub-agent, ognuno con prompt e schema Zod propri
|
||||
checklist.ts verificatore, Sonnet, batch da 12 per step di funnel
|
||||
visual.ts analisi visiva, Opus con input immagine
|
||||
history.ts scarto fra il sito di allora e l'azienda di oggi, Sonnet
|
||||
technical.ts audit Lighthouse + header + dati strutturati, Sonnet
|
||||
synthesis.ts sintetizzatore, Opus
|
||||
schema.ts Zod per ogni output di sub-agent + per la sintesi
|
||||
```
|
||||
|
||||
**Sequenza.** Raccolta in parallelo (I/O di rete puro) → quattro sub-agent in parallelo, ognuno sul proprio materiale → sintetizzatore che riceve i quattro output e **incrocia**.
|
||||
|
||||
**Cosa vuol dire "incrociate", in concreto.** I sub-agent producono osservazioni, non finding. È il sintetizzatore che le fonde:
|
||||
|
||||
> checklist: "nessun segnale di fiducia sulla scheda prodotto" + tecnico: "nessun dato strutturato `Product`/`Review`" + storico: "il testo dell'hero non cambia dal 2021" + visivo: "le recensioni sono sotto tre schermate di scroll"
|
||||
> → **un solo finding**, con quattro evidenze indipendenti, invece di quattro finding deboli.
|
||||
|
||||
Questo serve la regola di selezione del piano approvato: il documento promette "non un elenco di quaranta punti", e la forza sta nella selezione. Massimo 10 problemi, ordinati per impatto.
|
||||
|
||||
**Tre cose che lo spike non fa e vanno fatte:**
|
||||
|
||||
1. **Validazione Zod di ogni output di modello.** Lo spike fa `as Record<string, unknown>` e stampa. `proposal/schema.ts` è il precedente: `safeParse`, fallimento duro, nessun loop di riparazione.
|
||||
2. **Concorrenza limitata e retry.** Fan-out sì, ma con un tetto (4 chiamate contemporanee) e un retry con backoff sulle 429/529 di Anthropic. Lo spike non ha né l'uno né l'altro.
|
||||
3. **Heartbeat a ogni passo.** `audit_runs.heartbeat_at`; una run senza battito da N minuti va in `error`, "Rilancia" riparte dall'ultimo passo completato. È la mitigazione già prevista per il redeploy che uccide il job.
|
||||
|
||||
**Da riusare invariati dallo spike:** i blocchi `SICUREZZA` e `NUMERI`, la funzione `fence()` che neutralizza i tag di chiusura, e l'estrazione del primo blocco `text` con guardia su `stop_reason === "max_tokens"` (più robusta di `content[0]` in `proposal/agent.ts`).
|
||||
|
||||
**Impronta sul VPS:** I/O di rete e JSON. Nessun processo pesante, nessun Chromium. Il picco è la dimensione dello screenshot in memoria prima dell'invio ad Anthropic — vedi §7.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Schema — differenze rispetto a §5 del piano approvato
|
||||
|
||||
La migration resta `0017_audits.sql`, additiva e idempotente, applicata in prod **prima** del push. Rispetto all'elenco già approvato:
|
||||
|
||||
**Nuova tabella `audit_visits`** — il registro delle singole visite:
|
||||
`id`, `audit_id` CASCADE, `occurred_at` default now, `event` CHECK `('view','print')`, `referrer`, `user_agent`, `ip_hash`. Indice su `(audit_id, occurred_at desc)`.
|
||||
|
||||
L'IP **non si salva in chiaro**: SHA-256 di `ip + NEXTAUTH_SECRET` via Web Crypto, come già si fa per il digest del gate admin in `src/lib/admin-gate.ts`. Serve a distinguere due aperture dello stesso lettore da due lettori diversi, non a identificare qualcuno.
|
||||
|
||||
**Campi aggiunti su `audits`** — separare laboratorio e campo, perché è la distinzione che rende credibile il blocco 3:
|
||||
`lcp_field`, `inp_field`, `cls_field` (numeric, da CrUX, nullable — un sito senza traffico sufficiente non ha dati di campo, ed è un'informazione anch'essa).
|
||||
|
||||
**Restano come da piano approvato** le colonne di roll-up `first_viewed_at` / `last_viewed_at` / `view_count`: sono la lettura veloce per la lista admin, aggiornate insieme alla riga di `audit_visits`.
|
||||
|
||||
**`screenshot_desktop_url` / `screenshot_mobile_url`** ora li scrive la pipeline, non tu.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Immagini
|
||||
|
||||
**Due upload manuali per audit**, non di più: `redesign_prima_url` e `redesign_dopo_url`. JPG, limite **512 KB**. Il componente `ImageUploadField` accetta `image/jpeg|png|webp` — non ha senso rifiutare un PNG per principio — ma il limite di dimensione è quello.
|
||||
|
||||
**Due file scritti dalla pipeline**: gli screenshot PageSpeed mobile e desktop, decodificati da base64 e salvati come JPG sullo stesso volume.
|
||||
|
||||
Quattro file per audit, circa 1,5 MB. Il volume Coolify su `/app/uploads` e la lettura via `src/app/api/uploads/[...path]/route.ts` con guardia sul path traversal restano come da §7 del piano approvato — con un margine molto più comodo di quanto si era dimensionato.
|
||||
|
||||
> ⚠️ **Checkpoint bloccante.** Volume creato in Coolify **prima** del deploy, altrimenti gli upload si perdono a ogni redeploy.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Tracciamento
|
||||
|
||||
Un'isola client `<AuditVisitTracker>` montata nella pagina pubblica chiama una server action fire-and-forget:
|
||||
|
||||
- **all'mount** → evento `view`
|
||||
- **su `window.print()`** e sull'evento `beforeprint` → evento `print`
|
||||
|
||||
La server action, lato server, chiama `getServerSession`: **se c'è una sessione admin non scrive niente.** È così che l'anteprima admin non inquina i numeri — requisito già scritto nella verifica del piano approvato (test 11).
|
||||
|
||||
Perché un'isola client e non una scrittura nel render RSC: la pagina ha `revalidate = 0` e quindi ri-esegue a ogni richiesta, ma scrivere sul DB dentro un render è un anti-pattern Next e conterebbe anche i prefetch e i bot. La convenzione del progetto è comunque "le mutazioni sono Server Actions".
|
||||
|
||||
Lato admin: il registro visite compare nell'editor dell'audit, sotto forma di elenco cronologico.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Rischi da mettere in conto
|
||||
|
||||
- **Lo screenshot a pagina intera può essere altissimo** (una home lunga arriva a 10-15.000 px). Va ridimensionato prima di mandarlo a Opus, o mandato a fette. Non risolto: da misurare sul primo audit vero.
|
||||
- **Latenza PageSpeed**: 30-60 s per strategia, due strategie. Il job in background lo regge, ma incide sul tempo totale — stimare il totale della pipeline dopo il primo giro completo, non prima.
|
||||
- **Wayback e Observatory sono lenti e ballerini.** Ogni fonte deve fallire in modo non fatale, come già fa PageSpeed nello spike (`psi[s] = null` e si prosegue).
|
||||
- **CrUX non risponde per i siti a basso traffico.** Non è un errore: è un dato. Il documento deve saperlo dire ("non ci sono abbastanza visitatori perché Google raccolga dati di campo") invece di lasciare un buco.
|
||||
- **La ripetibilità è già stata vista traballare**: lo step `generale` ha dato 0 non conformi nel giro completo e 2 in quello isolato, a parità di sito e voci. Con il fan-out il rischio non diminuisce. Da tenere sotto osservazione al primo audit di prova.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Da correggere prima di eseguire
|
||||
|
||||
Due cose scritte ieri sono ora sbagliate:
|
||||
|
||||
1. **`CLAUDE.md`, deroga a LOCKED #5** — dice "la copia master è la cartella di cattura locale". Non esiste più nessuna cattura locale. Sostituire con la formulazione di §11 del piano approvato, che è già corretta e non parla di copie locali.
|
||||
2. **`.planning/STATE.md`** — la decisione "il renderer headless gira in LOCALE sul Mac" va riscritta come "nessun renderer headless: il buco a runtime è coperto dagli audit Lighthouse e dallo screenshot PageSpeed". Il *perché* il VPS non regge Chromium resta valido e va tenuto: è la ragione per cui l'opzione non tornerà.
|
||||
|
||||
Stessa correzione nel file di memoria persistente `project_clienthub_vps_no_headless.md`.
|
||||
|
||||
---
|
||||
|
||||
## 9 · File toccati
|
||||
|
||||
**Nuovi** — `src/db/migrations/0017_audits.sql` · `src/lib/audit/pipeline.ts` · `src/lib/audit/sources/{fetch,pagespeed,crux,history,signals}.ts` · `src/lib/audit/agents/{checklist,visual,history,technical,synthesis}.ts` · `src/lib/audit/schema.ts` · `src/lib/audit/template/{v1,index}.ts` · `src/lib/audit-queries.ts` · `src/app/audit/[slug]/page.tsx` · `src/components/public/audit/*` (uno per blocco, più `AuditVisitTracker`) · `src/app/admin/audit/**` · `src/components/admin/audit/AuditEditor.tsx` · `src/components/ui/ImageUploadField.tsx` · `src/app/api/uploads/[...path]/route.ts`
|
||||
|
||||
**Modificati** — `src/db/schema.ts` · `src/proxy.ts` (aggiungere `/audit` al matcher, con `rateLimit`) · `next.config.ts` (`X-Robots-Tag: noindex, nofollow`) · `src/app/globals.css` (blocco `@media print`) · `src/components/admin/AdminSidebar.tsx` · `CLAUDE.md` · `.planning/STATE.md` · Dockerfile + volume Coolify
|
||||
|
||||
**Riusati senza modifiche** — `src/lib/rate-limit.ts` · `src/components/public/proposal/RichText.tsx` · `src/lib/admin-gate.ts` (per l'hash) · `src/app/admin/offers/actions.ts` come modello di editor a payload intero · `@dnd-kit/sortable` per il riordino
|
||||
|
||||
---
|
||||
|
||||
## 10 · Verifica
|
||||
|
||||
Non c'è test suite: **`npm run build` è la verifica di riferimento** (fa il typecheck).
|
||||
|
||||
**Prima di tutto** — la chiave PageSpeed funziona e `fullPageScreenshot` esiste davvero (§1). Se non esiste, fermarsi e rivedere §5.
|
||||
|
||||
Poi, nell'ordine:
|
||||
|
||||
1. `npm run build` pulito
|
||||
2. Migration applicata in prod **prima** del push; le sette tabelle esistono
|
||||
3. Un audit completo su giojello.com: **confrontare la quota di non verificabili con il 52% dello spike**. È la misura che dice se l'approccio senza Chromium ha funzionato
|
||||
4. Ogni numero nel documento consegnato ha una fonte rintracciabile in `audit_runs.raw`. Nessuna percentuale inventata
|
||||
5. Un sito senza dati CrUX: il documento lo dice, non lascia un buco
|
||||
6. Riavviare il container a metà analisi: la run va in `error`, "Rilancia" riparte senza rifare i passi completati
|
||||
7. Upload di un'immagine → redeploy → l'immagine è ancora lì (prova del volume)
|
||||
8. Aprire il documento consegnato in incognito: compare una riga in `audit_visits`. Aprirlo da admin loggato: **non** compare. Premere "Scarica PDF": compare una riga `print`
|
||||
9. Cmd+P sul documento: interruzioni di pagina corrette, slider impilato in due immagini, nessun marcatore di lavorazione sopravvissuto, e in **scala di grigi** impatti e metriche restano distinguibili
|
||||
10. Rete disattivata dopo il primo caricamento: i font restano quelli giusti (prova che sono self-hostati)
|
||||
11. I test 3, 4, 5, 8, 12 e 13 del piano approvato — blocchi condizionali per livello, salvataggio a metà, re-sync degli id dei figli, riordino, congelamento del template, e nessuna voce `registro='volume'` su un brand premium
|
||||
|
||||
⚠️ Playwright non funziona contro `npm run dev` (la CSP blocca `eval`). Vale solo se un giorno servirà un E2E sul portale: usare il build di produzione.
|
||||
@@ -0,0 +1,319 @@
|
||||
# Modifiche all'hub — dashboard, progetti, pipeline
|
||||
|
||||
## Contesto
|
||||
|
||||
Il 2026-08-18 hai elencato una serie di modifiche all'hub divise per sezione
|
||||
(dashboard, progetti, pipeline). La sessione si è fermata sul limite settimanale
|
||||
subito dopo aver lanciato l'esplorazione, e quel lavoro non è mai stato ripreso.
|
||||
Questo piano lo raccoglie.
|
||||
|
||||
Il punto di partenza è che **quasi tutto quello che chiedi è calcolabile con i
|
||||
dati che l'hub già ha**: le categorie di offerta esistono, le fasi e i task hanno
|
||||
uno stato, i pagamenti hanno una data di incasso, le conversazioni sono già
|
||||
aggregate. Serve poco schema nuovo — una sola migration additiva — e molta
|
||||
query + UI.
|
||||
|
||||
L'eccezione è l'ingresso da Whop per gli audit: dipende dal motore di analisi
|
||||
della v2.5, che è fermo alle sole fonti. Hai scelto di fare **prima le modifiche
|
||||
hub e poi il motore**, quindi quel blocco resta documentato ma non costruito.
|
||||
|
||||
### Decisioni prese
|
||||
|
||||
| Domanda | Scelta |
|
||||
|---|---|
|
||||
| Sequenza | Hub prima, motore audit dopo |
|
||||
| Fonte "Audit" negli analytics | È la tua **Entry Offer** — si legge da `offer_macros.category`, come Signature e Retainer |
|
||||
| Data di consegna attesa | **Derivata** da offerta + durata, con **override manuale** opzionale |
|
||||
| Ingresso lead | TidyCal + form sito — vedi il blocco C, dove c'è un vincolo che cambia le carte |
|
||||
|
||||
---
|
||||
|
||||
## Blocco A — Progetti
|
||||
|
||||
Il blocco a rischio più basso e a resa più immediata. Da fare per primo.
|
||||
|
||||
### A1 · Togliere il tab Commenti e il timer dalla lista
|
||||
|
||||
Due rimozioni chieste esplicitamente.
|
||||
|
||||
- **Tab "Commenti"** in [page.tsx:75](src/app/admin/projects/[id]/page.tsx#L75) e
|
||||
[page.tsx:118-120](src/app/admin/projects/[id]/page.tsx#L118-L120), più l'import a riga 8.
|
||||
**Non si perde niente**: ho verificato che `buildEntityMap()` in
|
||||
[conversations-queries.ts:57](src/lib/conversations-queries.ts#L57) cammina
|
||||
clienti → progetti → fasi → task → deliverable e raccoglie *tutti* i commenti
|
||||
con la loro etichetta d'entità. `/admin/conversazioni` è un sovrainsieme
|
||||
stretto di quel tab. Il campo `comments` in `ProjectFullDetail` diventa morto:
|
||||
va tolto anche da [admin-queries.ts:567](src/lib/admin-queries.ts#L567) e dalla query.
|
||||
- **Colonna "Timer"** dalla lista progetti: `<TimerCell>` in
|
||||
[ProjectRow.tsx:85](src/components/admin/ProjectRow.tsx#L85) e l'intestazione in
|
||||
[projects/page.tsx:47](src/app/admin/projects/page.tsx#L47). Il timer resta dove
|
||||
ha senso, dentro il progetto.
|
||||
|
||||
### A2 · Mini-dashboard nel singolo progetto
|
||||
|
||||
Una striscia sopra i tab, prima di `<Tabs>` in
|
||||
[projects/[id]/page.tsx:69](src/app/admin/projects/[id]/page.tsx#L69). **Nessuna
|
||||
query nuova**: `getProjectFullDetail` restituisce già tutto.
|
||||
|
||||
**Finance** — incassato / contrattualizzato / residuo, da `payments` +
|
||||
`offersAcceptedTotal`; ore tracciate e €/h reale da `totalTrackedSeconds` e
|
||||
`targetHourlyRate` (già passato alla pagina a riga 24).
|
||||
|
||||
**Avanzamento** — task `done` su totale, con barra. Stessa aritmetica del
|
||||
`progress_pct` già usato per le fasi.
|
||||
|
||||
Riusa il pattern `MetricCard` di [admin/page.tsx:18](src/app/admin/page.tsx#L18):
|
||||
va estratto in `src/components/admin/MetricCard.tsx` e importato da entrambe.
|
||||
Scrivere la striscia **a token semantici** (`bg-card`, `text-muted-foreground`) —
|
||||
questa route è il cluster peggiore di DEBT-01 (~182 occorrenze di palette raw) e
|
||||
non va peggiorata.
|
||||
|
||||
### A3 · Timer per task e fase
|
||||
|
||||
Oggi `time_entries` ha solo `project_id`
|
||||
([schema.ts:245](src/db/schema.ts#L245)). Servono due colonne nullable.
|
||||
|
||||
- **Migration `0018`** (dettagli in fondo): `phase_id`, `task_id` su
|
||||
`time_entries`, entrambe `ON DELETE SET NULL`. Cancellare un task **non deve**
|
||||
cancellare il tempo tracciato: è storico fatturabile, l'entry ricade a livello
|
||||
progetto. `project_id` resta obbligatoria, quindi ogni entry è sempre
|
||||
attribuita.
|
||||
- **Server actions** in [timer-actions.ts](src/app/admin/timer-actions.ts):
|
||||
`startTimer` prende `phaseId`/`taskId` opzionali; stessa cosa per
|
||||
`addManualTimeEntry`. La regola "un solo timer attivo alla volta" (righe 19-38)
|
||||
resta com'è — vale globalmente, non per task.
|
||||
- **UI**: `<TimerCell>` su ogni riga task dentro
|
||||
[PhasesTab.tsx](src/components/admin/tabs/PhasesTab.tsx), con il totale della
|
||||
fase come somma dei suoi task. `TimerTab` continua a mostrare il totale progetto.
|
||||
|
||||
---
|
||||
|
||||
## Blocco B — Dashboard
|
||||
|
||||
### B1 · Analytics per linea di prodotto
|
||||
|
||||
Tre righe — **Entry (Audit), Signature, Retainer** — lette da
|
||||
`offer_macros.category`, che è già una taxonomy editabile da
|
||||
`/admin/impostazioni` ([taxonomy.ts:37](src/lib/taxonomy.ts#L37)). In produzione
|
||||
oggi ci sono esattamente quelle tre categorie.
|
||||
|
||||
Per categoria:
|
||||
|
||||
- **Iniziati questo mese** — `count(project_offers)` con `start_date` nel mese corrente.
|
||||
- **Totale anno** — `count` + somma `accepted_total` con `start_date` nell'anno.
|
||||
- **Incassato** — `payments` in stato `saldato` con `paid_at` nell'anno.
|
||||
|
||||
L'incasso ha un problema di attribuzione da risolvere esplicitamente: i pagamenti
|
||||
stanno sul **progetto**, non sull'offerta. La regola:
|
||||
|
||||
1. progetto con **una** offerta → tutto l'incasso va a quella categoria;
|
||||
2. progetto con **più** offerte → ripartito in proporzione ai rispettivi `accepted_total`;
|
||||
3. progetto **senza** offerta → riga separata **"Senza offerta"**, mostrata a video.
|
||||
|
||||
Il terzo caso non va nascosto. Oggi in prod ci sono 5 progetti e 2 righe in
|
||||
`project_offers`: la maggior parte dell'incassato finirebbe lì, e vederlo è il
|
||||
modo per accorgersene.
|
||||
|
||||
Nuovo modulo `src/lib/product-analytics.ts` (non gonfiare `analytics-queries.ts`),
|
||||
nuovo componente `src/components/admin/dashboard/ProductBreakdown.tsx`.
|
||||
|
||||
> **Nota da verificare al primo giro:** l'unica Entry Offer in produzione si
|
||||
> chiama *"Sblocca Business"*. Se l'audit è un prodotto diverso, va creata la sua
|
||||
> `offer_macro` con categoria `Entry Offer` — è configurazione, non codice.
|
||||
|
||||
### B2 · Timeline delle consegne
|
||||
|
||||
Riguarda i progetti che **si consegnano** — Entry e Signature. I retainer sono
|
||||
continuativi e non hanno una consegna: restano fuori, filtrando su
|
||||
`offer_macros.offer_type = 'una_tantum'`.
|
||||
|
||||
Per ogni progetto non archiviato:
|
||||
|
||||
- **Consegna attesa** = `projects.due_date` se valorizzata, altrimenti
|
||||
`project_offers.start_date + offer_micros.duration_months`. La colonna
|
||||
`due_date` arriva con la migration 0018 ed è l'override manuale che hai chiesto.
|
||||
- **% completamento** = task `done` / task totali.
|
||||
- **% tempo trascorso** = `(oggi − inizio) / (consegna − inizio)`.
|
||||
- **Semaforo** — soglia ±10 punti: `in linea` dentro la banda, `in ritardo` se il
|
||||
completamento è sotto, `in anticipo` se è sopra. Un progetto oltre la data di
|
||||
consegna e non completo è `in ritardo` a prescindere.
|
||||
|
||||
I progetti senza scadenza calcolabile vanno elencati sotto come **"senza
|
||||
scadenza"** invece di sparire — altrimenti un progetto senza offerta assegnata
|
||||
diventa invisibile proprio nella vista che dovrebbe segnalarlo.
|
||||
|
||||
Query in `src/lib/delivery-queries.ts`, componente
|
||||
`src/components/admin/dashboard/DeliveryTimeline.tsx`. `StatusBadge` per il
|
||||
semaforo, Geist Mono per date e percentuali.
|
||||
|
||||
### B3 · Inbox
|
||||
|
||||
**Questo esiste già.** [MessagesWidget.tsx](src/components/admin/dashboard/MessagesWidget.tsx)
|
||||
mostra i clienti con messaggi non letti, l'anteprima dell'ultimo messaggio e il
|
||||
link "Rispondi →" verso `/admin/conversazioni`. È il widget stretto in colonna
|
||||
1/3, in fondo: probabilmente non l'hai visto perché sta sotto la piega.
|
||||
|
||||
Quindi non si costruisce, si promuove:
|
||||
|
||||
- fascia **a piena larghezza in cima** alla dashboard, sopra i KPI, e solo quando
|
||||
c'è almeno un non letto;
|
||||
- 6 righe invece di 4, con **data relativa** e **etichetta dell'entità**
|
||||
(`lastMessageAt` e `lastEntityLabel` sono già in `ConversationSummary`,
|
||||
[conversations-queries.ts:8](src/lib/conversations-queries.ts#L8) — oggi non
|
||||
vengono usati);
|
||||
- anteprima più lunga del messaggio.
|
||||
|
||||
Nuovo layout in [admin/page.tsx](src/app/admin/page.tsx): Inbox → KPI →
|
||||
Timeline consegne → Prodotti → il resto.
|
||||
|
||||
---
|
||||
|
||||
## Blocco C — Pipeline: ingresso lead
|
||||
|
||||
### Il vincolo che cambia le carte
|
||||
|
||||
**TidyCal non ha webhook.** È scritto nella loro FAQ: nessun supporto nativo, e
|
||||
la strada suggerita è passare da Zapier / Make / Pabbly. Quello che TidyCal *ha*
|
||||
è una REST API con OAuth 2.0 e **Personal Access Token disponibile su tutti i
|
||||
piani** (si crea da `tidycal.com/integrations/oauth`), con endpoint sulle
|
||||
prenotazioni.
|
||||
|
||||
Elementor Pro, invece, ha un'azione **Webhook** nativa in "Actions After Submit":
|
||||
si incolla un URL e lui fa POST dei campi del form. Se invece andate su Astro,
|
||||
il POST lo scrivete voi. In entrambi i casi è una chiamata in ingresso.
|
||||
|
||||
Da qui la forma della soluzione: **un endpoint solo, sia per il form che per
|
||||
TidyCal**, e per TidyCal un pezzo in più che va a prendersi le prenotazioni.
|
||||
|
||||
### C1 · Endpoint di ingresso — `POST /api/webhooks/lead`
|
||||
|
||||
Un solo endpoint, indipendente da chi chiama.
|
||||
|
||||
- **Guardia**: header `x-webhook-secret` confrontato con una env nuova
|
||||
(`LEAD_WEBHOOK_SECRET`), stesso pattern di
|
||||
[validate-slug/route.ts:7](src/app/api/internal/validate-slug/route.ts#L7) —
|
||||
ma **senza** la scorciatoia "se non è configurato passa": questa route è
|
||||
esposta a internet, secret assente deve voler dire 403.
|
||||
- **Rate limit** con `rateLimit()` da [rate-limit.ts](src/lib/rate-limit.ts),
|
||||
bucket per IP. `src/proxy.ts` **non intercetta** `/api/*` (matcher a riga 120),
|
||||
quindi la difesa è tutta dentro la route.
|
||||
- **Payload** validato con Zod: `name` obbligatorio, `email`/`phone`/`company`/
|
||||
`notes` opzionali, più un `source` libero. Mappatura campi in un modulo a
|
||||
parte così aggiungere una sorgente non tocca la route.
|
||||
- **Effetto**: crea un `lead` in stato `contacted` riusando le funzioni di
|
||||
[lead-service.ts](src/lib/lead-service.ts). Se l'email esiste già, aggiorna
|
||||
`last_contact_date` invece di duplicare.
|
||||
|
||||
Questo è tutto ciò che serve per Elementor, ed è pronto in anticipo per Astro:
|
||||
la decisione Elementor-vs-Astro **non blocca niente**, perché il contratto è
|
||||
un POST JSON in entrambi i casi.
|
||||
|
||||
### C2 · TidyCal — sincronizzazione a polling
|
||||
|
||||
Senza webhook, l'unico modo pulito senza terze parti è andare a leggere.
|
||||
|
||||
- `src/lib/tidycal.ts` — client con Personal Access Token in
|
||||
`TIDYCAL_ACCESS_TOKEN`, che chiede le prenotazioni create dall'ultimo giro.
|
||||
- `GET /api/internal/tidycal-sync` — protetta da `INTERNAL_SECRET`, come le due
|
||||
internal esistenti. Per ogni prenotazione nuova crea un lead con nome, email e
|
||||
la data della call in `next_action_date`, e registra un'`activity` di tipo
|
||||
`meeting`. Idempotente sull'id TidyCal, così rilanciarla non duplica.
|
||||
- **Schedulazione**: Coolify ha gli Scheduled Tasks. Un `curl` ogni 15 minuti
|
||||
verso quella route. Non serve infrastruttura cron nell'app — e infatti nel
|
||||
repo non ce n'è.
|
||||
|
||||
**Prima di scrivere il client va guardata la documentazione vera dell'API**, che
|
||||
è dietro login (`tidycal.com/integrations` → API Keys) e non è indicizzata: forma
|
||||
esatta dell'endpoint prenotazioni, filtro per data, paginazione. È il primo passo
|
||||
del blocco, non un dettaglio: vale la regola già scritta in memoria — *ogni
|
||||
estrazione da API di terzi va vista funzionare, non dedotta dai docs*.
|
||||
|
||||
Se l'API risultasse inadatta, il ripiego è Zapier/Make che POSTa su C1, che a
|
||||
quel punto esiste già.
|
||||
|
||||
### C3 · "Alleggerire l'hub"
|
||||
|
||||
Questa richiesta non ha ancora un perimetro. Non la pianifico al buio: quando i
|
||||
blocchi A e B sono in produzione ti porto l'elenco di cosa è davvero poco usato
|
||||
(`/admin/quotes` e `/admin/preventivi` convivono, `service_catalog` e
|
||||
`offer_services` sono legacy da DEBT-02) e decidi tu cosa togliere. Cancellare
|
||||
route è irreversibile e va fatto guardando, non indovinando.
|
||||
|
||||
---
|
||||
|
||||
## Blocco D — Whop → audit *(rinviato, dipende dal motore)*
|
||||
|
||||
L'ingresso Whop è già predisposto nello schema: `audits.origin` accetta
|
||||
`'whop'` e `audits.external_ref` tiene il riferimento esterno
|
||||
([schema.ts:688-690](src/db/schema.ts#L688-L690)).
|
||||
|
||||
Ma "partono gli agent e fanno il lavoro" oggi **non è possibile**: in
|
||||
`src/lib/audit/` ci sono solo le cinque fonti; agent, sintetizzatore e pipeline
|
||||
(AUD-06 → AUD-11) non sono scritti. Costruire il webhook adesso significa
|
||||
costruire un innesco che non innesca niente.
|
||||
|
||||
Quando il motore c'è, il blocco è: `POST /api/webhooks/whop` con verifica firma →
|
||||
crea cliente + progetto con la Entry Offer assegnata (così l'audit compare
|
||||
automaticamente in B1 e B2) → crea l'`audit` con `origin='whop'` → accoda la run.
|
||||
|
||||
---
|
||||
|
||||
## Migration 0018 — additiva
|
||||
|
||||
`src/db/migrations/0018_timer_scope_and_due_date.sql`, in parallelo alle stesse
|
||||
modifiche in [schema.ts](src/db/schema.ts) (drizzle-kit generate è rotto, i due
|
||||
file si tengono in pari a mano).
|
||||
|
||||
```
|
||||
ALTER TABLE time_entries ADD COLUMN phase_id text REFERENCES phases(id) ON DELETE SET NULL;
|
||||
ALTER TABLE time_entries ADD COLUMN task_id text REFERENCES tasks(id) ON DELETE SET NULL;
|
||||
CREATE INDEX time_entries_phase_idx ON time_entries(phase_id);
|
||||
CREATE INDEX time_entries_task_idx ON time_entries(task_id);
|
||||
ALTER TABLE projects ADD COLUMN due_date timestamptz;
|
||||
```
|
||||
|
||||
Solo `ADD COLUMN` e `CREATE INDEX`: nessun DROP, nessun TRUNCATE, nessuna colonna
|
||||
rimossa — conforme a Data Safety (LOCKED). Le righe esistenti di `time_entries`
|
||||
restano valide con le due colonne a NULL, cioè "tempo di progetto".
|
||||
|
||||
**Ordine di applicazione**, come da CLAUDE.md: prima a produzione via
|
||||
`ssh root@178.104.27.55` + `docker exec`, **poi** il push del codice che le usa.
|
||||
|
||||
---
|
||||
|
||||
## Ordine di esecuzione
|
||||
|
||||
1. **A1** — le due rimozioni (nessuna dipendenza, effetto immediato)
|
||||
2. **Migration 0018** in produzione
|
||||
3. **A3** timer su task/fase · **A2** mini-dashboard progetto
|
||||
4. **B3** inbox (piccola) → **B1** analytics prodotto → **B2** timeline consegne
|
||||
5. **C1** endpoint lead → **C2** TidyCal, dopo aver letto l'API vera
|
||||
6. **C3** e **D** dopo, con le informazioni che oggi non abbiamo
|
||||
|
||||
Commit per unità logica, come negli ultimi quattro.
|
||||
|
||||
## Verifica
|
||||
|
||||
Non c'è suite di test in questo progetto: **`npm run build` è la verifica di
|
||||
riferimento** (fa il typecheck), più `npm run lint`.
|
||||
|
||||
Controlli manuali, in ordine:
|
||||
|
||||
- **A1** — il progetto non mostra più il tab Commenti; gli stessi commenti si
|
||||
vedono ancora in `/admin/conversazioni` con la loro etichetta d'entità; la
|
||||
lista progetti non ha più la colonna Timer.
|
||||
- **A3** — timer avviato su un task: `time_entries` ha `task_id` valorizzato; il
|
||||
totale della fase è la somma dei suoi task; il totale progetto non cambia.
|
||||
Poi cancellare quel task e verificare che **l'entry sopravviva** con
|
||||
`task_id` a NULL.
|
||||
- **A2 / B1 / B2** — confrontare ogni numero a video con la stessa query lanciata
|
||||
a mano su prod via `psql`. Su un dataset di 5 progetti si controllano tutti a
|
||||
occhio; è l'unico momento in cui questo è ancora possibile.
|
||||
- **B2** — mettere una `due_date` manuale su un progetto e verificare che vinca
|
||||
sulla data derivata dall'offerta.
|
||||
- **C1** — `curl` con secret giusto (lead creato), con secret sbagliato (403),
|
||||
senza secret (403), e ripetuto per verificare che non duplichi.
|
||||
- Dual light/dark su ogni schermata nuova, e nessuna classe palette raw.
|
||||
|
||||
Il portale cliente non va toccato da nessuna di queste modifiche: `client-view.ts`
|
||||
non si tocca, quindi il vincolo LOCKED #2 non è in gioco.
|
||||
@@ -16,7 +16,9 @@ Dopo **ogni** unità di lavoro conclusa — una fase, una migration applicata, u
|
||||
|
||||
## Cosa scrivere nella memoria persistente
|
||||
|
||||
`~/.claude/projects/-Users-simonecavalli-Vault-IAMCAVALLI/memory/` — un file per fatto, più la riga di indice in `MEMORY.md`.
|
||||
`~/.claude/projects/-Users-simonecavalli-Vault-IAMCAVALLI-hub/memory/` — un file per fatto, più la riga di indice in `MEMORY.md`.
|
||||
|
||||
⚠️ **La chiave finisce in `-hub`.** Quella senza suffisso (`…-Vault-IAMCAVALLI/memory/`) è la memoria del *workspace*, un altro posto con altri file: scriverci un fatto di ClientHub significa non ritrovarlo più, perché a inizio sessione qui viene iniettata solo quella con `-hub`. Da non confondere nemmeno con `.claude/memory/`, che è versionata nel repo — la distinzione sta in [`../CLAUDE.md`](../CLAUDE.md).
|
||||
|
||||
Ci va quello che **non si deduce dal repo**: decisioni e il loro perché, vincoli operativi, cose che sono state provate e non funzionano. Non ci va quello che il codice già dice: struttura, cronologia dei fix, contenuto di `CLAUDE.md`.
|
||||
|
||||
|
||||
+22
-11
@@ -18,6 +18,28 @@
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit|MultiEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guardia-migration.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit|MultiEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guardia-token.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
@@ -28,16 +50,5 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"impeccable@impeccable": true
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"impeccable": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "pbakaus/impeccable"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: audit
|
||||
description: Far girare le fonti di rilevazione dell'audit sito di ClientHub su un URL e capire cosa e' stato misurato e cosa no. Da usare quando si lavora al motore audit v2.5, quando serve una rilevazione su un sito reale, quando si vuole sapere se una fonte risponde, o prima di scrivere qualsiasi pezzo del documento di audit.
|
||||
---
|
||||
|
||||
# Audit — le rilevazioni, e cosa vale come misura
|
||||
|
||||
Il motore v2.5 **non e' scritto**. Quello che esiste, e che questa skill mette in moto,
|
||||
sono le fonti di rilevazione: nessun LLM, nessun database, nessun browser headless.
|
||||
|
||||
## Due attrezzi, due domande diverse
|
||||
|
||||
| Comando | Cosa fa | Quando |
|
||||
|---|---|---|
|
||||
| `npx tsx scripts/audit-fonti.ts <url>` | Le **cinque fonti** di `src/lib/audit/sources/` — pagine, CrUX, PageSpeed, storico Wayback, segnali. Puramente meccanico | «Cosa si riesce a misurare su questo sito?» |
|
||||
| `npx tsx scripts/spike-audit.ts <url>` | Verifica le **264 voci di checklist** con Sonnet 5, poi sintetizza con Opus 5. Volutamente **isolato** da `src/`: non importa nulla, non tocca il DB | «Cosa c'e' che non va, in parole?» |
|
||||
|
||||
Opzioni comuni: `--profilo=servizi|ecommerce`, `--no-psi` (salta PageSpeed, che da solo
|
||||
vale meta' del tempo). Riferimento misurato il 2026-08-26 su `giojello.com`: cinque fonti
|
||||
su cinque, **42,7 s** in tutto, PageSpeed 34,2 s. Se una fonte tace, **quella e' la notizia** —
|
||||
va riportata, non aggirata.
|
||||
|
||||
`PAGESPEED_API_KEY` viene letta dall'ambiente o da `.env.local`. Senza, PageSpeed e CrUX
|
||||
rispondono a vuoto **senza errore**: lo script lo dice in testa, leggerlo.
|
||||
|
||||
Il grezzo finisce in `audit-fonti-<dominio>.json` (gitignorato). E' li' che ogni numero del
|
||||
documento dovra' essere rintracciabile.
|
||||
|
||||
## Le tre regole che il motore erediterà
|
||||
|
||||
Non sono preferenze. Sono gia' costate, e stanno per esteso in `STATUS.md` § Lezioni operative.
|
||||
|
||||
1. **Un numero entra solo se e' stato misurato.** Rintracciabile nel grezzo, e nel motore in
|
||||
`audit_runs.raw`. Nessun numero dedotto, arrotondato o ricordato.
|
||||
|
||||
2. **Laboratorio e campo non si fondono — la differenza *e'* il risultato.** Su giojello.com
|
||||
Lighthouse dava `server-response-time` **7 ms** e CrUX TTFB p75 **3.553 ms con l'1% nel
|
||||
verde**: il server risponde in fretta al datacenter Google e lento a tutti gli altri. Due
|
||||
numeri con lo stesso nome verrebbero fusi in uno solo — per questo il campo si chiama
|
||||
`risposta_server_ms` e non `ttfb_ms`.
|
||||
|
||||
3. **Un punteggio va sempre con la sua data.** Performance mobile 52, poi 64 sullo stesso sito
|
||||
mezz'ora dopo. Mai presentato come una costante del sito.
|
||||
|
||||
E una regola di metodo che vale per ogni fonte nuova: **ogni estrazione da un'API di terzi va
|
||||
vista funzionare, non dedotta dai docs.** Scrivendo `sources/`, due estrazioni prese dalla
|
||||
documentazione hanno restituito valori vuoti *senza errore* — `largest-contentful-paint-element`
|
||||
non esiste piu' e `configSettings.screenEmulation` non esiste affatto nelle risposte pubbliche.
|
||||
Trovate solo perche' le fonti sono state fatte girare su un sito vero.
|
||||
|
||||
## Perche' niente browser headless
|
||||
|
||||
Misurato il 2026-08-17 sul VPS: **1,5 GB di RAM liberi su 3,8**, Chromium ne prende 500 MB–1 GB
|
||||
→ OOM kill sui servizi con dati reali. Verificato il 2026-08-18 che non serve comunque: 153 voci
|
||||
si verificano sul DOM renderizzato che PageSpeed restituisce, e lo screenshot buono e'
|
||||
`final-screenshot`, non `fullPageScreenshot`.
|
||||
|
||||
## Lo stato di v2.5, per non ripartire dal posto sbagliato
|
||||
|
||||
**In pausa dal 2026-08-19** per scelta: prima le modifiche all'hub, poi il motore.
|
||||
|
||||
| Pezzo | Dove | Stato |
|
||||
|---|---|---|
|
||||
| Schema, 7 tabelle + rubrica 264 voci | `0017_audits.sql`, `checklist_items` | in produzione |
|
||||
| Le cinque fonti | `src/lib/audit/sources/` | **in prod ma inerti**: nessuna route le chiama |
|
||||
| Agent, sintetizzatore, pipeline, editor, pagina | `src/lib/audit/`, `src/app/{admin/audit,audit}` | **da scrivere** |
|
||||
|
||||
I piani stanno in [`../../plans/`](../../plans/): `v2.5-audit-documento.md` (i tre livelli
|
||||
Radiografia / Prima-Dopo / Rotta come configurazioni di **un unico** documento) e
|
||||
`v2.5-audit-motore.md` (raccolta in parallelo → quattro sub-agent → sintetizzatore che
|
||||
**incrocia** le osservazioni in massimo 10 finding).
|
||||
|
||||
## L'agente, quando lo progetteremo
|
||||
|
||||
Va in `.claude/agents/audit-*.md`, non qui. Non esiste ancora e non va abbozzato: il design
|
||||
dei quattro sub-agent cambiera' scrivendo il motore. Quando nascera' eredita le tre regole
|
||||
qui sopra — sono il perimetro, non il contorno.
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: preventivo
|
||||
description: Lavorare sulla pipeline che genera i preventivi di ClientHub (src/lib/proposal/) senza romperla. Da usare quando si modifica il prompt, lo schema Zod, il montaggio o la resa di un preventivo, quando una generazione fallisce con "Contenuto AI non valido", quando una sezione del documento esce vuota, o prima di pubblicare una proposta a un cliente.
|
||||
---
|
||||
|
||||
# Preventivo — la catena e come non spezzarla
|
||||
|
||||
Il preventivo lo genera **l'app**, da `/admin/preventivi/genera`. Questa skill non contiene
|
||||
un prompt di generazione e non ne va aggiunto uno: il prompt vive in `agent.ts` ed e' l'unico.
|
||||
Un secondo prompt qui resterebbe indietro rispetto a quello vero senza che nessuno se ne accorga.
|
||||
|
||||
## La catena: quattro file che devono dire la stessa cosa
|
||||
|
||||
```
|
||||
src/lib/proposal/agent.ts il prompt chiede N campi ─┐
|
||||
src/lib/proposal/schema.ts lo Zod pretende quegli N campi │ se non
|
||||
src/lib/proposal/assemble.ts li impacchetta con prezzi+profilo │ coincidono,
|
||||
src/components/public/proposal/ ProposalDeck + sections/ li resa ─┘ si rompe
|
||||
```
|
||||
|
||||
**Si tocca il prompt, si riapre lo schema. Sempre.** I due fallimenti hanno forma diversa e
|
||||
solo uno si vede subito:
|
||||
|
||||
| Cosa hai fatto | Cosa succede |
|
||||
|---|---|
|
||||
| Campo aggiunto allo **schema**, non al prompt | `ProposalContentSchema.safeParse` fallisce → **ogni** generazione muore con «Contenuto AI non valido». Rumoroso, si scopre subito |
|
||||
| Campo aggiunto al **prompt**, non allo schema | Zod lo scarta in silenzio. Il documento esce senza quella parte, e te ne accorgi davanti al cliente |
|
||||
| Campo nello schema, nessuna `<Section>` che lo legge | Generazione verde, sezione assente. Il piu' subdolo: niente segnala l'errore |
|
||||
|
||||
Quando aggiungi un campo, il giro completo e' **quattro file**: prompt in `buildUserPrompt`,
|
||||
schema Zod, eventuale passaggio in `assembleProposal`, e la sezione in
|
||||
`src/components/public/proposal/sections/` piu' la riga in `ProposalDeck.tsx` che la monta.
|
||||
I vincoli di cardinalita' stanno nello schema (`.min(3).max(5)` sui problemi, `.length(5)` sui
|
||||
nodi del diagramma, `.min(4).max(10)` sulla matrice): se li cambi li' e non nel prompt, il
|
||||
modello continua a produrre il numero vecchio e Zod lo rifiuta.
|
||||
|
||||
## Prezzi: cosa puo' vedere il cliente
|
||||
|
||||
Vincolo **LOCKED #2** (`../../CLAUDE.md`): al cliente vanno i totali, mai le righe di prezzo.
|
||||
|
||||
`PricingSection.tsx` renderizza `tier.publicPrice ?? tier.servicesTotal` e il **nome** dei
|
||||
servizi — corretto. Ma `assembleProposal` mette in `content.offer.tiers[].services[].unitPrice`
|
||||
anche il prezzo unitario, e `ProposalDeck` e' `"use client"`: riceve l'intero `proposal` come
|
||||
prop da un server component, quindi **tutto** l'oggetto finisce serializzato nel payload RSC
|
||||
della pagina, renderizzato o no.
|
||||
|
||||
E' la stessa trappola del gate OTP annotata in `STATUS.md` — *sparire a schermo non e' sparire*.
|
||||
Prima di toccare la pagina pubblica, e prima di mandare un preventivo a un cliente che potrebbe
|
||||
aprire il sorgente:
|
||||
|
||||
```bash
|
||||
curl -s https://<host>/preventivo/<slug> > /tmp/p.html
|
||||
LC_ALL=C grep -c unitPrice /tmp/p.html # atteso a regime: 0
|
||||
```
|
||||
|
||||
Se e' > 0, la correzione non e' nascondere la sezione: e' una proiezione client-safe in
|
||||
`assemble.ts` o al confine del componente, come gia' fa `src/lib/client-view.ts` per il portale.
|
||||
|
||||
## Prima di pubblicare
|
||||
|
||||
1. **Preflight sui dati finti** — `./check-profilo.sh` da questa cartella. `profile.ts` e' uno
|
||||
**snapshot**: quello che c'e' dentro al momento della generazione finisce in
|
||||
`proposals.content` e ci resta anche se poi correggi il file.
|
||||
2. **Le citazioni sono verbatim o non sono.** Il prompt lo impone; verificarlo a campione contro
|
||||
il transcript e' il controllo che nessuna macchina fa al posto tuo. Una citazione inventata
|
||||
in un preventivo e' peggio di un preventivo senza citazioni.
|
||||
3. **Copy** — italiano, registro di `../../../../brand/voce.md`, e **nessun numero che non stia
|
||||
in `../../../../brand/prove.md` marcato divulgabile** (`../../../../.claude/rules/lingua-e-tono.md`).
|
||||
⚠️ `brand/` sta **fuori dal repo hub**: su un clone senza il workspace questo passo si salta
|
||||
dichiarandolo, non si finge di averlo fatto.
|
||||
4. **Stato** — `draft` non e' visibile (la pagina risponde «non ancora disponibile»).
|
||||
Pubblicare = `publishProposal` in `src/app/admin/preventivi/actions.ts`.
|
||||
|
||||
## Come si prova davvero
|
||||
|
||||
- `npm run build` e' **la verifica di riferimento**: non esiste test suite, e il build fa il
|
||||
typecheck. Verde qui significa «i tipi tornano», non «il documento e' giusto».
|
||||
- Per vedere l'output serve una **generazione vera** dall'admin, con un'offerta e almeno un
|
||||
transcript. In locale oggi **non si puo'**: `.env.local` non autentica piu' contro il DB
|
||||
(dal 2026-08-21, vedi `STATUS.md`). Si guarda in produzione.
|
||||
- Un preventivo si legge a schermo prima di mandarlo. «Buildato» non e' «funziona», e
|
||||
«generato» non e' «verificato».
|
||||
|
||||
## Note sulla chiamata al modello
|
||||
|
||||
`agent.ts` usa `max_tokens: 8192` per uno schema che chiede fino a 5 problemi + 5 soluzioni +
|
||||
matrice. Se la risposta viene troncata, il fallimento **non** dice «troncata»: dice
|
||||
«L'AI ha prodotto JSON non valido», e manda a cercare nel posto sbagliato. Se capita,
|
||||
controllare `message.stop_reason === "max_tokens"` prima di dare la colpa al parsing.
|
||||
Executable
+49
@@ -0,0 +1,49 @@
|
||||
#!/usr/bin/env bash
|
||||
# Preflight: src/lib/proposal/profile.ts contiene dati placeholder?
|
||||
#
|
||||
# profile.ts e' uno SNAPSHOT: finisce dentro proposals.content al momento della
|
||||
# generazione e ci resta. Un placeholder spedito una volta non si corregge piu'
|
||||
# modificando il file — va rigenerato il preventivo.
|
||||
#
|
||||
# exit 0 = pulito · exit 1 = placeholder trovati
|
||||
set -uo pipefail
|
||||
|
||||
ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
|
||||
F="$ROOT/src/lib/proposal/profile.ts"
|
||||
[ -f "$F" ] || { echo "profile.ts non trovato in $F" >&2; exit 1; }
|
||||
|
||||
# Ogni riga: etichetta|regex. Sono i segni concreti di "da riempire".
|
||||
PATTERNS=(
|
||||
'testimonianza segnaposto|→ Aggiungere'
|
||||
'nome cliente finto|"Cliente [0-9]"'
|
||||
'ruolo generico|role: "Professione"'
|
||||
'campo da compilare|// → '
|
||||
'dominio sbagliato (il brand e iamcavalli.net)|iamcavalli\.com'
|
||||
)
|
||||
|
||||
TROVATI=0
|
||||
for p in "${PATTERNS[@]}"; do
|
||||
ETICHETTA="${p%%|*}"; RE="${p#*|}"
|
||||
N=$(grep -cE "$RE" "$F" || true)
|
||||
if [ "$N" -gt 0 ]; then
|
||||
printf ' ✗ %-48s %s occorrenz%s\n' "$ETICHETTA" "$N" "$([ "$N" = 1 ] && echo a || echo e)"
|
||||
TROVATI=$((TROVATI + N))
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$TROVATI" -gt 0 ]; then
|
||||
cat >&2 <<'MSG'
|
||||
|
||||
BLOCCO — profile.ts spedisce dati placeholder in ogni preventivo generato.
|
||||
|
||||
Non si riempiono a occhio: i numeri divulgabili stanno in brand/prove.md, che oggi
|
||||
e' ancora `stato: scheletro-intervista`. Finche' non sono verificati, la mossa giusta
|
||||
non e' inventare — e' non renderizzare il blocco.
|
||||
|
||||
Regola: ../../../.claude/rules/lingua-e-tono.md — «un numero affermato con sicurezza e
|
||||
mai verificato e' il modo piu' veloce per bruciare la credibilita' che il tono costruisce».
|
||||
MSG
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo " ✓ profile.ts pulito"
|
||||
@@ -15,3 +15,15 @@ INTERNAL_SECRET=generate-with-openssl-rand-base64-32
|
||||
# RESEND_FROM deve usare un dominio verificato su Resend
|
||||
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxx
|
||||
RESEND_FROM=Nome Mittente <no-reply@iamcavalli.net>
|
||||
|
||||
# Base pubblica dei link nelle email (pulsante "Apri la conversazione" della
|
||||
# notifica di tag). Opzionale: se manca si usa NEXTAUTH_URL, che in ogni
|
||||
# ambiente e' gia' l'origine giusta. Serve solo se le due devono divergere.
|
||||
# APP_BASE_URL=https://hub.iamcavalli.net
|
||||
|
||||
# Ingresso lead da fuori (form del sito, bridge Zapier/Make) su
|
||||
# POST /api/webhooks/lead, header x-webhook-secret.
|
||||
# A differenza di INTERNAL_SECRET questa route e' esposta a internet: se la
|
||||
# variabile manca, la route risponde 403 invece di lasciar passare.
|
||||
# Generate with: openssl rand -base64 32
|
||||
LEAD_WEBHOOK_SECRET=generate-with-openssl-rand-base64-32
|
||||
|
||||
@@ -46,3 +46,9 @@ yarn-error.log*
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
# Output degli spike audit (dati di siti di clienti, non vanno committati)
|
||||
spike-audit-*.json
|
||||
|
||||
# Grezzo delle rilevazioni audit (npx tsx scripts/audit-fonti.ts)
|
||||
audit-fonti-*.json
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# Design System — Offer Studio UI direction (v2.1)
|
||||
|
||||
**Definito:** 2026-06-13 (via skill `ui-ux-pro-max`)
|
||||
**Scope:** Applies to Phase 11 (Catalog DB-view), 12 (Offer composition/DnD), 13 (Servizi Attivi), 14 (CRM Attio-style) — any "database view" table in `/admin/*`.
|
||||
|
||||
## Direzione
|
||||
|
||||
ClickUp / Pipedrive: dense ma leggibile, flat, zero decorazione. **Pattern:** Minimalism & Swiss Style + Flat Design — grid-based, alto contrasto, hover/transition rapidi (150-250ms), nessuna ombra/gradiente pesante.
|
||||
|
||||
## Brand tokens — INVARIATI (da `src/app/globals.css`)
|
||||
|
||||
Non introdurre una nuova palette: ClickUp/Pipedrive è una direzione di LAYOUT/interazione, non di colore. Il brand iamcavalli resta:
|
||||
|
||||
| Token | Valore | Uso |
|
||||
|---|---|---|
|
||||
| `--color-primary` | `#1A463C` (verde scuro) | azioni primarie, focus ring, link attivi |
|
||||
| `--color-accent` | `#DEF168` (lime) | highlight/badge di stato attivo, CTA secondarie |
|
||||
| `--color-background` | `#ffffff` | sfondo pagina/tabella |
|
||||
| `--color-muted` / `--color-bg-subtle` | `#f9f9f9` | righe alternate, header tabella, quick-add row |
|
||||
| `--color-border` | `#e5e7eb` | bordi cella sottili (1px), MAI ombre pesanti |
|
||||
| `--color-foreground` | `#1a1a1a` | testo primario |
|
||||
| `--color-muted-foreground` | `#71717a` | placeholder, metadati, celle vuote |
|
||||
| Font | Geist Sans (già configurato) | nessun cambio — coerente con "Minimal Swiss" |
|
||||
|
||||
## Pattern tabella database-view (Phase 11-13)
|
||||
|
||||
- **Riga**: altezza compatta (~40px), padding orizzontale `px-3`, bordo inferiore `border-border` 1px — NO bordi verticali tra celle (look ClickUp, non Excel)
|
||||
- **Inline edit**: click su cella → diventa `<input>`/`<select>` borderless con `ring-1 ring-primary` on focus → Enter salva, Esc annulla, blur salva. Nessun modal, nessun reload.
|
||||
- **Tag multi-select**: `Badge` (già in `components/ui/badge.tsx`) con colori derivati da una palette fissa a rotazione (6-8 colori pastello su sfondo, testo scuro per contrasto AA) + pulsante "+" inline per creare un nuovo tag senza uscire dalla riga
|
||||
- **Quick-add row**: ultima riga della tabella, sempre visibile, placeholder "+ Aggiungi servizio" — stile identico alle righe dati ma `text-muted-foreground`, diventa riga normale dopo il primo salvataggio
|
||||
- **Filtri/ricerca**: barra sopra la tabella, input singolo con icona search (Lucide), filtro client-side istantaneo su nome/tag — NO bottone "Cerca", NO reload
|
||||
- **Header tabella**: sticky, `bg-muted`, font-weight 600, NO maiuscolo decorativo eccessivo (small-caps ok, ALL-CAPS pesante no)
|
||||
- **Hover riga**: `bg-muted/50`, transizione `transition-colors duration-150`, cursore pointer solo su celle editabili
|
||||
|
||||
## Componenti shadcn da riusare/estendere
|
||||
|
||||
Già presenti: `table`, `badge`, `dialog`, `select`, `input`, `button`, `form`. Per Phase 11 servirà probabilmente:
|
||||
- Un componente `EditableCell` (input/select inline, non in shadcn — da costruire ad-hoc su `input.tsx`)
|
||||
- Un `TagMultiSelect` (combobox + badge, da costruire su `select.tsx`/`badge.tsx` — shadcn `command`/`popover` non ancora installati, valutare in planning)
|
||||
|
||||
## Anti-pattern da evitare
|
||||
|
||||
- Ombre pesanti, glassmorphism, gradienti decorativi
|
||||
- Icone emoji (usare SVG Lucide, coerente col resto dell'app)
|
||||
- Tabelle senza filtro/ricerca
|
||||
- Azioni riga-per-riga quando serve bulk (Phase 12+: valutare checkbox + action bar per operazioni multiple)
|
||||
- Hover che causa layout shift (no scale transform su righe tabella)
|
||||
|
||||
## Checklist pre-delivery (per ogni componente nuovo)
|
||||
|
||||
- [ ] Contrasto testo ≥ 4.5:1 (light mode — testo muted minimo `#475569`/`text-muted-foreground` attuale è `#71717a`, verificare su `bg-muted`)
|
||||
- [ ] `cursor-pointer` su celle/righe editabili e cliccabili
|
||||
- [ ] Focus ring visibile (`ring-1 ring-primary` o `--color-ring`) su input inline e bottoni
|
||||
- [ ] Transizioni 150-250ms, `transform`/`opacity` non `width`/`height`
|
||||
- [ ] Responsive: tabella in `overflow-x-auto` wrapper sotto 1024px, niente layout rotto
|
||||
|
||||
---
|
||||
*Riferimento per CONTEXT.md (Phase 11) e per eventuale `/gsd-ui-phase` su fasi 11-14.*
|
||||
@@ -1,57 +0,0 @@
|
||||
# Handoff
|
||||
|
||||
Living document — update at the end of each session so the next one can resume without re-deriving context. Overwrite stale sections; keep it short and actionable.
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-13 — Milestone v2.1 "Offer Studio + Proposal AI" pianificata — pronta per esecuzione
|
||||
|
||||
### Cosa è stato fatto
|
||||
|
||||
Eseguito ciclo completo `/gsd-new-milestone "Offer Studio + Proposal AI"` (research saltata su scelta utente):
|
||||
|
||||
- **PROJECT.md**: nuovo milestone v2.1 con goal, 4 target feature, sezione "Validated" aggiornata con v2.0 (Phase 7-10), "Active" riscritta in 4 categorie prioritizzate, nuove Key Decisions (compartimenti stagni confermato, ordine Offer Studio→Proposal AI, tab Preventivo→Servizi Attivi zero-perdita verificata)
|
||||
- **v2.0 archiviata** (copie, non spostamenti): `REQUIREMENTS.md`/`ROADMAP.md`/phases 07-10 → `.planning/milestones/v2.0-*`
|
||||
- **REQUIREMENTS.md** riscritto: 23 requisiti v1 in 5 categorie (Offer Studio, Workspace Servizi Attivi, CRM Attio, Dashboard [bloccata], Proposal AI) + deferred v2 (OFFER-14, AUTH-OTP-01, ARCH-01) + out of scope
|
||||
- **ROADMAP.md** creato: 7 nuove fasi (11-17), copertura 100% (23/23 requisiti mappati), tutte approvate dall'utente
|
||||
- **STATE.md**: switch a v2.1, focus = Phase 11
|
||||
|
||||
### Roadmap v2.1 (Phase 11-17)
|
||||
|
||||
| Fase | Titolo | Requisiti | Note |
|
||||
| --- | --- | --- | --- |
|
||||
| 11 | Catalog Database-View UX & Legacy Consolidation | OFFER-07,08,09,10,13 | unifica `service_catalog`/`offer_services` → `services` PRIMA della nuova UX |
|
||||
| 12 | Offer Composition Drag&Drop & CSV Import | OFFER-11,12 | `@dnd-kit`, totale live durante drag, import CSV one-shot |
|
||||
| 13 | Workspace — Servizi Attivi | PROJ-06..10 | rimuove tab Preventivo (zero perdita, `accepted_total` resta via Payments) e Forecast; nuova tab Servizi Attivi (one-shot/ricorrenti + tracking incassi mensili) |
|
||||
| 14 | CRM Attio-style & Fix | CRM-08..12 | inline edit lead + tag, fix FollowUpWidget IT / LeadForm types / SendQuoteModal |
|
||||
| 15 | Dashboard Revenue Stats | DASH-11 | **BLOCCATA** — attesa mockup utente, isolata/skippabile, non blocca 16/17 |
|
||||
| 16 | Proposal AI — Data Foundations & Auto-Provisioning | PROP-03,04 | campo Stripe Payment Link + auto-provisioning su accettazione (ex-Phase 11) |
|
||||
| 17 | Proposal AI — Builder, Pagina Pubblica & Email | PROP-01,02,05 | AI builder + redesign `/quote/[token]` + invio email Resend (ex-Phase 12) |
|
||||
|
||||
### Nota trasparenza — deviazione dal workflow
|
||||
|
||||
Il workflow `/gsd-new-milestone` prevede uno step "phases clear" che farebbe `rm -rf` di `.planning/phases/01-10/` senza backup. **Non l'ho eseguito**: è distruttivo, senza archiviazione automatica, e CLAUDE.md richiede conferma prima di operazioni distruttive/di investigare prima di rimuovere lavoro storico. Le fasi 07-10 sono state invece COPIATE (non spostate) in `.planning/milestones/v2.0-phases/`; le directory originali `01-10` restano in `.planning/phases/`. Nessuna perdita — solo directory duplicate, pulizia facoltativa in futuro.
|
||||
|
||||
### Prossima sessione
|
||||
|
||||
1. **Pianificare Phase 11** (Catalog Database-View UX & Legacy Consolidation): `/gsd-plan-phase 11` (oppure `/gsd-discuss-phase 11` prima per decisioni aperte: schema tag, formato CSV import, strategia consolidamento `service_catalog`/`offer_services`)
|
||||
2. Se arriva il **mockup dashboard** dall'utente: Phase 15 (DASH-11) può essere sbloccata, usare `/gsd-ui-phase` come contratto UI
|
||||
3. Migration Phase 11 (consolidamento catalogo) e Phase 13/16 (nuovi campi recurring/payment link) vanno applicate a prod via SSH+docker exec PRIMA del push del codice dipendente (regola storica, vedi sotto)
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-12 — Direzione "Offer Studio" + "Proposal AI" → ora pianificata (vedi sopra)
|
||||
|
||||
- **BUG fixato e deployato**: `/admin/leads/[id]` 500 per `params` non awaited (Next.js 16) → fix commit `ea20685`, confermato live in prod (container `857af5c1...`).
|
||||
- Decisioni strutturali (Preventivo→Servizi Attivi, Forecast→Dashboard, CRM Attio-style, compartimenti stagni) sono ora formalizzate in PROJECT.md/REQUIREMENTS.md/ROADMAP.md — vedi sezione 2026-06-13 sopra.
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-11 (sera) — Phase 10 redo COMPLETATO, root cause risolta (storico)
|
||||
|
||||
- **Root cause del crash post-deploy Phase 10**: il DB prod non aveva NESSUNA migration dopo la 0000 (mancavano `services`, `leads`, `offer_phases`, `quotes`…). Catalogo e quote già rotti prima di Phase 10; il deploy Phase 10 ha aggiunto il crash dashboard (FollowUpWidget→leads). NON era un problema di piattaforma (l'app è Gitea→Coolify, non Vercel).
|
||||
- **Fix**: migrations 0001+0003+0004+0005 applicate atomicamente al DB prod via `ssh root@178.104.27.55` → `docker exec -i xwkk0040w0kk0gsgcgog8owk psql` (porta 54321 firewallata dall'esterno, si passa da SSH). Dati protetti verificati intatti (4 clients / 5 projects / 13 payments / 6 phases).
|
||||
- **Redo Phase 10 deployato**: commit `5aa6614` (deps+UI primitives) e `008a434` (modulo CRM completo). Utente conferma pagine visibili in prod.
|
||||
- **REGOLA**: le migration qui sono manuali — applicare al DB prod PRIMA di pushare codice che usa il nuovo schema. Pattern: `cat migration.sql | ssh root@178.104.27.55 "docker exec -i xwkk0040w0kk0gsgcgog8owk sh -c 'psql -U \$POSTGRES_USER -d clienthub -v ON_ERROR_STOP=1 --single-transaction'"` (verificare prima che sia additive-only).
|
||||
- Branch `phase10-wip` (= `8e2752a`) cancellabile quando il redo è considerato definitivo. Dangling ancora recuperabile: `5d75752` (sidebar App shortcuts).
|
||||
- Script riusabile: `scripts/push-phase10-migration.ts` (solo dal server o con tunnel).
|
||||
@@ -1,5 +1,40 @@
|
||||
# Milestones
|
||||
|
||||
## v2.4 Post-vendita (Phases 13 + 26, in corso)
|
||||
|
||||
**Consegnato:** 2 fasi, entrambe in produzione e verificate.
|
||||
|
||||
**Key accomplishments:**
|
||||
|
||||
- Ciclo di vita dei servizi ricorrenti (Phase 13, prod 2026-08-01): `project_offers.status` (attivo/sospeso/cessato) + `end_date` via migr. 0016; il forecast a 12 mesi smette di sommare un retainer fermo; comandi Sospendi/Riattiva/Cessa nella tab Offerte; il cliente vede stato, "attivo dal / fino al" e canone mensile (RET-01..05)
|
||||
- Anteprima admin del portale + toggle password sul login (Phase 26, prod 2026-08-08): `?preview=1` con sessione Auth.js valida apre il portale di un cliente in sola lettura, senza passare dal gate OTP (PREV-01/02, AUTH-09)
|
||||
|
||||
**Deviazione registrata:** vincolo LOCKED #4 — una route `/client/*` ora legge anche la sessione Auth.js (Phase 26).
|
||||
|
||||
**Aperto:** RET-06 (canoni mensili tracciabili), più il backlog ereditato. Vedi `REQUIREMENTS.md`.
|
||||
|
||||
Fasi: [13-ciclo-vita-servizi-ricorrenti](phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md) · [26-anteprima-admin-e-login](phases/26-anteprima-admin-e-login/26-SUMMARY.md)
|
||||
|
||||
---
|
||||
|
||||
## v2.3 Email & Accesso (Phases 23–25, shipped 2026-07-29)
|
||||
|
||||
**Phases completed:** 3 fasi (23–25) · eseguite fuori dal ciclo GSD (nessun PLAN/SUMMARY per fase)
|
||||
|
||||
**Key accomplishments:**
|
||||
|
||||
- Resend Setup (Phase 23): `resend@6.18.1`, `src/lib/mailer.ts` con Result tipizzato, template OTP in italiano, env configurate su Coolify
|
||||
- Schema + Whitelist Admin (Phase 24): migr. 0015 additiva pura applicata a prod — `client_emails`, `otp_codes`, `clients.sessions_valid_from`; sezione "Accessi al portale" in `/admin/clients/[id]` (OTP-01, OTP-08)
|
||||
- OTP Gate + Sessione (Phase 25): codice 6 cifre CSPRNG hashato, TTL 15 min, monouso, max 5 tentativi; cookie HMAC per-cliente, 90 giorni; rate limiting e no-enumeration (OTP-02..07)
|
||||
|
||||
**Verificata end-to-end in produzione** su `hub.iamcavalli.net` il 2026-07-29: senza cookie il gate non lascia trapelare **nessun dato di progetto** nell'HTML.
|
||||
|
||||
**Known deferred items at close:** SEND-01/SEND-02 (invio preventivo via email) — rinviati, il mailer resta comunque in prod.
|
||||
|
||||
Archive: [`milestones/v2.3-ROADMAP.md`](milestones/v2.3-ROADMAP.md) · [`milestones/v2.3-REQUIREMENTS.md`](milestones/v2.3-REQUIREMENTS.md)
|
||||
|
||||
---
|
||||
|
||||
## v2.2 Sales Loop (Phases 18–22, shipped 2026-06-20)
|
||||
|
||||
**Phases completed:** 5 phases (18–22) · 9 plans · 27 commits · 87 files · +7.349/-842 righe
|
||||
@@ -28,6 +63,10 @@ Archive: `.planning/milestones/v2.2-ROADMAP.md` · `.planning/milestones/v2.2-RE
|
||||
- Offer Editor Tier A/B/C (Phase 12): editor offerte con matrice checkbox servizi×tier, totale live, prezzo pubblico manuale, tag 4-dimensioni, promessa di trasformazione; 55 servizi reali caricati (OFFER-11, OFFER-15..18)
|
||||
- CRM Attio-style (Phase 14): `/admin/leads` ridisegnata con inline edit + tag multi-select; FollowUpWidget in italiano; LeadForm tipizzato; SendQuoteModal senza rami irraggiungibili (CRM-08..12)
|
||||
|
||||
Phase 13 è poi tornata in vita come milestone v2.4, consegnata il 2026-08-01.
|
||||
|
||||
Archive: [`milestones/v2.1-ROADMAP.md`](milestones/v2.1-ROADMAP.md) (ricostruito il 2026-08-08) · fasi in [`milestones/v2.1-phases/`](milestones/v2.1-phases/)
|
||||
|
||||
---
|
||||
|
||||
## v2.0 Business Operations Suite (Phases 7–10, completato 2026-06-13)
|
||||
|
||||
+29
-15
@@ -8,15 +8,16 @@ Suite operativa per un consulente di personal branding, live su hub.iamcavalli.n
|
||||
|
||||
Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
|
||||
|
||||
## Current Milestone: v2.3 Email & Accesso
|
||||
## Current Milestone: v2.4 Post-vendita
|
||||
|
||||
**Goal:** Aggiungere uno strato email all'app — OTP gate per il portale cliente e invio link preventivo dall'admin — con un'unica integrazione Resend condivisa.
|
||||
**Goal:** Chiudere il ciclo di vita di ciò che è già venduto — un retainer deve poter finire, e l'admin deve poter vedere il portale con gli occhi del cliente.
|
||||
|
||||
**Target features:**
|
||||
- AUTH-OTP-01 — OTP gate portale cliente (whitelist email + sessione 30gg + admin UI)
|
||||
- PUB-03 — Invio link `/preventivo/[slug]` via email Resend dall'admin
|
||||
**Consegnato (in produzione):**
|
||||
|
||||
**Backlog v2.4+:** PROP-03 (Stripe Payment Link), PROP-04 (auto-provisioning al "Vinto"), Phase 13 (servizi ricorrenti)
|
||||
- Phase 13 — Ciclo di vita dei servizi ricorrenti (RET-01..05), prod 2026-08-01
|
||||
- Phase 26 — Anteprima admin del portale + toggle password sul login (PREV-01/02, AUTH-09), prod 2026-08-08
|
||||
|
||||
**Backlog:** RET-06 (canoni mensili tracciabili), SEND-01/02 (invio preventivo via email), PROP-03 (Stripe Payment Link), PROP-04 (auto-provisioning al "Vinto"), DEBT-01 (debito design). Elenco completo in `REQUIREMENTS.md`.
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -57,10 +58,19 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
|
||||
- ✓ Agente AI: Claude Opus 4.8, Zod schema 20+ sezioni, snapshot JSONB proposals, form admin — Phase 21 (AI-01, AI-02)
|
||||
- ✓ Deck pubblico `/preventivo/[slug]`: 20+ slide 100vh, keyboard nav; accept/reject `accepted_at` immutabile — Phase 22 (PUB-01, PUB-02)
|
||||
|
||||
### Active — v2.3
|
||||
Validated in v2.3 Email & Accesso (shipped 2026-07-29):
|
||||
|
||||
- [ ] AUTH-OTP-01 — Accesso cliente via OTP email: whitelist `client_emails`, gate `/client/[token]/*`, sessione 30gg, admin whitelist UI
|
||||
- [ ] PUB-03 — Invia link `/preventivo/[slug]` via email Resend dall'admin
|
||||
- ✓ Gate OTP sul portale cliente: whitelist `client_emails`, codice 6 cifre via Resend, sessione firmata **90 giorni** (non 30: modificata il 2026-07-28), revoca in blocco dall'admin — Phase 23/24/25 (OTP-01..08). Migr. 0015.
|
||||
- ✗ PUB-03 / SEND-01/02 (invio preventivo via email) **non consegnato**: rinviato al backlog il 2026-07-28. Il preventivo si manda a mano; l'infrastruttura Resend è comunque in prod.
|
||||
|
||||
Validated in v2.4 Post-vendita (in produzione):
|
||||
|
||||
- ✓ Ciclo di vita dei servizi ricorrenti: `project_offers.status` + `end_date`, forecast che si ferma, comandi Sospendi/Riattiva/Cessa, stato visibile al cliente — Phase 13 (RET-01..05). Migr. 0016.
|
||||
- ✓ Anteprima admin in sola lettura del portale cliente + toggle password sul login — Phase 26 (PREV-01/02, AUTH-09).
|
||||
|
||||
### Active
|
||||
|
||||
Nessun requisito in lavorazione. Il prossimo va scelto dal backlog in `REQUIREMENTS.md`.
|
||||
|
||||
### Out of Scope
|
||||
|
||||
@@ -79,8 +89,8 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
|
||||
- Tutto sotto la stessa app: `/admin/*` (sessione Auth.js) + `/client/[token]/*` (token) + `/preventivo/[slug]` (pubblico)
|
||||
- La sidebar admin include: Dashboard, Leads (con toggle Lista/Kanban), Offerte, Catalogo, Preventivi (con CTA globale "Genera preventivo")
|
||||
- Stack v2.2: `@anthropic-ai/sdk@0.105.0` (Claude Opus 4.8), `@dnd-kit` (Kanban), `nanoid` (slug proposals)
|
||||
- DB live: 10 migrazioni applicate a prod (0000–0010); `proposals` table con `content jsonb` snapshot; `client_transcripts` per lead
|
||||
- Migrations sono manuali: SSH tunnel → `node` script PRIMA di pushare codice schema-dipendente; `drizzle-kit generate` rotto da Phase 8
|
||||
- DB live: migrazioni applicate a prod fino alla **0016**; `proposals` con `content jsonb` snapshot; `client_transcripts` per lead; `client_emails`/`otp_codes` per il gate OTP
|
||||
- Migrations sono manuali: SQL a mano applicato via **SSH + docker exec** PRIMA di pushare il codice schema-dipendente (procedura in `CLAUDE.md`); `drizzle-kit generate` rotto da Phase 8
|
||||
- `ANTHROPIC_API_KEY` in Coolify — aggiunta 2026-06-20 via PHP artisan; costo ~$0.44/preventivo (Opus 4.8)
|
||||
- Il flusso commerciale reale: call con lead → transcript incollato → genera preventivo AI → deck pubblica → cliente sceglie tier → vinto/perso
|
||||
|
||||
@@ -90,7 +100,7 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
|
||||
- **Architettura (LOCKED)**: `clients.token` separato e rotatable; `quote_items` mai esposti via client API; `deliverables.approved_at` immutabile; no file hosting
|
||||
- **Compartimenti stagni**: un'unica app Next.js, moduli isolati (route group + service layer propri) su Postgres condiviso; migrations solo additive; niente deploy separati per ora (modello OMC adattato)
|
||||
- **NO database esterno / Excel come fonte dati**: Postgres resta l'unica fonte di verità — il problema è la UX, non il dato
|
||||
- **Numerazione fasi**: v2.0 ha chiuso a Phase 10; v2.1 parte da Phase 11
|
||||
- **Numerazione fasi**: progressiva e mai riusata — v1.0 1–6, v2.0 7–10, v2.1 11–17 (13/15/16/17 mai eseguite), v2.2 18–22, v2.3 23–25, v2.4 13 (ripresa dal congelamento) + 26
|
||||
|
||||
## Key Decisions
|
||||
|
||||
@@ -103,14 +113,18 @@ Validated in v2.2 Sales Loop (shipped 2026-06-20):
|
||||
| Catalogo servizi unificato (una tabella `services`) | Due cataloghi paralleli (service_catalog + offer_services) duplicano manutenzione prezzi | ✓ Good — tabella `services` live da Phase 7, consolidamento legacy in v2.1 |
|
||||
| Tier offerte indipendenti (A/B/C separati, stesso tag) | Più semplice di un meccanismo di ereditarietà; ogni tier configurato a sé | ✓ Good — usato in deck slide Pricing/StagesRecap/Comparison |
|
||||
| Prezzi pacchetti per-preventivo, non da catalogo | Permette di alzare i prezzi nel tempo senza toccare il catalogo | ✓ Good — `public_price` per tier, snapshot in `proposals.content` |
|
||||
| Al "Vinto" le fasi dell'offerta sono COPIATE nel progetto | Il progetto resta modificabile senza toccare il template offerta | — Pending (PROP-04, backlog v2.3) |
|
||||
| Al "Vinto" le fasi dell'offerta sono COPIATE nel progetto | Il progetto resta modificabile senza toccare il template offerta | — Pending (PROP-04, backlog) |
|
||||
| NO DB esterno/Excel, Postgres unica fonte | Lezione 2026-06-11: due fonti disallineate hanno causato il crash Phase 10 | ✓ Good |
|
||||
| Catalogo/Offerte UX = database view custom (non Notion-clone) | Notion troppo complesso per v1; serve velocità, non sezioni analitiche | ✓ Good — confermato in v2.1 |
|
||||
| Tab "Preventivo" rimossa, "Offerte" → "Servizi attivi" | Preventivo Builder è l'unico flusso; `accepted_total` già coperto da Payments | ✓ Confermato — zero perdita funzionale verificata (2026-06-13) |
|
||||
| Ordine: Offer Studio (UX dato) prima, Proposal AI (AI) dopo | L'AI è l'ultimo miglio, serve un dato pulito e veloce da gestire prima | ✓ Good — strategia validata: catalogo+offerte puliti → AI in v2.2 |
|
||||
| Output AI = JSON strutturato Zod → template fisso | Coerenza visiva garantita; zero rischio HTML rotto dall'AI | ✓ Good — 20+ sezioni Zod validate, deck sempre coerente |
|
||||
| `proposals.content` = JSONB snapshot immutabile | Prezzi e profilo consulente "bloccati" al momento della generazione | ✓ Good — invariante di audit, coerente con `accepted_at` |
|
||||
| Email Resend (PUB-03) deferred | Scope minimo funziona; link condiviso manualmente per ora | — Pending (v2.3 candidato #1) |
|
||||
| Email Resend (PUB-03) deferred | Scope minimo funziona; link condiviso manualmente per ora | — Pending — rinviata di nuovo il 2026-07-28, il mailer però è in prod |
|
||||
| Il gate OTP sta in cima alla `page`, mai nel layout | Nell'App Router il `page` è renderizzato in parallelo al layout: gattare nel layout lascia i dati nel payload RSC | ✓ Good — verificato: 46.907 → 17.594 byte di HTML |
|
||||
| Sessione OTP a 90 giorni invece di 30 | Rientro più fluido per il cliente, compensato dalla revoca in blocco lato admin (OTP-08) | ✓ Good — in prod dal 2026-07-29 |
|
||||
| Storico di vendita ≠ forecast | `getOffersSoldBreakdown` non filtra per stato: escludere le offerte cessate riscriverebbe il fatturato passato | ✓ Good — Phase 13 |
|
||||
| Anteprima admin del portale in sola lettura | Le API client autenticano sul token nel body, non sulla sessione: un click distratto approverebbe un deliverable, e `approved_at` è immutabile (LOCKED #3) | ✓ Good — protezione a livello UI, deviazione da LOCKED #4 accettata (Phase 26) |
|
||||
|
||||
## Evolution
|
||||
|
||||
@@ -130,4 +144,4 @@ This document evolves at phase transitions and milestone boundaries.
|
||||
4. Update Context with current state
|
||||
|
||||
---
|
||||
*Last updated: 2026-06-21 — v2.3 milestone started: Email & Accesso (AUTH-OTP-01 + PUB-03)*
|
||||
*Last updated: 2026-08-08 — v2.3 archiviata, v2.4 Post-vendita corrente (Phase 13 + 26 in produzione)*
|
||||
|
||||
+110
-52
@@ -1,69 +1,127 @@
|
||||
# Requirements: ClientHub v2.3 Email & Accesso
|
||||
# Requirements: ClientHub v2.5 Audit
|
||||
|
||||
**Defined:** 2026-06-21
|
||||
**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
|
||||
**Definiti:** 2026-08-16 (piano approvato) · **rivisti:** 2026-08-18 (motore)
|
||||
**Core Value della milestone:** L'imprenditore paga un'analisi del suo sito e riceve un
|
||||
documento che gli dice, con numeri misurati, cosa non funziona e cosa costa — non un
|
||||
elenco di quaranta punti generato da un tool gratuito.
|
||||
|
||||
## v2.3 Requirements
|
||||
Milestone precedente: [v2.4 Post-vendita](milestones/v2.4-REQUIREMENTS.md), chiusa 2026-08-08.
|
||||
|
||||
### Email OTP Gate (AUTH-OTP-01)
|
||||
Piani di riferimento (fuori dal repo, in `~/.claude/plans/`):
|
||||
`dovremmo-fare-una-cosa-woolly-puddle.md` (documento, editor, template) +
|
||||
`vorrei-solo-farti-capire-radiant-valley.md` (motore — sostituisce §6/§7 del primo).
|
||||
|
||||
Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.
|
||||
## Il prodotto
|
||||
|
||||
- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
|
||||
- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
|
||||
- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
|
||||
- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
|
||||
- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
|
||||
- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
|
||||
- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
|
||||
- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente
|
||||
Tre livelli venduti, che sono **configurazioni di un unico documento**, non tre documenti:
|
||||
|
||||
> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
|
||||
> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
|
||||
> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
|
||||
> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.
|
||||
| Livello | Blocchi inclusi |
|
||||
|---|---|
|
||||
| **Radiografia** | 1, 2, 2b, 3, 4, 5, 8, 9 |
|
||||
| **Prima/Dopo** | + 6 (il redesign), 6b (cosa il redesign non risolve) |
|
||||
| **Rotta** | + 7 (le ottimizzazioni, con priorità e impegno in giornate) |
|
||||
|
||||
## v2.4+ Backlog
|
||||
I blocchi non pertinenti **non esistono nel DOM**, non sono nascosti via CSS.
|
||||
|
||||
### Conversione Commerciale
|
||||
## Requisiti
|
||||
|
||||
- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
|
||||
- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
|
||||
- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*
|
||||
### Motore (Phase 27)
|
||||
|
||||
### Post-Vendita
|
||||
- [x] **AUD-01**: Schema additivo per audit, finding, ottimizzazioni, rubrica, esiti, run e visite — *migration `0017_audits.sql`, in prod 2026-08-18*
|
||||
- [x] **AUD-02**: La rubrica del motore (264 voci falsificabili) vive in `checklist_items`, non nel documento — *in prod 2026-08-18*
|
||||
- [x] **AUD-03**: Le fonti raccolgono **rilevazioni, non stime**: PageSpeed (153 audit sul DOM renderizzato), CrUX (utenti reali), Wayback, RDAP, robots/sitemap/JSON-LD, header — *`src/lib/audit/sources/`, provato sul campo 2026-08-18, non ancora pushato*
|
||||
- [x] **AUD-04**: Ogni fonte fallisce in modo **non fatale** e dice *perché*: "non ha risposto" e "ha risposto che non ci sono dati" sono informazioni diverse
|
||||
- [x] **AUD-05**: Quando CrUX non ha dati di campo il documento lo **dice** ("i visitatori non sono abbastanza numerosi perché Google raccolga dati"), non lascia un buco — *`nota` in `crux.ts`; il caso "zero dati" resta da vedere su un sito vero*
|
||||
- [ ] **AUD-06**: Ogni output di modello è validato con Zod, `safeParse`, fallimento duro — nessun loop di riparazione (precedente: `src/lib/proposal/schema.ts`)
|
||||
- [ ] **AUD-07**: Quattro sub-agent in parallelo (checklist, visivo, storico, tecnico) più un sintetizzatore che **incrocia** le loro osservazioni in un solo finding con più evidenze indipendenti
|
||||
- [ ] **AUD-08**: Massimo **10 finding**, ordinati per impatto su tre soli valori (`alto|medio|basso`); la sfumatura sta nell'ordine dentro il gruppo
|
||||
- [ ] **AUD-09**: Disciplina sui numeri imposta nel prompt di sistema — un numero entra nel documento solo se misurato, e ogni numero consegnato è rintracciabile in `audit_runs.raw`
|
||||
- [ ] **AUD-10**: Fan-out con tetto di concorrenza e retry con backoff sulle 429/529 di Anthropic
|
||||
- [ ] **AUD-11**: Heartbeat a ogni passo su `audit_runs`; una run senza battito va in `error` e "Rilancia" riparte dall'ultimo passo completato *(un redeploy Coolify uccide un job in corso)*
|
||||
|
||||
- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)
|
||||
### Storage immagini (Phase 28)
|
||||
|
||||
## Out of Scope
|
||||
- [ ] **AUD-12**: Volume persistente Coolify su `/app/uploads`, lettura da `/api/uploads/[...path]` con guardia sul path traversal, whitelist MIME e limite di dimensione
|
||||
- [ ] **AUD-13**: Due immagini caricate a mano per audit (hero **prima** e **dopo** del redesign, JPG ≤ 512 KB); due scritte dalla pipeline (screenshot mobile e desktop da PageSpeed)
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
|
||||
| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
|
||||
| Email marketing / newsletter | Non pertinente al portale |
|
||||
| Multi-admin | Ancora single admin per ora |
|
||||
### Editor admin (Phase 29)
|
||||
|
||||
## Traceability
|
||||
- [ ] **AUD-14**: Creazione **manuale** di un audit (livello, profilo, URL, cliente/lead). L'ingresso Whop è predisposto nello schema (`origin`, `external_ref`) ma **non costruito**
|
||||
- [ ] **AUD-15**: Editor a payload intero (modello: `admin/offers/actions.ts`) che **salva sempre, anche a metà** — tutti i campi di contenuto sono nullable, la validazione di completezza scatta solo alla consegna
|
||||
- [ ] **AUD-16**: Riordino di finding e ottimizzazioni con `@dnd-kit/sortable`, con re-sync degli id dei figli
|
||||
- [ ] **AUD-17**: Il **blocco 8 (La direzione) resta manuale, foglio bianco** — è il blocco che giustifica il prezzo; se diventa formula il cliente lo sente
|
||||
- [ ] **AUD-18**: Il registro delle visite è visibile nell'editor, in ordine cronologico
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
|
||||
| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
|
||||
| SEND-01 | — | ⏭️ Rinviato a v2.4 |
|
||||
| SEND-02 | — | ⏭️ Rinviato a v2.4 |
|
||||
### Documento pubblico (Phase 30)
|
||||
|
||||
**Coverage:**
|
||||
- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
|
||||
- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
|
||||
- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.
|
||||
- [ ] **AUD-19**: `/audit/[slug]` — pagina privata, `X-Robots-Tag: noindex, nofollow`, rate limit sul matcher di `proxy.ts`
|
||||
- [ ] **AUD-20**: Il template è **congelato alla creazione** (`template_version`): migliorare il documento tocca gli audit successivi, mai quelli già consegnati
|
||||
- [ ] **AUD-21**: PDF via **print CSS**, non libreria: interruzioni di pagina corrette, slider impilato in due immagini, **nessun marcatore di lavorazione sopravvissuto**
|
||||
- [ ] **AUD-22**: In **scala di grigi** impatti e metriche restano distinguibili — il colore non può essere l'unico portatore di informazione
|
||||
- [ ] **AUD-23**: Il documento usa **il design system dell'area admin** ("Quiet Luxury", `design-reference/DESIGN-SYSTEM.md`): token semantici, Plus Jakarta Sans per il testo, **Geist Mono per metriche, punteggi e date**, e i primitivi già esistenti (`StatusBadge` per gli impatti). *Decisione del 2026-08-18, sostituisce la deroga tipografica prevista dal piano.* Due conseguenze: i font sono già self-hostati da `next/font/google`, quindi la CSP `font-src 'self'` è soddisfatta senza lavoro; e il documento **non aggiunge debito a DEBT-01** perché nasce già a token.
|
||||
- [ ] **AUD-24**: Tracciamento delle aperture (`view`) e delle stampe (`print`) via isola client + Server Action; **un admin loggato non viene contato** (altrimenti i numeri li inquiniamo noi rileggendo le bozze)
|
||||
- [ ] **AUD-25**: L'IP non si salva in chiaro — SHA-256 di `ip + NEXTAUTH_SECRET`, come il digest del gate admin
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-06-21*
|
||||
*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*
|
||||
## Vincoli che questa milestone tocca
|
||||
|
||||
- **LOCKED #5 (no file hosting)** — emendato limitatamente agli asset di audit, deroga già annotata in `CLAUDE.md`. Non estendere ad altre entità.
|
||||
- **Nessun renderer headless, da nessuna parte.** Il VPS non regge Chromium (RAM), e non serve: gli audit Lighthouse arrivano già fatti sul DOM renderizzato.
|
||||
|
||||
## Modifiche hub (richieste 2026-08-18, in corso)
|
||||
|
||||
Fuori dalla milestone v2.5, che è in pausa. Piano in
|
||||
`~/.claude/plans/sei-arrivato-qua-search-recursive-kettle.md`.
|
||||
|
||||
- [x] **HUB-01**: Via il tab Commenti dal progetto — `/admin/conversazioni` li aggrega già tutti con l'etichetta dell'entità. *Perde solo la risposta sulla singola entità, che era già confluita sul thread generale.*
|
||||
- [x] **HUB-02**: Via il timer dalla lista progetti — si avvia dove c'è il contesto
|
||||
- [x] **HUB-03**: Riepilogo soldi + avanzamento in testa al progetto, senza query nuove
|
||||
- [x] **HUB-04**: Timer per fase e task — migration `0018`, `ON DELETE SET NULL` perché le ore sopravvivono al task
|
||||
- [x] **HUB-05**: Inbox in cima alla dashboard, con da-quanto-aspetta e contesto del messaggio
|
||||
- [x] **HUB-06**: Analytics per linea di prodotto (Entry/Signature/Retainer) dalla tassonomia, con l'incassato non attribuibile mostrato a parte
|
||||
- [x] **HUB-07**: Timeline delle consegne con semaforo ritardo/anticipo; scadenza dedotta da offerta + durata, `projects.due_date` come override
|
||||
- [x] **HUB-08**: `POST /api/webhooks/lead` — un endpoint per form del sito e bridge, con dedup sull'email
|
||||
- [ ] **HUB-09**: Confermare la forma del payload Elementor con un invio **vero** — oggi è gestita in modo difensivo
|
||||
- [ ] **HUB-10**: `LEAD_WEBHOOK_SECRET` su Coolify — finché manca, la route risponde 403 a tutti
|
||||
- [ ] **HUB-11**: TidyCal. **[BLOCCANTE]** Niente webhook (loro FAQ): serve polling della REST API. Path e filtri stanno dietro il login → servono token o documentazione dall'utente
|
||||
- [ ] **HUB-12**: Alleggerire l'hub. Senza perimetro: si definisce guardando cosa è poco usato
|
||||
- [ ] **HUB-13**: Whop → progetto + audit automatico. Dipende dal motore v2.5 (AUD-06→11)
|
||||
- [x] **HUB-14**: Rifiniture dall'uso reale del pannello — rinomina di un valore di tassonomia con propagazione alle fasi dei progetti, stato task "In revisione", tab pagamenti con ordine stabile e importi a mano, riordino task per trascinamento. *In prod 2026-08-20, migration `0019`.*
|
||||
- [x] **HUB-15**: Portale cliente — barra di avanzamento compatta e a tutta larghezza, card offerta senza accordion, "Valore dell'offerta" con override admin (`project_offers.offer_value_override`). *In prod 2026-08-21, migration `0020`. Serviva perché la somma dei prezzi di catalogo mostrava €20.250 su offerte vendute a 7.000 e 5.500.*
|
||||
- [ ] **HUB-16**: Guardare a mano HUB-14 e HUB-15 in produzione. `updateOfferValueOverride` **è provata** (Caruso Speaker ha un override a 7.500 messo dal pannello); restano da cliccare `reorderTasks`, `updatePaymentField`, `clearPaymentOverride` e il drag, e dal 2026-08-21 la verifica locale contro i dati veri non è più possibile
|
||||
|
||||
## Backlog (ereditato, nessuno in corso)
|
||||
|
||||
- [ ] **SEND-01 / SEND-02** — Invio del link `/preventivo/[slug]` via email. Il mailer è già in produzione dalla v2.3: manca il pulsante e l'action. *Rinviati il 2026-07-28.*
|
||||
- [ ] **PROP-03** — Stripe Payment Link sul deck pubblico del preventivo.
|
||||
- [ ] **PROP-04** — Auto-provisioning cliente / progetto / fasi al passaggio del lead a "Vinto".
|
||||
- [ ] **RET-06** — Canoni mensili tracciabili. **Serve una tabella nuova**: `payments` è protetta dai vincoli di Data Safety.
|
||||
- [ ] **OFFER-14** — Sezioni analitiche stile Notion sull'offerta.
|
||||
- [ ] **ARCH-01** — Split del modulo "compartimento stagno" in un deploy separato. *Solo se cresce.*
|
||||
- [ ] **DEBT-01** — Debito design: ~40 file, ~450 occorrenze di palette raw/hex al posto dei token. Cluster in `/admin/projects/[id]` (~182), `/admin/offers/[id]/edit` (~79), `/admin/clients/[id]` (~59), `/quote/[token]` (~48, ed è rivolto al cliente), `ChatPanel` (37), `ui/dialog.tsx`. *Misurato il 2026-08-08.*
|
||||
- [ ] **DEBT-02** — Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services`; `createService` / `serviceSchema` dead code.
|
||||
|
||||
## Rinviati esplicitamente da v2.5
|
||||
|
||||
- **Allegato tecnico** — seconda vista sugli stessi finding con registro da sviluppatore (selettori, file, stime). Renderebbe vera la promessa del blocco 9 *"il documento resta tuo e puoi darlo a chiunque lavorerà sul sito"*. Da valutare **dopo il primo audit consegnato**.
|
||||
- **Affettare lo screenshot a pagina intera** — richiede `sharp`, da verificare su `node:20-alpine`. Non serve in fase 1: `final-screenshot` (250×498) è leggibile.
|
||||
- **Ingresso via webhook Whop** — schema predisposto, costruzione in fase 2.
|
||||
|
||||
## Aperto, non un requisito
|
||||
|
||||
**`.env.local` da riallineare a Coolify.** `ADMIN_PASSWORD`, `NEXTAUTH_SECRET` **e la
|
||||
password del DB** sono stale, e l'host che il file dichiara (`178.104.27.55:5432`) è chiuso
|
||||
dal firewall — il DB vero è su `127.0.0.1:54321` dietro tunnel. Finché resta così **una
|
||||
modifica al portale si verifica solo in produzione**: build, migration e query di controllo,
|
||||
poi occhio umano sul sito. Recuperare la password viva dal container è bloccato dal
|
||||
classifier dei permessi e non va aggirato: la sblocca l'utente copiando le variabili da
|
||||
Coolify. Le migration non ne soffrono (`docker exec` non usa quelle credenziali).
|
||||
|
||||
**Whitelist del portale vuota per 3 clienti su 4.** La migration 0015 ha seedato solo
|
||||
`mario@test.it`. Protocollo Estetico, Caruso Speaker e Teckell hanno whitelist vuota e
|
||||
finché lo è **il loro portale non è accessibile**. Si popola da `/admin/clients/<id>` →
|
||||
"Accessi al portale", poi va reinviato il link.
|
||||
|
||||
## Fuori scope
|
||||
|
||||
- Tabella utenti / multi-admin: l'auth resta una singola credenziale da env.
|
||||
- File hosting per i documenti del portale cliente: restano URL esterni (LOCKED #5, non emendato per quelli).
|
||||
|
||||
+57
-95
@@ -4,10 +4,11 @@
|
||||
|
||||
- ✅ **v1.0 Client Portal & Offer System** — Phases 1–6 (shipped 2026-06-10) — [archive](milestones/v1.0-ROADMAP.md)
|
||||
- ✅ **v2.0 Business Operations Suite** — Phases 7–10 (shipped 2026-06-13) — [archive](milestones/v2.0-ROADMAP.md)
|
||||
- ✅ **v2.1 Offer Studio + CRM** — Phases 11–14 parziale (chiuso 2026-06-19, reset → v2.2)
|
||||
- ✅ **v2.1 Offer Studio + CRM** — Phases 11, 12, 14 (chiusa per reset 2026-06-19) — [archive](milestones/v2.1-ROADMAP.md)
|
||||
- ✅ **v2.2 Sales Loop** — Phases 18–22 (shipped 2026-06-20) — [archive](milestones/v2.2-ROADMAP.md)
|
||||
- ✅ **v2.3 Email & Accesso** — Phases 23–25 (shipped 2026-07-29)
|
||||
- 🔨 **v2.4 Post-vendita** — Phase 13 (in corso)
|
||||
- ✅ **v2.3 Email & Accesso** — Phases 23–25 (shipped 2026-07-29) — [archive](milestones/v2.3-ROADMAP.md)
|
||||
- ✅ **v2.4 Post-vendita** — Phases 13 + 26 (entrambe in produzione, 2026-08-01 / 2026-08-08)
|
||||
- 🔨 **v2.5 Audit** — Phases 27–30 — documento di restituzione del servizio di analisi sito
|
||||
|
||||
## Phases
|
||||
|
||||
@@ -15,10 +16,10 @@
|
||||
<summary>✅ v1.0 + v2.0 + v2.1 (Phases 1–17) — SHIPPED / CHIUSE</summary>
|
||||
|
||||
Vedi archivi:
|
||||
|
||||
- `milestones/v1.0-ROADMAP.md` — Phases 1–6
|
||||
- `milestones/v2.0-ROADMAP.md` — Phases 7–10
|
||||
- Phases 11, 12, 14 — Offer Studio + CRM Attio (shipped in prod)
|
||||
- Phases 13, 15, 16, 17 — congelate/abbandonate/ri-scopate in v2.2
|
||||
- `milestones/v2.1-ROADMAP.md` — Phases 11, 12, 14 shipped; 15/16/17 abbandonate o ri-scopate; **Phase 13 ripresa in v2.4**
|
||||
|
||||
</details>
|
||||
|
||||
@@ -35,70 +36,67 @@ Archivio completo: [milestones/v2.2-ROADMAP.md](milestones/v2.2-ROADMAP.md)
|
||||
|
||||
</details>
|
||||
|
||||
### 🔨 v2.3 — Email & Accesso (Phases 23–25)
|
||||
<details>
|
||||
<summary>✅ v2.3 Email & Accesso (Phases 23–25) — SHIPPED 2026-07-29</summary>
|
||||
|
||||
- [x] **Phase 23: Resend Setup** — SDK Resend + `src/lib/mailer.ts` + template OTP *(l'invio preventivo è stato rinviato a v2.4 il 2026-07-28)*
|
||||
- [x] **Phase 24: Schema + Whitelist Admin** — Tabelle `client_emails` e `otp_codes`, admin UI gestione whitelist + revoca sessioni
|
||||
- [x] **Phase 25: OTP Gate + Sessione** — Gate OTP completo, sessione **90gg**, rate limiting, no enumeration
|
||||
- [x] Phase 23: Resend Setup — SDK + `src/lib/mailer.ts` + template OTP *(SEND-01/02 rinviati al backlog il 2026-07-28)*
|
||||
- [x] Phase 24: Schema + Whitelist Admin — `client_emails`, `otp_codes`, UI whitelist + revoca sessioni (migr. 0015)
|
||||
- [x] Phase 25: OTP Gate + Sessione — gate completo, sessione **90gg**, rate limiting, no enumeration
|
||||
|
||||
✅ **Shipped 2026-07-29** (commit `27da969`), verificata end-to-end su `hub.iamcavalli.net`. SEND-01/02 rinviati a backlog.
|
||||
Shipped col commit `27da969`, verificata end-to-end su `hub.iamcavalli.net`.
|
||||
Archivio completo: [milestones/v2.3-ROADMAP.md](milestones/v2.3-ROADMAP.md)
|
||||
|
||||
### 🔨 v2.4 — Post-vendita (Phase 13)
|
||||
</details>
|
||||
|
||||
- [ ] **Phase 13: Ciclo di vita dei servizi ricorrenti** — `project_offers.status` + `end_date` (migr. 0016), forecast che si ferma davvero, comandi Sospendi/Riattiva/Cessa nella tab Offerte, stato dell'abbonamento visibile al cliente.
|
||||
### ✅ v2.4 — Post-vendita (Phases 13 + 26)
|
||||
|
||||
Fuori scope di questo giro, rimandato: tracciamento dei canoni mese per mese (serve una tabella nuova — `payments` è protetta e la sua riscalatura è pensata per i piani una tantum).
|
||||
- [x] **Phase 13: Ciclo di vita dei servizi ricorrenti** — `project_offers.status` + `end_date` (migr. 0016), forecast che si ferma davvero, comandi Sospendi/Riattiva/Cessa nella tab Offerte, stato dell'abbonamento visibile al cliente. ✅ **prod 2026-08-01** (`5177a37`) — [13-SUMMARY.md](phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md)
|
||||
- [x] **Phase 26: Anteprima admin del portale + toggle password** — `?preview=1` con sessione Auth.js valida apre il portale di un cliente in sola lettura, senza gate OTP. ✅ **prod 2026-08-08** (`09a5b1f`, `187550f`) — [26-SUMMARY.md](phases/26-anteprima-admin-e-login/26-SUMMARY.md)
|
||||
|
||||
## Phase Details
|
||||
### 🔨 v2.5 — Audit (Phases 27–30) · *in corso*
|
||||
|
||||
### Phase 23: Resend Setup + Invio Preventivo
|
||||
**Goal**: Admin può inviare il link `/preventivo/[slug]` via email con un click dall'admin UI
|
||||
**Depends on**: Nothing — primo uso di Resend, nessuna dipendenza DB
|
||||
**Requirements**: SEND-01, SEND-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Admin fa click su "Invia preventivo" nel dettaglio lead/preventivo e l'email parte senza uscire dall'app
|
||||
2. Il destinatario riceve un'email in italiano con nome cliente e link cliccabile al deck pubblico
|
||||
3. L'invio usa Resend con le variabili d'ambiente configurate su Coolify (`RESEND_API_KEY`, `RESEND_FROM`)
|
||||
4. In caso di errore Resend, l'admin vede un messaggio di errore chiaro nell'UI (non un crash silenzioso)
|
||||
**Plans**: TBD
|
||||
**UI hint**: yes
|
||||
Il servizio di analisi sito (tre livelli: **Radiografia / Prima-Dopo / Rotta**) diventa
|
||||
un documento privato su `/audit/[slug]`, generato da un motore multi-agente e rifinito a
|
||||
mano prima della consegna. Piano approvato il 2026-08-16, motore ripianificato il
|
||||
2026-08-18.
|
||||
|
||||
### Phase 24: Schema + Whitelist Admin
|
||||
**Goal**: Admin può gestire la whitelist email di ogni cliente, con le tabelle DB pronte per l'OTP gate
|
||||
**Depends on**: Phase 23 (Resend SDK già installato e variabili d'ambiente configurate)
|
||||
**Requirements**: OTP-01
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Admin può aggiungere una o più email alla whitelist di un cliente dalla pagina dettaglio cliente
|
||||
2. Admin può rimuovere un'email dalla whitelist di un cliente
|
||||
3. Le tabelle `client_emails` e `otp_codes` esistono in produzione (migration additive applicata via SSH prima del codice)
|
||||
4. La migration non tocca nessuna delle tabelle protette (`clients`, `projects`, `payments`, `phases`)
|
||||
**Plans**: TBD
|
||||
**UI hint**: yes
|
||||
- [ ] **Phase 27: Motore di analisi** — *in corso, ~50%*
|
||||
- [x] Migration `0017_audits.sql` (7 tabelle additive) — **applicata in prod 2026-08-18**
|
||||
- [x] `checklist_items` seminata, 264 voci — **in prod**
|
||||
- [x] `src/lib/audit/sources/` — 5 moduli, **provati sul campo su giojello.com** (73 s, tutte le fonti hanno risposto). *Scritti, non pushati.*
|
||||
- [ ] `src/lib/audit/schema.ts` + `agents/` (checklist, visual, history, technical, synthesis) con validazione Zod dura
|
||||
- [ ] `src/lib/audit/pipeline.ts` con heartbeat su `audit_runs`
|
||||
- [ ] **Phase 28: Storage immagini** — volume persistente Coolify, `ImageUploadField`, `/api/uploads/[...path]` con guardia sul path traversal. ⚠️ **Checkpoint bloccante: il volume va creato in Coolify PRIMA del deploy**, altrimenti gli upload si perdono a ogni redeploy.
|
||||
- [ ] **Phase 29: Editor admin** — lista audit, editor a payload intero (modello: `admin/offers/actions.ts`), riordino finding e ottimizzazioni con `@dnd-kit/sortable`, registro visite
|
||||
- [ ] **Phase 30: Pagina pubblica + PDF + tracciamento** — `/audit/[slug]`, blocchi condizionali per livello, print CSS per il PDF, `<AuditVisitTracker>` che non conta le aperture da admin loggato
|
||||
|
||||
### Phase 25: OTP Gate + Sessione
|
||||
**Goal**: Il portale `/client/[token]/*` richiede verifica OTP email prima di mostrare la dashboard
|
||||
**Depends on**: Phase 24 (tabelle `client_emails` e `otp_codes` in prod)
|
||||
**Requirements**: OTP-02, OTP-03, OTP-04, OTP-05, OTP-06, OTP-07
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Cliente senza sessione OTP valida vede una schermata "inserisci la tua email" al posto della dashboard
|
||||
2. Inserita un'email in whitelist, il cliente riceve il codice OTP via Resend; inserendo il codice corretto ottiene accesso con cookie valido 30 giorni
|
||||
3. Un'email non in whitelist non riceve OTP — il messaggio d'errore mostrato è identico a quello per email valide (no enumeration)
|
||||
4. Un codice OTP non utilizzato entro 15 minuti viene rifiutato; il cliente deve richiederne uno nuovo
|
||||
5. Tentativi ripetuti sugli endpoint OTP vengono bloccati dal rate limiter (no brute force)
|
||||
**Plans**: TBD
|
||||
> I nomi di 28–30 sono **derivati dalle sezioni §7/§8/§9 del piano approvato**, non ancora
|
||||
> passati da `/gsd-plan-phase`. La numerazione riprende da 27 perché 15–17 sono state
|
||||
> abbandonate o ri-scopate.
|
||||
|
||||
**Ingresso Whop**: predisposto nello schema (`origin`, `external_ref`), **non costruito** —
|
||||
è fase 2, fuori da v2.5.
|
||||
|
||||
## Progress
|
||||
|
||||
Tutte le fasi del progetto, dalla 1 alla 30. La numerazione è **progressiva e mai
|
||||
riusata**: i buchi (15–17) sono fasi abbandonate o ri-scopate, non fasi mancanti.
|
||||
|
||||
| Phase | Milestone | Plans | Status | Completed |
|
||||
|-------|-----------|-------|--------|-----------|
|
||||
| 1–6. Foundation → UX Overhaul | v1.0 | 24/24 | ✅ Done | 2026-06-10 |
|
||||
| 7–10. Unified Catalog → CRM Pipeline | v2.0 | 12/12 | ✅ Done | 2026-06-13 |
|
||||
| 1. Foundation & Client Dashboard | v1.0 | — | ✅ Done | 2026-06 |
|
||||
| 2. Admin Area & Interactive Features | v1.0 | — | ✅ Done | 2026-06 |
|
||||
| 3. Service Catalog & Quote Builder | v1.0 | — | ✅ Done | 2026-06 |
|
||||
| 4. Progetti — Multi-Project per Cliente | v1.0 | — | ✅ Done | 2026-06 |
|
||||
| 5. Offer System | v1.0 | — | ✅ Done | 2026-06 |
|
||||
| 6. UX Overhaul — Sidebar + Dashboard | v1.0 | 24/24 tot. | ✅ Done | 2026-06-10 |
|
||||
| 7. Claude AI Onboarding (v2) | v2.0 | — | ✅ Done | 2026-06 |
|
||||
| 8–10. Unified Catalog → CRM Pipeline | v2.0 | 12/12 tot. | ✅ Done | 2026-06-13 |
|
||||
| 11. Catalog Database-View UX | v2.1 | 4/4 | ✅ Done | 2026-06-13 |
|
||||
| 12. Offer Editor Tier A/B/C | v2.1 | 5/5 | ✅ Done | 2026-06-18 |
|
||||
| 13. Workspace Servizi Attivi | v2.1 | — | ❌ Congelata | — |
|
||||
| 14. CRM Attio-style & Fix | v2.1 | 3/3 | ✅ Done | 2026-06-14 |
|
||||
| 15. Dashboard Revenue Stats | v2.1 | — | ❌ Abbandonata | — |
|
||||
| 16–17. Proposal AI originale | v2.1 | — | ❌ Ri-scopata in v2.2 | — |
|
||||
| 16–17. Proposal AI originale | v2.1 | — | ♻️ Ri-scopata in v2.2 | — |
|
||||
| 18. Cleanup & Consolidamento | v2.2 | 3/3 | ✅ Done | 2026-06-19 |
|
||||
| 19. Pipeline CRM Kanban | v2.2 | 1/1 | ✅ Done | 2026-06-19 |
|
||||
| 20. Knowledge Base Cliente | v2.2 | 3/3 | ✅ Done | 2026-06-20 |
|
||||
@@ -107,50 +105,14 @@ Fuori scope di questo giro, rimandato: tracciamento dei canoni mese per mese (se
|
||||
| 23. Resend Setup | v2.3 | 1/1 | ✅ Done | 2026-07-28 |
|
||||
| 24. Schema + Whitelist Admin | v2.3 | 1/1 | ✅ Done | 2026-07-28 |
|
||||
| 25. OTP Gate + Sessione | v2.3 | 1/1 | ✅ Done | 2026-07-29 |
|
||||
| 13. Ciclo di vita servizi ricorrenti | v2.4 | 1/1 | 🔨 In corso | — |
|
||||
| 13. Ciclo di vita servizi ricorrenti | v2.4 | 1/1 | ✅ Done | 2026-08-01 |
|
||||
| 26. Anteprima admin + login | v2.4 | 1/1 | ✅ Done | 2026-08-08 |
|
||||
| 27. Motore di analisi | v2.5 | 0/1 | 🔨 In corso (~50%) | — |
|
||||
| 28. Storage immagini | v2.5 | 0/1 | ⏳ Da pianificare | — |
|
||||
| 29. Editor admin | v2.5 | 0/1 | ⏳ Da pianificare | — |
|
||||
| 30. Pagina pubblica + PDF | v2.5 | 0/1 | ⏳ Da pianificare | — |
|
||||
|
||||
---
|
||||
*Roadmap aggiornata: 2026-08-18 — v2.4 chiusa, v2.5 "Audit" aperta (era assente: la roadmap
|
||||
è rimasta ferma al 2026-08-08 mentre v2.5 partiva e Phase 27 arrivava a metà).*
|
||||
|
||||
## Requirement Coverage (v2.3)
|
||||
|
||||
| Requirement | Phase |
|
||||
|-------------|-------|
|
||||
| SEND-01 | Phase 23 |
|
||||
| SEND-02 | Phase 23 |
|
||||
| OTP-01 | Phase 24 |
|
||||
| OTP-02 | Phase 25 |
|
||||
| OTP-03 | Phase 25 |
|
||||
| OTP-04 | Phase 25 |
|
||||
| OTP-05 | Phase 25 |
|
||||
| OTP-06 | Phase 25 |
|
||||
| OTP-07 | Phase 25 |
|
||||
|
||||
**Mapped: 9/9. No orphans.**
|
||||
|
||||
---
|
||||
|
||||
## Dependency Chain (v2.3)
|
||||
|
||||
```
|
||||
Phase 23 (Resend config + SDK)
|
||||
└── Phase 24 (schema DB additive: client_emails + otp_codes)
|
||||
└── Phase 25 (OTP gate + sessione cookie 30gg)
|
||||
```
|
||||
|
||||
Phase 23 first: Resend SDK e variabili d'ambiente sono infrastruttura condivisa con Phase 25 (email OTP).
|
||||
Phase 24 before Phase 25: le tabelle `client_emails` e `otp_codes` devono essere in prod (via SSH migration) prima del gate.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes (v2.3)
|
||||
|
||||
**Migration constraint:** `client_emails` e `otp_codes` sono nuove tabelle — migration additiva pura. SQL a mano (drizzle-kit generate rotto da Phase 8). Applicare via SSH tunnel PRIMA di pushare il codice dipendente.
|
||||
|
||||
**OTP middleware layer:** Il token middleware esistente (proxy.ts → `/api/internal/validate-token`) rimane invariato. Il gate OTP è uno strato aggiuntivo dopo la validazione del token, non un suo rimpiazzo.
|
||||
|
||||
**Resend shared infra:** La stessa istanza Resend client e le stesse variabili d'ambiente (`RESEND_API_KEY`, `RESEND_FROM`) servono sia Phase 23 (email preventivo) sia Phase 25 (email OTP). Configurare una volta in Phase 23, riusare in Phase 25.
|
||||
|
||||
**Security invariants (Phase 25, come consegnata):** rate limiting su entrambi gli endpoint OTP; risposta identica per email in whitelist e non; OTP 6 cifre, scade 15 minuti, monouso (`consumed_at` al primo uso), max 5 tentativi; cookie HttpOnly + Secure + SameSite=Lax, **MaxAge 90 giorni** (non 30: modificato il 2026-07-28, compensato dalla revoca admin), per-cliente. Il gate sta in cima alla `page`, non nel layout — vedi la lezione in `STATE.md`.
|
||||
|
||||
---
|
||||
*Roadmap created: 2026-06-21 — v2.3 Email & Accesso*
|
||||
|
||||
+70
-124
@@ -1,157 +1,103 @@
|
||||
---
|
||||
gsd_state_version: 1.0
|
||||
milestone: v2.3
|
||||
milestone_name: Email & Accesso
|
||||
milestone: v2.5
|
||||
milestone_name: Audit
|
||||
status: executing
|
||||
stopped_at: "v2.3 deployata in produzione; resta da popolare la whitelist dei 3 clienti reali"
|
||||
last_updated: "2026-07-29T21:20:00.000Z"
|
||||
last_activity: 2026-07-29 -- dominio Resend verificato, gate OTP deployato in produzione
|
||||
stopped_at: "v2.5 in PAUSA. Modifiche hub: A, B, C1, rifiniture, chat a canali (0021), modifica messaggi + firma (0022), stati task e date pagamenti (0023) in prod; C2 (TidyCal) bloccato sulle credenziali API. Conversazioni (scrittura per primo, menzioni, mail sul tag) pushata il 2026-09-01, nessuna migration, MAI provata a mano. Nulla del portale e' stato visto a schermo: .env.local non autentica piu', serve ?preview=1 in prod. Il riquadro 'Prossimo pagamento' non compare finche' nessuna rata ha una due_date."
|
||||
last_updated: "2026-09-01T00:15:00.000Z"
|
||||
last_activity: 2026-09-01 -- conversazioni: scrivere per primo, menzioni, mail sul tag. Pushata dopo aver recuperato l'accesso a gitea dalla CLI admin
|
||||
progress:
|
||||
total_phases: 3
|
||||
completed_phases: 3
|
||||
total_plans: 3
|
||||
completed_plans: 3
|
||||
percent: 100
|
||||
total_phases: 4
|
||||
completed_phases: 0
|
||||
total_plans: 4
|
||||
completed_plans: 0
|
||||
percent: 25
|
||||
---
|
||||
|
||||
# Project State
|
||||
|
||||
> **Digest breve, per orientarsi.** Narrativa e lezioni → **`STATUS.md`** (root);
|
||||
> requisiti → **`REQUIREMENTS.md`**; tutte le fasi → **`ROADMAP.md`**.
|
||||
> Questo file resta sotto le 100 righe: lo impone il template GSD.
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-06-21)
|
||||
|
||||
**Core value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
|
||||
|
||||
**Current focus:** Milestone **v2.3 "Email & Accesso"** — **consegnata**. Il portale cliente è protetto da gate email OTP. L'invio del preventivo via email (SEND-01/02) è stato rinviato a v2.4 — si manda a mano.
|
||||
See: .planning/PROJECT.md · **Core value:** il cliente apre il link e vede a che punto è
|
||||
il suo progetto, senza scrivere email. · **Current focus:** modifiche hub (v2.5 in pausa).
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 23/24/25 completate e deployate
|
||||
Plan: `~/.claude/plans/si-ma-abbiamo-un-jaunty-micali.md`
|
||||
Status: in produzione. Resta da popolare la whitelist dei 3 clienti reali.
|
||||
Last activity: 2026-07-29 — dominio Resend verificato, deploy su `hub.iamcavalli.net`
|
||||
**v2.5 è in pausa per scelta** (2026-08-19): prima le modifiche all'hub, poi il motore.
|
||||
Phase 27 resta a metà — schema e fonti in prod, resto da scrivere.
|
||||
|
||||
### ✅ Prerequisiti email risolti (2026-07-29)
|
||||
| Blocco (modifiche hub) | Stato |
|
||||
|---|---|
|
||||
| A — Progetti (via commenti/timer, riepilogo, timer per task) | ✅ in produzione 2026-08-19 |
|
||||
| B — Dashboard (inbox, linee di prodotto, timeline consegne) | ✅ in produzione 2026-08-19 |
|
||||
| C1 — `POST /api/webhooks/lead` | ✅ in produzione, provato contro il DB vero |
|
||||
| C2 — TidyCal | ⛔ **[BLOCCANTE]** vedi sotto |
|
||||
| C3 — Alleggerire l'hub | ⏸️ senza perimetro |
|
||||
| Rifiniture — tassonomie, tab pagamenti, riordino task | ✅ in prod 2026-08-20 (`0019`) |
|
||||
| Portale cliente — stepper compatto/full-width, card offerta | ✅ in prod 2026-08-21 (`0020`); override provato su Caruso Speaker |
|
||||
| Chat — canali, modifica messaggi, firma admin | ✅ in prod 2026-08-21 (`0021`, `0022`); **mai provata a mano**; manca l'attribuzione |
|
||||
| Conversazioni — scrivere per primo, menzioni `@Nome`, mail sul tag | ✅ pushata 2026-09-01 (`41530b5`), nessuna migration. Menu dei tag corretto lo stesso giorno: mostrava **una riga per alias** invece che per persona. Build + lint puliti, 23 test sul parser e sul menu; **nessuna mail di tag mai partita davvero** |
|
||||
| Portale — stati task (forma, pill, legenda, «Cancellata») + date dei pagamenti | ✅ in prod 2026-08-22 (`2e9bd2a`, `8b54f48`, `fe76789`, migration `0023`); **mai visto a schermo**, nessuna `due_date` ancora inserita |
|
||||
| D — Whop → audit | ⏸️ dipende dal motore v2.5 |
|
||||
|
||||
- **Dominio `iamcavalli.net` verificato su Resend.** L'utente ha ricreato la registrazione del dominio (nuovo id `f81202f1-3bba-47c5-8c0f-84101440b960`, la precedente `a2a80798-…` non esiste più) e messo i DNS. Tutti e tre i record `verified`: DKIM TXT su `resend._domainkey`, SPF TXT + MX su `send`. Invio da `no-reply@iamcavalli.net` verso un indirizzo esterno confermato riuscito.
|
||||
- *Nota:* ricreare il dominio su Resend **rigenera la chiave DKIM**. Se in futuro il dominio torna `failed`, non fidarsi di valori DKIM annotati in passato — rileggerli da `GET /domains` e confrontarli con `dig +short TXT resend._domainkey.iamcavalli.net @8.8.8.8`.
|
||||
- `RESEND_API_KEY` + `RESEND_FROM` **configurate su Coolify** (production e preview) via API — verificate presenti.
|
||||
- **Mailer verificato**: `sendEmail()` col template OTP reale ha restituito `{ok:true, id:…}`.
|
||||
- Verificato che quando Resend rifiuta, la route risponde comunque col messaggio neutro e logga l'errore lato server — il no-enumeration tiene anche a provider guasto.
|
||||
Progress: [███░░░░░░░] 25% (v2.5)
|
||||
|
||||
### ✅ Verificato in produzione (2026-07-29, commit 27da969)
|
||||
## Dove sta cosa
|
||||
|
||||
Su `hub.iamcavalli.net`: gate mostrato senza cookie e **zero dati di progetto nell'HTML** (12.487 byte); email fuori whitelist e in whitelist danno risposta identica e solo la seconda genera un OTP; codice sbagliato rifiutato, corretto accettato; cookie `ch_sess_<id>` con `Secure` + `HttpOnly` + `SameSite=lax` + `Max-Age=7776000` (90 giorni); rientro col cookie mostra la dashboard; sessione di un cliente sull'URL di un altro mostra il gate. Nessun errore d'invio nei log del container. Dati di test rimossi, tabelle protette invariate (4/5/11/10).
|
||||
I piani della milestone sono **nel repo dal 2026-08-26**: `.claude/plans/v2.5-*.md`.
|
||||
|
||||
### Da fare
|
||||
| Cosa (audit) | Dove | Stato |
|
||||
|---|---|---|
|
||||
| Schema, 7 tabelle + rubrica 264 voci | `0017_audits.sql`, `checklist_items` | **in produzione** |
|
||||
| Fonti del motore (5 moduli) | `src/lib/audit/sources/` | **in prod ma inerte**: nessuna route lo chiama |
|
||||
| Agent, sintetizzatore, pipeline, editor, pagina | `src/lib/audit/`, `src/app/{admin/audit,audit}` | **da scrivere** |
|
||||
| L'unico audit prodotto finora | `spike-audit-giojello.com.json` (gitignorato) | spike 2026-08-16, **zero rilevazioni** |
|
||||
|
||||
Popolare la whitelist dei 3 clienti reali da `/admin/clients/<id>` → "Accessi al portale", e reinviare loro il link. La migration aveva seedato solo `mario@test.it` (cliente di test "Rossi Inc"); Protocollo Estetico, Caruso Speaker e Teckell hanno whitelist vuota e finché lo è il loro portale non è accessibile.
|
||||
## Come funziona il motore
|
||||
|
||||
### Cosa è stato consegnato in v2.3 (codice locale, buildato e testato)
|
||||
|
||||
- **Resend**: `resend@6.18.1`, `src/lib/mailer.ts` (Result tipizzato, mai catch silenzioso) + template OTP in italiano.
|
||||
- **Schema**: migration `0015_otp_access.sql` **già applicata a prod** — `client_emails` (whitelist, unique case-insensitive), `otp_codes` (hash del codice, mai il codice), `clients.sessions_valid_from` (revoca). Additiva pura: conteggi pre/post identici su clients 4 / projects 5 / payments 11 / phases 10.
|
||||
- **Admin**: sezione "Accessi al portale" in `/admin/clients/[id]` — aggiungi/rimuovi email + "Revoca sessioni attive". Server actions in `clients/[id]/actions.ts`. Scritta a token semantici benché la pagina attorno sia ancora a palette vecchia.
|
||||
- **Gate**: `src/lib/otp.ts` (codice 6 cifre CSPRNG, hash SHA-256 con `NEXTAUTH_SECRET`+clientId, TTL 15 min, max 5 tentativi), `src/lib/client-session.ts` (cookie HMAC per-cliente `ch_sess_<id>`, 90 giorni, httpOnly/secure/lax, path=/client), `src/lib/client-gate.ts`, route `/api/client/otp/request|verify`, componente `OtpGate`.
|
||||
|
||||
### ⚠️ Lezione: il gate NON va nel layout
|
||||
|
||||
Prima implementazione: gate in `client/[token]/layout.tsx` che rendeva `<OtpGate/>` al posto di `{children}`. **Non funziona come protezione.** Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: la dashboard spariva a schermo ma fasi, task e pagamenti restavano leggibili nel payload RSC dell'HTML (46.907 byte → 17.594 dopo il fix). Il gate è ora in cima alla `page`, prima di ogni query, via `getClientGate()`. **Ogni nuova route sotto `/client/[token]/` deve fare lo stesso** — il layout porta un commento che lo ricorda.
|
||||
|
||||
### Lavoro recente precedente (in prod)
|
||||
|
||||
- **[2026-07-27/28] Audit di sicurezza**: 4 vulnerabilità chiuse e deployate (secondo gate admin, hardening slug, XSS, CSP/HSTS); slug clienti deboli ruotati a 12 char CSPRNG; `INTERNAL_SECRET` e `ADMIN_PASSWORD` configurati su Coolify. Finding #1 (password Postgres committata) declassato CRITICO→BASSO: verificata inattiva, già ruotata. Report in `.planning/SECURITY-*.md`.
|
||||
- **[2026-07-28] Riorganizzazione cartella**: fasi di planning consolidate, script one-off archiviati in `cestino/`, `CLAUDE.md` arricchito.
|
||||
- **Design system "Quiet Luxury"**: dashboard, liste (Clienti/Offerte/Catalogo/Preventivi/Progetti), Conversazioni, Impostazioni, Pipeline+Kanban, dettaglio Lead e portale cliente base sono a token e dual-theme. **Ancora a design vecchio** (funzionanti, solo estetica): `/admin/offers/[id]/edit`, `/admin/projects/[id]` (il cluster peggiore, ~140 occorrenze fra i suoi tab), `/admin/projects/new`, `/admin/clients/[id]`, `/admin/clients/[id]/edit`, `/admin/login`, badge in `/admin/preventivi/[id]`, chat portale cliente — più, non censiti prima: **tutto `/quote/[token]`** (~40 occorrenze, pagina rivolta al cliente) e `ui/dialog.tsx`, che propaga la palette vecchia a ogni modale.
|
||||
- **Tassonomie**: gestione centralizzata categorie/tag in Impostazioni (`src/lib/taxonomy.ts`).
|
||||
- **Lead → Cliente (A+B)**: `clients.email/phone` + `leads.archived` (migration 0011); `convertLeadToClient`.
|
||||
|
||||
### Fasi completate (v2.2, storico)
|
||||
|
||||
Phase 18 (cleanup), Phase 19 (Kanban CRM), Phase 20 (transcript KB), Phase 21 (AI agent), Phase 22 (deck pubblico) — consegnate e in prod 2026-06-20.
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
|
||||
- Total plans completed: 7 (v2.1) + 9 (v2.2) = 16 totali
|
||||
- Average duration: —
|
||||
- Total execution time: —
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| Phase 11 P01 | 25min | 2 tasks | 6 files |
|
||||
| 11 | 4 | - | - |
|
||||
| 14 | 3 | - | - |
|
||||
|
||||
**Recent Trend:**
|
||||
|
||||
- Last 5 plans: —
|
||||
- Trend: —
|
||||
|
||||
*Updated after each plan completion*
|
||||
| Phase 11 P02 | 12min | 2 tasks | 2 files |
|
||||
| Phase 11 P03 | 9min | 2 tasks | 2 files |
|
||||
| Phase 11 P04 | 12min | 2 tasks | 4 files |
|
||||
Raccolta in parallelo (nessun LLM, nessun browser headless) → quattro sub-agent →
|
||||
sintetizzatore che **incrocia** le osservazioni in massimo 10 finding. Vincolo che
|
||||
regge tutto: **un numero entra solo se misurato**, rintracciabile in `audit_runs.raw`.
|
||||
Passo per passo in `STATUS.md` e in `.claude/plans/v2.5-audit-motore.md`.
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
Log completo in `PROJECT.md`. Vive per il lavoro corrente:
|
||||
|
||||
- **[v2.3 2026-06-21] Resend come provider email unico** — PUB-03 (invio preventivo) e AUTH-OTP-01 (OTP gate) condividono la stessa integrazione Resend. Phase 23 configura SDK + env vars, Phase 25 li riusa.
|
||||
- **[v2.3 2026-06-21] OTP gate è strato aggiuntivo, non rimpiazzo del token middleware** — proxy.ts e `/api/internal/validate-token` rimangono invariati. Il gate OTP interviene dopo la validazione del token, nel rendering della route `/client/[token]/*`.
|
||||
- **[v2.3 2026-06-21] Migration Phase 24 è additiva pura** — `client_emails` e `otp_codes` sono nuove tabelle. Nessun drop/truncate. SQL a mano (drizzle-kit generate rotto). Applicare via SSH prima del codice dipendente.
|
||||
- **[RESET 2026-06-19] Milestone v2.2 "Sales Loop"** sostituisce le fasi residue v2.1. Decisioni bloccate: (1) URL preventivo = `/preventivo/[slug]` pubblico; (2) tagliare Forecast + quote builder manuale + Phase 15, fondere `/admin/analytics` nella dashboard; (3) portale post-vendita resta core, non si tocca (Phase 13 congelata); (4) agente AI = "io scelgo l'offerta, l'AI personalizza" leggendo i transcript, provider Claude. Piano: `.claude/plans/glittery-sprouting-pudding.md`
|
||||
- [SUPERSEDED dal reset] v2.1 roadmap: Offer Studio (Phases 11-15) sequenced before Proposal AI (Phases 16-17) — clean/fast data UX before the AI builder
|
||||
- Phase 11 bundles catalog database-view UX (OFFER-07..10) with legacy consolidation (OFFER-13) since the new UX should be built on a single unified `services` table, not on top of legacy `service_catalog`/`offer_services`
|
||||
- Phase 13 (Workspace — Servizi Attivi) is independent of Phases 11/12 — can execute in parallel order if useful, but numbered after for narrative flow
|
||||
- Phase 15 (Dashboard Revenue Stats / DASH-11) is isolated and BLOCKED on user-provided mockup; no other phase depends on it — can be deferred/skipped without blocking Phase 16/17
|
||||
- Phase 16/17 split: schema/automation (payment link field + auto-provisioning) first, then AI builder + public page redesign + email — keeps the AI-dependent work last
|
||||
- [Phase 11]: Phase 11: hand-write Drizzle migration SQL (0006_add_tags_table.sql) following the project's established convention since drizzle-kit generate is non-functional (meta snapshots out of sync since migration 0001, pre-existing since Phase 8) — Avoids architectural snapshot-reconciliation work (Rule 4, out of scope) while matching exact precedent from migrations 0003-0005
|
||||
- [Phase 11]: Phase 11 Plan 02: onConflictDoNothing() without explicit target compiles cleanly for tags table (single unique index tags_entity_name_unique) — used as written in plan, no fallback needed — Avoids unnecessary deviation; Drizzle's no-target ON CONFLICT DO NOTHING is correct given the single unique constraint from Plan 01
|
||||
- [Phase 11]: Phase 11 Plan 03: removed the plan's prescribed value-sync useEffect (and a follow-up render-time ref-read attempt) from EditableCell — both violate this project's react-hooks lint rules (set-state-in-effect, refs-during-render / React Compiler). tempValue is now only (re)initialized in startEdit()/cancel(), and the toggle display branch reads `value` directly instead of `tempValue` — Rule 1 lint fix, no behavioral change to the 8 spec'd test behaviors
|
||||
- [Phase 11]: Phase 11 Plan 04: left `createService`/`serviceSchema` in `src/app/admin/catalog/actions.ts` as unused dead code after deleting `ServiceForm.tsx` (its only consumer) — `actions.ts` was outside this plan's `files_modified` scope and `updateService` still depends on `serviceSchema`; logged to deferred-items.md for future cleanup
|
||||
- [Phase 18-02]: fmtEur unified to number version (analytics/page.tsx variant); KPI card callers using DB string values wrapped with parseFloat() — cleaner than maintaining two named variants
|
||||
- [Phase 18-02]: /admin/analytics route deleted; YearSelector now routes to /admin?year=Y — single admin entry point for statistics (CLEAN-03)
|
||||
|
||||
### Pending Todos
|
||||
|
||||
[From .planning/todos/pending/ — ideas captured during sessions]
|
||||
|
||||
None yet.
|
||||
- **[2026-09-01] Una lista che serve a leggere non è una lista da offrire in scrittura** — il menu dei tag mostrava tre voci (nome, brand, nome di battesimo) per una persona sola, perché gli era stata passata la stessa lista che il parser usa per **riconoscere** un tag nel testo. Sono due domande diverse: *come lo si può scrivere* (tutti gli alias, invisibili) e *chi si può scegliere* (una riga per destinatario). Ora `MentionTarget` le tiene separate — `label` per il menu, `aliases` per la rilettura — e il filtro passa da `normalizeForSearch`, la stessa normalizzazione del parser: con un `toLowerCase()` a parte, digitare «nicolo» non troverebbe «Nicolò» nel menu mentre nel messaggio verrebbe riconosciuto. Il difetto scalava peggio del valore: con tre contatti sarebbero state nove righe.
|
||||
- **[2026-09-01] L'accesso a Gitea si recupera dalla sua CLI, non dal web** — il push rispondeva 403 (la credenziale nel portachiavi leggeva ma non scriveva) e l'account web non era piu' accessibile, quindi la via del browser era chiusa in partenza. Si rientra da dentro il container: `docker exec -u git gitea-tgw04ws48sogkso84oogwckk gitea admin user change-password` per la password e `... generate-access-token --scopes write:repository --raw` per il token del push. Il token va messo nel portachiavi con `git credential approve`, **non** nell'URL del remote: li' finirebbe in chiaro dentro `.git/config`. Da ricordare perche' senza push non esiste deploy — Coolify parte da `main` e basta.
|
||||
- **[2026-08-22] Un task cancellato esce dai denominatori, non dalla lista** — resta visibile barrato (il cliente ha letto quella voce e deve capire che fine ha fatto) ma non conta, via un solo `countsTowardProgress()` in `task-status.ts`: contarlo terrebbe la fase sotto il 100% per sempre, contarlo come fatto racconterebbe una consegna mai avvenuta. Se in una fase restano solo cancellati torna «Da iniziare»: degenere, ma «Completata» mentirebbe.
|
||||
- **[2026-08-22] Le date dei pagamenti sì, gli importi per riga no** — LOCKED #2 parla di cifre, non di date. Salvate a **mezzogiorno UTC** (a mezzanotte il giorno civile a Roma è già quello dopo) e contate sui giorni civili a Roma in `src/lib/payment-dates.ts`, lo stesso modulo del futuro promemoria email: mail e portale non devono contraddirsi su quanti giorni mancano.
|
||||
- **[2026-08-20] Gli importi scritti a mano non si ricalcolano** — `amount_locked` esclude la riga da `rescalePayments`, e lo scarto fra somma rate e totale si dichiara invece di aggiustarlo. Il backfill dell'ordine rate va per `percent DESC`, non per `ctid`: 3 progetti su 5 erano già scombinati e l'ordine fisico avrebbe fissato l'errore.
|
||||
- **[2026-08-20] Rinominare una fase rinomina anche le fasi dei progetti** — non c'è FK fra tassonomia e `phases`: `importOfferIntoProject` riconosce una fase solo dal titolo (`offer_phase_id` non viene mai popolata). Senza propagazione, il re-import di un'offerta crea una fase duplicata accanto a quella vecchia. È l'unico rename che scrive fuori dal catalogo, quindi l'unico con conferma.
|
||||
- **[2026-08-19] Prima l'hub, poi il motore** — le modifiche all'hub sono indipendenti e a basso rischio, il motore no. Il Whop → audit resta ultimo perché dipende dal motore.
|
||||
- **[2026-08-19] L'incassato non attribuibile si mostra, non si spalma** — i pagamenti stanno sul progetto, non sull'offerta. Un progetto senza offerta finisce in una riga "Senza offerta" separata: spalmarlo darebbe un totale che quadra e righe che mentono.
|
||||
- **[2026-08-19] Il tempo lavorato sopravvive alla cancellazione del task** — `ON DELETE SET NULL`, mai cascade: con cascade, ripulire una fase abbasserebbe in silenzio il fatturato tracciato.
|
||||
- **[2026-08-18] Audit:** design system dell'area admin; nessun renderer headless (il VPS non regge Chromium); laboratorio ≠ campo, quindi nomi distinti per Lighthouse e CrUX; la checklist alimenta il **motore**, non il documento. Per esteso in `STATUS.md`.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
- ~~Record DKIM / dominio Resend~~ — **risolto 2026-07-29**: dominio ricreato e `verified`, invio dal dominio reale confermato.
|
||||
- ~~`RESEND_API_KEY` + `RESEND_FROM` su Coolify~~ — **fatto 2026-07-29**, production e preview.
|
||||
- **Whitelist vuota per 3 clienti su 4** (non bloccante: l'utente li re-invita) — da popolare da `/admin/clients/<id>` → "Accessi al portale".
|
||||
- **Coolify API**: credenziali in `~/.coolify.env` (`export COOLIFY_URL/COOLIFY_TOKEN`, va sorgentato con `set -a; . ~/.coolify.env`). App ClientHub uuid `xsksow44g4kcoo8wocsgkscc`. Il POST su `/api/v1/applications/<uuid>/envs` **non accetta** il campo `is_build_time` (422): mandare solo `key`, `value`, `is_preview`. I token Hetzner/Cloudflare nel file sono **vuoti** → il DNS non è modificabile via API.
|
||||
- **Migrations (sempre valido)**: ogni fase con schema DEVE avere la migration applicata a prod PRIMA di pushare il codice dipendente. `drizzle-kit generate` rotto → SQL a mano. La 0015 è già applicata. Due strade: `cat migration.sql | ssh root@178.104.27.55 "docker exec -i xwkk0040w0kk0gsgcgog8owk psql -U clienthub -d clienthub -v ON_ERROR_STOP=1 --single-transaction"` (autoritativa, nessun tunnel), oppure tunnel `ssh -f -N -L 54321:localhost:54321 root@178.104.27.55` con `DATABASE_URL` riscritto a `127.0.0.1:54321` se serve puntarci il tooling locale.
|
||||
- **`.env.local` punta al DB di PRODUZIONE** (178.104.27.55:54321, richiede il tunnel). Non esiste un DB di sviluppo separato: qualsiasi test in locale scrive su dati reali. Verificare sempre i conteggi delle tabelle protette prima e dopo.
|
||||
- **Debito tecnico (non bloccante)**: tabelle legacy `service_catalog`/`offer_services`/`offer_micro_services` restano come deadweight; `createService`/`serviceSchema` dead code in `catalog/actions.ts`.
|
||||
- **[BLOCCANTE] TidyCal non ha webhook** (verificato 2026-08-19 sulla loro FAQ; la via suggerita è Zapier/Make). La REST API c'è, con Personal Access Token su tutti i piani, ma path, filtri e paginazione **stanno dietro il login**. Sblocca: l'utente apre `tidycal.com/integrations` → API Keys e passa token o documentazione. Non dedurre la forma dell'API dai docs.
|
||||
- **[BLOCCANTE] `LEAD_WEBHOOK_SECRET` non è su Coolify**: finché manca, `/api/webhooks/lead` risponde 403 a tutti (fallimento chiuso voluto). Sblocca: l'utente la imposta.
|
||||
- **Il 100% dell'incassato è "Senza offerta"** — Caruso Speaker e Protocollo Estetico: 5.300 € senza offerte assegnate. Si sistema assegnandole dai rispettivi progetti. Il payload Elementor, intanto, non è ancora verificato sul campo: gestito in modo difensivo, serve un invio vero.
|
||||
- **Il copy del template v1 non ha fonte nel repo** — il prototipo Giojello non c'è: testi e gerarchia dei blocchi da recuperare prima di Phase 30.
|
||||
- **Audit, da vedere sul campo:** il caso "zero dati CrUX" (test 5) e quanto del 52% non verificabile da HTML statico recuperi Lighthouse (test 3). **Whitelist portale vuota per 3 clienti su 4** — si popola da `/admin/clients/<id>`.
|
||||
- **`.env.local` NON è allineato a Coolify**: `ADMIN_PASSWORD`, `NEXTAUTH_SECRET` **e la password del DB** sono stale, e l'host che scrive (`178.104.27.55:5432`) è chiuso — il DB vero è su `127.0.0.1:54321` dietro tunnel SSH. Estrarre la password viva dal container è **bloccato dal classifier** e non va aggirato. Rendere in locale contro i dati veri **oggi non si può** (2026-08-21); sblocca: l'utente riallinea il file alle variabili di Coolify. Le migration non ne soffrono, e resta valido il resto della procedura: **ogni fase con schema applica la migration a prod prima del push del codice**.
|
||||
- **Debito design (DEBT-01)** — ~40 file, ~450 occorrenze. Dettaglio in `STATUS.md`.
|
||||
|
||||
## Deferred Items
|
||||
|
||||
Items acknowledged and carried forward from previous milestone close:
|
||||
|
||||
| Category | Item | Status | Deferred At |
|
||||
|----------|------|--------|-------------|
|
||||
| v2.4 | PROP-03 — Stripe Payment Link su deck pubblico | Backlog | v2.3 kickoff |
|
||||
| v2.4 | PROP-04 — Auto-provisioning cliente/progetto/fasi al "Vinto" | Backlog | v2.3 kickoff |
|
||||
| v2+ | Phase 13 — Servizi attivi/ricorrenti post-vendita | Congelata | v2.1 kickoff |
|
||||
| v2 | OFFER-14 — Sezioni analitiche stile Notion | Backlog | v2.1 kickoff |
|
||||
| v2 | ARCH-01 — Split modulo "compartimento stagno" in deploy separato | Backlog (only if module grows) | v2.1 kickoff |
|
||||
| v2.4 | SEND-01/02 — Invio link preventivo via email dall'admin | Backlog (mailer già pronto) | 2026-07-28 |
|
||||
| Design | 11 pagine ancora a palette vecchia — vedi elenco in "Lavoro recente" | Backlog | 2026-07-28 |
|
||||
## Deferred Items — vedi `REQUIREMENTS.md` § Backlog e § Rinviati da v2.5.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-07-29T21:20:00.000Z
|
||||
Stopped at: v2.3 deployata in produzione. Dominio Resend verificato, Coolify configurato, gate OTP live su `hub.iamcavalli.net`.
|
||||
Next: popolare la whitelist dei 3 clienti reali da `/admin/clients/<id>` → "Accessi al portale", e reinviare loro il link.
|
||||
Resume file: .planning/STATE.md
|
||||
Last session: 2026-08-26
|
||||
Stopped at: **stato task «Cancellata» + date dei pagamenti nel portale** (`fe76789`, migration `0023` applicata a prod prima del push). Un task tolto dal lavoro ora ha dove stare: **X nel cerchio, titolo barrato**, pill «Cancellata» — l'unico stato chiuso con la pill, perché «Fatto» e «Cancellata» sono entrambi barrati e scambiarli significa credere consegnato ciò che non esiste. Esce da **tutti** i denominatori via `countsTowardProgress()`. Nel Kanban cliente la colonna compare solo se piena (mai nascosta se ha dentro qualcosa); nell'admin c'è sempre, ed è così che si cancella un task. Lato pagamenti: `payments.due_date` (nullable, più indice parziale per il futuro promemoria email), riquadro «Prossimo pagamento» con conto alla rovescia in parole e rosso se scaduto, «Scade il…» / «Pagato il…» su ogni riga, **zero importi**. Admin: campo Scadenza per rata, «Incassato nel mese» → «Incassato il» (giorno; le analytics raggruppano per mese e non se ne accorgono). Build, typecheck e lint verdi.
|
||||
**2026-08-26 — architettura `.claude/`**: skill `/preventivo` e `/audit`, due hook di guardia, piani nel repo. Nessun tocco al prodotto. Le due cose trovate e non risolte sul preventivo → `STATUS.md`.
|
||||
|
||||
Next: (0) **[SICUREZZA] rigenerare il token Gitea creato il 2026-09-01**: e' stato incollato in chat, quindi va considerato esposto. Si revoca da Settings -> Applications e si rifa'; (1) verificare in prod con `?preview=1` **entrambe** le cose: stati task su **Caruso Speaker, fase «3 - Esecuzione»** (l'unica con «In corso» e «In revisione» insieme, 4 + 2 su 11) e box pagamenti — ma prima **inserire una scadenza** dal tab Pagamenti, altrimenti il riquadro non compare per definizione; (2) due `paid_at` storici valgono il primo del mese (2026-03-01, 2026-01-01, scritti dal vecchio selettore a mese) e il cliente ora li legge come «Pagato il 1 mar 2026»: correggerli se il giorno vero era un altro; (3) provare la chat in prod: modificare un messaggio admin e vederlo cambiare da solo entro ~20s senza duplicarsi; (4) sbloccare TidyCal con token o documentazione; (5) `LEAD_WEBHOOK_SECRET` su Coolify, senza cui `/api/webhooks/lead` risponde 403 a tutti; (6) poi v2.5 da `src/lib/audit/schema.ts` + `agents/`.
|
||||
Resume file: None
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
# UI Rules — ClientHub admin
|
||||
|
||||
Derived from the live codebase (`src/app/globals.css`, design system usage across admin pages).
|
||||
These are the rules to follow for any new or modified admin page.
|
||||
|
||||
---
|
||||
|
||||
## Brand palette
|
||||
|
||||
All colours must be written as **hex literals** — no Tailwind semantic tokens (`text-foreground`, `bg-muted`, etc.) in admin UI. Semantic tokens are defined in `globals.css` but mixing hex and tokens creates inconsistency.
|
||||
|
||||
| Role | Hex | Usage example |
|
||||
|-------------------|-------------|-----------------------------------------|
|
||||
| Primary | `#1A463C` | Primary buttons, active states, accents |
|
||||
| Primary hover | `#163a31` | Hover on primary buttons |
|
||||
| Accent | `#DEF168` | Brand highlights (use sparingly) |
|
||||
| Foreground | `#1a1a1a` | Body text, headings |
|
||||
| Muted text | `#71717a` | Secondary text, labels, meta |
|
||||
| Border | `#e5e7eb` | Card borders, table dividers, inputs |
|
||||
| Background muted | `#f9f9f9` | Table header rows, card hover bg |
|
||||
| White | `#ffffff` | Card / panel backgrounds |
|
||||
| Destructive | `#dc2626` | Delete/archive actions, error text |
|
||||
|
||||
---
|
||||
|
||||
## Typographic scale
|
||||
|
||||
| Level | Classes |
|
||||
|--------------------|----------------------------------------------|
|
||||
| Page title (h1) | `text-2xl font-bold text-[#1a1a1a]` |
|
||||
| Section heading | `text-base font-semibold text-[#1a1a1a]` |
|
||||
| Subsection (h3) | `text-sm font-bold text-[#71717a] uppercase tracking-wider` |
|
||||
| Body | `text-sm text-[#1a1a1a]` |
|
||||
| Secondary/label | `text-xs text-[#71717a]` |
|
||||
| Numeric values | always add `tabular-nums` |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
- **Page wrapper:** `<div className="space-y-6">` — uniform vertical rhythm, full-width.
|
||||
- **Page header:** always use `<PageHeader>` from `src/components/admin/PageHeader.tsx` — never hand-roll the title + action row.
|
||||
- **No width constraints on list pages:** do not add `max-w-*` or `mx-auto` to the page root. Width is controlled by the sidebar layout (`src/app/admin/layout.tsx`).
|
||||
- **Detail/form pages** (e.g. OfferEditorClient) may keep their own `max-w-4xl mx-auto` — this rule applies to list/overview pages only.
|
||||
- **Cards:** `rounded-lg border border-[#e5e7eb] bg-white p-4`; hover: `hover:shadow-[0_4px_12px_rgba(0,0,0,0.08)]`.
|
||||
- **Tables:** `bg-white rounded-xl border border-[#e5e7eb] overflow-hidden`; thead `bg-[#f9f9f9] border-b border-[#e5e7eb]`; row divider `border-b border-[#e5e7eb]`.
|
||||
|
||||
---
|
||||
|
||||
## Interaction
|
||||
|
||||
- Clickable elements: `cursor-pointer`
|
||||
- Colour transitions: `transition-colors duration-150`
|
||||
- Focus ring: `focus:outline-none focus-visible:ring-2 focus-visible:ring-[#1A463C]/30`
|
||||
- Minimum touch target on buttons: 44 × 44 px (use `py-2 px-4` minimum or `h-10`)
|
||||
- Primary CTA: `bg-[#1A463C] text-white hover:bg-[#163a31] transition-colors`
|
||||
- Secondary/ghost CTA: `border border-[#e5e7eb] text-[#1a1a1a] hover:bg-[#f9f9f9] transition-colors`
|
||||
- Destructive action: `text-[#dc2626] hover:bg-red-50 transition-colors`
|
||||
|
||||
---
|
||||
|
||||
## Anti-patterns (do not do these)
|
||||
|
||||
- **No emoji as UI icons** — use Lucide React icons instead.
|
||||
- **No mixed semantic tokens and hex** — pick hex throughout any given page/component.
|
||||
- **No per-page `max-w-*` on list pages** — layout width is the sidebar shell's responsibility.
|
||||
- **No hand-rolled page header divs** — always use `<PageHeader>` to keep title size/weight/colour uniform.
|
||||
- **No inline `style={{}}` for colours that have a Tailwind class** — reserve `style` for dynamic values only (e.g. progress bar width percentages).
|
||||
@@ -0,0 +1,64 @@
|
||||
# Archivio milestone v2.1 — Offer Studio + CRM
|
||||
|
||||
**Fasi previste:** 11–17 · **Consegnate:** 11, 12, 14 · **Aperta:** 2026-06-13 · **Chiusa per reset:** 2026-06-19
|
||||
|
||||
> **Ricostruito a posteriori il 2026-08-08.** v2.1 è l'unica milestone rimasta senza
|
||||
> archivio: è stata interrotta da un reset di scope e nessuno l'ha chiusa
|
||||
> formalmente, così le sue fasi sono rimaste in `.planning/phases/` per due mesi.
|
||||
> Questo file è ricostruito da `MILESTONES.md`, dalla tabella Progress di
|
||||
> `ROADMAP.md` e dalle cartelle di fase archiviate in [v2.1-phases/](v2.1-phases/).
|
||||
> Non esiste un `v2.1-REQUIREMENTS.md`: i 23 requisiti originali sono stati
|
||||
> sovrascritti quando `REQUIREMENTS.md` è stato riscritto per v2.3.
|
||||
|
||||
## Obiettivo originale
|
||||
|
||||
Offer Studio (fasi 11–15) prima di Proposal AI (fasi 16–17): prima una UX dati
|
||||
pulita e veloce, poi il builder AI costruito sopra.
|
||||
|
||||
## Esito per fase
|
||||
|
||||
| Fase | Titolo | Plans | Esito |
|
||||
|---|---|---|---|
|
||||
| 11 | Catalog Database-View UX + consolidamento legacy | 4/4 | ✅ 2026-06-13 |
|
||||
| 12 | Offer Editor Tier A/B/C | 5/5 | ✅ 2026-06-18 |
|
||||
| 13 | Workspace — Servizi Attivi | — | ❄️ Congelata → ripresa in **v2.4** |
|
||||
| 14 | CRM Attio-style & Fix | 3/3 | ✅ 2026-06-14 |
|
||||
| 15 | Dashboard Revenue Stats | — | ❌ Abbandonata (bloccata su un mockup mai fornito) |
|
||||
| 16–17 | Proposal AI (impianto originale) | — | ♻️ Ri-scopate in v2.2 (fasi 21–22) |
|
||||
|
||||
Documentazione di dettaglio (PLAN, SUMMARY, RESEARCH, VERIFICATION) in
|
||||
[v2.1-phases/](v2.1-phases/).
|
||||
|
||||
## Cosa è stato consegnato
|
||||
|
||||
- **Phase 11 — Catalog Database-View UX** (OFFER-07..10, OFFER-13): il catalogo
|
||||
`services` come tabella a edit inline, tag multi-select, quick-add, ricerca
|
||||
istantanea; consolidamento delle tabelle legacy.
|
||||
- **Phase 12 — Offer Editor Tier A/B/C** (OFFER-11, OFFER-15..18): editor offerte
|
||||
con matrice checkbox servizi × tier, totale live, prezzo pubblico manuale, tag su
|
||||
4 dimensioni, promessa di trasformazione. 55 servizi reali caricati.
|
||||
- **Phase 14 — CRM Attio-style** (CRM-08..12): `/admin/leads` ridisegnata con edit
|
||||
inline e tag multi-select; FollowUpWidget in italiano; LeadForm tipizzato;
|
||||
SendQuoteModal ripulita dai rami irraggiungibili.
|
||||
|
||||
## Il reset del 2026-06-19
|
||||
|
||||
A metà milestone il piano è stato riscritto: la milestone **v2.2 "Sales Loop"**
|
||||
sostituisce le fasi residue. Decisioni bloccate in quel momento:
|
||||
|
||||
1. L'URL del preventivo è `/preventivo/[slug]`, pubblico.
|
||||
2. Si tagliano Forecast, quote builder manuale e Phase 15; `/admin/analytics` viene
|
||||
fusa nella Dashboard.
|
||||
3. Il portale post-vendita resta core e non si tocca (Phase 13 congelata).
|
||||
4. L'agente AI è "io scelgo l'offerta, l'AI personalizza" leggendo i transcript;
|
||||
provider Claude.
|
||||
|
||||
Phase 13 è poi tornata in vita come **milestone v2.4**, consegnata il 2026-08-01.
|
||||
|
||||
## Debito lasciato aperto
|
||||
|
||||
- Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services`
|
||||
rimaste come deadweight.
|
||||
- `createService` / `serviceSchema` dead code in `src/app/admin/catalog/actions.ts`
|
||||
(Phase 11 Plan 04, annotato in `deferred-items.md`).
|
||||
- `offer_micros` senza `created_at` — nessun "tier più vecchio" affidabile.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Requirements: ClientHub v2.3 Email & Accesso
|
||||
|
||||
**Defined:** 2026-06-21
|
||||
**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
|
||||
|
||||
## v2.3 Requirements
|
||||
|
||||
### Email OTP Gate (AUTH-OTP-01)
|
||||
|
||||
Portale cliente blindato da email OTP. Nuovo `client_emails` table (whitelist) + `otp_codes` table (codice, email, expires_at, consumed). Resend come provider email. Sessione **90 giorni** con cookie dopo verifica, revocabile dall'admin.
|
||||
|
||||
- [x] **OTP-01**: Admin può aggiungere e rimuovere email dalla whitelist di ogni cliente nell'admin UI
|
||||
- [x] **OTP-02**: Cliente senza sessione OTP vede una schermata "inserisci email" invece della dashboard
|
||||
- [x] **OTP-03**: Sistema invia OTP via Resend solo se l'email inserita è nella whitelist di quel cliente
|
||||
- [x] **OTP-04**: Cliente inserisce il codice OTP ricevuto e ottiene sessione autenticata (cookie **90 giorni**)
|
||||
- [x] **OTP-05**: Codici OTP scadono dopo 15 minuti dall'invio
|
||||
- [x] **OTP-06**: Endpoint OTP è rate-limited per prevenire brute force
|
||||
- [x] **OTP-07**: Messaggi di errore OTP non rivelano se l'email è in whitelist o no (no enumeration)
|
||||
- [x] **OTP-08**: Admin può revocare in blocco tutte le sessioni attive di un cliente
|
||||
|
||||
> **[2026-07-28] Modifiche alla spec del 2026-06-21**, decise in sessione:
|
||||
> - Sessione **90 giorni** invece di 30 (rientro più fluido), compensata da OTP-08.
|
||||
> - **SEND-01/SEND-02 spostati al backlog v2.4**: il preventivo si invia a mano, l'automazione non serve ora. Phase 23 si è ridotta alla sola infrastruttura Resend, che l'OTP usa comunque.
|
||||
> - **Il gate NON sta nel layout** ma in cima a ogni page sotto `/client/[token]/`. Nell'App Router il segmento `page` viene renderizzato in parallelo al layout: gattare nel layout nascondeva la dashboard a schermo ma lasciava fasi, task e pagamenti nel payload RSC dell'HTML (verificato: 46.907 byte con i dati → 17.594 dopo il fix). Helper: `src/lib/client-gate.ts`.
|
||||
|
||||
## v2.4+ Backlog
|
||||
|
||||
### Conversione Commerciale
|
||||
|
||||
- **PROP-03**: Stripe Payment Link su deck pubblico `/preventivo/[slug]`
|
||||
- **PROP-04**: Auto-provisioning cliente/progetto/fasi al "Vinto" nel CRM
|
||||
- **SEND-01/SEND-02**: invio del link `/preventivo/[slug]` via email dall'admin UI — *rinviato da v2.3 il 2026-07-28, l'invio si fa a mano. L'infrastruttura Resend (`src/lib/mailer.ts`) è già pronta, manca solo l'azione e il pulsante.*
|
||||
|
||||
### Post-Vendita
|
||||
|
||||
- **Phase 13**: Gestione servizi attivi/ricorrenti post-vendita nel portale cliente (congelata da v2.1)
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Self-registration cliente | Solo whitelist admin-gestita — nessun accesso senza approvazione esplicita |
|
||||
| Magic link senza OTP | OTP è più sicuro e già deciso come design; magic link = scope creep |
|
||||
| Email marketing / newsletter | Non pertinente al portale |
|
||||
| Multi-admin | Ancora single admin per ora |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| OTP-01 | Phase 24 | ✅ Done (2026-07-28) |
|
||||
| OTP-02 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-03 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-04 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-05 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-06 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-07 | Phase 25 | ✅ Done (2026-07-28) |
|
||||
| OTP-08 | Phase 24 | ✅ Done (2026-07-28) |
|
||||
| SEND-01 | — | ⏭️ Rinviato a v2.4 |
|
||||
| SEND-02 | — | ⏭️ Rinviato a v2.4 |
|
||||
|
||||
**Coverage:**
|
||||
- v2.3 requirements: 8 in scope (OTP-01…08) + 2 rinviati
|
||||
- Implementati: 8/8 ✓ — verificati con 9 test E2E in locale contro il DB di produzione
|
||||
- **Non ancora in produzione**: il codice è scritto e testato ma NON pushato. Vedi i blocchi in `STATE.md`.
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-06-21*
|
||||
*Last updated: 2026-07-28 — sessione 90gg, OTP-08 aggiunto, SEND-01/02 rinviati, OTP-01…08 implementati*
|
||||
@@ -0,0 +1,99 @@
|
||||
# Archivio milestone v2.3 — Email & Accesso
|
||||
|
||||
**Fasi:** 23–25 · **Aperta:** 2026-06-21 · **Shipped:** 2026-07-29 (commit `27da969`)
|
||||
**Requisiti:** [v2.3-REQUIREMENTS.md](v2.3-REQUIREMENTS.md)
|
||||
|
||||
> **Nota di archivio.** v2.3 è stata eseguita **fuori dal ciclo GSD**: non sono mai
|
||||
> esistite cartelle `phases/23`, `24`, `25` con PLAN/SUMMARY. Questo file *è*
|
||||
> la documentazione della milestone — non cercare altrove.
|
||||
|
||||
## Obiettivo
|
||||
|
||||
Aggiungere uno strato email all'app: gate OTP per il portale cliente e invio del
|
||||
link preventivo dall'admin, con un'unica integrazione Resend condivisa.
|
||||
|
||||
Il portale non doveva più essere apribile col solo link: chiunque avesse l'URL
|
||||
vedeva il progetto del cliente.
|
||||
|
||||
## Fasi
|
||||
|
||||
### Phase 23 — Resend Setup ✅ 2026-07-28
|
||||
|
||||
**Goal:** infrastruttura email condivisa.
|
||||
**Requisiti:** SEND-01, SEND-02 (poi ridotti — vedi sotto).
|
||||
|
||||
Consegnato: `resend@6.18.1`, `src/lib/mailer.ts` (Result tipizzato, mai un catch
|
||||
silenzioso), template OTP in italiano. `RESEND_API_KEY` e `RESEND_FROM` configurate
|
||||
su Coolify (production **e** preview).
|
||||
|
||||
**Riduzione di scope del 2026-07-28:** SEND-01/SEND-02 (invio del preventivo via
|
||||
email dall'admin) spostati al backlog. Il preventivo si manda a mano; l'automazione
|
||||
non serviva subito. Phase 23 si è ridotta alla sola infrastruttura Resend, che il
|
||||
gate OTP usa comunque.
|
||||
|
||||
### Phase 24 — Schema + Whitelist Admin ✅ 2026-07-28
|
||||
|
||||
**Goal:** l'admin gestisce la whitelist email di ogni cliente; tabelle pronte per il gate.
|
||||
**Requisiti:** OTP-01. **Dipende da:** Phase 23.
|
||||
|
||||
Migration `0015_otp_access.sql`, **additiva pura**, applicata a prod via SSH prima
|
||||
del codice dipendente: `client_emails` (whitelist, unique case-insensitive),
|
||||
`otp_codes` (hash del codice, mai il codice in chiaro), `clients.sessions_valid_from`
|
||||
(revoca in blocco). Conteggi pre/post identici sulle tabelle protette —
|
||||
clients 4 / projects 5 / payments 11 / phases 10.
|
||||
|
||||
UI: sezione "Accessi al portale" in `/admin/clients/[id]` — aggiungi/rimuovi email,
|
||||
"Revoca sessioni attive". Server actions in `clients/[id]/actions.ts`.
|
||||
|
||||
### Phase 25 — OTP Gate + Sessione ✅ 2026-07-29
|
||||
|
||||
**Goal:** `/client/[token]/*` richiede verifica OTP prima di mostrare la dashboard.
|
||||
**Requisiti:** OTP-02..OTP-07. **Dipende da:** Phase 24.
|
||||
|
||||
Consegnato: `src/lib/otp.ts` (codice 6 cifre CSPRNG, hash SHA-256 con
|
||||
`NEXTAUTH_SECRET`+clientId, TTL 15 minuti, monouso, max 5 tentativi),
|
||||
`src/lib/client-session.ts` (cookie HMAC per-cliente `ch_sess_<id>`, httpOnly +
|
||||
secure + SameSite=lax, `path=/client`), `src/lib/client-gate.ts`, le route
|
||||
`/api/client/otp/request|verify`, il componente `OtpGate`.
|
||||
|
||||
**Scostamento dalla spec del 21/06:** sessione **90 giorni** invece di 30 — rientro
|
||||
più fluido, compensato da OTP-08 (revoca in blocco lato admin).
|
||||
|
||||
## Catena di dipendenze
|
||||
|
||||
```
|
||||
Phase 23 (Resend SDK + env)
|
||||
└── Phase 24 (schema additivo: client_emails + otp_codes)
|
||||
└── Phase 25 (gate OTP + sessione cookie 90gg)
|
||||
```
|
||||
|
||||
## Copertura requisiti
|
||||
|
||||
| Requisito | Fase | Esito |
|
||||
|---|---|---|
|
||||
| SEND-01, SEND-02 | 23 | ⏭ Rinviati al backlog il 2026-07-28 |
|
||||
| OTP-01 | 24 | ✅ |
|
||||
| OTP-02 … OTP-07 | 25 | ✅ |
|
||||
| OTP-08 (revoca) | 24 | ✅ |
|
||||
|
||||
## Verifica in produzione (2026-07-29, `hub.iamcavalli.net`)
|
||||
|
||||
Gate mostrato senza cookie e **zero dati di progetto nell'HTML** (12.487 byte);
|
||||
email fuori e dentro whitelist danno risposta identica e solo la seconda genera un
|
||||
OTP; codice sbagliato rifiutato, corretto accettato; cookie `ch_sess_<id>` con
|
||||
`Secure` + `HttpOnly` + `SameSite=lax` + `Max-Age=7776000`; rientro col cookie
|
||||
mostra la dashboard; la sessione di un cliente sull'URL di un altro mostra il gate.
|
||||
Nessun errore d'invio nei log del container. Dati di test rimossi, tabelle protette
|
||||
invariate.
|
||||
|
||||
## Lezioni
|
||||
|
||||
Le due lezioni operative di questa milestone (il gate non va nel layout App Router;
|
||||
ricreare il dominio su Resend rigenera la chiave DKIM) sono in `STATUS.md`,
|
||||
sezione "Lezioni operative" — è lì che si vanno a cercare.
|
||||
|
||||
## Strascico alla chiusura
|
||||
|
||||
La whitelist è stata seedata solo con `mario@test.it` (cliente di test). Tre clienti
|
||||
reali su quattro hanno whitelist vuota e finché lo è **il loro portale non è
|
||||
accessibile**. Voce aperta in `STATUS.md`.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Requirements: ClientHub v2.4 Post-vendita
|
||||
|
||||
**Definiti:** 2026-08-08 (ricostruiti a posteriori — v2.4 è partita senza requisiti scritti)
|
||||
**Core Value:** Il cliente apre il link e vede esattamente a che punto è il suo progetto, cosa deve ancora succedere e cosa ha già approvato — senza dover scrivere email per chiedere aggiornamenti.
|
||||
|
||||
Milestone precedente: [v2.3 Email & Accesso](milestones/v2.3-ROADMAP.md), shipped 2026-07-29.
|
||||
|
||||
## Consegnati
|
||||
|
||||
### Ciclo di vita dei servizi ricorrenti (Phase 13) — ✅ in produzione 2026-08-01
|
||||
|
||||
- [x] **RET-01**: Un'offerta ricorrente assegnata a un progetto ha uno stato (attivo / sospeso / cessato) e una data di fine opzionale
|
||||
- [x] **RET-02**: L'admin può sospendere, riattivare e cessare un retainer dalla tab Offerte del progetto
|
||||
- [x] **RET-03**: Il forecast a 12 mesi smette di sommare un retainer sospeso, cessato o oltre la sua `end_date`
|
||||
- [x] **RET-04**: Lo storico del venduto (`getOffersSoldBreakdown`) **non** filtra per stato — escludere le cessate riscriverebbe il passato
|
||||
- [x] **RET-05**: Il cliente vede stato, "attivo dal / fino al" e "canone mensile"; le offerte cessate non gli arrivano
|
||||
|
||||
### Anteprima admin e login (Phase 26) — ✅ in produzione 2026-08-08
|
||||
|
||||
- [x] **PREV-01**: L'admin può aprire il portale di un cliente in sola lettura senza passare dal gate OTP (`?preview=1` + sessione Auth.js valida)
|
||||
- [x] **PREV-02**: In anteprima approvazione e composer messaggi sono disattivati a livello di UI
|
||||
- [x] **AUTH-09**: Il campo password del login admin ha un toggle mostra/nascondi
|
||||
|
||||
## Backlog v2.4+ (non pianificati)
|
||||
|
||||
Ereditati dalle chiusure di milestone precedenti, nessuno in corso:
|
||||
|
||||
- [ ] **SEND-01 / SEND-02** — Invio del link `/preventivo/[slug]` via email dall'admin. Il mailer (`src/lib/mailer.ts`) è già pronto e in produzione dalla v2.3: manca solo il pulsante e l'action. *Rinviati il 2026-07-28.*
|
||||
- [ ] **PROP-03** — Stripe Payment Link sul deck pubblico del preventivo. *Rinviato al kickoff v2.3.*
|
||||
- [ ] **PROP-04** — Auto-provisioning di cliente / progetto / fasi al passaggio del lead a "Vinto". *Rinviato al kickoff v2.3.*
|
||||
- [ ] **RET-06** — Canoni mensili tracciabili (agosto pagato / settembre no). **Serve una tabella nuova**: `payments` è protetta dai vincoli di Data Safety e la sua riscalatura è pensata per i piani una tantum. *Fuori scope di Phase 13.*
|
||||
- [ ] **OFFER-14** — Sezioni analitiche stile Notion sull'offerta. *Rinviato al kickoff v2.1.*
|
||||
- [ ] **ARCH-01** — Split del modulo "compartimento stagno" in un deploy separato. *Solo se il modulo cresce.*
|
||||
- [ ] **DEBT-01** — Debito design: **~40 file, ~450 occorrenze** di palette Tailwind raw e hex literal al posto dei token semantici. I cluster: `/admin/projects/[id]` e i suoi tab (~182), `/admin/offers/[id]/edit` (~79), `/admin/clients/[id]` (~59), tutto `/quote/[token]` (~48, ed è rivolto al cliente), `ChatPanel` del portale (37), più `ui/dialog.tsx` che propaga il look vecchio a ogni modale. Esclusi perché legittimi: `AdminSidebar` (eccezione brand documentata), `src/lib/mailer.ts` (HTML email, niente CSS var), i colori di stato di `StatusBadge` (sanzionati dal design system, hanno già le varianti `dark:`). *Misurato il 2026-08-08 — la stima precedente di "11 pagine" era sottostimata.*
|
||||
- [ ] **DEBT-02** — Tabelle legacy `service_catalog` / `offer_services` / `offer_micro_services` come deadweight; `createService` / `serviceSchema` dead code in `src/app/admin/catalog/actions.ts`.
|
||||
|
||||
## Aperto, non un requisito
|
||||
|
||||
**Whitelist del portale vuota per 3 clienti su 4.** La migration 0015 ha seedato solo
|
||||
`mario@test.it` (cliente di test). Protocollo Estetico, Caruso Speaker e Teckell hanno
|
||||
whitelist vuota e finché lo è **il loro portale non è accessibile**. Si popola da
|
||||
`/admin/clients/<id>` → "Accessi al portale", poi va reinviato il link.
|
||||
|
||||
## Fuori scope
|
||||
|
||||
- File hosting (vincolo LOCKED #5: i documenti restano URL esterni).
|
||||
- Tabella utenti / multi-admin: l'auth resta una singola credenziale da env.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Phase 13 — Ciclo di vita dei servizi ricorrenti
|
||||
|
||||
**Milestone:** v2.4 Post-vendita · **Stato:** ✅ in produzione, verificata end-to-end
|
||||
**Consegnata:** 2026-08-01 · **Commit:** `5177a37` · **Migration:** `0016_project_offer_lifecycle.sql`
|
||||
|
||||
> **Ricostruito a posteriori il 2026-08-08** dal commit, dalla migration e da
|
||||
> `STATUS.md`. La fase è stata eseguita fuori dal ciclo GSD: non esiste un PLAN.
|
||||
> Phase 13 nasce congelata in v2.1 (giugno) e riaperta come milestone v2.4.
|
||||
|
||||
## Il problema
|
||||
|
||||
Un retainer, una volta assegnato, non si poteva fermare. `project_offers` aveva solo
|
||||
`start_date`, e il ramo retainer di `src/lib/forecast-queries.ts` sommava il canone a
|
||||
**ogni mese** dell'orizzonte da lì in poi, per sempre. Un cliente che disdiceva
|
||||
continuava a gonfiare il forecast a 12 mesi e a vedersi l'abbonamento attivo nel
|
||||
proprio portale.
|
||||
|
||||
## Cosa è stato fatto
|
||||
|
||||
**Schema** — migration `0016`, additiva pura, applicata a prod **prima** del push:
|
||||
`project_offers.status` (`attivo|sospeso|cessato`, CHECK `NOT VALID` per evitare un
|
||||
lock lungo) e `project_offers.end_date` (nullable, NULL = continuativo). Default
|
||||
`'attivo'` così ogni riga esistente conserva esattamente il comportamento precedente.
|
||||
Nessun DROP, nessun TRUNCATE. Idempotente.
|
||||
|
||||
**Forecast** — i retainer si fermano a `end_date`; sospesi e cessati escono dal
|
||||
calcolo. `getOffersSoldBreakdown` **non** filtra per stato di proposito: è uno
|
||||
storico di vendita, ed escludere le cessate riscriverebbe il passato.
|
||||
`offersAcceptedTotal` esclude le cessate (default del piano pagamenti).
|
||||
|
||||
**Admin** — comandi Sospendi / Riattiva / Cessa più data di fine nella tab Offerte,
|
||||
mostrati solo per i ricorrenti. `setProjectOfferLifecycle` valida con Zod e filtra
|
||||
**anche per `project_id`**, così un id arbitrario non può toccare un altro progetto.
|
||||
|
||||
**Portale cliente** — "Attivo dal", "fino al", badge *In pausa*, "Canone mensile" al
|
||||
posto di "Prezzo finale". Le offerte cessate non arrivano mai al client.
|
||||
|
||||
**Fix collaterale** — un retainer sospeso continuava a intestare i pagamenti "Totale
|
||||
Pagamento Mensile" e a sovrascriverne l'importo.
|
||||
|
||||
## Decisioni
|
||||
|
||||
- **Storico di vendita ≠ forecast.** Due letture diverse degli stessi dati: il
|
||||
breakdown del venduto ignora lo stato, il forecast lo rispetta. Unificarle
|
||||
avrebbe fatto sparire fatturato già incassato dai report.
|
||||
- **Default `'attivo'` invece di NULL.** Rende la migration a comportamento
|
||||
invariato senza una backfill separata.
|
||||
- **Filtro per `project_id` nell'action**, non solo per id dell'offerta: difesa in
|
||||
profondità contro un id manipolato.
|
||||
|
||||
## Fuori scope, rimandato
|
||||
|
||||
Tracciamento dei canoni mese per mese (agosto pagato / settembre no). Serve una
|
||||
tabella nuova: `payments` è protetta dai vincoli di Data Safety e la sua riscalatura
|
||||
è pensata per i piani una tantum. Voce di backlog in `REQUIREMENTS.md`.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Phase 26 — Anteprima admin del portale + toggle password sul login
|
||||
|
||||
**Milestone:** v2.4 Post-vendita · **Stato:** ✅ in produzione (deploy Coolify 2026-08-08)
|
||||
**Commit:** `09a5b1f` (toggle password) · `187550f` (anteprima admin)
|
||||
|
||||
> **Ricostruito a posteriori il 2026-08-08.** Lavoro non pianificato in roadmap,
|
||||
> nato da due attriti d'uso reali. 26 è il primo numero di fase libero.
|
||||
|
||||
## 1. Toggle mostra/nascondi password — `09a5b1f`
|
||||
|
||||
Il campo password del login admin non offriva modo di rileggere quanto digitato: un
|
||||
accesso fallito era indistinguibile da un errore di battitura.
|
||||
|
||||
Toggle **inline**, non un nuovo primitivo in `ui/`: `type="password"` compare una
|
||||
sola volta in tutto il codebase, un'astrazione avrebbe avuto un solo consumatore.
|
||||
`type="button"` perché dentro un `<form>` il default è submit; `tabIndex={-1}` per
|
||||
tenere il Tab sulla sequenza campo → Accedi. Classi a token semantici; gli hex
|
||||
literal preesistenti della pagina restano da migrare col resto del debito design.
|
||||
|
||||
**Causa a monte (non era un bug):** `ADMIN_PASSWORD` è stata ruotata il 2026-07-28
|
||||
**solo su Coolify**, e `.env.local` è rimasto alla precedente. Vale anche per
|
||||
`NEXTAUTH_SECRET`. `.env.local` non è allineato a produzione e non va trattato come
|
||||
fonte di verità per le credenziali.
|
||||
|
||||
## 2. Anteprima admin in sola lettura del portale — `187550f`
|
||||
|
||||
Quando un cliente segnalava "non trovo una cosa" non c'era modo di guardare il
|
||||
portale con i suoi occhi: il gate OTP lascia entrare solo lui. Dall'elenco clienti
|
||||
(`ClientRow`) un'icona apre ora `/client/<slug>?preview=1` in una scheda nuova.
|
||||
|
||||
**Come funziona.** `getClientGate()` accetta `{ previewRequested }` e salta il gate
|
||||
solo se il query param c'è **e** `getServerSession(authOptions)` è valida. Senza il
|
||||
param anche un admin vede il gate OTP — così il gate resta testabile dal vivo.
|
||||
Ritorna `preview: true` **senza sintetizzare una `ClientSession`**: un admin in
|
||||
anteprima non è un cliente autenticato, e confondere i due stati li renderebbe
|
||||
indistinguibili proprio dove serve distinguerli. Il flag viaggia via
|
||||
`PreviewProvider` / `usePreview()` e non per prop drilling: `ApproveButton` sta
|
||||
quattro livelli sotto la dashboard.
|
||||
|
||||
**Perché sola lettura.** Il portale scrive davvero: `/api/client/approve` e
|
||||
`/api/client/comment` autenticano sul token nel body, non sulla sessione, e
|
||||
`deliverables.approved_at` è immutabile una volta impostato (**LOCKED #3**). Un
|
||||
click distratto approverebbe un deliverable in modo irreversibile. La protezione è
|
||||
a livello **UI, non API**: un admin può ancora chiamare le route a mano. È voluto —
|
||||
l'obiettivo è impedire l'incidente, non difendersi da sé stessi.
|
||||
|
||||
## ⚠️ Deviazione consapevole dal vincolo LOCKED #4
|
||||
|
||||
`CLAUDE.md` fissa: `/client/[token]/*` → token middleware, `/admin/*` → sessione
|
||||
Auth.js. Ora una route client legge **anche** la sessione Auth.js. Non indebolisce
|
||||
nulla — per i clienti il gate OTP è identico — ma la sezione LOCKED richiede
|
||||
approvazione esplicita prima di essere modificata. **Annotato in `CLAUDE.md` il
|
||||
2026-08-08 con l'ok dell'utente.**
|
||||
|
||||
## Verifica
|
||||
|
||||
**Verificato** col build di produzione su `:3100` contro il DB reale (sole letture):
|
||||
`?preview=1` senza sessione admin → gate OTP; con cookie di sessione contraffatto →
|
||||
gate OTP; `?preview=0`, `?preview=abc`, `?preview=` → gate OTP; nessun query param
|
||||
**con** sessione admin → gate OTP (nessuna regressione); sessione admin valida +
|
||||
`?preview=1` → portale con banner e composer disattivato, sia sul cliente a progetto
|
||||
singolo sia su quello a due progetti.
|
||||
|
||||
**Non verificato dal vivo:** il ramo `ApproveButton` — in produzione la tabella
|
||||
`deliverables` è **vuota** (0 righe), quindi quel pulsante oggi non si renderizza
|
||||
mai. Wiring controllato solo a livello di codice. Il click dell'occhiolino sul login
|
||||
è verificato solo nel markup renderizzato (`type="button"`, `tabindex="-1"`,
|
||||
`aria-label`).
|
||||
|
||||
**Nota di metodo:** Playwright non funziona contro `npm run dev` — la CSP blocca
|
||||
`eval` e i client component non si idratano. Va usato il build di produzione.
|
||||
@@ -1,107 +0,0 @@
|
||||
# FEATURES.md — ClientHub Freelancer Client Portal
|
||||
|
||||
**Domain:** Freelancer client portal — solo personal branding consultant
|
||||
**Project:** ClientHub (welcomeclient.iamcavalli.net)
|
||||
**Researched:** 2026-05-09
|
||||
**Confidence:** HIGH
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Two asymmetric roles. Admin (the freelancer) has full CRUD. Client (read + lightweight interaction) accesses via secret URL — no login, no account — and can view, comment, and approve. The product competes indirectly with Notion client portals, HoneyBook, Dubsado, and bespoke agency portals. The differentiator is zero-friction secret link access and personal brand positioning.
|
||||
|
||||
---
|
||||
|
||||
## Table Stakes
|
||||
|
||||
Features clients expect when opening any project portal. Missing these causes confusion, distrust, or support overhead.
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|------------|-------|
|
||||
| Project overview at a glance | Client needs to know "where we are" without reading walls of text | Low | Name, brand, brief, current phase |
|
||||
| Phase + task status visibility | Primary client question is "what's done, what's next" | Low | Phases with nested tasks; status per task (todo / in progress / done) |
|
||||
| Deliverable approval | Client must formally sign off on outputs | Medium | Per-deliverable approve action; state persists; admin sees approval timestamp |
|
||||
| Inline commenting on tasks/deliverables | Feedback and questions without email | Medium | Flat comments sufficient for v1; threading is nice-to-have |
|
||||
| Document / file links | Deliverables, briefs, contracts surface in the portal | Low | Links to Google Drive, PDF, external URL; no file hosting needed |
|
||||
| Payment status visibility | Client needs to know what they owe | Low | Deposit 50% + balance 50%; three states each: pending / invoiced / paid |
|
||||
| Total quoted amount (not itemized) | Client expects to see the agreed number | Low | Single total; line items are admin-only |
|
||||
| Mobile-readable layout | Clients open links on phones | Low | Responsive web; no native app |
|
||||
| Persistent secret link | Link must not expire or rotate without notice | Low | UUIDs in DB, never regenerated unless admin resets explicitly |
|
||||
| Trustworthy, branded appearance | First impression determines confidence in the consultant | Low | Logo, brand colors, professional typography — not a generic SaaS look |
|
||||
|
||||
---
|
||||
|
||||
## Differentiators
|
||||
|
||||
Not expected, but meaningfully improve experience or workflow.
|
||||
|
||||
| Feature | Value Proposition | Complexity | Notes |
|
||||
|---------|-------------------|------------|-------|
|
||||
| Decision log / history | Running record of agreed decisions — eliminates "we never agreed on that" disputes | Low | Append-only note stream visible to client; admin writes entries |
|
||||
| Phase progress indicator | Visual progress bar gives a sense of momentum | Low | Derived from task completion %; no extra data model needed |
|
||||
| "Last updated" timestamp on dashboard | Shows the portal is live and maintained | Low | Trivially derived from DB updated_at |
|
||||
| Admin overview: all clients at a glance | Freelancer scans all active projects and overdue payments in one view | Medium | List with status badges; payment alert if overdue |
|
||||
| Payment status badge with clear labels | Color-coded states (red = unpaid, yellow = invoiced, green = paid) | Low | Client sees their own; admin sees all |
|
||||
| Shareable link reset | Admin can invalidate and regenerate a client's link if it leaks | Low | DB field update + redirect; rarely used but reassuring |
|
||||
| Service catalog | Admin builds quotes from a curated menu of services; reusable across clients | Medium | Lookup table; admin-only; used by Claude in v2 |
|
||||
| Claude-assisted onboarding (v2) | Generates phases + quote draft from a brief — massively speeds up admin work | High | Explicitly v2 in PROJECT.md |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Features
|
||||
|
||||
Deliberately NOT building these.
|
||||
|
||||
| Anti-Feature | Why Avoid | What to Do Instead |
|
||||
|--------------|-----------|-------------------|
|
||||
| Client login / account creation | Adds friction with no benefit for a small client list | Secret UUID link |
|
||||
| In-app invoicing / PDF generation | Accounting is out of scope | Show payment status only |
|
||||
| File upload / storage | Massive complexity | Link to Google Drive or Dropbox |
|
||||
| Email / SMS notifications | Transactional email infrastructure is heavy | Manual communication fine for small client list |
|
||||
| Multi-admin / team roles | Freelancer works alone | Single admin |
|
||||
| Client-editable project structure | Clients editing phases corrupts admin's source of truth | Comment and approve only |
|
||||
| Itemized pricing visible to client | Erodes commercial confidentiality | Single total; detail is admin-only |
|
||||
| Kanban / drag-and-drop board | Phases are sequential, not a fluid backlog | Ordered phase list |
|
||||
| Time tracking | Out of scope for project-based billing | Not relevant |
|
||||
| Multi-language / i18n | Single consultant, single-market | Hardcode interface language |
|
||||
|
||||
---
|
||||
|
||||
## Feature Dependencies
|
||||
|
||||
```
|
||||
Secret link (UUID) → Client dashboard
|
||||
Client dashboard → Phase/task display
|
||||
Phase/task display → Deliverable approval
|
||||
Phase/task display → Inline commenting
|
||||
Admin client management → Secret link generation
|
||||
Admin client management → Payment tracking
|
||||
Service catalog → Quote building (admin picks from catalog)
|
||||
Quote building → Payment tracking (total = basis for deposit/balance)
|
||||
Service catalog → Claude onboarding v2
|
||||
```
|
||||
|
||||
**Key insight:** Admin must create data before the client dashboard shows anything meaningful. Admin-first, then client.
|
||||
|
||||
---
|
||||
|
||||
## MVP Build Order
|
||||
|
||||
1. Admin: create/edit client record with secret link generation
|
||||
2. Admin: create/edit phases and tasks per client
|
||||
3. Admin: set payment amounts and statuses
|
||||
4. Client dashboard: read-only view (overview, phases, tasks, payment status, documents)
|
||||
5. Client: deliverable approval
|
||||
6. Client: inline comments
|
||||
7. Admin: all-clients overview
|
||||
8. Admin: service catalog
|
||||
9. v2: Claude-assisted onboarding
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
- What happens when a client accidentally shares their secret link? Is link reset sufficient, or should there be an access log?
|
||||
- Does the decision log need to be visible to clients from day one, or deferred?
|
||||
- Should approval actions be reversible (un-approve)?
|
||||
@@ -1,412 +0,0 @@
|
||||
# Feature Landscape: Business Operations Suite v2.0 (New Features)
|
||||
|
||||
**Domain:** Proposal generation + lightweight CRM for solo personal-branding consultant
|
||||
**Researched:** 2026-06-10
|
||||
**Research Mode:** Ecosystem (proposal software + lightweight CRM patterns)
|
||||
**Confidence:** MEDIUM-HIGH
|
||||
**Scope:** ONLY new v2.0 features (does NOT review v1.0 table stakes already shipped)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The Business Operations Suite adds three interconnected workflows to ClientHub:
|
||||
|
||||
1. **Proposal Generation & Delivery** — Sales call → multistep proposal page (2-hour delivery) → lead selects tier A/B/C → acceptance triggers automation
|
||||
2. **Lead Pipeline Management** — Minimal CRM for tracking prospects through 5 stages (Contacted → Qualified → Proposal Sent → Negotiating → Won/Lost)
|
||||
3. **Onboarding Automation** — When lead is marked Won, auto-create client + project with phases copied from chosen offer + configurable payment schedule
|
||||
|
||||
**For a solo consultant, this is radically different from team CRMs** (Pipedrive, HubSpot, GoHighLevel). Avoid: territory management, team routing, email automation, role-based access, forecasting rollups, lead scoring algorithms. Instead: **minimal data entry, follow-up reminders based on last-contact date, and seamless handoff from proposal acceptance to project setup.**
|
||||
|
||||
**Core insight:** Solo consultants manage long-term relationships across years, not one-time deals closed in 30 days. Pipeline stages should reflect relationship milestones (Contacted, Qualified, Proposal Sent), not sales rep activity (Attempted, Left Message). Follow-ups are "who did I talk to recently?" not "assign task to rep."
|
||||
|
||||
---
|
||||
|
||||
## Table Stakes Features (New v2.0)
|
||||
|
||||
Features users expect when adopting a proposal + CRM system. Missing these = product feels incomplete.
|
||||
|
||||
### Proposal Generation & Delivery
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|-----------|-------|
|
||||
| Pick client + 1–3 offers, set per-quote prices | Core value: sales call → proposal in 2 hours. Prices set per quote, not from catalog (allows price increases over time without updating service catalog) | Medium | Depends on existing `offers` & `clients` (Phase 5). Quote prices override offer base prices. |
|
||||
| Generate public multistep HTML/CSS page | Leads need clickable link, not PDF email. Interactive engagement beats static documents (Qwilr/Proposify standard). Reduces abandonment. | Medium | Responsive, mobile-first, branded with consultant name/logo. No login required. |
|
||||
| Multistep flow (intro → pricing tiers → CTA) | Reduces cognitive overload vs. single long page. Step 1: offer overview. Step 2: A/B/C tiers with pricing. Step 3: accept/decline button. | Low | Conditional logic hides irrelevant sections; simple progressive disclosure. |
|
||||
| Public acceptance button (no e-signature) | Lead confirms tier choice WITHOUT entering hub. Triggers: timestamp capture + email record + lead status update. | Low | Simple "Accept this offer" button → records accepted_at + accepted_by_email. E-signature deferred (design ready, v1 constraint). |
|
||||
| Proposal URL shareable & public | Lead receives link in email, opens in browser, no friction. | Low | Generate unique slug (`/proposal/[uuid]`). No auth. Optionally expires after N days or on acceptance. |
|
||||
| Acceptance proof (signer + timestamp) | Documentation for dispute resolution. Downloadable PDF or stored audit record. | Low | Store: accepted_by_name, accepted_by_email, accepted_at, accepted_offer_id. |
|
||||
|
||||
### Lead Pipeline
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|-----------|-------|
|
||||
| Pipeline stages: Contacted → Qualified → Proposal Sent → Negotiating → Won/Lost | Core tracking. Each stage requires buyer action, not just rep activity. Termination: Won or Lost. | Low | **Minimal for solo:** 5 stages max. More = data entry overhead. Stages are immutable enums. |
|
||||
| Move lead between stages (UI) | Basic pipeline UX. See all leads grouped by stage at a glance. | Low | Dropdown per row (simple) or kanban board (polish). Dropdown sufficient for MVP. |
|
||||
| Lead details: name, email, company, phone, last_contact_date, next_action, notes | Minimum context for follow-ups. | Low | Notes = freeform text (call outcomes, concerns, personality notes, next steps). |
|
||||
| Lead created manually OR auto-created from proposal send | Manual: import prospects. Auto-create: when proposal sent to unknown email, create lead record automatically. | Low | Auto-create is convenience; manual is fallback. Both supported. |
|
||||
| Log activities: calls, emails, meetings, notes | Track interactions without leaving dashboard. Auto-updates last_contact_date. | Low | Activity types: [call, email, meeting, note]. Log date, duration, description. Displayed as feed. |
|
||||
|
||||
### Follow-Up Reminders
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|-----------|-------|
|
||||
| Dashboard widget: "Follow up today" sorted by last_contact_date | Solves core pain: "who did I talk to recently that I should check in with?" | Low | Query: WHERE last_contact_date <= TODAY - 7 days AND stage NOT IN (Won, Lost). Red badge. |
|
||||
| Proposal stall detector: if Proposal Sent >3 days, no response | Flags silence = red flag for follow-up. | Low | Simple dashboard alert; no email automation (consultant checks dashboard in morning). |
|
||||
| Auto-update last_contact_date on activity | Keeps reminders accurate. Prevents "I called them but forgot to log it" drift. | Low | Trigger: on call/email/meeting/note creation OR stage change → update lead.last_contact_date = NOW. |
|
||||
|
||||
### Project Auto-Creation (Won → Onboarding)
|
||||
|
||||
| Feature | Why Expected | Complexity | Notes |
|
||||
|---------|--------------|-----------|-------|
|
||||
| On lead.stage = Won: auto-create `client` + `project` with copied phases | Closing automation. Proposal acceptance → instant hub readiness for delivery. | Medium | Requires: chosen offer known, project_offers finalized (Phase 5), 1-4 configurable installments. |
|
||||
| Copy offer phases → project phases (modifiable) | Project inherits offer structure but can be customized per client without mutating offer template. | Medium | Phases are modifiable in hub (Phase 1). Creation source logged: "Copied from Offer X on [date]" for audit. |
|
||||
| Set payment installments per project (not per offer) | Payment plan configured case-by-case: some 50/50, others 4-part. Allows flexibility. | Medium | Templates: 50/50 (acconto/saldo), 3-part, 4-part, custom. UI: choose template during Won → project creation. |
|
||||
| Lead → Client transition: copy email, create token, link to existing client if repeat | Avoid duplicate clients. Allow linking Won lead to existing client (repeat engagement). | Medium | Check email collision. If exists: "Add project to existing client X?" vs. "Create new client". Generate secret token. |
|
||||
|
||||
---
|
||||
|
||||
## Differentiators (New v2.0)
|
||||
|
||||
Features that set ClientHub apart from generic proposal software + CRM. Not expected, but valued for solo consultant use case.
|
||||
|
||||
| Feature | Value Proposition | Complexity | Notes |
|
||||
|---------|-------------------|-----------|-------|
|
||||
| Tier-independent offer structure (Signature A/B/C as separate offers) | Each tier has own URL, phases, pricing. A = professional, B = budget—same catalog, different scope. No cloning, no inheritance logic. | Medium | Requires flexible offer builder (drag services between phases), offer status (draft/active/archived). Built in Phase 5. |
|
||||
| Proposal phases visible in public page (lead sees what they're buying) | Lead sees not just price, but scope: "4-week branding sprint, 3 revision rounds, monthly retainer". Transparency builds confidence. | Low | Proposal page shows phase names, deliverables summary (text), timeline (start + duration). |
|
||||
| Dashboard follow-up list filterable by offer type + stage | "Show all Signature A leads in Negotiating" to spot bottlenecks by tier. | Low | Filter buttons: by offer type, stage, last_contact_date range. Dropdown or toggle buttons. |
|
||||
| Activity feed per lead (call notes, email log, meetings, searchable) | Context without leaving dashboard. "Last contact: 2026-05-28, 11am call—timeline concerns". | Medium | Depends on activity logging system. Store type, date, duration, description. Searchable. |
|
||||
| Proposal pages branded with consultant info (not generic SaaS) | Proposal is part of sales process; branding reinforces personal brand. | Low | Logo, consultant name, brand colors, professional typography inherited from admin settings. |
|
||||
| Email integration hint (design ready, defer to later batch) | Send proposal via dashboard; auto-log email send as activity. | Medium | Deferred per PROJECT.md (v1 constraint). Placeholder: manual copy-paste OK for MVP. |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Features: What NOT to Build (v2.0)
|
||||
|
||||
| Anti-Feature | Why Avoid | What to Do Instead |
|
||||
|--------------|-----------|-------------------|
|
||||
| Multi-user team collaboration, role-based access | Solo consultant is single admin. Team features add auth complexity, sync issues, notification storms. Overhead >> value. | Stay single-admin. Architecture with permission flags but don't build UI/logic. If team joins later, migrate incrementally. |
|
||||
| CRM email automation, drip campaigns, email sequences | Solo consultant sends proposals + checks in manually. Automation-heavy workflows are for outbound prospecting funnels (not this use case). Lead generation not in scope. | Keep simple: dashboard reminder = "check in with X". Consultant sends email manually, logs it as activity. |
|
||||
| Forecasting with rollups, quota tracking, team capacity planning, territory assignment | These are team sales metrics. Solo consultant cares: "How many leads in pipeline?" and "What's revenue if all Negotiating deals close?" | Simple dashboard: shows total value by stage (e.g., "Negotiating: $45k"), breakdown by offer type. No forecast math. |
|
||||
| Lead scoring, MQL → SQL qualification algorithms, scoring rules | Solo consultant qualifies leads manually (call + gut feel). Scoring requires training data and tuning. | Keep manual: stage = Contacted, Qualified, Proposal Sent. "Qualified" is consultant's call. No automation. |
|
||||
| Calendar sync, email sync, call recording, Slack/Teams integration | Adds external dependency surface area. Consultant logs calls + emails manually. | Fallback: freeform "Call notes" text field per activity. No attempt to auto-log from email/Slack. |
|
||||
| Multi-currency support, tax calculation, invoice generation, accounting system integration | Accounting is out of scope (PROJECT.md locked). Payment tracking only. | Keep simple: amount_accepted in EUR, payment schedule in local currency. No conversion logic or invoicing. |
|
||||
| Proposal version control, edit history, detailed audit trail | Overkill for solo consultant. One proposal per client, accept or decline. | Simple: created_at, updated_at timestamps. Accepted version is locked (immutable once accepted_at set). No versioning. |
|
||||
| Client can reverse/un-approve acceptance | Creates ambiguity in closing. | Once accepted_at is set, proposal is final. Consultant can move lead back to Proposal Sent if needed. |
|
||||
|
||||
---
|
||||
|
||||
## Feature Dependencies (v2.0)
|
||||
|
||||
```
|
||||
Proposal Generation:
|
||||
├─ clients (exists, Phase 1)
|
||||
├─ projects (exists, Phase 1)
|
||||
├─ offers (Phase 5: id, name, offer_type [Entry/Signature/Retainer/custom], created_at)
|
||||
├─ services catalog (Phase 3: id, name, price, duration_days)
|
||||
└─ offer_services (Phase 5: junction table, offers ↔ services)
|
||||
|
||||
Lead Pipeline & CRM:
|
||||
├─ leads table (NEW: id, name, email, company, phone, created_at, last_contact_date, stage, offer_id FK, next_action text)
|
||||
├─ activities table (NEW: id, lead_id FK, type enum [call/email/meeting/note], log_date, description, duration_minutes)
|
||||
├─ lead_stage enum (NEW: Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost)
|
||||
|
||||
Project Auto-Creation (Won → Onboarding):
|
||||
├─ leads.stage = Won (from pipeline, not auto-set)
|
||||
├─ projects (exists, must be creatable via API/trigger)
|
||||
├─ phases (exists, must be copyable from offer phases)
|
||||
├─ payments (Phase 5: must support project_id FK, amount, due_date, status)
|
||||
└─ clients.token (exists, Phase 1/4: rotatable secret)
|
||||
|
||||
Proposal Public Pages:
|
||||
└─ proposals table (NEW: id, client_id, lead_email, offers [JSON array], created_at, public_url, accepted_at, accepted_by_name, accepted_by_email, accepted_offer_id)
|
||||
```
|
||||
|
||||
**Critical dependency:** Phase 5's `project_offers` relationship must be finalized. If not, proposal generation cannot proceed. Phase 7 proposal work is blocked by Phase 5 completion.
|
||||
|
||||
---
|
||||
|
||||
## Feature Categorization by Component
|
||||
|
||||
### Component 1: Proposal Builder & Public Pages
|
||||
|
||||
**Responsibility:**
|
||||
- Admin UI: select client, pick 1–3 offers, confirm per-quote pricing, set lead email, generate shareable link
|
||||
- Public page: multistep form (intro → tiers → CTA), responsive, no login, branded
|
||||
- Acceptance: simple "Accept" button, no e-signature
|
||||
- Database: `proposals` table
|
||||
|
||||
**Features in scope:**
|
||||
- Proposal generation from client + offers + prices
|
||||
- Public multistep page with interactive tier selection
|
||||
- Conditional phase visibility (show/hide sections based on tier)
|
||||
- Acceptance button + timestamp + email capture
|
||||
- Auto-create lead on proposal send (if lead email not in DB)
|
||||
- Proposal expiry (optional, default: never)
|
||||
|
||||
**Database schema:**
|
||||
```
|
||||
proposals:
|
||||
id UUID PK
|
||||
client_id FK → clients
|
||||
lead_email VARCHAR (recipient)
|
||||
offer_ids JSON array (which offers are included)
|
||||
quote_prices JSON {offer_id: price} (per-quote override)
|
||||
created_at timestamp
|
||||
updated_at timestamp
|
||||
public_url slug
|
||||
accepted_at timestamp nullable
|
||||
accepted_by_name VARCHAR nullable
|
||||
accepted_by_email VARCHAR nullable
|
||||
accepted_offer_id FK nullable (which tier was chosen)
|
||||
```
|
||||
|
||||
### Component 2: Lead Pipeline & Dashboard
|
||||
|
||||
**Responsibility:**
|
||||
- Lead table with name, email, company, stage, last_contact_date, notes
|
||||
- Dashboard: table or kanban view of all leads grouped by stage
|
||||
- Activities: log calls, emails, meetings, notes
|
||||
- Follow-up reminder widget: leads not contacted in 7+ days
|
||||
|
||||
**Features in scope:**
|
||||
- Create/edit/delete leads manually or auto-create from proposal
|
||||
- Move lead between stages (dropdown or drag/drop)
|
||||
- Log activities: type [call/email/meeting/note], duration, description
|
||||
- Auto-update last_contact_date on activity
|
||||
- Follow-up reminders: "Follow up today" widget, proposal stall detector
|
||||
- Lead notes: freeform text, searchable
|
||||
- Filter by offer type, stage, date range
|
||||
- Activity feed per lead (searchable)
|
||||
|
||||
**Database schema:**
|
||||
```
|
||||
leads:
|
||||
id UUID PK
|
||||
name VARCHAR
|
||||
email VARCHAR (unique or indexed)
|
||||
company VARCHAR nullable
|
||||
phone VARCHAR nullable
|
||||
stage enum [Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost]
|
||||
offer_id FK → offers nullable (which offer was sent)
|
||||
created_at timestamp
|
||||
last_contact_date date
|
||||
next_action text nullable (next step consultant plans)
|
||||
notes text (accumulated call notes, concerns, personality)
|
||||
|
||||
activities:
|
||||
id UUID PK
|
||||
lead_id FK → leads
|
||||
type enum [call, email, meeting, note]
|
||||
log_date timestamp
|
||||
duration_minutes INT nullable
|
||||
description text
|
||||
created_at timestamp
|
||||
```
|
||||
|
||||
### Component 3: Project Auto-Creation & Onboarding Flow
|
||||
|
||||
**Responsibility:**
|
||||
- On lead.stage = Won, trigger creation: new client (if not exists), new project, copy phases, set payment schedule
|
||||
- UI: lead moves to Won → modal: "Which offer was chosen?" → "Confirm project creation?" → choose payment template → create
|
||||
- Result: lead archived, project appears in /admin/projects, client gets dashboard URL
|
||||
|
||||
**Features in scope:**
|
||||
- Auto-create client from lead details
|
||||
- Auto-create project with copied phases
|
||||
- Copy phases from offer (modifiable in hub)
|
||||
- Payment installments: choose template → creates N payment records
|
||||
- Generate client secret token + dashboard URL
|
||||
- Optional: link to existing client instead of creating new
|
||||
- Notification: "Lead X → Project Y created on [date]"
|
||||
|
||||
**Database schema:**
|
||||
```
|
||||
No new tables needed. Uses existing: clients, projects, phases, payments.
|
||||
When lead → Won:
|
||||
1. Check if lead.email in clients table
|
||||
2. If not: create new client, generate secret token
|
||||
3. If yes: ask to link to existing client or create new
|
||||
4. Copy phases from offer_id to new project
|
||||
5. Create N payment records based on chosen template
|
||||
6. Update lead.stage = Won (already set by UI)
|
||||
7. Record: project creation_source = "Lead X, offer Y"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MVP Recommendation
|
||||
|
||||
### Phase 7 (MVP): Core Proposal Generation + Basic Pipeline
|
||||
|
||||
**Priority 1: Must-Have (Launch features)**
|
||||
|
||||
1. **Proposal builder UI:** client + offer(s) + per-quote prices → generate public multistep page
|
||||
2. **Public proposal page:** Step 1 = offer overview, Step 2 = A/B/C tiers + pricing, Step 3 = "Accept this Offer" CTA
|
||||
3. **Acceptance flow:** "Accept" button → timestamp + email capture, marks proposal as accepted
|
||||
4. **Lead auto-creation:** when proposal sent to unknown email, auto-create lead record
|
||||
5. **Basic lead pipeline:** Contacted, Qualified, Proposal Sent, Negotiating, Won, Lost stages
|
||||
6. **Lead dashboard:** table view, move stage via dropdown, lead details sidebar
|
||||
7. **Follow-up reminder widget:** leads not contacted in 7+ days, sorted by last_contact_date, dashboard badge
|
||||
8. **Activity logging (basic):** create call/email/meeting records, auto-update last_contact_date
|
||||
|
||||
**Estimated effort:** 5–7 days (proposal builder UI + public page + lead CRUD + follow-up reminders)
|
||||
|
||||
**Launch readiness:** Solo consultant can generate proposal in 2 hours, track lead through pipeline, see follow-up reminders.
|
||||
|
||||
---
|
||||
|
||||
### Phase 8 (Enrichment): Lead Context & Polish
|
||||
|
||||
**Priority 2: Features**
|
||||
|
||||
1. **Lead notes:** freeform text per lead, searchable
|
||||
2. **Activity feed:** display recent activities per lead (call, email, meeting, note), searchable
|
||||
3. **Dashboard filters:** by offer type, stage, date range (last_contact_date)
|
||||
4. **Proposal stall detector:** flag if Proposal Sent >3 days with no activity
|
||||
5. **Lead detail card:** expand to show full context (notes, activities, next_action) without leaving dashboard
|
||||
|
||||
**Estimated effort:** 3–4 days
|
||||
|
||||
**Value:** Consultant has full context for each lead without switching views.
|
||||
|
||||
---
|
||||
|
||||
### Phase 9+ (Automation & Onboarding): Project Auto-Creation
|
||||
|
||||
**Priority 3: Features**
|
||||
|
||||
1. **Project auto-creation:** on lead → Won, auto-create client + project with copied phases
|
||||
2. **Copy phases from offer:** phases inherit name, duration, deliverables from offer template; modifiable in hub
|
||||
3. **Payment installments:** choose template (50/50, 3-part, 4-part, custom) → create N payment records
|
||||
4. **Client token generation:** auto-generate secret token, send dashboard URL to client
|
||||
5. **Duplicate client check:** if lead.email exists in clients, ask to link or create new
|
||||
6. **Won lead notification:** dashboard shows "Lead X → Project Y created", activity logged
|
||||
|
||||
**Estimated effort:** 3–4 days
|
||||
|
||||
**Value:** Closing automation. Lead acceptance → instant project setup in hub, ready for delivery.
|
||||
|
||||
---
|
||||
|
||||
## Complexity Assessment (Effort & Maintenance)
|
||||
|
||||
| Feature | Dev Effort | Maintenance Burden | Deferability | Phase |
|
||||
|---------|-----------|-------------------|----------------|-------|
|
||||
| Proposal generation (builder UI + logic) | 2–3 days | Low (static) | No—core | 7 |
|
||||
| Public multistep page (HTML/CSS template) | 1–2 days | Low (static) | No—core | 7 |
|
||||
| Acceptance flow (button + timestamp) | 1 day | Minimal | No—core | 7 |
|
||||
| Lead pipeline (CRUD + stage transitions) | 1 day | Low | No—core | 7 |
|
||||
| Follow-up reminders (dashboard query) | 4 hours | Minimal | No—core | 7 |
|
||||
| Activity logging (calls, emails, meetings) | 1 day | Low | Yes—Phase 8 | 8 |
|
||||
| Activity feed (search + timeline) | 1 day | Low | Yes—Phase 8 | 8 |
|
||||
| Lead notes + search | 1 day | Low | Yes—Phase 8 | 8 |
|
||||
| Dashboard filters (offer type, stage, date) | 1 day | Low | Yes—Phase 8 | 8 |
|
||||
| Project auto-creation (trigger + cascade) | 2 days | Medium (error handling) | Yes—Phase 9 | 9 |
|
||||
| Payment installments (templates) | 1 day | Low | Yes—Phase 9 | 9 |
|
||||
| Client token generation + link | 4 hours | Low | Yes—Phase 9 | 9 |
|
||||
| Duplicate client check | 4 hours | Low | Yes—Phase 9 | 9 |
|
||||
| Email integration (send proposal, auto-log) | 2–3 days | Medium (provider) | Yes—defer | Later |
|
||||
| Multi-user + team features | 3–5 days | Medium-High (roles) | N/A—anti-feature | Never |
|
||||
|
||||
**Total Phase 7 MVP:** ~5–6 days
|
||||
**Total Phases 7–9:** ~11–14 days (complete suite)
|
||||
|
||||
---
|
||||
|
||||
## Solo Consultant Design Constraints
|
||||
|
||||
### What's Different from Team CRMs
|
||||
|
||||
| Constraint | Implication | Design Pattern |
|
||||
|-----------|-----------|-----------------|
|
||||
| Single admin, no team routing | No "assign to rep" or "owner" field. All leads = Simone. | All leads belong to admin; no ownership concept. No role-based UI. |
|
||||
| Relationship-heavy, not transaction-heavy | Leads stay in pipeline for months, not 30 days. | Stage = relationship milestone (Contacted, Qualified, Proposal Sent), not rep activity (Attempted, Left Message, Following Up). |
|
||||
| Qualitative follow-up, not automation | "Check in with X, heard timeline concerns" not email sequences. | Notes + activity log, no email automation. Manual send, logged as activity. |
|
||||
| Low deal volume (5–15 in flight) | Pipeline visualization doesn't need advanced analytics. | Simple table or 5-column kanban board. No forecasting rollups. |
|
||||
| Minimal data entry tolerance | Won't log every call if it takes >3 clicks. | Modal: "Log call → name/date/notes → save" in <10 seconds. |
|
||||
| No role-based access | No "manager sees forecast, rep sees pipeline". | Single "admin dashboard" with all data. No permission layers. |
|
||||
| No forecasting pressure | Consultant forecasts deal value by feel, not rollup math. | Dashboard shows "Total Negotiating: $45k". That's it. No probability weighting. |
|
||||
| Calendar/email often offline (field work) | Email sync is nice-to-have, not must-have. | Fallback: manual entry. No real-time sync requirement. |
|
||||
| Accountability is personal, not hierarchical | No "why is this deal stalled?" escalations. | Follow-up reminder = consultant decides action. No automatic escalations. |
|
||||
|
||||
### UX Patterns for Solo Consultant
|
||||
|
||||
1. **Minimize data entry by default:** Yes/No confirmations, checkboxes, dropdowns. Avoid text fields unless essential.
|
||||
2. **Context visible by default:** Open a lead → see last 3 activities, next_action, stage, offer type in one view. No tabs.
|
||||
3. **Dashboard as command center:** Lead reminders + upcoming payments + next meetings all visible. No app switching.
|
||||
4. **Proposal as shared artifact:** Lead sees what they're buying (phases, deliverables, price). Consultant sees acceptance status + lead email.
|
||||
5. **Automation where it reduces clicks:** Accept proposal → auto-create lead. Move to Won → ask once for payment plan, auto-create project. Don't auto-email.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Benchmark (Reference)
|
||||
|
||||
From industry research:
|
||||
|
||||
| Metric | Benchmark | Implication for ClientHub |
|
||||
|--------|-----------|---------------------------|
|
||||
| Typical pipeline stages | 5–7 stages | ClientHub uses 5: Contacted, Qualified, Proposal Sent, Negotiating, Won/Lost. Minimal overhead. |
|
||||
| Proposal Sent → Negotiation conversion | 40%+ | Flag stale proposals (>3 days, no activity) in dashboard. |
|
||||
| Negotiation → Won conversion | 50%+ | If low, consultant reviews proposal scope or pricing. |
|
||||
| Lead follow-up frequency | 8+ touches to close | Activity logging tracks touches (calls, emails, meetings). No automation; manual follow-up. |
|
||||
| Typical pipeline review cadence | Weekly or bi-weekly | Consultant checks dashboard daily; reviews pipeline health weekly. |
|
||||
| Average deal cycle for consultants | 30–90 days | ClientHub supports long cycles (no pressure to close fast). |
|
||||
|
||||
---
|
||||
|
||||
## Confidence & Sources
|
||||
|
||||
| Area | Confidence | Basis | Sources |
|
||||
|------|------------|-------|---------|
|
||||
| Proposal software features (multistep, acceptance, tiering) | HIGH | Verified with Qwilr, PandaDoc, Proposify; 2026 comparison articles | [Qwilr vs PandaDoc](https://www.proposify.com/blog/qwilr-vs-pandadoc), [PandaDoc vs Proposify vs Qwilr](https://saas-tools.medium.com/pandadoc-vs-proposify-vs-qwilr-which-proposal-tool-is-worth-your-budget-in-2026-8e8339d6ab87), [8 best proposal software](https://www.getaccept.com/blog/proposal-software) |
|
||||
| Pipeline stage structure (5–7 stages, Won/Lost termination) | HIGH | Verified with Pipedrive, Capsule CRM, Salesforce; "Proposal Sent → Negotiation → Won" is standard | [Salesforce Pipeline Management](https://www.salesforce.com/sales/pipeline/management/), [CRM Pipeline Stages](https://prospeo.io/s/crm-pipeline-stages), [GoHighLevel Pipeline](https://ecosire.com/blog/ghl-crm-pipeline-management) |
|
||||
| Lead follow-up reminders (last_contact_date, 7+ days flagged) | MEDIUM-HIGH | Sourced from Outreach, HubSpot, Nimble best practices; solo consultant context is reasonable inference | [Sales Pipeline Best Practices](https://www.nimble.com/blog/best-practices-of-sales-pipeline-management/), [Outreach Pipeline Management](https://www.outreach.ai/resources/blog/sales-pipeline-management-best-practices) |
|
||||
| Solo consultant CRM avoidance of team features | MEDIUM | Sourced from "Best CRM for Solopreneurs" guides; solo preference for simplicity consistent across 3+ sources | [Breakcold: CRM for Consultants](https://www.breakcold.com/blog/crm-for-consultants), [Authencio: CRM for Freelancers](https://www.authencio.com/blog/best-crm-for-consultants-freelancers-guide), [Addtocrm: Best CRM Solopreneurs](https://addtocrm.com/tools/best-crm-for-solopreneurs), [Mimiran: Anti-CRM](https://www.mimiran.com/fun-crm-for-solo-consultants-who-hate-selling/) |
|
||||
| Tiered proposal (A/B/C independent offers) | MEDIUM-HIGH | Verified via multiple consulting pricing guides; "3 tiers ideal" is consensus. Independent offers is ClientHub-specific. | [Mercury: Pricing Strategy](https://mercury.com/blog/pricing-strategy-consulting), [Ignition: Tiered Pricing](https://www.ignitionapp.com/blog/tiered-pricing-strategy-for-professional-services-proposal-templates), [Consulting Success: Consulting Rates](https://www.consultingsuccess.com/consulting-rates) |
|
||||
| Multi-step form engagement patterns | HIGH | Verified with Heyflow, Optimonk, HubSpot research; form completion rates improve with progressive disclosure | [Instapage: Multi-Step Forms](https://instapage.com/blog/multi-step-forms), [HubSpot: Multi-Step Forms](https://blog.hubspot.com/marketing/multi-step-forms), [Webstacks: Multi-Step Form Examples](https://www.webstacks.com/blog/multi-step-form) |
|
||||
| Proposal acceptance automation (→ project creation) | MEDIUM | Sourced from Anchor, Estimate Rocket, Monograph workflows. ClientHub implementation is custom but pattern is established. | [Sayanchor: Proposal Acceptance](https://www.sayanchor.com/post/proposal-acceptance-guide), [Monograph: Build, Send, Sign](https://monograph.com/blog/build-send-and-sign-proposals-with-pipeline), [DocuSign: Workflow Automation](https://www.docusign.com/blog/workflow-automation-electronic-signatures) |
|
||||
|
||||
---
|
||||
|
||||
## Open Questions for Later Phases
|
||||
|
||||
1. **Email integration:** Should proposals be sent via dashboard integration, or manual copy-paste? (Deferred to Phase 10+)
|
||||
2. **Proposal expiry:** Should proposals auto-expire after N days, or stay open indefinitely? (MVP: no expiry)
|
||||
3. **Lead de-duplication:** If lead email is already in clients table, how should system handle it? (MVP: manual check; Phase 9+ auto-detect)
|
||||
4. **Activity type richness:** Should activities include location, participant names, sentiment tags? (MVP: basic type + notes; Phase 8 can enhance)
|
||||
5. **Proposal versioning:** Can consultant send multiple proposals to same lead? (MVP: yes, same lead.email + new proposal record)
|
||||
6. **Payment plan customization:** Can consultant define custom installment schedules, or only use templates? (MVP: templates; Phase 9 can add custom)
|
||||
7. **Lead archive vs. delete:** When lead is Won → converted to client/project, should lead record stay in DB for history? (Recommendation: keep for audit trail; mark archived or moved_to_project_id)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Frequently Asked Questions
|
||||
|
||||
**Q: Why no e-signature in MVP?**
|
||||
A: Design is ready (CLAUDE.md notes it as deferred). A simple "Accept" button + timestamp is sufficient proof of acceptance for solo consultant use case. E-signature (DocuSign, Stripe Sign) adds external dependency and cost; defer unless client explicitly requests.
|
||||
|
||||
**Q: Should proposals auto-expire?**
|
||||
A: No, not in MVP. Solo consultant may send proposal Monday, follow up Thursday, acceptance Friday. Expiry is team-sales friction (forces re-quote). Keep simple: accepted_at = null means still open.
|
||||
|
||||
**Q: Can a lead be in two stages at once?**
|
||||
A: No. Stage is singular immutable state at any moment. If second proposal sent to same lead: either (a) create new lead record (same email, add suffix "2"), or (b) update same lead.stage to "Proposal Sent" again. Option (b) is simpler; stage can repeat; last_contact_date updates on each proposal send.
|
||||
|
||||
**Q: Should activities auto-log from email/Slack?**
|
||||
A: No, not in MVP. Adds external dependency surface. Fallback: consultant manually logs calls/emails as activities in <10 seconds. Acceptable for solo consultant volume (5–15 leads).
|
||||
|
||||
**Q: What if lead email already exists in clients table?**
|
||||
A: Phase 9 auto-detection: when moving lead to Won, check if lead.email in clients. If yes, ask: "Link to existing client X (repeat engagement)?" or "Create new client". Prevents duplicate records.
|
||||
|
||||
**Q: Can phases be reordered after project creation?**
|
||||
A: Yes. Phases are copied from offer at project creation time, but project phases are modifiable in hub (Phase 1, already built). Offer template is never mutated. Studio-grade immutability.
|
||||
|
||||
**Q: What's the payment flow after Won → project creation?**
|
||||
A: Consultant chooses payment template (50/50, 3-part, 4-part, custom) during Won → project creation modal. System creates N records in `payments` table with due_dates calculated from project start_date. Client sees payment schedule in hub dashboard (Phase 1, already built). No invoicing or collection automation (out of scope, PROJECT.md locked).
|
||||
|
||||
**Q: Can consultant change their mind after accepting a proposal?**
|
||||
A: If consultant moves lead back to Proposal Sent or Negotiating (after accepting and creating project), the original accepted_proposal record remains immutable. Project can be deleted/archived if needed, but proposal acceptance is final. This matches real-world: once accepted, consultant can't un-close a deal.
|
||||
|
||||
---
|
||||
|
||||
**End of FEATURES_v2.0.md**
|
||||
+1177
-85
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user