src/app/api/v1/ticket_comments.py

"""
Ticket Comments API - Team Collaboration

Endpoints for:
1. Create comments on tickets
2. Update comments (by author)
3. Delete comments (by author or PM)
4. List comments with filtering
5. Get comment replies (threading)

Authorization:
- All authenticated users can create comments
- Only author can edit their own comments
- Author or PM can delete comments
"""

from fastapi import APIRouter, Depends, status, Query
from sqlalchemy.orm import Session
from typing import Optional, List
from uuid import UUID

from app.api.deps import get_db, get_current_user
from app.models.user import User
from app.services.ticket_comment_service import TicketCommentService
from app.schemas.ticket_comment import (
    TicketCommentCreate,
    TicketCommentUpdate,
    TicketCommentResponse,
    TicketCommentListResponse,
    COMMENT_TYPES
)

router = APIRouter()


# ============================================
# CREATE COMMENT
# ============================================

@router.post(
    "/tickets/{ticket_id}/comments",
    response_model=TicketCommentResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create comment on ticket",
    description="""
    Create a new comment on a ticket.
    
    **Features:**
    - Internal comments (team only) or external (client-visible)
    - Threading: Reply to other comments using parent_comment_id
    - Mentions: Tag users with mentioned_user_ids
    - Attachments: Link documents/images with attachment_document_ids
    
    **Image Attachments:**
    - Upload images first via POST /api/v1/documents/upload
    - Then include document IDs in attachment_document_ids array
    - Images are automatically detected and displayed inline
    - Supports multiple images per comment
    
    **Comment Types:**
    - note: General note or observation
    - issue: Problem or blocker
    - resolution: Solution or fix
    - question: Question for team
    - update: Status update
    
    **Authorization:** All authenticated users
    """
)
def create_comment(
    ticket_id: UUID,
    data: TicketCommentCreate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """Create a new comment on a ticket"""
    return TicketCommentService.create_comment(
        ticket_id=ticket_id,
        data=data,
        current_user=current_user,
        db=db
    )


# ============================================
# UPDATE COMMENT
# ============================================

@router.put(
    "/comments/{comment_id}",
    response_model=TicketCommentResponse,
    summary="Update comment",
    description="""
    Update a comment (only by original author).
    
    **Edit Tracking:**
    - is_edited flag set to true
    - edited_at timestamp recorded
    - edited_by_user_id tracked
    
    **Authorization:** Comment author only
    """
)
def update_comment(
    comment_id: UUID,
    data: TicketCommentUpdate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """Update a comment (author only)"""
    return TicketCommentService.update_comment(
        comment_id=comment_id,
        data=data,
        current_user=current_user,
        db=db
    )


# ============================================
# DELETE COMMENT
# ============================================

@router.delete(
    "/comments/{comment_id}",
    status_code=status.HTTP_200_OK,
    summary="Delete comment",
    description="""
    Delete a comment (soft delete).
    
    **Authorization:** 
    - Comment author can delete their own comments
    - Project managers can delete any comment
    - Platform admins can delete any comment
    """
)
def delete_comment(
    comment_id: UUID,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """Delete a comment (soft delete)"""
    return TicketCommentService.delete_comment(
        comment_id=comment_id,
        current_user=current_user,
        db=db
    )


# ============================================
# GET SINGLE COMMENT
# ============================================

@router.get(
    "/comments/{comment_id}",
    response_model=TicketCommentResponse,
    summary="Get comment by ID",
    description="""
    Get a single comment by ID.
    
    **Returns:**
    - Comment details
    - Author information
    - Edit history
    - Reply count
    
    **Authorization:** All authenticated users
    """
)
def get_comment(
    comment_id: UUID,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """Get a single comment"""
    return TicketCommentService.get_comment(
        comment_id=comment_id,
        db=db
    )


# ============================================
# LIST COMMENTS
# ============================================

@router.get(
    "/tickets/{ticket_id}/comments",
    response_model=TicketCommentListResponse,
    summary="List ticket comments",
    description="""
    List all comments for a ticket with pagination and filtering.
    
    **Filtering:**
    - is_internal: Show only internal or external comments
    - comment_type: Filter by comment type (note, issue, resolution, etc.)
    - parent_only: Show only top-level comments (exclude replies)
    
    **Pagination:**
    - page: Page number (1-indexed)
    - page_size: Items per page (default 50, max 100)
    
    **Sorting:**
    - Comments sorted by created_at DESC (newest first)
    
    **Authorization:** All authenticated users
    """
)
def list_comments(
    ticket_id: UUID,
    page: int = Query(1, ge=1, description="Page number"),
    page_size: int = Query(50, ge=1, le=100, description="Items per page"),
    is_internal: Optional[bool] = Query(None, description="Filter by internal/external"),
    comment_type: Optional[str] = Query(None, description=f"Filter by type: {', '.join(COMMENT_TYPES)}"),
    parent_only: bool = Query(False, description="Show only top-level comments"),
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """List comments for a ticket"""
    return TicketCommentService.list_comments(
        ticket_id=ticket_id,
        page=page,
        page_size=page_size,
        is_internal=is_internal,
        comment_type=comment_type,
        parent_only=parent_only,
        db=db
    )


# ============================================
# GET COMMENT REPLIES
# ============================================

@router.get(
    "/comments/{comment_id}/replies",
    response_model=List[TicketCommentResponse],
    summary="Get comment replies",
    description="""
    Get all replies to a specific comment (threading).
    
    **Use Case:**
    - Load replies when user expands a comment thread
    - Show conversation history
    
    **Sorting:**
    - Replies sorted by created_at ASC (oldest first)
    
    **Authorization:** All authenticated users
    """
)
def get_comment_replies(
    comment_id: UUID,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """Get all replies to a comment"""
    return TicketCommentService.get_comment_replies(
        comment_id=comment_id,
        db=db
    )