using Dpz.Core.Public.ViewModel.Request;
using Dpz.Core.Public.ViewModel.Response;

namespace Dpz.Core.Service.RepositoryService;

public interface ICodeFileSystemEntryService
{
    /// <summary>
    /// 根据路径分段查找文件系统实体
    /// </summary>
    /// <param name="pathSegments">路径分段列表（null 或空表示根目录）</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>匹配的响应模型，不存在则返回 null</returns>
    Task<CodeFileSystemEntryResponse?> FindByPathAsync(
        IReadOnlyCollection<string>? pathSegments,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 根据路径分段查找文件系统实体（绕过缓存，读取最新数据库状态）
    /// </summary>
    /// <param name="pathSegments">路径分段列表（null 或空表示根目录）</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>匹配的响应模型，不存在则返回 null</returns>
    Task<CodeFileSystemEntryResponse?> FindByPathWithoutCacheAsync(
        IReadOnlyCollection<string>? pathSegments,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取指定父路径下的所有子项
    /// </summary>
    /// <param name="parentPathSegments">父路径分段列表（null 或空表示根目录）</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>子项响应列表</returns>
    Task<List<CodeFileSystemEntryResponse>> GetChildrenAsync(
        IReadOnlyCollection<string>? parentPathSegments,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 根据关键字搜索文件/目录名称（忽略大小写）
    /// </summary>
    /// <param name="keyword">搜索关键字</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>匹配的响应列表</returns>
    Task<List<CodeFileSystemEntryResponse>> SearchAsync(
        string keyword,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 在可预览文本文件的内容中按字面量子串搜索（忽略大小写）
    /// </summary>
    /// <param name="query">搜索词，按字面量匹配并转义正则元字符</param>
    /// <param name="maxResults">返回条数上限，默认且最大 20</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>命中列表；无匹配或空查询返回空列表</returns>
    Task<List<CodeContentSearchHitResponse>> SearchContentAsync(
        string query,
        int? maxResults = null,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取分页列表，支持路径、名称、扩展名查询和多种排序
    /// </summary>
    /// <param name="request">查询请求参数</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>分页列表</returns>
    Task<IPagedList<CodeFileSystemEntryListResponse>> GetPagedListAsync(
        CodeFlatRequest request,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取所有目录，支持根据路径过滤
    /// </summary>
    /// <param name="pathSegments">路径分段列表（null 或空表示获取所有目录）</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>目录列表</returns>
    Task<List<string[]>> GetAllDirectoriesAsync(
        string[]? pathSegments = null,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 保存描述
    /// </summary>
    /// <param name="path">路径分段</param>
    /// <param name="name">文件或目录名称</param>
    /// <param name="description">描述</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>是否保存成功</returns>
    Task<bool> SaveDescriptionAsync(
        string[]? path,
        string name,
        string? description,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 保存AI分析结果
    /// </summary>
    /// <param name="path">路径分段</param>
    /// <param name="name">文件名称</param>
    /// <param name="analyzeResult">分析结果</param>
    /// <param name="analyzedHash">源文件 hash</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task SaveAiAnalyzeResultAsync(
        string[]? path,
        string name,
        string analyzeResult,
        string? analyzedHash = null,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 判断是否需要触发AI分析
    /// </summary>
    /// <param name="path"></param>
    /// <param name="name"></param>
    /// <param name="codeContainer"></param>
    /// <param name="cancellationToken"></param>
    /// <returns></returns>
    Task<bool> ShouldAnalyzeAsync(
        string[]? path,
        string? name,
        CodeContainer? codeContainer,
        CancellationToken cancellationToken = default
    );
}