"""
Base models and mixins for SQLAlchemy ORM.

This module provides the foundational base class and reusable mixins
for all database models in the ClaudeTools application.
"""

import uuid
from datetime import datetime
from typing import Any

from sqlalchemy import CHAR, Column, DateTime
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy.sql import func


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

    pass


class UUIDMixin:
    """
    Mixin that adds a UUID primary key column.

    This mixin provides a standardized UUID-based primary key for models,
    stored as CHAR(36) for compatibility with MariaDB and other databases
    that don't have native UUID support.

    Attributes:
        id: UUID primary key stored as CHAR(36), automatically generated
    """

    id: Mapped[str] = mapped_column(
        CHAR(36),
        primary_key=True,
        default=lambda: str(uuid.uuid4()),
        nullable=False,
        doc="Unique identifier for the record",
    )


class TimestampMixin:
    """
    Mixin that adds timestamp columns for record tracking.

    This mixin provides automatic timestamp tracking for record creation
    and updates, using database-level defaults for consistency.

    Attributes:
        created_at: Timestamp when the record was created
        updated_at: Timestamp when the record was last updated
    """

    created_at: Mapped[datetime] = mapped_column(
        DateTime,
        nullable=False,
        server_default=func.now(),
        doc="Timestamp when the record was created",
    )

    updated_at: Mapped[datetime] = mapped_column(
        DateTime,
        nullable=False,
        server_default=func.now(),
        server_onupdate=func.now(),
        doc="Timestamp when the record was last updated",
    )