- 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
124 lines
9.6 KiB
Markdown
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.
|