# TrattorIA - Documento dei Requisiti di Prodotto

**Autore:** ARchetipo
**Data:** 06/05/2026
**Versione:** 1.0

---

## Elevator Pitch

> TrattorIA aiuta chi vive la strada a trovare in pochi secondi una sosta affidabile dove mangiare bene, parcheggiare senza stress e spendere il giusto.
>
> Per **camionisti e lavoratori in trasferta**, che hanno il problema di **trovare rapidamente trattorie affidabili in luoghi che non conoscono**, **TrattorIA** e una **app mobile di discovery locale per la ristorazione on-the-road** che **mostra subito i locali piu vicini con segnali chiari su distanza, parcheggio camion, prezzo e affidabilita**. A differenza di **Google Maps, passaparola e app generaliste**, il nostro prodotto **rende visibili trattorie familiari rilevanti per chi transita e filtra il rumore con informazioni pratiche pensate per una sosta di lavoro**.

---

## Visione

TrattorIA vuole diventare il punto di riferimento per la sosta pranzo e cena di chi lavora su strada in Italia, partendo da un bisogno semplice ma critico: decidere velocemente dove fermarsi senza sbagliare. Il prodotto non nasce per aiutare a "scegliere un ristorante", ma per aiutare a "trovare una sosta affidabile in meno di un minuto".

Sul lato offerta, TrattorIA vuole dare alle trattorie a conduzione familiare uno strumento leggero per farsi trovare da nuovi clienti di passaggio, comunicare cio che serve davvero a chi guida per lavoro e costruire fidelizzazione senza dover investire in marketing digitale complesso.

### Differenziatore di Prodotto

TrattorIA si differenzia perche:

- e focalizzata su utenti in mobilita lavorativa, non sulla ristorazione generalista
- privilegia segnali decisionali immediati: distanza, parcheggio camion, rapidita, prezzo, affidabilita
- valorizza trattorie indipendenti oggi poco visibili sulle piattaforme mainstream
- funziona anche con profili quasi statici, senza richiedere aggiornamenti quotidiani complessi ai ristoratori
- usa un modello di fiducia semplice e riconoscibile: badge verificato + "clacsonate" degli utenti

---

## User Personas

### Persona 1: Mario, camionista lungo raggio

**Ruolo:** Camionista professionista
**Eta:** 46 | **Background:** Lavora su tratte nazionali, guida per molte ore al giorno e pianifica soste in base a tempi, accessibilita e affidabilita

**Obiettivi:**
- trovare una trattoria vicina alla posizione attuale senza perdere tempo
- evitare posti con parcheggio inadatto al camion o con tempi di servizio troppo lunghi
- capire subito se il prezzo e coerente con la pausa di lavoro
- costruire nel tempo un set di soste affidabili da riutilizzare

**Pain Point:**
- in zone sconosciute si affida a Google Maps o al passaparola, con risultati incoerenti
- le app generaliste non mostrano chiaramente informazioni essenziali per chi viaggia con mezzi ingombranti
- molte recensioni online non parlano di parcheggio, velocita del servizio o praticita della sosta
- ha poco tempo e poco margine per sperimentare posti sbagliati

**Comportamenti e Strumenti:**
- usa principalmente smartphone in mobilita
- consulta mappe e chiamate rapide prima di uscire dalla tratta
- preferisce segnali semplici e affidabili a schede lunghe o contenuti editoriali
- condivide consigli con altri colleghi quando un posto funziona davvero

**Motivazioni:** Mangiare bene, non perdere tempo operativo e ridurre il rischio di una sosta sbagliata.
**Confidenza Tecnologica:** Media

#### Customer Journey - Mario, camionista lungo raggio

