using FileShare_Common.Core;
using FileShare_Services.Core;

namespace FileShare_Services.Services.FileLibrary
{
    /// <summary>
    /// 文件库 HTTP 端点服务接口，将 HTTP 请求适配到 <see cref="IFileLibraryService"/> 业务层。
    /// </summary>
    public interface IFileLibraryEndpointService
    {
        /// <summary>
        /// 获取服务器所有磁盘驱动器。
        /// </summary>
        /// <param name="ctx">端点上下文。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetDrivesAsync(ServiceEndpointContext ctx);

        /// <summary>
        /// 查询指定路径下的子目录。
        /// </summary>
        /// <param name="request">包含路径的查询请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetDirectoriesAsync(DirectoryQueryRequest request);

        /// <summary>
        /// 获取所有已注册的文件库根目录。
        /// </summary>
        /// <param name="ctx">端点上下文。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetRootsAsync(ServiceEndpointContext ctx);

        /// <summary>
        /// 添加新的文件库根目录。
        /// </summary>
        /// <param name="request">包含路径和配置的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> AddRootAsync(AddLibraryRootRequest request);

        /// <summary>
        /// 启用或禁用指定的文件库根目录。
        /// </summary>
        /// <param name="request">包含根目录 ID 和目标状态的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> SetRootEnabledAsync(UpdateLibraryRootRequest request);

        /// <summary>
        /// 删除指定的文件库根目录。
        /// </summary>
        /// <param name="request">包含根目录 ID 的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> DeleteRootAsync(DeleteLibraryRootRequest request);

        /// <summary>
        /// 立即扫描指定文件库根目录。
        /// </summary>
        /// <param name="request">包含根目录 ID 的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> ScanRootAsync(ScanLibraryRootRequest request);

        /// <summary>
        /// 分页搜索已扫描的文件记录。
        /// </summary>
        /// <param name="request">包含分页和过滤条件的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> SearchFilesAsync(SearchFilesRequest request);

        /// <summary>
        /// 根据 ID 获取文件详情。
        /// </summary>
        /// <param name="request">包含文件 ID 的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetFileAsync(FileQueryRequest request);

        /// <summary>
        /// 获取文本文件预览内容。
        /// </summary>
        /// <param name="request">包含文件 ID 的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetTextPreviewAsync(FileQueryRequest request);

        /// <summary>
        /// 浏览文件库目录结构。
        /// </summary>
        /// <param name="request">包含根目录 ID 和路径的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> BrowseDirectoryAsync(BrowseDirectoryRequest request);

        /// <summary>
        /// 获取最近添加或最近播放的文件列表。
        /// </summary>
        /// <param name="request">包含类型和数量的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> GetRecentFilesAsync(RecentFilesRequest request);

        /// <summary>
        /// 标记文件为已播放，更新最近播放时间。
        /// </summary>
        /// <param name="request">包含文件 ID 的请求。</param>
        /// <returns>API 响应。</returns>
        Task<IApiResponse> MarkFilePlayedAsync(MarkFilePlayedRequest request);
    }
}