FileShare/FileShare-Services/Services/FileLibrary/FileLibraryService.cs

using FileShare_Common.Core;
using FileShare_EFCore.Database;
using FileShare_EFCore.Models;
using FileShare_Services.Core;
using Microsoft.EntityFrameworkCore;
using System.Text;

namespace FileShare_Services.Services.FileLibrary
{
    /// <summary>
    /// 文件库核心业务服务，实现磁盘枚举、目录管理、文件扫描与检索。
    /// </summary>
    public sealed class FileLibraryService(AppDataContext db, IVideoThumbnailService thumbnailService) : IFileLibraryService
    {
        /// <summary>
        /// 默认扫描间隔（分钟），当请求未指定间隔时使用。
        /// </summary>
        private const int DefaultScanIntervalMinutes = 5;
        /// <summary>
        /// 文本预览最大读取字节数（1 MB）。
        /// </summary>
        private const int MaxTextPreviewBytes = 1024 * 1024;

        /// <inheritdoc />
        public Task<List<DriveDto>> GetDrivesAsync(CancellationToken cancellationToken = default)
        {
            var drives = DriveInfo.GetDrives()
                .Select(drive => new DriveDto(
                    drive.Name,
                    drive.IsReady ? $"{drive.Name} ({drive.VolumeLabel})" : drive.Name,
                    drive.RootDirectory.FullName,
                    drive.DriveType.ToString(),
                    SafeDriveValue(drive, d => d.TotalSize),
                    SafeDriveValue(drive, d => d.AvailableFreeSpace),
                    drive.IsReady))
                .OrderBy(drive => drive.Name)
                .ToList();

            return Task.FromResult(drives);
        }

        /// <inheritdoc />
        public Task<List<DirectoryDto>> GetDirectoriesAsync(string? path, CancellationToken cancellationToken = default)
        {
            var normalized = NormalizeExistingDirectory(path);
            var directories = Directory.EnumerateDirectories(normalized)
                .Select(directory => new DirectoryInfo(directory))
                .OrderBy(directory => directory.Name)
                .Select(directory => new DirectoryDto(directory.Name, directory.FullName))
                .ToList();

            return Task.FromResult(directories);
        }

        /// <inheritdoc />
        public async Task<List<LibraryRootDto>> GetRootsAsync(CancellationToken cancellationToken = default)
        {
            var counts = await db.ManagedFileRecords
                .Where(file => file.Exists)
                .GroupBy(file => file.LibraryRootId)
                .Select(group => new { RootId = group.Key, Count = group.Count() })
                .ToDictionaryAsync(item => item.RootId, item => item.Count, cancellationToken);

            var roots = await db.ManagedLibraryRoots
                .OrderBy(root => root.Path)
                .ToListAsync(cancellationToken);

            return roots.Select(root => ToRootDto(root, counts.GetValueOrDefault(root.Id))).ToList();
        }

        /// <inheritdoc />
        public async Task<LibraryRootDto> AddRootAsync(AddLibraryRootRequest request, CancellationToken cancellationToken = default)
        {
            var normalized = NormalizeExistingDirectory(request.Path);
            var existing = await db.ManagedLibraryRoots.FirstOrDefaultAsync(root => root.Path == normalized, cancellationToken);
            if (existing is not null)
            {
                existing.IsEnabled = true;
                existing.IsAvailable = true;
                existing.DisplayName = ResolveDisplayName(normalized, request.DisplayName);
                existing.ScanIntervalMinutes = NormalizeInterval(request.ScanIntervalMinutes);
                await db.SaveChangesAsync(cancellationToken);
                var existingCount = await db.ManagedFileRecords
                    .CountAsync(file => file.LibraryRootId == existing.Id && file.Exists, cancellationToken);
                return ToRootDto(existing, existingCount);
            }

            var root = new ManagedLibraryRoot
            {
                Path = normalized,
                DisplayName = ResolveDisplayName(normalized, request.DisplayName),
                ScanIntervalMinutes = NormalizeInterval(request.ScanIntervalMinutes),
                IsEnabled = true,
                IsAvailable = true,
            };

            db.ManagedLibraryRoots.Add(root);
            await db.SaveChangesAsync(cancellationToken);

            return ToRootDto(root, 0);
        }

