feat(file): 新增可返回下载元数据的文件下载接口

[yuchat001]

背景

当前 JHFileApiExecution 已提供文件下载相关能力：

• getFileDownloadUrl(...)
• getFileInputStream(...)

但 getFileInputStream(...) 只返回 InputStream，调用方无法同时获取 HTTP 响应头、文件大小、文件名、Content-Type 等下载元数据。

在业务侧需要实现页面内下载进度条时，InputStream 只能累计已读字节数，缺少总大小时无法计算准确百分比。虽然部分场景可通过 getFileList(...) 返回的 FileInfo.size 获取文件大小，但下载接口本身仍缺少完整元数据返回能力。

需求

请新增一个支持返回更多下载信息的接口，例如：

FileDownloadResponse getFileDownloadResponse(
    String userId,
    String filePath,
    Boolean forceDownload
);
建议返回对象包含：

public class FileDownloadResponse {
    private InputStream inputStream;
    private long contentLength;
    private String fileName;
    private String contentType;
    private Map<String, String> headers;
}

其中：

inputStream：文件内容流
contentLength：文件总大小，优先来自 Content-Length 或 HttpEntity#getContentLength()
fileName：服务端响应或路径解析出的文件名
contentType：响应 Content-Type
headers：原始响应头，便于业务侧扩展使用

建议实现

底层 JHApiHttpClientImpl 使用 Apache HttpClient 时，可以在执行请求后保留响应元数据：

CloseableHttpResponse response = closeableHttpClient.execute(request);
HttpEntity entity = response.getEntity();

InputStream inputStream = entity.getContent();
long contentLength = entity.getContentLength();
Header contentType = entity.getContentType();
Header contentDisposition = response.getFirstHeader("Content-Disposition");

当前 SDK 的 HTTP client 方法只返回 InputStream，建议新增一个响应包装方法，不破坏现有接口兼容性。

可选增强
也可以进一步提供带进度回调的下载方法：

void downloadFile(
    String userId,
    String filePath,
    OutputStream outputStream,
    DownloadProgressListener listener
);

public interface DownloadProgressListener {
    void onProgress(long readBytes, long totalBytes);
}

这样调用方可以直接实现下载进度条，不需要重复包装 InputStream。

兼容性要求

• 保留现有 getFileInputStream(...) 和 getFileDownloadUrl(...) 方法。
• 新增接口不改变原有行为。
• 当服务端未返回 Content-Length 时，contentLength 可返回 -1 或 0，由调用方降级为不确定进度。
• 建议文档说明 contentLength 不保证一定存在，取决于服务端响应和传输方式。

使用场景

模型库需要从作业数据区下载文件并展示页面内进度条：

1. 调用新增下载接口获取 inputStream + contentLength。
2. 后端边读 InputStream 边累计 readBytes。
3. 根据 readBytes / contentLength 计算进度。
4. 通过 SSE、WebSocket 或轮询接口通知前端。