kongdeqiang
2026-10-14 9f9e043849b6f497e00399900ff234cf097eba82
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
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);
}