        /// <inheritdoc />
        public async Task<LibraryRootDto> SetRootEnabledAsync(UpdateLibraryRootRequest request, CancellationToken cancellationToken = default)
        {
            var root = await db.ManagedLibraryRoots.FirstOrDefaultAsync(item => item.Id == request.Id, cancellationToken)
                ?? throw new InvalidOperationException("文件库目录不存在。");

            root.IsEnabled = request.IsEnabled;
            await db.SaveChangesAsync(cancellationToken);

            var count = await db.ManagedFileRecords.CountAsync(file => file.LibraryRootId == root.Id && file.Exists, cancellationToken);
            return ToRootDto(root, count);
        }

        /// <inheritdoc />
        public async Task DeleteRootAsync(DeleteLibraryRootRequest request, CancellationToken cancellationToken = default)
        {
            var root = await db.ManagedLibraryRoots.FirstOrDefaultAsync(item => item.Id == request.Id, cancellationToken)
                ?? throw new InvalidOperationException("文件库目录不存在。");

            db.ManagedLibraryRoots.Remove(root);
            await db.SaveChangesAsync(cancellationToken);
        }

        /// <inheritdoc />
        public async Task<LibraryRootDto> ScanRootAsync(int rootId, CancellationToken cancellationToken = default)
        {
            var root = await db.ManagedLibraryRoots.FirstOrDefaultAsync(item => item.Id == rootId, cancellationToken)
                ?? throw new InvalidOperationException("文件库目录不存在。");

            Serilog.Log.Information("开始扫描文件库根目录 RootId={RootId} Path={Path}", root.Id, root.Path);
            root.LastScanStartedAt = DateTime.UtcNow;
            root.LastScanError = null;
            await db.SaveChangesAsync(cancellationToken);

            var staleFileCount = 0;
            var staleThumbnailPaths = new List<string>();

            try
            {
                if (!Directory.Exists(root.Path))
                {
                    throw new DirectoryNotFoundException($"目录不存在：{root.Path}");
                }

                root.IsAvailable = true;
                root.IsEnabled = true;

                var existing = await db.ManagedFileRecords
                    .Where(file => file.LibraryRootId == root.Id)
                    .ToDictionaryAsync(file => file.AbsolutePath, StringComparer.OrdinalIgnoreCase, cancellationToken);

                var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
                foreach (var path in EnumerateSupportedFiles(root.Path))
                {
                    cancellationToken.ThrowIfCancellationRequested();

                    var info = new FileInfo(path);
                    if (!info.Exists || !MediaFileTypes.TryGet(info.Extension.ToLowerInvariant(), out var mediaType, out var contentType, out _))
                    {
                        continue;
                    }

                    var absolutePath = info.FullName;
                    seen.Add(absolutePath);

                    if (!existing.TryGetValue(absolutePath, out var record))
                    {
                        record = new ManagedFileRecord
                        {
                            LibraryRootId = root.Id,
                            AbsolutePath = absolutePath,
                        };
                        db.ManagedFileRecords.Add(record);
                    }

                    record.FileName = info.Name;
                    record.RelativePath = Path.GetRelativePath(root.Path, absolutePath);
                    record.Extension = info.Extension.ToLowerInvariant();
                    record.SizeBytes = info.Length;
                    record.LastWriteTimeUtc = info.LastWriteTimeUtc;
                    record.FileCreationTimeUtc = info.CreationTimeUtc;
                    record.MediaType = mediaType;
                    record.ContentType = contentType;
                    record.Exists = true;
                    record.LastSeenAt = DateTime.UtcNow;

                    if (mediaType == "video" && record.ThumbnailId is null)
                    {
                        var thumbnail = await thumbnailService.GenerateThumbnailAsync(root.Id, absolutePath, cancellationToken);
                        if (thumbnail is not null)
                        {
                            var map = new ManagedThumbnailMap
                            {
                                LibraryRootId = root.Id,
                                RelativePath = thumbnail.RelativePath,
                                ContentType = thumbnail.ContentType,
                            };
                            db.ManagedThumbnailMaps.Add(map);
                            record.Thumbnail = map;
                        }

                        record.VideoDuration ??= thumbnailService.GetVideoDuration(absolutePath);
                    }
                }

                var staleFiles = existing.Values
                    .Where(file => !seen.Contains(file.AbsolutePath))
                    .ToList();
                staleFileCount = staleFiles.Count;

                foreach (var stale in staleFiles)
                {
                    stale.Exists = false;
                }

                var activeThumbnailIds = existing.Values
                    .Where(file => file.Exists && file.ThumbnailId is not null)
                    .Select(file => file.ThumbnailId!.Value)
                    .ToHashSet();
                var staleThumbnailIds = staleFiles
                    .Where(file => file.ThumbnailId is not null && !activeThumbnailIds.Contains(file.ThumbnailId.Value))
                    .Select(file => file.ThumbnailId!.Value)
                    .Distinct()
                    .ToList();

                if (staleThumbnailIds.Count > 0)
                {
                    var staleThumbnails = await db.ManagedThumbnailMaps
                        .Where(thumbnail => thumbnail.LibraryRootId == root.Id && staleThumbnailIds.Contains(thumbnail.Id))
                        .ToListAsync(cancellationToken);

                    staleThumbnailPaths = staleThumbnails
                        .Select(thumbnail => thumbnail.RelativePath)
                        .ToList();

                    foreach (var stale in staleFiles.Where(file => file.ThumbnailId is not null && staleThumbnailIds.Contains(file.ThumbnailId.Value)))
                    {
                        stale.ThumbnailId = null;
                        stale.Thumbnail = null;
                    }

                    db.ManagedThumbnailMaps.RemoveRange(staleThumbnails);
                }

                root.LastScanCompletedAt = DateTime.UtcNow;
                await db.SaveChangesAsync(cancellationToken);
                DeleteThumbnailFiles(staleThumbnailPaths);
            }
            catch (Exception ex)
            {
                root.IsAvailable = false;
                root.IsEnabled = false;
                root.LastScanError = ex.Message;
                root.LastScanCompletedAt = DateTime.UtcNow;
                await db.SaveChangesAsync(CancellationToken.None);
                throw;
            }

            var count = await db.ManagedFileRecords.CountAsync(file => file.LibraryRootId == root.Id && file.Exists, cancellationToken);
            Serilog.Log.Information(
                "扫描文件库根目录完成 RootId={RootId} FileCount={FileCount} StaleFiles={StaleFiles} RemovedThumbnails={RemovedThumbnails}",
                root.Id,
                count,
                staleFileCount,
                staleThumbnailPaths.Count);
            return ToRootDto(root, count);
        }

