feat(backend): add publish readiness endpoint and enforce publish gate contract

add backend endpoint for publish readiness checks

enforce publish gate contract before version publication
make publish preconditions explicit and consistent for clients

backend/app/services/api_errors.py

@@ -1,39 +1,40 @@
-from __future__ import annotations
-
 from fastapi import HTTPException, status
 
 
-def raise_conflict(*, code: str, message: str, **extra) -> None:
-    detail = {
+def raise_conflict(*, code: str, message: str, details: dict | None = None) -> None:
+    payload = {
         "code": code,
         "message": message,
-        **extra,
     }
+    if details:
+        payload.update(details)
+
     raise HTTPException(
         status_code=status.HTTP_409_CONFLICT,
-        detail=detail,
+        detail=payload,
     )
 
 
-def raise_unprocessable(*, code: str, message: str, **extra) -> None:
-    detail = {
+def raise_unprocessable(*, code: str, message: str, details: dict | None = None) -> None:
+    payload = {
         "code": code,
         "message": message,
-        **extra,
     }
+    if details:
+        payload.update(details)
+
     raise HTTPException(
         status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-        detail=detail,
+        detail=payload,
     )
 
 
-def raise_not_found(*, code: str, message: str, **extra) -> None:
-    detail = {
-        "code": code,
-        "message": message,
-        **extra,
-    }
+def raise_publish_not_ready(*, reason: str, details: dict) -> None:
     raise HTTPException(
-        status_code=status.HTTP_404_NOT_FOUND,
-        detail=detail,
+        status_code=status.HTTP_409_CONFLICT,
+        detail={
+            "code": "publish_not_ready",
+            "message": reason,
+            "details": details,
+        },
     )