feat(sprint4-session-a): API FastAPI — structure de base + endpoints lecture et export

Structure créée :
- app/config.py : Settings Pydantic lues depuis l'environnement (base_url,
data_dir, database_url, clés IA R06) — sans dépendance externe
- app/models/database.py : engine SQLAlchemy async (aiosqlite), Base
déclarative, get_db() dépendance FastAPI
- app/models/corpus.py : CorpusModel, ManuscriptModel, PageModel
(SQLAlchemy 2.0 Mapped, cascade delete-orphan)
- app/main.py : FastAPI + CORS ouvert + lifespan (create_all SQLite)
+ inclusion des 4 routers sous /api/v1/

Routers (R10 — tous sous /api/v1/) :
- api/v1/corpora.py : GET /corpora, POST /corpora (slug unique → 409),
GET /corpora/{id}, DELETE /corpora/{id}
- api/v1/pages.py : GET /pages/{id}, GET /pages/{id}/master-json (R02),
GET /pages/{id}/layers (couches détectées depuis master.json)
- api/v1/export.py : GET /manuscripts/{id}/iiif-manifest,
GET /manuscripts/{id}/mets, GET /pages/{id}/alto,
GET /manuscripts/{id}/export.zip (manifest + mets + alto par page)
- api/v1/profiles.py : GET /profiles, GET /profiles/{id}

Tests (63 nouveaux) :
- test_api_corpora.py : CRUD complet, 409, 422 Pydantic auto, isolation
- test_api_pages.py : 200/404, master-json via Path mock, couches
- test_api_export.py : IIIF, METS, ALTO, ZIP (contenu vérifié)
- conftest_api.py : fixtures db_session (SQLite in-memory) + async_client

Total : 396 tests passent, 3 skippés (intégration réseau).

https://claude.ai/code/session_018woyEHc8HG2th7V4ewJ4Kg

backend/app/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

backend/app/api/v1/__init__.py

@@ -0,0 +1 @@
+"""API v1 package."""

backend/app/api/v1/corpora.py

@@ -0,0 +1,99 @@
+"""
+Endpoints CRUD pour les corpus (R10 — préfixe /api/v1/).
+
+GET    /api/v1/corpora
+POST   /api/v1/corpora
+GET    /api/v1/corpora/{corpus_id}
+DELETE /api/v1/corpora/{corpus_id}
+
+Règle : toute logique métier est dans les services, jamais dans les routers.
+"""
+# 1. stdlib
+import uuid
+from datetime import datetime, timezone
+
+# 2. third-party
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app.models.corpus import CorpusModel
+from app.models.database import get_db
+
+router = APIRouter(prefix="/corpora", tags=["corpora"])
+
+
+# ── Schémas de requête / réponse ─────────────────────────────────────────────
+
+class CorpusCreate(BaseModel):
+    slug: str
+    title: str
+    profile_id: str
+
+
+class CorpusResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    slug: str
+    title: str
+    profile_id: str
+    created_at: datetime
+    updated_at: datetime
+
+
+# ── Endpoints ────────────────────────────────────────────────────────────────
+
+@router.get("", response_model=list[CorpusResponse])
+async def list_corpora(db: AsyncSession = Depends(get_db)) -> list[CorpusModel]:
+    """Retourne tous les corpus enregistrés."""
+    result = await db.execute(select(CorpusModel))
+    return list(result.scalars().all())
+
+
+@router.post("", response_model=CorpusResponse, status_code=201)
+async def create_corpus(
+    body: CorpusCreate, db: AsyncSession = Depends(get_db)
+) -> CorpusModel:
+    """Crée un nouveau corpus. Le slug doit être unique."""
+    # Vérifier unicité du slug
+    existing = await db.execute(
+        select(CorpusModel).where(CorpusModel.slug == body.slug)
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(status_code=409, detail=f"Slug «{body.slug}» déjà utilisé")
+
+    now = datetime.now(timezone.utc)
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()),
+        slug=body.slug,
+        title=body.title,
+        profile_id=body.profile_id,
+        created_at=now,
+        updated_at=now,
+    )
+    db.add(corpus)
+    await db.commit()
+    await db.refresh(corpus)
+    return corpus
+
+
+@router.get("/{corpus_id}", response_model=CorpusResponse)
+async def get_corpus(corpus_id: str, db: AsyncSession = Depends(get_db)) -> CorpusModel:
+    """Retourne un corpus par son id."""
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+    return corpus
+
+
+@router.delete("/{corpus_id}", status_code=204)
+async def delete_corpus(corpus_id: str, db: AsyncSession = Depends(get_db)) -> None:
+    """Supprime un corpus (cascade sur les manuscrits et pages associés)."""
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+    await db.delete(corpus)
+    await db.commit()

backend/app/api/v1/export.py

