simone
8000d562dc
La roadmap era ferma al 2026-08-08 e diceva ancora "nessuna fase aperta" mentre
v2.5 era gia' partita e Phase 27 era a meta'; REQUIREMENTS.md era ancora quello
di v2.4. STATE.md invece era corretto — segno che aggiornare solo quello non
basta. Da qui la divisione dei ruoli, ora esplicita in testa a ogni file:
- STATE.md orientamento breve (99 righe): dove sta cosa, come funziona il
motore, i blocchi vivi. Niente narrativa.
- ROADMAP.md tutte le fasi 1->30, con lo stato di ciascuna
- REQUIREMENTS.md i 25 requisiti di v2.5 (AUD-01..25) e il backlog
- STATUS.md l'unica narrativa lunga: lezioni e note tecniche
v2.4 chiusa e archiviata in milestones/v2.4-REQUIREMENTS.md.
Decisione nuova: il documento di restituzione usa il design system dell'area
admin ("Quiet Luxury"), non una tipografia sua — token semantici, Plus Jakarta
Sans, Geist Mono per metriche e date, StatusBadge per gli impatti. Sostituisce
la deroga tipografica prevista dal piano. I font sono gia' self-hostati da
next/font/google, quindi la CSP font-src 'self' e' soddisfatta senza lavoro, e
il documento non aggiunge debito a DEBT-01 perche' nasce gia' a token.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
200 lines
11 KiB
Markdown
200 lines
11 KiB
Markdown
# ClientHub (IAMCAVALLI) — Status
|
||
|
||
_Ultimo aggiornamento: 2026-08-18_
|
||
|
||
Questo è **l'unico documento narrativo** del progetto: a che punto siamo, cosa manca,
|
||
cosa abbiamo imparato. `.planning/STATE.md` è il digest che leggono i comandi
|
||
`/gsd-*` — non raddoppia questo file, ci rimanda.
|
||
|
||
## Stato attuale
|
||
|
||
In produzione su `hub.iamcavalli.net` (Coolify/Hetzner, deploy automatico su push a
|
||
`main` via Gitea). Build verde, `npm audit` pulito.
|
||
|
||
Milestone **v2.5 "Audit"** in corso — Phase 27 a metà. In produzione c'è **solo lo
|
||
schema** dell'audit: nessuna pagina, né admin né pubblica.
|
||
|
||
| Milestone | Fasi | Stato |
|
||
|---|---|---|
|
||
| v2.5 Audit | 27–30 | 🔨 in corso — Phase 27 ~50% |
|
||
| v2.4 Post-vendita | 13, 26 | ✅ chiusa 2026-08-08, entrambe in produzione |
|
||
| v2.3 Email & Accesso | 23–25 | ✅ shipped 2026-07-29, verificata E2E |
|
||
| v2.2 Sales Loop | 18–22 | ✅ shipped 2026-06-20 |
|
||
| v2.1 Offer Studio + CRM | 11, 12, 14 | ✅ chiusa per reset 2026-06-19 |
|
||
| v1.0 + v2.0 | 1–10 | ✅ shipped giugno 2026 |
|
||
|
||
## In corso
|
||
|
||
### v2.5 — Audit (Phases 27–30)
|
||
|
||
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. I tre livelli sono **configurazioni di un unico documento**:
|
||
i blocchi non pertinenti non esistono nel DOM.
|
||
|
||
Fatto finora (Phase 27, ~50%):
|
||
|
||
- **[prod 2026-08-18] Schema.** Migration `0017_audits.sql`, 7 tabelle additive, più
|
||
`checklist_items` seminata con 264 voci. Nessuna UI le legge ancora.
|
||
- **[non pushato] Le fonti del motore.** `src/lib/audit/sources/` — PageSpeed, CrUX,
|
||
Wayback, RDAP, robots/sitemap/JSON-LD, header. Provate sul campo su giojello.com:
|
||
giro completo in 73 s, tutte e cinque hanno risposto.
|
||
|
||
Manca: agent + sintetizzatore + pipeline, storage immagini, editor admin, pagina
|
||
pubblica. Dettaglio in [`.planning/ROADMAP.md`](.planning/ROADMAP.md) e
|
||
[`.planning/REQUIREMENTS.md`](.planning/REQUIREMENTS.md).
|
||
|
||
⚠️ **I due piani della milestone stanno in `~/.claude/plans/`, fuori dal repo**
|
||
(`…woolly-puddle.md` per il documento, `…radiant-valley.md` per il motore). Senza quei
|
||
file la milestone non è ricostruibile.
|
||
|
||
## Fatto
|
||
|
||
### v2.4 — Post-vendita
|
||
|
||
- **[Phase 13, prod 2026-08-01] Ciclo di vita dei servizi ricorrenti.**
|
||
`project_offers.status` (attivo/sospeso/cessato) + `end_date` (migr. 0016). Prima
|
||
un retainer non poteva finire e il forecast lo sommava a ogni mese in eterno.
|
||
Comandi Sospendi/Riattiva/Cessa nella tab Offerte; il cliente vede stato, "attivo
|
||
dal" e canone mensile. Dettaglio: [`.planning/phases/13-…/13-SUMMARY.md`](.planning/phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md)
|
||
- **[Phase 26, prod 2026-08-08] Anteprima admin del portale + toggle password.**
|
||
`?preview=1` più una sessione Auth.js valida apre il portale di un cliente in
|
||
**sola lettura**, senza passare dal gate OTP. Deviazione consapevole dal vincolo
|
||
LOCKED #4, annotata in `CLAUDE.md`. Dettaglio: [`.planning/phases/26-…/26-SUMMARY.md`](.planning/phases/26-anteprima-admin-e-login/26-SUMMARY.md)
|
||
|
||
### v2.3 — Email & Accesso
|
||
|
||
- **Gate OTP sul portale cliente**: whitelist email per cliente (`client_emails`),
|
||
codice a 6 cifre via Resend, sessione firmata 90 giorni, revoca in blocco
|
||
dall'admin (`clients.sessions_valid_from`). Migr. 0015. Verificato E2E in
|
||
produzione. Archivio: [`v2.3-ROADMAP.md`](.planning/milestones/v2.3-ROADMAP.md)
|
||
|
||
### Prima di v2.3
|
||
|
||
- **[2026-07] Audit di sicurezza chiuso**: 4 vulnerabilità risolte e deployate, slug
|
||
clienti ruotati a 12 char CSPRNG, `INTERNAL_SECRET` e `ADMIN_PASSWORD` configurati
|
||
su Coolify. Report in [`.planning/security/`](.planning/security/).
|
||
- **Design system "Quiet Luxury"**: dashboard, liste (Clienti/Offerte/Catalogo/
|
||
Preventivi/Progetti), Conversazioni, Impostazioni, Pipeline+Kanban, dettaglio Lead
|
||
e portale cliente base sono a token semantici e dual-theme.
|
||
- **Tassonomie centralizzate** in Impostazioni (modello Notion, pool persistenti
|
||
`src/lib/taxonomy.ts`).
|
||
- **Lead → Cliente**: `clients.email/phone` + `leads.archived` (migr. 0011).
|
||
`convertLeadToClient` riusa `createClientCore`, porta i transcript, archivia il
|
||
lead mantenendo "won".
|
||
- **Offerta → Fasi/Task**: `importOfferIntoProject` crea fasi raggruppando i servizi
|
||
del tier per `services.fase`.
|
||
- **Offerte (modello + UI)**: `offer_macros.offer_type` ('una_tantum'|'retainer') +
|
||
toggle "Modalità" nell'editor (migr. 0012). Tab Offerte a 2 step.
|
||
|
||
## Da fare
|
||
|
||
- [ ] **Whitelist portale**: dei 4 clienti solo uno ha email autorizzate. Chi ha la
|
||
whitelist vuota **non entra nel proprio portale** — si popola da
|
||
`/admin/clients/<id>` → "Accessi al portale", poi va reinviato il link.
|
||
- [ ] **Fasi/Task dall'offerta** funzionano solo se i servizi hanno il campo **Fase**
|
||
valorizzato nel Catalogo (altrimenti finiscono in "Generale").
|
||
- [ ] **Debito design (DEBT-01)**: **~40 file, ~450 occorrenze** di palette Tailwind
|
||
raw e hex literal invece 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` (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), i colori di stato di `StatusBadge` (sanzionati dal design system,
|
||
hanno già le varianti `dark:`).
|
||
- [ ] Micro legacy "Mantenimento" senza tier: valutare se rimuoverlo/normalizzarlo.
|
||
- [ ] **Backlog**: canoni mensili tracciabili (RET-06 — serve una tabella nuova),
|
||
PROP-03 (Stripe sul deck), PROP-04 (auto-provisioning al "Vinto"), SEND-01/02
|
||
(invio preventivo via email — il mailer è già pronto). Elenco completo in
|
||
[`.planning/REQUIREMENTS.md`](.planning/REQUIREMENTS.md).
|
||
|
||
## Lezioni operative
|
||
|
||
Cose imparate a caro prezzo. Non sono documentazione di feature: sono trappole in
|
||
cui si ricasca.
|
||
|
||
- **Il gate OTP non va nel layout.** Prima implementazione: gate in
|
||
`client/[token]/layout.tsx` che rendeva `<OtpGate/>` al posto di `{children}`.
|
||
**Non protegge nulla.** Nell'App Router il segmento `page` è 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 sta in cima alla `page`, prima di ogni query, via `getClientGate()`.
|
||
**Ogni nuova route sotto `/client/[token]/` deve fare lo stesso.**
|
||
- **Ricreare il dominio su Resend rigenera la chiave DKIM.** Se 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`.
|
||
- **`.env.local` non è allineato a produzione.** `ADMIN_PASSWORD` e
|
||
`NEXTAUTH_SECRET` sono stati ruotati il 2026-07-28 **solo su Coolify**. Per
|
||
costruire firme o hash validi in prod vanno letti da Coolify, non da `.env.local`.
|
||
- **L'API Coolify rifiuta `is_build_time`** con 422 sul POST a
|
||
`/api/v1/applications/<uuid>/envs`: mandare solo `key`, `value`, `is_preview`.
|
||
- **Playwright non funziona contro `npm run dev`**: la CSP blocca `eval` e i client
|
||
component non si idratano. Serve il build di produzione.
|
||
- **Le API di Google cambiano forma sotto i piedi, e in silenzio.** Scrivendo
|
||
`src/lib/audit/sources/` due estrazioni dedotte dalla documentazione hanno restituito
|
||
valori vuoti *senza errore*: `largest-contentful-paint-element` non esiste più (ora è
|
||
`lcp-breakdown-insight`, con `subpart`/`duration` e senza percentuali) e
|
||
`configSettings.screenEmulation` non esiste affatto nelle risposte pubbliche. Trovate
|
||
solo perché le fonti sono state fatte girare su un sito vero prima di costruirci sopra.
|
||
**Ogni estrazione da un'API di terzi va vista funzionare, non dedotta dai docs.**
|
||
- **Laboratorio e campo misurano cose diverse, e la differenza *è* il risultato.** Su
|
||
giojello.com Lighthouse dà `server-response-time` **7 ms** e CrUX dà TTFB p75 **3.553
|
||
ms con l'1% di visite 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 — da qui
|
||
`risposta_server_ms` invece di `ttfb_ms`.
|
||
- **I punteggi PageSpeed ballano fra un giro e l'altro**: performance mobile 52 e poi 64
|
||
sullo stesso sito a 30 minuti di distanza. Nei documenti consegnati un punteggio va
|
||
sempre con la sua data, mai presentato come una costante del sito.
|
||
|
||
## Note tecniche
|
||
|
||
- **Il DB di `.env.local` È la produzione** (178.104.27.55). Non esiste un database
|
||
di sviluppo separato: qualunque cosa si esegua in locale scrive su dati reali.
|
||
Verificare i conteggi delle tabelle protette prima e dopo ogni prova.
|
||
- **Migrazioni**: SQL scritto a mano in `src/db/migrations/` (`drizzle-kit generate`
|
||
è rotto — vanno tenuti in sync `schema.ts` e l'SQL). Si applicano **da locale via
|
||
SSH + docker exec**, senza tunnel — procedura completa in `CLAUDE.md`. Il tunnel
|
||
`ssh -f -N -L 54321:localhost:54321` serve solo per puntare il tooling locale
|
||
(es. `npx tsx`) al DB di prod.
|
||
- **Ordine di deploy con schema**: applicare la migrazione a prod **prima** del push
|
||
(il deploy fa girare subito il codice nuovo).
|
||
- **Coolify API**: credenziali in `~/.coolify.env` (formato `export VAR=…`, va
|
||
sorgentato). App uuid `xsksow44g4kcoo8wocsgkscc`.
|
||
- **`overrides` in package.json** forzano `postcss >= 8.5.18` e `sharp >= 0.35.0`:
|
||
le versioni che Next si porta dietro hanno CVE high e non c'è fix upstream. Se un
|
||
aggiornamento di Next rompe qualcosa, è il primo posto dove guardare.
|
||
- `offer_micros` non ha `created_at` (no "tier più vecchio" affidabile).
|
||
- **Debito tecnico non bloccante**: tabelle legacy `service_catalog` /
|
||
`offer_services` / `offer_micro_services` come deadweight; `createService` /
|
||
`serviceSchema` dead code in `src/app/admin/catalog/actions.ts`.
|
||
|
||
## File chiave
|
||
|
||
| File | Scopo |
|
||
|---|---|
|
||
| src/proxy.ts | Middleware (Next 16 lo chiama `proxy`, non `middleware`) |
|
||
| src/lib/client-gate.ts | Gate OTP — va chiamato in cima a ogni page sotto `/client/[token]/` |
|
||
| src/lib/otp.ts, client-session.ts | Codici OTP e cookie di sessione 90gg |
|
||
| src/lib/mailer.ts | Unico punto di invio email (Resend) |
|
||
| src/lib/forecast-queries.ts | Forecast 12 mesi — rispetta stato e `end_date` dei retainer |
|
||
| src/lib/taxonomy.ts | Pool tassonomie (Impostazioni) |
|
||
| src/app/admin/projects/project-actions.ts | `importOfferIntoProject`, `setProjectOfferLifecycle`, piani pagamento |
|
||
| src/components/admin/tabs/OffersTab.tsx | Tab Offerte + comandi ciclo di vita |
|
||
| src/lib/admin-queries.ts / client-view.ts | I due layer separati: admin vs proiezioni client-safe |
|
||
| src/lib/audit/sources/ | Le 5 fonti del motore audit (nessun LLM) — `fetch` espone anche gli helper di rete condivisi |
|
||
| src/db/migrations/ | 0011 (email/phone), 0012 (offer_type), 0015 (OTP), 0016 (ciclo di vita), 0017 (audit) |
|
||
|
||
## Dove sta il resto
|
||
|
||
| Cosa | Dove |
|
||
|---|---|
|
||
| Regole per Claude, procedure deploy/DB, vincoli LOCKED | `CLAUDE.md` |
|
||
| Digest di stato per i comandi `/gsd-*` | `.planning/STATE.md` |
|
||
| Requisiti e backlog della milestone corrente | `.planning/REQUIREMENTS.md` |
|
||
| Roadmap e storico milestone | `.planning/ROADMAP.md`, `.planning/MILESTONES.md` |
|
||
| Archivi delle milestone chiuse | `.planning/milestones/` |
|
||
| Fasi della milestone in corso | `.planning/phases/` |
|
||
| Report dell'audit di sicurezza (chiuso) | `.planning/security/` |
|
||
| Design system e mock per pagina | `design-reference/` |
|