PLANS.md

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.