1. Glossario
Terminologia di dominio centralizzata per garantire comprensione comune nel team.
| Termine |
Definizione |
| Oggetto Errante |
Oggetto fisico creato da un artigiano, dotato di tag NFC, destinato a viaggiare nel mondo |
| Artigiano |
Utente creatore di oggetti erranti |
| Avvistamento (Sighting) |
Registrazione di una scansione NFC con posizione geografica |
| Viaggiatore |
Utente che ha acquistato un Diario di Viaggio e lo usa per documentare i propri viaggi |
| Follower |
Utente che segue il viaggio di uno o più oggetti erranti |
2. Requisiti Funzionali - Modulo Artigiano
RF-AUTH-01 Registrazione Artigiano
Descrizione: L'artigiano deve poter creare un account sulla piattaforma per iniziare a creare oggetti erranti.
Input richiesti:
- Email (univoca, validata)
- Password (min 8 caratteri, almeno 1 maiuscola, 1 numero)
- Nome attività/brand
- Partita IVA (opzionale)
- Descrizione attività
- Accettazione termini e condizioni
Flusso:
- 1. Artigiano compila form di registrazione
- 2. Sistema valida i dati e verifica unicità email
- 3. Sistema invia email di conferma
- 4. Artigiano clicca su link di verifica
- 5. Account passa in stato "pending_verification" (attesa approvazione admin)
- 6. Admin approva l'account
- 7. Account passa in stato "active" e artigiano può accedere
Criteri di Accettazione:
- ✓ Email deve essere univoca nel sistema
- ✓ Password hashata con bcrypt (salt rounds = 12)
- ✓ Email di conferma inviata entro 30 secondi
- ✓ Link di verifica valido per 24 ore
- ✓ Dopo approvazione admin, artigiano riceve notifica email
RF-ART-02 Creazione Oggetto Errante
Descrizione: L'artigiano verificato può creare nuovi oggetti erranti da immettere nel mondo.
Input richiesti:
- Nome oggetto (max 100 caratteri)
- Messaggio/dedica (max 500 caratteri)
- Descrizione dettagliata (opzionale, max 2000 caratteri)
- Tipo oggetto: "Classico" o "Diario di Viaggio"
- Foto oggetto (opzionale, max 5MB, formato JPG/PNG)
Output:
- Codice univoco generato (formato: 6 caratteri alfanumerici maiuscoli)
- URL pubblico:
https://errantia.net/e/{codice}
- QR code scaricabile (formato PNG, 512x512px)
Regole di Business:
- Codice univoco deve essere verificato per non esistere già
- Oggetti "Diario di Viaggio" possono essere registrati solo dal proprietario
- Oggetti "Classici" possono essere registrati da chiunque li trovi
- Artigiano può creare max 50 oggetti al mese (limite anti-spam)
RF-ART-03 Dashboard Artigiano
Descrizione: L'artigiano ha una dashboard per visualizzare e gestire i propri oggetti erranti.
Funzionalità:
- Lista di tutti gli oggetti creati con info essenziali:
- Nome, foto, codice univoco
- Numero totale avvistamenti
- Data ultimo avvistamento
- Distanza totale percorsa (calcolata da geo-coordinate)
- Filtri: tutti / attivi / archiviati
- Ordinamento: per data creazione, ultimo avvistamento, numero avvistamenti
- Ricerca full-text per nome oggetto
Azioni disponibili:
- Visualizza dettaglio oggetto (storia completa avvistamenti)
- Modifica info oggetto (nome, descrizione, foto)
- Archivia oggetto (nasconde dalla lista pubblica)
- Scarica report PDF con storia avvistamenti
3. Tracciabilità Requisiti
Ogni requisito è collegato a:
- Sprint di implementazione: RF-AUTH-01 → SPRINT-01-POC
- API endpoint: RF-AUTH-01 → POST /api/v1/auth/register
- Test case: RF-AUTH-01 → TC-AUTH-01, TC-AUTH-02, TC-AUTH-03
- User story: RF-AUTH-01 → US-01 "Come artigiano voglio registrarmi per creare oggetti"
4. Benefici dello Spec Driven Development
Questo documento rappresenta il nostro single source of truth:
- ✓ Versionato in Git insieme al codice (branch:
feature/artisan-registration)
- ✓ Ogni modifica alle spec genera una pull request per review
- ✓ Frontend e Backend team lavorano dalla stessa specifica
- ✓ Stakeholder approvano le spec PRIMA dello sviluppo
- ✓ Link interni tra documenti per navigazione veloce
- ✓ Export PDF per presentazioni e meeting
1. Glossary
Centralized domain terminology to ensure shared understanding within the team.
| Term |
Definition |
| Wandering Object |
Physical object created by an artisan, equipped with an NFC tag, destined to travel the world |
| Artisan |
User who creates wandering objects |
| Sighting |
Registration of an NFC scan with geographic location |
| Traveler |
User who has purchased a Travel Diary and uses it to document their travels |
| Follower |
User who follows the journey of one or more wandering objects |
2. Functional Requirements - Artisan Module
RF-AUTH-01 Artisan Registration
Description: The artisan must be able to create an account on the platform to start creating wandering objects.
Required inputs:
- Email (unique, validated)
- Password (min 8 characters, at least 1 uppercase, 1 number)
- Business name/brand
- VAT number (optional)
- Business description
- Terms and conditions acceptance
Flow:
- 1. Artisan fills in registration form
- 2. System validates data and verifies email uniqueness
- 3. System sends confirmation email
- 4. Artisan clicks verification link
- 5. Account moves to "pending_verification" state (awaiting admin approval)
- 6. Admin approves the account
- 7. Account moves to "active" state and artisan can access
Acceptance Criteria:
- ✓ Email must be unique in the system
- ✓ Password hashed with bcrypt (salt rounds = 12)
- ✓ Confirmation email sent within 30 seconds
- ✓ Verification link valid for 24 hours
- ✓ After admin approval, artisan receives email notification
RF-ART-02 Create Wandering Object
Description: The verified artisan can create new wandering objects to release into the world.
Required inputs:
- Object name (max 100 characters)
- Message/dedication (max 500 characters)
- Detailed description (optional, max 2000 characters)
- Object type: "Classic" or "Travel Diary"
- Object photo (optional, max 5MB, JPG/PNG format)
Output:
- Generated unique code (format: 6 uppercase alphanumeric characters)
- Public URL:
https://errantia.net/e/{code}
- Downloadable QR code (PNG format, 512x512px)
Business Rules:
- Unique code must be verified to not already exist
- "Travel Diary" objects can only be registered by the owner
- "Classic" objects can be registered by anyone who finds them
- Artisan can create max 50 objects per month (anti-spam limit)
RF-ART-03 Artisan Dashboard
Description: The artisan has a dashboard to view and manage their wandering objects.
Features:
- List of all created objects with essential info:
- Name, photo, unique code
- Total sightings count
- Last sighting date
- Total distance traveled (calculated from geo-coordinates)
- Filters: all / active / archived
- Sorting: by creation date, last sighting, number of sightings
- Full-text search by object name
Available actions:
- View object detail (complete sighting history)
- Edit object info (name, description, photo)
- Archive object (hides from public list)
- Download PDF report with sighting history
3. Requirements Traceability
Each requirement is linked to:
- Implementation sprint: RF-AUTH-01 → SPRINT-01-POC
- API endpoint: RF-AUTH-01 → POST /api/v1/auth/register
- Test case: RF-AUTH-01 → TC-AUTH-01, TC-AUTH-02, TC-AUTH-03
- User story: RF-AUTH-01 → US-01 "As an artisan I want to register to create objects"
4. Benefits of Spec Driven Development
This document represents our single source of truth:
- ✓ Versioned in Git alongside code (branch:
feature/artisan-registration)
- ✓ Every spec change generates a pull request for review
- ✓ Frontend and Backend teams work from the same specification
- ✓ Stakeholders approve specs BEFORE development
- ✓ Internal links between documents for quick navigation
- ✓ PDF export for presentations and meetings