using MyHomePage.Api.Models.Dtos;

namespace MyHomePage.Api.Services;

/// <summary>文件上传服务。</summary>
public interface IUploadService
{
    /// <summary>保存浏览器上传的文件（IFormFile）。</summary>
    Task<UploadResultDto> SaveAsync(IFormFile file);

    /// <summary>保存任意来源的字节流（如抓取的 favicon）。</summary>
    /// <param name="stream">数据流（由调用方负责释放）</param>
    /// <param name="fileName">用于推断扩展名的原始文件名</param>
    /// <param name="contentType">HTTP Content-Type（如 image/png）</param>
    /// <param name="subDir">可选子目录（如 "favicons"），用于逻辑分组</param>
    Task<UploadResultDto> SaveStreamAsync(Stream stream, string fileName, string contentType, string? subDir = null);

    /// <summary>确保上传根目录存在，返回根目录绝对路径。</summary>
    string EnsureRoot();
}