Changes

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

@@ -0,0 +1,92 @@
+using CvMatcher.Models.Requests;
+using Api.Services.Contracts;
+using Microsoft.AspNetCore.Mvc;
+using CvMatcher.Models.Responses;
+using Shared.Models.Requests;
+using Swashbuckle.AspNetCore.Annotations;
+using Shared.Models.Responses;
+
+namespace Api.Controllers;
+
+[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;
+    }
+
+    [HttpPost("upload")]
+    [RequestSizeLimit(10 * 1024 * 1024)]
+    [SwaggerOperation(Summary = "Upload CV document", Description = "Uploads a CV PDF and indexes it for matching.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "CV uploaded and indexed successfully")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid upload request")]
+    [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" });
+        }
+    }
+
+    [HttpPost("find-jobs")]
+    [SwaggerOperation(Summary = "Find matching jobs", Description = "Finds top matching jobs for a previously uploaded CV document.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Matching jobs returned")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid find jobs request")]
+    [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" });
+        }
+    }
+
+    [HttpPost("match-job")]
+    [SwaggerOperation(Summary = "Match CV to one job", Description = "Computes detailed match analysis between a CV and a single job description or URL.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Job match computed successfully")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid match job request")]
+    [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" });
+        }
+    }
+}

Apis/cv-matcher-api/Controllers/HealthController.cs

@@ -0,0 +1,79 @@
+using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
+
+namespace Api.Controllers
+{
+    /// <summary>
+    /// Controller that exposes simple health and readiness endpoints for the API.
+    /// Routes are prefixed with "api/health".
+    /// </summary>
+    [ApiController]
+    [Route("api/[controller]")]
+    public sealed class HealthController : ControllerBase
+    {
+        /// <summary>
+        /// Liveness probe.
+        /// Indicates whether the process is running. Used by orchestration systems to confirm the process is alive.
+        /// </summary>
+        /// <returns>
+        /// 200 OK with JSON payload: { "status": "alive" } when the process is running.
+        /// </returns>
+        // GET api/health/live
+        [HttpGet("live")]
+        [SwaggerOperation(Summary = "Liveness probe", Description = "Returns whether the API process is alive.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Service is alive")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
+        public IActionResult Live() => Ok(new { status = "alive" });
+
+        /// <summary>
+        /// Basic health check endpoint.
+        /// Returns overall status and the current server time in UTC.
+        /// </summary>
+        /// <returns>
+        /// 200 OK with JSON payload: { "status": "ok", "time": &lt;UTC time&gt; }.
+        /// </returns>
+        // GET api/health
+        [HttpGet]
+        [SwaggerOperation(Summary = "Health check", Description = "Returns overall health status and current UTC time.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Health check succeeded")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
+        public IActionResult Health() => Ok(new { status = "ok", time = DateTimeOffset.UtcNow });
+
+        /// <summary>
+        /// Echo endpoint.
+        /// Returns the received JSON payload unchanged. Useful for testing request/response plumbing.
+        /// </summary>
+        /// <param name="payload">Arbitrary JSON from the request body. The endpoint returns the same object.</param>
+        /// <returns>200 OK with the same JSON payload provided in the request body.</returns>
+        // POST api/health/echo
+        [HttpPost("echo")]
+        [SwaggerOperation(Summary = "Echo payload", Description = "Returns the same JSON payload received in the request body.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Payload echoed successfully")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
+        public IActionResult Echo(object payload) => Ok(payload);
+
+        /// <summary>
+        /// Readiness probe.
+        /// Indicates whether the service is ready to accept traffic. Typically checks downstream dependencies.
+        /// </summary>
+        /// <returns>
+        /// 200 OK with JSON { "status": "ready" } when ready;
+        /// 503 Service Unavailable with JSON { "status": "not_ready" } when not ready.
+        /// </returns>
+        // GET api/health/ready
+        [HttpGet("ready")]
+        [SwaggerOperation(Summary = "Readiness probe", Description = "Returns whether the service is ready to accept traffic.")]
+        [SwaggerResponse(StatusCodes.Status200OK, "Service is ready")]
+        [SwaggerResponse(StatusCodes.Status503ServiceUnavailable, "Service is not ready")]
+        [ProducesResponseType(StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status503ServiceUnavailable)]
+        public IActionResult Ready()
+        {
+            var ready = true;
+
+            return ready
+                ? Ok(new { status = "ready" })
+                : StatusCode(503, new { status = "not_ready" });
+        }
+    }
+}