| Fase | Azione | Pensiero | Emozione | Opportunita |
|---|---|---|---|---|
| Scoperta | Vede l'app consigliata da un collega o in una comunita di autotrasportatori | "Se mi fa trovare un posto giusto in fretta, mi serve davvero" | Curioso ma prudente | Posizionare TrattorIA come strumento pratico per chi vive la strada |
| Valutazione | Controlla se l'app mostra locali vicini con parcheggio camion, prezzo e affidabilita | "Non mi interessa tutto: mi servono solo i posti adatti al mio lavoro" | Selettivo | Evidenziare utilita immediata e filtro del rumore |
| Primo Utilizzo | Apre l'app in pausa, guarda i locali vicini e tocca la scheda migliore | "Devo decidere in 20 secondi se uscire o andare avanti" | Sotto pressione | Mostrare subito distanza, clacsonate, prezzo e badge verificato |
| Uso Regolare | Riusa l'app nelle soste successive e inizia a confrontare opzioni affidabili | "Se continua a darmi posti giusti, diventa una mia abitudine" | Fiducioso | Introdurre preferiti e storico soste come acceleratori d'uso |
| Advocacy | Lascia una clacsonata e consiglia il locale o l'app ad altri colleghi | "Questo posto merita, qui ci torno" | Soddisfatto | Trasformare il passaparola offline in segnale digitale utile |

---

### Persona 2: Anna, gestora di trattoria familiare

**Ruolo:** Titolare operativa di trattoria a conduzione familiare
**Eta:** 53 | **Background:** Gestisce sala, cassa e rapporto con i clienti; ha poco tempo per strumenti digitali e nessun presidio marketing strutturato

**Obiettivi:**
- farsi trovare da camionisti e lavoratori in transito vicino al locale
- comunicare in modo semplice menu del giorno, promo e servizi utili
- ricevere piu clienti reali senza dover imparare piattaforme complesse
- fidelizzare chi passa spesso in zona

**Pain Point:**
- non ha tempo per curare pubblicita, social o portali complessi
- e poco presente sulle piattaforme digitali che oggi generano scoperta
- gli strumenti esistenti non sono pensati per il traffico di passaggio e per esigenze pratiche come il parcheggio camion
- teme di dover aggiornare troppe informazioni troppo spesso

**Comportamenti e Strumenti:**
- usa smartphone e WhatsApp ogni giorno
- preferisce processi guidati, brevi e con supporto umano quando serve
- aggiorna volentieri poche informazioni ad alto impatto
- ragiona in termini di coperti reali, non di vanity metrics

**Motivazioni:** Riempire i tavoli nei momenti giusti e trasformare i passanti in clienti abituali con il minimo sforzo operativo.
**Confidenza Tecnologica:** Bassa-Media

#### Customer Journey - Anna, gestora di trattoria familiare

| Fase | Azione | Pensiero | Emozione | Opportunita |
|---|---|---|---|---|
| Scoperta | Viene contattata dal team o scopre il servizio tramite passaparola locale | "Se mi porta clienti veri senza complicarmi la giornata, mi interessa" | Interessata ma diffidente | Presentare un valore diretto e concreto, non marketing astratto |
| Valutazione | Controlla cosa deve inserire e come puo ricevere contatti | "Quanto tempo mi costa stare qui sopra?" | Prudente | Offrire onboarding breve e supporto via WhatsApp |
| Primo Utilizzo | Crea o rivendica la scheda e compila i dati essenziali | "Se bastano poche info, posso farlo subito" | Sollevata | Ridurre al minimo i campi obbligatori e guidare la compilazione |
| Uso Regolare | Aggiorna saltuariamente menu, promo e orari speciali | "Va bene se funziona anche quando non aggiorno ogni giorno" | Pragmatica | Progettare un sistema che resta utile anche con profili quasi statici |
| Advocacy | Nota nuovi clienti di passaggio e rinnova il profilo premium o consiglia il servizio ad altri locali | "Mi porta persone giuste, quindi continuo" | Convinta | Collegare visibilita digitale a impatto commerciale misurabile |

---

## Insight di Brainstorming

> Principali scoperte e direzioni alternative emerse durante la sessione di inception.

### Assunzioni Sfidate