@@ -0,0 +1,218 @@
+"""
+Endpoints d'export documentaire (R10 — préfixe /api/v1/).
+
+GET  /api/v1/manuscripts/{manuscript_id}/iiif-manifest  → JSON
+GET  /api/v1/manuscripts/{manuscript_id}/mets           → XML
+GET  /api/v1/pages/{page_id}/alto                       → XML
+GET  /api/v1/manuscripts/{manuscript_id}/export.zip     → ZIP
+
+Règle (R02) : toutes les sorties sont générées depuis les PageMasters
+(master.json), jamais depuis les réponses brutes de l'IA.
+"""
+# 1. stdlib
+import io
+import json
+import logging
+import zipfile
+from pathlib import Path
+
+# 2. third-party
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response, StreamingResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app import config as _config_module
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from app.models.database import get_db
+from app.schemas.page_master import PageMaster
+from app.services.export.alto import generate_alto
+from app.services.export.iiif import generate_manifest
+from app.services.export.mets import generate_mets
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["export"])
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _load_manuscript_with_masters(
+    manuscript_id: str,
+    db: AsyncSession,
+) -> tuple[ManuscriptModel, CorpusModel, list[PageMaster]]:
+    """Charge un manuscrit, son corpus et tous ses PageMasters.
+
+    Raises:
+        HTTPException 404: si le manuscrit ou son corpus est introuvable.
+        HTTPException 404: si aucun master.json n'est disponible.
+    """
+    manuscript = await db.get(ManuscriptModel, manuscript_id)
+    if manuscript is None:
+        raise HTTPException(status_code=404, detail="Manuscrit introuvable")
+
+    corpus = await db.get(CorpusModel, manuscript.corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+
+    # Pages dans l'ordre de séquence
+    result = await db.execute(
+        select(PageModel)
+        .where(PageModel.manuscript_id == manuscript_id)
+        .order_by(PageModel.sequence)
+    )
+    pages = list(result.scalars().all())
+
+    masters: list[PageMaster] = []
+    for page in pages:
+        master = _read_master_json(corpus.slug, page.id)
+        if master is not None:
+            masters.append(master)
+
+    if not masters:
+        raise HTTPException(
+            status_code=404,
+            detail="Aucun master.json disponible pour ce manuscrit",
+        )
+
+    return manuscript, corpus, masters
+
+
+def _read_master_json(corpus_slug: str, page_id: str) -> PageMaster | None:
+    """Lit le master.json d'une page depuis data/. Retourne None si absent."""
+    path = (
+        _config_module.settings.data_dir
+        / "corpora"
+        / corpus_slug
+        / "pages"
+        / page_id
+        / "master.json"
+    )
+    if not path.exists():
+        return None
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    return PageMaster.model_validate(raw)
+
+
+def _build_manuscript_meta(
+    manuscript: ManuscriptModel, corpus: CorpusModel
+) -> dict:
+    return {
+        "manuscript_id": manuscript.id,
+        "label": manuscript.title,
+        "corpus_slug": corpus.slug,
+        "shelfmark": manuscript.shelfmark,
+        "date_label": manuscript.date_label,
+    }
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.get("/manuscripts/{manuscript_id}/iiif-manifest")
+async def get_iiif_manifest(
+    manuscript_id: str, db: AsyncSession = Depends(get_db)
+) -> dict:
+    """Génère et retourne le Manifest IIIF 3.0 du manuscrit (R02)."""
+    manuscript, corpus, masters = await _load_manuscript_with_masters(
+        manuscript_id, db
+    )
+    meta = _build_manuscript_meta(manuscript, corpus)
+    manifest = generate_manifest(
+        masters, meta, _config_module.settings.base_url
+    )
+    logger.info(
+        "Manifest IIIF servi",
+        extra={"manuscript_id": manuscript_id, "pages": len(masters)},
+    )
+    return manifest
+
+
+@router.get("/manuscripts/{manuscript_id}/mets")
+async def get_mets(
+    manuscript_id: str, db: AsyncSession = Depends(get_db)
+) -> Response:
+    """Génère et retourne le METS XML du manuscrit (R02)."""
+    manuscript, corpus, masters = await _load_manuscript_with_masters(
+        manuscript_id, db
+    )
+    meta = _build_manuscript_meta(manuscript, corpus)
+    mets_xml = generate_mets(masters, meta)
+    return Response(
+        content=mets_xml,
+        media_type="application/xml; charset=utf-8",
+    )
+
+
+@router.get("/pages/{page_id}/alto")
+async def get_alto(page_id: str, db: AsyncSession = Depends(get_db)) -> Response:
+    """Génère et retourne l'ALTO XML d'une page (R02)."""
+    page = await db.get(PageModel, page_id)
+    if page is None:
+        raise HTTPException(status_code=404, detail="Page introuvable")
+
+    manuscript = await db.get(ManuscriptModel, page.manuscript_id)
+    corpus = await db.get(CorpusModel, manuscript.corpus_id)
+
+    master = _read_master_json(corpus.slug, page_id)
+    if master is None:
+        raise HTTPException(
+            status_code=404,
+            detail="master.json introuvable — la page n'a pas encore été analysée",
+        )
+
+    alto_xml = generate_alto(master)
+    return Response(
+        content=alto_xml,
+        media_type="application/xml; charset=utf-8",
+    )
+
+
+@router.get("/manuscripts/{manuscript_id}/export.zip")
+async def get_export_zip(
+    manuscript_id: str, db: AsyncSession = Depends(get_db)
+) -> StreamingResponse:
+    """Génère et retourne un ZIP contenant manifest.json + mets.xml + alto par page.
+
+    Structure du ZIP :
+      manifest.json
+      mets.xml
+      alto/{page_id}.xml
+    """
+    manuscript, corpus, masters = await _load_manuscript_with_masters(
+        manuscript_id, db
+    )
+    meta = _build_manuscript_meta(manuscript, corpus)
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        # manifest.json
+        manifest = generate_manifest(
+            masters, meta, _config_module.settings.base_url
+        )
+        zf.writestr(
+            "manifest.json",
+            json.dumps(manifest, ensure_ascii=False, indent=2),
+        )
+
+        # mets.xml
+        mets_xml = generate_mets(masters, meta)
+        zf.writestr("mets.xml", mets_xml)
+
+        # alto/{page_id}.xml
+        for master in masters:
+            alto_xml = generate_alto(master)
+            zf.writestr(f"alto/{master.page_id}.xml", alto_xml)
+
+    buf.seek(0)
+
+    filename = f"{manuscript_id}.zip"
+    logger.info(
+        "Export ZIP généré",
+        extra={"manuscript_id": manuscript_id, "pages": len(masters)},
+    )
+    return StreamingResponse(
+        buf,
+        media_type="application/zip",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )

backend/app/api/v1/pages.py

@@ -0,0 +1,203 @@
+"""
+Endpoints lecture des pages et de leur master.json (R10 — préfixe /api/v1/).
+
+GET  /api/v1/pages/{page_id}
+GET  /api/v1/pages/{page_id}/master-json
+GET  /api/v1/pages/{page_id}/layers
+
+Règle (R02) : le master.json est la source canonique. Ces endpoints le lisent
+depuis data/ — ils ne reconstruisent jamais une réponse depuis d'autres sources.
+"""
+# 1. stdlib
+import json
+import logging
+from pathlib import Path
+
+# 2. third-party
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app import config as _config_module
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from app.models.database import get_db
+from app.schemas.annotation import LayerStatus
+from app.schemas.corpus_profile import LayerType
+from app.schemas.page_master import PageMaster
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/pages", tags=["pages"])
+
+
+# ── Schémas de réponse ────────────────────────────────────────────────────────
+
+class PageResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    manuscript_id: str
+    folio_label: str
+    sequence: int
+    image_master_path: str | None
+    processing_status: str
+    confidence_summary: float | None
+
+
+class LayerInfo(BaseModel):
+    layer_type: str
+    status: str
+    has_content: bool
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _load_master(
+    page: PageModel,
+    db: AsyncSession,
+) -> PageMaster | None:
+    """Lit et valide le master.json d'une page depuis data/.
+
+    Retourne None si le fichier n'existe pas.
+    """
+    manuscript = await db.get(ManuscriptModel, page.manuscript_id)
+    if manuscript is None:
+        return None
+    corpus = await db.get(CorpusModel, manuscript.corpus_id)
+    if corpus is None:
+        return None
+
+    master_path = (
+        _config_module.settings.data_dir
+        / "corpora"
+        / corpus.slug
+        / "pages"
+        / page.id
+        / "master.json"
+    )
+    if not master_path.exists():
+        return None
+
+    raw = json.loads(master_path.read_text(encoding="utf-8"))
+    return PageMaster.model_validate(raw)
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.get("/{page_id}", response_model=PageResponse)
+async def get_page(page_id: str, db: AsyncSession = Depends(get_db)) -> PageModel:
+    """Retourne les métadonnées BDD d'une page."""
+    page = await db.get(PageModel, page_id)
+    if page is None:
+        raise HTTPException(status_code=404, detail="Page introuvable")
+    return page
+
+
+@router.get("/{page_id}/master-json")
+async def get_master_json(
+    page_id: str, db: AsyncSession = Depends(get_db)
+) -> dict:
+    """Retourne le PageMaster validé par Pydantic (source canonique R02)."""
+    page = await db.get(PageModel, page_id)
+    if page is None:
+        raise HTTPException(status_code=404, detail="Page introuvable")
+
+    master = await _load_master(page, db)
+    if master is None:
+        raise HTTPException(
+            status_code=404,
+            detail="master.json introuvable — la page n'a pas encore été analysée",
+        )
+
+    return master.model_dump(mode="json")
+
+
+@router.get("/{page_id}/layers", response_model=list[LayerInfo])
+async def get_page_layers(
+    page_id: str, db: AsyncSession = Depends(get_db)
+) -> list[LayerInfo]:
+    """Liste les couches disponibles dans le master.json de la page.
+
+    Une couche est présente si le champ correspondant est non-null dans le JSON.
+    """
+    page = await db.get(PageModel, page_id)
+    if page is None:
+        raise HTTPException(status_code=404, detail="Page introuvable")
+
+    master = await _load_master(page, db)
+    if master is None:
+        raise HTTPException(
+            status_code=404,
+            detail="master.json introuvable — la page n'a pas encore été analysée",
+        )
+
+    layers: list[LayerInfo] = []
+
+    # Couches toujours présentes après analyse primaire
+    layers.append(
+        LayerInfo(
+            layer_type=LayerType.IMAGE.value,
+            status=LayerStatus.DONE.value,
+            has_content=bool(master.image),
+        )
+    )
+
+    if master.ocr is not None:
+        layers.append(
+            LayerInfo(
+                layer_type=LayerType.OCR_DIPLOMATIC.value,
+                status=LayerStatus.DONE.value,
+                has_content=bool(master.ocr.diplomatic_text),
+            )
+        )
+
+    if master.translation is not None:
+        if master.translation.fr:
+            layers.append(
+                LayerInfo(
+                    layer_type=LayerType.TRANSLATION_FR.value,
+                    status=LayerStatus.DONE.value,
+                    has_content=True,
+                )
+            )
+        if master.translation.en:
+            layers.append(
+                LayerInfo(
+                    layer_type=LayerType.TRANSLATION_EN.value,
+                    status=LayerStatus.DONE.value,
+                    has_content=True,
+                )
+            )
+
+    if master.summary is not None:
+        layers.append(
+            LayerInfo(
+                layer_type=LayerType.SUMMARY.value,
+                status=LayerStatus.DONE.value,
+                has_content=bool(master.summary),
+            )
+        )
+
+    if master.commentary is not None:
+        if master.commentary.scholarly:
+            layers.append(
+                LayerInfo(
+                    layer_type=LayerType.SCHOLARLY_COMMENTARY.value,
+                    status=LayerStatus.DONE.value,
+                    has_content=True,
+                )
+            )
+        if master.commentary.public:
+            layers.append(
+                LayerInfo(
+                    layer_type=LayerType.PUBLIC_COMMENTARY.value,
+                    status=LayerStatus.DONE.value,
+                    has_content=True,
+                )
+            )
+
+    logger.info(
+        "Couches listées",
+        extra={"page_id": page_id, "count": len(layers)},
+    )
+    return layers

backend/app/api/v1/profiles.py

@@ -0,0 +1,63 @@
+"""
+Endpoints de lecture des profils de corpus (R10 — préfixe /api/v1/).
+
+GET  /api/v1/profiles
+GET  /api/v1/profiles/{profile_id}
+
+Les profils sont des fichiers JSON dans profiles/ (racine du dépôt).
+Ils sont validés par CorpusProfile avant d'être retournés.
+"""
+# 1. stdlib
+import json
+import logging
+from pathlib import Path
+
+# 2. third-party
+from fastapi import APIRouter, HTTPException
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.corpus_profile import CorpusProfile
+
+logger = logging.getLogger(__name__)
+
+# Répertoire des profils — relatif à la racine du dépôt
+# (identique au chemin utilisé dans test_profiles.py)
+_PROFILES_DIR = Path(__file__).parent.parent.parent.parent.parent / "profiles"
+
+router = APIRouter(prefix="/profiles", tags=["profiles"])
+
+
+def _load_profile(path: Path) -> CorpusProfile | None:
+    """Charge et valide un fichier de profil JSON. Retourne None si invalide."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return CorpusProfile.model_validate(data)
+    except (json.JSONDecodeError, ValidationError) as exc:
+        logger.warning("Profil invalide ignoré", extra={"path": str(path), "error": str(exc)})
+        return None
+
+
+@router.get("", response_model=list[dict])
+async def list_profiles() -> list[dict]:
+    """Retourne tous les profils valides du dossier profiles/."""
+    if not _PROFILES_DIR.is_dir():
+        return []
+    profiles = []
+    for path in sorted(_PROFILES_DIR.glob("*.json")):
+        profile = _load_profile(path)
+        if profile is not None:
+            profiles.append(profile.model_dump())
+    return profiles
+
+
+@router.get("/{profile_id}", response_model=dict)
+async def get_profile(profile_id: str) -> dict:
+    """Retourne un profil par son id (nom du fichier sans extension)."""
+    path = _PROFILES_DIR / f"{profile_id}.json"
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="Profil introuvable")
+    profile = _load_profile(path)
+    if profile is None:
+        raise HTTPException(status_code=422, detail="Profil invalide")
+    return profile.model_dump()

backend/app/config.py

@@ -0,0 +1,53 @@
+"""
+Configuration globale de la plateforme, chargée depuis les variables d'environnement.
+
+Équivalent fonctionnel de pydantic-settings sans dépendance externe :
+  - les valeurs sont lues depuis os.environ au moment de l'instanciation
+  - l'objet `settings` est importé partout dans l'application
+  - dans les tests : monkeypatch.setattr(config, "settings", ...) pour surcharger
+"""
+# 1. stdlib
+import os
+from pathlib import Path
+
+# 2. third-party
+from pydantic import BaseModel, ConfigDict
+
+
+class Settings(BaseModel):
+    """Paramètres d'application lus depuis les variables d'environnement.
+
+    Toutes les clés API sont optionnelles (None si non configurées).
+    Elles ne sont jamais loguées ni exportées (R06).
+    """
+
+    model_config = ConfigDict(frozen=False)
+
+    # ── Serveur ──────────────────────────────────────────────────────────────
+    base_url: str = "http://localhost:8000"
+    data_dir: Path = Path("data")
+
+    # ── Base de données ───────────────────────────────────────────────────────
+    database_url: str = "sqlite+aiosqlite:///./scriptorium.db"
+
+    # ── Fournisseurs IA (R06 — clés depuis l'environnement uniquement) ────────
+    google_ai_studio_api_key: str | None = None
+    vertex_api_key: str | None = None
+    vertex_service_account_json: str | None = None
+
+
+def _load_settings() -> Settings:
+    """Lit les variables d'environnement et construit l'objet Settings."""
+    return Settings(
+        base_url=os.getenv("BASE_URL", "http://localhost:8000"),
+        data_dir=Path(os.getenv("DATA_DIR", "data")),
+        database_url=os.getenv(
+            "DATABASE_URL", "sqlite+aiosqlite:///./scriptorium.db"
+        ),
+        google_ai_studio_api_key=os.getenv("GOOGLE_AI_STUDIO_API_KEY"),
+        vertex_api_key=os.getenv("VERTEX_API_KEY"),
+        vertex_service_account_json=os.getenv("VERTEX_SERVICE_ACCOUNT_JSON"),
+    )
+
+
+settings: Settings = _load_settings()

backend/app/main.py

@@ -0,0 +1,57 @@
+"""
+Application FastAPI — point d'entrée de Scriptorium AI.
+
+Tous les endpoints sont sous /api/v1/ (R10).
+CORS ouvert pour le développement local (origins=["*"]).
+La BDD SQLite est créée automatiquement au démarrage (lifespan).
+"""
+# 1. stdlib
+import logging
+from contextlib import asynccontextmanager
+
+# 2. third-party
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+# 3. local — on importe les modèles pour que Base.metadata les connaisse
+import app.models  # noqa: F401  (enregistrement des modèles SQLAlchemy)
+from app.api.v1 import corpora, export, pages, profiles
+from app.models.database import Base, engine
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(application: FastAPI):
+    """Crée les tables SQLite au démarrage, libère l'engine à l'arrêt."""
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    logger.info("Tables SQLite initialisées")
+    yield
+    await engine.dispose()
+    logger.info("Engine SQLite fermé")
+
+
+app = FastAPI(
+    title="Scriptorium AI",
+    description="Plateforme générique de génération d'éditions savantes augmentées",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# ── CORS (dev : tous les origines autorisés) ──────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routers (préfixe /api/v1/ — R10) ─────────────────────────────────────────
+_V1_PREFIX = "/api/v1"
+
+app.include_router(corpora.router, prefix=_V1_PREFIX)
+app.include_router(pages.router, prefix=_V1_PREFIX)
+app.include_router(export.router, prefix=_V1_PREFIX)
+app.include_router(profiles.router, prefix=_V1_PREFIX)

backend/app/models/__init__.py

@@ -0,0 +1,7 @@
+"""
+Modèles SQLAlchemy — importés ici pour que Base.metadata les connaisse
+au moment de la création des tables (Base.metadata.create_all).
+"""
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+
+__all__ = ["CorpusModel", "ManuscriptModel", "PageModel"]

backend/app/models/corpus.py

@@ -0,0 +1,77 @@
+"""
+Modèles SQLAlchemy 2.0 — tables Corpus, Manuscript, Page.
+
+Ces modèles représentent la couche de persistance (BDD).
+Ils NE se substituent PAS aux schémas Pydantic (source canonique des types).
+"""
+# 1. stdlib
+from datetime import datetime, timezone
+
+# 2. third-party
+from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+# 3. local
+from app.models.database import Base
+
+
+class CorpusModel(Base):
+    """Un corpus regroupe un ou plusieurs manuscrits sous un même profil."""
+
+    __tablename__ = "corpora"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    slug: Mapped[str] = mapped_column(String, unique=True, nullable=False, index=True)
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    profile_id: Mapped[str] = mapped_column(String, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+    manuscripts: Mapped[list["ManuscriptModel"]] = relationship(
+        back_populates="corpus", cascade="all, delete-orphan"
+    )
+
+
+class ManuscriptModel(Base):
+    """Un manuscrit appartient à un corpus et contient des pages."""
+
+    __tablename__ = "manuscripts"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    corpus_id: Mapped[str] = mapped_column(
+        String, ForeignKey("corpora.id"), nullable=False, index=True
+    )
+    shelfmark: Mapped[str | None] = mapped_column(String, nullable=True)
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    date_label: Mapped[str | None] = mapped_column(String, nullable=True)
+    total_pages: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+
+    corpus: Mapped["CorpusModel"] = relationship(back_populates="manuscripts")
+    pages: Mapped[list["PageModel"]] = relationship(
+        back_populates="manuscript", cascade="all, delete-orphan"
+    )
+
+
+class PageModel(Base):
+    """Une page appartient à un manuscrit.
+
+    processing_status suit le cycle de vie défini en CLAUDE.md §10 :
+      CREATED → INGESTING → INGESTED → PREPARED → ANALYZED → LAYERED
+      → EXPORTED → VALIDATED → ERROR
+    """
+
+    __tablename__ = "pages"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    manuscript_id: Mapped[str] = mapped_column(
+        String, ForeignKey("manuscripts.id"), nullable=False, index=True
+    )
+    folio_label: Mapped[str] = mapped_column(String, nullable=False)
+    sequence: Mapped[int] = mapped_column(Integer, nullable=False)
+    image_master_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+    processing_status: Mapped[str] = mapped_column(
+        String, nullable=False, default="CREATED"
+    )
+    confidence_summary: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    manuscript: Mapped["ManuscriptModel"] = relationship(back_populates="pages")

backend/app/models/database.py

@@ -0,0 +1,46 @@
+"""
+Engine SQLAlchemy async (aiosqlite) et session factory.
+
+Utilisation dans les endpoints FastAPI :
+    async def my_endpoint(db: AsyncSession = Depends(get_db)):
+        ...
+
+Les tables sont créées au démarrage de l'application (voir main.py lifespan).
+"""
+# 1. stdlib
+import logging
+
+# 2. third-party
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+# 3. local
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    connect_args={"check_same_thread": False},
+)
+
+async_session_factory = async_sessionmaker(
+    engine,
+    expire_on_commit=False,
+    class_=AsyncSession,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db():
+    """Dépendance FastAPI — injecte une AsyncSession par requête."""
+    async with async_session_factory() as session:
+        yield session

backend/tests/conftest_api.py

@@ -0,0 +1,56 @@
+"""
+Fixtures partagées pour les tests d'API FastAPI (Sprint 4 — Session A).
+
+Usage dans les fichiers de test :
+    from tests.conftest_api import async_client, db_session  # noqa: F401
+
+Stratégie :
+  - BDD SQLite en mémoire (":memory:") — isolation totale entre tests
+  - Dependency override de `get_db` pour injecter la session de test
+  - `httpx.AsyncClient` + `ASGITransport` pour simuler des requêtes HTTP
+"""
+# 1. stdlib
+import pytest
+import pytest_asyncio
+
+# 2. third-party
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+# 3. local
+import app.models  # noqa: F401 — enregistrement des modèles dans Base.metadata
+from app.models.database import Base, get_db
+
+_TEST_DB_URL = "sqlite+aiosqlite:///:memory:"
+
+
+@pytest_asyncio.fixture
+async def db_session():
+    """Session AsyncSession sur une BDD SQLite en mémoire."""
+    test_engine = create_async_engine(_TEST_DB_URL, echo=False)
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+    async with session_factory() as session:
+        yield session
+
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await test_engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def async_client(db_session: AsyncSession):
+    """AsyncClient HTTP connecté à l'app FastAPI, avec BDD de test injectée."""
+    from app.main import app
+
+    async def _override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = _override_get_db
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        yield client
+    app.dependency_overrides.clear()

backend/tests/test_api_corpora.py

@@ -0,0 +1,208 @@
+"""
+Tests des endpoints CRUD /api/v1/corpora (Sprint 4 — Session A).
+
+Vérifie :
+- GET  /api/v1/corpora → liste vide puis liste peuplée
+- POST /api/v1/corpora → 201 + corps de réponse complet
+- POST /api/v1/corpora (slug dupliqué) → 409
+- GET  /api/v1/corpora/{id} → 200 ou 404
+- DELETE /api/v1/corpora/{id} → 204 ou 404
+- Champs manquants dans le POST body → 422 automatique Pydantic
+"""
+# 1. stdlib
+import pytest
+
+# 3. local
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_CORPUS_PAYLOAD = {
+    "slug": "beatus-lat8878",
+    "title": "Beatus de Saint-Sever",
+    "profile_id": "medieval-illuminated",
+}
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/corpora
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_list_corpora_empty(async_client):
+    response = await async_client.get("/api/v1/corpora")
+    assert response.status_code == 200
+    assert response.json() == []
+
+
+@pytest.mark.asyncio
+async def test_list_corpora_after_create(async_client):
+    await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    response = await async_client.get("/api/v1/corpora")
+    assert response.status_code == 200
+    corpora = response.json()
+    assert len(corpora) == 1
+    assert corpora[0]["slug"] == "beatus-lat8878"
+
+
+@pytest.mark.asyncio
+async def test_list_corpora_multiple(async_client):
+    await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    await async_client.post(
+        "/api/v1/corpora",
+        json={"slug": "grandes-chroniques", "title": "Grandes Chroniques", "profile_id": "medieval-textual"},
+    )
+    response = await async_client.get("/api/v1/corpora")
+    assert len(response.json()) == 2
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/corpora
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_create_corpus_status_201(async_client):
+    response = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    assert response.status_code == 201
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_response_fields(async_client):
+    response = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    data = response.json()
+    assert "id" in data
+    assert data["slug"] == "beatus-lat8878"
+    assert data["title"] == "Beatus de Saint-Sever"
+    assert data["profile_id"] == "medieval-illuminated"
+    assert "created_at" in data
+    assert "updated_at" in data
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_id_is_uuid(async_client):
+    response = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = response.json()["id"]
+    # UUID v4 — 36 caractères avec tirets
+    assert len(corpus_id) == 36
+    assert corpus_id.count("-") == 4
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_duplicate_slug_409(async_client):
+    await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    response = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    assert response.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_missing_slug_422(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora", json={"title": "X", "profile_id": "medieval-illuminated"}
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_missing_title_422(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora", json={"slug": "x", "profile_id": "medieval-illuminated"}
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_create_corpus_missing_profile_id_422(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora", json={"slug": "x", "title": "X"}
+    )
+    assert response.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/corpora/{id}
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_corpus_ok(async_client):
+    create_resp = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = create_resp.json()["id"]
+
+    response = await async_client.get(f"/api/v1/corpora/{corpus_id}")
+    assert response.status_code == 200
+    assert response.json()["id"] == corpus_id
+
+
+@pytest.mark.asyncio
+async def test_get_corpus_fields(async_client):
+    create_resp = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = create_resp.json()["id"]
+    data = (await async_client.get(f"/api/v1/corpora/{corpus_id}")).json()
+
+    assert data["slug"] == "beatus-lat8878"
+    assert data["title"] == "Beatus de Saint-Sever"
+    assert data["profile_id"] == "medieval-illuminated"
+
+
+@pytest.mark.asyncio
+async def test_get_corpus_not_found(async_client):
+    response = await async_client.get("/api/v1/corpora/nonexistent-id")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_corpus_not_found_detail(async_client):
+    response = await async_client.get("/api/v1/corpora/unknown")
+    assert "introuvable" in response.json()["detail"].lower()
+
+
+# ---------------------------------------------------------------------------
+# DELETE /api/v1/corpora/{id}
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_delete_corpus_204(async_client):
+    create_resp = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = create_resp.json()["id"]
+
+    response = await async_client.delete(f"/api/v1/corpora/{corpus_id}")
+    assert response.status_code == 204
+
+
+@pytest.mark.asyncio
+async def test_delete_corpus_disappears_from_list(async_client):
+    create_resp = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = create_resp.json()["id"]
+
+    await async_client.delete(f"/api/v1/corpora/{corpus_id}")
+    list_resp = await async_client.get("/api/v1/corpora")
+    assert list_resp.json() == []
+
+
+@pytest.mark.asyncio
+async def test_delete_corpus_makes_get_404(async_client):
+    create_resp = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    corpus_id = create_resp.json()["id"]
+
+    await async_client.delete(f"/api/v1/corpora/{corpus_id}")
+    get_resp = await async_client.get(f"/api/v1/corpora/{corpus_id}")
+    assert get_resp.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_corpus_not_found(async_client):
+    response = await async_client.delete("/api/v1/corpora/nonexistent")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_only_target_corpus(async_client):
+    """Supprimer un corpus ne supprime pas les autres."""
+    r1 = await async_client.post("/api/v1/corpora", json=_CORPUS_PAYLOAD)
+    r2 = await async_client.post(
+        "/api/v1/corpora",
+        json={"slug": "other", "title": "Other", "profile_id": "medieval-textual"},
+    )
+    await async_client.delete(f"/api/v1/corpora/{r1.json()['id']}")
+
+    list_resp = await async_client.get("/api/v1/corpora")
+    remaining = list_resp.json()
+    assert len(remaining) == 1
+    assert remaining[0]["id"] == r2.json()["id"]

backend/tests/test_api_export.py

@@ -0,0 +1,385 @@
+"""
+Tests des endpoints d'export /api/v1/ (Sprint 4 — Session A).
+
+Stratégie :
+  - BDD en mémoire avec corpus / manuscrit / pages créés directement
+  - master.json mockés via monkeypatch sur Path.exists + Path.read_text
+  - Vérifie : 200, 404, type de contenu, structure JSON/XML/ZIP
+
+Tests :
+- GET /api/v1/manuscripts/{id}/iiif-manifest → JSON IIIF 3.0 ou 404
+- GET /api/v1/manuscripts/{id}/mets          → XML ou 404
+- GET /api/v1/pages/{id}/alto               → XML ou 404
+- GET /api/v1/manuscripts/{id}/export.zip   → ZIP ou 404
+"""
+# 1. stdlib
+import io
+import json
+import uuid
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+# 2. third-party
+import pytest
+
+# 3. local
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_NOW = datetime.now(timezone.utc)
+_IIIF_CONTEXT = "http://iiif.io/api/presentation/3/context.json"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+async def _populate_db(db_session, n_pages: int = 2):
+    """Crée corpus + manuscrit + n pages dans la BDD de test."""
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()),
+        slug="test-ms",
+        title="Test Corpus",
+        profile_id="medieval-illuminated",
+        created_at=_NOW,
+        updated_at=_NOW,
+    )
+    db_session.add(corpus)
+
+    ms = ManuscriptModel(
+        id=str(uuid.uuid4()),
+        corpus_id=corpus.id,
+        title="Test Manuscript",
+        shelfmark="Latin 0001",
+        date_label="XIIe siècle",
+        total_pages=n_pages,
+    )
+    db_session.add(ms)
+
+    pages = []
+    for i in range(1, n_pages + 1):
+        p = PageModel(
+            id=f"test-ms-f{i:03d}r",
+            manuscript_id=ms.id,
+            folio_label=f"f{i:03d}r",
+            sequence=i,
+            image_master_path=f"/data/master/f{i:03d}r.tif",
+            processing_status="ANALYZED",
+        )
+        db_session.add(p)
+        pages.append(p)
+
+    await db_session.commit()
+    return corpus, ms, pages
+
+
+def _make_master_json(page_id: str, folio_label: str, sequence: int) -> str:
+    return json.dumps({
+        "schema_version": "1.0",
+        "page_id": page_id,
+        "corpus_profile": "medieval-illuminated",
+        "manuscript_id": "test-ms",
+        "folio_label": folio_label,
+        "sequence": sequence,
+        "image": {
+            "original_url": f"https://example.com/{page_id}.jpg",
+            "derivative_web": f"/data/deriv/{page_id}.jpg",
+            "thumbnail": f"/data/thumb/{page_id}.jpg",
+            "width": 1500,
+            "height": 2000,
+        },
+        "layout": {"regions": []},
+        "ocr": {
+            "diplomatic_text": "Text content",
+            "blocks": [],
+            "lines": [],
+            "language": "la",
+            "confidence": 0.9,
+            "uncertain_segments": [],
+        },
+        "editorial": {
+            "status": "machine_draft",
+            "validated": False,
+            "validated_by": None,
+            "version": 1,
+            "notes": [],
+        },
+    })
+
+
+def _mock_master_files(monkeypatch, pages):
+    """Patche Path.exists / Path.read_text pour simuler les master.json."""
+    master_data = {
+        p.id: _make_master_json(p.id, p.folio_label, p.sequence)
+        for p in pages
+    }
+
+    def fake_exists(self: Path) -> bool:
+        return any(p_id in str(self) for p_id in master_data)
+
+    def fake_read_text(self: Path, **kwargs) -> str:
+        for p_id, data in master_data.items():
+            if p_id in str(self):
+                return data
+        raise FileNotFoundError(str(self))
+
+    monkeypatch.setattr(Path, "exists", fake_exists)
+    monkeypatch.setattr(Path, "read_text", fake_read_text)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/manuscripts/{id}/iiif-manifest
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_not_found(async_client):
+    response = await async_client.get("/api/v1/manuscripts/unknown/iiif-manifest")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_no_master_files(async_client, db_session, monkeypatch):
+    _, ms, _ = await _populate_db(db_session, n_pages=1)
+    monkeypatch.setattr(Path, "exists", lambda self: False)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_ok(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_context(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    data = (await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")).json()
+    assert data["@context"] == _IIIF_CONTEXT
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_type(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    data = (await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")).json()
+    assert data["type"] == "Manifest"
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_canvas_count(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    data = (await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")).json()
+    assert len(data["items"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_iiif_manifest_id_contains_base_url(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    data = (await async_client.get(f"/api/v1/manuscripts/{ms.id}/iiif-manifest")).json()
+    assert data["id"].startswith("http")
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/manuscripts/{id}/mets
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_mets_not_found(async_client):
+    response = await async_client.get("/api/v1/manuscripts/unknown/mets")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_mets_ok(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/mets")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_mets_content_type_xml(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/mets")
+    assert "xml" in response.headers["content-type"]
+
+
+@pytest.mark.asyncio
+async def test_mets_body_starts_with_xml(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/mets")
+    assert response.text.lstrip().startswith("<?xml")
+
+
+@pytest.mark.asyncio
+async def test_mets_contains_mets_root(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    text = (await async_client.get(f"/api/v1/manuscripts/{ms.id}/mets")).text
+    assert "mets" in text.lower()
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/pages/{id}/alto
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_alto_not_found(async_client):
+    response = await async_client.get("/api/v1/pages/unknown-page/alto")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_alto_no_master_file(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    monkeypatch.setattr(Path, "exists", lambda self: False)
+
+    response = await async_client.get(f"/api/v1/pages/{pages[0].id}/alto")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_alto_ok(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/pages/{pages[0].id}/alto")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_alto_content_type_xml(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/pages/{pages[0].id}/alto")
+    assert "xml" in response.headers["content-type"]
+
+
+@pytest.mark.asyncio
+async def test_alto_body_is_xml(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/pages/{pages[0].id}/alto")
+    assert response.text.lstrip().startswith("<?xml")
+
+
+@pytest.mark.asyncio
+async def test_alto_contains_alto_element(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    text = (await async_client.get(f"/api/v1/pages/{pages[0].id}/alto")).text
+    assert "alto" in text.lower() or "ALTO" in text
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/manuscripts/{id}/export.zip
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_export_zip_not_found(async_client):
+    response = await async_client.get("/api/v1/manuscripts/unknown/export.zip")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_export_zip_no_master_files(async_client, db_session, monkeypatch):
+    _, ms, _ = await _populate_db(db_session, n_pages=1)
+    monkeypatch.setattr(Path, "exists", lambda self: False)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_export_zip_ok(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_export_zip_content_type(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    assert "zip" in response.headers["content-type"]
+
+
+@pytest.mark.asyncio
+async def test_export_zip_contains_manifest(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    with zipfile.ZipFile(io.BytesIO(response.content)) as zf:
+        assert "manifest.json" in zf.namelist()
+
+
+@pytest.mark.asyncio
+async def test_export_zip_contains_mets(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    with zipfile.ZipFile(io.BytesIO(response.content)) as zf:
+        assert "mets.xml" in zf.namelist()
+
+
+@pytest.mark.asyncio
+async def test_export_zip_contains_alto_per_page(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=2)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    with zipfile.ZipFile(io.BytesIO(response.content)) as zf:
+        names = zf.namelist()
+        alto_files = [n for n in names if n.startswith("alto/")]
+        assert len(alto_files) == 2
+
+
+@pytest.mark.asyncio
+async def test_export_zip_manifest_is_valid_json(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    with zipfile.ZipFile(io.BytesIO(response.content)) as zf:
+        manifest_data = json.loads(zf.read("manifest.json").decode("utf-8"))
+        assert manifest_data["@context"] == _IIIF_CONTEXT
+        assert manifest_data["type"] == "Manifest"
+
+
+@pytest.mark.asyncio
+async def test_export_zip_content_disposition(async_client, db_session, monkeypatch):
+    _, ms, pages = await _populate_db(db_session, n_pages=1)
+    _mock_master_files(monkeypatch, pages)
+
+    response = await async_client.get(f"/api/v1/manuscripts/{ms.id}/export.zip")
+    cd = response.headers.get("content-disposition", "")
+    assert "attachment" in cd
+    assert ".zip" in cd

backend/tests/test_api_pages.py

@@ -0,0 +1,337 @@
+"""
+Tests des endpoints /api/v1/pages/{id} (Sprint 4 — Session A).
+
+Stratégie :
+  - Données BDD créées directement via la session SQLAlchemy (pas via l'API)
+  - master.json mockés via monkeypatch sur les méthodes de Path
+  - Vérifie : 200, 404, structure du master.json, liste des couches
+
+Tests :
+- GET /api/v1/pages/{id}                → 200 ou 404
+- GET /api/v1/pages/{id}/master-json    → 200 (mock), 404 (pas de fichier)
+- GET /api/v1/pages/{id}/layers         → liste des couches disponibles
+"""
+# 1. stdlib
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# 2. third-party
+import pytest
+
+# 3. local
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_NOW = datetime.now(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Helpers — création de données de test en BDD
+# ---------------------------------------------------------------------------
+
+async def _create_corpus(db_session, slug="test-corpus"):
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()),
+        slug=slug,
+        title="Test Corpus",
+        profile_id="medieval-illuminated",
+        created_at=_NOW,
+        updated_at=_NOW,
+    )
+    db_session.add(corpus)
+    await db_session.commit()
+    await db_session.refresh(corpus)
+    return corpus
+
+
+async def _create_manuscript(db_session, corpus_id, ms_id=None):
+    ms = ManuscriptModel(
+        id=ms_id or str(uuid.uuid4()),
+        corpus_id=corpus_id,
+        title="Test Manuscript",
+        shelfmark="Latin 8878",
+        date_label="XIe siècle",
+        total_pages=1,
+    )
+    db_session.add(ms)
+    await db_session.commit()
+    await db_session.refresh(ms)
+    return ms
+
+
+async def _create_page(db_session, manuscript_id, page_id=None):
+    page = PageModel(
+        id=page_id or str(uuid.uuid4()),
+        manuscript_id=manuscript_id,
+        folio_label="f001r",
+        sequence=1,
+        image_master_path="/data/master/f001r.tif",
+        processing_status="ANALYZED",
+        confidence_summary=0.87,
+    )
+    db_session.add(page)
+    await db_session.commit()
+    await db_session.refresh(page)
+    return page
+
+
+def _make_master_json(page_id: str, corpus_profile: str = "medieval-illuminated") -> str:
+    data = {
+        "schema_version": "1.0",
+        "page_id": page_id,
+        "corpus_profile": corpus_profile,
+        "manuscript_id": "ms-test",
+        "folio_label": "f001r",
+        "sequence": 1,
+        "image": {
+            "original_url": "https://example.com/f001r.jpg",
+            "derivative_web": "/data/deriv/f001r.jpg",
+            "thumbnail": "/data/thumb/f001r.jpg",
+            "width": 1500,
+            "height": 2000,
+        },
+        "layout": {"regions": []},
+        "ocr": {
+            "diplomatic_text": "Incipit liber primus",
+            "blocks": [],
+            "lines": [],
+            "language": "la",
+            "confidence": 0.87,
+            "uncertain_segments": [],
+        },
+        "translation": {"fr": "Ici commence le premier livre", "en": ""},
+        "summary": {"short": "Prologue", "detailed": "Le prologue du commentaire"},
+        "commentary": {
+            "public": "Ce folio ouvre l'œuvre",
+            "scholarly": "Analyse paléographique détaillée",
+            "claims": [],
+        },
+        "editorial": {
+            "status": "machine_draft",
+            "validated": False,
+            "validated_by": None,
+            "version": 1,
+            "notes": [],
+        },
+    }
+    return json.dumps(data)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/pages/{id}
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_page_not_found(async_client):
+    response = await async_client.get("/api/v1/pages/nonexistent-page")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_page_not_found_detail(async_client):
+    response = await async_client.get("/api/v1/pages/unknown")
+    assert "introuvable" in response.json()["detail"].lower()
+
+
+@pytest.mark.asyncio
+async def test_get_page_ok(async_client, db_session):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    response = await async_client.get(f"/api/v1/pages/{page.id}")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_get_page_fields(async_client, db_session):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    data = (await async_client.get(f"/api/v1/pages/{page.id}")).json()
+    assert data["id"] == page.id
+    assert data["manuscript_id"] == ms.id
+    assert data["folio_label"] == "f001r"
+    assert data["sequence"] == 1
+    assert data["processing_status"] == "ANALYZED"
+    assert data["confidence_summary"] == pytest.approx(0.87)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/pages/{id}/master-json
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_master_json_page_not_found(async_client):
+    response = await async_client.get("/api/v1/pages/unknown/master-json")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_master_json_file_not_found(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    # Simule l'absence du fichier
+    monkeypatch.setattr(Path, "exists", lambda self: False)
+
+    response = await async_client.get(f"/api/v1/pages/{page.id}/master-json")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_master_json_ok(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    master_data = _make_master_json(page.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: master_data)
+
+    response = await async_client.get(f"/api/v1/pages/{page.id}/master-json")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_master_json_contains_page_id(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    master_data = _make_master_json(page.id)
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: master_data)
+
+    data = (await async_client.get(f"/api/v1/pages/{page.id}/master-json")).json()
+    assert data["page_id"] == page.id
+
+
+@pytest.mark.asyncio
+async def test_master_json_schema_version(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    master_data = _make_master_json(page.id)
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: master_data)
+
+    data = (await async_client.get(f"/api/v1/pages/{page.id}/master-json")).json()
+    assert data["schema_version"] == "1.0"
+
+
+@pytest.mark.asyncio
+async def test_master_json_ocr_present(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    master_data = _make_master_json(page.id)
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: master_data)
+
+    data = (await async_client.get(f"/api/v1/pages/{page.id}/master-json")).json()
+    assert data["ocr"]["diplomatic_text"] == "Incipit liber primus"
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/pages/{id}/layers
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_layers_page_not_found(async_client):
+    response = await async_client.get("/api/v1/pages/unknown/layers")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_layers_file_not_found(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: False)
+
+    response = await async_client.get(f"/api/v1/pages/{page.id}/layers")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_layers_ok_is_list(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: _make_master_json(page.id))
+
+    response = await async_client.get(f"/api/v1/pages/{page.id}/layers")
+    assert response.status_code == 200
+    layers = response.json()
+    assert isinstance(layers, list)
+    assert len(layers) > 0
+
+
+@pytest.mark.asyncio
+async def test_layers_contains_image(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: _make_master_json(page.id))
+
+    layers = (await async_client.get(f"/api/v1/pages/{page.id}/layers")).json()
+    types = [l["layer_type"] for l in layers]
+    assert "image" in types
+
+
+@pytest.mark.asyncio
+async def test_layers_contains_ocr(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: _make_master_json(page.id))
+
+    layers = (await async_client.get(f"/api/v1/pages/{page.id}/layers")).json()
+    types = [l["layer_type"] for l in layers]
+    assert "ocr_diplomatic" in types
+
+
+@pytest.mark.asyncio
+async def test_layers_contains_translation(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: _make_master_json(page.id))
+
+    layers = (await async_client.get(f"/api/v1/pages/{page.id}/layers")).json()
+    types = [l["layer_type"] for l in layers]
+    assert "translation_fr" in types
+
+
+@pytest.mark.asyncio
+async def test_layers_have_status(async_client, db_session, monkeypatch):
+    corpus = await _create_corpus(db_session)
+    ms = await _create_manuscript(db_session, corpus.id)
+    page = await _create_page(db_session, ms.id)
+
+    monkeypatch.setattr(Path, "exists", lambda self: True)
+    monkeypatch.setattr(Path, "read_text", lambda self, **kw: _make_master_json(page.id))
+
+    layers = (await async_client.get(f"/api/v1/pages/{page.id}/layers")).json()
+    for layer in layers:
+        assert "layer_type" in layer
+        assert "status" in layer
+        assert "has_content" in layer