        /// <inheritdoc />
        public async Task ScanDueRootsAsync(CancellationToken cancellationToken = default)
        {
            var now = DateTime.UtcNow;
            var roots = await db.ManagedLibraryRoots
                .Where(root => root.IsEnabled && root.IsAvailable)
                .ToListAsync(cancellationToken);
            var dueRoots = roots
                .Where(root =>
                {
                    var interval = Math.Max(1, root.ScanIntervalMinutes);
                    return root.LastScanCompletedAt is null || root.LastScanCompletedAt.Value.AddMinutes(interval) <= now;
                })
                .ToList();

            Serilog.Log.Information(
                "文件库定时扫描检查完成 CheckedRoots={CheckedRoots} DueRoots={DueRoots}",
                roots.Count,
                dueRoots.Count);

            foreach (var root in dueRoots)
            {
                try
                {
                    Serilog.Log.Information("文件库定时扫描开始 RootId={RootId} Path={Path}", root.Id, root.Path);
                    var scannedRoot = await ScanRootAsync(root.Id, cancellationToken);
                    Serilog.Log.Information(
                        "文件库定时扫描完成 RootId={RootId} FileCount={FileCount}",
                        scannedRoot.Id,
                        scannedRoot.FileCount);
                }
                catch (Exception ex)
                {
                    Serilog.Log.Warning(ex, "扫描文件库根目录失败 RootId={RootId}", root.Id);
                }
            }
        }

