giampy-dogservice/.gitea/readme.md

Giampy Dog Service

Cos'è questo progetto

Questo repository contiene il sito di Giampy Dog Service, sviluppato con SvelteKit.

Il progetto ha due parti principali:

• sito pubblico: landing page con contenuti, immagini, testimonianze, mappa e form contatti
• area admin: pannello interno per modificare testi, SEO, immagini, testimonianze, notifiche, richieste ricevute e utenti amministratori

Non usa un database esterno: i dati vengono salvati in file JSON dentro la cartella data/.

Linguaggi e tecnologie usate

• TypeScript: logica server, validazioni, storage, autenticazione
• Svelte 5 / SvelteKit: rendering delle pagine, routing e form actions
• CSS: stile globale del sito e del pannello admin
• Node.js: runtime server-side
• Vite: build e sviluppo locale
• Leaflet: mappa caricata lato client nella home page

Dipendenze principali dichiarate in package.json:

• @sveltejs/kit
• svelte
• typescript
• vite
• @sveltejs/adapter-node
• leaflet
• @fortawesome/fontawesome-free

Come funziona il codice

1. Avvio globale

Il punto importante è src/hooks.server.ts.

Qui succedono due cose:

• viene creato automaticamente un admin di default se non esiste ancora
• viene controllata la sessione per proteggere tutte le route /admin

Se non esistono utenti admin, al boot viene creato:

• username: admin
• password: changeme

oppure vengono usate le variabili ambiente:

• ADMIN_USERNAME
• ADMIN_PASSWORD

2. Sito pubblico

La home è composta principalmente da:

• src/routes/+page.svelte
• src/routes/+page.server.ts

Il file server:

• carica i contenuti con getContent()
• gestisce l'action del form contatti
• salva le richieste in data/submissions.json
• crea una notifica in data/notifications.json

Il file Svelte:

• legge i testi e le immagini dal contenuto caricato dal server
• costruisce tutte le sezioni della landing page
• carica Leaflet solo nel browser tramite onMount
• mostra la mappa di Sassari

3. Gestione contenuti

La logica dei contenuti è centralizzata in:

• src/lib/server/content.ts
• src/lib/content/defaults.ts

defaults.ts definisce:

• tutti gli slot di testo modificabili
• le immagini di default
• le testimonianze iniziali
• i valori SEO iniziali

content.ts invece:

• legge data/content.json
• unisce i dati salvati con i valori di default
• espone funzioni per aggiornare copy, immagini, SEO e testimonianze

Questo significa che il progetto funziona anche senza content.json: se il file manca, usa i default.

4. Persistenza dati

Il salvataggio su disco è gestito da src/lib/server/storage.ts.

Il meccanismo è semplice:

• legge i file JSON dalla cartella data/
• se un file non esiste, usa un fallback
• quando scrive, salva prima su un file temporaneo e poi fa rename, riducendo il rischio di corruzione

File dati attesi:

• data/content.json
• data/submissions.json
• data/notifications.json
• data/admin.json
• data/sessions.json

5. Autenticazione admin

La logica è in src/lib/server/auth.ts.

Funziona così:

• gli admin sono salvati in data/admin.json
• le password non sono in chiaro: vengono hashate con scrypt
• le sessioni sono salvate in data/sessions.json
• il cookie di sessione è gds_admin

Operazioni supportate:

• login
• logout
• creazione admin
• eliminazione admin
• cambio password

6. Area admin

Le route admin si trovano in src/routes/admin/.

Sezioni principali:

• copy/: modifica testi e SEO
• images/: upload o reset immagini
• testimonials/: CRUD testimonianze
• submissions/: elenco ed eliminazione contatti ricevuti
• notifications/: lettura e gestione notifiche
• users/: gestione amministratori
• login/ e logout/: autenticazione

Il layout server admin in src/routes/admin/+layout.server.ts calcola anche:

• numero richieste ricevute
• numero notifiche non lette

