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 {
|
|
/**
|
* 当前用户的会话列表。
|
*
|
* <p>排序固定为「置顶优先」:
|
* <pre>
|
* ORDER BY pinned DESC, pinned_at DESC, updated_at DESC
|
* </pre>
|
* 置顶区内按置顶时间倒序(最近钉上去的在最前),
|
* 非置顶区里 pinned_at 全为 NULL,于是自然退化为「按最近活跃倒序」。
|
*
|
* @param archived false = 主列表(未归档);true = 归档列表
|
*/
|
List<ChatDTO> listByUser(Long userId, boolean archived);
|
|
/** 新建会话,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);
|
|
/**
|
* 把会话移入 / 移出分组。
|
*
|
* <p>单独一个方法而不是塞进 {@link #update}:那里的约定是
|
* 「字段为 null 表示不修改」,而「移出分组」正是要把 groupId 置为 null,
|
* 同一个字段上无法同时表达这两种语义。
|
*
|
* @param groupId 目标分组 id;null 表示移出分组
|
* @throws com.custom.webui.exception.BusinessException 会话不属于该用户(404),
|
* 或目标分组不存在 / 不属于该用户(404)
|
*/
|
ChatDTO moveToGroup(Long userId, Long chatId, Long groupId);
|
|
/** 读取会话的模型参数,meta 为空或非法 JSON 时返回全 null 的对象 */
|
ChatMetaRequest parseMeta(Chat chat);
|
|
/** 更新会话标题(用于 LLM 自动生成标题) */
|
void updateTitle(Long chatId, String title);
|
|
/**
|
* 搜索当前用户的历史对话。
|
*
|
* <p>同时匹配**标题**与**消息内容** —— 只搜标题不够用:
|
* 用户往往记得「聊过某个话题」却想不起原话,而标题只是首条提问的截断。
|
*
|
* <p>排序:命中的会话按最近活跃时间倒序,最多返回 {@code limit} 条。
|
*
|
* @param keyword 关键词,空白则返回空列表(不返回全部,避免把搜索框
|
* 当成「无过滤列表」误用)
|
* @param archived 搜索范围:false = 未归档(与主列表一致),true = 归档
|
* @return 命中的会话,附带命中片段与命中类型
|
*/
|
List<ChatDTO> search(Long userId, String keyword, int limit, boolean archived);
|
}
|