gestione-adozioni-animali

Piattaforma per gestione adozioni animali con ruoli e autenticazione.

Overview

Product Requirements Document (PRD)

1. Project Overview

gestione-adozioni-animali è una piattaforma web per la gestione delle adozioni di animali tra rifugi e adottanti. L’obiettivo è digitalizzare e semplificare il processo di adozione, offrendo strumenti sicuri e trasparenti per la pubblicazione di annunci, la gestione delle richieste e la comunicazione tra le parti coinvolte. La piattaforma garantisce un controllo amministrativo centralizzato e la conformità alle normative vigenti (es. GDPR).

---

2. Goals & Success Metrics

Obiettivi

• Facilitare l’incontro tra adottanti e rifugi tramite una piattaforma intuitiva e accessibile.
• Garantire la sicurezza dei dati e la trasparenza delle operazioni.
• Automatizzare e tracciare il processo di adozione, riducendo errori e tempi di gestione.
• Offrire strumenti di comunicazione diretta e notifiche tempestive agli utenti.
• Consentire la moderazione e la supervisione amministrativa.

Success Metrics

• Tempo medio di risposta API: < 2 secondi per il 95% delle richieste.
• Uptime della piattaforma: > 99% su base mensile.
• Tasso di completamento delle adozioni: almeno il 10% delle richieste inviate si conclude con un’adozione.
• Tempo medio di risposta alle richieste di adozione: < 24 ore.
• Zero violazioni di sicurezza e conformità GDPR.
• Soddisfazione utenti: punteggio > 4/5 nei sondaggi di feedback.

---

3. Target Users

Adottante

• Privati cittadini interessati ad adottare un animale.
• Esigenze: consultare annunci, inviare richieste, comunicare con i rifugi, monitorare lo stato delle proprie richieste.

Rifugio

• Organizzazioni o volontari che gestiscono animali in cerca di adozione.
• Esigenze: pubblicare e gestire annunci, ricevere e gestire richieste, comunicare con adottanti.

Amministratore

• Staff della piattaforma o enti di controllo.
• Esigenze: gestione utenti, moderazione contenuti, verifica rifugi, consultazione log, gestione segnalazioni.

---

4. Core Features

4.1 Autenticazione & Autorizzazione

• Login/Logout tramite Laravel Sanctum (token-based).
• Registrazione utenti (adottante, rifugio, amministratore).
• Gestione ruoli: policy e middleware per autorizzare le operazioni in base al ruolo.
• Stato account: attivo, sospeso, disattivato.

4.2 Gestione Annunci Animali

• Consultazione pubblica degli annunci (anche da non autenticati).
• Filtri e ricerca per specie, razza, età, taglia, stato, ecc.
• Dettaglio annuncio con immagini e descrizione.
• CRUD annunci (solo rifugi): creazione, modifica, rimozione.
• Stato annuncio: disponibile, in valutazione, adottato.

4.3 Gestione Richieste di Adozione

• Invio richiesta (adottanti autenticati) per un annuncio.
• Visualizzazione richieste: adottante (le proprie), rifugio (ricevute per i propri annunci).
• Aggiornamento stato richiesta: inviata, presa in carico, approvata, rifiutata, completata.
• Storico richieste per ogni utente.

4.4 Chat Interna

• Conversazione associata a ciascuna richiesta di adozione.
• Invio e ricezione messaggi in tempo reale (WebSocket).
• Notifica di nuovi messaggi (email + badge UI).
• Visualizzazione stato lettura dei messaggi.

4.5 Notifiche

• Email per eventi chiave: nuova richiesta, nuovi messaggi, cambio stato richiesta.
• Sistema di notifiche in-app (badge, elenco notifiche).
• Gestione preferenze notifiche (opt-in/out email).

4.6 Moderazione & Amministrazione

• Gestione utenti: visualizza, sospendi, disattiva, riattiva account.
• Gestione rifugi: approva/rifiuta registrazione, verifica documentazione.
• Moderazione annunci: modifica/rimuovi contenuti non conformi.
• Gestione segnalazioni: ricezione e risoluzione.
• Ripristino contenuti rimossi per errore.
• Consultazione log di sistema.

4.7 Log di Sistema

• Tracciamento eventi: login/logout, registrazioni, CRUD annunci, richieste di adozione, azioni amministrative, errori, accessi non autorizzati.
• Dettagli log: utente coinvolto, azione, data/ora, IP, esito.
• Visualizzazione e ricerca log (solo amministratori).
• Esportazione log (CSV/PDF).

---

5. Technical Architecture

5.1 Stack Tecnologico

