feat(interfaces/web): Sprint A14-S35 — squelette FastAPI natif

Squelette FastAPI **natif** au nouveau monde, écrit pour consommer
directement les services applicatifs S17+ via DI explicite. Pas un
shim sur le legacy picarones.web.app — c'est une app neuve.

Le legacy reste exposé jusqu'au S46.

picarones/interfaces/web/app.py
-------------------------------
- WebAppState (frozen dataclass) : container immuable des services
injectés (workspace, registry, corpus, benchmark, orchestrator,
version).
- create_app(WebAppState) -> FastAPI : factory qui construit l'app
avec les services injectés. Pas de singleton global — chaque appel
produit une instance indépendante (utile pour les tests isolés).
- Endpoint GET /health : liveness probe, toujours 200 OK si l'app a
démarré (pas de dépendance aux services backends — détecte les
crashes d'app, pas les crashes transitoires).
- Endpoint GET /version : version du code + workspace_root + counts
de métriques/projecteurs (vérifie que le bootstrap a bien eu lieu).
- /api/docs et /api/redoc : OpenAPI/Swagger exposés.

Pas de routers métier en S35
-----------------------------
- Pas de middleware CSP/CSRF (S38 quand on servira HTML).
- Pas de mount static (S38).
- Pas d'endpoints corpus/benchmark/jobs (S36-S37).
- Pas de lifespan (services injectés déjà construits).

Le squelette est intentionnellement minimal — chaque sprint suivant
S36-S38 ajoute incrémentalement sans toucher à app.py.

Tests S35 dédiés (17 nouveaux)
------------------------------
- WebAppStateDataclass : frozen, defaults pour version.
- CreateApp : returns FastAPI instance, state attaché à
app.state.picarones, rejette non-WebAppState (TypeError), chaque
call produit instance indépendante, title/version corrects, /api/docs
et /api/redoc accessibles.
- HealthEndpoint : 200 OK avec {"status": "ok"}, schéma HealthResponse.
- VersionEndpoint : 200 OK avec workspace_root, n_metrics/n_projectors
> 0 (bootstrap par défaut), version reflète state, schéma
VersionResponse.
- SkeletonScope : pas de /api/corpus|benchmark|jobs en S35 (404),
pas de /static/* en S35 (S38).

Tests : 4748 passed, 11 skipped (vs 4731 avant : +17 S35).
Lint : ruff check picarones/ tests/ → All checks passed.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

README.md

@@ -396,7 +396,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4750 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4760 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when

picarones/interfaces/web/__init__.py

@@ -1,26 +1,34 @@
-"""FastAPI app — Sprint S21.
+"""Interface web FastAPI — Sprints S35-S38.
 
-Cible : nouvelle implémentation **mince** des routers.  Chaque
-endpoint = 5-15 lignes max : valide DTO Pydantic, appelle un
-service de ``app/``, retourne une réponse.
+Squelette FastAPI **natif** au nouveau monde, écrit pour consommer
+directement les services applicatifs du Sprint S17+ via DI explicite.
+**Pas un shim** sur le legacy ``picarones.web.app``.
 
-Sécurité durcie par défaut au S21 (cohérence avec les 6 P0 du S1) :
+Architecture
+------------
+- ``app.py`` (S35) : factory ``create_app(WebAppState)`` qui
+  produit une instance FastAPI consommant les services injectés.
+  Endpoints squelette ``/health`` et ``/version``.
+- (S36) routers/corpus.py : import ZIP, listing, validation.
+- (S36) routers/benchmark.py : démarrage/lecture d'un run.
+- (S37) routers/jobs.py : queue + persistance SQLite + cancellation.
+- (S38) ui.py : Jinja2 templates + static + i18n.
 
-- CSRF activé par défaut (plus de ``PICARONES_CSRF_REQUIRED``
-  opt-in).
-- CSP sans ``'unsafe-inline'`` (refactor JS pour supprimer les
-  ``onclick=`` inline).
-- Cookie ``Secure`` détecté automatiquement (header
-  ``X-Forwarded-Proto`` + liste de proxies de confiance).
-- Rate limit sur IP **réelle** (proxy chain validée), plus
-  d'``X-Forwarded-For`` aveugle.
-- Workspaces isolés par session via ``WorkspaceManager``.
-
-Le code de ``picarones.web`` reste en place jusqu'au S22 — au S21
-on construit la nouvelle SPA en parallèle, au S22 on bascule
-``picarones`` script entry et on supprime l'ancien ``web/``.
+Le legacy ``picarones.web.app`` reste exposé jusqu'au S46.
 """
 
 from __future__ import annotations
 
-__all__: list[str] = []
+from picarones.interfaces.web.app import (
+    HealthResponse,
+    VersionResponse,
+    WebAppState,
+    create_app,
+)
+
+__all__ = [
+    "HealthResponse",
+    "VersionResponse",
+    "WebAppState",
+    "create_app",
+]

picarones/interfaces/web/app.py

@@ -0,0 +1,179 @@
+"""``create_app`` — Sprint A14-S35.
+
+Squelette FastAPI du nouveau monde.  **Pas un shim** sur le legacy
+``picarones.web.app`` — c'est une app neuve, écrite pour consommer
+directement les services du Sprint S17+ (``BenchmarkService``,
+``RegistryService``, ``RunOrchestrator``, ``WorkspaceManager``,
+``CorpusService``).
+
+Le legacy ``picarones.web.app`` reste en place jusqu'au S46.
+
+Architecture
+------------
+- ``create_app(app_state) → FastAPI`` : factory qui construit l'app
+  avec les services injectés. Pas de singleton global — chaque
+  ``create_app`` produit une instance indépendante.
+- ``WebAppState`` : container immuable des services injectés
+  (services + workspace root + version).
+- Endpoint ``GET /health`` : liveness probe pour Docker / k8s.
+- Endpoint ``GET /version`` : version + flags (mode public, etc.).
+- Endpoints corpus/benchmark/jobs : ajoutés aux S36-S37 via routers
+  dédiés.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de middleware CSP/CSRF dans S35 — ajoutés au S38 quand on
+  servira des templates HTML (le squelette S35 est API-only).
+- Pas de lifespan (rien à initialiser au démarrage — les services
+  sont injectés déjà construits).
+- Pas de mount static (S38).
+- Pas de jobs queue (S37).
+
+Chaque sprint S36-S38 ajoute incrémentalement sans toucher au
+squelette : on monte des routers, on attache des middlewares, on
+mount des fichiers statiques.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from picarones.app.services import (
+    BenchmarkService,
+    CorpusService,
+    RegistryService,
+    RunOrchestrator,
+    WorkspaceManager,
+)
+
+
+@dataclass(frozen=True)
+class WebAppState:
+    """Container immuable des services injectés dans l'app web.
+
+    Attributes
+    ----------
+    workspace:
+        ``WorkspaceManager`` du run en cours.
+    registry:
+        ``RegistryService`` (registres de métriques + projecteurs
+        pré-bootstrap).
+    corpus:
+        ``CorpusService`` (import ZIP, détection patterns).
+    benchmark:
+        ``BenchmarkService`` (orchestration runner + vues +
+        persistance).
+    orchestrator:
+        ``RunOrchestrator`` (workflow YAML → bench → HTML report).
+    version:
+        Version du code Picarones à afficher dans
+        ``GET /version``.
+
+    Notes
+    -----
+    Frozen : aucun service ne change de référence après le démarrage
+    de l'app.  Pour reconstruire l'état (test isolé), créer une
+    nouvelle ``WebAppState``.
+    """
+
+    workspace: WorkspaceManager
+    registry: RegistryService
+    corpus: CorpusService
+    benchmark: BenchmarkService
+    orchestrator: RunOrchestrator
+    version: str = "1.0.0"
+
+
+class HealthResponse(BaseModel):
+    """Schéma JSON pour ``GET /health``."""
+
+    status: str = "ok"
+
+
+class VersionResponse(BaseModel):
+    """Schéma JSON pour ``GET /version``."""
+
+    version: str
+    workspace_root: str
+    n_metrics: int
+    n_projectors: int
+
+
+def create_app(state: WebAppState) -> FastAPI:
+    """Construit une instance FastAPI consommant l'``WebAppState``.
+
+    Pas de singleton global : chaque appel produit une nouvelle app
+    indépendante.  Permet aux tests d'instancier des apps avec des
+    services mockés sans interférence avec d'autres tests.
+
+    Parameters
+    ----------
+    state:
+        ``WebAppState`` immuable injectée dans tous les endpoints
+        via ``Request.app.state.picarones``.
+
+    Returns
+    -------
+    FastAPI
+        Instance prête à être lancée par ``uvicorn`` ou consommée
+        par ``TestClient``.
+    """
+    if not isinstance(state, WebAppState):
+        raise TypeError(
+            f"create_app : state doit être WebAppState, "
+            f"reçu {type(state).__name__}.",
+        )
+
+    app = FastAPI(
+        title="Picarones",
+        description=(
+            "Plateforme de benchmark OCR/HTR pour documents patrimoniaux. "
+            "API du nouveau monde (Sprint A14-S35)."
+        ),
+        version=state.version,
+        docs_url="/api/docs",
+        redoc_url="/api/redoc",
+    )
+
+    # On stocke l'état dans app.state.picarones pour permettre aux
+    # endpoints (S36+) d'y accéder via Request.app.state.picarones
+    # — namespace explicite pour ne pas collisionner avec d'autres
+    # extensions FastAPI.
+    app.state.picarones = state
+
+    # ──────────────────────────────────────────────────────────────
+    # Endpoints squelette (sondes santé/version)
+    # ──────────────────────────────────────────────────────────────
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health() -> HealthResponse:
+        """Liveness probe — toujours ``200 OK`` si l'app a démarré.
+
+        Pas de dépendance aux services backends : on veut détecter
+        un crash de l'app, pas un crash transitoire d'un service.
+        """
+        return HealthResponse(status="ok")
+
+    @app.get("/version", response_model=VersionResponse)
+    async def version() -> VersionResponse:
+        """Affiche la version du code et un compte rapide des
+        registres pour vérifier que le bootstrap a bien eu lieu."""
+        return VersionResponse(
+            version=state.version,
+            workspace_root=str(state.workspace.root),
+            n_metrics=len(state.registry.metrics),
+            n_projectors=len(state.registry.projectors),
+        )
+
+    return app
+
+
+__all__ = [
+    "HealthResponse",
+    "VersionResponse",
+    "WebAppState",
+    "create_app",
+]

tests/interfaces/web/test_sprint_a14_s35_web_app.py

@@ -0,0 +1,231 @@
+"""Sprint A14-S35 — squelette FastAPI ``interfaces/web``.
+
+Tests du squelette FastAPI natif qui consomme les services
+applicatifs du Sprint S17+.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from picarones.app.services import (
+    BenchmarkService,
+    CorpusService,
+    RegistryService,
+    RunOrchestrator,
+    WorkspaceManager,
+)
+from picarones.interfaces.web import (
+    HealthResponse,
+    VersionResponse,
+    WebAppState,
+    create_app,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────
+
+
+def _make_state(tmp_path: Path) -> WebAppState:
+    """Construit un ``WebAppState`` avec services réels (registres
+    bootstrappés, workspace temporaire)."""
+    workspace = WorkspaceManager(
+        base_dir=tmp_path,
+        session_id="test_session",
+    )
+    registry = RegistryService.bootstrap_defaults()
+
+    # Pour les tests S35 squelette, on n'a pas besoin de services
+    # complètement fonctionnels — des MagicMock conviennent puisque
+    # les endpoints squelette ne les invoquent pas.
+    corpus = MagicMock(spec=CorpusService)
+    benchmark = MagicMock(spec=BenchmarkService)
+    orchestrator = MagicMock(spec=RunOrchestrator)
+
+    return WebAppState(
+        workspace=workspace,
+        registry=registry,
+        corpus=corpus,
+        benchmark=benchmark,
+        orchestrator=orchestrator,
+        version="1.0.0-s35-test",
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# WebAppState dataclass
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestWebAppStateDataclass:
+    def test_frozen(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        with pytest.raises(Exception):  # FrozenInstanceError
+            state.version = "modified"  # type: ignore[misc]
+
+    def test_default_version(self, tmp_path: Path) -> None:
+        workspace = WorkspaceManager(base_dir=tmp_path, session_id="test")
+        registry = RegistryService.bootstrap_defaults()
+        state = WebAppState(
+            workspace=workspace,
+            registry=registry,
+            corpus=MagicMock(),
+            benchmark=MagicMock(),
+            orchestrator=MagicMock(),
+        )
+        assert state.version == "1.0.0"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# create_app factory
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestCreateApp:
+    def test_returns_fastapi_instance(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        assert isinstance(app, FastAPI)
+
+    def test_state_attached_to_app(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        assert app.state.picarones is state
+
+    def test_rejects_non_state_input(self) -> None:
+        with pytest.raises(TypeError, match="WebAppState"):
+            create_app("not a state")  # type: ignore[arg-type]
+
+    def test_each_call_yields_new_app(self, tmp_path: Path) -> None:
+        """Pas de singleton global — chaque create_app produit une
+        instance indépendante."""
+        state = _make_state(tmp_path)
+        app1 = create_app(state)
+        app2 = create_app(state)
+        assert app1 is not app2
+
+    def test_app_has_title_and_version(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        assert app.title == "Picarones"
+        assert app.version == state.version
+
+    def test_openapi_doc_endpoints_available(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        # /api/docs et /api/redoc doivent exister.
+        r_docs = client.get("/api/docs")
+        r_redoc = client.get("/api/redoc")
+        assert r_docs.status_code == 200
+        assert r_redoc.status_code == 200
+
+
+# ──────────────────────────────────────────────────────────────────────
+# /health endpoint
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestHealthEndpoint:
+    def test_health_returns_200_ok(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/health")
+        assert response.status_code == 200
+        body = response.json()
+        assert body == {"status": "ok"}
+
+    def test_health_response_schema(self, tmp_path: Path) -> None:
+        # Le schéma HealthResponse doit valider {"status": "ok"}.
+        h = HealthResponse(status="ok")
+        assert h.status == "ok"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# /version endpoint
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestVersionEndpoint:
+    def test_version_returns_200_ok(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/version")
+        assert response.status_code == 200
+
+    def test_version_includes_workspace_root(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/version")
+        body = response.json()
+        assert "workspace_root" in body
+        # Le root doit pointer dans tmp_path.
+        assert tmp_path.name in body["workspace_root"]
+
+    def test_version_includes_n_metrics_and_projectors(
+        self, tmp_path: Path,
+    ) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/version")
+        body = response.json()
+        # Bootstrap par défaut enregistre cer/wer/mer/wil + autres → > 0.
+        assert body["n_metrics"] > 0
+        assert body["n_projectors"] > 0
+
+    def test_version_string_matches_state(self, tmp_path: Path) -> None:
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/version")
+        body = response.json()
+        assert body["version"] == "1.0.0-s35-test"
+
+    def test_version_response_schema(self) -> None:
+        v = VersionResponse(
+            version="1.0.0",
+            workspace_root="/tmp/test",
+            n_metrics=5,
+            n_projectors=3,
+        )
+        assert v.version == "1.0.0"
+        assert v.n_metrics == 5
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Pas de routers métier en S35
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestSkeletonScope:
+    def test_no_corpus_endpoint_yet(self, tmp_path: Path) -> None:
+        """S35 ne contient pas encore les endpoints métier (S36+)."""
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        # Aucun endpoint corpus / benchmark / jobs n'est attendu en S35.
+        for path in ("/api/corpus", "/api/benchmark", "/api/jobs"):
+            response = client.get(path)
+            assert response.status_code == 404, (
+                f"Endpoint {path!r} ne devrait pas exister en S35 — "
+                "viendra en S36-S37."
+            )
+
+    def test_no_static_mount_yet(self, tmp_path: Path) -> None:
+        """S35 ne sert pas encore de fichiers statiques (S38)."""
+        state = _make_state(tmp_path)
+        app = create_app(state)
+        client = TestClient(app)
+        response = client.get("/static/css/main.css")
+        assert response.status_code == 404