package com.custom.webui.service;
|
|
import com.custom.webui.dto.resp.FileDTO;
|
import com.custom.webui.dto.resp.OcrResultDTO;
|
import com.custom.webui.security.AuthPrincipal;
|
import com.custom.webui.entity.UploadFile;
|
import org.springframework.web.multipart.MultipartFile;
|
|
import java.util.List;
|
|
/** 文件与知识库服务。 */
|
public interface FileService {
|
|
/**
|
* 保存上传文件。
|
*
|
* <p>安全校验顺序(任一失败即拒绝,不落盘):
|
* <ol>
|
* <li>文件非空、大小在限制内</li>
|
* <li>扩展名在白名单内 —— 防止上传 jsp/exe 等可执行文件</li>
|
* <li>原始文件名做净化,存储名由服务端生成 UUID,
|
* 彻底消除 {@code ../} 路径穿越的可能</li>
|
* </ol>
|
*
|
* @param chatId 绑定的会话 id,可为 null 表示公共知识库
|
*/
|
/**
|
* 上传文件。
|
*
|
* @param autoIngest 是否上传后立即向量化。**推荐 true** ——
|
* 未入库的文件对检索完全无效,用户看到「未向量化」
|
* 却不知道意味着什么,很容易以为已经能用了。
|
* 设为 false 时返回未入库的文件,由调用方择机触发。
|
*/
|
FileDTO upload(Long userId, Long chatId, MultipartFile file, boolean autoIngest, Long categoryId);
|
|
/**
|
* 以管理员身份上传**全局知识库**文件,全员可见可绑定。
|
*
|
* @param autoIngest 是否上传后立即向量化
|
* @throws com.custom.webui.exception.BusinessException 调用者不是管理员(403)
|
*/
|
FileDTO uploadGlobal(Long userId, MultipartFile file, boolean autoIngest, Long categoryId);
|
|
/**
|
* 当前用户**可管理**的文件列表(自己上传的 + 管理员上传的全局文件)。
|
*
|
* <p>「可见」与「可管理」是两件事:普通用户能看到全局文件并绑定使用,
|
* 但不能删除或重新向量化它们 —— 那会影响所有人。
|
*
|
* @param chatId 非空时只返回该会话绑定的文件
|
*/
|
List<FileDTO> list(Long userId, Long chatId);
|
|
/** 列出全部全局知识库文件(任何登录用户都能看到,用于绑定) */
|
List<FileDTO> listGlobal();
|
|
/** 删除文件记录与磁盘文件,同时清理向量集合;需有管理权限 */
|
void delete(Long userId, Long fileId);
|
|
/**
|
* 校验**管理权限**并返回实体。
|
*
|
* <p>权限规则:上传者本人,或任意管理员。
|
*/
|
UploadFile requireManageableFile(Long userId, Long fileId);
|
|
/**
|
* 把文件标记为全局 / 取消全局。仅管理员可操作。
|
*
|
* <p>切换后集合名会保持不变,因此已绑定的会话不受影响。
|
*/
|
FileDTO setGlobal(Long userId, Long fileId, boolean global);
|
|
/**
|
* 把已上传的文件送入 RAG 微服务做向量化。
|
*
|
* @return 更新后的文件信息(含 collectionName 与 chunkCount)
|
*/
|
FileDTO ingest(Long userId, Long fileId);
|
|
/** 读取磁盘文件内容为文本(供检索/预览),仅允许白名单内的纯文本类型 */
|
String readTextContent(UploadFile file);
|
|
/**
|
* 对已上传的图片做 OCR 文字识别。
|
*
|
* <p>与 {@link #readTextContent} 的区别:后者只读纯文本文件,
|
* 本方法专走 OCR 链路,用于图片。
|
*/
|
OcrResultDTO recognizeImage(Long userId, Long fileId);
|
|
/**
|
* 以 Spring Resource 形式读取文件内容(用于在消息里展示图片)。
|
*
|
* <p>与 {@link #readTextContent} 的区别:那个返回字符串且限纯文本,
|
* 本方法返回原始字节流,供 HTTP 响应直接输出。
|
*/
|
org.springframework.core.io.Resource loadAsResource(Long userId, Long fileId);
|
|
/**
|
* 返回当前用户**可检索**的集合名:自己上传并入库的 + 全部已入库的全局知识库。
|
*
|
* <p>这是知识库权限的核心方法:检索、绑定、健康检查都基于它,
|
* 保证「全局文件人人可用、私有文件互不可见」。
|
*/
|
List<String> accessibleCollections(Long userId);
|
}
|