Spaces:
Sleeping
Sleeping
| # 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. | |