package com.custom.webui.service; import com.custom.webui.dto.resp.CategoryDTO; import com.custom.webui.entity.KbCategory; import java.util.List; /** * 知识库分类服务。 * *

把文档归类,使绑定时可以「整类绑定」到会话,不必逐个勾选。 * *

可见性与权限规则(与文件保持一致): *

*/ public interface CategoryService { /** * 当前用户可见的分类列表,带文档数与已入库集合名。 * * @param chatId 传入时额外标记每个分类「是否已绑定到该会话」, * 前端可据此把已绑定的分类显示为选中态 */ List 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); /** * 删除分类。 * *

分类内的文档不会被删除,只是变为「未分类」—— * 用户想删的是分类,不是里面的资料,静默删文件是不可接受的。 */ void delete(Long userId, Long categoryId); /** * 把文档归入某个分类(categoryId 为 null 表示移出分类)。 * *

会校验分类与文档的可见范围匹配:全局分类只装全局文档, * 私有分类只装自己的文档,避免出现越权组合。 */ void assignFile(Long userId, Long fileId, Long categoryId); /** 校验分类归属并返回实体(要求管理权限:自己的分类,或本人是管理员) */ KbCategory requireManageable(Long userId, Long categoryId); /** * 校验分类对当前用户**可见**并返回实体。 * *

与 {@link #requireManageable} 的区别:只要求可见即可 * (自己的分类,或全局分类),用于「绑定使用」这类不需要管理权限的场景 —— * 普通用户必须能绑定管理员创建的全局分类。 */ KbCategory requireVisibleForUser(Long userId, Long categoryId); /** * 展开某个分类下所有**已入库**文档的集合名。 * *

这是「整类绑定」的核心:一次拿到分类内全部可检索集合。 */ List collectionsOfCategory(Long userId, Long categoryId); }