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
package com.custom.webui.service;
 
import com.custom.webui.dto.req.ChatCreateRequest;
import com.custom.webui.dto.req.ChatMetaRequest;
import com.custom.webui.dto.req.ChatUpdateRequest;
import com.custom.webui.dto.resp.ChatDTO;
import com.custom.webui.entity.Chat;
 
import java.util.List;
 
/**
 * 会话服务。
 *
 * <p><b>数据隔离约定</b>:所有方法都必须接收 {@code userId} 并在查询条件中带上,
 * 严禁提供「按 id 直接查」的公开方法 —— 越权访问是这类系统最常见的安全问题。
 */
public interface ChatService {
 
    /** 当前用户的会话列表,按更新时间倒序(最近活跃的在最上方) */
    List<ChatDTO> listByUser(Long userId);
 
    /** 新建会话,title 为空时使用默认「新对话」 */
    ChatDTO create(Long userId, ChatCreateRequest request);
 
    /**
     * 修改标题或模型参数,字段为 null 表示不修改。
     *
     * @throws com.custom.webui.exception.BusinessException 会话不存在或不属于该用户(404/403)
     */
    ChatDTO update(Long userId, Long chatId, ChatUpdateRequest request);
 
    /**
     * 删除会话,级联删除其下所有消息、文件绑定与知识库绑定。
     *
     * <p>数据库未使用外键,级联在 Service 层显式完成,便于控制与测试。
     */
    void delete(Long userId, Long chatId);
 
    /** 校验会话归属,返回实体;不属于该用户时抛 404(而非 403,避免探测他人会话是否存在) */
    Chat requireOwnedChat(Long userId, Long chatId);
 
    /** 读取会话的模型参数,meta 为空或非法 JSON 时返回全 null 的对象 */
    ChatMetaRequest parseMeta(Chat chat);
 
    /** 更新会话标题(用于 LLM 自动生成标题) */
    void updateTitle(Long chatId, String title);
 
    /**
     * 搜索当前用户的历史对话。
     *
     * <p>同时匹配**标题**与**消息内容** —— 只搜标题不够用:
     * 用户往往记得「聊过某个话题」却想不起原话,而标题只是首条提问的截断。
     *
     * <p>排序:命中的会话按最近活跃时间倒序,最多返回 {@code limit} 条。
     *
     * @param keyword 关键词,空白则返回空列表(不返回全部,避免把搜索框
     *                当成「无过滤列表」误用)
     * @return 命中的会话,附带命中片段与命中类型
     */
    List<ChatDTO> search(Long userId, String keyword, int limit);
}