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
package com.custom.webui.service;
 
import com.custom.webui.dto.resp.CategoryDTO;
import com.custom.webui.entity.KbCategory;
 
import java.util.List;
 
/**
 * 知识库分类服务。
 *
 * <p>把文档归类,使绑定时可以「整类绑定」到会话,不必逐个勾选。
 *
 * <p><b>可见性与权限规则</b>(与文件保持一致):
 * <ul>
 *   <li>可见 = 自己创建的分类 + 全部全局分类</li>
 *   <li>可管理 = 自己创建的分类,或本人是管理员</li>
 *   <li>只有管理员能创建全局分类</li>
 * </ul>
 */
public interface CategoryService {
 
    /**
     * 当前用户可见的分类列表,带文档数与已入库集合名。
     *
     * @param chatId 传入时额外标记每个分类「是否已绑定到该会话」,
     *               前端可据此把已绑定的分类显示为选中态
     */
    List<CategoryDTO> listVisible(Long userId, Long chatId);
 
    /** 创建分类;管理员可创建全局分类 */
    CategoryDTO create(Long userId, String name, String description, boolean global);
 
    /** 重命名 / 修改说明 */
    CategoryDTO update(Long userId, Long categoryId, String name, String description);
 
    /**
     * 删除分类。
     *
     * <p><b>分类内的文档不会被删除</b>,只是变为「未分类」——
     * 用户想删的是分类,不是里面的资料,静默删文件是不可接受的。
     */
    void delete(Long userId, Long categoryId);
 
    /**
     * 把文档归入某个分类(categoryId 为 null 表示移出分类)。
     *
     * <p>会校验分类与文档的可见范围匹配:全局分类只装全局文档,
     * 私有分类只装自己的文档,避免出现越权组合。
     */
    void assignFile(Long userId, Long fileId, Long categoryId);
 
    /** 校验分类归属并返回实体(要求管理权限:自己的分类,或本人是管理员) */
    KbCategory requireManageable(Long userId, Long categoryId);
 
    /**
     * 校验分类对当前用户**可见**并返回实体。
     *
     * <p>与 {@link #requireManageable} 的区别:只要求可见即可
     * (自己的分类,或全局分类),用于「绑定使用」这类不需要管理权限的场景 ——
     * 普通用户必须能绑定管理员创建的全局分类。
     */
    KbCategory requireVisibleForUser(Long userId, Long categoryId);
 
    /**
     * 展开某个分类下所有**已入库**文档的集合名。
     *
     * <p>这是「整类绑定」的核心:一次拿到分类内全部可检索集合。
     */
    List<String> collectionsOfCategory(Long userId, Long categoryId);
}