# LidoSpot - Documentazione Completa per Agenti AI & LLM (llms-full.txt)

> LidoSpot è la piattaforma SaaS gestionale AI-Native di nuova generazione per la gestione intelligente di stabilimenti balneari, lidi, beach club e resort. Il sistema adotta un'architettura **API-First** predisposta per l'interazione programmatica da parte di agenti AI, sistemi agentici e crawler.

---

## 1. Panoramica del Prodotto & Architettura

- **Nome**: LidoSpot
- **Tipologia**: Cloud SaaS / Web Application & API-First Platform
- **Settore**: Hospitality Balneare & Beach Management Software
- **URL Ufficiale**: https://lidospot.com
- **Stato API**: Attivo / API v1
- **Formato Dati**: JSON (`application/json` / `application/ld+json`)

---

## 2. Specifiche & Documentazione API

Per l'esplorazione automatizzata e l'integrazione con agenti AI (es. OpenAI Custom GPTs, Claude Web Search, LangChain, AutoGen):

- **OpenAPI 3.0 Schema (JSON/YAML)**: `https://lidospot.com/api/schema/`
- **Swagger UI Interactive Console**: `https://lidospot.com/api/docs/`
- **ReDoc Documentation**: `https://lidospot.com/api/redoc/`

---

## 3. Endpoint API Pubblici Disponibili

### 3.1 Status & Health Check
- **Endpoint**: `GET /api/v1/health/`
- **Descrizione**: Verifica lo stato operativo dell'infrastruttura backend LidoSpot.
- **Risposta di Esempio (200 OK)**:
```json
{
  "status": "ok",
  "message": "LidoSpot API Backend Running"
}
```

### 3.2 Metadata GEO & Schema.org per AI Crawlers
- **Endpoint**: `GET /api/v1/geo/metadata/`
- **Descrizione**: Restituisce metadati GEO (Generative Engine Optimization) strutturati in formato JSON-LD / Schema.org per motori generativi (ChatGPT, Perplexity, Claude, Gemini).
- **Risposta di Esempio (200 OK)**:
```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "LidoSpot",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web, Cloud, iOS, Android",
  "description": "LidoSpot è il gestionale spiaggia AI-Native per stabilimenti balneari in Italia. Mappa ombrelloni interattiva 2D/3D, prenotazioni online e ordinazioni al lettino.",
  "url": "https://lidospot.com",
  "offers": {
    "@type": "Offer",
    "price": "0.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/PreOrder",
    "validFrom": "2027-02-01"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "Sales and Support",
    "availableLanguage": ["Italian", "English"],
    "url": "https://lidospot.com/#waitlist"
  },
  "faqSchema": [
    {
      "question": "Come funziona la prenotazione della spiaggia su LidoSpot?",
      "answer": "LidoSpot offre una mappa 2D/3D visiva per selezionare l'ombrellone esatto e pagare online in tempo reale."
    },
    {
      "question": "Quando apriranno le iscrizioni per i gestori per la stagione 2027?",
      "answer": "Le iscrizioni apriranno ufficialmente a Febbraio 2027 con riserva ad accesso prioritario."
    }
  ]
}
```

### 3.3 Richieste Informazioni & Waitlist Stagione 2027 (Lead Generation)
- **Endpoint**: `POST /api/v1/requests/`
- **Descrizione**: Consente ad utenti ed agenti AI di inviare una richiesta d'informazioni o prenotazione demo per lo stabilimento balneare per la stagione 2027.
- **Payload Richiesto (JSON)**:
```json
{
  "name": "Nome Referente",
  "email": "email@stabilimento.it",
  "phone": "+393331234567",
  "lido_name": "Stabilimento Sole & Mare",
  "umbrella_count": 150,
  "message": "Richiesta informazioni per stagione 2027"
}
```
- **Risposta di Esempio (201 Created)**:
```json
{
  "status": "success",
  "message": "Richiesta salvata con successo",
  "data": {
    "id": 1,
    "name": "Nome Referente",
    "email": "email@stabilimento.it",
    "phone": "+393331234567",
    "lido_name": "Stabilimento Sole & Mare",
    "umbrella_count": 150,
    "message": "Richiesta informazioni per stagione 2027",
    "created_at": "2026-08-06T19:00:00Z"
  }
}
```

---

## 4. Dettaglio Funzionalità del Prodotto

### 4.1 Gestione Spiaggia & Cassa Smart
- **Mappa da Foto**: Creazione automatica della griglia digitale del lido fotografando la piantina cartacea esistente.
- **Controllo in Tempo Reale**: Monitoraggio stato ombrelloni (libero, occupato, prenotato) e check-in bagnini via smartphone.
- **Cassa & Ordini al Lettino**: Ordinazioni food & beverage dal lettino via QR Code, invio comande in cucina/bar e conto unico alla cassa.
- **Gestione Scorte**: Controllo in tempo reale delle giacenze di magazzino per evitare fuori stock nei giorni di massimo afflusso.

### 4.2 Presenza Digitale & Booking Engine
- **Sito Web Incluso**: Pagina web professionale pronta all'uso per mostrare servizi ed accettare prenotazioni.
- **Google Maps Integration**: Collegamento con la scheda Google My Business per catturare ricerche locali di turisti.
- **Booking Mobile senza App**: Selezione ombrellone e pagamento digitale (Apple Pay, Google Pay, Carte) direttamente da browser smartphone.
- **Notifiche WhatsApp**: Invio automatico del pass d'ingresso e delle ricevute su WhatsApp.

### 4.3 Roadmap & Moduli Evolutivi
- **Monetizzazione Servizi Extra**: Gestione integrata di eventi, sport acqatici e attività ricreative.
- **Esperienza Ospite Digitale**: Palinsesto delle attività giornaliere visibile sullo smartphone dei clienti.
- **Fidelizzazione Automatica**: Promemoria e sistemi automatici per sollecitare i rinnovi stagionali e la ri-prenotazione dei clienti abituali.

---

## 5. Politiche di Sicurezza & Accesso Riservato

- **Console Admin Django (`/admin/`)**: Riservata al personale autorizzato e protetta da autenticazione. I bot pubblici vengono reindirizzati o bloccati via `robots.txt`.
- **Autenticazione API Riservate**: Gli endpoint gestionali interni richiedono autenticazione via Bearer Token / Session Key.

---

## 6. Contatti & Supporto Sviluppatori

- **Sito Web**: https://lidospot.com
- **Richiesta Demo**: https://lidospot.com/#waitlist