        /// <inheritdoc />
        public async Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default)
        {
            var page = Math.Clamp(request.Page, 1, 100000);
            var pageSize = Math.Clamp(request.PageSize, 1, 100);
            var mediaType = request.MediaType?.Trim();
            var keyword = request.Keyword?.Trim();
            var rootId = Math.Clamp(request.RootId, 0, int.MaxValue);

            var query = db.ManagedFileRecords
                .AsNoTracking()
                .Where(file => file.Exists && file.LibraryRoot != null && file.LibraryRoot.IsAvailable);

            if (!string.IsNullOrWhiteSpace(mediaType) && !mediaType.Equals("all", StringComparison.OrdinalIgnoreCase))
            {
                query = query.Where(file => file.MediaType == mediaType);
            }

            if (rootId > 0)
            {
                query = query.Where(file => file.LibraryRootId == rootId);
            }

            if (!string.IsNullOrWhiteSpace(keyword))
            {
                query = query.Where(file => file.FileName.Contains(keyword) || file.RelativePath.Contains(keyword));
            }

            var total = await query.CountAsync(cancellationToken);
            var items = await ApplyFileSort(query, request.SortBy, request.SortDirection)
                .Skip((page - 1) * pageSize)
                .Take(pageSize)
                .Select(file => ToFileDto(file))
                .ToListAsync(cancellationToken);

            return PagedResponse<FileRecordDto>.From(items, total, page, pageSize);
        }

        /// <inheritdoc />
        public async Task<FileRecordDto?> GetFileAsync(int id, CancellationToken cancellationToken = default)
        {
            return await db.ManagedFileRecords
                .AsNoTracking()
                .Where(file => file.Id == id && file.Exists && file.LibraryRoot != null && file.LibraryRoot.IsAvailable)
                .Select(file => ToFileDto(file))
                .FirstOrDefaultAsync(cancellationToken);
        }

        /// <inheritdoc />
        public async Task<BrowseDirectoryResponse> BrowseDirectoryAsync(BrowseDirectoryRequest request, CancellationToken cancellationToken = default)
        {
            var rootId = request.RootId;
            var page = Math.Clamp(request.Page, 1, 100000);
            var pageSize = Math.Clamp(request.PageSize, 1, 100);
            var mediaType = request.MediaType?.Trim();
            // URL 友好的正斜杠，用于响应和内存处理
            var prefix = (request.Path ?? "").Trim().Replace('\\', '/').Trim('/');
            // Windows 反斜杠，用于数据库查询
            var dbPrefix = prefix.Replace('/', '\\');

            var query = db.ManagedFileRecords
                .AsNoTracking()
                .Where(f => f.LibraryRootId == rootId && f.Exists
                    && f.LibraryRoot != null && f.LibraryRoot.IsAvailable);

            if (!string.IsNullOrEmpty(dbPrefix))
            {
                var dbPrefixWithSlash = dbPrefix + "\\";
                query = query.Where(f => f.RelativePath.StartsWith(dbPrefixWithSlash));
            }

            var allFiles = await query.ToListAsync(cancellationToken);

            var subdirs = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
            var currentFiles = new List<ManagedFileRecord>();

            foreach (var file in allFiles)
            {
                var relativePath = file.RelativePath.Replace('\\', '/');
                var remaining = string.IsNullOrEmpty(prefix)
                    ? relativePath
                    : relativePath[(prefix.Length + 1)..];

                var slashIndex = remaining.IndexOf('/');
                if (slashIndex < 0)
                {
                    currentFiles.Add(file);
                }
                else
                {
                    subdirs.Add(remaining[..slashIndex]);
                }
            }

            if (!string.IsNullOrWhiteSpace(mediaType) && !mediaType.Equals("all", StringComparison.OrdinalIgnoreCase))
            {
                currentFiles = currentFiles
                    .Where(file => file.MediaType.Equals(mediaType, StringComparison.OrdinalIgnoreCase))
                    .ToList();
            }

            var total = currentFiles.Count;
            var files = ApplyFileSort(currentFiles, request.SortBy, request.SortDirection)
                .Skip((page - 1) * pageSize)
                .Take(pageSize)
                .Select(ToFileDto)
                .ToList();

            return new BrowseDirectoryResponse(
                prefix,
                subdirs.OrderBy(d => d, StringComparer.OrdinalIgnoreCase).ToList(),
                files,
                total,
                page,
                pageSize,
                pageSize > 0 ? (int)Math.Ceiling((double)total / pageSize) : 0);
        }

