From a49b1b13ca47fa2663ac5827687ca682062088cc Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Sun, 11 Oct 2026 18:49:10 +0200 Subject: [PATCH] docs: documentazione iniziale (requisiti, architettura, roadmap, ADR 0001-0013) Co-Authored-By: Claude Sonnet 5.5 --- .gitignore | 9 ++ CHANGELOG.md | 26 ++++++ CLAUDE.md | 23 +++++ README.md | 32 +++++++ docs/01-vision-requisiti.md | 45 +++++++++ docs/02-architettura.md | 91 +++++++++++++++++++ docs/03-roadmap.md | 25 +++++ docs/04-rischi-e-domande-aperte.md | 31 +++++++ docs/PROJECT_STATE.md | 26 ++++++ docs/adr/0000-template.md | 19 ++++ docs/adr/0001-backend-pocketbase.md | 28 ++++++ .../adr/0002-ricodifica-invece-di-archivio.md | 20 ++++ docs/adr/0003-codec-av1-vs-hevc.md | 40 ++++++++ docs/adr/0004-pipeline-di-ingest.md | 21 +++++ docs/adr/0005-categorie-ad-albero.md | 19 ++++ docs/adr/0006-posizione-di-riproduzione.md | 16 ++++ docs/adr/0007-frontend-vanilla.md | 16 ++++ docs/adr/0008-progresso-per-utente.md | 24 +++++ docs/adr/0009-accesso-admin-e-utenti.md | 29 ++++++ docs/adr/0010-filmati-solo-nelle-foglie.md | 24 +++++ .../0011-interfaccia-admin-e-credenziali.md | 26 ++++++ docs/adr/0012-pannello-admin-proprio.md | 28 ++++++ docs/adr/0013-accesso-su-rete-di-casa.md | 24 +++++ docs/index.md | 35 +++++++ 24 files changed, 677 insertions(+) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/01-vision-requisiti.md create mode 100644 docs/02-architettura.md create mode 100644 docs/03-roadmap.md create mode 100644 docs/04-rischi-e-domande-aperte.md create mode 100644 docs/PROJECT_STATE.md create mode 100644 docs/adr/0000-template.md create mode 100644 docs/adr/0001-backend-pocketbase.md create mode 100644 docs/adr/0002-ricodifica-invece-di-archivio.md create mode 100644 docs/adr/0003-codec-av1-vs-hevc.md create mode 100644 docs/adr/0004-pipeline-di-ingest.md create mode 100644 docs/adr/0005-categorie-ad-albero.md create mode 100644 docs/adr/0006-posizione-di-riproduzione.md create mode 100644 docs/adr/0007-frontend-vanilla.md create mode 100644 docs/adr/0008-progresso-per-utente.md create mode 100644 docs/adr/0009-accesso-admin-e-utenti.md create mode 100644 docs/adr/0010-filmati-solo-nelle-foglie.md create mode 100644 docs/adr/0011-interfaccia-admin-e-credenziali.md create mode 100644 docs/adr/0012-pannello-admin-proprio.md create mode 100644 docs/adr/0013-accesso-su-rete-di-casa.md create mode 100644 docs/index.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8454687 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +# dati e binari (vedi docs/02-architettura.md) +pb_data/ +/pocketbase +/pocketbase.exe +*.zip +# segreti +.env +.env.* +!.env.example diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..15d1131 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +Formato: [Keep a Changelog](https://keepachangelog.com/it-IT/1.1.0/). Versionamento semantico dal primo rilascio. + +## [Non rilasciato] + +### Aggiunto +- 2026-10-11: struttura documentale iniziale (requisiti, architettura, roadmap, rischi, ADR 0001-0006, PROJECT_STATE). +- 2026-10-11: requisito F-11 (accesso necessario per aggiungere/modificare/eliminare filmati e categorie) e domanda aperta Q-07. +- 2026-10-11: requisito F-12 (per guardare serve un account; gli utenti per ora possono solo guardare); domanda aperta Q-08 (progresso per utente). +- 2026-10-11: ADR 0008, progresso e stato "visto" per utente; sostituisce ADR 0006 (Q-08 chiusa); modello dati `progress` aggiornato. +- 2026-10-11: deciso un solo account admin (F-11); Q-07 ridotta ai punti ancora aperti. +- 2026-10-11: ADR 0009 (admin = superuser PocketBase, account creati solo dall'admin, accesso già dall'MVP); Q-07 chiusa. +- 2026-10-11: risposte Q-02/Q-03/Q-04: ADR 0010 (filmati solo nelle foglie, sostituisce 0005), F-08 diventa Must, N-06 (originali conservati nell'MVP); Q-01/Q-05/Q-06 riformulate. +- 2026-10-11: ADR 0011 (poi sostituito). +- 2026-10-11: risposta Q-05: N-09 dimensionamento iniziale (~40 filmati da 2-3 GB, SSD 1 TB), R-05/R-06 aggiornati; +- 2026-10-11: risposta Q-11: password dimenticata reimpostata dall'admin (F-14/F-15); +- 2026-10-11: risposta Q-09: F-15 profilo utente con cambio password, gestione account in F-14; nuova Q-11 (password dimenticata). +- 2026-10-11: domande Q-13…Q-16 convertite in assunzioni dell'MVP; documentazione pronta per il primo commit. +- 2026-10-11: l'app gira su Raspberry Pi nella rete di casa (N-01, N-10); Q-12 chiusa; nuove Q-14, Q-15, Q-16 e rischi R-07, R-08; sezione Sicurezza riscritta; ADR 0013 sostituisce 0009 (server sulla rete di casa invece di 127.0.0.1). +- 2026-10-11: N-07 riscritto (compatibilità con Safari iOS, Chrome Android e Windows); Q-10 chiusa; nuove Q-12 (accesso da telefono) e Q-13 (admin da telefono); ADR 0003 e R-03 aggiornati. +- 2026-10-11: Q-10 resta aperta, browser di destinazione non decisi (prototipo); non blocca M0. +- 2026-10-11: risposte Q-01 (ipotesi Chrome e Safari, poi ritirata: browser non ancora decisi, N-07/Q-10) e Q-06 (visivamente identico, N-08); ADR 0003 aggiornato con i vincoli dei due browser; nuova Q-10 (dispositivi Safari). +- 2026-10-11: README con cosa c'è da fare; domanda aperta Q-09 (password degli account utenti). +- 2026-10-11: ADR 0012 (pannello admin proprio, F-14, fase M3b; superuser come da documentazione PocketBase, niente `.env`); sostituisce 0011. +- 2026-10-11: allineati PROJECT_STATE, roadmap (M1/M3/M4/M6) e CLAUDE.md alle decisioni su accesso, progresso e categorie. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8b306ad --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,23 @@ +# CLAUDE.md — regole di lavoro per l'IA su questo repo + +1. **Document-first**: prima di scrivere codice, aggiorna il documento pertinente in `docs/` (o crea un ADR). Poi implementa. +2. **SSOT**: non duplicare informazioni. Consulta `docs/index.md` per sapere dove vive ogni tema; negli altri file usa link. +3. **ADR**: ogni scelta tecnica rilevante → nuovo file `docs/adr/NNNN-titolo.md` (numerazione progressiva, mai riusata). Non modificare un ADR accettato: se la decisione cambia, crea un nuovo ADR che lo sostituisce e aggiorna lo stato del vecchio in `Sostituito da NNNN`. +4. **Stato**: a fine lavoro aggiorna `docs/PROJECT_STATE.md` e `CHANGELOG.md` (root). +5. **Verifica**: fatti su librerie/versioni/limiti vanno verificati su fonti ufficiali e citati nel documento (con data). Mai a memoria. +6. **Decisioni aperte**: non scegliere al posto dell'utente; elencale in `docs/04-rischi-e-domande-aperte.md` e chiedi. +7. **Casi limite**: per ogni modulo ragiona sui casi possibili (input vuoti, file corrotti, interruzioni, concorrenza, spazio disco) come farebbe uno sviluppatore senior, e documentali. +8. **Costo zero**: preferire soluzioni gratuite e self-hosted; se serve qualcosa a pagamento, verificare il costo reale e segnalarlo prima. +9. La struttura di `docs/` può adattarsi al progetto: se serve un nuovo documento, aggiungilo a `docs/index.md`. + +## Contesto del progetto (non duplicare: i dettagli stanno nei link) + +- **Cos'è**: web app locale per archiviare e guardare filmati per categoria/sottocategoria, con ripresa dal punto lasciato. Stack: PocketBase + frontend vanilla (ADR 0001, 0007). Stato: [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md). Fase attuale: pre-M0, nessun codice. +- **Lingua**: documentazione, commit e risposte in italiano. +- **Vincoli che non vanno violati senza nuovo ADR**: un solo admin = superuser PocketBase, gli utenti con account possono solo guardare ([ADR 0013](docs/adr/0013-accesso-su-rete-di-casa.md)); progresso e "visto" per utente ([ADR 0008](docs/adr/0008-progresso-per-utente.md)); filmati solo in categorie foglia ([ADR 0010](docs/adr/0010-filmati-solo-nelle-foglie.md)); originali conservati nell'MVP (N-06 in [docs/01-vision-requisiti.md](docs/01-vision-requisiti.md)). +- **Ogni modifica a una regola API o a un campo dati**: aggiorna il modello in [docs/02-architettura.md](docs/02-architettura.md) e ricontrolla i casi limite di accesso (un utente non deve vedere né scrivere i dati di un altro). +- **Fatti su PocketBase/ffmpeg/codec/browser**: verifica sulla documentazione ufficiale e cita URL e data nell'ADR (regola 5). Non assumere comportamenti a memoria (es. collection `users` predefinita: non confermata). +- **Nuovo documento**: aggiungilo a `docs/index.md`. **Nuovo ADR**: aggiungi la riga al registro in `docs/index.md` e usa il template [docs/adr/0000-template.md](docs/adr/0000-template.md). +- **Alla chiusura di una domanda aperta** (Q-xx): rimuovila da `docs/04-rischi-e-domande-aperte.md`, registra l'esito nel requisito o nell'ADR, aggiorna `PROJECT_STATE.md` e `CHANGELOG.md`. +- **Segreti**: nessuna password o token nel repo, nei log o nel changelog; il superuser si crea come da documentazione PocketBase ([ADR 0012](docs/adr/0012-pannello-admin-proprio.md)). +- **Verifica dei link** tra file `.md` dopo ogni modifica alla documentazione. diff --git a/README.md b/README.md new file mode 100644 index 0000000..90e5c2f --- /dev/null +++ b/README.md @@ -0,0 +1,32 @@ +# Videoteca + +Web app **locale** per archiviare filmati per categoria/sottocategoria e guardarli nel browser, con ripresa dal punto in cui si era rimasti. + +- Stato corrente: [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md) +- Indice documentazione e fonti uniche: [docs/index.md](docs/index.md) +- Storico modifiche: [CHANGELOG.md](CHANGELOG.md) + +## Cosa c'è da fare + +Stato: documentazione completa, **nessun codice** (primo commit = solo documentazione). Dettagli e criteri di completamento: [docs/03-roadmap.md](docs/03-roadmap.md). + +1. **Assunzioni dell'MVP** (da rivedere dopo): [docs/04-rischi-e-domande-aperte.md](docs/04-rischi-e-domande-aperte.md). +2. **M0** — spike: PocketBase in locale, prova di codec e ffmpeg su 3 file campione. +3. **M1** — schema dati, utenti e regole di accesso. +4. **M2** — upload e ricodifica. +5. **M3 / M3b** — interfaccia per gli utenti e pannello admin. +6. **M4** — player con ripresa. +7. **M5** — robustezza, backup. **M6** (futura) — esposizione in rete con HTTPS. + +## Principi del repo + +| Principio | Significato qui | +|---|---| +| Docs-as-code | Tutta la documentazione è Markdown nel repo, versionata con il codice | +| Document-first | Prima si scrive/aggiorna doc o ADR, poi il codice | +| ADR | Ogni scelta tecnica rilevante ha un record in `docs/adr/` | +| SSOT | Ogni informazione ha **un solo** documento di riferimento (vedi `docs/index.md`); gli altri la linkano | + +## Avvio (a regime, dopo M1) + +Da definire in `docs/02-architettura.md` §Esecuzione. Non duplicare qui i comandi: linkare. diff --git a/docs/01-vision-requisiti.md b/docs/01-vision-requisiti.md new file mode 100644 index 0000000..7e1b208 --- /dev/null +++ b/docs/01-vision-requisiti.md @@ -0,0 +1,45 @@ +# Visione e requisiti + +## Visione +Archivio personale di filmati, navigabile per categoria → sottocategoria, riproducibile nel browser, che occupa meno spazio possibile senza attese di "decompressione" e ricorda dove ti sei fermato. + +## Correzione del presupposto iniziale +L'idea originale era: salvare i filmati in archivio (zip/tar.gz), decomprimerli all'apertura, ricomprimerli alla chiusura. Non adottata: gli .mp4 (H.264/H.265) sono già compressi e un archivio generico non li riduce in modo apprezzabile, mentre costa tempo e spazio temporaneo a ogni apertura. Il risparmio reale si ottiene **ricodificando** il video una sola volta. Dettagli: [ADR 0002](adr/0002-ricodifica-invece-di-archivio.md). +Conseguenza: non esiste il ciclo "decomprimi → guarda → ricomprimi"; il file è sempre pronto alla riproduzione. + +## Requisiti funzionali + +| ID | Requisito | Priorità | +|---|---|---| +| F-01 | Gestire categorie con sottocategorie (es. A → A1, A2) | Must | +| F-02 | Caricare un filmato assegnandolo a una categoria foglia (come un episodio in una stagione; [ADR 0010](adr/0010-filmati-solo-nelle-foglie.md)) | Must | +| F-03 | Dopo il caricamento il filmato viene ricodificato per ridurne il peso; stato visibile (in elaborazione / pronto / errore) | Must | +| F-04 | Navigare: scegli categoria → sottocategoria → filmato | Must | +| F-05 | Riprodurre nel browser con play/pausa, seek avanti/indietro (±10 s e barra) | Must | +| F-06 | Alla pausa/chiusura, la posizione è salvata; alla riapertura si riparte da lì | Must | +| F-07 | Segnare come "visto" un filmato finito (la posizione riparte da 0) | Should | +| F-08 | Passare al filmato precedente/successivo della stessa categoria | Must (insieme ai ±10 s di F-05) | +| F-09 | Rinominare/spostare/eliminare filmati e categorie | Should | +| F-10 | Miniatura per filmato | Could | +| F-11 | Aggiungere, modificare ed eliminare filmati, categorie e sottocategorie (F-01, F-02, F-09) richiede un accesso (login); senza accesso non si può modificare nulla. Esiste un solo account admin e solo lui ha questo accesso; è il superuser PocketBase e vale già dall'MVP ([ADR 0013](adr/0013-accesso-su-rete-di-casa.md)) | Must | +| F-12 | Per guardare i filmati serve un account (login). Gli utenti con account possono solo guardare: non possono aggiungere, modificare né eliminare nulla (per ora) | Must | +| F-14 | Pannello admin intuitivo, accessibile solo all'admin: caricare filmati con stato di elaborazione visibile, gestire l'albero categorie/stagioni, gestire gli account utenti (creare con password iniziale, reimpostare la password dimenticata, eliminare), rinominare/spostare/eliminare con conferma ([ADR 0012](adr/0012-pannello-admin-proprio.md)) | Must | +| F-15 | Ogni utente ha un profilo con impostazioni dove può cambiare la propria password; la password iniziale la decide l'admin alla creazione dell'account. Se la dimentica, la reimposta l'admin (nessun recupero via email, N-01 costo zero). Un utente può modificare solo il proprio profilo | Must | + +## Requisiti non funzionali + +| ID | Requisito | +|---|---| +| N-01 | L'app gira su un Raspberry Pi nella rete di casa; telefoni, tablet e PC la raggiungono dall'indirizzo IP del Raspberry (decisione 2026-10-11). Nessun accesso da Internet; nessun servizio a pagamento | +| N-02 | Seek fluido anche su file grandi: nessuna riproduzione "tutto in memoria" | +| N-03 | Un upload interrotto o una transcodifica fallita non lasciano stato incoerente né file orfani | +| N-04 | I dati vivono in una sola cartella (`pb_data/`) per un backup semplice | +| N-05 | Ogni scelta tecnica rilevante è tracciata in un ADR | +| N-06 | Gli originali sono conservati durante l'MVP, finché la qualità non è validata | +| N-07 | Compatibilità ampia (decisione 2026-10-11): deve funzionare in modo affidabile su Safari iOS, Chrome Android e Windows (Chrome/Edge), oltre agli altri browser desktop. Implicazioni: interfaccia adatta al touch (pulsanti ±10 s e precedente/successivo grandi, niente scorciatoie solo da tastiera), layout responsive, riproduzione in pagina, file video riproducibili da tutti i browser (vedi [ADR 0003](adr/0003-codec-av1-vs-hevc.md)) | +| N-08 | Qualità: ricodifica "visivamente identica" (CRF prudente, taratura in M0 con confronto visivo); non lossless. Si parte con pochi filmati e poi si allarga | +| N-09 | Dimensionamento iniziale (decisione 2026-10-11): circa 40 filmati da 2-3 GB ciascuno, cioè circa 80-120 GB di originali; SSD da 1 TB. Il risparmio reale e i tempi di ricodifica si misurano in M0 | +| N-10 | Il backend e la ricodifica devono poter girare su Raspberry Pi (Linux ARM). Modello, RAM e disco: Q-14 | + +## Fuori scopo (per ora) +Permessi utente oltre a "guardare" (F-12) e "amministrare" (F-11), accesso da Internet, streaming adattivo (HLS/DASH), sottotitoli, trascodifica al volo per dispositivi diversi. diff --git a/docs/02-architettura.md b/docs/02-architettura.md new file mode 100644 index 0000000..0358208 --- /dev/null +++ b/docs/02-architettura.md @@ -0,0 +1,91 @@ +# Architettura + +## Vista d'insieme + +``` +Browser ──HTTP──> PocketBase (Raspberry Pi, rete di casa, :8090; ADR 0013) + │ ├─ / → pb_public/ (frontend statico, ADR 0007) + │ ├─ /api/... → REST: categories, videos, progress + │ ├─ /api/files/ → video (Range supportato) + │ └─ pb_hooks/ → logica di ingest (ADR 0004) + └─