phase4: entity_attachments table + DMS unified storage + attachment service rewritten + download via DMS

app/models/__init__.py

@@ -84,3 +84,4 @@ __all__ = [
     "WorkflowStepHistory",
     "SavedView",
 ]
+from app.models.entity_attachment import EntityAttachment  # noqa: F401

app/models/entity_attachment.py

@@ -0,0 +1,51 @@
+"""EntityAttachment model — references DMS files for any entity."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Index, String
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
+
+
+class EntityAttachment(Base, TenantMixin, OwnedMixin):
+    """Links a DMS file to any entity (contact, address, invoice, etc.).
+    
+    The actual file is stored in the DMS (files table).
+    This table only holds the reference + category + display_name.
+    """
+
+    __tablename__ = "entity_attachments"
+    __table_args__ = (
+        Index("ix_entity_attachments_entity", "entity_type", "entity_id", "tenant_id"),
+        Index("ix_entity_attachments_dms_file", "dms_file_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    entity_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    entity_id: Mapped[uuid.UUID] = mapped_column(PGUUID(as_uuid=True), nullable=False)
+    dms_file_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True),
+        ForeignKey("files.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    category: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    display_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=__import__('sqlalchemy').func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=__import__('sqlalchemy').func.now(),
+        onupdate=__import__('sqlalchemy').func.now(),
+    )
+    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)