US04-01: Build and Export Rename Plans (#66)

photo_pipeline/api/app.py

@@ -22,6 +22,7 @@ from photo_pipeline.api.routes import (
     inventory,
     jobs,
     library,
+    renames,
     safety,
     thumbnails,
     workflow,
@@ -65,6 +66,7 @@ def create_app(config: Config | None = None) -> FastAPI:
     app.include_router(analysis.router, prefix="/api/v1")
     app.include_router(library.router, prefix="/api/v1")
     app.include_router(albums.router, prefix="/api/v1")
+    app.include_router(renames.router, prefix="/api/v1")
     # Static single-page app (hash-routed). Mounted last so /api/v1 wins.
     if FRONTEND_DIR.is_dir():
         app.mount("/app", StaticFiles(directory=FRONTEND_DIR, html=True), name="app")

photo_pipeline/api/routes/renames.py

@@ -0,0 +1,54 @@
+"""Rename plan API (US04-01): build, inspect, and export plans.
+
+Planning is read-only — it previews and validates but never touches the filesystem.
+Applying a plan is a later story, so there is deliberately no apply endpoint here.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from photo_pipeline.services.renames import RenameError, RenameService
+
+router = APIRouter(tags=["renames"])
+
+
+def _service(request: Request) -> RenameService:
+    return RenameService(
+        request.app.state.session_factory,
+        library_roots=tuple(request.app.state.config.library_roots),
+    )
+
+
+def _error(status: int, code: str, message: str) -> JSONResponse:
+    return JSONResponse(status_code=status, content={"error": {"code": code, "message": message}})
+
+
+@router.post("/rename-plans")
+def build_plan(request: Request):
+    try:
+        return _service(request).build_plan()
+    except RenameError as error:
+        return _error(422, "nothing_to_plan", str(error))
+
+
+@router.get("/rename-plans")
+def list_plans(request: Request) -> dict:
+    return _service(request).list_plans()
+
+
+@router.get("/rename-plans/{plan_id}")
+def get_plan(plan_id: str, request: Request):
+    plan = _service(request).get(plan_id)
+    if plan is None:
+        return _error(404, "not_found", f"unknown rename plan {plan_id}")
+    return plan
+
+
+@router.get("/rename-plans/{plan_id}/export")
+def export_plan(plan_id: str, request: Request):
+    try:
+        return _service(request).export(plan_id)
+    except RenameError as error:
+        return _error(404, "not_found", str(error))