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 { /** * 保存上传文件。 * *

安全校验顺序(任一失败即拒绝,不落盘): *

    *
  1. 文件非空、大小在限制内
  2. *
  3. 扩展名在白名单内 —— 防止上传 jsp/exe 等可执行文件
  4. *
  5. 原始文件名做净化,存储名由服务端生成 UUID, * 彻底消除 {@code ../} 路径穿越的可能
  6. *
* * @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); /** * 当前用户**可管理**的文件列表(自己上传的 + 管理员上传的全局文件)。 * *

「可见」与「可管理」是两件事:普通用户能看到全局文件并绑定使用, * 但不能删除或重新向量化它们 —— 那会影响所有人。 * * @param chatId 非空时只返回该会话绑定的文件 */ List list(Long userId, Long chatId); /** 列出全部全局知识库文件(任何登录用户都能看到,用于绑定) */ List listGlobal(); /** 删除文件记录与磁盘文件,同时清理向量集合;需有管理权限 */ void delete(Long userId, Long fileId); /** * 校验**管理权限**并返回实体。 * *

权限规则:上传者本人,或任意管理员。 */ 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 accessibleCollections(Long userId); }