state-hub/api/models/task.py

import enum
import uuid
from datetime import date

from sqlalchemy import Boolean, Date, Enum, ForeignKey, String, Text
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship

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


class TaskStatus(str, enum.Enum):
    wait = "wait"
    todo = "todo"
    progress = "progress"
    done = "done"
    cancel = "cancel"


class TaskPriority(str, enum.Enum):
    low = "low"
    medium = "medium"
    high = "high"
    critical = "critical"


class Task(Base, TimestampMixin):
    __tablename__ = "tasks"

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=new_uuid
    )
    workplan_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("workplans.id", ondelete="RESTRICT", onupdate="CASCADE"),
        nullable=False,
        index=True,
    )
    # Canonical work-record identifier, e.g. "CUST-WP-0067-T01" (ADR-007).
    # Nullable because rows created before STATE-WP-0083-T06 have none; only the
    # repository files know the mapping. Without it a task can be matched only by
    # title, so renaming a heading looks like one task vanishing and another
    # appearing.
    record_id: Mapped[str | None] = mapped_column(String(120), nullable=True, index=True)
    flavor: Mapped[str | None] = mapped_column(String(32), nullable=True, index=True)
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    status: Mapped[TaskStatus] = mapped_column(
        Enum(TaskStatus), nullable=False, default=TaskStatus.todo
    )
    priority: Mapped[TaskPriority] = mapped_column(
        Enum(TaskPriority), nullable=False, default=TaskPriority.medium
    )
    assignee: Mapped[str | None] = mapped_column(String(100), nullable=True)
    due_date: Mapped[date | None] = mapped_column(Date, nullable=True)
    blocking_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
    needs_human: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False, index=True)
    intervention_note: Mapped[str | None] = mapped_column(Text, nullable=True)
    # Record id of the tracked decision a human-gated wait hangs on, e.g.
    # "CCR-2026-0004" (CUST-WP-0074 Case B). Free text: the decision may live
    # in another repo and may not be indexed in the hub yet.
    decision_id: Mapped[str | None] = mapped_column(String(120), nullable=True)
    parent_task_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("tasks.id", ondelete="SET NULL", onupdate="CASCADE"),
        nullable=True,
    )

    workplan: Mapped["Workplan"] = relationship("Workplan", back_populates="tasks")  # noqa: F821
    subtasks: Mapped[list["Task"]] = relationship(
        "Task", foreign_keys=[parent_task_id], lazy="selectin"
    )
    progress_events: Mapped[list["ProgressEvent"]] = relationship(  # noqa: F821
        "ProgressEvent", back_populates="task", lazy="selectin"
    )