FileShare/FileShare-Services/Services/FileLibrary/IVideoThumbnailService.cs

namespace FileShare_Services.Services.FileLibrary
{
    /// <summary>
    /// 视频缩略图生成服务接口，负责从视频文件中截取缩略图并获取时长信息。
    /// </summary>
    public interface IVideoThumbnailService
    {
        /// <summary>
        /// 为指定视频文件生成缩略图，如果已存在则直接返回。
        /// </summary>
        /// <param name="libraryRootId">文件库根目录 ID。</param>
        /// <param name="videoPath">视频文件的绝对路径。</param>
        /// <param name="ct">取消令牌。</param>
        /// <returns>生成的缩略图信息，失败时返回 null。</returns>
        Task<GeneratedThumbnail?> GenerateThumbnailAsync(int libraryRootId, string videoPath, CancellationToken ct = default);

        /// <summary>
        /// 将相对路径转换为缩略图存储目录下的绝对路径，并校验路径安全性。
        /// </summary>
        /// <param name="relativePath">相对路径。</param>
        /// <returns>绝对路径。</returns>
        /// <exception cref="InvalidOperationException">当路径越权访问缩略图存储根目录之外的位置时抛出。</exception>
        string GetAbsolutePath(string relativePath);

        /// <summary>
        /// 获取视频文件的总时长。
        /// </summary>
        /// <param name="videoPath">视频文件的绝对路径。</param>
        /// <returns>视频时长（秒），获取失败时返回 null。</returns>
        double? GetVideoDuration(string videoPath);
    }

    /// <summary>
    /// 缩略图生成结果记录。
    /// </summary>
    /// <param name="RelativePath">缩略图相对于存储根目录的路径。</param>
    /// <param name="ContentType">缩略图的 MIME 类型。</param>
    public sealed record GeneratedThumbnail(string RelativePath, string ContentType);
}