NexStudio/README.md

# NexStudio Website Runbook

Sito istituzionale NexStudio basato su Astro, con deploy su Cloudflare e form contatti protetto da Turnstile.

## Obiettivo del repository

- Presentazione aziendale e servizi (homepage e pagine legali).
- Entry point unico per richieste commerciali e supporto.
- Base pronta per contenuti multilingua IT/EN/TH.
- Pipeline di deploy stabile su Cloudflare.

## Stack tecnico

- Astro + Tailwind CSS
- Adapter Cloudflare (`@astrojs/cloudflare`)
- Sitemap (`@astrojs/sitemap`)
- Form backend su endpoint `/api/contact`
- Turnstile + Cloudflare Email Service per anti-spam e invio email

## Struttura essenziale

- `src/pages/`: pagine pubbliche e route API (`src/pages/api/contact.ts`)
- `src/components/`: componenti UI condivisi
- `src/data/`: contenuti testuali e configurazioni pagine
- `public/`: asset statici (loghi, immagini, robots)
- `.env.example`: variabili locali di riferimento

## Prerequisiti

- Node.js 20+
- npm 10+
- Account Cloudflare (Workers + Turnstile + Email Service con dominio onboardato, es. `nexstudio.ai`)

## Avvio locale

1. Installazione dipendenze:
   - `npm install`
2. Copia variabili di ambiente:
   - copia `.env.example` in `.env`
3. Avvio sviluppo:
   - `npm run dev`
4. Se Vite resta in cache incoerente:
   - `npm run dev:fresh`

## Comandi utili

- `npm run dev`: sviluppo locale
- `npm run dev:fresh`: reset cache `.vite` e `.astro` + avvio dev server
- `npm run build`: build produzione
- `npm run preview`: preview locale della build
- `npm run deploy:cf`: build + deploy con wrangler su output Astro

## Configurazione contatti

Variabili pubbliche (frontend):

- `PUBLIC_CONTACT_FORM_ACTION_URL` (default consigliato: `/api/contact`)
- `PUBLIC_CONTACT_FORM_SUCCESS_REDIRECT` (URL assoluto della pagina post-submit)
- `PUBLIC_CONTACT_FORM_MAILTO` (fallback se action URL non disponibile)
- `PUBLIC_CONTACT_TURNSTILE_SITE_KEY`

Variabili server (Cloudflare/local):

- `CONTACT_FORM_MODE` (`dev` oppure `live`)
- `CONTACT_FORM_FROM_EMAIL` (consigliato: `no-reply@nexstudio.ai`, dominio verificato su Email Service)
- `CONTACT_FORM_TO_EMAIL` (casella reale dove ricevi, es. Gmail; evita indirizzi solo Email Routing se DMARC è `p=reject`)
- `CONTACT_FORM_TO_EMAIL_INFO` (opzionale, override esplicito per area "info")
- `CONTACT_FORM_TO_EMAIL_PRIVACY`
- `CONTACT_FORM_TO_EMAIL_CAREERS`
- `CONTACT_TURNSTILE_SECRET_KEY`

Comportamento:

- `dev`: accetta submit e scrive payload nei log (senza invio reale)
- `live`: valida Turnstile e invia email via binding `EMAIL` (Cloudflare Email Service)

Routing pubblico consigliato (portale vetrina):

- `info`: informazioni generali/commerciali
- `privacy`: richieste privacy e diritti interessato
- `careers`: candidature e collaborazioni

Indirizzi consigliati portale:

- `info@nexstudio.ai`
- `privacy@nexstudio.ai`
- `careers@nexstudio.ai`
- `no-reply@nexstudio.ai` (solo invio comunicazioni/newsletter, non destinazione inbound)

## Configurazione newsletter

Sistema custom su Cloudflare D1 + Cloudflare Email Service (double opt-in).

Prerequisito: dominio (es. `nexstudio.ai`) onboardato in **Email Service** con SPF/DKIM, e binding `send_email` → `EMAIL` nel Worker.

Variabili server:

- `NEWSLETTER_MODE` (`dev` oppure `live`; se assente usa `CONTACT_FORM_MODE`)
- `NEWSLETTER_FROM_EMAIL` (fallback: `CONTACT_FORM_FROM_EMAIL`, consigliato `no-reply@nexstudio.ai`)
- `NEWSLETTER_NOTIFY_TO_EMAIL` (notifiche admin; fallback: `CONTACT_FORM_TO_EMAIL`)
- `NEWSLETTER_ADMIN_TOKEN` (Bearer token per endpoint admin)
- `NEWSLETTER_TURNSTILE_SECRET_KEY` (opzionale; fallback: `CONTACT_TURNSTILE_SECRET_KEY`)
- `PUBLIC_SITE_URL` (origine usata nei link di conferma/disiscrizione)

Endpoint pubblici:

- `POST /api/newsletter/subscribe` — iscrizione (form footer)
- `GET /api/newsletter/confirm?token=…` — conferma double opt-in
- `GET|POST /api/newsletter/unsubscribe?token=…` — disiscrizione

Endpoint admin (header `Authorization: Bearer <NEWSLETTER_ADMIN_TOKEN>`):

- `GET /api/newsletter/admin/subscribers?status=active|pending|unsubscribed`
- `POST /api/newsletter/admin/send` — body JSON `{ "subject", "text", "html?", "dryRun?" }`

Nota: Email Service è pensato per email **transazionali** (conferme, contatti, notifiche). Le campagne marketing di massa non sono ancora il target ufficiale del servizio.

Database:

- D1 `nexstudio-newsletter` (binding `NEWSLETTER_DB`)
- Migrazioni in `migrations/`
- `npm run db:migrate:local` / `npm run db:migrate:remote`

Comportamento:

- `dev`: accetta submit e logga (senza D1/Email obbligatori)
- `live`: scrive su D1, invia email di conferma via Cloudflare Email Service, richiede binding D1 + EMAIL

## Deploy Cloudflare

Impostazioni consigliate:

- Build command: `npm run build`
- Deploy command: `npm run deploy:cf`

Questa configurazione evita errori tipo:
`The entry-point file at "@astrojs/cloudflare/entrypoints/server" was not found.`

## Dominio e sicurezza

- Dominio ufficiale: `https://nexstudio.ai`
- Hostname Turnstile da mantenere allineati:
  - `nexstudio.ai`
  - `www.nexstudio.ai` (se usato)
  - `localhost` (test locale)
- Accesso pre-go-live gestito con Cloudflare Zero Trust Access

## Stato operativo attuale

- Issue #1 (contact form live): implementata
- Issue #2 (anti-spam Turnstile): implementata
- Issue #3 (SEO base): implementata (sitemap, robots, canonical/OG/Twitter)
- Issue #4: in avanzamento (contenuti non placeholder)
- Issue #5: da completare (localizzazione reale IT/EN/TH)

## Note operative

- Per modifiche non minori usare branch dedicato (`feat/*`, `fix/*`) e merge su `main` dopo verifica.
- Evitare commit su `main` per attivita complesse.
- Rigenerare eventuali API key esposte e aggiornare subito i secret su Cloudflare.