Files
Studio_Grasso/README.md
T
Claude 0d0bebf708 fix: correzioni della revisione finale (testi, visuale, brief, codice)
- testi: «lo Studio» uniforme, «Centro autorizzato CAF», ripetizioni tolte
  nei servizi e in «Lo studio», valori senza superlativi, meta corrette,
  testo della mappa di §10.2, numeri e indirizzi con spazi non separabili
- visuale: breadcrumb, anello della banda CTA, card dei professionisti,
  pager e sidebar dei servizi su mobile, pagine legali a colonna singola,
  pulsante e-mail su una riga, card sedi allineate
- dati: fatti della sede di Asti da studio.ts/testi.ts, sede.telefono
- 404 e conferma senza canonical; avviso mappa senza JavaScript
- controlli: CSP per direttive (endpoint), anno da SOURCE_DATE_EPOCH,
  URL del sito controllati sulla build locale, import file:// e tar da
  stdin per Windows, .gitattributes, porta libera corretta
- modulo: pattern del telefono valido, avviso visibile, Esc sul
  sottomenu aperto al passaggio del mouse; contact.php con -f, senza
  mbstring obbligatorio, fuso Europe/Rome
- release: note --shell-safe, ripiego REST automatico, RELEASE_TOKEN;
  deploy di esempio senza esclusione di contact.php; nginx /privacy/
- DECISIONS D-040–D-044, TODO C4 e riferimenti di riga aggiornati

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016zJ9ZWGKvoKoxYwbmnRKdJ
2026-10-16 00:13:01 +00:00

124 lines
9.6 KiB
Markdown