- Il vero job-to-be-done non e "scoprire ristoranti", ma "trovare una sosta affidabile in 30 secondi".
- Per la prima versione non servono booking, pagamenti o esperienze complesse di prenotazione.
- Le trattorie non devono essere costrette ad aggiornare tutto ogni giorno: il prodotto deve restare utile anche con profili quasi statici.
- Per l'MVP e sufficiente la ricerca vicino alla posizione attuale; la ricerca lungo il percorso puo restare fuori dal perimetro iniziale.
- Un'app mobile puo essere il prodotto principale, ma l'acquisizione di utenti prima del primo bisogno reale resta un'ipotesi da validare sul campo.

### Nuove Direzioni Scoperte

- La metrica sociale distintiva puo essere la "clacsonata", un segnale rapido che equivale a "ci tornerei".
- Il badge verificato assegnato dallo staff puo diventare un forte acceleratore di fiducia nelle prime fasi del marketplace.
- L'onboarding lato trattoria deve combinare registrazione autonoma e supporto guidato via WhatsApp.
- Il prodotto puo crescere in seguito con preferiti, storico soste, filtri avanzati e loyalty per utenti abituali.
- Questioni aperte da validare nelle prime settimane:
  - quanto l'app-only limita l'acquisizione rispetto a una superficie web piu ampia
  - quale modello operativo rende sostenibile una copertura nazionale di locali verificati
  - se il supporto WhatsApp debba restare umano o evolvere in automazione assistita da AI

---

## Product Scope

### MVP - Minimum Viable Product

L'MVP di TrattorIA deve includere:

- app mobile per iOS e Android con ricerca delle trattorie vicine alla posizione attuale
- lista e mappa dei locali con indicatori grafici immediati di prezzo e clacsonate
- dettaglio trattoria con distanza, parcheggio camion, orari, prezzo medio o fisso, menu del giorno se presente, telefono/WhatsApp e badge verificato
- contatto one-tap verso telefono o WhatsApp
- recensione semplificata tramite clacsonata e breve commento opzionale
- registrazione e gestione scheda trattoria via app o web leggero
- backoffice staff per verifica dei locali, moderazione recensioni e gestione contenuti essenziali
- supporto a profili quasi statici, con aggiornamenti facoltativi per menu del giorno e promo

Sono esplicitamente fuori dall'MVP:

- booking
- pagamenti
- ricerca lungo il percorso
- loyalty attiva
- notifiche push avanzate

### Growth Features (Post-MVP)

- preferiti utente e storico soste
- filtri avanzati per servizi aggiuntivi e bisogni specifici
- promo geolocalizzate e alert contestuali
- dashboard merchant con metriche base su visualizzazioni e contatti generati
- ricerca per corridoi logistici, aree industriali o uscite strategiche

### Visione (Futuro)

- motore di raccomandazione per soste abituali e nuove alternative affidabili
- programma loyalty tra utenti di passaggio e trattorie aderenti
- assistente AI su WhatsApp per onboarding e aggiornamento contenuti dei ristoratori
- partnership con flotte, reti logistiche e comunita professionali di autotrasporto
- estensione del modello a servizi on-the-road oltre al pasto (docce, riposo, servizi al mezzo)

---

## Architettura Tecnica

> **Proposta da:** Leonardo (Architect)

### System Architecture

L'architettura proposta per TrattorIA e una piattaforma a due lati con un client mobile per gli utenti on-the-road, una superficie web leggera per trattorie e staff, e un backend centralizzato che gestisce ricerca geolocalizzata, profili, recensioni, verifica e contenuti. Il sistema deve privilegiare velocita di risposta, semplicita operativa e capacita di evolvere senza introdurre subito microservizi.

**Architectural Pattern:** Modular monolith API-first con client mobile sottile e servizi di ricerca geospaziale

**Main Components:**
- app mobile Expo/React Native per discovery, dettaglio locale, clacsonate e contatti rapidi
- API backend modulare per autenticazione, ricerca geolocalizzata, schede trattoria, recensioni e badge verificato
- database PostgreSQL con PostGIS per query per prossimita e ordinamento geografico
- portale web leggero per onboarding trattorie e backoffice staff
- object storage per immagini e asset delle schede
- integrazione mappe/geocoding per visualizzazione e normalizzazione indirizzi
- integrazione via deep link a telefono e WhatsApp, senza chat proprietaria obbligatoria nell'MVP

