"""Generalized external identifier system.

Links an Aurora entity (any type) to its identifier in an external provider
(TMDb, IMDb, TVDb, Wikidata, ...). External IDs are references, never
primary keys — see app/core/ids.py and docs/architecture.md.
"""

from __future__ import annotations

import uuid

from sqlalchemy import ForeignKey, String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column, relationship

from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
from app.models.provider import Provider


class ExternalID(Base, UUIDPrimaryKeyMixin, TimestampMixin):
    __tablename__ = "external_ids"
    __table_args__ = (
        # A provider's ID for a given entity type must be unique (one Aurora
        # entity per provider-native ID).
        UniqueConstraint(
            "provider_id", "entity_type", "external_id", name="uq_external_id_source"
        ),
        # An Aurora entity has at most one mapping per provider.
        UniqueConstraint(
            "entity_type", "entity_id", "provider_id", name="uq_external_id_entity_provider"
        ),
    )

    entity_type: Mapped[str] = mapped_column(String(30), nullable=False)
    entity_id: Mapped[uuid.UUID] = mapped_column(nullable=False)

    provider_id: Mapped[uuid.UUID] = mapped_column(
        ForeignKey("providers.id", ondelete="CASCADE"), nullable=False
    )
    external_id: Mapped[str] = mapped_column(String(200), nullable=False)
    url: Mapped[str | None] = mapped_column(String(500), nullable=True)

    provider: Mapped[Provider] = relationship()


__all__ = ["ExternalID"]