feat(05-09): PATCH /documents/{id} endpoint + cloud-aware Celery re-analyze

- Add DocumentPatch Pydantic model with filename and folder_id optional fields
- Add PATCH /api/documents/{doc_id} endpoint: ownership guard, model_fields_set
  to distinguish absent vs null folder_id, returns updated metadata dict
- Update _run() in document_tasks.py to use get_storage_backend_for_document
  for non-MinIO backends instead of hardcoded MinIO path
- CloudConnectionError caught in cloud path: returns extract_failed status
- Update test to use pure unit mocks (no PostgreSQL) for _run() cloud routing
- All 3 plan tests pass; 23 test_cloud.py tests pass

backend/api/documents.py

@@ -69,6 +69,19 @@ class UploadUrlRequest(BaseModel):
     content_type: str
 
 
+class DocumentPatch(BaseModel):
+    """Pydantic model for PATCH /api/documents/{doc_id}.
+
+    Optional fields — model_fields_set distinguishes "not provided" from "set to null".
+    At least one field must be present in model_fields_set (enforced in the handler).
+
+    T-05-09-01: explicit field declaration prevents mass assignment.
+    T-05-09-02: only filename and folder_id are accepted — no other fields can be set.
+    """
+    filename: Optional[str] = None
+    folder_id: Optional[uuid.UUID] = None
+
+
 # ── POST /api/documents/upload-url ───────────────────────────────────────────
 
 @router.post("/upload-url")
@@ -520,6 +533,53 @@ async def get_document(
     return meta
 
 
+# ── PATCH /api/documents/{doc_id} ────────────────────────────────────────────
+
+@router.patch("/{doc_id}")
+async def patch_document(
+    doc_id: str,
+    body: DocumentPatch,
+    session: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_regular_user),
+):
+    """Update document metadata (filename and/or folder_id).
+
+    T-05-09-01: get_regular_user dep rejects admins (403) and unauthenticated (401).
+    T-05-09-01: ownership check — non-owner gets 404 to avoid leaking document IDs (D-16).
+    T-05-09-02: response uses storage.get_metadata() which excludes credentials_enc and
+                password_hash via the _doc_to_dict whitelist.
+
+    At least one field must be provided — empty body returns 422.
+    folder_id=null moves the document to the root (no folder).
+    """
+    try:
+        uid = uuid.UUID(doc_id)
+    except ValueError:
+        raise HTTPException(404, "Document not found")
+
+    doc = await session.get(Document, uid)
+    if doc is None or doc.user_id != current_user.id:
+        raise HTTPException(404, "Document not found")
+
+    # Require at least one field to be set (model_fields_set tracks provided fields)
+    if not body.model_fields_set:
+        raise HTTPException(422, "At least one field (filename, folder_id) must be provided")
+
+    if "filename" in body.model_fields_set and body.filename is not None:
+        doc.filename = body.filename
+
+    if "folder_id" in body.model_fields_set:
+        # folder_id=null → move to root (no folder); folder_id=<uuid> → move to folder
+        doc.folder_id = body.folder_id
+
+    await session.commit()
+
+    meta = await storage.get_metadata(session, doc_id)
+    if meta is None:
+        raise HTTPException(404, "Document not found")
+    return meta
+
+
 # ── DELETE /api/documents/{doc_id} ───────────────────────────────────────────
 
 @router.delete("/{doc_id}")