simone/clienthub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: apre v2.5 "Audit" e rimette in pari roadmap e requisiti

Browse Source 
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>
This commit is contained in:
Simone Cavalli
2026-08-18 17:48:46 +02:00
parent 24213e7251
commit 8000d562dc
5 changed files with 278 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/STATE.md
+62 -61
View File
@@ -1,98 +1,99 @@
---
gsd_state_version: 1.0
milestone: v2.4
milestone_name: Post-vendita
milestone: v2.5
milestone_name: Audit
status: executing
stopped_at: "Phase 13 e 26 in produzione. Nessun lavoro in sospeso: il prossimo va scelto dal backlog in REQUIREMENTS.md."
last_updated: "2026-08-08T20:30:00.000Z"
last_activity: 2026-08-08 -- riordino della documentazione di progetto
stopped_at: "Phase 27 a metà: schema in prod, fonti scritte e provate sul campo. Prossimo: src/lib/audit/schema.ts + agents/."
last_updated: "2026-08-18T17:45:00.000Z"
last_activity: 2026-08-18 -- fonti del motore scritte e verificate su sito reale
progress:
total_phases: 2
completed_phases: 2
total_plans: 2
completed_plans: 2
percent: 100
total_phases: 4
completed_phases: 0
total_plans: 4
completed_plans: 0
percent: 25
---
# Project State
> Digest per i comandi `/gsd-*`. La narrativa completa — cosa è stato fatto, cosa
> manca, le lezioni operative — sta in **`STATUS.md`** alla radice del repo.
> Questo file resta sotto le 100 righe di proposito.
> **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-08-08)
**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.4 "Post-vendita"** — tutto ciò che era pianificato è in produzione. Nessuna fase aperta.
See: .planning/PROJECT.md · **Core value:** il cliente apre il link e vede a che punto è
il suo progetto, senza scrivere email. · **Current focus:** milestone **v2.5 "Audit"** —
il servizio di analisi sito diventa un documento privato su `/audit/[slug]`.
## Current Position
Phase: 2 of 2 (Phase 13 Ciclo di vita servizi ricorrenti · Phase 26 Anteprima admin)
Plan: 2 of 2 in current milestone
Status: Phase complete — nessuna fase aperta, prossimo lavoro da scegliere dal backlog
Last activity: 2026-08-08 — riordino della documentazione (`.planning/` e doc di root)
Phase: 27 of 30 — Motore di analisi
Plan: schema e fonti fatti; agent, sintetizzatore e pipeline da scrivere
Status: nessun bloccante — prossimo passo `src/lib/audit/schema.ts` + `agents/`
Last activity: 2026-08-18 — `src/lib/audit/sources/` scritto e provato su giojello.com
Progress: [██████████] 100%
Progress: [███░░░░░░░] 25%
Entrambe le fasi sono **in produzione e verificate**:
## Dove sta cosa
- Phase 13 → `5177a37`, migr. 0016, prod 2026-08-01 · [13-SUMMARY.md](phases/13-ciclo-vita-servizi-ricorrenti/13-SUMMARY.md)
- Phase 26 → `09a5b1f` + `187550f`, prod 2026-08-08 · [26-SUMMARY.md](phases/26-anteprima-admin-e-login/26-SUMMARY.md)
| Cosa | Dove | Stato |
|---|---|---|
| Schema audit (7 tabelle) | `src/db/migrations/0017_audits.sql` + `src/db/schema.ts` | **in produzione** |
| Rubrica del motore, 264 voci | tabella `checklist_items`, sorgente `scripts/data/checklist.json` | **in produzione** |
| Fonti del motore (5 moduli) | `src/lib/audit/sources/` | scritto e provato, **non in prod** |
| Agent, sintetizzatore, pipeline | `src/lib/audit/{schema,agents,pipeline}.ts` | **da scrivere** |
| Editor admin e pagina pubblica | `src/app/admin/audit/`, `src/app/audit/[slug]/` | **da scrivere** |
| L'unico audit prodotto finora | `spike-audit-giojello.com.json` (root, **gitignorato**) | spike del 2026-08-16, **zero rilevazioni** |
| I due piani della milestone | `~/.claude/plans/` — `…woolly-puddle.md` (documento) + `…radiant-valley.md` (motore) | **fuori dal repo** |
## Come funziona il motore
Si incolla un URL. Nessun browser headless da nessuna parte.
1. **Raccolta in parallelo** (`sources/`, nessun LLM): PageSpeed, CrUX, Wayback, RDAP, robots/sitemap/JSON-LD, header. Ogni fonte fallisce in modo non fatale e dice *perché*.
2. **Quattro sub-agent in parallelo** (`agents/`): checklist, visivo, storico, tecnico. Producono osservazioni, non finding.
3. **Sintetizzatore** che le **incrocia**: quattro osservazioni deboli su temi diversi diventano un finding solo con quattro evidenze indipendenti. Massimo 10, per impatto.
4. **Editor admin** per rifinire, poi consegna su `/audit/[slug]`.
Vincolo che regge tutto: **un numero entra solo se misurato**, e dev'essere rintracciabile in `audit_runs.raw`.
## Performance Metrics
**Velocity:** 21 plans completati in totale — 7 (v2.1) + 9 (v2.2) + 3 (v2.3) + 2 (v2.4).
**Recent Trend:** — · v2.3 e v2.4 sono state eseguite fuori dal ciclo GSD, quindi non cronometrate.
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 13 | 1 | — | — |
| 26 | 1 | — | — |
*Updated after each plan completion*
**Velocity:** 21 plans completati (v2.1–v2.4). Phase 27: spike ~1h, schema ~1h, fonti ~2h.
## Accumulated Context
### Decisions
Log completo in PROJECT.md (Key Decisions). Rilevanti per il lavoro corrente:
Log completo in `PROJECT.md`. Vive per il lavoro corrente:
- **[Phase 26, 2026-08-08] Deviazione consapevole dal vincolo LOCKED #4** — una route `/client/*` ora legge anche la sessione Auth.js per l'anteprima admin. Non indebolisce il gate per i clienti; annotata in `CLAUDE.md`.
- **[Phase 26] L'anteprima è in sola lettura a livello UI, non API** — le route `/api/client/*` autenticano sul token nel body. L'obiettivo è impedire l'incidente, non difendersi da sé stessi.
- **[Phase 13] Storico di vendita ≠ forecast** — `getOffersSoldBreakdown` non filtra per stato: escludere le offerte cessate riscriverebbe il fatturato passato.
- **[v2.3, 2026-07-28] Sessione OTP a 90 giorni invece di 30** — rientro più fluido, compensato dalla revoca in blocco lato admin (OTP-08).
- **[2026-08-18] Il documento usa il design system dell'area admin** — token semantici, Plus Jakarta Sans, Geist Mono per metriche e date, `StatusBadge` per gli impatti. Sostituisce la deroga tipografica del piano; i font sono già self-hostati da `next/font/google`, quindi la CSP è soddisfatta senza lavoro.
- **[2026-08-18] Nessun renderer headless** — PageSpeed dà 153 audit sul DOM renderizzato, cioè le osservazioni visive che prima richiedevano screenshot a mano.
- **[2026-08-18] Laboratorio ≠ campo, e la differenza è il risultato** — Lighthouse dà 7 ms di risposta server, CrUX dà TTFB p75 3.553 ms. Da qui il nome `risposta_server_ms`: con lo stesso nome il sintetizzatore li tratterebbe come un numero solo.
- **[2026-08-17] Il VPS non regge Chromium** — RAM, non disco. È la ragione per cui l'opzione headless non torna.
- **[2026-08-16] La checklist alimenta il MOTORE, non il documento** — se diventa il rendering della checklist, torna a sembrare un audit automatico gratuito.
- **[2026-08-16] Immagini** — le due del redesign le carica l'utente, le due dello stato di fatto le scrive la pipeline. Emenda LOCKED #5 solo per gli asset di audit.
### Pending Todos
[From .planning/todos/pending/ — ideas captured during sessions]
None yet.
### Pending Todos — nessuno (`.planning/todos/` non esiste)
### Blockers/Concerns
- **Whitelist portale vuota per 3 clienti su 4** (non bloccante: l'utente li re-invita) — da popolare da `/admin/clients/<id>` → "Accessi al portale".
- **`.env.local` punta al DB di PRODUZIONE** e non è allineato a Coolify per `ADMIN_PASSWORD` / `NEXTAUTH_SECRET` (ruotati il 2026-07-28). Nessun DB di sviluppo separato: ogni prova locale scrive su dati reali.
- **Ogni fase con schema** DEVE avere la migration applicata a prod PRIMA del push del codice dipendente. `drizzle-kit generate` è rotto → SQL a mano. Procedura in `CLAUDE.md`.
- **Debito design (DEBT-01)** — ~40 file, ~450 occorrenze di palette raw/hex. Misurato il 2026-08-08. Dettaglio in `STATUS.md`.
- **Il copy fisso del template v1 non ha una fonte nel repo** — il prototipo Giojello non c'è. Lo *stile* ora viene dal design system, ma testi e gerarchia dei blocchi vanno recuperati prima di Phase 30.
- **Il caso "zero dati CrUX" non è ancora stato visto** su un sito vero (test 5 del piano).
- **Il 52% della checklist non è verificabile da HTML statico** — quanto ne recuperino gli audit Lighthouse non è ancora misurato (test 3 del piano).
- **Whitelist portale vuota per 3 clienti su 4** — si popola da `/admin/clients/<id>`.
- **`.env.local` punta al DB di PRODUZIONE**, non allineato a Coolify per `ADMIN_PASSWORD` / `NEXTAUTH_SECRET`.
- **Ogni fase con schema**: migration applicata a prod **prima** del push del codice.
- **Debito design (DEBT-01)** — ~40 file, ~450 occorrenze. Dettaglio in `STATUS.md`.
## Deferred Items
| Category | Item | Status | Deferred At |
|----------|------|--------|-------------|
| v2.4 | RET-06 — Canoni mensili tracciabili (serve tabella nuova) | Backlog | 2026-08-01 |
| v2.4 | SEND-01/02 — Invio link preventivo via email (mailer già pronto) | Backlog | 2026-07-28 |
| v2.4+ | PROP-03 — Stripe Payment Link sul deck | Backlog | v2.3 kickoff |
| v2.4+ | PROP-04 — Auto-provisioning cliente/progetto/fasi al "Vinto" | Backlog | v2.3 kickoff |
| Design | DEBT-01 — Migrazione a token semantici | Backlog | 2026-07-28 |
| Tech debt | DEBT-02 — Tabelle legacy catalogo + dead code | Backlog | v2.1 |
| v2+ | OFFER-14 — Sezioni analitiche stile Notion | Backlog | v2.1 kickoff |
| v2+ | ARCH-01 — Split modulo in deploy separato | Backlog (solo se cresce) | v2.1 kickoff |
Vedi `REQUIREMENTS.md` § Backlog e § Rinviati esplicitamente da v2.5.
## Session Continuity
Last session: 2026-08-08 20:30
Stopped at: Riordino della documentazione — milestone chiuse archiviate, v2.4 documentata, STATUS.md unico documento narrativo.
Next: Popolare la whitelist dei 3 clienti reali, oppure attaccare DEBT-01 (debito design).
Last session: 2026-08-18
Stopped at: `src/lib/audit/sources/` (5 moduli) scritto e **provato sul campo su giojello.com** — giro completo 73 s, tutte le fonti hanno risposto. Build e lint puliti.
Next: (1) `src/lib/audit/schema.ts` + `agents/` con validazione Zod dura; (2) `pipeline.ts` con heartbeat su `audit_runs`; (3) volume Coolify prima del deploy; (4) editor e pagina.
Resume file: None