        /// <inheritdoc />
        public async Task<TextPreviewDto?> GetTextPreviewAsync(int id, CancellationToken cancellationToken = default)
        {
            var file = await db.ManagedFileRecords
                .AsNoTracking()
                .Include(item => item.LibraryRoot)
                .FirstOrDefaultAsync(item =>
                    item.Id == id
                    && item.Exists
                    && item.MediaType == "text"
                    && item.LibraryRoot != null
                    && item.LibraryRoot.IsAvailable,
                    cancellationToken);

            if (file is null || !File.Exists(file.AbsolutePath))
            {
                return null;
            }

            await using var stream = File.OpenRead(file.AbsolutePath);
            var limit = (int)Math.Min(stream.Length, MaxTextPreviewBytes);
            var buffer = new byte[limit];
            var read = await stream.ReadAsync(buffer.AsMemory(0, limit), cancellationToken);
            var content = Encoding.UTF8.GetString(buffer, 0, read);
            return new TextPreviewDto(file.Id, file.FileName, content, stream.Length > MaxTextPreviewBytes);
        }

        /// <inheritdoc />
        public async Task<List<FileRecordDto>> GetRecentFilesAsync(string type, int count = 12, CancellationToken cancellationToken = default)
        {
            var query = db.ManagedFileRecords
                .AsNoTracking()
                .Where(file => file.Exists && file.LibraryRoot != null && file.LibraryRoot.IsAvailable);

            query = type == "played"
                ? query.Where(file => file.LastPlayedAt != null).OrderByDescending(file => file.LastPlayedAt)
                : query.OrderByDescending(file => file.CreatedAt);

            return await query
                .Take(Math.Clamp(count, 1, 10))
                .Select(file => ToFileDto(file))
                .ToListAsync(cancellationToken);
        }

        /// <inheritdoc />
        public async Task MarkFilePlayedAsync(int id, CancellationToken cancellationToken = default)
        {
            var record = await db.ManagedFileRecords.FindAsync([id], cancellationToken);
            if (record is not null)
            {
                record.LastPlayedAt = DateTime.UtcNow;
                await db.SaveChangesAsync(cancellationToken);
            }
        }

        /// <inheritdoc />
        public async Task SaveFileProgressAsync(int id, double position, CancellationToken cancellationToken = default)
        {
            var record = await db.ManagedFileRecords.FindAsync([id], cancellationToken);
            if (record is not null)
            {
                record.PlaybackPosition = Math.Max(0, position);
                await db.SaveChangesAsync(cancellationToken);
            }
        }

        /// <summary>
        /// 深度优先遍历目录树，枚举所有被 <see cref="MediaFileTypes"/> 支持的媒体文件路径。
        /// 遇到无权限的目录时跳过该分支继续遍历。
        /// </summary>
        /// <param name="rootPath">根目录路径。</param>
        /// <returns>支持的文件完整路径枚举。</returns>
        private static IEnumerable<string> EnumerateSupportedFiles(string rootPath)
        {
            var pending = new Stack<string>();
            pending.Push(rootPath);

            while (pending.Count > 0)
            {
                var current = pending.Pop();
                IEnumerable<string> directories;
                IEnumerable<string> files;

                try
                {
                    directories = Directory.EnumerateDirectories(current);
                    files = Directory.EnumerateFiles(current);
                }
                catch (Exception ex)
                {
                    Serilog.Log.Information(ex, "无法枚举目录 {Directory}，已跳过", current);
                    continue;
                }

                foreach (var directory in directories)
                {
                    pending.Push(directory);
                }

                foreach (var file in files)
                {
                    if (MediaFileTypes.TryGet(Path.GetExtension(file), out _, out _, out _))
                    {
                        yield return file;
                    }
                }
            }
        }

        /// <summary>
        /// 规范化目录路径并验证目录存在。
        /// </summary>
        /// <param name="path">原始路径。</param>
        /// <returns>规范化后的完整路径。</returns>
        /// <exception cref="InvalidOperationException">路径为空时抛出。</exception>
        /// <exception cref="DirectoryNotFoundException">目录不存在时抛出。</exception>
        private static string NormalizeExistingDirectory(string? path)
        {
            if (string.IsNullOrWhiteSpace(path))
            {
                throw new InvalidOperationException("目录路径不能为空。");
            }

            var fullPath = Path.GetFullPath(path.Trim());
            if (!Directory.Exists(fullPath))
            {
                throw new DirectoryNotFoundException($"目录不存在：{fullPath}");
            }

            return new DirectoryInfo(fullPath).FullName;
        }

