"""
Tag model for categorizing and organizing work items.

Provides flexible tagging system for technologies, clients, infrastructure,
problem types, actions, and services.
"""

from typing import Optional

from sqlalchemy import Index, Integer, String, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship

from .base import Base, TimestampMixin, UUIDMixin


class Tag(Base, UUIDMixin, TimestampMixin):
    """
    Tag model for categorizing and organizing work items.

    Provides a flexible tagging system for organizing work by technology,
    client, infrastructure, problem type, action, or service. Tags can be
    pre-populated or created on-demand, with automatic usage tracking.

    Attributes:
        name: Tag name (unique)
        category: Tag category (technology, client, infrastructure, problem_type, action, service)
        description: Description of the tag
        usage_count: Number of times this tag has been used (auto-incremented)
    """

    __tablename__ = "tags"

    # Tag identification
    name: Mapped[str] = mapped_column(
        String(100),
        nullable=False,
        unique=True,
        doc="Tag name (unique)"
    )

    # Categorization
    category: Mapped[Optional[str]] = mapped_column(
        String(50),
        doc="Tag category: technology, client, infrastructure, problem_type, action, service"
    )

    # Description
    description: Mapped[Optional[str]] = mapped_column(
        Text,
        doc="Description of the tag"
    )

    # Usage tracking
    usage_count: Mapped[int] = mapped_column(
        Integer,
        default=0,
        server_default="0",
        doc="Number of times this tag has been used (auto-incremented)"
    )

    # Indexes
    __table_args__ = (
        Index("idx_tags_category", "category"),
        Index("idx_tags_name", "name"),
    )

    def __repr__(self) -> str:
        """String representation of the tag."""
        return f"<Tag(name='{self.name}', category='{self.category}', usage_count={self.usage_count})>"