feat(file-storage): add document_files model and enum

surfsense_backend/app/file_storage/persistence/__init__.py

@@ -0,0 +1,11 @@
+"""Models and enums for the document file-storage tables."""
+
+from __future__ import annotations
+
+from .enums import DocumentFileKind
+from .models import DocumentFile
+
+__all__ = [
+    "DocumentFile",
+    "DocumentFileKind",
+]

surfsense_backend/app/file_storage/persistence/enums.py

@@ -0,0 +1,11 @@
+"""DocumentFile kinds: the original upload plus future derived artifacts."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class DocumentFileKind(StrEnum):
+    ORIGINAL = "ORIGINAL"
+    REDACTED = "REDACTED"
+    FILLED_FORM = "FILLED_FORM"

surfsense_backend/app/file_storage/persistence/models.py

@@ -0,0 +1,66 @@
+"""``document_files`` table: durable blobs associated with a document."""
+
+from __future__ import annotations
+
+from sqlalchemy import (
+    BigInteger,
+    Column,
+    Enum as SQLAlchemyEnum,
+    ForeignKey,
+    Integer,
+    String,
+)
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.db import BaseModel, TimestampMixin
+
+from .enums import DocumentFileKind
+
+
+class DocumentFile(BaseModel, TimestampMixin):
+    """One stored file for a document (its original upload, or a derived copy)."""
+
+    __tablename__ = "document_files"
+
+    document_id = Column(
+        Integer,
+        ForeignKey("documents.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    search_space_id = Column(
+        Integer,
+        ForeignKey("searchspaces.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    kind = Column(
+        SQLAlchemyEnum(
+            DocumentFileKind,
+            name="document_file_kind",
+            values_callable=lambda x: [e.value for e in x],
+        ),
+        nullable=False,
+        default=DocumentFileKind.ORIGINAL,
+        server_default=DocumentFileKind.ORIGINAL.value,
+        index=True,
+    )
+
+    # Where the bytes live: the backend that stored them and its object key.
+    storage_backend = Column(String(32), nullable=False)
+    storage_key = Column(String, nullable=False)
+
+    original_filename = Column(String, nullable=False)
+    mime_type = Column(String, nullable=True)
+    size_bytes = Column(BigInteger, nullable=False)
+    checksum_sha256 = Column(String(64), nullable=True)
+
+    created_by_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("user.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )
+
+    document = relationship("Document", back_populates="files")