### Technology Stack

| Layer | Tecnologia | Versione | Razionale |
|---|---|---|---|
| Linguaggio | TypeScript | 5.6 | Unifica backend, mobile e web con forte tipizzazione e buona produttivita per team piccoli |
| Framework Backend | NestJS | 11 | Offre struttura modulare, testabilita e convenzioni chiare per un backend API-first |
| Framework Frontend | Expo / React Native | SDK 53 / RN 0.76 | Consente di rilasciare rapidamente una vera app mobile cross-platform con ottima DX |
| Database | PostgreSQL + PostGIS | 16 / 3.4 | Supporta in modo affidabile ricerca geospaziale, ordinamenti per distanza e crescita futura |
| ORM | Prisma | 6 | |
| Auth | Supabase Auth | | |
| Testing | Vitest + Supertest + Playwright | | |

### Project Structure

**Organizational pattern:** Monorepo per applicazioni e pacchetti condivisi, organizzato per dominio e responsabilita

```text
apps/
  mobile/
  api/
  merchant-web/
packages/
  ui/
  config/
  domain/
  schemas/
infrastructure/
  docker/
  scripts/
docs/
  PRD.md
```

### Development Environment

L'ambiente locale deve permettere a un piccolo team di sviluppare mobile, backend e pannello merchant con setup prevedibile. Il backend gira in locale con PostgreSQL/PostGIS via Docker, mentre la mobile app usa Expo per sviluppo rapido su device reali.

**Required tools:** Node.js 22 LTS, pnpm 9, Docker Desktop, PostgreSQL/PostGIS locale o containerizzato, Expo CLI / Expo Go, GitHub, accesso a provider mappe

### CI/CD & Deployment

**Build tool:** pnpm workspace + Turborepo + Expo Application Services (EAS)

**Pipeline:** GitHub Actions esegue lint, type-check, unit test, test API, build del pannello web e build preview mobile; il deploy in produzione richiede approvazione manuale per i rilasci mobile.

**Deployment:** Backend containerizzato su piattaforma managed in regione EU, portale merchant deployato come web app statica/serverless, database PostgreSQL gestito, object storage separato per media; le release mobile passano da App Store e Google Play.

**Target infrastructure:** Fly.io o Render per API, Neon o equivalente PostgreSQL EU con PostGIS, Vercel per merchant-web, Cloudflare R2 o equivalente per immagini, Sentry per monitoraggio errori

### Architecture Decision Records (ADR)

- ADR-001: partire con app mobile come prodotto principale per l'utente finale, mantenendo una superficie web leggera lato merchant/staff.
- ADR-002: limitare l'MVP alla ricerca vicino alla posizione attuale per ridurre complessita di UX e integrazioni.
- ADR-003: adottare un modular monolith anziche microservizi, per velocizzare sviluppo e manutenzione nelle prime fasi.
- ADR-004: progettare il profilo trattoria per funzionare bene anche in modalita quasi statica, con pochi campi ad alto impatto.
- ADR-005: affidare la fiducia iniziale a badge verificato e clacsonate, non a sistemi reputazionali complessi.
- ADR-006: escludere booking e pagamenti dall'MVP e concentrare la conversione su chiamata e WhatsApp.

---

## Requisiti Funzionali

### Discovery e ricerca

1. **FR-001** - Il sistema deve rilevare la posizione attuale dell'utente, previo consenso, e mostrare le trattorie entro un raggio configurabile.
2. **FR-002** - Il sistema deve presentare i risultati in lista e mappa, ordinati di default per distanza crescente.
3. **FR-003** - Ogni risultato deve mostrare in modo visivo almeno nome locale, distanza, presenza parcheggio camion, fascia prezzo e numero di clacsonate.
4. **FR-004** - L'utente deve poter filtrare almeno per parcheggio camion disponibile, aperto ora, fascia prezzo e badge verificato.

### Scheda trattoria e conversione

