state-hub/api/models/technical_debt.py

import enum
import uuid

from sqlalchemy import DateTime, Enum, ForeignKey, String, Text
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy.sql import func

from api.models.base import Base, TimestampMixin, new_uuid


class TDStatus(str, enum.Enum):
    # Legacy general statuses
    open = "open"
    in_progress = "in_progress"
    resolved = "resolved"
    deferred = "deferred"
    wont_fix = "wont_fix"
    # Dashboard-improvement workflow steps
    submitted = "submitted"
    analyse = "analyse"
    plan = "plan"
    implement = "implement"
    test = "test"
    review = "review"
    finished = "finished"


# Ordered workflow steps for dashboard-improvement suggestions
SUGGESTION_STEPS = ["submitted", "analyse", "plan", "implement", "test", "review", "finished"]


class TDNote(Base):
    __tablename__ = "td_notes"

    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=new_uuid)
    td_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), ForeignKey("technical_debt.id", ondelete="CASCADE"),
        nullable=False, index=True,
    )
    step: Mapped[str] = mapped_column(String(30), nullable=False)
    author: Mapped[str | None] = mapped_column(String(100), nullable=True)
    content: Mapped[str] = mapped_column(Text, nullable=False)
    created_at: Mapped[DateTime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), nullable=False
    )

    td: Mapped["TechnicalDebt"] = relationship("TechnicalDebt", back_populates="notes")


class TechnicalDebt(Base, TimestampMixin):
    __tablename__ = "technical_debt"

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=new_uuid
    )
    td_id: Mapped[str | None] = mapped_column(
        String(30), nullable=True, unique=True, index=True
    )  # human-readable ref, e.g. TD-CUST-001
    domain_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("domains.id", ondelete="RESTRICT"),
        nullable=False,
        index=True,
    )
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    location: Mapped[str | None] = mapped_column(String(500), nullable=True)
    debt_type: Mapped[str] = mapped_column(
        String(50), nullable=False, default="other"
    )  # design | implementation | test | docs | dependencies | performance | security | other
    severity: Mapped[str] = mapped_column(String(20), nullable=False, default="medium")
    status: Mapped[TDStatus] = mapped_column(
        Enum(TDStatus, name="tdstatus"), nullable=False, default=TDStatus.open
    )
    topic_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True), ForeignKey("topics.id", ondelete="SET NULL"), nullable=True
    )
    workplan_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("workplans.id", ondelete="SET NULL", onupdate="CASCADE"),
        nullable=True,
    )

    domain: Mapped["Domain"] = relationship("Domain", lazy="selectin")  # noqa: F821
    topic: Mapped["Topic"] = relationship("Topic", lazy="selectin")  # noqa: F821
    workplan: Mapped["Workplan"] = relationship("Workplan", lazy="selectin")  # noqa: F821
    notes: Mapped[list["TDNote"]] = relationship(
        "TDNote", back_populates="td", lazy="selectin",
        order_by="TDNote.created_at",
    )

    @property
    def domain_slug(self) -> str:
        return self.domain.slug if self.domain is not None else ""