OA2023/OASystem/OASystem.Api/OAMethodLib/DeepSeekAPI/IDeepSeekService.cs

namespace OASystem.API.OAMethodLib.DeepSeekAPI
{
    /// <summary>
    /// DeepSeek API 服务接口
    /// </summary>
    public interface IDeepSeekService
    {
        /// <summary>
        /// 测试API连通性
        /// </summary>
        /// <returns></returns>
        Task<bool> TestApiConnectivityAsync();

        /// <summary>
        /// 检查可用端点
        /// </summary>
        /// <returns></returns>
        Task<List<string>> DiscoverAvailableEndpointsAsync();

        /// <summary>
        /// 上传文件到DeepSeek API
        /// </summary>
        /// <param name="file">要上传的文件</param>
        /// <param name="purpose">文件用途</param>
        /// <returns>文件上传响应</returns>
        Task<DeepSeekFileUploadResponse> UploadFileAsync(IFormFile file, string purpose = "assistants");

        /// <summary>
        /// 批量上传文件
        /// </summary>
        /// <param name="files">文件列表</param>
        /// <param name="purpose">文件用途</param>
        /// <returns>上传结果列表</returns>
        Task<List<FileUploadResult>> UploadFilesAsync(List<IFormFile> files, string purpose = "assistants");

        /// <summary>
        /// 获取文件列表
        /// </summary>
        /// <returns>文件列表响应</returns>
        Task<DeepSeekFileListResponse> ListFilesAsync();

        /// <summary>
        /// 获取文件信息
        /// </summary>
        /// <param name="fileId">文件ID</param>
        /// <returns>文件信息</returns>
        Task<DeepSeekFileUploadResponse> GetFileInfoAsync(string fileId);

        /// <summary>
        /// 删除文件
        /// </summary>
        /// <param name="fileId">文件ID</param>
        /// <returns>是否删除成功</returns>
        Task<bool> DeleteFileAsync(string fileId);

        /// <summary>
        /// 使用已上传的文件进行聊天
        /// </summary>
        /// <param name="fileIds">文件ID列表</param>
        /// <param name="question">问题</param>
        /// <param name="model">模型名称</param>
        /// <param name="temperature">温度参数</param>
        /// <param name="maxTokens">最大token数</param>
        /// <returns>聊天响应</returns>
        Task<ApiResponse> ChatWithFilesAsync(List<string> fileIds, string question, string model = "deepseek-chat", float temperature = 0.7f, int maxTokens = 4000);

        /// <summary>
        /// chat接口 - 直接提问（不使用文件上下文）
        /// </summary>
        /// <param name="question">问题</param>
        /// <param name="model">模型名称</param>
        /// <param name="stream">是否流式输出</param>
        /// <param name="temperature">温度参数</param>
        /// <param name="maxTokens">最大token数</param>
        /// <returns>聊天响应</returns>
        Task<ApiResponse> ChatAsync(string question, bool stream = false, string model = "deepseek-chat", float temperature = 0.7f, int maxTokens = 4000);

        /// <summary>
        /// 流式 chat；每段带 <see cref="DeepSeekStreamPhase"/>，reasoner 模型下思考与正文都会产出。
        /// </summary>
        /// <param name="question">问题</param>
        /// <param name="model">模型名称</param>
        /// <param name="temperature">温度参数</param>
        /// <param name="maxTokens">最大token数</param>
        IAsyncEnumerable<DeepSeekStreamChunk> ChatStreamAsync(string question, string model = "deepseek-chat", float temperature = 0.7f, int maxTokens = 4000);

        /// <summary>
        /// 带完整上下文的流式对话：将 <paramref name="messages"/> 原样提交给 chat/completions（stream=true）。
        /// 与 <see cref="ChatStreamAsync"/> 行为一致（含 reasoner 的 reasoning/content 分阶段），但支持多轮记忆。
        /// </summary>
        /// <param name="messages">已排序的会话历史，最后一条一般应为 user</param>
        /// <param name="model">模型名称</param>
        /// <param name="temperature">温度参数</param>
        /// <param name="maxTokens">最大 token 数</param>
        IAsyncEnumerable<DeepSeekStreamChunk> ChatStreamWithHistoryAsync(
            IReadOnlyList<DeepSeekHistoryMessage> messages,
            string model = "deepseek-chat",
            float temperature = 0.7f,
            int maxTokens = 4000);

        /// <summary>
        /// 等待文件处理完成
        /// </summary>
        /// <param name="fileId">文件ID</param>
        /// <param name="timeoutSeconds">超时时间（秒）</param>
        /// <returns>处理后的文件状态</returns>
        Task<DeepSeekFileUploadResponse> WaitForFileProcessingAsync(string fileId, int timeoutSeconds = 60);

        #region 本地项目相关
        /// <summary>
        /// 读取项目内的指定文件并转换为IFormFile
        /// </summary>
        /// <param name="relativePaths">文件相对路径列表</param>
        /// <returns>文件读取响应</returns>
        Task<ProjectFileReadResponse> ReadProjectFilesAsync(List<string> relativePaths);

        /// <summary>
        /// 读取项目内指定目录的文件
        /// </summary>
        /// <param name="directoryPath">目录相对路径</param>
        /// <param name="searchPattern">文件搜索模式</param>
        /// <param name="recursive">是否递归搜索</param>
        /// <returns>文件读取响应</returns>
        Task<ProjectFileReadResponse> ReadProjectDirectoryAsync(string directoryPath, string searchPattern = "*.cs", bool recursive = false);

        /// <summary>
        /// 获取项目根目录路径
        /// </summary>
        /// <returns>项目根目录完整路径</returns>
        string GetProjectRootPath();

        /// <summary>
        /// 检查文件是否存在
        /// </summary>
        /// <param name="relativePath">文件相对路径</param>
        /// <returns>是否存在</returns>
        bool FileExists(string relativePath);

        /// <summary>
        /// 将物理文件转换为IFormFile
        /// </summary>
        /// <param name="filePath">文件完整路径</param>
        /// <returns>IFormFile实例</returns>
        Task<IFormFile> ConvertToFormFileAsync(string filePath);

        /// <summary>
        /// 读取特定的签证申请表单文件
        /// </summary>
        /// <param name="fileName"></param>
        /// <returns></returns>
        Task<ProjectFileReadResponse> ReadVisaFormFileAsync(string fileName);

        /// <summary>
        /// 读取OASystem项目中的所有CS文件
        /// </summary>
        Task<ProjectFileReadResponse> ReadOASystemFilesAsync(string searchPattern = "*.cs", bool recursive = true);

        /// <summary>
        /// 读取指定域模型中的CS文件
        /// </summary>
        Task<ProjectFileReadResponse> ReadDomainViewModelsAsync(string searchPattern = "*.cs", bool recursive = true);

        /// <summary>
        /// 读取签证表单相关的所有CS文件
        /// </summary>
        Task<ProjectFileReadResponse> ReadVisaFormFilesAsync(string searchPattern = "*.cs", bool recursive = true);

        #endregion

    }
}