claudetools/api/routers/projects.py

"""
Project API router for ClaudeTools.

This module defines all REST API endpoints for managing projects, including
CRUD operations with proper authentication, validation, and error handling.
"""

from uuid import UUID

from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy.orm import Session

from api.database import get_db
from api.middleware.auth import get_current_user
from api.schemas.project import (
    ProjectCreate,
    ProjectResponse,
    ProjectUpdate,
)
from api.services import project_service

# Create router with prefix and tags
router = APIRouter()


@router.get(
    "",
    response_model=dict,
    summary="List all projects",
    description="Retrieve a paginated list of all projects with optional filtering",
    status_code=status.HTTP_200_OK,
)
def list_projects(
    skip: int = Query(
        default=0,
        ge=0,
        description="Number of records to skip for pagination"
    ),
    limit: int = Query(
        default=100,
        ge=1,
        le=1000,
        description="Maximum number of records to return (max 1000)"
    ),
    client_id: str = Query(
        default=None,
        description="Filter projects by client ID"
    ),
    status_filter: str = Query(
        default=None,
        description="Filter projects by status (complete, working, blocked, pending, critical, deferred)"
    ),
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    List all projects with pagination and optional filtering.

    - **skip**: Number of projects to skip (default: 0)
    - **limit**: Maximum number of projects to return (default: 100, max: 1000)
    - **client_id**: Filter by client ID (optional)
    - **status_filter**: Filter by status (optional)

    Returns a list of projects with pagination metadata.

    **Example Request:**
    ```
    GET /api/projects?skip=0&limit=50&status_filter=working
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "total": 15,
        "skip": 0,
        "limit": 50,
        "projects": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "client_id": "123e4567-e89b-12d3-a456-426614174001",
                "name": "Website Redesign",
                "slug": "website-redesign",
                "category": "client_project",
                "status": "working",
                "priority": "high",
                "description": "Complete website overhaul",
                "started_date": "2024-01-15",
                "target_completion_date": "2024-03-15",
                "estimated_hours": 120.00,
                "created_at": "2024-01-15T10:30:00Z",
                "updated_at": "2024-01-15T10:30:00Z"
            }
        ]
    }
    ```
    """
    try:
        if client_id:
            projects, total = project_service.get_projects_by_client(db, client_id, skip, limit)
        elif status_filter:
            projects, total = project_service.get_projects_by_status(db, status_filter, skip, limit)
        else:
            projects, total = project_service.get_projects(db, skip, limit)

        return {
            "total": total,
            "skip": skip,
            "limit": limit,
            "projects": [ProjectResponse.model_validate(project) for project in projects]
        }

    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to retrieve projects: {str(e)}"
        )


@router.get(
    "/{project_id}",
    response_model=ProjectResponse,
    summary="Get project by ID",
    description="Retrieve a single project by its unique identifier",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Project found and returned",
            "model": ProjectResponse,
        },
        404: {
            "description": "Project not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Project with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def get_project(
    project_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Get a specific project by ID.

    - **project_id**: UUID of the project to retrieve

    Returns the complete project details.

    **Example Request:**
    ```
    GET /api/projects/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "client_id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "Website Redesign",
        "slug": "website-redesign",
        "category": "client_project",
        "status": "working",
        "priority": "high",
        "description": "Complete website overhaul with new branding",
        "started_date": "2024-01-15",
        "target_completion_date": "2024-03-15",
        "completed_date": null,
        "estimated_hours": 120.00,
        "actual_hours": 45.50,
        "gitea_repo_url": "https://gitea.example.com/client/website",
        "notes": "Client requested mobile-first approach",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-20T14:20:00Z"
    }
    ```
    """
    project = project_service.get_project_by_id(db, project_id)
    return ProjectResponse.model_validate(project)


@router.post(
    "",
    response_model=ProjectResponse,
    summary="Create new project",
    description="Create a new project with the provided details",
    status_code=status.HTTP_201_CREATED,
    responses={
        201: {
            "description": "Project created successfully",
            "model": ProjectResponse,
        },
        404: {
            "description": "Client not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
        409: {
            "description": "Project with slug already exists",
            "content": {
                "application/json": {
                    "example": {"detail": "Project with slug 'website-redesign' already exists"}
                }
            },
        },
        422: {
            "description": "Validation error",
            "content": {
                "application/json": {
                    "example": {
                        "detail": [
                            {
                                "loc": ["body", "name"],
                                "msg": "field required",
                                "type": "value_error.missing"
                            }
                        ]
                    }
                }
            },
        },
    },
)
def create_project(
    project_data: ProjectCreate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Create a new project.

    Requires a valid JWT token with appropriate permissions.
    The client_id must reference an existing client.

    **Example Request:**
    ```json
    POST /api/projects
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "client_id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "Website Redesign",
        "slug": "website-redesign",
        "category": "client_project",
        "status": "working",
        "priority": "high",
        "description": "Complete website overhaul with new branding",
        "started_date": "2024-01-15",
        "target_completion_date": "2024-03-15",
        "estimated_hours": 120.00,
        "gitea_repo_url": "https://gitea.example.com/client/website",
        "notes": "Client requested mobile-first approach"
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "client_id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "Website Redesign",
        "slug": "website-redesign",
        "status": "working",
        "priority": "high",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    """
    project = project_service.create_project(db, project_data)
    return ProjectResponse.model_validate(project)


@router.put(
    "/{project_id}",
    response_model=ProjectResponse,
    summary="Update project",
    description="Update an existing project's details",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Project updated successfully",
            "model": ProjectResponse,
        },
        404: {
            "description": "Project or client not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Project with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
        409: {
            "description": "Conflict with existing project",
            "content": {
                "application/json": {
                    "example": {"detail": "Project with slug 'website-redesign' already exists"}
                }
            },
        },
    },
)
def update_project(
    project_id: UUID,
    project_data: ProjectUpdate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Update an existing project.

    - **project_id**: UUID of the project to update

    Only provided fields will be updated. All fields are optional.
    If updating client_id, the new client must exist.

    **Example Request:**
    ```json
    PUT /api/projects/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "status": "completed",
        "completed_date": "2024-03-10",
        "actual_hours": 118.50,
        "notes": "Project completed ahead of schedule"
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "client_id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "Website Redesign",
        "slug": "website-redesign",
        "status": "completed",
        "completed_date": "2024-03-10",
        "actual_hours": 118.50,
        "notes": "Project completed ahead of schedule",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-03-10T16:45:00Z"
    }
    ```
    """
    project = project_service.update_project(db, project_id, project_data)
    return ProjectResponse.model_validate(project)


@router.delete(
    "/{project_id}",
    response_model=dict,
    summary="Delete project",
    description="Delete a project by its ID",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Project deleted successfully",
            "content": {
                "application/json": {
                    "example": {
                        "message": "Project deleted successfully",
                        "project_id": "123e4567-e89b-12d3-a456-426614174000"
                    }
                }
            },
        },
        404: {
            "description": "Project not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Project with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def delete_project(
    project_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Delete a project.

    - **project_id**: UUID of the project to delete

    This is a permanent operation and cannot be undone.

    **Example Request:**
    ```
    DELETE /api/projects/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "message": "Project deleted successfully",
        "project_id": "123e4567-e89b-12d3-a456-426614174000"
    }
    ```
    """
    return project_service.delete_project(db, project_id)