package com.custom.webui.util; import com.custom.webui.dto.resp.MessageDTO; import com.custom.webui.dto.resp.StreamEvent; import com.custom.webui.entity.Message; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.util.ArrayList; import java.util.Comparator; import java.util.HashMap; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; import java.util.Objects; /** * 消息树组装工具。 * *

这是整个系统的核心逻辑之一。 * 数据库中的 message 表是完全扁平的,没有任何树形 JSON; * 这里把扁平列表在内存中还原成树,并顺带算出前端做分支切换所需的全部信息。 * *

算法(单遍 O(n)): *

    *
  1. 按 parentId 把所有消息分桶(LinkedHashMap 保证同层内按创建时间有序)
  2. *
  3. 从 parentId == null 的根节点出发递归挂载 children
  4. *
  5. 每层为兄弟节点写入 siblingCount / siblingIndex / siblingIds
  6. *
* *

容错处理: *

*/ public final class MessageTreeUtil { /** * 仅用于解析消息 metadata 的轻量 ObjectMapper。 * *

静态持有是刻意的:本类是纯工具类,方法都是 static,无法注入 Spring 的 * ObjectMapper。ObjectMapper 本身线程安全(配置完成后),因此静态实例没问题。 */ private static final ObjectMapper MAPPER = new ObjectMapper() .configure(com.fasterxml.jackson.databind.DeserializationFeature .FAIL_ON_UNKNOWN_PROPERTIES, false); private MessageTreeUtil() { } /** * 把扁平消息列表组装成消息树。 * * @param flatMessages 同一会话的所有消息,顺序不限 * @return 根节点列表(通常只有一个根:会话的第一条 user 消息) */ public static List buildTree(List flatMessages) { if (flatMessages == null || flatMessages.isEmpty()) { return new ArrayList<>(); } // 1. 全部实体转 DTO,并建立 id -> DTO 的索引 Map dtoById = new HashMap<>(flatMessages.size() * 2); for (Message m : flatMessages) { if (m == null || m.getId() == null) { continue; } dtoById.put(m.getId(), toDto(m)); } // 2. 按 parentId 分桶;parentId 为 null 的进 roots 桶 Map> childrenByParent = new LinkedHashMap<>(); List roots = new ArrayList<>(); for (MessageDTO dto : dtoById.values()) { Long parentId = dto.getParentId(); // 孤儿节点:父消息不在本次结果集内,上浮为根,避免消息丢失 if (parentId == null || !dtoById.containsKey(parentId)) { roots.add(dto); } else { childrenByParent.computeIfAbsent(parentId, k -> new ArrayList<>()).add(dto); } } // 3. 同层排序:按创建时间升序,时间相同用 id 兜底,保证顺序稳定可复现 Comparator siblingOrder = Comparator .comparing(MessageDTO::getCreatedAt, Comparator.nullsLast(Comparator.naturalOrder())) .thenComparing(MessageDTO::getId, Comparator.nullsLast(Comparator.naturalOrder())); roots.sort(siblingOrder); childrenByParent.values().forEach(list -> list.sort(siblingOrder)); // 4. 递归挂载子节点,同时写入兄弟序号等分支元数据 List visited = new ArrayList<>(); for (MessageDTO root : roots) { attach(root, childrenByParent, visited); } // 5. 为根层也补齐兄弟信息(正常情况下只有 1 个根) applySiblingInfo(roots); return roots; } /** * 递归挂载:把 node 的子节点接上,并设置 node.activeChildId。 * * @param path 当前递归路径,用于检测脏数据造成的环 */ private static void attach(MessageDTO node, Map> childrenByParent, List path) { // 成环保护:同一节点在同一条递归路径上出现第二次说明数据有环 if (path.contains(node)) { return; } path.add(node); List children = childrenByParent.get(node.getId()); if (children != null && !children.isEmpty()) { applySiblingInfo(children); for (MessageDTO child : children) { node.addChild(child); attach(child, childrenByParent, path); } // activeChildId 默认取最后一条子消息: // 重新生成场景下最后生成的 assistant 回复就是用户当前正在看的分支 node.setActiveChildId(children.get(children.size() - 1).getId()); } path.remove(path.size() - 1); } /** 为一组兄弟节点写入 siblingCount / siblingIndex / siblingIds。 */ private static void applySiblingInfo(List siblings) { if (siblings == null || siblings.isEmpty()) { return; } List ids = new ArrayList<>(siblings.size()); for (MessageDTO s : siblings) { ids.add(s.getId()); } int total = siblings.size(); for (int i = 0; i < total; i++) { MessageDTO s = siblings.get(i); s.setSiblingIds(ids); s.setSiblingCount(total); s.setSiblingIndex(i + 1); } } /** * 实体转 DTO。{@code done} 在库里是 tinyint,可能为 null, * 这里统一兜底为 true,避免历史脏数据被前端误判为「生成中」。 */ public static MessageDTO toDto(Message m) { MessageDTO dto = new MessageDTO(); dto.setId(m.getId()); dto.setChatId(m.getChatId()); dto.setParentId(m.getParentId()); dto.setRole(m.getRole()); dto.setContent(m.getContent() == null ? "" : m.getContent()); dto.setModel(m.getModel()); dto.setDone(m.getDone() == null || Boolean.TRUE.equals(m.getDone())); dto.setMetadata(m.getMetadata()); dto.setCreatedAt(m.getCreatedAt()); // 从 metadata 里还原 RAG 引用来源。 // 生成时来源是随 done 事件发给前端的,但那条 SSE 连接早已结束; // 不在这里还原的话,刷新页面后「这条回答引用了哪些文档」就丢了。 dto.setSources(extractSources(m.getMetadata())); dto.setImageFileIds(extractImageFileIds(m.getMetadata())); dto.setImageText(extractImageText(m.getMetadata())); return dto; } /** * 从消息 metadata JSON 中提取 RAG 引用来源。 * *

metadata 形如: *

     * {"model":"qwen2.5:7b","finishedAt":"...",
     *  "ragSources":[{"filename":"a.pdf","section":"2.1 消息树","score":0.24}]}
     * 
* *

容错:metadata 为 null、不是合法 JSON、没有 ragSources、或元素解析失败时, * 一律返回空列表 —— 历史消息本就没有引用信息,不该因此导致接口 500。 */ private static List extractSources(String metadataJson) { if (metadataJson == null || metadataJson.isBlank()) { return new ArrayList<>(); } try { JsonNode root = MAPPER.readTree(metadataJson); JsonNode arr = root.get("ragSources"); if (arr == null || !arr.isArray()) { return new ArrayList<>(); } List sources = new ArrayList<>(arr.size()); for (JsonNode node : arr) { StreamEvent.Source source = new StreamEvent.Source(); source.setFilename(textOrNull(node, "filename")); source.setSection(textOrNull(node, "section")); source.setSnippet(textOrNull(node, "snippet")); source.setCollectionName(textOrNull(node, "collectionName")); if (node.hasNonNull("score")) { source.setScore(node.get("score").asDouble()); } if (node.hasNonNull("chunkIndex")) { source.setChunkIndex(node.get("chunkIndex").asInt()); } sources.add(source); } return sources; } catch (Exception e) { // 不打印堆栈级别,脏 metadata 不值得刷满日志 return new ArrayList<>(); } } /** * 从 metadata 中还原随消息上传的图片 id 列表。 * *

与 {@link #extractSources} 同样的容错策略:任何异常都返回空列表, * 历史消息本就没有图片,不该因此让接口失败。 */ private static List extractImageFileIds(String metadataJson) { List ids = new ArrayList<>(); if (metadataJson == null || metadataJson.isBlank()) { return ids; } try { JsonNode arr = MAPPER.readTree(metadataJson).get("imageFileIds"); if (arr == null || !arr.isArray()) { return ids; } for (JsonNode node : arr) { if (node.isNumber()) { ids.add(node.asLong()); } } } catch (Exception e) { // 脏 metadata 不值得刷日志 } return ids; } /** 还原随消息上传图片的 OCR 文字;没有则返回 null */ private static String extractImageText(String metadataJson) { if (metadataJson == null || metadataJson.isBlank()) { return null; } try { JsonNode node = MAPPER.readTree(metadataJson).get("imageText"); return node == null || node.isNull() ? null : node.asText(); } catch (Exception e) { return null; } } private static String textOrNull(JsonNode node, String field) { JsonNode value = node.get(field); return value == null || value.isNull() ? null : value.asText(); } /** * 沿着 parentId 向上回溯,返回从根到指定消息的链路(含自身),按时间正序。 * *

用途:构造 LLM 上下文。发送新消息时需要把「当前分支」的历史带进 prompt, * 而当前分支就是新消息 parentId 的祖先链。 * 若某个父节点已被删除形成断链,回溯会提前停止并返回已收集的部分, * 保证请求不会因为脏数据而失败。 */ public static List pathToRoot(Map byId, Long leafId) { List chain = new ArrayList<>(); Long cursor = leafId; int guard = 0; int limit = byId.size() + 1; while (cursor != null && guard++ <= limit) { Message node = byId.get(cursor); if (node == null) { break; } chain.add(node); cursor = node.getParentId(); } // 回溯得到的是 leaf -> root,反转成 root -> leaf java.util.Collections.reverse(chain); return chain; } /** 判断一条消息是否属于指定的聊天,用于越权访问校验。 */ public static boolean belongsToChat(Message m, Long chatId) { return m != null && Objects.equals(m.getChatId(), chatId); } }