luoqian
6ef410fdfa
- 前端 Header 新增搜索栏，接入已有 SearchFiles API，结果支持列表/网格视图 - 新增 PlaybackPosition 数据库列与 /api/files/progress 端点，播放进度存服务端 - 播放中每 5 秒自动保存进度，再次打开视频时弹出"继续播放"提示 - 目录浏览新增媒体类型过滤条（全部/视频/音频/文本），前端即时过滤 - 新增 4 种数据库迁移（AddPlaybackPosition）
126 lines
6.4 KiB
C#
126 lines
6.4 KiB
C#
using FileShare_Common.Core;
|
||
|
||
namespace FileShare_Services.Services.FileLibrary
|
||
{
|
||
/// <summary>
|
||
/// 文件库核心业务服务接口，提供磁盘枚举、目录管理、文件扫描与检索功能。
|
||
/// </summary>
|
||
public interface IFileLibraryService
|
||
{
|
||
/// <summary>
|
||
/// 获取服务器所有磁盘驱动器信息。
|
||
/// </summary>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>驱动器信息列表。</returns>
|
||
Task<List<DriveDto>> GetDrivesAsync(CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 获取指定路径下的子目录列表。
|
||
/// </summary>
|
||
/// <param name="path">父目录路径，为空时返回根目录。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>子目录信息列表。</returns>
|
||
Task<List<DirectoryDto>> GetDirectoriesAsync(string? path, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 获取所有已注册的文件库根目录及其文件数量。
|
||
/// </summary>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>文件库根目录列表。</returns>
|
||
Task<List<LibraryRootDto>> GetRootsAsync(CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 添加新的文件库根目录，如已存在则激活并重新扫描。
|
||
/// </summary>
|
||
/// <param name="request">包含路径、显示名称和扫描间隔的请求。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>新添加或已存在的根目录信息。</returns>
|
||
Task<LibraryRootDto> AddRootAsync(AddLibraryRootRequest request, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 启用或禁用指定的文件库根目录。
|
||
/// </summary>
|
||
/// <param name="request">包含根目录 ID 和目标启用状态的请求。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>更新后的根目录信息。</returns>
|
||
Task<LibraryRootDto> SetRootEnabledAsync(UpdateLibraryRootRequest request, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 删除指定的文件库根目录。
|
||
/// </summary>
|
||
/// <param name="request">包含根目录 ID 的请求。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
Task DeleteRootAsync(DeleteLibraryRootRequest request, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 立即扫描指定根目录，枚举所有支持的媒体文件并更新数据库。
|
||
/// </summary>
|
||
/// <param name="rootId">根目录 ID。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>扫描后的根目录信息。</returns>
|
||
Task<LibraryRootDto> ScanRootAsync(int rootId, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 扫描所有已到期（距上次扫描超过间隔时间）的根目录。
|
||
/// </summary>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
Task ScanDueRootsAsync(CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 分页搜索已扫描的文件记录，支持按媒体类型、关键词和根目录过滤。
|
||
/// </summary>
|
||
/// <param name="request">包含分页和过滤条件的请求。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>分页文件记录响应。</returns>
|
||
Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 根据 ID 获取单个文件的记录信息。
|
||
/// </summary>
|
||
/// <param name="id">文件记录 ID。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>文件记录 DTO，不存在时返回 null。</returns>
|
||
Task<FileRecordDto?> GetFileAsync(int id, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 获取文本文件的预览内容（最多 1 MB）。
|
||
/// </summary>
|
||
/// <param name="id">文件记录 ID。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>文本预览 DTO，文件不存在或非文本类型时返回 null。</returns>
|
||
Task<TextPreviewDto?> GetTextPreviewAsync(int id, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 浏览指定根目录下的目录结构和文件列表。
|
||
/// </summary>
|
||
/// <param name="request">包含根目录 ID 和路径的请求。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>目录浏览响应，包含子目录和文件列表。</returns>
|
||
Task<BrowseDirectoryResponse> BrowseDirectoryAsync(BrowseDirectoryRequest request, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 获取最近添加或最近播放的文件列表。
|
||
/// </summary>
|
||
/// <param name="type">筛选类型，"added" 按创建时间排序，"played" 按最近播放时间排序。</param>
|
||
/// <param name="count">返回数量，范围 1-48，默认 12。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
/// <returns>文件记录 DTO 列表。</returns>
|
||
Task<List<FileRecordDto>> GetRecentFilesAsync(string type, int count = 12, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 将指定文件的最近播放时间更新为当前 UTC 时间。
|
||
/// </summary>
|
||
/// <param name="id">文件记录 ID。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
Task MarkFilePlayedAsync(int id, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// 保存文件的播放进度位置。
|
||
/// </summary>
|
||
/// <param name="id">文件记录 ID。</param>
|
||
/// <param name="position">播放位置（秒）。</param>
|
||
/// <param name="cancellationToken">取消令牌。</param>
|
||
Task SaveFileProgressAsync(int id, double position, CancellationToken cancellationToken = default);
|
||
}
|
||
}
|