claudetools/api/models/problem_solution.py

"""
Problem solution model for tracking issues and their resolutions.

This model captures problems encountered during work sessions, the investigation
process, root cause analysis, and solutions applied.
"""

from datetime import datetime
from typing import Optional

from sqlalchemy import CHAR, ForeignKey, Index, Integer, String, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy.sql import func

from api.models.base import Base, UUIDMixin


class ProblemSolution(UUIDMixin, Base):
    """
    Track problems and their solutions.

    Records issues encountered during work, including symptoms, investigation steps,
    root cause analysis, solutions applied, and verification methods.

    Attributes:
        id: UUID primary key
        work_item_id: Reference to the work item
        session_id: Reference to the session
        problem_description: Detailed description of the problem
        symptom: What the user observed/experienced
        error_message: Exact error code or message
        investigation_steps: JSON array of diagnostic commands/steps taken
        root_cause: Identified root cause of the problem
        solution_applied: The solution that was implemented
        verification_method: How the fix was verified
        rollback_plan: Plan to rollback if solution causes issues
        recurrence_count: Number of times this problem has occurred
        created_at: When the problem was recorded
    """

    __tablename__ = "problem_solutions"

    # Foreign keys
    work_item_id: Mapped[str] = mapped_column(
        CHAR(36),
        ForeignKey("work_items.id", ondelete="CASCADE"),
        nullable=False,
        doc="Reference to work item",
    )
    session_id: Mapped[str] = mapped_column(
        CHAR(36),
        ForeignKey("sessions.id", ondelete="CASCADE"),
        nullable=False,
        doc="Reference to session",
    )

    # Problem details
    problem_description: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        doc="Detailed description of the problem",
    )
    symptom: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="What the user observed/experienced",
    )
    error_message: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="Exact error code or message",
    )

    # Investigation and analysis
    investigation_steps: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="JSON array of diagnostic commands/steps taken",
    )
    root_cause: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="Identified root cause of the problem",
    )

    # Solution details
    solution_applied: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        doc="The solution that was implemented",
    )
    verification_method: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="How the fix was verified",
    )
    rollback_plan: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        doc="Plan to rollback if solution causes issues",
    )

    # Recurrence tracking
    recurrence_count: Mapped[int] = mapped_column(
        Integer,
        nullable=False,
        server_default="1",
        doc="Number of times this problem has occurred",
    )

    # Timestamp
    created_at: Mapped[datetime] = mapped_column(
        nullable=False,
        server_default=func.now(),
        doc="When the problem was recorded",
    )

    # Table constraints
    __table_args__ = (
        Index("idx_problems_work_item", "work_item_id"),
        Index("idx_problems_session", "session_id"),
    )

    def __repr__(self) -> str:
        """String representation of the problem solution."""
        desc_preview = self.problem_description[:50] + "..." if len(self.problem_description) > 50 else self.problem_description
        return f"<ProblemSolution(id={self.id}, problem={desc_preview}, recurrence={self.recurrence_count})>"