        /// <summary>
        /// 解析根目录的显示名称，优先使用用户指定名称，否则使用目录名。
        /// </summary>
        /// <param name="path">目录路径。</param>
        /// <param name="displayName">用户指定的显示名称。</param>
        /// <returns>最终显示名称。</returns>
        private static string ResolveDisplayName(string path, string? displayName)
        {
            if (!string.IsNullOrWhiteSpace(displayName))
            {
                return displayName.Trim();
            }

            var directory = new DirectoryInfo(path);
            return string.IsNullOrWhiteSpace(directory.Name) ? directory.FullName : directory.Name;
        }

        /// <summary>
        /// 删除数据库中已释放的缩略图文件，失败时保留扫描结果并记录告警。
        /// </summary>
        /// <param name="relativePaths">待删除缩略图相对路径。</param>
        private void DeleteThumbnailFiles(IEnumerable<string> relativePaths)
        {
            foreach (var relativePath in relativePaths)
            {
                try
                {
                    var absolutePath = thumbnailService.GetAbsolutePath(relativePath);
                    if (File.Exists(absolutePath))
                    {
                        File.Delete(absolutePath);
                    }
                }
                catch (Exception ex)
                {
                    Serilog.Log.Warning(ex, "清理失效缩略图文件失败 ThumbnailPath={ThumbnailPath}", relativePath);
                }
            }
        }

        /// <summary>
        /// 规范化扫描间隔，限制在 1 到 1440 分钟范围内，未指定时使用默认值。
        /// </summary>
        /// <param name="interval">用户指定的间隔。</param>
        /// <returns>规范化后的间隔分钟数。</returns>
        private static int NormalizeInterval(int? interval)
        {
            return Math.Clamp(interval ?? DefaultScanIntervalMinutes, 1, 1440);
        }

        private static IQueryable<ManagedFileRecord> ApplyFileSort(
            IQueryable<ManagedFileRecord> query,
            string? sortBy,
            string? sortDirection)
        {
            var descending = IsDescending(sortDirection);
            return NormalizeSortBy(sortBy) switch
            {
                "size" => descending
                    ? query.OrderByDescending(file => file.SizeBytes).ThenBy(file => file.FileName)
                    : query.OrderBy(file => file.SizeBytes).ThenBy(file => file.FileName),
                "created" => descending
                    ? query.OrderByDescending(file => file.FileCreationTimeUtc ?? file.LastWriteTimeUtc).ThenBy(file => file.FileName)
                    : query.OrderBy(file => file.FileCreationTimeUtc ?? file.LastWriteTimeUtc).ThenBy(file => file.FileName),
                "modified" => descending
                    ? query.OrderByDescending(file => file.LastWriteTimeUtc).ThenBy(file => file.FileName)
                    : query.OrderBy(file => file.LastWriteTimeUtc).ThenBy(file => file.FileName),
                "type" => descending
                    ? query.OrderByDescending(file => file.MediaType).ThenByDescending(file => file.Extension).ThenBy(file => file.FileName)
                    : query.OrderBy(file => file.MediaType).ThenBy(file => file.Extension).ThenBy(file => file.FileName),
                _ => descending
                    ? query.OrderByDescending(file => file.FileName).ThenBy(file => file.RelativePath)
                    : query.OrderBy(file => file.FileName).ThenBy(file => file.RelativePath),
            };
        }

