api/shared/db/base.py - master - systemsstrategyy/Treker

api/shared/db/base.py
75 строк2 KB
SystemsStrategy
Initial import
02 июл 2026, 15:15
02 июл 2026, 15:159624ed1
"""SQLAlchemy declarative base.

Foundation Agent: all module models must inherit from `Base` for Alembic
autogenerate to detect them. Import models in alembic/env.py:

    from api.modules.auth import models  # noqa
    from api.modules.spaces import models  # noqa
    # etc.

This forces SQLAlchemy to register them with Base.metadata.
"""

from datetime import datetime
from uuid import UUID, uuid4

from sqlalchemy import DateTime, MetaData, func
from sqlalchemy.dialects.postgresql import UUID as PG_UUID
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

# Naming convention for constraints — keeps Alembic migrations stable
NAMING_CONVENTION = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
}


class Base(DeclarativeBase):
    """Declarative base for all ORM models."""

    metadata = MetaData(naming_convention=NAMING_CONVENTION)

    # Default repr — useful in logs and tests
    def __repr__(self) -> str:
        attrs = ", ".join(
            f"{k}={v!r}"
            for k, v in self.__dict__.items()
            if not k.startswith("_") and k in {"id", "uid"}
        )
        return f"<{type(self).__name__} {attrs}>"


class TimestampMixin:
    """Adds created_at / updated_at automatically."""

    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        server_default=func.now(),
        onupdate=func.now(),
        nullable=False,
    )


class UUIDMixin:
    """Dual ID pattern (mirrors Kaiten):
    - `id` for internal FK joins (autoincrement integer for compactness)
    - `uid` for external API references (UUID, unguessable)

    Foundation Agent: see TZ section 2.4 / Kaiten Reverse Engineering Report.
    """

    uid: Mapped[UUID] = mapped_column(
        PG_UUID(as_uuid=True),
        default=uuid4,
        unique=True,
        nullable=False,
        index=True,
    )