5. **FR-005** - La scheda trattoria deve includere come campi obbligatori: nome, indirizzo, distanza, orari, parcheggio camion, prezzo medio o fisso, numero telefono o WhatsApp; menu del giorno e promo devono essere opzionali ma evidenti quando presenti.
6. **FR-006** - L'app deve consentire con un solo tap di chiamare il locale o aprire la conversazione WhatsApp sul numero configurato.
7. **FR-007** - L'app deve evidenziare chiaramente il badge verificato e la data dell'ultimo aggiornamento dei contenuti variabili, per aiutare la valutazione di affidabilita.

### Fiducia e feedback

8. **FR-008** - Gli utenti devono poter lasciare una clacsonata come segnale rapido di gradimento e, opzionalmente, una breve recensione testuale.
9. **FR-009** - Il sistema deve calcolare e mostrare il totale delle clacsonate e una sintesi delle recensioni recenti nella scheda trattoria.
10. **FR-010** - Lo staff deve poter moderare recensioni, segnalazioni e abusi, nonche assegnare o revocare il badge verificato.

### Onboarding e gestione trattorie

11. **FR-011** - Una trattoria deve potersi registrare tramite app o sito web leggero e creare o rivendicare la propria scheda.
12. **FR-012** - Il ristoratore deve poter aggiornare con flusso semplificato i dati statici del locale e, quando desidera, menu del giorno e promo pranzo/cena.
13. **FR-013** - Il sistema deve permettere al ristoratore di definire il canale di contatto preferito tra telefono e WhatsApp, con supporto a entrambi se disponibili.
14. **FR-014** - Lo staff deve poter assistere l'onboarding della trattoria da backoffice, inclusa la creazione manuale o la correzione di profili incompleti.

### Operazioni e misurazione

15. **FR-015** - Il sistema deve tracciare eventi chiave come visualizzazioni scheda, tap su chiamata, tap su WhatsApp e inserimento clacsonate per misurare l'efficacia del marketplace.
16. **FR-016** - Il sistema deve supportare profili quasi statici senza penalizzare la visibilita dei locali che non aggiornano quotidianamente menu e promo.

---

## Requisiti Non Funzionali

### Security

- autenticazione obbligatoria per trattorie e staff; navigazione pubblica consentita agli utenti finali, con account richiesto per recensioni e clacsonate persistenti
- autorizzazione basata su ruoli per separare permessi utente, merchant e staff
- cifratura dei dati in transito tramite HTTPS/TLS e protezione dei segreti tramite secret management del provider
- conservazione minima dei dati di geolocalizzazione, evitando memorizzazione non necessaria della posizione precisa degli utenti
- conformita GDPR per informativa privacy, consenso, export dati e richiesta di cancellazione account
- rate limiting, protezione anti-spam e controlli antifrode per clacsonate e recensioni abusive
- audit log per azioni sensibili di backoffice come verifica locale, modifica schede e moderazione contenuti

### Integrations

- integrazione con SDK di geolocalizzazione mobile per ottenere la posizione attuale dell'utente
- integrazione con provider mappe/geocoding per visualizzazione mappa, reverse geocoding e normalizzazione indirizzi
- integrazione con deep link telefonici e WhatsApp per conversione immediata fuori dall'app
- integrazione con servizio di storage media per immagini dei locali
- integrazione con analytics e crash reporting per misurare attivazione, conversione e affidabilita dell'app
- nessuna integrazione di booking o pagamenti prevista nell'MVP

---

## Prossimi Passi

1. **Backlog** - Eseguire `/archetipo-spec` per trasformare questo PRD in backlog operativo.
2. **Design** - Eseguire `/archetipo-design` per produrre mockup UI dell'app mobile e del pannello trattoria.
3. **Validation** - Validare con stakeholder e utenti sul campo le ipotesi piu rischiose: acquisizione app-only, sostenibilita del badge verificato su scala nazionale e valore percepito della clacsonata.

---

_PRD generato tramite ARchetipo Product Inception - 06/05/2026_
_Sessione condotta da: Utente con il team ARchetipo_
