feat(phase-4a): backend skeleton, auth, health, tests

app/models/__init__.py

@@ -0,0 +1,15 @@
+"""SQLAlchemy ORM models for the CRM system."""
+
+from app.models.base import Base, OrgScopedMixin, SoftDeleteMixin, TimestampMixin
+from app.models.org import Org
+from app.models.user import User, UserRole
+
+__all__ = [
+    "Base",
+    "Org",
+    "OrgScopedMixin",
+    "SoftDeleteMixin",
+    "TimestampMixin",
+    "User",
+    "UserRole",
+]

app/models/base.py

@@ -0,0 +1,52 @@
+"""Base model and reusable mixins for the CRM system."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import DateTime, ForeignKey, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base
+
+
+class TimestampMixin:
+    """Adds created_at and updated_at columns to a model."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+        index=True,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+
+class SoftDeleteMixin:
+    """Adds deleted_at column for soft-delete pattern."""
+
+    deleted_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        default=None,
+        index=True,
+    )
+
+
+class OrgScopedMixin:
+    """Adds org_id foreign key. All queries must filter by org_id (OrgScopedQuery)."""
+
+    org_id: Mapped[int] = mapped_column(
+        ForeignKey("orgs.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+
+__all__ = ["Base", "OrgScopedMixin", "SoftDeleteMixin", "TimestampMixin"]

app/models/org.py

@@ -0,0 +1,34 @@
+"""Organization model."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, TimestampMixin
+
+if TYPE_CHECKING:
+    from app.models.user import User
+
+
+class Org(Base, TimestampMixin):
+    __tablename__ = "orgs"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    logo_url: Mapped[Optional[str]] = mapped_column(String(1024), nullable=True)
+    default_currency: Mapped[str] = mapped_column(
+        String(3), nullable=False, default="EUR", server_default="EUR"
+    )
+
+    # Relationship to users (defined here to resolve circular import)
+    users: Mapped[list["User"]] = relationship(
+        back_populates="org",
+        lazy="selectin",
+        cascade="all, delete-orphan",
+    )
+
+    def __repr__(self) -> str:
+        return f"<Org id={self.id} name={self.name!r}>"

app/models/user.py

@@ -0,0 +1,50 @@
+"""User model with role enum and soft-delete."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import Boolean, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base, OrgScopedMixin, SoftDeleteMixin, TimestampMixin
+
+if TYPE_CHECKING:
+    from app.models.org import Org
+
+
+class UserRole(str, Enum):
+    """User role for RBAC."""
+
+    admin = "admin"
+    sales_manager = "sales_manager"
+    sales_rep = "sales_rep"
+
+
+class User(Base, TimestampMixin, SoftDeleteMixin, OrgScopedMixin):
+    __tablename__ = "users"
+    __table_args__ = (
+        UniqueConstraint("org_id", "email", name="uq_users_org_email"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    email: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[UserRole] = mapped_column(
+        String(32),
+        nullable=False,
+        default=UserRole.sales_rep,
+        server_default=UserRole.sales_rep.value,
+    )
+    avatar_url: Mapped[Optional[str]] = mapped_column(String(1024), nullable=True)
+    email_notifications: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True, server_default="1"
+    )
+
+    # Relationship back to org (string reference avoids circular import at runtime)
+    org: Mapped["Org"] = relationship(back_populates="users", lazy="joined")
+
+    def __repr__(self) -> str:
+        return f"<User id={self.id} email={self.email!r} role={self.role}>"