myAi/Apis/cv-matcher-api/Controllers/CvController.cs

using CvMatcher.Models.Requests;
using Api.Services.Contracts;
using Microsoft.AspNetCore.Mvc;
using CvMatcher.Models.Responses;
using Common.Requests;
using Swashbuckle.AspNetCore.Annotations;
using Common.Responses;

namespace Api.Controllers;

/// <summary>
/// Internal endpoints for CV indexing and job-matching operations.
/// Routes are prefixed with <c>api/cv</c>. Protected by the internal API key middleware — not reachable from the public internet.
/// </summary>
[ApiController]
[Route("api/cv")]
public sealed class CvController : ControllerBase
{
    private readonly ICvMatcherService _service;
    private readonly ILogger<CvController> _logger;

    public CvController(ICvMatcherService service, ILogger<CvController> logger)
    {
        _service = service;
        _logger = logger;
    }

    /// <summary>
    /// Uploads and indexes a CV PDF into the RAG vector store.
    /// Returns from cache immediately if an identical document was previously indexed.
    /// </summary>
    /// <param name="request">Multipart form containing the CV PDF file.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// 200 OK with a <see cref="CvUploadResponse"/> containing the document ID and whether it was a cache hit;
    /// 400 Bad Request if the file is missing or the request is otherwise invalid.
    /// </returns>
    [HttpPost("upload")]
    [RequestSizeLimit(10 * 1024 * 1024)]
    [SwaggerOperation(Summary = "Upload CV document", Description = "Uploads a CV PDF and indexes it into the RAG vector store. Returns from cache if the same document was previously uploaded.")]
    [SwaggerResponse(StatusCodes.Status200OK, "CV indexed successfully", typeof(CvUploadResponse))]
    [SwaggerResponse(StatusCodes.Status400BadRequest, "File missing or request invalid", typeof(ErrorResponse))]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<CvUploadResponse>> Upload([FromForm] UploadFileRequest request, CancellationToken ct)
    {
        try
        {
            if (request.File is null) return BadRequest(new ErrorResponse { Error = "Missing CV PDF.", Code = "cv_file_missing" });
            _logger.LogInformation("CV upload received. FileName={FileName}, Size={SizeBytes}", request.File.FileName, request.File.Length);
            var result = await _service.UploadCvAsync(request.File, ct);
            _logger.LogInformation("CV upload processed. CvDocumentId={CvDocumentId}, Cached={Cached}", result.DocumentId, result.Cached);
            return Ok(result);
        }
        catch (InvalidOperationException ex)
        {
            _logger.LogWarning(ex, "Invalid CV upload request.");
            return BadRequest(new ErrorResponse { Error = ex.Message, Code = "invalid_request" });
        }
    }

    /// <summary>
    /// Returns the top matching job documents for a previously indexed CV using semantic vector search.
    /// </summary>
    /// <param name="request">The request containing the CV document ID and the maximum number of results to return.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// 200 OK with a <see cref="FindJobsResponse"/> containing the ranked list of matching jobs;
    /// 400 Bad Request if the CV document ID is missing or invalid.
    /// </returns>
    [HttpPost("find-jobs")]
    [SwaggerOperation(Summary = "Find matching jobs", Description = "Performs semantic search over indexed job documents to find the best matches for a given CV.")]
    [SwaggerResponse(StatusCodes.Status200OK, "Matching jobs returned", typeof(FindJobsResponse))]
    [SwaggerResponse(StatusCodes.Status400BadRequest, "CV document ID missing or invalid", typeof(ErrorResponse))]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<FindJobsResponse>> FindJobs([FromBody] FindJobsRequest request, CancellationToken ct)
    {
        try
        {
            _logger.LogInformation("Find jobs request received. CvDocumentId={CvDocumentId}, TopK={TopK}", request.CvDocumentId, request.TopK);
            var result = await _service.FindJobsAsync(request, ct);
            _logger.LogInformation("Find jobs completed. CvDocumentId={CvDocumentId}, ResultCount={ResultCount}", request.CvDocumentId, result.Jobs.Count);
            return result;
        }
        catch (InvalidOperationException ex)
        {
            _logger.LogWarning(ex, "Invalid find jobs request.");
            return BadRequest(new ErrorResponse { Error = ex.Message, Code = "invalid_request" });
        }
    }

    /// <summary>
    /// Scores a CV against a single job using LLM analysis.
    /// Fetches and extracts job text from the provided URL if no inline description is supplied,
    /// then runs a deep semantic match and returns a score with strengths and gaps.
    /// </summary>
    /// <param name="request">The match request: CV document ID plus either a job URL or an inline job description.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// 200 OK with a <see cref="JobMatchResponse"/> containing the score (0–100), strengths, gaps, and cache status;
    /// 400 Bad Request if required fields are missing or the request is invalid.
    /// </returns>
    [HttpPost("match-job")]
    [SwaggerOperation(Summary = "Match CV to one job", Description = "Scores a CV against a job URL or description using LLM analysis and returns a match score with strengths and gaps.")]
    [SwaggerResponse(StatusCodes.Status200OK, "Job match computed successfully", typeof(JobMatchResponse))]
    [SwaggerResponse(StatusCodes.Status400BadRequest, "Required fields missing or request invalid", typeof(ErrorResponse))]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<JobMatchResponse>> MatchJob([FromBody] MatchJobRequest request, CancellationToken ct)
    {
        try
        {
            _logger.LogInformation("Match job request received. CvDocumentId={CvDocumentId}, HasJobUrl={HasJobUrl}, HasJobDescription={HasJobDescription}, EmailRequested={EmailRequested}",
                request.CvDocumentId, !string.IsNullOrWhiteSpace(request.JobUrl), !string.IsNullOrWhiteSpace(request.JobDescription), !string.IsNullOrWhiteSpace(request.Email));
            var result = await _service.MatchJobAsync(request, ct);
            _logger.LogInformation("Match job completed. CvDocumentId={CvDocumentId}, Score={Score}, Cached={Cached}", request.CvDocumentId, result.Score, result.Cached);
            return result;
        }
        catch (InvalidOperationException ex)
        {
            _logger.LogWarning(ex, "Invalid match job request.");
            return BadRequest(new ErrorResponse { Error = ex.Message, Code = "invalid_request" });
        }
    }
}