101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# Novela 2.0 - Technical Plan
|
|
|
|
## Scope
|
|
Dit document beschrijft de technische uitvoering van de blauwdruk in implementeerbare stappen.
|
|
|
|
## Architectural Rules
|
|
- Bestand is source of truth.
|
|
- Database is snelle index.
|
|
- Schrijfacties: eerst bestand, dan DB.
|
|
- Lezen: primair uit DB, met scan/rescan voor recovery.
|
|
|
|
## Data Integrity Rules
|
|
- Alle child-tabellen refereren `library(filename)` met `ON DELETE CASCADE`.
|
|
- Verwijderen van een boek is een enkel `DELETE FROM library` na file-delete.
|
|
- Rename-flow moet `filename` synchroon aanpassen in:
|
|
- `library`
|
|
- `book_tags`
|
|
- `reading_progress`
|
|
- `reading_sessions`
|
|
- `library_cover_cache`
|
|
|
|
## Runtime Lifecycle
|
|
- Startup:
|
|
1. `init_pool()`
|
|
2. `run_migrations()`
|
|
3. routers mounten
|
|
- Shutdown:
|
|
1. `close_pool()`
|
|
|
|
## Module Responsibilities
|
|
- `db.py`: pool ownership + connection helpers.
|
|
- `migrations.py`: schema + seeds.
|
|
- `routers/library.py`: import/scan/delete/cover/home/stats.
|
|
- `routers/reader.py`: lezen + progress + metadata patch + epub editor endpoints.
|
|
- `routers/editor.py`: uiteindelijke dedicated editor routes (kan initieel delegaten).
|
|
- `routers/grabber.py`: scraper orchestration + credentials + SSE.
|
|
- `routers/backup.py`: Dropbox sync + pg dump + logging.
|
|
- `routers/settings.py`: break patterns + cleaning endpoints.
|
|
|
|
## Endpoint Contract Notes
|
|
- Alle file routes gebruiken veilige path-resolutie tegen traversal.
|
|
- Cover endpoint gedrag:
|
|
- cached eerst
|
|
- fallback raw extract
|
|
- anders 404
|
|
- Progress payload:
|
|
- EPUB: `{ cfi, progress }`
|
|
- PDF/CBR: `{ page, progress }`
|
|
|
|
## Backup Plan
|
|
- `POST /api/backup/run`:
|
|
- insert `running` in `backup_log`
|
|
- sync files naar Dropbox (incremental op mtime+size)
|
|
- draai `pg_dump` en upload `.sql`
|
|
- update `backup_log` naar `success`/`error`
|
|
- OAuth token opslag via `credentials` (`site='dropbox'`) en encrypted-at-rest (Fernet) in de database.
|
|
- Beheer via webinterface op `/credentials-manager` (site: `dropbox`, token in password veld).
|
|
- Legacy plaintext credentials worden automatisch gemigreerd naar encrypted bij uitlezen.
|
|
|
|
## Migration Plan from Current State
|
|
1. Behoud v1 stabiele modules (`epub.py`, `xhtml.py`, scrapers, templates/static).
|
|
2. Introduceer nieuwe routers zonder bestaande frontend te breken (compat routes waar nodig).
|
|
3. Schakel library root om naar `library/`.
|
|
4. Activeer PDF/CBR scan en reader paden.
|
|
5. Split editor-routes uit reader naar dedicated `editor.py`.
|
|
6. Volledige scrape->epub flow migreren naar `grabber.py`.
|
|
7. Backup volledig afronden (Dropbox + pg_dump).
|
|
|
|
## Test Matrix
|
|
- Import:
|
|
- EPUB met/zonder cover
|
|
- PDF 1+ pagina
|
|
- CBR/CBZ met images
|
|
- Reader:
|
|
- EPUB CFI save/load
|
|
- PDF page render + page progress
|
|
- CBR page render + page progress
|
|
- Metadata edit:
|
|
- rename path
|
|
- db references geupdate
|
|
- old row cleanup
|
|
- Delete:
|
|
- file weg
|
|
- lege dirs gepruned
|
|
- cascade records weg
|
|
- Break patterns:
|
|
- create/update/delete/enable
|
|
- Grabber:
|
|
- preload/debug
|
|
- convert job events
|
|
- Backup:
|
|
- status/history
|
|
- success/error logging
|
|
|
|
## Deployment Notes
|
|
- Docker image bouwt vanuit `containers/novela`.
|
|
- Stack uit `stack/stack.yml` met env uit `stack/novela.env`.
|
|
- `NOVELA_MASTER_KEY` is verplicht voor encrypt/decrypt van credentials in de database en moet stabiel blijven na initiele ingebruikname.
|
|
- Postgres volume persistent.
|
|
- Library mount persistent.
|