kongdeqiang
2026-10-09 9af621d181217a03b1b3dce208a163915db974a3
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
package com.custom.webui.service.impl;
 
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.custom.webui.config.props.RagProperties;
import com.custom.webui.config.props.StorageProperties;
import com.custom.webui.security.CurrentUser;
import com.custom.webui.dto.resp.FileDTO;
import com.custom.webui.dto.resp.OcrResultDTO;
import com.custom.webui.entity.RagCollection;
import com.custom.webui.entity.UploadFile;
import com.custom.webui.exception.BusinessException;
import com.custom.webui.entity.KbCategory;
import com.custom.webui.mapper.KbCategoryMapper;
import com.custom.webui.mapper.RagCollectionMapper;
import com.custom.webui.mapper.UploadFileMapper;
import com.custom.webui.service.FileService;
import com.custom.webui.service.CategoryService;
import com.custom.webui.service.RagProxyService;
import com.custom.webui.util.StoragePathUtil;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.multipart.MultipartFile;
 
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.UUID;
 
/**
 * 文件与知识库服务实现。
 *
 * <p><b>安全设计(重点)</b>:
 * <ol>
 *   <li><b>扩展名白名单</b>:只允许配置中列出的类型,杜绝上传 .jsp/.php/.sh 等可执行文件</li>
 *   <li><b>服务端生成存储名</b>:磁盘文件名是 {@code UUID.扩展名},
 *       完全丢弃用户提供的文件名,从根上消除 {@code ../../etc/passwd} 式的路径穿越</li>
 *   <li><b>目录按日期分片</b>:{@code 2025/01/15/uuid.pdf},避免单目录文件过多导致
 *       ext4/NTFS 的目录项查找退化成线性扫描</li>
 *   <li><b>规范化后校验前缀</b>:写入前用 {@code toRealPath} 规范化,
 *       并断言最终路径确实位于存储根目录下 —— 防御符号链接攻击</li>
 * </ol>
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class FileServiceImpl implements FileService {
 
    private static final DateTimeFormatter DATE_DIR_FORMAT = DateTimeFormatter.ofPattern("yyyy/MM/dd");
 
    private final UploadFileMapper uploadFileMapper;
    private final RagCollectionMapper ragCollectionMapper;
    private final KbCategoryMapper kbCategoryMapper;
    private final StorageProperties storageProperties;
    private final RagProperties ragProperties;
    private final RagProxyService ragProxyService;
    private final CategoryService categoryService;
 
    // ============================================================
    // 上传
    // ============================================================
 
    @Override
    @Transactional(rollbackFor = Exception.class)
    public FileDTO upload(Long userId, Long chatId, MultipartFile file, boolean autoIngest,
                          Long categoryId) {
        // 普通上传一律私有:即使调用者是管理员,想设成全局必须显式走
        // uploadGlobal 或事后调用 setGlobal —— 避免误把私人文件暴露给全员
        FileDTO uploaded = saveUpload(userId, chatId, file, false);
        applyCategory(userId, uploaded, categoryId);
        return autoIngest ? tryAutoIngest(userId, uploaded) : uploaded;
    }
 
    @Override
    @Transactional(rollbackFor = Exception.class)
    public FileDTO uploadGlobal(Long userId, MultipartFile file, boolean autoIngest,
                                Long categoryId) {
        requireAdmin();
        log.info("管理员上传全局知识库 userId={} name={} autoIngest={}",
                userId, file == null ? null : file.getOriginalFilename(), autoIngest);
        // 全局文件不绑定具体会话(chatId=null),它面向所有会话
        FileDTO uploaded = saveUpload(userId, null, file, true);
        applyCategory(userId, uploaded, categoryId);
        return autoIngest ? tryAutoIngest(userId, uploaded) : uploaded;
    }
 
    /**
     * 上传后归类。
     *
     * <p>归类失败**不抛异常**:文件已经上传成功,因为分类参数有问题
     * 就把整个上传判为失败,用户会以为文件丢了。改为记日志 + 文件保持未分类,
     * 用户可以在界面上重新归类。
     */
    private void applyCategory(Long userId, FileDTO uploaded, Long categoryId) {
        if (uploaded == null || uploaded.getId() == null || categoryId == null) {
            return;
        }
        try {
            categoryService.assignFile(userId, uploaded.getId(), categoryId);
            uploaded.setCategoryId(categoryId);
        } catch (Exception e) {
            log.warn("上传后归类失败,文件保持未分类 fileId={} categoryId={} err={}",
                    uploaded.getId(), categoryId, e.getMessage());
            uploaded.setCategoryId(null);
        }
    }
 
    /**
     * 上传后自动向量化。
     *
     * <p><b>失败不抛异常</b>,而是把原因写进返回的 {@code ingestMessage}。
     * 理由:文件已经成功落盘并入库(元数据),此时因为 embedding 服务不可用
     * 或代理问题把整个上传判为失败,会让用户以为文件丢了 —— 而实际上文件好好的,
     * 只是暂时没向量化,修好环境后点一次「向量化」即可。
     */
    private FileDTO tryAutoIngest(Long userId, FileDTO uploaded) {
        if (uploaded == null || uploaded.getId() == null) {
            return uploaded;
        }
        try {
            log.info("上传后自动向量化 fileId={} name={}", uploaded.getId(), uploaded.getFilename());
            return ingest(userId, uploaded.getId());
        } catch (Exception e) {
            log.warn("自动向量化失败,文件已保存,可稍后手动重试 fileId={} err={}",
                    uploaded.getId(), e.getMessage());
            uploaded.setIngested(false);
            uploaded.setIngestMessage("自动向量化失败:" + e.getMessage()
                    + "(文件已保存,可稍后点「向量化」重试)");
            return uploaded;
        }
    }
 
    /** 校验当前登录者是否为管理员,否则 403 */
    private void requireAdmin() {
        if (!CurrentUser.isAdmin()) {
            throw BusinessException.forbidden("只有管理员可以维护全局知识库");
        }
    }
 
    /**
     * 上传文件的共用实现。
     *
     * @param isGlobal true 表示全局知识库(仅管理员可传入)
     */
    private FileDTO saveUpload(Long userId, Long chatId, MultipartFile file, boolean isGlobal) {
        if (file == null || file.isEmpty()) {
            throw BusinessException.badRequest("上传文件为空");
        }
        if (file.getSize() > storageProperties.getMaxFileSize()) {
            throw BusinessException.badRequest(
                    "文件超过大小限制 " + (storageProperties.getMaxFileSize() / 1024 / 1024) + "MB");
        }
 
        // 原始文件名可能包含路径,先剥掉目录部分
        String originalName = sanitizeFilename(file.getOriginalFilename());
        String extension = extractExtension(originalName);
 
        if (!storageProperties.getAllowedExtensions().contains(extension)) {
            throw BusinessException.badRequest(
                    "不支持的文件类型 ." + extension + ",允许的类型: "
                            + String.join(", ", storageProperties.getAllowedExtensions()));
        }
 
        // 存储名完全由服务端生成:UUID + 已校验的扩展名
        String storedName = UUID.randomUUID().toString().replace("-", "") + "." + extension;
        String dateDir = LocalDate.now().format(DATE_DIR_FORMAT);
 
        Path root = storageRoot();
        Path targetDir = root.resolve(dateDir).normalize();
 
        // 防御符号链接:确保目标目录确实在存储根目录之下
        if (!targetDir.startsWith(root)) {
            throw BusinessException.badRequest("非法的存储路径");
        }
 
        try {
            Files.createDirectories(targetDir);
            Path targetFile = targetDir.resolve(storedName).normalize();
            if (!targetFile.startsWith(root)) {
                throw BusinessException.badRequest("非法的存储路径");
            }
 
            try (var in = file.getInputStream()) {
                // 已存在同名(UUID 冲突概率极低)则覆盖;REPLACE_EXISTING 也避免重复上传报错
                Files.copy(in, targetFile, StandardCopyOption.REPLACE_EXISTING);
            }
 
            UploadFile entity = new UploadFile();
            entity.setUserId(userId);
            entity.setChatId(chatId);
            entity.setFilename(originalName);
            entity.setSavePath(targetFile.toString());
            entity.setFileSize(file.getSize());
            entity.setMimeType(file.getContentType());
            entity.setIsGlobal(isGlobal);
            entity.setCreatedAt(LocalDateTime.now());
            uploadFileMapper.insert(entity);
 
            log.info("文件上传成功 userId={} fileId={} name={} size={}B chatId={} 全局={}",
                    userId, entity.getId(), originalName, file.getSize(), chatId, isGlobal);
 
            return toDto(entity, null);
 
        } catch (IOException e) {
            log.error("文件写入失败 name={}", originalName, e);
            throw BusinessException.serverError("文件保存失败: " + e.getMessage());
        }
    }
 
    // ============================================================
    // 查询
    // ============================================================
 
    @Override
    public List<FileDTO> list(Long userId, Long chatId) {
        // 可见范围 = 自己上传的 + 全局知识库。
        // 用 OR 条件一次查完,而不是查两次再合并 —— 少一次往返,也不会漏。
        var query = Wrappers.<UploadFile>lambdaQuery()
                .and(w -> w.eq(UploadFile::getUserId, userId)
                        .or()
                        .eq(UploadFile::getIsGlobal, true))
                .orderByDesc(UploadFile::getId);
        if (chatId != null) {
            query.eq(UploadFile::getChatId, chatId);
        }
        return attachCollectionInfo(uploadFileMapper.selectList(query));
    }
 
    @Override
    public List<FileDTO> listGlobal() {
        // 全局文件对任何登录用户都可见,不做用户过滤
        return attachCollectionInfo(uploadFileMapper.selectList(
                Wrappers.<UploadFile>lambdaQuery()
                        .eq(UploadFile::getIsGlobal, true)
                        .orderByDesc(UploadFile::getId)));
    }
 
    /** 批量补充 RAG 集合信息并转 DTO,避免逐个文件查库造成 N+1 */
    private List<FileDTO> attachCollectionInfo(List<UploadFile> files) {
        if (files == null || files.isEmpty()) {
            return Collections.emptyList();
        }
 
        List<Long> fileIds = files.stream().map(UploadFile::getId).toList();
        var collections = ragCollectionMapper.selectList(
                Wrappers.<RagCollection>lambdaQuery().in(RagCollection::getFileId, fileIds));
        var byFileId = new java.util.HashMap<Long, RagCollection>();
        for (RagCollection c : collections) {
            byFileId.put(c.getFileId(), c);
        }
 
        Long currentUserId = CurrentUser.requireUserId();
        boolean admin = CurrentUser.isAdmin();
 
        // 一次取出涉及到的分类名,避免逐条查库
        Map<Long, String> categoryNames = new HashMap<>();
        List<Long> categoryIds = files.stream()
                .map(UploadFile::getCategoryId)
                .filter(Objects::nonNull)
                .distinct()
                .toList();
        if (!categoryIds.isEmpty()) {
            for (KbCategory c : kbCategoryMapper.selectBatchIds(categoryIds)) {
                categoryNames.put(c.getId(), c.getName());
            }
        }
 
        List<FileDTO> result = new ArrayList<>(files.size());
        for (UploadFile f : files) {
            FileDTO dto = toDto(f, byFileId.get(f.getId()));
            // 批量场景下用上面一次查好的映射覆盖,避免逐条查库
            if (f.getCategoryId() != null && categoryNames.containsKey(f.getCategoryId())) {
                dto.setCategoryName(categoryNames.get(f.getCategoryId()));
            }
            // 可管理 = 自己上传的,或本人是管理员。
            // 注意:可见 ≠ 可管理。普通用户能看到全局知识库并绑定使用,
            // 但不能删除或重新向量化 —— 那会影响所有人的检索结果。
            dto.setCanManage(admin || Objects.equals(f.getUserId(), currentUserId));
            result.add(dto);
        }
        return result;
    }
 
    @Override
    @Transactional(rollbackFor = Exception.class)
    public FileDTO setGlobal(Long userId, Long fileId, boolean global) {
        requireAdmin();
        UploadFile file = requireManageableFile(userId, fileId);
 
        UploadFile patch = new UploadFile();
        patch.setId(fileId);
        patch.setIsGlobal(global);
        uploadFileMapper.updateById(patch);
 
        log.info("管理员{}全局知识库 fileId={} name={}",
                global ? "设为" : "取消", fileId, file.getFilename());
 
        // 集合名与 isGlobal 无关,因此已绑定该知识库的会话不受影响
        List<FileDTO> refreshed = attachCollectionInfo(List.of(uploadFileMapper.selectById(fileId)));
        return refreshed.isEmpty() ? toDto(file, null) : refreshed.get(0);
    }
 
    @Override
    public List<String> accessibleCollections(Long userId) {
        // 自己已入库的
        List<String> own = ragCollectionMapper.selectList(
                        Wrappers.<RagCollection>lambdaQuery()
                                .eq(RagCollection::getUserId, userId)
                                .eq(RagCollection::getStatus, RagCollection.STATUS_READY))
                .stream().map(RagCollection::getCollectionName).toList();
 
        // 全局已入库的:先找出全部全局文件,再取它们对应的集合
        List<Long> globalFileIds = uploadFileMapper.selectList(
                        Wrappers.<UploadFile>lambdaQuery()
                                .select(UploadFile::getId)
                                .eq(UploadFile::getIsGlobal, true))
                .stream().map(UploadFile::getId).toList();
 
        List<String> global = globalFileIds.isEmpty()
                ? Collections.emptyList()
                : ragCollectionMapper.selectList(
                                Wrappers.<RagCollection>lambdaQuery()
                                        .in(RagCollection::getFileId, globalFileIds)
                                        .eq(RagCollection::getStatus, RagCollection.STATUS_READY))
                        .stream().map(RagCollection::getCollectionName).toList();
 
        List<String> all = new ArrayList<>(own.size() + global.size());
        all.addAll(own);
        // 去重:理论上不会重叠(own 按 userId,global 按 isGlobal),
        // 但管理员既上传了全局文件、自己又入库过同一个文件时可能重复
        for (String c : global) {
            if (!all.contains(c)) {
                all.add(c);
            }
        }
        return all;
    }
 
    @Override
    public UploadFile requireManageableFile(Long userId, Long fileId) {
        UploadFile file = uploadFileMapper.selectById(fileId);
        if (file == null) {
            throw BusinessException.notFound("文件不存在或无权访问");
        }
        // 权限:上传者本人,或任意管理员(管理员要能维护全局知识库)
        boolean isOwner = file.getUserId() != null && file.getUserId().equals(userId);
        if (!isOwner && !CurrentUser.isAdmin()) {
            // 统一返回 404 而非 403:避免暴露「这个 id 存在但不属于你」的信息
            throw BusinessException.notFound("文件不存在或无权访问");
        }
        return file;
    }
 
    // ============================================================
    // 删除
    // ============================================================
 
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void delete(Long userId, Long fileId) {
        UploadFile file = requireManageableFile(userId, fileId);
 
        // 先清理向量集合,再删元数据;顺序很重要:
        // 若先删元数据而向量清理失败,就会留下永远无法定位的僵尸向量数据。
        List<RagCollection> collections = ragCollectionMapper.selectList(
                Wrappers.<RagCollection>lambdaQuery().eq(RagCollection::getFileId, fileId));
        for (RagCollection c : collections) {
            try {
                ragProxyService.deleteCollection(c.getCollectionName());
            } catch (Exception e) {
                log.warn("删除向量集合失败 collection={} err={}", c.getCollectionName(), e.getMessage());
            }
        }
        ragCollectionMapper.delete(Wrappers.<RagCollection>lambdaQuery().eq(RagCollection::getFileId, fileId));
 
        // 删除磁盘文件:失败只告警不中断,避免因为文件被占用导致记录删不掉
        try {
            Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath());
            boolean deleted = Files.deleteIfExists(path);
            log.debug("磁盘文件删除 fileId={} path={} deleted={}", fileId, file.getSavePath(), deleted);
        } catch (IOException e) {
            log.warn("磁盘文件删除失败 fileId={} err={}", fileId, e.getMessage());
        }
 
        uploadFileMapper.deleteById(fileId);
        log.info("文件删除完成 userId={} fileId={} name={}", userId, fileId, file.getFilename());
    }
 
    // ============================================================
    // 向量化入库
    // ============================================================
 
    /**
     * 把文件送入 Python 服务做向量化。
     *
     * <p><b>刻意不加 {@code @Transactional}</b>:向量化是一次可能持续数分钟的
     * 外部 HTTP 调用。若把它包在事务里,一个数据库连接会被占住直到调用结束,
     * 并发十几个文档入库就能耗尽连接池,让整个系统不可用。
     * 这里改为「短事务分步提交」:
     * <ol>
     *   <li>写 pending 记录(独立提交)—— 保证崩了也能看到待处理痕迹</li>
     *   <li>无事务地调用 Python 服务</li>
     *   <li>写 ready/failed 结果(独立提交)</li>
     * </ol>
     */
    @Override
    public FileDTO ingest(Long userId, Long fileId) {
        UploadFile file = requireManageableFile(userId, fileId);
 
        if (!ragProperties.isEnabled()) {
            throw BusinessException.badRequest("RAG 功能已在配置中关闭(webui.rag.enabled=false)");
        }
 
        Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath());
        if (!Files.exists(path)) {
            throw BusinessException.badRequest("文件在磁盘上不存在,可能已被清理: " + file.getFilename());
        }
 
        // 集合名规则:user_{userId}_file_{fileId}
        // 用确定性命名而非随机名,使得重复入库可以幂等覆盖,不会产生重复集合。
        String collectionName = buildCollectionName(file);
 
        // 步骤 1:先写 pending 记录
        upsertPending(userId, fileId, collectionName);
 
        try {
            // 步骤 2:无事务地调用 Python 服务
            RagProxyService.IngestResult result =
                    ragProxyService.ingest(path, collectionName, userId);
 
            // 步骤 3:写回成功状态
            RagCollection record = findCollectionRecord(fileId, collectionName);
            if (record != null) {
                RagCollection patch = new RagCollection();
                patch.setId(record.getId());
                patch.setChunkCount(result.chunkCount());
                patch.setStatus(RagCollection.STATUS_READY);
                patch.setMessage(result.message());
                ragCollectionMapper.updateById(patch);
            }
 
            log.info("向量化入库成功 fileId={} collection={} chunks={}",
                    fileId, result.collectionName(), result.chunkCount());
 
            return toDto(file, findCollectionRecord(fileId, collectionName));
 
        } catch (Exception e) {
            log.error("向量化入库失败 fileId={} collection={}", fileId, collectionName, e);
 
            RagCollection record = findCollectionRecord(fileId, collectionName);
            if (record != null) {
                RagCollection patch = new RagCollection();
                patch.setId(record.getId());
                patch.setStatus(RagCollection.STATUS_FAILED);
                patch.setMessage(abbreviate(e.getMessage(), 500));
                ragCollectionMapper.updateById(patch);
            }
 
            throw e instanceof BusinessException be
                    ? be
                    : BusinessException.serverError("向量化失败: " + e.getMessage());
        }
    }
 
    // ============================================================
    // 文本读取
    // ============================================================
 
    @Override
    public OcrResultDTO recognizeImage(Long userId, Long fileId) {
        UploadFile file = requireManageableFile(userId, fileId);
        Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath());
        if (!Files.exists(path)) {
            throw BusinessException.badRequest("图片在磁盘上不存在: " + file.getFilename());
        }
        OcrResultDTO result = ragProxyService.recognizeImage(path);
        // 以用户上传时的原始文件名为准,OCR 服务返回的是磁盘存储名
        result.setFilename(file.getFilename());
        return result;
    }
 
    @Override
    public org.springframework.core.io.Resource loadAsResource(Long userId, Long fileId) {
        UploadFile file = requireManageableFile(userId, fileId);
        Path path = StoragePathUtil.resolve(storageRoot(), file.getSavePath());
        if (!Files.exists(path)) {
            throw BusinessException.notFound("文件在磁盘上不存在,可能已被清理");
        }
        try {
            return new org.springframework.core.io.FileSystemResource(path);
        } catch (Exception e) {
            throw BusinessException.serverError("读取文件失败: " + e.getMessage());
        }
    }
 
    @Override
    public String readTextContent(UploadFile file) {
        String extension = extractExtension(file.getFilename());
        // 只直接读取纯文本类,pdf/docx 必须走 Python 解析服务
        List<String> textTypes = List.of("txt", "md", "markdown", "csv", "json", "log");
        if (!textTypes.contains(extension)) {
            throw BusinessException.badRequest(
                    "文件类型 ." + extension + " 不是纯文本,请通过 RAG 服务解析");
        }
 
        long maxReadBytes = 5L * 1024 * 1024;
        if (file.getFileSize() != null && file.getFileSize() > maxReadBytes) {
            throw BusinessException.badRequest("文本文件超过 5MB,请通过 RAG 服务处理");
        }
 
        try {
            return Files.readString(
                    StoragePathUtil.resolve(storageRoot(), file.getSavePath()),
                    StandardCharsets.UTF_8);
        } catch (IOException e) {
            throw BusinessException.serverError("读取文件内容失败: " + e.getMessage());
        }
    }
 
    // ============================================================
    // 内部辅助
    // ============================================================
 
    /**
     * 清洗原始文件名:只保留最后的文件名部分,并剔除控制字符与路径分隔符。
     *
     * <p>即便存储名由 UUID 生成(用户文件名不参与落盘路径),
     * 这里的净化依然必要 —— 原始名会入库并回显到前端,
     * 未净化的名字可能被用来做 XSS 或误导用户(如伪装成 .exe)。
     */
    private String sanitizeFilename(String raw) {
        if (raw == null || raw.isBlank()) {
            return "unnamed";
        }
        // 去掉任何目录成分:同时处理 Unix 与 Windows 分隔符
        String name = raw.replace('\\', '/');
        int slash = name.lastIndexOf('/');
        if (slash >= 0) {
            name = name.substring(slash + 1);
        }
        // 剔除控制字符
        name = name.replaceAll("[\\p{Cntrl}]", "");
        // 剔除会干扰展示的引号与尖括号
        name = name.replaceAll("[<>\"']", "");
        name = name.trim();
        if (name.isEmpty() || ".".equals(name) || "..".equals(name)) {
            return "unnamed";
        }
        return name.length() > 255 ? name.substring(0, 255) : name;
    }
 
    /** 提取小写扩展名;无扩展名返回空串 */
    private String extractExtension(String filename) {
        int dot = filename.lastIndexOf('.');
        if (dot < 0 || dot == filename.length() - 1) {
            return "";
        }
        return filename.substring(dot + 1).toLowerCase(Locale.ROOT);
    }
 
    /** 配置的存储根目录(绝对路径),供路径兜底使用 */
    private Path storageRoot() {
        return Paths.get(storageProperties.getLocation()).toAbsolutePath().normalize();
    }
 
    /** 集合名:确定性生成,保证同一文件重复入库时幂等 */
    private String buildCollectionName(UploadFile file) {
        // 集合名用确定性规则生成(而非随机名),使重复入库幂等、不产生重复集合。
        // 全局文件用 global_ 前缀,运维在 Chroma 里一眼能分辨归属。
        if (Boolean.TRUE.equals(file.getIsGlobal())) {
            return "global_file_" + file.getId();
        }
        return "user_" + file.getUserId() + "_file_" + file.getId();
    }
 
    /** 不存在则插入 pending 记录,存在则重置为 pending */
    private void upsertPending(Long userId, Long fileId, String collectionName) {
        RagCollection existing = findCollectionRecord(fileId, collectionName);
        if (existing == null) {
            RagCollection record = new RagCollection();
            record.setUserId(userId);
            record.setFileId(fileId);
            record.setCollectionName(collectionName);
            record.setChunkCount(0);
            record.setStatus(RagCollection.STATUS_PENDING);
            record.setCreatedAt(LocalDateTime.now());
            ragCollectionMapper.insert(record);
        } else {
            RagCollection patch = new RagCollection();
            patch.setId(existing.getId());
            patch.setStatus(RagCollection.STATUS_PENDING);
            patch.setMessage(null);
            ragCollectionMapper.updateById(patch);
        }
    }
 
    private RagCollection findCollectionRecord(Long fileId, String collectionName) {
        return ragCollectionMapper.selectOne(
                Wrappers.<RagCollection>lambdaQuery()
                        .eq(RagCollection::getFileId, fileId)
                        .eq(RagCollection::getCollectionName, collectionName)
                        .last("LIMIT 1"));
    }
 
    private FileDTO toDto(UploadFile file, RagCollection collection) {
        FileDTO dto = new FileDTO();
        dto.setId(file.getId());
        dto.setFilename(file.getFilename());
        dto.setFileSize(file.getFileSize());
        dto.setMimeType(file.getMimeType());
        dto.setChatId(file.getChatId());
        dto.setCreatedAt(file.getCreatedAt());
        // 不暴露 savePath:服务器的磁盘布局属于内部实现细节
        dto.setIngested(collection != null && RagCollection.STATUS_READY.equals(collection.getStatus()));
        dto.setCollectionName(collection == null ? null : collection.getCollectionName());
        dto.setChunkCount(collection == null ? null : collection.getChunkCount());
        dto.setIngestMessage(collection == null ? null : collection.getMessage());
        // canManage 需要当前登录者信息,由 attachCollectionInfo 统一填充
        dto.setIsGlobal(Boolean.TRUE.equals(file.getIsGlobal()));
        dto.setCategoryId(file.getCategoryId());
        // 分类名在这里查一次(单条查询,代价可忽略)。
        // 不查的话,ingest / setGlobal 这些走 toDto 的接口会返回
        // categoryId 有值、categoryName 为 null 的不完整对象,
        // 前端展示会出现「有分类但显示不出名字」的不一致。
        if (file.getCategoryId() != null) {
            KbCategory category = kbCategoryMapper.selectById(file.getCategoryId());
            dto.setCategoryName(category == null ? null : category.getName());
        }
        return dto;
    }
 
    private String abbreviate(String s, int max) {
        if (s == null) {
            return null;
        }
        return s.length() <= max ? s : s.substring(0, max) + "...";
    }
}