Antifraude.Net/Antifraude.Net/ApiDenuncias/Services/IGestionaService.cs

using GestionaDenuncias.Shared.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace ApiDenuncias.Services
{
    public interface IGestionaService
    {
        // =========================
        //  Expedientes (files)
        // =========================

        /// <summary>
        /// Crea un expediente resolviendo el procedimiento externo desde el catalogo de Gestiona y devuelve los links 'file' y 'file-open'.
        /// </summary>
        Task<GestionaCreateFileResponse> CreateFileAsync(
            string subject,
            string documentSeries,
            string siaCode
        );

        /// <summary>
        /// Abre el expediente (lo pone en OPEN_EDITABLE), asigna título, clasificación y lo vincula al grupo indicado.
        /// </summary>
        Task OpenFileAsync(
            string fileUrl,
            string? fileOpenUrl,
            string assignedGroupCode,
            bool confidential,
            string freeTitle
        );

        /// <summary>
        /// Reemplaza los grupos/usuarios asignados al expediente. No modifica la unidad gestora.
        /// </summary>
        Task AssignFileAsync(
            string fileUrl,
            string assignedGroupCode
        );

        // =========================
        //  Documentos
        // =========================

        /// <summary>
        /// Crea un recurso de upload, sube bytes y devuelve la URI de upload.
        /// </summary>
        Task<string> CreateUploadAsync(
            byte[] contentBytes,
            string fileName
        );

        /// <summary>
        /// Crea el documento (metadata) y sube el contenido PDF a la raíz o a una carpeta.
        /// </summary>
        Task UploadDocumentAsync(
            string fileUrl,
            byte[] contentBytes,
            string fileName
        );

        /// <summary>
        /// Crea una carpeta de nombre 'folderName' en la raíz del expediente y devuelve su GUID.
        /// </summary>
        Task<Guid> CreateFolderAsync(
            string fileUrl,
            string folderName
        );

        // =========================
        //  Terceros
        // =========================

        /// <summary>
        /// Busca un tercero por NIF. Devuelve su ID y href si existe, null si no existe.
        /// </summary>
        Task<(string Id, string SelfHref)> BuscarTerceroPorNifAsync(string nif);

        /// <summary>
        /// Crea un tercero en Gestiona y devuelve su ID y href.
        /// </summary>
        Task<(string Id, string SelfHref)> CrearTerceroAsync(ThirdPartyIdentityData thirdParty);

        /// <summary>
        /// Obtiene la lista de terceros ya enlazados a un expediente.
        /// </summary>
        Task<HashSet<string>> ObtenerTercerosEnlazadosAsync(string fileUrl);

        /// <summary>
        /// Enlaza un tercero ya existente (por su href) a un expediente.
        /// </summary>
        Task EnlazarTerceroExistenteAsync(string fileUrl, string thirdSelfHref);

        /// <summary>
        /// Usa el NIF tal cual viene.
        /// Si es anónimo o vacío ? no crea ni enlaza.
        /// Si no existe, lo crea.
        /// Si no está enlazado al expediente, lo enlaza.
        /// </summary>
        Task<GestionaEnsureThirdResponse> AsegurarTerceroYEnlazarAsync(string fileUrl, ThirdPartyIdentityData thirdParty);



        // =========================
        //  CONSULTAS OPERATIVAS
        // =========================

        /// <summary>
        /// Devuelve el JSON crudo del listado operativo de expedientes, sin recorrer histórico paginado.
        /// </summary>
        Task<string> ListarExpedientesJsonAsyncBasico(int maxPages = 1);

        /// <summary>
        /// Busca directamente un expediente cuyo asunto sea "Denuncia {idDenuncia}-CD".
        /// Devuelve URL, número de expediente y título si lo encuentra; null si no.
        /// </summary>
        Task<GestionaExpedienteInfo?> BuscarExpedientePorIdEnAsuntoAsync(int idDenuncia);

        /// <summary>
        /// Busca un expediente por su numero/codigo visible de Gestiona, por ejemplo "151/2025".
        /// </summary>
        Task<GestionaExpedienteInfo?> BuscarExpedientePorCodigoAsync(string codigoExpediente);

        /// <summary>
        /// Obtiene los metadatos visibles de un expediente concreto.
        /// </summary>
        Task<GestionaExpedienteInfo?> ObtenerExpedienteAsync(string fileUrl);

        /// <summary>
        /// Obtiene la última entrada de auditoría del expediente, si Gestiona devuelve contenido.
        /// </summary>
        Task<GestionaAuditInfo?> ObtenerUltimaAuditoriaExpedienteAsync(string fileUrl);

        Task<List<ExpedienteTerceroDto>> ObtenerExpedientesPorTerceroAsync(
            string nif,
            DateTimeOffset? desde = null,
            DateTimeOffset? hasta = null,
            int maxPages = 1,
            int maxResults = 30,
            int maxParallel = 6
        );



    }
}