simone/clienthub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a9358da96f21686ab2e9807d2f095621c4c0c07a
clienthub/STATUS.md
T
simone 8000d562dc docs: apre v2.5 "Audit" e rimette in pari roadmap e requisiti 
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>
2026-08-18 17:48:46 +02:00

11 KiB
Raw Blame History

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 e .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
  • [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

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

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/.
  • 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.

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/
Reference in New Issue View Git Blame Copy Permalink