Initial commit

backend/app/schemas/documents.py

@@ -0,0 +1,92 @@
+"""Pydantic schema definitions for document API payloads."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from app.models.document import DocumentStatus
+
+
+class DocumentResponse(BaseModel):
+    """Represents a document record returned by API endpoints."""
+
+    id: UUID
+    original_filename: str
+    source_relative_path: str
+    mime_type: str
+    extension: str
+    size_bytes: int
+    sha256: str
+    logical_path: str
+    suggested_path: str | None
+    image_text_type: str | None
+    handwriting_style_id: str | None
+    tags: list[str] = Field(default_factory=list)
+    suggested_tags: list[str] = Field(default_factory=list)
+    status: DocumentStatus
+    preview_available: bool
+    is_archive_member: bool
+    archived_member_path: str | None
+    parent_document_id: UUID | None
+    replaces_document_id: UUID | None
+    created_at: datetime
+    processed_at: datetime | None
+
+    class Config:
+        """Enables ORM object parsing for SQLAlchemy model instances."""
+
+        from_attributes = True
+
+
+class DocumentDetailResponse(DocumentResponse):
+    """Represents a full document payload including extracted text content."""
+
+    extracted_text: str
+    metadata_json: dict
+
+
+class DocumentsListResponse(BaseModel):
+    """Represents a paginated document list response payload."""
+
+    total: int
+    items: list[DocumentResponse]
+
+
+class UploadConflict(BaseModel):
+    """Describes an upload conflict where a matching checksum already exists."""
+
+    original_filename: str
+    sha256: str
+    existing_document_id: UUID
+
+
+class UploadResponse(BaseModel):
+    """Represents the result of a batch upload request."""
+
+    uploaded: list[DocumentResponse] = Field(default_factory=list)
+    conflicts: list[UploadConflict] = Field(default_factory=list)
+
+
+class DocumentUpdateRequest(BaseModel):
+    """Captures document metadata changes."""
+
+    original_filename: str | None = None
+    logical_path: str | None = None
+    tags: list[str] | None = None
+
+
+class SearchResponse(BaseModel):
+    """Represents the result of a search query."""
+
+    total: int
+    items: list[DocumentResponse]
+
+
+class ContentExportRequest(BaseModel):
+    """Describes filters used to export extracted document contents as Markdown files."""
+
+    document_ids: list[UUID] = Field(default_factory=list)
+    path_prefix: str | None = None
+    include_trashed: bool = False
+    only_trashed: bool = False