diff --git a/docs/script/sql/update/update-0615-trace.sql b/docs/script/sql/update/update-0615-trace.sql
new file mode 100644
index 00000000..974d9f63
--- /dev/null
+++ b/docs/script/sql/update/update-0615-trace.sql
@@ -0,0 +1,128 @@
+-- 链路追踪运行记录表
+CREATE TABLE IF NOT EXISTS `trace_run` (
+ `id` bigint NOT NULL COMMENT '主键',
+ `trace_id` varchar(64) NOT NULL COMMENT '链路ID',
+ `trace_name` varchar(128) NOT NULL COMMENT '链路名称',
+ `business_type` varchar(64) NOT NULL COMMENT '业务类型',
+ `business_id` varchar(128) DEFAULT NULL COMMENT '业务ID',
+ `user_id` bigint DEFAULT NULL COMMENT '用户ID',
+ `tenant_id` varchar(20) DEFAULT '000000' COMMENT '租户编号',
+ `status` varchar(32) NOT NULL COMMENT '状态',
+ `start_time` datetime NOT NULL COMMENT '开始时间',
+ `end_time` datetime DEFAULT NULL COMMENT '结束时间',
+ `duration_ms` bigint DEFAULT NULL COMMENT '耗时毫秒',
+ `error_message` varchar(1000) DEFAULT NULL COMMENT '错误摘要',
+ `metadata` text DEFAULT NULL COMMENT '元数据JSON',
+ `create_dept` bigint DEFAULT NULL COMMENT '创建部门',
+ `create_by` bigint DEFAULT NULL COMMENT '创建者',
+ `create_time` datetime DEFAULT NULL COMMENT '创建时间',
+ `update_by` bigint DEFAULT NULL COMMENT '更新者',
+ `update_time` datetime DEFAULT NULL COMMENT '更新时间',
+ `del_flag` char(1) DEFAULT '0' COMMENT '删除标志（0代表存在 2代表删除）',
+ PRIMARY KEY (`id`) USING BTREE,
+ UNIQUE KEY `uk_trace_run_trace_id` (`trace_id`) USING BTREE,
+ KEY `idx_trace_run_business` (`business_type`, `business_id`) USING BTREE,
+ KEY `idx_trace_run_status_time` (`status`, `start_time`) USING BTREE,
+ KEY `idx_trace_run_tenant_time` (`tenant_id`, `start_time`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='链路追踪运行记录表' ROW_FORMAT=DYNAMIC;
+
+-- 链路追踪节点记录表
+CREATE TABLE IF NOT EXISTS `trace_node` (
+ `id` bigint NOT NULL COMMENT '主键',
+ `trace_id` varchar(64) NOT NULL COMMENT '链路ID',
+ `node_id` varchar(64) NOT NULL COMMENT '节点ID',
+ `tenant_id` varchar(20) DEFAULT '000000' COMMENT '租户编号',
+ `parent_node_id` varchar(64) DEFAULT NULL COMMENT '父节点ID',
+ `node_name` varchar(128) NOT NULL COMMENT '节点名称',
+ `node_type` varchar(64) NOT NULL COMMENT '节点类型',
+ `depth` int DEFAULT 0 COMMENT '节点深度',
+ `sort_order` int DEFAULT 0 COMMENT '排序',
+ `class_name` varchar(255) DEFAULT NULL COMMENT '类名',
+ `method_name` varchar(128) DEFAULT NULL COMMENT '方法名',
+ `status` varchar(32) NOT NULL COMMENT '状态',
+ `start_time` datetime NOT NULL COMMENT '开始时间',
+ `end_time` datetime DEFAULT NULL COMMENT '结束时间',
+ `duration_ms` bigint DEFAULT NULL COMMENT '耗时毫秒',
+ `error_message` varchar(1000) DEFAULT NULL COMMENT '错误摘要',
+ `input_payload` text DEFAULT NULL COMMENT '输入JSON',
+ `output_payload` text DEFAULT NULL COMMENT '输出JSON',
+ `metadata` text DEFAULT NULL COMMENT '元数据JSON',
+ `create_dept` bigint DEFAULT NULL COMMENT '创建部门',
+ `create_by` bigint DEFAULT NULL COMMENT '创建者',
+ `create_time` datetime DEFAULT NULL COMMENT '创建时间',
+ `update_by` bigint DEFAULT NULL COMMENT '更新者',
+ `update_time` datetime DEFAULT NULL COMMENT '更新时间',
+ `del_flag` char(1) DEFAULT '0' COMMENT '删除标志（0代表存在 2代表删除）',
+ PRIMARY KEY (`id`) USING BTREE,
+ KEY `idx_trace_node_trace_id` (`trace_id`) USING BTREE,
+ KEY `idx_trace_node_parent` (`trace_id`, `parent_node_id`) USING BTREE,
+ KEY `idx_trace_node_time` (`trace_id`, `start_time`) USING BTREE,
+ KEY `idx_trace_node_tenant_time` (`tenant_id`, `start_time`) USING BTREE,
+ KEY `idx_trace_node_type_status` (`node_type`, `status`) USING BTREE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='链路追踪节点记录表' ROW_FORMAT=DYNAMIC;
+
+-- 兼容已存在的旧 trace 表：CREATE TABLE IF NOT EXISTS 不会给旧表补新字段
+SET @trace_run_add_tenant_sql = (
+ SELECT IF(COUNT(*) = 0,
+ 'ALTER TABLE `trace_run` ADD COLUMN `tenant_id` varchar(20) DEFAULT ''000000'' COMMENT ''租户编号'' AFTER `user_id`',
+ 'SELECT 1'
+ )
+ FROM information_schema.COLUMNS
+ WHERE TABLE_SCHEMA = DATABASE()
+ AND TABLE_NAME = 'trace_run'
+ AND COLUMN_NAME = 'tenant_id'
+);
+PREPARE trace_run_add_tenant_stmt FROM @trace_run_add_tenant_sql;
+EXECUTE trace_run_add_tenant_stmt;
+DEALLOCATE PREPARE trace_run_add_tenant_stmt;
+
+SET @trace_run_add_tenant_idx_sql = (
+ SELECT IF(COUNT(*) = 0,
+ 'ALTER TABLE `trace_run` ADD INDEX `idx_trace_run_tenant_time` (`tenant_id`, `start_time`) USING BTREE',
+ 'SELECT 1'
+ )
+ FROM information_schema.STATISTICS
+ WHERE TABLE_SCHEMA = DATABASE()
+ AND TABLE_NAME = 'trace_run'
+ AND INDEX_NAME = 'idx_trace_run_tenant_time'
+);
+PREPARE trace_run_add_tenant_idx_stmt FROM @trace_run_add_tenant_idx_sql;
+EXECUTE trace_run_add_tenant_idx_stmt;
+DEALLOCATE PREPARE trace_run_add_tenant_idx_stmt;
+
+SET @trace_node_add_tenant_sql = (
+ SELECT IF(COUNT(*) = 0,
+ 'ALTER TABLE `trace_node` ADD COLUMN `tenant_id` varchar(20) DEFAULT ''000000'' COMMENT ''租户编号'' AFTER `node_id`',
+ 'SELECT 1'
+ )
+ FROM information_schema.COLUMNS
+ WHERE TABLE_SCHEMA = DATABASE()
+ AND TABLE_NAME = 'trace_node'
+ AND COLUMN_NAME = 'tenant_id'
+);
+PREPARE trace_node_add_tenant_stmt FROM @trace_node_add_tenant_sql;
+EXECUTE trace_node_add_tenant_stmt;
+DEALLOCATE PREPARE trace_node_add_tenant_stmt;
+
+SET @trace_node_add_tenant_idx_sql = (
+ SELECT IF(COUNT(*) = 0,
+ 'ALTER TABLE `trace_node` ADD INDEX `idx_trace_node_tenant_time` (`tenant_id`, `start_time`) USING BTREE',
+ 'SELECT 1'
+ )
+ FROM information_schema.STATISTICS
+ WHERE TABLE_SCHEMA = DATABASE()
+ AND TABLE_NAME = 'trace_node'
+ AND INDEX_NAME = 'idx_trace_node_tenant_time'
+);
+PREPARE trace_node_add_tenant_idx_stmt FROM @trace_node_add_tenant_idx_sql;
+EXECUTE trace_node_add_tenant_idx_stmt;
+DEALLOCATE PREPARE trace_node_add_tenant_idx_stmt;
+
+-- 链路追踪监控菜单 & 按钮权限
+INSERT INTO `sys_menu`
+(`menu_id`, `menu_name`, `parent_id`, `order_num`, `path`, `component`, `query_param`, `is_frame`, `is_cache`, `menu_type`, `visible`, `status`, `perms`, `icon`, `create_dept`, `create_by`, `create_time`, `remark`)
+SELECT (SELECT COALESCE(MAX(`menu_id`), 0) + 1 FROM (SELECT `menu_id` FROM `sys_menu`) t), '链路追踪', 2, 7, 'trace', 'monitor/trace/index', '', 1, 0, 'C', '0', '0', 'monitor:trace:list', 'tabler:route', 103, 1, NOW(), '链路追踪监控菜单';
+
+INSERT INTO `sys_menu`
+(`menu_id`, `menu_name`, `parent_id`, `order_num`, `path`, `component`, `query_param`, `is_frame`, `is_cache`, `menu_type`, `visible`, `status`, `perms`, `icon`, `create_dept`, `create_by`, `create_time`, `remark`)
+SELECT (SELECT COALESCE(MAX(`menu_id`), 0) + 1 FROM (SELECT `menu_id` FROM `sys_menu`) t), '链路追踪查询', (SELECT `menu_id` FROM `sys_menu` WHERE `perms` = 'monitor:trace:list' AND `menu_type` = 'C' LIMIT 1), 1, '#', '', '', 1, 0, 'F', '0', '0', 'monitor:trace:query', '#', 103, 1, NOW(), '';
diff --git a/ruoyi-admin/src/main/resources/application.yml b/ruoyi-admin/src/main/resources/application.yml
index 14d4faa4..a528f646 100644
--- a/ruoyi-admin/src/main/resources/application.yml
+++ b/ruoyi-admin/src/main/resources/application.yml
@@ -227,6 +227,24 @@ xss:
excludeUrls:
- /system/notice
+--- # 链路追踪配置
+trace:
+ # 是否启用链路追踪，默认 true
+ # 关闭后所有埋点代码会直接透传业务逻辑，不写库、不创建上下文，零性能开销
+ enabled: true
+ payload:
+ # 是否记录方法真实入参和返回值，默认 false（仅存摘要）
+ # 仅对 @TraceNode 注解方式生效，编程式埋点使用 TracePayloadBuilder 手动构建的摘要不受此开关影响
+ # true → 自动序列化原始入参/返回值，截断后写入 input_payload / output_payload
+ # false → 只存 nodeName / 耗时 / 状态等元信息，input_payload / output_payload 为空
+ record-detail: false
+ # input payload 最大字符长度，超过部分会被截断丢弃
+ max-input-length: 1000
+ # output payload 最大字符长度，超过部分会被截断丢弃
+ max-output-length: 2000
+ # 错误信息最大字符长度（格式: "异常类名: 异常消息"），超过部分会被截断丢弃
+ max-error-length: 1000
+
--- # 分布式锁 lock4j 全局配置
lock4j:
# 获取分布式锁超时时间，默认为 3000 毫秒
diff --git a/ruoyi-common/pom.xml b/ruoyi-common/pom.xml
index a91e84b0..e6b49eaa 100644
--- a/ruoyi-common/pom.xml
+++ b/ruoyi-common/pom.xml
@@ -35,6 +35,7 @@
ruoyi-common-tenant
ruoyi-common-websocket
ruoyi-common-sse
+ ruoyi-common-trace
ruoyi-common
diff --git a/ruoyi-common/ruoyi-common-bom/pom.xml b/ruoyi-common/ruoyi-common-bom/pom.xml
index ec18b08a..9b0acbdd 100644
--- a/ruoyi-common/ruoyi-common-bom/pom.xml
+++ b/ruoyi-common/ruoyi-common-bom/pom.xml
@@ -186,6 +186,13 @@
${revision}
+
+
+ org.ruoyi
+ ruoyi-common-trace
+ ${revision}
+
+
diff --git a/ruoyi-common/ruoyi-common-trace/pom.xml b/ruoyi-common/ruoyi-common-trace/pom.xml
new file mode 100644
index 00000000..011726ae
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/pom.xml
@@ -0,0 +1,42 @@
+
+
+
+ org.ruoyi
+ ruoyi-common
+ ${revision}
+
+ 4.0.0
+
+ ruoyi-common-trace
+
+
+ ruoyi-common-trace 通用链路追踪
+
+
+
+
+ org.ruoyi
+ ruoyi-common-core
+
+
+ org.ruoyi
+ ruoyi-common-mybatis
+
+
+ org.ruoyi
+ ruoyi-common-json
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+ org.mockito
+ mockito-junit-jupiter
+ test
+
+
+
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/annotation/TraceNode.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/annotation/TraceNode.java
new file mode 100644
index 00000000..7e8a8761
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/annotation/TraceNode.java
@@ -0,0 +1,31 @@
+package org.ruoyi.common.trace.annotation;
+
+import org.ruoyi.common.trace.constant.TraceConstants;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Trace 方法节点标记。
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface TraceNode {
+
+ /**
+ * 节点名称。
+ */
+ String name() default "";
+
+ /**
+ * 节点类型。
+ */
+ String type() default TraceConstants.NODE_METHOD;
+
+ /**
+ * 安全输入摘要。
+ */
+ String input() default "";
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/aspect/TraceNodeAspect.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/aspect/TraceNodeAspect.java
new file mode 100644
index 00000000..606afaf1
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/aspect/TraceNodeAspect.java
@@ -0,0 +1,89 @@
+package org.ruoyi.common.trace.aspect;
+
+import cn.hutool.core.util.IdUtil;
+import cn.hutool.core.util.StrUtil;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.Around;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.ruoyi.common.trace.annotation.TraceNode;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.core.TraceContext;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+
+import java.lang.reflect.Method;
+import java.util.Date;
+
+/**
+ * Trace 方法节点采集切面。
+ */
+@Slf4j
+@Aspect
+@Order(Ordered.HIGHEST_PRECEDENCE + 10)
+@RequiredArgsConstructor
+public class TraceNodeAspect {
+
+ private final TraceRecordService traceRecordService;
+ private final TraceProperties traceProperties;
+
+ @Around("@annotation(traceNode)")
+ public Object aroundNode(ProceedingJoinPoint joinPoint, TraceNode traceNode) throws Throwable {
+ if (!traceProperties.isEnabled() || StrUtil.isBlank(TraceContext.getTraceId())) {
+ return joinPoint.proceed();
+ }
+ Method method = ((MethodSignature) joinPoint.getSignature()).getMethod();
+ String nodeId = IdUtil.getSnowflakeNextIdStr();
+ String traceId = TraceContext.getTraceId();
+ long startMillis = System.currentTimeMillis();
+ Date startTime = new Date();
+
+ org.ruoyi.common.trace.domain.TraceNode node = new org.ruoyi.common.trace.domain.TraceNode();
+ node.setTraceId(traceId);
+ node.setNodeId(nodeId);
+ node.setParentNodeId(TraceContext.currentNodeId());
+ node.setDepth(TraceContext.depth());
+ node.setNodeName(StrUtil.blankToDefault(traceNode.name(), method.getName()));
+ node.setNodeType(StrUtil.blankToDefault(traceNode.type(), TraceConstants.NODE_METHOD));
+ node.setClassName(method.getDeclaringClass().getName());
+ node.setMethodName(method.getName());
+ node.setStatus(TraceConstants.STATUS_RUNNING);
+ node.setStartTime(startTime);
+ node.setInputPayload(StrUtil.isBlank(traceNode.input()) ? null : traceNode.input());
+
+ try {
+ traceRecordService.startNode(node);
+ } catch (Exception ex) {
+ log.warn("写入 trace 节点失败，traceId={}", traceId, ex);
+ return joinPoint.proceed();
+ }
+
+ TraceContext.pushNode(nodeId);
+ try {
+ Object result = joinPoint.proceed();
+ safeFinishNode(traceId, nodeId, TraceConstants.STATUS_SUCCESS, null,
+ TracePayloadUtils.output(result, traceProperties), startMillis);
+ return result;
+ } catch (Throwable ex) {
+ safeFinishNode(traceId, nodeId, TraceConstants.STATUS_ERROR,
+ TracePayloadUtils.error(ex, traceProperties), null, startMillis);
+ throw ex;
+ } finally {
+ TraceContext.popNode();
+ }
+ }
+
+ private void safeFinishNode(String traceId, String nodeId, String status, String errorMessage, String outputPayload, long startMillis) {
+ try {
+ traceRecordService.finishNode(traceId, nodeId, status, errorMessage, outputPayload,
+ new Date(), System.currentTimeMillis() - startMillis);
+ } catch (Exception ex) {
+ log.warn("更新 trace 节点失败，traceId={}, nodeId={}", traceId, nodeId, ex);
+ }
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceAutoConfiguration.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceAutoConfiguration.java
new file mode 100644
index 00000000..d0475311
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceAutoConfiguration.java
@@ -0,0 +1,24 @@
+package org.ruoyi.common.trace.config;
+
+import org.ruoyi.common.trace.aspect.TraceNodeAspect;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * 通用链路追踪自动配置。
+ */
+@AutoConfiguration
+@EnableConfigurationProperties(TraceProperties.class)
+public class TraceAutoConfiguration {
+
+ @Bean
+ @ConditionalOnMissingBean
+ @ConditionalOnProperty(prefix = "trace", name = "enabled", havingValue = "true", matchIfMissing = true)
+ public TraceNodeAspect traceNodeAspect(TraceRecordService traceRecordService, TraceProperties traceProperties) {
+ return new TraceNodeAspect(traceRecordService, traceProperties);
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceProperties.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceProperties.java
new file mode 100644
index 00000000..4e3c5247
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/config/TraceProperties.java
@@ -0,0 +1,46 @@
+package org.ruoyi.common.trace.config;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * 通用链路追踪配置。
+ */
+@Data
+@ConfigurationProperties(prefix = "trace")
+public class TraceProperties {
+
+ /**
+ * 是否启用链路追踪。
+ */
+ private boolean enabled = true;
+
+ /**
+ * payload 记录策略。
+ */
+ private Payload payload = new Payload();
+
+ @Data
+ public static class Payload {
+
+ /**
+ * 是否记录截断后的详情。默认 false，只记录摘要。
+ */
+ private boolean recordDetail = false;
+
+ /**
+ * input payload 最大长度。
+ */
+ private int maxInputLength = 1000;
+
+ /**
+ * output payload 最大长度。
+ */
+ private int maxOutputLength = 2000;
+
+ /**
+ * 错误信息最大长度。
+ */
+ private int maxErrorLength = 1000;
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceConstants.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceConstants.java
new file mode 100644
index 00000000..846d1589
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceConstants.java
@@ -0,0 +1,22 @@
+package org.ruoyi.common.trace.constant;
+
+/**
+ * 通用链路追踪常量。
+ */
+public final class TraceConstants {
+
+ private TraceConstants() {
+ }
+
+ public static final String STATUS_RUNNING = "RUNNING";
+ public static final String STATUS_SUCCESS = "SUCCESS";
+ public static final String STATUS_ERROR = "ERROR";
+ public static final String STATUS_CANCELLED = "CANCELLED";
+
+ public static final String NODE_METHOD = "METHOD";
+ public static final String NODE_HTTP = "HTTP";
+ public static final String NODE_DB = "DB";
+ public static final String NODE_CACHE = "CACHE";
+ public static final String NODE_TASK = "TASK";
+ public static final String NODE_STREAM = "STREAM";
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceDisplayConstants.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceDisplayConstants.java
new file mode 100644
index 00000000..48fc9f20
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/constant/TraceDisplayConstants.java
@@ -0,0 +1,163 @@
+package org.ruoyi.common.trace.constant;
+
+import java.util.Map;
+
+/**
+ * 链路追踪中文展示常量。
+ *
+ * 将技术标识映射为用户可读的中文标签，供前端直接展示。
+ */
+public final class TraceDisplayConstants {
+
+ private TraceDisplayConstants() {
+ }
+
+ // ======================== 节点类型中文映射 ========================
+
+ /**
+ * 通用节点类型中文标签。
+ */
+ public static final Map NODE_TYPE_LABELS = Map.ofEntries(
+ Map.entry("RETRIEVAL", "知识检索"),
+ Map.entry("RERANK", "重排序"),
+ Map.entry("LLM_CALL", "LLM 调用"),
+ Map.entry("STREAM", "流式输出"),
+ Map.entry("METHOD", "方法调用"),
+ Map.entry("HTTP", "HTTP 请求"),
+ Map.entry("DB", "数据库"),
+ Map.entry("CACHE", "缓存操作"),
+ Map.entry("TASK", "异步任务"),
+ Map.entry("ROOT", "根节点")
+ );
+
+ /**
+ * 业务类型中文标签。
+ */
+ public static final Map BUSINESS_TYPE_LABELS = Map.ofEntries(
+ Map.entry("RAG_CHAT", "RAG 对话"),
+ Map.entry("API", "API 调用"),
+ Map.entry("SCHEDULED", "定时任务")
+ );
+
+ /**
+ * 状态中文标签。
+ */
+ public static final Map STATUS_LABELS = Map.ofEntries(
+ Map.entry("RUNNING", "运行中"),
+ Map.entry("SUCCESS", "成功"),
+ Map.entry("ERROR", "失败"),
+ Map.entry("CANCELLED", "已取消"),
+ Map.entry("TIMEOUT", "超时")
+ );
+
+ // ======================== 工具方法 ========================
+
+ /**
+ * 获取节点类型中文标签，未匹配时返回原始值。
+ */
+ public static String nodeTypeLabel(String nodeType) {
+ if (nodeType == null) {
+ return "-";
+ }
+ return NODE_TYPE_LABELS.getOrDefault(nodeType.toUpperCase(), nodeType);
+ }
+
+ /**
+ * 获取业务类型中文标签，未匹配时返回原始值。
+ */
+ public static String businessTypeLabel(String businessType) {
+ if (businessType == null) {
+ return "-";
+ }
+ return BUSINESS_TYPE_LABELS.getOrDefault(businessType.toUpperCase(), businessType);
+ }
+
+ /**
+ * 获取状态中文标签，未匹配时返回原始值。
+ */
+ public static String statusLabel(String status) {
+ if (status == null) {
+ return "未知";
+ }
+ return STATUS_LABELS.getOrDefault(status.toUpperCase(), status);
+ }
+
+ /**
+ * 将技术节点名称转为可读展示名。
+ *
+ * 支持 kebab-case / snake_case / camelCase → 首字母大写空格分隔。
+ */
+ public static String prettifyNodeName(String raw) {
+ if (raw == null || raw.isBlank()) {
+ return "-";
+ }
+ String trimmed = raw.trim();
+ // 已知映射优先
+ Map known = Map.ofEntries(
+ Map.entry("rag-chat", "RAG 流式对话"),
+ Map.entry("rag-stream-chat", "RAG 流式对话"),
+ Map.entry("retrieval-engine", "知识库检索"),
+ Map.entry("multi-channel-retrieval", "多路召回"),
+ Map.entry("context-build", "上下文组装"),
+ Map.entry("prompt-render", "Prompt 渲染"),
+ Map.entry("query-rewrite-and-split", "问题改写与拆分"),
+ Map.entry("intent-resolve", "意图识别"),
+ Map.entry("guidance-detect", "歧义引导"),
+ Map.entry("conversation-title-gen", "会话标题生成"),
+ Map.entry("user-first-packet", "用户感知首包"),
+ Map.entry("llm-first-packet", "LLM 首包"),
+ Map.entry("llm-chat-routing", "LLM 路由调度"),
+ Map.entry("llm-stream-routing", "LLM 流式路由")
+ );
+ if (known.containsKey(trimmed)) {
+ return known.get(trimmed);
+ }
+ // 通用格式化: 按 [-_] 分割，每段首字母大写
+ String[] parts = trimmed.split("[-_\\s]+");
+ StringBuilder sb = new StringBuilder();
+ for (String part : parts) {
+ if (part.isEmpty()) {
+ continue;
+ }
+ if (sb.length() > 0) {
+ sb.append(' ');
+ }
+ sb.append(Character.toUpperCase(part.charAt(0)));
+ if (part.length() > 1) {
+ sb.append(part.substring(1));
+ }
+ }
+ return sb.length() > 0 ? sb.toString() : trimmed;
+ }
+
+ /**
+ * 判断状态是否为失败。
+ */
+ public static boolean isFailed(String status) {
+ if (status == null) {
+ return false;
+ }
+ String upper = status.toUpperCase();
+ return "ERROR".equals(upper) || "FAILED".equals(upper) || "TIMEOUT".equals(upper);
+ }
+
+ /**
+ * 判断状态是否为成功。
+ */
+ public static boolean isSuccess(String status) {
+ if (status == null) {
+ return false;
+ }
+ return "SUCCESS".equalsIgnoreCase(status);
+ }
+
+ /**
+ * 判断状态是否为运行中。
+ */
+ public static boolean isRunning(String status) {
+ if (status == null) {
+ return false;
+ }
+ return "RUNNING".equalsIgnoreCase(status);
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpan.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpan.java
new file mode 100644
index 00000000..a9bb9d64
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpan.java
@@ -0,0 +1,71 @@
+package org.ruoyi.common.trace.core;
+
+import lombok.extern.slf4j.Slf4j;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
+
+import java.util.Date;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * 默认流式 trace 节点实现。
+ */
+@Slf4j
+public class DefaultTraceStreamSpan implements TraceStreamSpan {
+
+ private final TraceRecordService traceRecordService;
+ private final TraceProperties traceProperties;
+ private final String traceId;
+ private final String nodeId;
+ private final long startMillis;
+ private final AtomicBoolean finished = new AtomicBoolean(false);
+ private final AtomicBoolean detached = new AtomicBoolean(false);
+
+ public DefaultTraceStreamSpan(TraceRecordService traceRecordService,
+ TraceProperties traceProperties,
+ String traceId,
+ String nodeId,
+ long startMillis) {
+ this.traceRecordService = traceRecordService;
+ this.traceProperties = traceProperties;
+ this.traceId = traceId;
+ this.nodeId = nodeId;
+ this.startMillis = startMillis;
+ }
+
+ @Override
+ public void detach() {
+ if (detached.compareAndSet(false, true)) {
+ TraceContext.popNode();
+ }
+ }
+
+ @Override
+ public void finishSuccess() {
+ finish(TraceConstants.STATUS_SUCCESS, null);
+ }
+
+ @Override
+ public void finishError(Throwable throwable) {
+ finish(TraceConstants.STATUS_ERROR, TracePayloadUtils.error(throwable, traceProperties));
+ }
+
+ @Override
+ public void finishCancelledIfRunning() {
+ finish(TraceConstants.STATUS_CANCELLED, null);
+ }
+
+ private void finish(String status, String errorMessage) {
+ if (!finished.compareAndSet(false, true)) {
+ return;
+ }
+ try {
+ traceRecordService.finishNode(traceId, nodeId, status, errorMessage, null,
+ new Date(), System.currentTimeMillis() - startMillis);
+ } catch (Exception e) {
+ log.warn("结束 trace stream span 失败，traceId={}, nodeId={}", traceId, nodeId, e);
+ }
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceContext.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceContext.java
new file mode 100644
index 00000000..85db1dc0
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceContext.java
@@ -0,0 +1,115 @@
+package org.ruoyi.common.trace.core;
+
+import java.util.ArrayDeque;
+import java.util.Deque;
+
+/**
+ * 通用链路追踪上下文。
+ */
+public final class TraceContext {
+
+ private static final ThreadLocal TRACE_ID = new ThreadLocal<>();
+ private static final ThreadLocal BUSINESS_TYPE = new ThreadLocal<>();
+ private static final ThreadLocal BUSINESS_ID = new ThreadLocal<>();
+ private static final ThreadLocal USER_ID = new ThreadLocal<>();
+ private static final ThreadLocal TENANT_ID = new ThreadLocal<>();
+ private static final ThreadLocal> NODE_STACK = new ThreadLocal<>();
+
+ private TraceContext() {
+ }
+
+ public static TraceScope begin(String traceId, String businessType, String businessId, Long userId, String tenantId) {
+ TraceScope scope = new TraceScope(getTraceId(), getBusinessType(), getBusinessId(), getUserId(), getTenantId());
+ TRACE_ID.set(traceId);
+ BUSINESS_TYPE.set(businessType);
+ BUSINESS_ID.set(businessId);
+ USER_ID.set(userId);
+ TENANT_ID.set(tenantId);
+ NODE_STACK.remove();
+ return scope;
+ }
+
+ static void restore(String traceId, String businessType, String businessId, Long userId, String tenantId) {
+ setOrRemove(TRACE_ID, traceId);
+ setOrRemove(BUSINESS_TYPE, businessType);
+ setOrRemove(BUSINESS_ID, businessId);
+ setOrRemove(USER_ID, userId);
+ setOrRemove(TENANT_ID, tenantId);
+ NODE_STACK.remove();
+ }
+
+ private static void setOrRemove(ThreadLocal holder, T value) {
+ if (value == null) {
+ holder.remove();
+ } else {
+ holder.set(value);
+ }
+ }
+
+ public static String getTraceId() {
+ return TRACE_ID.get();
+ }
+
+ public static String getBusinessType() {
+ return BUSINESS_TYPE.get();
+ }
+
+ public static String getBusinessId() {
+ return BUSINESS_ID.get();
+ }
+
+ public static Long getUserId() {
+ return USER_ID.get();
+ }
+
+ public static String getTenantId() {
+ return TENANT_ID.get();
+ }
+
+ public static String currentNodeId() {
+ Deque stack = NODE_STACK.get();
+ return stack == null ? null : stack.peek();
+ }
+
+ public static int depth() {
+ Deque stack = NODE_STACK.get();
+ return stack == null ? 0 : stack.size();
+ }
+
+ public static void pushNode(String nodeId) {
+ Deque stack = NODE_STACK.get();
+ if (stack == null) {
+ stack = new ArrayDeque<>();
+ NODE_STACK.set(stack);
+ }
+ stack.push(nodeId);
+ }
+
+ public static void popNode() {
+ Deque stack = NODE_STACK.get();
+ if (stack == null || stack.isEmpty()) {
+ return;
+ }
+ stack.pop();
+ if (stack.isEmpty()) {
+ NODE_STACK.remove();
+ }
+ }
+
+ /**
+ * 为未来的跨线程上下文传播保留的拷贝入口，避免共享可变栈。
+ */
+ public static Deque copyNodeStack() {
+ Deque stack = NODE_STACK.get();
+ return stack == null ? new ArrayDeque<>() : new ArrayDeque<>(stack);
+ }
+
+ public static void clear() {
+ TRACE_ID.remove();
+ BUSINESS_TYPE.remove();
+ BUSINESS_ID.remove();
+ USER_ID.remove();
+ TENANT_ID.remove();
+ NODE_STACK.remove();
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceNodeTemplate.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceNodeTemplate.java
new file mode 100644
index 00000000..d60cb637
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceNodeTemplate.java
@@ -0,0 +1,159 @@
+package org.ruoyi.common.trace.core;
+
+import lombok.extern.slf4j.Slf4j;
+import org.ruoyi.common.core.utils.StringUtils;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
+
+import java.util.Date;
+import java.util.UUID;
+import java.util.function.Function;
+
+/**
+ * 链路追踪节点模板，封装节点创建、上下文压栈、执行、结束、出栈的标准生命周期。
+ *
+ * 用于同步方法内的 trace 埋点，消除手写 start/finish/pop 的重复代码。
+ * 对于需要异步结束的场景（如流式响应），请使用 {@link DefaultTraceStreamSpan}。
+ *
+ * @see DefaultTraceStreamSpan
+ */
+@Slf4j
+public final class TraceNodeTemplate {
+
+ private TraceNodeTemplate() {
+ }
+
+ /**
+ * 在 trace 节点上下文中执行业务逻辑，成功后使用 outputBuilder 生成输出摘要。
+ *
+ * @param traceRecordService 记录服务
+ * @param traceProperties 配置
+ * @param nodeName 节点名称
+ * @param nodeType 节点类型
+ * @param className 类名
+ * @param methodName 方法名
+ * @param inputPayload 输入摘要
+ * @param action 业务逻辑
+ * @param successOutput 成功时从结果构建输出摘要
+ * @param 业务返回值类型
+ * @return 业务执行结果
+ */
+ public static T withNode(
+ TraceRecordService traceRecordService,
+ TraceProperties traceProperties,
+ String nodeName,
+ String nodeType,
+ String className,
+ String methodName,
+ String inputPayload,
+ NodeAction action,
+ Function successOutput) {
+
+ if (!traceProperties.isEnabled() || StringUtils.isBlank(TraceContext.getTraceId())) {
+ return unwrap(action);
+ }
+
+ String traceId = TraceContext.getTraceId();
+ String nodeId = UUID.randomUUID().toString().replace("-", "");
+ long startMillis = System.currentTimeMillis();
+
+ TraceNode node = buildNode(traceId, nodeId, nodeName, nodeType,
+ className, methodName, inputPayload, startMillis);
+
+ try {
+ traceRecordService.startNode(node);
+ } catch (Exception e) {
+ log.warn("写入 trace 节点失败，traceId={}, nodeId={}", traceId, nodeId, e);
+ return unwrap(action);
+ }
+
+ TraceContext.pushNode(nodeId);
+ try {
+ T result = action.execute();
+ String output = successOutput != null && result != null ? successOutput.apply(result) : null;
+ finishNode(traceRecordService, traceProperties, traceId, nodeId,
+ TraceConstants.STATUS_SUCCESS, null, output, startMillis);
+ return result;
+ } catch (Throwable ex) {
+ finishNode(traceRecordService, traceProperties, traceId, nodeId,
+ TraceConstants.STATUS_ERROR, ex, null, startMillis);
+ throw rethrow(ex);
+ } finally {
+ TraceContext.popNode();
+ }
+ }
+
+ /**
+ * 在 trace 节点上下文中执行业务逻辑（无输出摘要）。
+ */
+ public static T withNode(
+ TraceRecordService traceRecordService,
+ TraceProperties traceProperties,
+ String nodeName,
+ String nodeType,
+ String className,
+ String methodName,
+ String inputPayload,
+ NodeAction action) {
+ return withNode(traceRecordService, traceProperties, nodeName, nodeType,
+ className, methodName, inputPayload, action, null);
+ }
+
+ // ======================== 内部工具方法 ========================
+
+ private static TraceNode buildNode(String traceId, String nodeId, String nodeName,
+ String nodeType, String className, String methodName,
+ String inputPayload, long startMillis) {
+ TraceNode node = new TraceNode();
+ node.setTraceId(traceId);
+ node.setNodeId(nodeId);
+ node.setParentNodeId(TraceContext.currentNodeId());
+ node.setDepth(TraceContext.depth());
+ node.setNodeName(nodeName);
+ node.setNodeType(nodeType);
+ node.setClassName(className);
+ node.setMethodName(methodName);
+ node.setStatus(TraceConstants.STATUS_RUNNING);
+ node.setStartTime(new Date(startMillis));
+ node.setInputPayload(inputPayload);
+ return node;
+ }
+
+ private static void finishNode(TraceRecordService service, TraceProperties props,
+ String traceId, String nodeId, String status,
+ Throwable error, String outputPayload, long startMillis) {
+ try {
+ service.finishNode(traceId, nodeId, status,
+ TracePayloadUtils.error(error, props), outputPayload,
+ new Date(), System.currentTimeMillis() - startMillis);
+ } catch (Exception e) {
+ log.warn("结束 trace 节点失败，traceId={}, nodeId={}", traceId, nodeId, e);
+ }
+ }
+
+ private static T unwrap(NodeAction action) {
+ try {
+ return action.execute();
+ } catch (RuntimeException | Error e) {
+ throw e;
+ } catch (Throwable e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private static T rethrow(Throwable t) throws T {
+ throw (T) t;
+ }
+
+ /**
+ * 可抛出 Throwable 的业务动作。
+ */
+ @FunctionalInterface
+ public interface NodeAction {
+ T execute() throws Throwable;
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceScope.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceScope.java
new file mode 100644
index 00000000..df05888c
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceScope.java
@@ -0,0 +1,30 @@
+package org.ruoyi.common.trace.core;
+
+/**
+ * Trace 上下文作用域。
+ */
+public final class TraceScope implements AutoCloseable {
+
+ private final String previousTraceId;
+ private final String previousBusinessType;
+ private final String previousBusinessId;
+ private final Long previousUserId;
+ private final String previousTenantId;
+
+ TraceScope(String previousTraceId,
+ String previousBusinessType,
+ String previousBusinessId,
+ Long previousUserId,
+ String previousTenantId) {
+ this.previousTraceId = previousTraceId;
+ this.previousBusinessType = previousBusinessType;
+ this.previousBusinessId = previousBusinessId;
+ this.previousUserId = previousUserId;
+ this.previousTenantId = previousTenantId;
+ }
+
+ @Override
+ public void close() {
+ TraceContext.restore(previousTraceId, previousBusinessType, previousBusinessId, previousUserId, previousTenantId);
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceStreamSpan.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceStreamSpan.java
new file mode 100644
index 00000000..349238d5
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/core/TraceStreamSpan.java
@@ -0,0 +1,15 @@
+package org.ruoyi.common.trace.core;
+
+/**
+ * 可跨回调结束的流式 trace 节点。
+ */
+public interface TraceStreamSpan {
+
+ void detach();
+
+ void finishSuccess();
+
+ void finishError(Throwable throwable);
+
+ void finishCancelledIfRunning();
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceNode.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceNode.java
new file mode 100644
index 00000000..dece4bbb
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceNode.java
@@ -0,0 +1,45 @@
+package org.ruoyi.common.trace.domain;
+
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableLogic;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.ruoyi.common.mybatis.core.domain.BaseEntity;
+
+import java.io.Serial;
+import java.util.Date;
+
+/**
+ * 链路追踪节点记录 trace_node。
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("trace_node")
+public class TraceNode extends BaseEntity {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ @TableId(value = "id")
+ private Long id;
+ private String traceId;
+ private String nodeId;
+ private String parentNodeId;
+ private String nodeName;
+ private String nodeType;
+ private Integer depth;
+ private Integer sortOrder;
+ private String className;
+ private String methodName;
+ private String status;
+ private Date startTime;
+ private Date endTime;
+ private Long durationMs;
+ private String errorMessage;
+ private String inputPayload;
+ private String outputPayload;
+ private String metadata;
+ @TableLogic
+ private String delFlag;
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceRun.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceRun.java
new file mode 100644
index 00000000..ac7c05c4
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/TraceRun.java
@@ -0,0 +1,40 @@
+package org.ruoyi.common.trace.domain;
+
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableLogic;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.ruoyi.common.mybatis.core.domain.BaseEntity;
+
+import java.io.Serial;
+import java.util.Date;
+
+/**
+ * 链路追踪运行记录 trace_run。
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("trace_run")
+public class TraceRun extends BaseEntity {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ @TableId(value = "id")
+ private Long id;
+ private String traceId;
+ private String traceName;
+ private String businessType;
+ private String businessId;
+ private Long userId;
+ private String tenantId;
+ private String status;
+ private Date startTime;
+ private Date endTime;
+ private Long durationMs;
+ private String errorMessage;
+ private String metadata;
+ @TableLogic
+ private String delFlag;
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/bo/TraceRunBo.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/bo/TraceRunBo.java
new file mode 100644
index 00000000..bdcc81e2
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/bo/TraceRunBo.java
@@ -0,0 +1,32 @@
+package org.ruoyi.common.trace.domain.bo;
+
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.ruoyi.common.mybatis.core.domain.BaseEntity;
+import org.ruoyi.common.trace.domain.TraceRun;
+
+import java.util.Date;
+
+/**
+ * 链路追踪运行记录查询对象。
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = TraceRun.class, reverseConvertGenerate = false)
+public class TraceRunBo extends BaseEntity {
+
+ private Long id;
+ private String traceId;
+ private String traceName;
+ private String businessType;
+ private String businessId;
+ private Long userId;
+ private String tenantId;
+ private String status;
+ private Date startTime;
+ private Date endTime;
+ private Long durationMs;
+ private String errorMessage;
+ private String metadata;
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceDetailVo.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceDetailVo.java
new file mode 100644
index 00000000..43a07694
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceDetailVo.java
@@ -0,0 +1,83 @@
+package org.ruoyi.common.trace.domain.vo;
+
+import lombok.Data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 链路追踪详情视图对象。
+ *
+ * 包含运行信息、节点树以及统计摘要。
+ */
+@Data
+public class TraceDetailVo implements Serializable {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ private TraceRunVo run;
+ private List nodes;
+ private TraceStatistics statistics;
+
+ /**
+ * 链路追踪统计摘要，帮助快速了解整体执行情况。
+ */
+ @Data
+ public static class TraceStatistics implements Serializable {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ /** 总节点数 */
+ private int totalNodes;
+
+ /** 成功节点数 */
+ private int successCount;
+
+ /** 失败节点数 */
+ private int failedCount;
+
+ /** 运行中节点数 */
+ private int runningCount;
+
+ /** 最大调用深度 */
+ private int maxDepth;
+
+ /** 平均耗时 (ms) */
+ private long avgDurationMs;
+
+ /** 总链路耗时 (ms) */
+ private long totalDurationMs;
+
+ /** 慢节点 Top N */
+ private List topSlowNodes = new ArrayList<>();
+ }
+
+ /**
+ * 慢节点简要信息。
+ */
+ @Data
+ public static class SlowNodeInfo implements Serializable {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ /** 节点 ID */
+ private String nodeId;
+
+ /** 节点展示名称 */
+ private String nodeDisplayName;
+
+ /** 节点类型中文标签 */
+ private String nodeTypeLabel;
+
+ /** 耗时 (ms) */
+ private long durationMs;
+
+ /** 占总耗时百分比 */
+ private double percentOfTotal;
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceNodeVo.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceNodeVo.java
new file mode 100644
index 00000000..1ac81555
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceNodeVo.java
@@ -0,0 +1,80 @@
+package org.ruoyi.common.trace.domain.vo;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import org.ruoyi.common.trace.domain.TraceNode;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 链路追踪节点记录视图对象。
+ *
+ * 除实体映射字段外，还提供前端可直接展示的显示标签和解析后的 payload 对象。
+ */
+@Data
+@AutoMapper(target = TraceNode.class)
+public class TraceNodeVo implements Serializable {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ private Long id;
+ private String traceId;
+ private String nodeId;
+ private String parentNodeId;
+ private String nodeName;
+ private String nodeType;
+ private Integer depth;
+ private Integer sortOrder;
+ private String className;
+ private String methodName;
+ private String status;
+ private Date startTime;
+ private Date endTime;
+ private Long durationMs;
+ private String errorMessage;
+
+ /** 原始 payload 字符串（兼容旧版），新代码请使用 parsedInput */
+ private String inputPayload;
+
+ /** 原始 payload 字符串（兼容旧版），新代码请使用 parsedOutput */
+ private String outputPayload;
+
+ /** 原始 metadata 字符串（兼容旧版），新代码请使用 parsedMetadata */
+ private String metadata;
+
+ private List children;
+
+ // ======================== 展示用计算字段 ========================
+
+ /** 节点类型中文标签，如 "知识检索"、"LLM 调用" */
+ @JsonProperty("nodeTypeLabel")
+ private String nodeTypeLabel;
+
+ /** 状态中文标签，如 "成功"、"失败"、"运行中" */
+ @JsonProperty("statusLabel")
+ private String statusLabel;
+
+ /** 节点展示名称（中文友好），从 nodeName 转换 */
+ @JsonProperty("nodeDisplayName")
+ private String nodeDisplayName;
+
+ // ======================== 解析后的 payload ========================
+
+ /** input payload 解析为 Map，前端可直接读取结构化字段 */
+ @JsonProperty("parsedInput")
+ private Map parsedInput;
+
+ /** output payload 解析为 Map，前端可直接读取结构化字段 */
+ @JsonProperty("parsedOutput")
+ private Map parsedOutput;
+
+ /** metadata 解析为 Map */
+ @JsonProperty("parsedMetadata")
+ private Map parsedMetadata;
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceRunVo.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceRunVo.java
new file mode 100644
index 00000000..db97e06e
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/domain/vo/TraceRunVo.java
@@ -0,0 +1,54 @@
+package org.ruoyi.common.trace.domain.vo;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import org.ruoyi.common.trace.domain.TraceRun;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.Map;
+
+/**
+ * 链路追踪运行记录视图对象。
+ *
+ * 除实体映射字段外，还提供前端可直接展示的显示标签和解析后的 metadata 对象。
+ */
+@Data
+@AutoMapper(target = TraceRun.class)
+public class TraceRunVo implements Serializable {
+
+ @Serial
+ private static final long serialVersionUID = 1L;
+
+ private Long id;
+ private String traceId;
+ private String traceName;
+ private String businessType;
+ private String businessId;
+ private Long userId;
+ private String tenantId;
+ private String status;
+ private Date startTime;
+ private Date endTime;
+ private Long durationMs;
+ private String errorMessage;
+
+ /** 原始 metadata 字符串（兼容旧版），新代码请使用 parsedMetadata */
+ private String metadata;
+
+ // ======================== 展示用计算字段 ========================
+
+ /** 状态中文标签，如 "成功"、"失败"、"运行中" */
+ @JsonProperty("statusLabel")
+ private String statusLabel;
+
+ /** 业务类型中文标签，如 "RAG 对话" */
+ @JsonProperty("businessTypeLabel")
+ private String businessTypeLabel;
+
+ /** metadata 解析为 Map */
+ @JsonProperty("parsedMetadata")
+ private Map parsedMetadata;
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceNodeMapper.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceNodeMapper.java
new file mode 100644
index 00000000..b5100e77
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceNodeMapper.java
@@ -0,0 +1,11 @@
+package org.ruoyi.common.trace.mapper;
+
+import org.ruoyi.common.mybatis.core.mapper.BaseMapperPlus;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.domain.vo.TraceNodeVo;
+
+/**
+ * 链路追踪节点记录 Mapper。
+ */
+public interface TraceNodeMapper extends BaseMapperPlus {
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceRunMapper.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceRunMapper.java
new file mode 100644
index 00000000..ae88b5fb
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/mapper/TraceRunMapper.java
@@ -0,0 +1,11 @@
+package org.ruoyi.common.trace.mapper;
+
+import org.ruoyi.common.mybatis.core.mapper.BaseMapperPlus;
+import org.ruoyi.common.trace.domain.TraceRun;
+import org.ruoyi.common.trace.domain.vo.TraceRunVo;
+
+/**
+ * 链路追踪运行记录 Mapper。
+ */
+public interface TraceRunMapper extends BaseMapperPlus {
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/TraceRecordService.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/TraceRecordService.java
new file mode 100644
index 00000000..69a7745d
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/TraceRecordService.java
@@ -0,0 +1,35 @@
+package org.ruoyi.common.trace.service;
+
+import org.ruoyi.common.mybatis.core.page.PageQuery;
+import org.ruoyi.common.mybatis.core.page.TableDataInfo;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.domain.TraceRun;
+import org.ruoyi.common.trace.domain.bo.TraceRunBo;
+import org.ruoyi.common.trace.domain.vo.TraceDetailVo;
+import org.ruoyi.common.trace.domain.vo.TraceNodeVo;
+import org.ruoyi.common.trace.domain.vo.TraceRunVo;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 链路追踪记录服务。
+ */
+public interface TraceRecordService {
+
+ void startRun(TraceRun run);
+
+ void finishRun(String traceId, String status, String errorMessage, Date endTime, long durationMs);
+
+ void startNode(TraceNode node);
+
+ void finishNode(String traceId, String nodeId, String status, String errorMessage, String outputPayload, Date endTime, long durationMs);
+
+ TableDataInfo pageRuns(TraceRunBo bo, PageQuery pageQuery);
+
+ TraceRunVo getRun(String traceId);
+
+ List listNodes(String traceId);
+
+ TraceDetailVo getDetail(String traceId);
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/impl/TraceRecordServiceImpl.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/impl/TraceRecordServiceImpl.java
new file mode 100644
index 00000000..1b47173e
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/service/impl/TraceRecordServiceImpl.java
@@ -0,0 +1,256 @@
+package org.ruoyi.common.trace.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.ruoyi.common.core.utils.StringUtils;
+import org.ruoyi.common.mybatis.core.page.PageQuery;
+import org.ruoyi.common.mybatis.core.page.TableDataInfo;
+import org.ruoyi.common.trace.constant.TraceDisplayConstants;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.domain.TraceRun;
+import org.ruoyi.common.trace.domain.bo.TraceRunBo;
+import org.ruoyi.common.trace.domain.vo.TraceDetailVo;
+import org.ruoyi.common.trace.domain.vo.TraceNodeVo;
+import org.ruoyi.common.trace.domain.vo.TraceRunVo;
+import org.ruoyi.common.trace.mapper.TraceNodeMapper;
+import org.ruoyi.common.trace.mapper.TraceRunMapper;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * 链路追踪记录服务实现。
+ *
+ * 在自动映射的基础上，对 VO 进行二次加工：补充展示标签、解析 payload 为结构化对象、计算统计信息。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class TraceRecordServiceImpl implements TraceRecordService {
+
+ private static final int TOP_SLOW_NODES_LIMIT = 5;
+
+ private final TraceRunMapper traceRunMapper;
+ private final TraceNodeMapper traceNodeMapper;
+
+ @Override
+ public void startRun(TraceRun run) {
+ try {
+ traceRunMapper.insert(run);
+ } catch (Exception e) {
+ log.warn("写入 trace run 失败，traceId={}", run == null ? null : run.getTraceId(), e);
+ }
+ }
+
+ @Override
+ public void finishRun(String traceId, String status, String errorMessage, Date endTime, long durationMs) {
+ try {
+ TraceRun update = new TraceRun();
+ update.setStatus(status);
+ update.setErrorMessage(errorMessage);
+ update.setEndTime(endTime);
+ update.setDurationMs(durationMs);
+ traceRunMapper.update(update, Wrappers.lambdaUpdate(TraceRun.class).eq(TraceRun::getTraceId, traceId));
+ } catch (Exception e) {
+ log.warn("更新 trace run 失败，traceId={}", traceId, e);
+ }
+ }
+
+ @Override
+ public void startNode(TraceNode node) {
+ try {
+ traceNodeMapper.insert(node);
+ } catch (Exception e) {
+ log.warn("写入 trace node 失败，traceId={}, nodeId={}",
+ node == null ? null : node.getTraceId(), node == null ? null : node.getNodeId(), e);
+ }
+ }
+
+ @Override
+ public void finishNode(String traceId, String nodeId, String status, String errorMessage, String outputPayload, Date endTime, long durationMs) {
+ try {
+ TraceNode update = new TraceNode();
+ update.setStatus(status);
+ update.setErrorMessage(errorMessage);
+ update.setOutputPayload(outputPayload);
+ update.setEndTime(endTime);
+ update.setDurationMs(durationMs);
+ traceNodeMapper.update(update, Wrappers.lambdaUpdate(TraceNode.class)
+ .eq(TraceNode::getTraceId, traceId)
+ .eq(TraceNode::getNodeId, nodeId));
+ } catch (Exception e) {
+ log.warn("更新 trace node 失败，traceId={}, nodeId={}", traceId, nodeId, e);
+ }
+ }
+
+ @Override
+ public TableDataInfo pageRuns(TraceRunBo bo, PageQuery pageQuery) {
+ LambdaQueryWrapper wrapper = buildRunWrapper(bo == null ? new TraceRunBo() : bo);
+ if (StringUtils.isBlank(pageQuery.getOrderByColumn())) {
+ wrapper.orderByDesc(TraceRun::getStartTime);
+ }
+ Page page = traceRunMapper.selectVoPage(pageQuery.build(), wrapper);
+ if (page.getRecords() != null) {
+ page.getRecords().forEach(this::enrichRunVo);
+ }
+ return TableDataInfo.build(page);
+ }
+
+ @Override
+ public TraceRunVo getRun(String traceId) {
+ TraceRunVo run = traceRunMapper.selectVoOne(Wrappers.lambdaQuery(TraceRun.class).eq(TraceRun::getTraceId, traceId));
+ if (run != null) {
+ enrichRunVo(run);
+ }
+ return run;
+ }
+
+ @Override
+ public List listNodes(String traceId) {
+ List nodes = traceNodeMapper.selectVoList(Wrappers.lambdaQuery(TraceNode.class)
+ .eq(TraceNode::getTraceId, traceId)
+ .orderByAsc(TraceNode::getStartTime)
+ .orderByAsc(TraceNode::getId));
+ if (nodes != null) {
+ nodes.forEach(this::enrichNodeVo);
+ }
+ return nodes;
+ }
+
+ @Override
+ public TraceDetailVo getDetail(String traceId) {
+ TraceDetailVo detail = new TraceDetailVo();
+ TraceRunVo run = getRun(traceId);
+ detail.setRun(run);
+
+ List nodes = listNodes(traceId);
+ if (nodes != null) {
+ nodes.forEach(this::enrichNodeVo);
+ }
+ // 返回扁平列表，前端自行按 parentNodeId 建树
+ detail.setNodes(nodes != null ? nodes : new ArrayList<>());
+
+ // 计算统计信息
+ if (nodes != null) {
+ detail.setStatistics(buildStatistics(nodes, run));
+ }
+ return detail;
+ }
+
+ // ======================== VO 加工 ========================
+
+ /**
+ * 为 TraceRunVo 补充展示标签和解析后的 metadata。
+ */
+ private void enrichRunVo(TraceRunVo vo) {
+ if (vo == null) {
+ return;
+ }
+ vo.setStatusLabel(TraceDisplayConstants.statusLabel(vo.getStatus()));
+ vo.setBusinessTypeLabel(TraceDisplayConstants.businessTypeLabel(vo.getBusinessType()));
+ vo.setParsedMetadata(TracePayloadUtils.parseJsonToMap(vo.getMetadata()));
+ }
+
+ /**
+ * 为 TraceNodeVo 补充展示标签和解析后的 payload。
+ */
+ private void enrichNodeVo(TraceNodeVo vo) {
+ if (vo == null) {
+ return;
+ }
+ vo.setNodeTypeLabel(TraceDisplayConstants.nodeTypeLabel(vo.getNodeType()));
+ vo.setStatusLabel(TraceDisplayConstants.statusLabel(vo.getStatus()));
+ vo.setNodeDisplayName(TraceDisplayConstants.prettifyNodeName(vo.getNodeName()));
+ vo.setParsedInput(TracePayloadUtils.parseJsonToMap(vo.getInputPayload()));
+ vo.setParsedOutput(TracePayloadUtils.parseJsonToMap(vo.getOutputPayload()));
+ vo.setParsedMetadata(TracePayloadUtils.parseJsonToMap(vo.getMetadata()));
+ }
+
+ // ======================== 统计计算 ========================
+ private TraceDetailVo.TraceStatistics buildStatistics(List nodes, TraceRunVo run) {
+ TraceDetailVo.TraceStatistics stats = new TraceDetailVo.TraceStatistics();
+
+ int total = nodes == null ? 0 : nodes.size();
+ int success = 0;
+ int failed = 0;
+ int running = 0;
+ int maxDepth = 0;
+ long totalDuration = 0;
+
+ for (TraceNodeVo node : nodes) {
+ if (node == null) {
+ continue;
+ }
+ if (TraceDisplayConstants.isSuccess(node.getStatus())) {
+ success++;
+ } else if (TraceDisplayConstants.isFailed(node.getStatus())) {
+ failed++;
+ } else if (TraceDisplayConstants.isRunning(node.getStatus())) {
+ running++;
+ }
+
+ int depth = node.getDepth() == null ? 0 : node.getDepth();
+ if (depth > maxDepth) {
+ maxDepth = depth;
+ }
+
+ long dur = node.getDurationMs() == null ? 0 : node.getDurationMs();
+ totalDuration += dur;
+ }
+
+ stats.setTotalNodes(total);
+ stats.setSuccessCount(success);
+ stats.setFailedCount(failed);
+ stats.setRunningCount(running);
+ stats.setMaxDepth(maxDepth);
+ stats.setAvgDurationMs(total > 0 ? totalDuration / total : 0);
+ stats.setTotalDurationMs(run != null && run.getDurationMs() != null ? run.getDurationMs() : totalDuration);
+
+ // 慢节点 Top N
+ long totalMs = stats.getTotalDurationMs();
+ List topSlow = nodes.stream()
+ .filter(n -> n != null && n.getDurationMs() != null && n.getDurationMs() > 0)
+ .sorted(Comparator.comparingLong(TraceNodeVo::getDurationMs).reversed())
+ .limit(TOP_SLOW_NODES_LIMIT)
+ .map(n -> {
+ TraceDetailVo.SlowNodeInfo info = new TraceDetailVo.SlowNodeInfo();
+ info.setNodeId(n.getNodeId());
+ info.setNodeDisplayName(n.getNodeDisplayName() != null ? n.getNodeDisplayName() : n.getNodeName());
+ info.setNodeTypeLabel(n.getNodeTypeLabel());
+ info.setDurationMs(n.getDurationMs());
+ info.setPercentOfTotal(totalMs > 0 ? Math.round(n.getDurationMs() * 1000.0 / totalMs) / 10.0 : 0);
+ return info;
+ })
+ .collect(Collectors.toList());
+ stats.setTopSlowNodes(topSlow);
+
+ return stats;
+ }
+
+ // ======================== 查询辅助 ========================
+
+ private LambdaQueryWrapper buildRunWrapper(TraceRunBo bo) {
+ Map params = bo.getParams();
+ return new LambdaQueryWrapper()
+ .eq(StringUtils.isNotBlank(bo.getTraceId()), TraceRun::getTraceId, bo.getTraceId())
+ .like(StringUtils.isNotBlank(bo.getTraceName()), TraceRun::getTraceName, bo.getTraceName())
+ .eq(StringUtils.isNotBlank(bo.getBusinessType()), TraceRun::getBusinessType, bo.getBusinessType())
+ .eq(StringUtils.isNotBlank(bo.getBusinessId()), TraceRun::getBusinessId, bo.getBusinessId())
+ .eq(StringUtils.isNotBlank(bo.getStatus()), TraceRun::getStatus, bo.getStatus())
+ .eq(bo.getUserId() != null, TraceRun::getUserId, bo.getUserId())
+ .eq(StringUtils.isNotBlank(bo.getTenantId()), TraceRun::getTenantId, bo.getTenantId())
+ .between(params.get("beginTime") != null && params.get("endTime") != null,
+ TraceRun::getStartTime, params.get("beginTime"), params.get("endTime"));
+ }
+
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/util/TracePayloadUtils.java b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/util/TracePayloadUtils.java
new file mode 100644
index 00000000..84497bbe
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/java/org/ruoyi/common/trace/util/TracePayloadUtils.java
@@ -0,0 +1,100 @@
+package org.ruoyi.common.trace.util;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import org.ruoyi.common.json.handler.BigNumberSerializer;
+import org.ruoyi.common.trace.config.TraceProperties;
+
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * Trace payload 序列化、截断与解析工具。
+ */
+public final class TracePayloadUtils {
+
+ private static final ObjectMapper OBJECT_MAPPER;
+
+ static {
+ OBJECT_MAPPER = new ObjectMapper();
+ SimpleModule jsSafeModule = new SimpleModule("js-safe-numbers");
+ jsSafeModule.addSerializer(Long.class, BigNumberSerializer.INSTANCE);
+ jsSafeModule.addSerializer(Long.TYPE, BigNumberSerializer.INSTANCE);
+ jsSafeModule.addSerializer(BigInteger.class, BigNumberSerializer.INSTANCE);
+ jsSafeModule.addSerializer(BigDecimal.class, ToStringSerializer.instance);
+ OBJECT_MAPPER.registerModule(jsSafeModule);
+ }
+
+ private TracePayloadUtils() {
+ }
+
+ public static String input(Object value, TraceProperties properties) {
+ if (value == null || properties == null || !properties.getPayload().isRecordDetail()) {
+ return null;
+ }
+ return truncate(asString(value), properties.getPayload().getMaxInputLength());
+ }
+
+ public static String output(Object value, TraceProperties properties) {
+ if (value == null || properties == null || !properties.getPayload().isRecordDetail()) {
+ return null;
+ }
+ return truncate(asString(value), properties.getPayload().getMaxOutputLength());
+ }
+
+ public static String error(Throwable throwable, TraceProperties properties) {
+ if (throwable == null) {
+ return null;
+ }
+ int maxLength = properties == null ? 1000 : properties.getPayload().getMaxErrorLength();
+ String message = throwable.getClass().getSimpleName() + ": " + (throwable.getMessage() == null ? "" : throwable.getMessage());
+ return truncate(message, maxLength);
+ }
+
+ public static String toJson(Object value) {
+ if (value == null) {
+ return null;
+ }
+ try {
+ return OBJECT_MAPPER.writeValueAsString(value);
+ } catch (JsonProcessingException e) {
+ return "{\"summary\":\"payload serialization failed\"}";
+ }
+ }
+
+ public static String truncate(String value, int maxLength) {
+ if (value == null) {
+ return null;
+ }
+ if (maxLength <= 0 || value.length() <= maxLength) {
+ return value;
+ }
+ return value.substring(0, maxLength);
+ }
+
+ /**
+ * 将 JSON 字符串解析为 Map，用于前端展示结构化数据。
+ * 解析失败时返回空 Map，不影响主流程。
+ */
+ @SuppressWarnings("unchecked")
+ public static Map parseJsonToMap(String json) {
+ if (json == null || json.isBlank()) {
+ return Collections.emptyMap();
+ }
+ try {
+ return OBJECT_MAPPER.readValue(json, new TypeReference>() {});
+ } catch (JsonProcessingException e) {
+ // 非 JSON 字符串，返回包含原始文本的 Map
+ return Collections.singletonMap("_raw", json);
+ }
+ }
+
+ private static String asString(Object value) {
+ return value instanceof String str ? str : toJson(value);
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/ruoyi-common/ruoyi-common-trace/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
new file mode 100644
index 00000000..14890863
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -0,0 +1 @@
+org.ruoyi.common.trace.config.TraceAutoConfiguration
diff --git a/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/aspect/TraceNodeAspectTest.java b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/aspect/TraceNodeAspectTest.java
new file mode 100644
index 00000000..15413b3f
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/aspect/TraceNodeAspectTest.java
@@ -0,0 +1,134 @@
+package org.ruoyi.common.trace.aspect;
+
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.ruoyi.common.trace.annotation.TraceNode;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.core.TraceContext;
+import org.ruoyi.common.trace.service.TraceRecordService;
+
+import java.lang.reflect.Method;
+import java.util.Date;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class TraceNodeAspectTest {
+
+ @Mock
+ private TraceRecordService traceRecordService;
+
+ @Mock
+ private ProceedingJoinPoint joinPoint;
+
+ @Mock
+ private MethodSignature methodSignature;
+
+ @AfterEach
+ void tearDown() {
+ TraceContext.clear();
+ }
+
+ @Test
+ void shouldProceedWithoutRecordingWhenNoTraceContext() throws Throwable {
+ TraceNodeAspect aspect = new TraceNodeAspect(traceRecordService, new TraceProperties());
+ Method method = SampleService.class.getDeclaredMethod("sample");
+ when(joinPoint.proceed()).thenReturn("ok");
+
+ Object result = aspect.aroundNode(joinPoint, method.getAnnotation(TraceNode.class));
+
+ assertEquals("ok", result);
+ verify(traceRecordService, never()).startNode(any());
+ }
+
+ @Test
+ void shouldRecordSuccessNode() throws Throwable {
+ TraceProperties properties = new TraceProperties();
+ properties.getPayload().setRecordDetail(true);
+ TraceNodeAspect aspect = new TraceNodeAspect(traceRecordService, properties);
+ Method method = SampleService.class.getDeclaredMethod("sample");
+ prepareSignature(method);
+ when(joinPoint.proceed()).thenReturn("ok");
+
+ try (var ignored = TraceContext.begin("trace-1", "TEST", "biz-1", 1L, "000000")) {
+ Object result = aspect.aroundNode(joinPoint, method.getAnnotation(TraceNode.class));
+
+ assertEquals("ok", result);
+ assertNull(TraceContext.currentNodeId());
+ }
+
+ ArgumentCaptor nodeCaptor =
+ ArgumentCaptor.forClass(org.ruoyi.common.trace.domain.TraceNode.class);
+ verify(traceRecordService).startNode(nodeCaptor.capture());
+ org.ruoyi.common.trace.domain.TraceNode node = nodeCaptor.getValue();
+ assertEquals("trace-1", node.getTraceId());
+ assertEquals("sample-node", node.getNodeName());
+ assertEquals(TraceConstants.NODE_METHOD, node.getNodeType());
+ assertEquals("safe-input", node.getInputPayload());
+ verify(traceRecordService).finishNode(eq("trace-1"), eq(node.getNodeId()), eq(TraceConstants.STATUS_SUCCESS),
+ isNull(), eq("ok"), any(Date.class), anyLong());
+ }
+
+ @Test
+ void shouldRethrowBusinessExceptionAfterErrorRecord() throws Throwable {
+ TraceNodeAspect aspect = new TraceNodeAspect(traceRecordService, new TraceProperties());
+ Method method = SampleService.class.getDeclaredMethod("sample");
+ prepareSignature(method);
+ IllegalArgumentException error = new IllegalArgumentException("bad");
+ when(joinPoint.proceed()).thenThrow(error);
+
+ try (var ignored = TraceContext.begin("trace-1", "TEST", "biz-1", 1L, "000000")) {
+ assertThrows(IllegalArgumentException.class,
+ () -> aspect.aroundNode(joinPoint, method.getAnnotation(TraceNode.class)));
+ }
+
+ ArgumentCaptor nodeCaptor =
+ ArgumentCaptor.forClass(org.ruoyi.common.trace.domain.TraceNode.class);
+ verify(traceRecordService).startNode(nodeCaptor.capture());
+ verify(traceRecordService).finishNode(eq("trace-1"), eq(nodeCaptor.getValue().getNodeId()), eq(TraceConstants.STATUS_ERROR),
+ eq("IllegalArgumentException: bad"), isNull(), any(Date.class), anyLong());
+ }
+
+ @Test
+ void writeFailureShouldNotAffectBusinessReturn() throws Throwable {
+ TraceNodeAspect aspect = new TraceNodeAspect(traceRecordService, new TraceProperties());
+ Method method = SampleService.class.getDeclaredMethod("sample");
+ prepareSignature(method);
+ when(joinPoint.proceed()).thenReturn("ok");
+ doThrow(new IllegalStateException("db down")).when(traceRecordService).startNode(any());
+
+ try (var ignored = TraceContext.begin("trace-1", "TEST", "biz-1", 1L, "000000")) {
+ assertEquals("ok", aspect.aroundNode(joinPoint, method.getAnnotation(TraceNode.class)));
+ }
+ }
+
+ private void prepareSignature(Method method) {
+ when(joinPoint.getSignature()).thenReturn(methodSignature);
+ when(methodSignature.getMethod()).thenReturn(method);
+ }
+
+ private static class SampleService {
+
+ @TraceNode(name = "sample-node", input = "safe-input")
+ String sample() {
+ return "ok";
+ }
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpanTest.java b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpanTest.java
new file mode 100644
index 00000000..f76b35ca
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/DefaultTraceStreamSpanTest.java
@@ -0,0 +1,83 @@
+package org.ruoyi.common.trace.core;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.service.TraceRecordService;
+
+import java.util.Date;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+
+@ExtendWith(MockitoExtension.class)
+class DefaultTraceStreamSpanTest {
+
+ @Mock
+ private TraceRecordService traceRecordService;
+
+ @AfterEach
+ void tearDown() {
+ TraceContext.clear();
+ }
+
+ @Test
+ void finishShouldBeIdempotent() {
+ DefaultTraceStreamSpan span = new DefaultTraceStreamSpan(traceRecordService, new TraceProperties(), "trace-1", "node-1", System.currentTimeMillis());
+
+ span.finishSuccess();
+ span.finishError(new IllegalStateException("ignored"));
+
+ verify(traceRecordService, times(1)).finishNode(eq("trace-1"), eq("node-1"), eq(TraceConstants.STATUS_SUCCESS),
+ isNull(), isNull(), any(Date.class), anyLong());
+ }
+
+ @Test
+ void finishErrorShouldRecordTruncatedError() {
+ TraceProperties properties = new TraceProperties();
+ properties.getPayload().setMaxErrorLength(8);
+ DefaultTraceStreamSpan span = new DefaultTraceStreamSpan(traceRecordService, properties, "trace-1", "node-1", System.currentTimeMillis());
+
+ span.finishError(new IllegalStateException("abcdef"));
+
+ ArgumentCaptor errorCaptor = ArgumentCaptor.forClass(String.class);
+ verify(traceRecordService).finishNode(eq("trace-1"), eq("node-1"), eq(TraceConstants.STATUS_ERROR),
+ errorCaptor.capture(), isNull(), any(Date.class), anyLong());
+ assertEquals("IllegalS", errorCaptor.getValue());
+ }
+
+ @Test
+ void detachShouldPopOnlyOnce() {
+ TraceContext.pushNode("root");
+ TraceContext.pushNode("stream");
+ DefaultTraceStreamSpan span = new DefaultTraceStreamSpan(traceRecordService, new TraceProperties(), "trace-1", "stream", System.currentTimeMillis());
+
+ span.detach();
+ span.detach();
+
+ assertEquals("root", TraceContext.currentNodeId());
+ }
+
+ @Test
+ void writeFailureShouldNotEscape() {
+ doThrow(new IllegalStateException("db down")).when(traceRecordService)
+ .finishNode(eq("trace-1"), eq("node-1"), eq(TraceConstants.STATUS_SUCCESS), isNull(), isNull(), any(Date.class), anyLong());
+ DefaultTraceStreamSpan span = new DefaultTraceStreamSpan(traceRecordService, new TraceProperties(), "trace-1", "node-1", System.currentTimeMillis());
+
+ span.finishSuccess();
+
+ assertNull(TraceContext.currentNodeId());
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/TraceContextTest.java b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/TraceContextTest.java
new file mode 100644
index 00000000..1347e6ec
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/core/TraceContextTest.java
@@ -0,0 +1,57 @@
+package org.ruoyi.common.trace.core;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Deque;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+class TraceContextTest {
+
+ @AfterEach
+ void tearDown() {
+ TraceContext.clear();
+ }
+
+ @Test
+ void beginShouldExposeTraceAndBusinessIdentity() {
+ try (TraceScope ignored = TraceContext.begin("trace-1", "RAG_CHAT", "session-1", 10L, "000000")) {
+ assertEquals("trace-1", TraceContext.getTraceId());
+ assertEquals("RAG_CHAT", TraceContext.getBusinessType());
+ assertEquals("session-1", TraceContext.getBusinessId());
+ assertEquals(10L, TraceContext.getUserId());
+ assertEquals("000000", TraceContext.getTenantId());
+ }
+ assertNull(TraceContext.getTraceId());
+ }
+
+ @Test
+ void nodeStackShouldTrackParentAndDepth() {
+ TraceContext.pushNode("root");
+ assertEquals("root", TraceContext.currentNodeId());
+ assertEquals(1, TraceContext.depth());
+
+ TraceContext.pushNode("child");
+ assertEquals("child", TraceContext.currentNodeId());
+ assertEquals(2, TraceContext.depth());
+
+ TraceContext.popNode();
+ assertEquals("root", TraceContext.currentNodeId());
+
+ TraceContext.popNode();
+ assertNull(TraceContext.currentNodeId());
+ assertEquals(0, TraceContext.depth());
+ }
+
+ @Test
+ void copyNodeStackShouldReturnIndependentDeque() {
+ TraceContext.pushNode("root");
+ Deque copy = TraceContext.copyNodeStack();
+ copy.push("child");
+
+ assertEquals("root", TraceContext.currentNodeId());
+ assertEquals("child", copy.peek());
+ }
+}
diff --git a/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/util/TracePayloadUtilsTest.java b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/util/TracePayloadUtilsTest.java
new file mode 100644
index 00000000..7c787c43
--- /dev/null
+++ b/ruoyi-common/ruoyi-common-trace/src/test/java/org/ruoyi/common/trace/util/TracePayloadUtilsTest.java
@@ -0,0 +1,40 @@
+package org.ruoyi.common.trace.util;
+
+import org.junit.jupiter.api.Test;
+import org.ruoyi.common.trace.config.TraceProperties;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class TracePayloadUtilsTest {
+
+ @Test
+ void truncateShouldRespectMaxLength() {
+ assertEquals("abc", TracePayloadUtils.truncate("abcdef", 3));
+ }
+
+ @Test
+ void truncateShouldHandleNull() {
+ assertNull(TracePayloadUtils.truncate(null, 3));
+ }
+
+ @Test
+ void toJsonShouldSerializeMap() {
+ String json = TracePayloadUtils.toJson(Map.of("count", 2));
+ assertTrue(json.contains("\"count\":2"));
+ }
+
+ @Test
+ void detailEnabledShouldTruncateInputAndOutput() {
+ TraceProperties properties = new TraceProperties();
+ properties.getPayload().setRecordDetail(true);
+ properties.getPayload().setMaxInputLength(4);
+ properties.getPayload().setMaxOutputLength(5);
+
+ assertEquals("1234", TracePayloadUtils.input("123456", properties));
+ assertEquals("12345", TracePayloadUtils.output("1234567", properties));
+ }
+}
diff --git a/ruoyi-modules/ruoyi-chat/pom.xml b/ruoyi-modules/ruoyi-chat/pom.xml
index f19e5a77..716e697e 100644
--- a/ruoyi-modules/ruoyi-chat/pom.xml
+++ b/ruoyi-modules/ruoyi-chat/pom.xml
@@ -29,6 +29,11 @@
ruoyi-common-sensitive
+
+ org.ruoyi
+ ruoyi-common-trace
+
+
dev.langchain4j
langchain4j-open-ai
diff --git a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/chat/impl/ChatServiceFacade.java b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/chat/impl/ChatServiceFacade.java
index 16e0750d..028ff230 100644
--- a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/chat/impl/ChatServiceFacade.java
+++ b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/chat/impl/ChatServiceFacade.java
@@ -50,6 +50,16 @@ import org.ruoyi.common.core.utils.StringUtils;
import org.ruoyi.common.satoken.utils.LoginHelper;
import org.ruoyi.common.sse.core.SseEmitterManager;
import org.ruoyi.common.sse.utils.SseMessageUtils;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.core.DefaultTraceStreamSpan;
+import org.ruoyi.common.trace.core.TraceContext;
+import org.ruoyi.common.trace.core.TraceScope;
+import org.ruoyi.common.trace.core.TraceStreamSpan;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.domain.TraceRun;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
import org.ruoyi.domain.bo.vector.QueryVectorBo;
import org.ruoyi.domain.vo.knowledge.KnowledgeInfoVo;
import org.ruoyi.factory.ChatServiceFactory;
@@ -62,14 +72,19 @@ import org.ruoyi.service.knowledge.IKnowledgeInfoService;
import org.ruoyi.service.retrieval.KnowledgeRetrievalService;
import org.ruoyi.service.knowledge.retriever.CustomVectorRetriever;
import org.ruoyi.service.vector.VectorStoreService;
+import org.ruoyi.trace.RagTraceNodeTypes;
+import org.ruoyi.trace.RagTracePayloadBuilder;
import org.springframework.stereotype.Service;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
import java.util.ArrayList;
+import java.util.Date;
import java.util.List;
import java.util.Map;
+import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicBoolean;
/**
* 聊天服务门面层
@@ -106,6 +121,10 @@ public class ChatServiceFacade implements IChatService {
private final ToolProviderFactory toolProviderFactory;
+ private final TraceRecordService traceRecordService;
+
+ private final TraceProperties traceProperties;
+
/**
* 内存实例缓存，避免同一会话重复创建
* Key: sessionId, Value: MessageWindowChatMemory实例
@@ -133,14 +152,10 @@ public class ChatServiceFacade implements IChatService {
throw new IllegalArgumentException("模型不存在: " + chatRequest.getModel());
}
- // 2. 构建上下文消息列表
- List contextMessages = buildContextMessages(chatRequest);
-
chatRequest.setEmitter(emitter);
chatRequest.setUserId(userId);
chatRequest.setTokenValue(tokenValue);
chatRequest.setChatModelVo(chatModelVo);
- chatRequest.setContextMessages(contextMessages);
// 保存用户消息
chatMessageService.saveChatMessage(userId, chatRequest.getSessionId(), chatRequest.getContent(), RoleType.USER.getName(), chatRequest.getModel());
@@ -151,18 +166,145 @@ public class ChatServiceFacade implements IChatService {
return sseEmitter;
}
- // 4. 路由服务提供商
- String providerCode = chatModelVo.getProviderCode();
+ TraceRunHandle traceRun = startRagTraceRun(chatRequest, userId);
+ try (TraceScope ignored = openTraceScope(traceRun, userId)) {
+ // 4. 构建上下文消息列表，普通 RAG 检索会在当前 trace 上下文中执行
+ List contextMessages = buildContextMessages(chatRequest);
+ chatRequest.setContextMessages(contextMessages);
+
+ // 5. 路由并发起普通 RAG 对话
+ executeNormalRagChat(chatRequest, userId, tokenValue, contextMessages, traceRun);
+ } catch (RuntimeException | Error e) {
+ finishTraceRun(traceRun, TraceConstants.STATUS_ERROR, e);
+ throw e;
+ }
+ return emitter;
+ }
+
+ private void executeNormalRagChat(ChatRequest chatRequest, Long userId, String tokenValue,
+ List contextMessages, TraceRunHandle traceRun) {
+ String providerCode = chatRequest.getChatModelVo().getProviderCode();
log.info("路由到服务提供商: {}, 模型: {}", providerCode, chatRequest.getModel());
AbstractChatService chatService = chatServiceFactory.getOriginalService(providerCode);
- StreamingChatResponseHandler handler = createResponseHandler(userId, tokenValue,chatRequest);
+ TraceStreamSpan llmSpan = startLlmCallSpan(traceRun, chatRequest);
+ try {
+ StreamingChatResponseHandler handler = createResponseHandler(userId, tokenValue, chatRequest,
+ traceRun, llmSpan);
+ StreamingChatModel streamingChatModel = chatService.buildStreamingChatModel(chatRequest.getChatModelVo(), chatRequest);
+ streamingChatModel.chat(contextMessages, handler);
+ } catch (RuntimeException | Error e) {
+ if (llmSpan != null) {
+ llmSpan.finishError(e);
+ }
+ throw e;
+ } finally {
+ if (llmSpan != null) {
+ llmSpan.detach();
+ }
+ }
+ }
- // 5. 发起对话
- StreamingChatModel streamingChatModel = chatService.buildStreamingChatModel(chatModelVo, chatRequest);
- streamingChatModel.chat(contextMessages, handler);
- return emitter;
+ private TraceRunHandle startRagTraceRun(ChatRequest chatRequest, Long userId) {
+ if (!traceProperties.isEnabled()) {
+ return null;
+ }
+
+ String traceId = UUID.randomUUID().toString().replace("-", "");
+ long startMillis = System.currentTimeMillis();
+ TraceRun run = new TraceRun();
+ run.setTraceId(traceId);
+ run.setTraceName(RagTraceNodeTypes.TRACE_NAME_RAG_CHAT);
+ run.setBusinessType(RagTraceNodeTypes.BUSINESS_TYPE_RAG_CHAT);
+ run.setBusinessId(chatRequest.getSessionId() == null ? null : chatRequest.getSessionId().toString());
+ run.setUserId(userId);
+ run.setTenantId(safeGetTenantId());
+ run.setStatus(TraceConstants.STATUS_RUNNING);
+ run.setStartTime(new Date(startMillis));
+ run.setMetadata(RagTracePayloadBuilder.chatRequestSummary(chatRequest));
+
+ try {
+ traceRecordService.startRun(run);
+ } catch (Exception e) {
+ log.warn("写入 RAG chat trace run 失败，traceId={}", traceId, e);
+ }
+ return new TraceRunHandle(traceId, startMillis, run.getBusinessId(), run.getTenantId());
+ }
+
+ private TraceScope openTraceScope(TraceRunHandle traceRun, Long userId) {
+ if (traceRun == null) {
+ return null;
+ }
+ return TraceContext.begin(traceRun.traceId, RagTraceNodeTypes.BUSINESS_TYPE_RAG_CHAT,
+ traceRun.businessId, userId, traceRun.tenantId);
+ }
+
+ private TraceStreamSpan startLlmCallSpan(TraceRunHandle traceRun, ChatRequest chatRequest) {
+ if (traceRun == null || StringUtils.isBlank(TraceContext.getTraceId())) {
+ return null;
+ }
+
+ String nodeId = UUID.randomUUID().toString().replace("-", "");
+ long startMillis = System.currentTimeMillis();
+ TraceNode node = new TraceNode();
+ node.setTraceId(traceRun.traceId);
+ node.setNodeId(nodeId);
+ node.setParentNodeId(TraceContext.currentNodeId());
+ node.setDepth(TraceContext.depth());
+ node.setNodeName("llm-call");
+ node.setNodeType(RagTraceNodeTypes.NODE_LLM_CALL);
+ node.setClassName(ChatServiceFacade.class.getName());
+ node.setMethodName("executeNormalRagChat");
+ node.setStatus(TraceConstants.STATUS_RUNNING);
+ node.setStartTime(new Date(startMillis));
+ node.setInputPayload(RagTracePayloadBuilder.streamInputSummary(chatRequest));
+
+ try {
+ traceRecordService.startNode(node);
+ TraceContext.pushNode(nodeId);
+ return new DefaultTraceStreamSpan(traceRecordService, traceProperties, traceRun.traceId, nodeId, startMillis);
+ } catch (Exception e) {
+ log.warn("写入 LLM trace 节点失败，traceId={}, nodeId={}", traceRun.traceId, nodeId, e);
+ return null;
+ }
+ }
+
+ private void finishTraceRun(TraceRunHandle traceRun, String status, Throwable error) {
+ if (traceRun == null || !traceRun.finished.compareAndSet(false, true)) {
+ return;
+ }
+ try {
+ traceRecordService.finishRun(traceRun.traceId, status, TracePayloadUtils.error(error, traceProperties),
+ new Date(), System.currentTimeMillis() - traceRun.startMillis);
+ } catch (Exception e) {
+ log.warn("结束 RAG chat trace run 失败，traceId={}", traceRun.traceId, e);
+ }
+ }
+
+ private String safeGetTenantId() {
+ try {
+ return LoginHelper.getTenantId();
+ } catch (Exception e) {
+ log.warn("获取 trace tenantId 失败: {}", e.getMessage());
+ return null;
+ }
+ }
+
+ private static final class TraceRunHandle {
+
+ private final String traceId;
+ private final long startMillis;
+ private final String businessId;
+ private final String tenantId;
+ private final AtomicBoolean finished = new AtomicBoolean(false);
+
+ private TraceRunHandle(String traceId, long startMillis, String businessId, String tenantId) {
+ this.traceId = traceId;
+ this.startMillis = startMillis;
+ this.businessId = businessId;
+ this.tenantId = tenantId;
+ }
}
/**
@@ -509,6 +651,11 @@ public class ChatServiceFacade implements IChatService {
* @return 标准的流式响应处理器
*/
protected StreamingChatResponseHandler createResponseHandler(Long userId, String tokenValue,ChatRequest chatRequest) {
+ return createResponseHandler(userId, tokenValue, chatRequest, null, null);
+ }
+
+ private StreamingChatResponseHandler createResponseHandler(Long userId, String tokenValue, ChatRequest chatRequest,
+ TraceRunHandle traceRun, TraceStreamSpan streamSpan) {
return new StreamingChatResponseHandler() {
private final StringBuilder messageBuffer = new StringBuilder();
@@ -540,19 +687,35 @@ public class ChatServiceFacade implements IChatService {
chatMessageService.saveChatMessage(userId, chatRequest.getSessionId(), fullMessage, RoleType.ASSISTANT.getName(), chatRequest.getModel());
}
+ if (streamSpan != null) {
+ streamSpan.finishSuccess();
+ }
+ finishTraceRun(traceRun, TraceConstants.STATUS_SUCCESS, null);
+
// 关闭SSE连接
SseMessageUtils.completeConnection(userId, tokenValue);
log.info("消息结束，已保存到数据库");
} catch (Exception e) {
log.error("完成响应时出错: {}", e.getMessage(), e);
+ if (streamSpan != null) {
+ streamSpan.finishError(e);
+ }
+ finishTraceRun(traceRun, TraceConstants.STATUS_ERROR, e);
}
}
@Override
public void onError(Throwable error) {
// 发送错误事件
- SseMessageUtils.sendError(userId, error.getMessage());
- log.error("流式响应错误: {}", error.getMessage());
+ try {
+ SseMessageUtils.sendError(userId, error.getMessage());
+ } finally {
+ if (streamSpan != null) {
+ streamSpan.finishError(error);
+ }
+ finishTraceRun(traceRun, TraceConstants.STATUS_ERROR, error);
+ log.error("流式响应错误: {}", error.getMessage(), error);
+ }
}
};
}
diff --git a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/retrieval/impl/KnowledgeRetrievalServiceImpl.java b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/retrieval/impl/KnowledgeRetrievalServiceImpl.java
index b6841ef1..56723057 100644
--- a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/retrieval/impl/KnowledgeRetrievalServiceImpl.java
+++ b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/service/retrieval/impl/KnowledgeRetrievalServiceImpl.java
@@ -3,6 +3,13 @@ package org.ruoyi.service.retrieval.impl;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.ruoyi.common.core.utils.StringUtils;
+import org.ruoyi.common.trace.config.TraceProperties;
+import org.ruoyi.common.trace.constant.TraceConstants;
+import org.ruoyi.common.trace.core.TraceContext;
+import org.ruoyi.common.trace.core.TraceNodeTemplate;
+import org.ruoyi.common.trace.domain.TraceNode;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
import org.ruoyi.domain.bo.rerank.RerankRequest;
import org.ruoyi.domain.bo.rerank.RerankResult;
import org.ruoyi.domain.bo.vector.QueryVectorBo;
@@ -13,10 +20,13 @@ import org.ruoyi.mapper.knowledge.KnowledgeFragmentMapper;
import org.ruoyi.service.rerank.RerankModelService;
import org.ruoyi.service.retrieval.KnowledgeRetrievalService;
import org.ruoyi.service.vector.VectorStoreService;
+import org.ruoyi.trace.RagTraceNodeTypes;
+import org.ruoyi.trace.RagTracePayloadBuilder;
import org.springframework.stereotype.Service;
import java.util.*;
import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicBoolean;
import java.util.stream.Collectors;
/**
@@ -34,6 +44,8 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
private final VectorStoreService vectorStoreService;
private final RerankModelFactory rerankModelFactory;
private final KnowledgeFragmentMapper fragmentMapper;
+ private final TraceRecordService traceRecordService;
+ private final TraceProperties traceProperties;
/**
* 粗召回默认扩大倍数
@@ -53,33 +65,40 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
public List retrieve(QueryVectorBo queryVectorBo) {
log.info("开始知识库检索, kid={}, query={}", queryVectorBo.getKid(), queryVectorBo.getQuery());
- // 1. 粗召回阶段 (向量检索 + 关键词搜索)
- List coarseResults = performCoarseRetrieval(queryVectorBo);
- log.debug("粗召回返回 {} 条结果", coarseResults.size());
+ return TraceNodeTemplate.withNode(traceRecordService, traceProperties,
+ "retrieval", RagTraceNodeTypes.NODE_RETRIEVAL,
+ KnowledgeRetrievalServiceImpl.class.getName(), "retrieve",
+ RagTracePayloadBuilder.retrievalInputSummary(queryVectorBo),
+ () -> {
+ // 1. 粗召回阶段 (向量检索 + 关键词搜索)
+ List coarseResults = performCoarseRetrieval(queryVectorBo);
+ log.debug("粗召回返回 {} 条结果", coarseResults.size());
- if (coarseResults.isEmpty()) {
- return coarseResults;
- }
+ if (coarseResults.isEmpty()) {
+ return coarseResults;
+ }
- // 2. 初始化原始索引
- for (int i = 0; i < coarseResults.size(); i++) {
- coarseResults.get(i).setOriginalIndex(i);
- }
+ // 2. 初始化原始索引
+ for (int i = 0; i < coarseResults.size(); i++) {
+ coarseResults.get(i).setOriginalIndex(i);
+ }
- // 3. 重排序阶段 (可选)
- List finalResults = coarseResults;
- if (Boolean.TRUE.equals(queryVectorBo.getEnableRerank()) &&
- StringUtils.isNotBlank(queryVectorBo.getRerankModelName())) {
- finalResults = performRerank(queryVectorBo, coarseResults);
- }
+ // 3. 重排序阶段 (可选)
+ List finalResults = coarseResults;
+ if (Boolean.TRUE.equals(queryVectorBo.getEnableRerank()) &&
+ StringUtils.isNotBlank(queryVectorBo.getRerankModelName())) {
+ finalResults = performRerank(queryVectorBo, coarseResults);
+ }
- // 4. 应用分值阈值过滤 (重排分值或 RRF 分值)
- double threshold = queryVectorBo.getRerankScoreThreshold() != null ?
- queryVectorBo.getRerankScoreThreshold() : 0.0;
-
- return finalResults.stream()
- .filter(res -> res.getScore() >= threshold)
- .collect(Collectors.toList());
+ // 4. 应用分值阈值过滤 (重排分值或 RRF 分值)
+ double threshold = queryVectorBo.getRerankScoreThreshold() != null ?
+ queryVectorBo.getRerankScoreThreshold() : 0.0;
+
+ return finalResults.stream()
+ .filter(res -> res.getScore() >= threshold)
+ .collect(Collectors.toList());
+ },
+ RagTracePayloadBuilder::retrievalOutputSummary);
}
/**
@@ -163,6 +182,9 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
* 重排序阶段
*/
private List performRerank(QueryVectorBo queryVectorBo, List coarseResults) {
+ int topN = queryVectorBo.getRerankTopN() != null ? queryVectorBo.getRerankTopN() : queryVectorBo.getMaxResults();
+ TraceNodeHandle traceNode = startTraceNode("rerank", RagTraceNodeTypes.NODE_RERANK, "performRerank",
+ RagTracePayloadBuilder.rerankInputSummary(queryVectorBo, coarseResults.size(), topN));
try {
RerankModelService rerankModel = rerankModelFactory.createModel(queryVectorBo.getRerankModelName());
@@ -170,9 +192,6 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
.map(KnowledgeRetrievalVo::getContent)
.collect(Collectors.toList());
- // topN 默认为 maxResults
- int topN = queryVectorBo.getRerankTopN() != null ? queryVectorBo.getRerankTopN() : queryVectorBo.getMaxResults();
-
RerankRequest rerankRequest = RerankRequest.builder()
.query(queryVectorBo.getQuery())
.documents(contents)
@@ -194,12 +213,18 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
coarseResults.sort((a, b) -> b.getScore().compareTo(a.getScore()));
// 截断到 topN
- return coarseResults.subList(0, Math.min(topN, coarseResults.size()));
+ List rerankedResults = coarseResults.subList(0, Math.min(topN, coarseResults.size()));
+ finishTraceNode(traceNode, TraceConstants.STATUS_SUCCESS, null,
+ RagTracePayloadBuilder.rerankOutputSummary(rerankedResults));
+ return rerankedResults;
} catch (Exception e) {
log.error("重排序流程失败: {}", e.getMessage());
int limit = queryVectorBo.getMaxResults() != null ? queryVectorBo.getMaxResults() : 10;
- return coarseResults.subList(0, Math.min(limit, coarseResults.size()));
+ List fallbackResults = coarseResults.subList(0, Math.min(limit, coarseResults.size()));
+ finishTraceNode(traceNode, TraceConstants.STATUS_ERROR, e,
+ RagTracePayloadBuilder.rerankOutputSummary(fallbackResults));
+ return fallbackResults;
}
}
@@ -242,6 +267,52 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
return fusedResults;
}
+ private TraceNodeHandle startTraceNode(String nodeName, String nodeType, String methodName, String inputPayload) {
+ if (!traceProperties.isEnabled() || StringUtils.isBlank(TraceContext.getTraceId())) {
+ return null;
+ }
+
+ String traceId = TraceContext.getTraceId();
+ String nodeId = UUID.randomUUID().toString().replace("-", "");
+ long startMillis = System.currentTimeMillis();
+ TraceNode node = new TraceNode();
+ node.setTraceId(traceId);
+ node.setNodeId(nodeId);
+ node.setParentNodeId(TraceContext.currentNodeId());
+ node.setDepth(TraceContext.depth());
+ node.setNodeName(nodeName);
+ node.setNodeType(nodeType);
+ node.setClassName(KnowledgeRetrievalServiceImpl.class.getName());
+ node.setMethodName(methodName);
+ node.setStatus(TraceConstants.STATUS_RUNNING);
+ node.setStartTime(new Date(startMillis));
+ node.setInputPayload(inputPayload);
+
+ try {
+ traceRecordService.startNode(node);
+ TraceContext.pushNode(nodeId);
+ return new TraceNodeHandle(traceId, nodeId, startMillis);
+ } catch (Exception e) {
+ log.warn("写入 RAG 检索 trace 节点失败，traceId={}, nodeId={}", traceId, nodeId, e);
+ return null;
+ }
+ }
+
+ private void finishTraceNode(TraceNodeHandle traceNode, String status, Throwable error, String outputPayload) {
+ if (traceNode == null || !traceNode.finished.compareAndSet(false, true)) {
+ return;
+ }
+ try {
+ traceRecordService.finishNode(traceNode.traceId, traceNode.nodeId, status,
+ TracePayloadUtils.error(error, traceProperties), outputPayload,
+ new Date(), System.currentTimeMillis() - traceNode.startMillis);
+ } catch (Exception e) {
+ log.warn("结束 RAG 检索 trace 节点失败，traceId={}, nodeId={}", traceNode.traceId, traceNode.nodeId, e);
+ } finally {
+ TraceContext.popNode();
+ }
+ }
+
private QueryVectorBo copyOf(QueryVectorBo original, int maxResults) {
QueryVectorBo copy = new QueryVectorBo();
copy.setQuery(original.getQuery());
@@ -253,4 +324,18 @@ public class KnowledgeRetrievalServiceImpl implements KnowledgeRetrievalService
copy.setBaseUrl(original.getBaseUrl());
return copy;
}
+
+ private static final class TraceNodeHandle {
+
+ private final String traceId;
+ private final String nodeId;
+ private final long startMillis;
+ private final AtomicBoolean finished = new AtomicBoolean(false);
+
+ private TraceNodeHandle(String traceId, String nodeId, long startMillis) {
+ this.traceId = traceId;
+ this.nodeId = nodeId;
+ this.startMillis = startMillis;
+ }
+ }
}
diff --git a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTraceNodeTypes.java b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTraceNodeTypes.java
new file mode 100644
index 00000000..ab751e03
--- /dev/null
+++ b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTraceNodeTypes.java
@@ -0,0 +1,18 @@
+package org.ruoyi.trace;
+
+/**
+ * RAG trace 业务与节点类型常量。
+ */
+public final class RagTraceNodeTypes {
+
+ private RagTraceNodeTypes() {
+ }
+
+ public static final String BUSINESS_TYPE_RAG_CHAT = "RAG_CHAT";
+ public static final String TRACE_NAME_RAG_CHAT = "rag-chat";
+
+ public static final String NODE_RETRIEVAL = "RETRIEVAL";
+ public static final String NODE_RERANK = "RERANK";
+ public static final String NODE_LLM_CALL = "LLM_CALL";
+ public static final String NODE_STREAM = "STREAM";
+}
diff --git a/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTracePayloadBuilder.java b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTracePayloadBuilder.java
new file mode 100644
index 00000000..b5a2255e
--- /dev/null
+++ b/ruoyi-modules/ruoyi-chat/src/main/java/org/ruoyi/trace/RagTracePayloadBuilder.java
@@ -0,0 +1,132 @@
+package org.ruoyi.trace;
+
+import org.ruoyi.common.chat.domain.dto.request.ChatRequest;
+import org.ruoyi.common.chat.domain.vo.chat.ChatModelVo;
+import org.ruoyi.common.trace.util.TracePayloadUtils;
+import org.ruoyi.domain.bo.vector.QueryVectorBo;
+import org.ruoyi.domain.vo.knowledge.KnowledgeRetrievalVo;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * RAG trace payload 摘要构建器。
+ */
+public final class RagTracePayloadBuilder {
+
+ private static final int MAX_RESULT_SUMMARY_SIZE = 5;
+
+ private RagTracePayloadBuilder() {
+ }
+
+ public static String chatRequestSummary(ChatRequest request) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("requestPresent", request != null);
+ if (request == null) {
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ ChatModelVo model = request.getChatModelVo();
+ payload.put("sessionId", request.getSessionId() == null ? null : request.getSessionId().toString());
+ payload.put("model", request.getModel());
+ payload.put("providerCode", model == null ? null : model.getProviderCode());
+ payload.put("knowledgeId", request.getKnowledgeId());
+ payload.put("hasKnowledge", request.getKnowledgeId() != null);
+ payload.put("contentLength", length(request.getContent()));
+ payload.put("contextMessageCount", request.getContextMessages() == null ? null : request.getContextMessages().size());
+ payload.put("enableWorkFlow", request.getEnableWorkFlow());
+ payload.put("isResume", request.getIsResume());
+ payload.put("enableThinking", request.getEnableThinking());
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String retrievalInputSummary(QueryVectorBo query) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("queryPresent", query != null);
+ if (query == null) {
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ payload.put("kid", query.getKid());
+ payload.put("queryLength", length(query.getQuery()));
+ payload.put("maxResults", query.getMaxResults());
+ payload.put("vectorModelName", query.getVectorModelName());
+ payload.put("embeddingModelName", query.getEmbeddingModelName());
+ payload.put("enableHybrid", query.getEnableHybrid());
+ payload.put("hybridAlpha", query.getHybridAlpha());
+ payload.put("similarityThreshold", query.getSimilarityThreshold());
+ payload.put("enableRerank", query.getEnableRerank());
+ payload.put("rerankModel", query.getRerankModelName());
+ payload.put("rerankTopN", query.getRerankTopN());
+ payload.put("rerankScoreThreshold", query.getRerankScoreThreshold());
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String retrievalOutputSummary(List results) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("resultCount", results == null ? 0 : results.size());
+ payload.put("results", summarizeResults(results));
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String rerankInputSummary(QueryVectorBo query, int candidateCount, Integer topN) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("candidateCount", candidateCount);
+ payload.put("rerankModel", query == null ? null : query.getRerankModelName());
+ payload.put("topN", topN);
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String rerankOutputSummary(List results) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("resultCount", results == null ? 0 : results.size());
+ payload.put("results", summarizeResults(results));
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String streamInputSummary(ChatRequest request) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("sessionId", request == null || request.getSessionId() == null ? null : request.getSessionId().toString());
+ payload.put("model", request == null ? null : request.getModel());
+ payload.put("contextMessageCount", request == null || request.getContextMessages() == null ? null : request.getContextMessages().size());
+ payload.put("contentLength", request == null ? null : length(request.getContent()));
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ public static String streamOutputSummary(int responseLength) {
+ Map payload = new LinkedHashMap<>();
+ payload.put("responseLength", responseLength);
+ return TracePayloadUtils.toJson(payload);
+ }
+
+ private static List> summarizeResults(List results) {
+ List> summaries = new ArrayList<>();
+ if (results == null || results.isEmpty()) {
+ return summaries;
+ }
+
+ int limit = Math.min(MAX_RESULT_SUMMARY_SIZE, results.size());
+ for (int i = 0; i < limit; i++) {
+ KnowledgeRetrievalVo result = results.get(i);
+ Map item = new LinkedHashMap<>();
+ item.put("rank", i + 1);
+ item.put("id", result == null ? null : result.getId());
+ item.put("docId", result == null ? null : result.getDocId());
+ item.put("knowledgeId", result == null || result.getKnowledgeId() == null ? null : result.getKnowledgeId().toString());
+ item.put("idx", result == null ? null : result.getIdx());
+ item.put("score", result == null ? null : result.getScore());
+ item.put("rawScore", result == null ? null : result.getRawScore());
+ item.put("originalIndex", result == null ? null : result.getOriginalIndex());
+ item.put("sourceName", result == null ? null : result.getSourceName());
+ item.put("contentLength", result == null ? null : length(result.getContent()));
+ summaries.add(item);
+ }
+ return summaries;
+ }
+
+ private static Integer length(String value) {
+ return value == null ? null : value.length();
+ }
+}
diff --git a/ruoyi-modules/ruoyi-chat/src/test/java/org/ruoyi/trace/RagTracePayloadBuilderTest.java b/ruoyi-modules/ruoyi-chat/src/test/java/org/ruoyi/trace/RagTracePayloadBuilderTest.java
new file mode 100644
index 00000000..b6a242f5
--- /dev/null
+++ b/ruoyi-modules/ruoyi-chat/src/test/java/org/ruoyi/trace/RagTracePayloadBuilderTest.java
@@ -0,0 +1,78 @@
+package org.ruoyi.trace;
+
+import org.junit.jupiter.api.Test;
+import org.ruoyi.common.chat.domain.dto.request.ChatRequest;
+import org.ruoyi.common.chat.domain.vo.chat.ChatModelVo;
+import org.ruoyi.domain.bo.vector.QueryVectorBo;
+import org.ruoyi.domain.vo.knowledge.KnowledgeRetrievalVo;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class RagTracePayloadBuilderTest {
+
+ @Test
+ void chatRequestSummaryShouldHandleNullsAndAvoidPromptBody() {
+ ChatRequest request = new ChatRequest();
+ request.setSessionId(100L);
+ request.setModel("qwen-plus");
+ request.setKnowledgeId("200");
+ request.setContent("secret prompt body");
+
+ ChatModelVo model = new ChatModelVo();
+ model.setProviderCode("dashscope");
+ request.setChatModelVo(model);
+
+ String payload = RagTracePayloadBuilder.chatRequestSummary(request);
+
+ assertTrue(payload.contains("\"sessionId\":100"));
+ assertTrue(payload.contains("\"contentLength\":18"));
+ assertTrue(payload.contains("\"providerCode\":\"dashscope\""));
+ assertFalse(payload.contains("secret prompt body"));
+ }
+
+ @Test
+ void retrievalInputSummaryShouldUseSummaryOnly() {
+ QueryVectorBo query = new QueryVectorBo();
+ query.setKid("200");
+ query.setQuery("private retrieval query");
+ query.setMaxResults(5);
+ query.setEnableRerank(true);
+ query.setRerankModelName("gte-rerank");
+ query.setRerankTopN(null);
+
+ String payload = RagTracePayloadBuilder.retrievalInputSummary(query);
+
+ assertTrue(payload.contains("\"kid\":\"200\""));
+ assertTrue(payload.contains("\"queryLength\":23"));
+ assertTrue(payload.contains("\"enableRerank\":true"));
+ assertFalse(payload.contains("private retrieval query"));
+ }
+
+ @Test
+ void retrievalOutputSummaryShouldAvoidFragmentContent() {
+ KnowledgeRetrievalVo result = new KnowledgeRetrievalVo();
+ result.setId("fragment-1");
+ result.setDocId("doc-1");
+ result.setIdx(1);
+ result.setScore(0.85);
+ result.setContent("sensitive knowledge fragment");
+
+ String payload = RagTracePayloadBuilder.retrievalOutputSummary(List.of(result));
+
+ assertTrue(payload.contains("\"resultCount\":1"));
+ assertTrue(payload.contains("\"contentLength\":28"));
+ assertTrue(payload.contains("\"fragment-1\""));
+ assertFalse(payload.contains("sensitive knowledge fragment"));
+ }
+
+ @Test
+ void summariesShouldAcceptNullValuesWithoutMapOfNpe() {
+ assertTrue(RagTracePayloadBuilder.chatRequestSummary(null).contains("\"requestPresent\":false"));
+ assertTrue(RagTracePayloadBuilder.retrievalInputSummary(null).contains("\"queryPresent\":false"));
+ assertTrue(RagTracePayloadBuilder.retrievalOutputSummary(null).contains("\"resultCount\":0"));
+ assertTrue(RagTracePayloadBuilder.rerankInputSummary(null, 0, null).contains("\"candidateCount\":0"));
+ }
+}
diff --git a/ruoyi-modules/ruoyi-system/pom.xml b/ruoyi-modules/ruoyi-system/pom.xml
index 4a8a22ad..02a03e01 100644
--- a/ruoyi-modules/ruoyi-system/pom.xml
+++ b/ruoyi-modules/ruoyi-system/pom.xml
@@ -48,6 +48,11 @@
ruoyi-common-log
+
+ org.ruoyi
+ ruoyi-common-trace
+
+
org.ruoyi
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/ruoyi/system/controller/monitor/TraceController.java b/ruoyi-modules/ruoyi-system/src/main/java/org/ruoyi/system/controller/monitor/TraceController.java
new file mode 100644
index 00000000..bf44ba87
--- /dev/null
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/ruoyi/system/controller/monitor/TraceController.java
@@ -0,0 +1,68 @@
+package org.ruoyi.system.controller.monitor;
+
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import lombok.RequiredArgsConstructor;
+import org.ruoyi.common.core.domain.R;
+import org.ruoyi.common.mybatis.core.page.PageQuery;
+import org.ruoyi.common.mybatis.core.page.TableDataInfo;
+import org.ruoyi.common.trace.domain.bo.TraceRunBo;
+import org.ruoyi.common.trace.domain.vo.TraceDetailVo;
+import org.ruoyi.common.trace.domain.vo.TraceNodeVo;
+import org.ruoyi.common.trace.domain.vo.TraceRunVo;
+import org.ruoyi.common.trace.service.TraceRecordService;
+import org.ruoyi.common.web.core.BaseController;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 链路追踪监控
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/monitor/trace")
+public class TraceController extends BaseController {
+
+ private final TraceRecordService traceRecordService;
+
+ /**
+ * 获取链路追踪运行列表
+ */
+ @SaCheckPermission("monitor:trace:list")
+ @GetMapping("/run/list")
+ public TableDataInfo list(TraceRunBo bo, PageQuery pageQuery) {
+ return traceRecordService.pageRuns(bo, pageQuery);
+ }
+
+ /**
+ * 获取链路追踪运行详情
+ */
+ @SaCheckPermission("monitor:trace:query")
+ @GetMapping("/run/{traceId}")
+ public R run(@PathVariable String traceId) {
+ return R.ok(traceRecordService.getRun(traceId));
+ }
+
+ /**
+ * 获取链路追踪节点列表
+ */
+ @SaCheckPermission("monitor:trace:query")
+ @GetMapping("/node/list/{traceId}")
+ public R> nodes(@PathVariable String traceId) {
+ return R.ok(traceRecordService.listNodes(traceId));
+ }
+
+ /**
+ * 获取链路追踪完整详情
+ */
+ @SaCheckPermission("monitor:trace:query")
+ @GetMapping("/detail/{traceId}")
+ public R detail(@PathVariable String traceId) {
+ return R.ok(traceRecordService.getDetail(traceId));
+ }
+}