7. SEO e GEO score

Il progetto contiene una logica semplice di scoring in src/lib/seo.ts.

Analizza i testi per stimare:

• leggibilità
• presenza keyword primarie
• punteggio SEO
• punteggio GEO

Quando i testi o i dati SEO vengono modificati da admin, il sistema confronta il punteggio prima/dopo. Se c'è un calo rilevante, genera una notifica.

Struttura pratica del repository

src/
  lib/
    content/
      defaults.ts        # configurazione contenuti iniziali
    server/
      auth.ts            # login, sessioni, admin
      content.ts         # lettura/scrittura contenuti
      notifications.ts   # notifiche admin
      storage.ts         # persistenza JSON su disco
      submissions.ts     # richieste dal form
      health.ts          # calcolo score SEO/GEO
    seo.ts               # analisi testi
  routes/
    +page.svelte         # sito pubblico
    +page.server.ts      # load + action form contatti
    admin/               # pannello amministrativo
static/
  img/                   # immagini statiche
data/                    # dati runtime salvati su file

Come eseguire il progetto

Installazione dipendenze:

npm install

Avvio in sviluppo:

npm run dev

Build produzione:

npm run build

Preview della build:

npm run preview

Controllo TypeScript/Svelte:

npm run check

Se vuoi modificarlo, cosa devi fare

Cambiare testi del sito

Hai due strade:

• usare il pannello /admin/copy
• modificare i default in src/lib/content/defaults.ts

Regola importante: se cambi solo defaults.ts, i contenuti già salvati in data/content.json continuano ad avere priorità.

Aggiungere una nuova sezione alla home

Passi consigliati:

1. aggiungi i nuovi slot testuali in src/lib/content/defaults.ts
2. se servono immagini, aggiungi un nuovo image slot nello stesso file
3. usa quei valori in src/routes/+page.svelte
4. se la sezione deve essere modificabile da admin, assicurati che legga dagli stessi slot

Modificare il comportamento del form contatti

Devi intervenire in src/routes/+page.server.ts.

Qui puoi:

• aggiungere campi
• cambiare validazioni
• cambiare il formato salvato in submissions.json
• aggiungere invii email o integrazioni esterne

Se aggiungi nuovi campi, aggiorna anche:

• il form in src/routes/+page.svelte
• il tipo Submission in src/lib/server/submissions.ts

Modificare login o utenti admin

Lavora in:

• src/lib/server/auth.ts
• src/routes/admin/login/+page.server.ts
• src/routes/admin/users/+page.server.ts

Se vuoi maggiore sicurezza, i miglioramenti più sensati sono:

• rate limit sul login
• scadenza sessioni più aggressiva
• rotazione sessioni al login
• storage su database invece che file JSON

Cambiare immagini o upload

Controlla:

• src/routes/admin/images/+page.server.ts
• src/routes/admin/testimonials/+page.server.ts

Qui trovi:

• tipi MIME ammessi
• limiti dimensione file
• percorso upload static/img/uploads

Modificare i punteggi SEO/GEO

Intervieni in src/lib/seo.ts.

Se cambi le regole di scoring, verifica anche:

• src/lib/server/health.ts
• src/routes/admin/copy/+page.server.ts

Limiti attuali del progetto

• non c'è un database: tutto è su file JSON
• non c'è un sistema di migrazione dati
• la concorrenza multi-istanza non è gestita
• gli upload finiscono su filesystem locale
• l'admin di default viene creato automaticamente se mancano utenti

Per un deploy piccolo o singola istanza va bene. Per un ambiente più strutturato conviene spostare dati, sessioni e upload su servizi dedicati.

Nota importante

In package.json è presente lo script:

"seed": "node scripts/seed.mjs"

ma nel repository attuale la cartella scripts/ non esiste. Quindi:

• o va aggiunto davvero il file scripts/seed.mjs
• oppure lo script va rimosso da package.json