Add development plan in PLANS.md

This document outlines the development plan divided into short, testable batches suitable for a workflow with Codex. Each batch is designed to be handled in a separate branch or worktree.

PLANS.md

@@ -0,0 +1,334 @@
+# PLANS.md
+
+## But
+
+Ce document découpe le développement en lots courts, testables et adaptés à un workflow avec Codex.
+
+Chaque lot doit pouvoir être traité dans une branche ou worktree séparé.
+
+---
+
+## Vue d’ensemble
+
+Ordre recommandé :
+
+1. Lot 0 — cadrage repo
+2. Lot 1 — backend socle
+3. Lot 2 — frontend socle
+4. Lot 3 — intégration Mirador minimale
+5. Lot 4 — import manuel + manifest-by-url
+6. Lot 5 — connecteur Gallica
+7. Lot 6 — connecteurs Bodleian + Europeana
+8. Lot 7 — ranking, cache, partial failures, provenance
+9. Lot 8 — couche MCP
+10. Lot 9 — Docker + Hugging Face Spaces
+11. Lot 10 — hardening final
+
+---
+
+## Lot 0 — cadrage repo
+
+### Objectif
+Poser la structure de travail, les conventions et la documentation de référence.
+
+### Livrables
+- `AGENTS.md`
+- `docs/specs.md`
+- `docs/mvp-scope.md`
+- `docs/architecture.md`
+- `docs/acceptance-checklist.md`
+- `README.md` minimal
+- arborescence vide du monorepo
+
+### Critères de validation
+- l’arborescence cible est claire ;
+- les conventions sont écrites ;
+- les lots suivants peuvent être lancés sans ambiguïté.
+
+---
+
+## Lot 1 — backend socle
+
+### Objectif
+Créer le noyau backend stable avant les connecteurs réels.
+
+### Inclus
+- FastAPI bootable
+- config minimale
+- modèles Pydantic
+- `BaseConnector`
+- `ConnectorRegistry`
+- `SearchOrchestrator`
+- endpoints :
+  - `/api/health`
+  - `/api/sources`
+  - `/api/search`
+  - `/api/item/{id}`
+  - `/api/resolve-manifest`
+  - `/api/import`
+- connecteur mock de démonstration
+- tests unitaires et intégration de base
+
+### Exclu
+- vrais connecteurs complexes
+- logique MCP
+- cache avancé
+
+### Critères de validation
+- l’API démarre ;
+- les modèles sont stables ;
+- les routes répondent ;
+- les succès partiels sont prévus ;
+- le frontend peut déjà se brancher dessus.
+
+---
+
+## Lot 2 — frontend socle
+
+### Objectif
+Mettre en place l’interface de base branchée sur le backend socle.
+
+### Inclus
+- React + TypeScript
+- Tailwind
+- navigation principale :
+  - Recherche
+  - Lecture
+  - Import
+  - Sources
+  - À propos
+- store global
+- barre de recherche
+- filtres basiques
+- galerie de résultats
+- composant `ResultCard`
+- gestion loading / empty / error
+- page Sources
+- branchement API backend
+
+### Exclu
+- connecteurs réels complexes
+- ranking avancé
+- features post-MVP
+
+### Critères de validation
+- le frontend build ;
+- une recherche mock affiche des cartes ;
+- la navigation est stable ;
+- l’ouverture vers Lecture est préparée.
+
+---
+
+## Lot 3 — intégration Mirador minimale
+
+### Objectif
+Intégrer Mirador proprement comme viewer de lecture.
+
+### Inclus
+- composant `MiradorWorkspace`
+- ouverture d’un manifest
+- ouverture de plusieurs manifests
+- mode simple / compare
+- stockage léger des manifests ouverts
+- lien entre résultats sélectionnés et page Lecture
+
+### Exclu
+- logique de recherche dans Mirador
+- persistance avancée de session
+
+### Critères de validation
+- un manifest URL peut être ouvert ;
+- plusieurs manifests peuvent être affichés ;
+- la sélection depuis la galerie alimente bien Mirador.
+
+---
+
+## Lot 4 — import manuel + connecteur manifest-by-url
+
+### Objectif
+Créer le chemin le plus robuste de démonstration fonctionnelle.
+
+### Inclus
+- page Import
+- validation d’URL
+- détection manifest direct
+- heuristiques simples de notice -> manifest
+- connecteur `manifest_by_url`
+- tests de sécurité basiques
+- tests d’import
+
+### Critères de validation
+- coller une URL de manifest ouvre Mirador ;
+- l’API `/api/import` fonctionne ;
+- les URLs invalides sont rejetées proprement.
+
+---
+
+## Lot 5 — connecteur Gallica
+
+### Objectif
+Ajouter la première source réelle prioritaire.
+
+### Inclus
+- connecteur Gallica
+- mapping vers `NormalizedItem`
+- recherche simple
+- `get_item`
+- `resolve_manifest`
+- mode mock ou fixtures
+- tests unitaires du mapping
+- tests d’intégration ciblés
+
+### Critères de validation
+- une requête simple renvoie des résultats Gallica normalisés ;
+- les manifests Gallica sont résolus quand disponible ;
+- l’échec Gallica n’empêche pas la réponse globale.
+
+---
+
+## Lot 6 — connecteurs Bodleian + Europeana
+
+### Objectif
+Porter la fédération à trois sources réelles minimum.
+
+### Inclus
+- connecteur Bodleian
+- connecteur Europeana
+- normalisation cohérente
+- capacités déclaratives
+- modes mock ou fixtures
+- tests unitaires par connecteur
+
+### Critères de validation
+- au moins trois sources fonctionnent ;
+- `/api/sources` reflète correctement les capacités ;
+- la galerie fusionne les résultats sans casser l’UI.
+
+---
+
+## Lot 7 — ranking, cache, partial failures, provenance
+
+### Objectif
+Améliorer la robustesse et la lisibilité des résultats.
+
+### Inclus
+- score simple agrégé
+- déduplication légère non agressive
+- cache mémoire
+- journal de provenance
+- temps de réponse par source
+- `partial_failures`
+- timeouts configurables
+
+### Critères de validation
+- les temps de réponse sont mieux maîtrisés ;
+- les erreurs sont visibles mais non bloquantes ;
+- les résultats sont mieux ordonnés ;
+- la provenance est consultable.
+
+---
+
+## Lot 8 — MCP
+
+### Objectif
+Exposer les fonctions métier via MCP sans créer de deuxième backend.
+
+### Inclus
+- outils :
+  - `search_items`
+  - `get_item`
+  - `resolve_manifest`
+  - `open_in_mirador`
+  - `list_sources`
+- documentation minimale
+- exemple client
+- tests de non-régression si simple
+
+### Exclu
+- logique métier dupliquée
+- nouveaux modèles indépendants de REST
+
+### Critères de validation
+- MCP appelle les mêmes services que REST ;
+- les réponses sont cohérentes ;
+- aucun fork de logique n’apparaît.
+
+---
+
+## Lot 9 — Docker + Hugging Face Spaces
+
+### Objectif
+Rendre le projet réellement déployable.
+
+### Inclus
+- Dockerfile
+- `.env.example`
+- config dev/prod
+- scripts de démarrage
+- instructions Hugging Face Spaces
+- healthcheck de conteneur
+
+### Critères de validation
+- build Docker OK ;
+- démarrage local OK ;
+- documentation de déploiement claire.
+
+---
+
+## Lot 10 — hardening final
+
+### Objectif
+Nettoyer et stabiliser avant démonstration.
+
+### Inclus
+- revue architecture
+- nettoyage dépendances
+- vérification typage
+- vérification tests
+- audit SSRF/import
+- polissage UX minimal
+- README final
+- checklist MVP finale
+
+### Critères de validation
+- le MVP est démontrable ;
+- la doc est lisible ;
+- la structure est propre ;
+- les limites connues sont documentées.
+
+---
+
+## Stratégie Git recommandée
+
+### Branches ou worktrees
+- `feat/repo-scaffold`
+- `feat/backend-core`
+- `feat/frontend-shell`
+- `feat/mirador`
+- `feat/import-manifest`
+- `feat/connector-gallica`
+- `feat/connectors-bodleian-europeana`
+- `feat/ranking-cache-observability`
+- `feat/mcp`
+- `feat/deploy-hf`
+- `chore/hardening`
+
+### Règle
+Un lot majeur = une branche ou un worktree.
+
+Ne pas mélanger :
+- frontend shell et connecteurs réels dans la même branche ;
+- MCP et refonte backend dans la même branche ;
+- déploiement et refactoring profond dans la même branche.
+
+---
+
+## Definition of done par lot
+
+Avant merge, vérifier :
+- code compilable ;
+- tests pertinents passants ;
+- docs mises à jour ;
+- pas de duplication ;
+- pas de débordement de périmètre ;
+- limites restantes listées noir sur blanc.