stripstream-librarian/PLAN.md

# Stripstream Librarian - Plan de Suivi MVP

## Objectif
Construire un serveur ultra performant pour indexer et servir des bibliotheques de livres/comics/BD (`cbz`, `cbr`, `pdf`) avec:
- API REST (librairies, livres, metadonnees, recherche, streaming pages),
- indexation incrementale,
- recherche full-text,
- admin UI (Rust SSR) pour gerer librairies/jobs/tokens,
- deploiement Docker Compose homelab.

## Decisions figees
- Backend/API: Rust (`axum`)
- Indexation: service Rust dedie (`indexer`)
- DB: PostgreSQL
- Recherche: Meilisearch
- Deploiement: Docker Compose
- Auth: token bootstrap env + tokens admin en DB (creables/revocables)
- Expiration tokens admin: aucune par defaut (revocation manuelle)
- Rendu PDF: a la volee
- CBR: extraction temporaire disque (`unrar-free`, commande `unrar`) + cleanup
- Formats pages: `webp`, `jpeg`, `png`

---

## Backlog executable (ordre recommande)

### T1 - Bootstrap monorepo Rust
- [x] Creer workspace Cargo
- [x] Creer crates/apps: `apps/api`, `apps/indexer`, `apps/admin-ui`, `crates/core`, `crates/parsers`
- [x] Config env centralisee + logging de base

**DoD:** Build des crates OK.

### T2 - Infra Docker Compose
- [x] Definir services `postgres`, `meilisearch`, `api`, `indexer`
- [x] Volumes persistants
- [x] Healthchecks

**DoD:** `docker compose up` demarre tout, services healthy.

### T3 - Schema DB + migrations
- [x] Tables: `libraries`, `books`, `book_files`, `index_jobs`, `api_tokens`
- [x] Index/contraintes (uniques, FK)
- [x] Scripts de migration

**DoD:** Migrations appliquees sans erreur, schema stable.

### T4 - Auth hybride
- [x] Middleware `Authorization: Bearer <token>`
- [x] Verif `API_BOOTSTRAP_TOKEN`
- [x] Verif tokens DB (hash Argon2id, non revoques/non expires)
- [x] MAJ `last_used_at`

**DoD:** Acces protege fonctionnel, tokens revoques refuses.

### T5 - API admin tokens
- [x] `POST /admin/tokens` (affichage secret une seule fois)
- [x] `GET /admin/tokens` (sans secret)
- [x] `DELETE /admin/tokens/:id` (revoke)

**DoD:** Flux creation/liste/revocation valide.

### T6 - CRUD librairies
- [x] `GET /libraries`
- [x] `POST /libraries`
- [x] `DELETE /libraries/:id`
- [x] Validation stricte des chemins (anti traversal)

**DoD:** Gestion librairies robuste et securisee.

### T7 - Jobs d'indexation
- [ ] Orchestration scan/rebuild
- [ ] `POST /index/rebuild`
- [ ] `GET /index/status`
- [ ] Persist statuts/erreurs dans `index_jobs`

**DoD:** Jobs tracables et relancables.

### T8 - Scan incremental
- [ ] Decouverte fichiers supportes
- [ ] Fingerprint (`size`, `mtime`, hash partiel)
- [ ] Upsert `book_files`
- [ ] Detection suppressions/renommages

**DoD:** Rescan = traitement des deltas uniquement.

### T9 - Parsing CBZ
- [ ] Lecture zip + ordre pages naturel
- [ ] Metadonnees de base + cover
- [ ] Gestion erreurs archive

**DoD:** Livres CBZ indexes correctement.

### T10 - Parsing CBR (temp disk)
- [ ] Extraction temp via `unrar`
- [ ] Ordonnancement pages
- [ ] Cleanup garanti (meme en erreur)

**DoD:** Pas de fuite temp, parsing stable.

### T11 - Parsing PDF
- [ ] Metadonnees (titre/auteur/pages)
- [ ] Preparation rendu page a la volee
- [ ] Gestion fichiers corrompus

**DoD:** PDF indexes et lisibles.

### T12 - API livres
- [ ] `GET /books` (filtres + curseur)
- [ ] `GET /books/:id`
- [ ] Contrat JSON propre et stable

**DoD:** Pagination/filtres fonctionnels.

### T13 - Recherche
- [ ] Projection vers Meilisearch
- [ ] `GET /search?q=...&library_id=...&type=...`
- [ ] Fuzzy + filtres

**DoD:** Recherche rapide et pertinente.

### T14 - Streaming pages multi-format
- [ ] `GET /books/:id/pages/:n`
- [ ] Query: `format=webp|jpeg|png`, `quality=1..100`, `width`
- [ ] Headers cache (`ETag`, `Cache-Control`)
- [ ] Validation stricte params

**DoD:** Pages servies correctement dans les 3 formats.

### T15 - Perf guards
- [ ] Cache LRU en memoire (cle: `book:page:format:quality:width`)
- [ ] Limite concurrence rendu PDF
- [ ] Timeouts et bornes (`width` max)

**DoD:** Service stable sous charge homelab.

### T16 - Admin UI Rust SSR
- [ ] Vue Libraries
- [ ] Vue Jobs
- [ ] Vue API Tokens (create/list/revoke)

**DoD:** Admin complet utilisable sans SPA lourde.

### T17 - Observabilite et hardening
- [ ] Logs structures `tracing`
- [ ] Metriques Prometheus
- [ ] Health/readiness endpoints
- [ ] Rate limiting leger

**DoD:** Diagnostics et exploitation simples.

### T18 - Validation MVP
- [ ] Tests d'integration API
- [ ] Smoke tests compose
- [ ] Bench p95/p99 basiques

**DoD:** Checklist MVP validee de bout en bout.

---

## Contrat API minimum (v1)
- `GET /libraries`
- `POST /libraries`
- `DELETE /libraries/:id`
- `GET /books`
- `GET /books/:id`
- `GET /search`
- `GET /books/:id/pages/:n`
- `POST /index/rebuild`
- `GET /index/status`
- `POST /admin/tokens`
- `GET /admin/tokens`
- `DELETE /admin/tokens/:id`

---

## Cibles perf MVP (homelab)
- `GET /books/:id` < 30 ms p95 (cache chaud)
- `GET /search` < 80 ms p95
- 1ere reponse `/pages/:n` < 200 ms p95 (hors PDF froid lourd)

---

## Risques connus et mitigation
- CBR heterogene -> isolation erreurs + logs detailles + retries limites
- PDF lourds CPU -> pool borne + timeout + cache
- Drift DB/Search -> indexation idempotente + job rebuild complet

---

## Suivi d'avancement
- [x] Lot 1: Fondations (T1 -> T6)
- [ ] Lot 2: Ingestion + Search (T7 -> T13)
- [ ] Lot 3: Lecture + UI + Hardening (T14 -> T18)

## Notes
- Scope token v1: `admin`, `read`
- Bootstrap token = break-glass (peut etre desactive plus tard)

## Journal
- 2026-03-05: `docker compose up -d --build` valide, stack complete en healthy (`postgres`, `meilisearch`, `api`, `indexer`, `admin-ui`).
- 2026-03-05: ajustements infra appliques pour demarrage stable (`unrar` -> `unrar-free`, image `rust:1-bookworm`, healthchecks `127.0.0.1`).