146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
# InsanityLab Website
|
|
|
|
Sito vetrina per InsanityLab con blog integrato e form di contatti.
|
|
|
|
## Descrizione
|
|
|
|
Il progetto realizza un sito web per InsanityLab, combinando una vetrina aziendale con un sistema di blog gestito tramite SQLite e un form di contatti funzionante. L'architettura è costruita su **Astro 7** con adapter **Node.js** per deployment su server, garantendo performance ottimali e SEO-friendly pages.
|
|
|
|
## Stack Tecnologico
|
|
|
|
- **Framework**: Astro 7
|
|
- **Runtime**: Node.js (adapter standalone)
|
|
- **Database**: SQLite (better-sqlite3)
|
|
- **Autenticazione**: bcryptjs
|
|
- **Email**: Nodemailer
|
|
- **Markup Editor**: TipTap (rich text)
|
|
- **Font System**: @fontsource (Montserrat, Open Sans)
|
|
- **Sitemap**: endpoint runtime `/sitemap.xml` (route vetrina, programmi e articoli pubblicati)
|
|
- **Testing**: Vitest
|
|
- **Linguaggio**: TypeScript
|
|
|
|
## Installazione
|
|
|
|
### Prerequisiti
|
|
|
|
- Node.js 18+ e npm
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Installa dipendenze
|
|
npm install
|
|
|
|
# Copia il template di configurazione env
|
|
cp .env.example .env
|
|
|
|
# Crea il primo utente amministratore (dopo aver configurato il DB)
|
|
npm run create-user -- admin tuapassword
|
|
```
|
|
|
|
Modifica `.env` con le credenziali SMTP, percorsi database e upload directory secondo il tuo ambiente.
|
|
|
|
## Comandi Disponibili
|
|
|
|
| Comando | Descrizione |
|
|
|---------|-------------|
|
|
| `npm run dev` | Avvia il server di sviluppo (localhost:4321) |
|
|
| `npm run build` | Compila il progetto per production |
|
|
| `npm run preview` | Visualizza l'anteprima della build (locale) |
|
|
| `npm run start` | Avvia il server production (richiede `npm run build` preliminare) |
|
|
| `npm run test` | Esegui i test con Vitest |
|
|
| `npm run create-user` | Crea un nuovo utente: `-- <nome> <password> [admin\|editor]` |
|
|
|
|
## Gestione Contenuti
|
|
|
|
I testi e le immagini del sito vetrina sono contenuti taggati, modificabili senza toccare il codice tramite il pannello `/admin/content`. Ogni blocco di contenuto è identificato da un tag (ad esempio `home.hero.title`) e può essere aggiornato nel valore, negli stili predefiniti (dimensione, peso, colore) e — per le immagini — sostituito con un upload o riportato all'originale.
|
|
|
|
Il pannello raggruppa i tag per pagina, offre una ricerca per tag o contenuto e mostra per ogni blocco l'ultima modifica effettuata. Visitando il sito da utente autenticato con il parametro `?annotate=1` (link "Vedi sito con tag" nel pannello), ogni contenuto taggato viene evidenziato con un badge che rimanda direttamente al form di modifica corrispondente.
|
|
|
|
Sono previsti due ruoli utente: `admin` ha accesso completo (articoli del blog, contenuti, upload), mentre `editor` può operare esclusivamente sul pannello contenuti. Gli utenti si creano con `npm run create-user -- <nome> <password> editor`.
|
|
|
|
## Struttura Progetto
|
|
|
|
```
|
|
insanitylab-website/
|
|
├── src/
|
|
│ ├── pages/ # Pagine Astro (routing automatico)
|
|
│ ├── components/ # Componenti Astro riutilizzabili
|
|
│ ├── layouts/ # Layout master
|
|
│ ├── utils/ # Funzioni di utilità
|
|
│ ├── env.d.ts # Type definitions globali
|
|
│ └── ...
|
|
├── data/ # Database SQLite e dati persistenti
|
|
│ └── insanitylab.db # (generato al primo avvio)
|
|
├── uploads/ # Directory per upload immagini e file
|
|
├── dist/ # Output build (server)
|
|
├── tests/ # Test suite
|
|
├── astro.config.mjs # Configurazione Astro
|
|
├── tsconfig.json # Configurazione TypeScript
|
|
├── vitest.config.ts # Configurazione test framework
|
|
├── .env.example # Template variabili di ambiente
|
|
├── .env # Variabili di ambiente (non versionato)
|
|
├── package.json # Dipendenze e script npm
|
|
└── README.md # Questo file
|
|
```
|
|
|
|
## Configurazione Ambiente
|
|
|
|
Il file `.env` richiede le seguenti variabili:
|
|
|
|
- `SMTP_HOST`: Host SMTP per invio email
|
|
- `SMTP_PORT`: Porta SMTP (solitamente 587)
|
|
- `SMTP_USER`: Utente SMTP
|
|
- `SMTP_PASS`: Password SMTP
|
|
- `CONTACT_TO`: Email di destinazione contatti
|
|
- `CONTACT_FROM`: Email mittente
|
|
- `DB_PATH`: Percorso database SQLite
|
|
- `UPLOADS_DIR`: Cartella upload file
|
|
|
|
## Development Workflow
|
|
|
|
1. **Avvia il server locale**: `npm run dev`
|
|
2. **Modifica file** in `src/` (hot reload automatico)
|
|
3. **Test**: `npm run test`
|
|
4. **Build**: `npm run build` (verifica errori di build)
|
|
5. **Commit**: Con prefisso `feat:` (feature) o `chore:` (manutenzione)
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
# Build per production
|
|
npm run build
|
|
|
|
# Opzionalmente, preview locale
|
|
npm run preview
|
|
|
|
# In production, il server parte con:
|
|
npm run start
|
|
|
|
# Variabili ambiente in production vanno impostate sull'hosting
|
|
# (es. Hostinger VPS, Vercel, etc.)
|
|
```
|
|
|
|
## Riferimenti Tecnici
|
|
|
|
Per dettagli su architettura, schema database, componenti e specifiche vedi:
|
|
- `/docs/superpowers/specs/2026-07-01-insanitylab-website-design.md`
|
|
- `/docs/superpowers/plans/2026-07-01-insanitylab-website.md`
|
|
|
|
## Problemi Comuni
|
|
|
|
### `better-sqlite3` fallisce su npm install
|
|
|
|
Se `better-sqlite3` non compila, assicurati di avere build tools installati:
|
|
- **Linux**: `sudo apt-get install build-essential python3`
|
|
- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
|
|
- **Windows**: Visual Studio Build Tools o MinGW
|
|
|
|
### Database locked
|
|
|
|
Se il database è locato durante i test, verifica che non ci siano processi in background che accedono a `data/insanitylab.db`.
|
|
|
|
## Licenza
|
|
|
|
Proprietario InsanityLab.
|