• Frontend: Vue.js 3, Vite, Tailwind CSS
• Backend: Laravel (PHP 8+), Laravel Sanctum
• Database: MySQL 8
• Realtime: Laravel Reverb/Pusher per chat
• Storage immagini: filesystem locale (dev), S3-compatible (prod)
• Email: SMTP provider esterno (Amazon SES, SendGrid, Mailgun)
• Containerizzazione: Docker, Docker Compose

5.2 Modelli Dati Principali

Utente

Campo	Tipo	Note
id	int	PK
nome	string
cognome	string
email	string	Unico
password	string	Hash
ruolo	enum	adottante, rifugio, admin
telefono	string
indirizzo	string
stato_account	enum	attivo, sospeso, disattivo
created_at	datetime
updated_at	datetime

Annuncio

Campo	Tipo	Note
id	int	PK
rifugio_id	int	FK -> utente
nome_animale	string
specie	string
razza	string
età	int
sesso	string
taglia	string
descrizione	text
immagini	array
stato	enum	disponibile, valutazione, adottato
created_at	datetime
updated_at	datetime

Richiesta di Adozione

Campo	Tipo	Note
id	int	PK
annuncio_id	int	FK -> annuncio
adottante_id	int	FK -> utente
messaggio_iniziale	text
stato	enum	inviata, presa in carico, approvata, rifiutata, completata
data_richiesta	datetime

Messaggio

Campo	Tipo	Note
id	int	PK
richiesta_id	int	FK -> richiesta
mittente_id	int	FK -> utente
contenuto	text
letto	bool
timestamp	datetime

5.3 API Endpoints Principali

Annunci

• GET /api/announcements
• GET /api/announcements/{id}
• POST /api/announcements (rifugio)
• PUT /api/announcements/{id} (rifugio)
• DELETE /api/announcements/{id} (rifugio)

Richieste di Adozione

• POST /api/adoption-requests (adottante)
• GET /api/adoption-requests (utente autenticato)
• PATCH /api/adoption-requests/{id}/status (rifugio)

Chat

• GET /api/adoption-requests/{id}/messages
• POST /api/adoption-requests/{id}/messages

Moderazione/Admin

• GET /api/users
• PATCH /api/users/{id}/status
• GET /api/logs
• POST /api/reports
• PATCH /api/shelters/{id}/verification

5.4 Componenti Chiave

• Frontend SPA: Vue.js, autenticazione tramite token, routing protetto.
• Backend API REST: Laravel, policy/middleware per autorizzazioni.
• Realtime Service: WebSocket per chat.
• Job Queue: Laravel Queue per notifiche asincrone.
• Storage: gestione immagini animali.
• Email Service: invio notifiche.
• Admin Panel: dashboard per amministratori.

---

6. Non-Functional Requirements

Performance

• Tempo medio risposta API < 2s.
• Caricamento SPA < 3s su connessioni standard.
• Ottimizzazione query DB e caching (Redis).

Sicurezza

• Autenticazione sicura (token, hashing password).
• Autorizzazione rigorosa tramite policy/middleware.
• Protezione dati personali (GDPR).
• Logging accessi e azioni sensibili.
• Rate limiting API.
• Validazione input e prevenzione XSS/CSRF.

Scalabilità

• Supporto a migliaia di utenti registrati.
• Code asincrone per notifiche/email.
• Storage immagini scalabile (S3).
• Possibilità di scaling orizzontale (API, WebSocket).
• Replica in lettura DB (futuro).

Affidabilità

• Backup regolari DB e storage.
• Monitoraggio uptime e errori.
• Recovery procedure documentate.

---

7. Out of Scope (v1)

• Notifiche push (mobile/web).
• App mobile native.
• Integrazione con social network per login.
• Pagamenti online o donazioni.
• Gestione documentazione legale per adozioni.
• Statistiche avanzate/reportistica custom.
• Traduzioni multilingua.
• Integrazione con sistemi esterni di gestione rifugi.

---

8. Open Questions

• Definizione dettagliata dei payload API e codici di errore (da completare in OpenAPI/Swagger).
• Specifica dei criteri di verifica dei rifugi (documentazione richiesta, flusso di approvazione).
• Policy di retention e anonimizzazione dei log in ottica GDPR.
• Limiti su dimensione e formato immagini caricabili.
• Gestione di account multipli per uno stesso rifugio (necessità di ruoli secondari?).
• Modalità di escalation e risoluzione delle segnalazioni.
• Personalizzazione email (branding, template).
• Flessibilità futura per supporto multilingua.

---

Fine documento