# Sito web dello Studio Grasso
Sito statico dello **Studio Grasso — Studio Tributario e Societario** (Montegrosso d'Asti e Asti), realizzato con [Astro](https://astro.build/). Nessun tracciamento, nessun cookie, nessuna risorsa di terze parti caricata senza un'azione esplicita dell'utente; pacchetto di rilascio universale (solo file statici, con `.htaccess`) pronto per qualsiasi hosting.
- Requisiti di progetto: [`docs/BRIEF.md`](docs/BRIEF.md) · Mockup: [`docs/mockups/`](docs/mockups/)
- Decisioni tecniche: [`DECISIONS.md`](DECISIONS.md) · Dati da fornire: [`TODO-STUDIO.md`](TODO-STUDIO.md) · Novità: [`CHANGELOG.md`](CHANGELOG.md)
- Pubblicazione sull'hosting: [`docs/DEPLOY.md`](docs/DEPLOY.md) · Aggiornare i contenuti: [`docs/CONTENUTI.md`](docs/CONTENUTI.md) · Conformità: [`docs/CONFORMITA.md`](docs/CONFORMITA.md)
## Requisiti
- **Node.js** LTS: versione in [`.nvmrc`](.nvmrc) (24), minimo 22.22.3. Con [nvm](https://github.com/nvm-sh/nvm): `nvm install && nvm use`.
- **npm** (incluso in Node.js).
- Per i test: Chromium di Playwright. Se manca: `npx playwright install --with-deps chromium` (una volta sola).
## Avvio rapido
```bash
npm ci # installa le dipendenze esatte di package-lock.json
npm run dev # sito in sviluppo su http://localhost:4321 (si aggiorna a ogni modifica)
npm run build # genera il sito statico in dist/
npm run preview # serve dist/ su http://127.0.0.1:4321
npm run verify # tutti i controlli di qualità (gli stessi della CI)
npm run package # crea il pacchetto di rilascio in release/
```
## Comandi
| Comando | Cosa fa |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| `npm run dev` | server di sviluppo |
| `npm run build` | build statica in `dist/` |
| `npm run preview` | anteprima di `dist/` |
| `npm run lint` | ESLint (JavaScript, TypeScript, Astro) |
| `npm run format` / `format:check` | Prettier: corregge / verifica la formattazione |
| `npm run check` | `astro check`: tipi TypeScript e componenti |
| `npm run test:html` | validità HTML di tutte le pagine (html-validate) |
| `npm run test:links` | link interni, asset e ancore (linkinator); `-- --external` anche i siti esterni |
| `npm run test:e2e` | test end-to-end (Playwright): pagine, navigazione, menu, privacy, mappa, modulo |
| `npm run test:a11y` | accessibilità: axe su tutte le pagine a 1440 e 390 px, tastiera, zoom, reflow |
| `npm run test:compliance` | conformità (P.IVA, pagine legali, nessun tracciamento, JSON-LD, titoli professionali…) |
| `npm run test:lighthouse` | Lighthouse CI: Performance ≥ 0.95, Accessibility 1, Best Practices ≥ 0.95, SEO 1 |
| `npm test` | html + link + e2e + a11y + conformità |
| `npm run verify` | lint + formattazione + tipi + build + `npm test` + Lighthouse |
| `npm run package` | build + pacchetto in `release/` + verifica del pacchetto (`test:package`) |
| `npm run icons` | rigenera marchio, favicon, apple-touch-icon e immagine di condivisione |
`npm run verify` deve terminare senza errori prima di ogni rilascio: è il comando eseguito dalla CI.
## Struttura
```
src/data/ dati e testi: studio.ts (anagrafica, sedi, orari, professionisti, abilitazioni,
partner, modulo), pagine.ts (testi delle pagine), testi.ts, navigazione.ts
src/content/ servizi/*.md, legali/*.md (privacy, cookie, note legali, accessibilità),
link-utili.json — schemi in src/content.config.ts
src/components/ componenti Astro (intestazione, footer, card, mappa, modulo…)
src/layouts/ BaseLayout.astro: <head>, SEO, dati strutturati, struttura della pagina
src/pages/ una pagina per file; servizi/[slug].astro genera le 6 pagine dei servizi
src/styles/ tokens.css (colori, tipografia, spaziature), global.css, fonts.css, print.css
src/scripts/ piccoli script: menu, mappa su consenso, modulo, ancore del vecchio sito
public/ .htaccess, favicon e immagini statiche (copiati così come sono)
scripts/ script di test, pacchetto, icone, note di rilascio, upload della release
tests/ e2e/ e a11y/ (Playwright), helpers/
deploy/ nginx.conf.example, optional-php-form/contact.php, esempio di deploy automatico
.forgejo/workflows ci.yml (verifica) e release.yml (pubblicazione della release)
docs/ brief, mockup, guide di deploy e contenuti, conformità
```
## Configurazione
| Impostazione | Dove | Valore predefinito |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------- |
| Dominio del sito (canonical, sitemap, robots, dati strutturati) | variabile d'ambiente `SITE_URL` | `https://www.grassoezio.it` |
| Modulo di contatto: `off`, `php`, `endpoint` | `contactForm.mode` in `src/data/studio.ts`, oppure variabile `CONTACT_FORM_MODE` | `off` (card «Scrivici una e-mail») |
| Data riproducibile (anno nel footer, date negli archivi) | variabile `SOURCE_DATE_EPOCH` | ora corrente / data dell'ultimo commit |
Esempio: `SITE_URL=https://studiograssoezio.it npm run build`.
Per verificare il modulo attivo (validazione, anti-spam, pagina di conferma):
```bash
CONTACT_FORM_MODE=php npm run build && npx playwright test tests/e2e/form.spec.ts && npm run build
```
## Pubblicare il repository su Forgejo
Questo repository è un clone di `https://forgejo.encke-hake.ts.net/BalboSoft/Studio_Grasso.git`: il remote `origin` è già configurato. Per un repository nuovo: `git remote add origin <url-del-repository>`.
```bash
git push -u origin main # pubblica il codice: parte la CI (.forgejo/workflows/ci.yml)
```
Consigliato: proteggere il branch `main` (Impostazioni del repository → Branch → Protezione: niente push forzati, merge solo con CI verde) e lavorare con branch e pull request. I messaggi di commit seguono [Conventional Commits](https://www.conventionalcommits.org/it/) in italiano (`feat:`, `fix:`, `docs:`, `ci:`, `test:`, `chore:`).
La CI richiede un **runner Forgejo Actions** con label `docker` (modificabile in cima ai file dei workflow). Le azioni sono indicate con URL completo su `code.forgejo.org`, quindi non dipendono dalla configurazione dell'istanza.
## Fare una release
1. Aggiornare `version` in `package.json` (SemVer: `1.0.1` correzioni, `1.1.0` novità, `2.0.0` cambiamenti importanti) e `npm install` per allineare `package-lock.json`.
2. Aggiungere in `CHANGELOG.md` la sezione `## [X.Y.Z] - AAAA-MM-GG`: diventa il testo della release.
3. `npm run verify`, commit (`chore(release): prepara vX.Y.Z`) e push su `main`.
4. Creare e pubblicare il tag:
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```
Il workflow `release.yml` verifica che tag, `package.json` e CHANGELOG coincidano, esegue `npm run verify` e `npm run package` e pubblica nella sezione **Release** del repository: `sito-studio-grasso-vX.Y.Z.zip`, `.tar.gz`, `SHA256SUMS.txt`, `BUILD-INFO.txt`.
**Token:** su alcune istanze il token automatico dei workflow non può creare release. In quel caso creare un _access token_ (Impostazioni utente → Applicazioni → Genera nuovo token, permesso **`write:repository`**) e salvarlo come segreto del repository con nome **`FORGEJO_TOKEN`** (Impostazioni del repository → Actions → Segreti): il workflow lo usa automaticamente. Se l'istanza rifiuta i nomi che iniziano con `FORGEJO_`, chiamarlo **`RELEASE_TOKEN`**. Lo stesso token serve per avviare in automatico il deploy facoltativo (`docs/DEPLOY.md`, sezione 9).
Il workflow pubblica la release con l'action `forgejo-release`; se l'action non riesce, lo step successivo la pubblica con l'API REST (`scripts/release-upload.sh`, solo `curl` e `node`). Lo stesso script serve anche a mano (istruzioni in testa al file e in `docs/DEPLOY.md`).
## Aggiornare le dipendenze
Le versioni sono bloccate (senza `^`) e `package-lock.json` è committato. Per aggiornare: `npm install <pacchetto>@<versione> --save-exact`, poi `npm run verify`. **Playwright:** la versione di `@playwright/test`, `playwright` e `playwright-core` deve coincidere con l'immagine `mcr.microsoft.com/playwright:vX.Y.Z-noble` usata in `.forgejo/workflows/ci.yml` e `release.yml` (oggi 1.56.1).
## Note
- Le icone (favicon, `og-default.png`, logo) si rigenerano con `npm run icons` dopo modifiche al marchio; i file generati vanno committati.
- Telemetria di Astro: disattivata in CI (`ASTRO_TELEMETRY_DISABLED=1`); in locale `npx astro telemetry disable`.
- Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.