julienfroidefond/stripstream-librarian
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
stripstream-librarian/PLAN.md
Froidefond Julien 389d71b42f refactor: replace Meilisearch with PostgreSQL full-text search 
Remove Meilisearch dependency entirely. Search is now handled by
PostgreSQL ILIKE with pg_trgm indexes, joining series_metadata for
series-level authors. No external search engine needed.

- Replace search.rs Meilisearch HTTP calls with PostgreSQL queries
- Remove meili.rs from indexer, sync_meili call from job pipeline
- Remove MEILI_URL/MEILI_MASTER_KEY from config, state, env files
- Remove meilisearch service from docker-compose.yml
- Add migration 0027: drop sync_metadata, enable pg_trgm, add indexes
- Remove search resync button/endpoint (no longer needed)
- Update all documentation (CLAUDE.md, README.md, AGENTS.md, PLAN.md)

API contract unchanged — same SearchResponse shape returned.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 10:59:25 +01:00

278 lines
10 KiB
Markdown
Raw Permalink Blame History

# 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,
- backoffice web (Next.js) pour gerer librairies/jobs/tokens,
- deploiement Docker Compose homelab.
## Decisions figees
- Backend/API: Rust (`axum`)
- Indexation: service Rust dedie (`indexer`)
- DB: PostgreSQL
- Recherche: PostgreSQL full-text (ILIKE + pg_trgm)
- 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`
- Backoffice UI: Next.js (remplace Rust SSR)
---
## 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`, `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
- [x] Orchestration scan/rebuild
- [x] `POST /index/rebuild`
- [x] `GET /index/status`
- [x] Persist statuts/erreurs dans `index_jobs`
**DoD:** Jobs tracables et relancables.
### T8 - Scan incremental
- [x] Decouverte fichiers supportes
- [x] Fingerprint (`size`, `mtime`, hash partiel)
- [x] Upsert `book_files`
- [x] Detection suppressions/renommages
**DoD:** Rescan = traitement des deltas uniquement.
### T9 - Parsing CBZ
- [x] Lecture zip + ordre pages naturel
- [x] Metadonnees de base + cover
- [x] Gestion erreurs archive
**DoD:** Livres CBZ indexes correctement.
### T10 - Parsing CBR (temp disk)
- [x] Extraction temp via `unrar`
- [x] Ordonnancement pages
- [x] Cleanup garanti (meme en erreur)
**DoD:** Pas de fuite temp, parsing stable.
### T11 - Parsing PDF
- [x] Metadonnees (titre/auteur/pages)
- [x] Preparation rendu page a la volee
- [x] Gestion fichiers corrompus
**DoD:** PDF indexes et lisibles.
### T12 - API livres
- [x] `GET /books` (filtres + curseur)
- [x] `GET /books/:id`
- [x] Contrat JSON propre et stable
**DoD:** Pagination/filtres fonctionnels.
### T13 - Recherche
- [x] Recherche full-text PostgreSQL
- [x] `GET /search?q=...&library_id=...&type=...`
- [x] Fuzzy + filtres
**DoD:** Recherche rapide et pertinente.
### T14 - Streaming pages multi-format
- [x] `GET /books/:id/pages/:n`
- [x] Query: `format=webp|jpeg|png`, `quality=1..100`, `width`
- [x] Headers cache (`ETag`, `Cache-Control`)
- [x] Validation stricte params
**DoD:** Pages servies correctement dans les 3 formats.
### T15 - Perf guards
- [x] Cache LRU en memoire (cle: `book:page:format:quality:width`)
- [x] Limite concurrence rendu PDF
- [x] Timeouts et bornes (`width` max)
**DoD:** Service stable sous charge homelab.
### T16 - Backoffice Next.js
- [x] Bootstrap app Next.js (`apps/backoffice`)
- [x] Vue Libraries (folder selector, add/delete)
- [x] Vue Jobs (rebuild per library, cancel job)
- [x] Vue API Tokens (create/list/revoke)
- [x] Auth backoffice via token API
- [x] Theme switcher Light/Dark
- [x] Style aligne avec site officiel
**DoD:** Backoffice Next.js utilisable pour l'administration complete.
### T17 - Observabilite et hardening
- [x] Logs structures `tracing`
- [x] Metriques Prometheus
- [x] Health/readiness endpoints
- [x] Rate limiting leger
**DoD:** Diagnostics et exploitation simples.
### T18 - Validation MVP
- [ ] Tests d'integration API
- [x] Smoke tests compose
- [x] Bench p95/p99 basiques
**DoD:** Checklist MVP validee de bout en bout.
### T19 - Progression temps reel des jobs (Option 2 - stockage minimal) - [COMPLETE]
- [x] Table `index_job_errors` pour stocker les erreurs (job_id, file_path, error_message, created_at)
- [x] Endpoint polling `GET /index/jobs/:id` (remplace SSE pour compatibilite) avec progression temps reel
- [x] Indexer: stockage progression en DB (current_file, progress_percent, processed_files, total_files)
- [x] Backoffice: composant `JobProgress` avec barre de progression et pourcentage
- [x] Affichage du fichier en cours de traitement et compteur (traite/total)
- [x] Stats globales utilisees depuis `index_jobs.stats_json`
**DoD:** ✅ Barre de progression temps reel + erreurs stockees pour debug post-job.
### T20 - Header avec indicateur jobs - [COMPLETE]
- [x] Endpoint `GET /index/jobs/active` pour recuperer les jobs pending/running
- [x] Composant `JobsIndicator` dans le header avec badge compteur dynamique
- [x] Dropdown au clic affichant la liste des jobs actifs avec progression
- [x] Polling toutes les 5s pour mise a jour temps reel
- [x] Lien rapide vers la page jobs detaillee
**DoD:** ✅ Icone cliquable dans le header montrant les jobs en cours avec badge rouge.
### T21 - Bouton indexation sur libraries - [COMPLETE]
- [x] Boutons "Index" (incremental) et "Index Full" (rebuild complet) sur chaque ligne
- [x] Endpoint `POST /libraries/:id/scan` pour lancer le job
- [x] Support parametre `full: true` pour rebuild complet
- [x] Feedback visuel via revalidation Next.js
- [x] Type de job `full_rebuild` distinct du `rebuild` normal
**DoD:** ✅ Lancement d'indexation direct depuis la page libraries avec support full rebuild.
### T22 - Details enrichis des jobs - [COMPLETE]
- [x] Endpoint `GET /index/jobs/:id` avec statistiques completes
- [x] Endpoint `GET /index/jobs/:id/errors` avec liste des erreurs
- [x] Page detaillee `/jobs/[id]/page.tsx` avec:
- Timeline visuelle (Created → Started → Finished)
- Barre de progression avec pourcentage
- Stats: scanned, indexed, removed, errors
- Vitesse de traitement (fichiers/sec)
- Liste des erreurs detaillees
- Navigation retour vers la liste
- [x] Bouton "View" sur chaque ligne de job
- [x] Lien cliquable sur l'ID du job
**DoD:** ✅ Page job detaillee avec timeline, stats completes et navigation.
### T23 - Surveillance automatique des libraries - [PARTIEL]
- [x] Migration `0004_library_monitoring.sql`: colonnes `monitor_enabled`, `scan_mode`, `last_scan_at`, `next_scan_at`
- [x] Enum scan_mode: 'manual', 'hourly', 'daily', 'weekly' avec contrainte CHECK
- [ ] Checkbox "Enable monitoring" et select "Scan frequency" dans formulaire library
- [ ] Scheduler dans l'indexer (toutes les minutes) verifiant les libraries a scanner
- [x] Endpoint `POST /libraries/:id/scan` pour scan manuel declenche par API
- [ ] Badge "Auto" (vert) ou "Manual" (gris) dans la liste des libraries
- [ ] Prochain scan estime affiche dans les details de la library
**DoD:** ⚠️ Schema DB et endpoint API OK, UI et scheduler a implementer.
---
## Contrat API minimum (v1)
- `GET /libraries`
- `POST /libraries`
- `DELETE /libraries/:id`
- `POST /libraries/:id/scan` (T23)
- `GET /books`
- `GET /books/:id`
- `GET /search`
- `GET /books/:id/pages/:n`
- `POST /index/rebuild`
- `GET /index/status`
- `GET /index/jobs/active` (T20)
- `GET /index/jobs/:id/details` (T22)
- `GET /index/jobs/:id/files` (T22)
- `GET /index/jobs/:id/stream` (T19)
- `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)
- [x] Lot 2: Ingestion + Search (T7 -> T13)
- [x] Lot 3: Lecture + UI + Hardening (T14 -> T18)
- [x] Lot 4: Ameliorations Indexation (T19 -> T22) [COMPLETE PARTIELLEMENT]
- [ ] Lot 5: Optimisations et Polishing (T23 + ameliorations)
## 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`, `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`).
- 2026-03-05: ajout d'un service `migrate` dans Compose pour executer automatiquement `infra/migrations/0001_init.sql` au demarrage.
- 2026-03-05: Lot 2 termine (jobs, scan incremental, parsers `cbz/cbr/pdf`, API livres, recherche PostgreSQL).
- 2026-03-05: verification de bout en bout OK sur une librairie de test (`/libraries/demo`) avec indexation, listing `/books` et recherche `/search` (1 CBZ detecte).
- 2026-03-05: Lot 3 avancee: endpoint pages (`/books/:id/pages/:n`) actif avec cache LRU, ETag/Cache-Control, limite concurrence rendu et timeouts.
- 2026-03-05: hardening API: readiness expose sans auth via `route_layer`, metriques simples `/metrics`, rate limiting lecture (120 req/s).
- 2026-03-05: smoke + bench scripts corriges et verifies (`infra/smoke.sh`, `infra/bench.sh`).
- 2026-03-05: pivot backoffice valide: remplacement de l'admin UI Rust SSR par une app Next.js.
- 2026-03-05: backoffice Next.js implemente (`apps/backoffice`) avec branding neon base sur le logo, actions libraries/jobs/tokens, et integration Docker Compose.
- 2026-03-06: planification Lot 4 - ajout des taches T19-T23 pour ameliorations indexing (progression temps reel, indicateur header, bouton indexation, details jobs, surveillance auto libraries)
Reference in New Issue View Git Blame Copy Permalink