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 { /** * 保存上传文件。 * *
安全校验顺序(任一失败即拒绝,不落盘): *
「可见」与「可管理」是两件事:普通用户能看到全局文件并绑定使用,
* 但不能删除或重新向量化它们 —— 那会影响所有人。
*
* @param chatId 非空时只返回该会话绑定的文件
*/
List 权限规则:上传者本人,或任意管理员。
*/
UploadFile requireManageableFile(Long userId, Long fileId);
/**
* 把文件标记为全局 / 取消全局。仅管理员可操作。
*
* 切换后集合名会保持不变,因此已绑定的会话不受影响。
*/
FileDTO setGlobal(Long userId, Long fileId, boolean global);
/**
* 把已上传的文件送入 RAG 微服务做向量化。
*
* @return 更新后的文件信息(含 collectionName 与 chunkCount)
*/
FileDTO ingest(Long userId, Long fileId);
/** 读取磁盘文件内容为文本(供检索/预览),仅允许白名单内的纯文本类型 */
String readTextContent(UploadFile file);
/**
* 对已上传的图片做 OCR 文字识别。
*
* 与 {@link #readTextContent} 的区别:后者只读纯文本文件,
* 本方法专走 OCR 链路,用于图片。
*/
OcrResultDTO recognizeImage(Long userId, Long fileId);
/**
* 以 Spring Resource 形式读取文件内容(用于在消息里展示图片)。
*
* 与 {@link #readTextContent} 的区别:那个返回字符串且限纯文本,
* 本方法返回原始字节流,供 HTTP 响应直接输出。
*/
org.springframework.core.io.Resource loadAsResource(Long userId, Long fileId);
/**
* 返回当前用户**可检索**的集合名:自己上传并入库的 + 全部已入库的全局知识库。
*
* 这是知识库权限的核心方法:检索、绑定、健康检查都基于它,
* 保证「全局文件人人可用、私有文件互不可见」。
*/
List