        private static IOrderedEnumerable<ManagedFileRecord> ApplyFileSort(
            IEnumerable<ManagedFileRecord> files,
            string? sortBy,
            string? sortDirection)
        {
            var descending = IsDescending(sortDirection);
            return NormalizeSortBy(sortBy) switch
            {
                "size" => descending
                    ? files.OrderByDescending(file => file.SizeBytes).ThenBy(file => file.FileName)
                    : files.OrderBy(file => file.SizeBytes).ThenBy(file => file.FileName),
                "created" => descending
                    ? files.OrderByDescending(file => file.FileCreationTimeUtc ?? file.LastWriteTimeUtc).ThenBy(file => file.FileName)
                    : files.OrderBy(file => file.FileCreationTimeUtc ?? file.LastWriteTimeUtc).ThenBy(file => file.FileName),
                "modified" => descending
                    ? files.OrderByDescending(file => file.LastWriteTimeUtc).ThenBy(file => file.FileName)
                    : files.OrderBy(file => file.LastWriteTimeUtc).ThenBy(file => file.FileName),
                "type" => descending
                    ? files.OrderByDescending(file => file.MediaType).ThenByDescending(file => file.Extension).ThenBy(file => file.FileName)
                    : files.OrderBy(file => file.MediaType).ThenBy(file => file.Extension).ThenBy(file => file.FileName),
                _ => descending
                    ? files.OrderByDescending(file => file.FileName).ThenBy(file => file.RelativePath)
                    : files.OrderBy(file => file.FileName).ThenBy(file => file.RelativePath),
            };
        }

        private static string NormalizeSortBy(string? sortBy)
        {
            return sortBy?.Trim().ToLowerInvariant() switch
            {
                "size" or "sizebytes" => "size",
                "created" or "createdat" or "createtime" or "creationtime" => "created",
                "modified" or "lastwrite" or "lastwritetime" or "lastwritetimeutc" or "time" or "date" => "modified",
                "type" or "mediatype" or "extension" or "ext" => "type",
                _ => "name",
            };
        }

        private static bool IsDescending(string? sortDirection)
        {
            return sortDirection?.Trim().Equals("desc", StringComparison.OrdinalIgnoreCase) == true
                || sortDirection?.Trim().Equals("descending", StringComparison.OrdinalIgnoreCase) == true;
        }

        /// <summary>
        /// 安全获取驱动器属性值，驱动器未就绪或访问异常时返回 null。
        /// </summary>
        /// <param name="drive">驱动器信息。</param>
        /// <param name="selector">属性选择器。</param>
        /// <returns>属性值，不可用时返回 null。</returns>
        private static long? SafeDriveValue(DriveInfo drive, Func<DriveInfo, long> selector)
        {
            try
            {
                return drive.IsReady ? selector(drive) : null;
            }
            catch (Exception ex)
            {
                Serilog.Log.Information(ex, "获取驱动器属性失败，已跳过");
                return null;
            }
        }

        /// <summary>
        /// 将 <see cref="ManagedLibraryRoot"/> 实体映射为 <see cref="LibraryRootDto"/>。
        /// </summary>
        /// <param name="root">数据库实体。</param>
        /// <param name="fileCount">关联的文件记录数。</param>
        /// <returns>DTO 对象。</returns>
        private static LibraryRootDto ToRootDto(ManagedLibraryRoot root, int fileCount)
        {
            return new LibraryRootDto(
                root.Id,
                root.Path,
                root.DisplayName,
                root.IsEnabled,
                root.IsAvailable,
                root.ScanIntervalMinutes,
                root.LastScanStartedAt,
                root.LastScanCompletedAt,
                root.LastScanError,
                fileCount);
        }

        /// <summary>
        /// 将 <see cref="ManagedFileRecord"/> 实体映射为 <see cref="FileRecordDto"/>，并生成流式访问和文本预览 URL。
        /// </summary>
        /// <param name="file">数据库实体。</param>
        /// <returns>DTO 对象。</returns>
        private static FileRecordDto ToFileDto(ManagedFileRecord file)
        {
            return new FileRecordDto(
                file.Id,
                file.LibraryRootId,
                file.FileName,
                file.RelativePath,
                file.Extension,
                file.SizeBytes,
                file.LastWriteTimeUtc,
                file.FileCreationTimeUtc,
                file.MediaType,
                file.ContentType,
                $"/api/files/{file.Id}/stream",
                file.MediaType == "text" ? $"/api/files/text?id={file.Id}" : null,
                MediaFileTypes.IsBrowserPlayable(file.Extension),
                file.ThumbnailId is null ? null : $"/api/thumbnails/{file.ThumbnailId}",
                file.VideoDuration,
                file.LastPlayedAt,
                file.PlaybackPosition);
        }

    }
}