refactor(logging): 补齐核心模块日志与中文注释约束

2026-06-01 05:52:51 +08:00
parent 92b0a971f2
commit 1d401c6841
9 changed files with 95 additions and 6 deletions
--- a/common-agent-agent/src/main/java/com/bruce/agent/controller/AgentSessionController.java
+++ b/common-agent-agent/src/main/java/com/bruce/agent/controller/AgentSessionController.java
@@ -10,6 +10,7 @@ import com.bruce.agent.vo.AgentSessionDetailVO;
 import com.bruce.agent.vo.AgentWorkspaceVO;
 import com.bruce.common.domain.model.RequestResult;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -20,6 +21,12 @@ import org.springframework.web.bind.annotation.RestController;

 import java.util.List;

+/**
+ * Agent 会话控制器。
+ * <p>
+ * 负责会话创建、详情、消息查询与工作台聚合查询，保持前端只消费 DTO / VO 契约。
+ */
+@Slf4j
@RestController
@RequestMapping("/api/agent-sessions")
@RequiredArgsConstructor
@@ -31,16 +38,19 @@ public class AgentSessionController {

    @PostMapping("/create")
    public RequestResult<Boolean> create(@RequestBody AgentSessionCreateDTO request) {
+        log.info("Agent会话创建请求开始，agentId={}, sessionCode={}", request.getAgentId(), request.getSessionCode());
        return RequestResult.success(agentSessionService.createSession(request));
    }

    @GetMapping("/detail")
    public RequestResult<AgentSessionDetailVO> detail(@RequestParam("id") Long id) {
+        log.info("Agent会话详情查询开始，sessionId={}", id);
        return RequestResult.success(agentSessionService.getDetailById(id));
    }

    @GetMapping("/{sessionId}/messages")
    public RequestResult<List<AgentMessageVO>> messages(@PathVariable("sessionId") Long sessionId) {
+        log.info("Agent消息列表查询开始，sessionId={}", sessionId);
        return RequestResult.success(agentMessageService.listBySessionId(sessionId));
    }

@@ -48,12 +58,15 @@ public class AgentSessionController {
    public RequestResult<Boolean> appendMessage(@PathVariable("sessionId") Long sessionId,
                                                @RequestBody AgentSessionMessageCreateDTO request) {
        request.setSessionId(sessionId);
+        log.info("Agent消息写入请求开始，sessionId={}, role={}, requestId={}",
+                sessionId, request.getRole(), request.getRequestId());
        return RequestResult.success(agentMessageService.appendMessage(request));
    }

    @GetMapping("/workspace")
    public RequestResult<AgentWorkspaceVO> workspace(@RequestParam("agentId") Long agentId,
                                                     @RequestParam(value = "sessionId", required = false) Long sessionId) {
+        log.info("Agent工作台查询开始，agentId={}, sessionId={}", agentId, sessionId);
        return RequestResult.success(agentWorkspaceService.getWorkspace(agentId, sessionId));
    }
 }
--- a/common-agent-mcp/src/main/java/com/bruce/mcp/controller/McpImportController.java
+++ b/common-agent-mcp/src/main/java/com/bruce/mcp/controller/McpImportController.java
@@ -11,6 +11,7 @@ import com.bruce.mcp.vo.McpCapabilityVO;
 import com.bruce.mcp.vo.McpServerVO;
 import com.bruce.mcp.vo.McpWorkspaceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -21,6 +22,12 @@ import org.springframework.web.bind.annotation.RestController;

 import java.util.List;

+/**
+ * MCP 接入控制器。
+ * <p>
+ * 负责导入服务、查询服务与能力、以及工作台聚合视图查询。
+ */
+@Slf4j
@RestController
@RequestMapping("/api/mcp")
@RequiredArgsConstructor
@@ -33,16 +40,19 @@ public class McpImportController {

    @PostMapping("/import")
    public RequestResult<Boolean> importServer(@RequestBody McpImportDTO request) {
+        log.info("MCP服务导入开始，serverCode={}, importType={}", request.getServerCode(), request.getImportType());
        return RequestResult.success(mcpImportService.importServer(request));
    }

    @GetMapping("/servers")
    public RequestResult<List<McpServerVO>> listServers() {
+        log.info("MCP服务列表查询开始");
        return RequestResult.success(mcpServerService.listServers());
    }

    @GetMapping("/servers/{serverId}/capabilities")
    public RequestResult<List<McpCapabilityVO>> listCapabilities(@PathVariable("serverId") Long serverId) {
+        log.info("MCP能力列表查询开始，serverId={}", serverId);
        return RequestResult.success(mcpCapabilityService.listByServerId(serverId));
    }

@@ -51,16 +61,19 @@ public class McpImportController {
     */
    @GetMapping("/servers/code/{serverCode}/capabilities")
    public RequestResult<List<McpCapabilityVO>> listCapabilitiesByServerCode(@PathVariable("serverCode") String serverCode) {
+        log.info("MCP能力列表按编码查询开始，serverCode={}", serverCode);
        return RequestResult.success(mcpCapabilityService.listByServerCode(serverCode));
    }

    @PostMapping("/capabilities/save")
    public RequestResult<Boolean> saveCapability(@RequestBody McpCapabilitySaveDTO request) {
+        log.info("MCP能力保存开始，serverId={}, capabilityCode={}", request.getServerId(), request.getCapabilityCode());
        return RequestResult.success(mcpCapabilityService.saveCapability(request));
    }

    @GetMapping("/workspace")
    public RequestResult<McpWorkspaceVO> workspace(@RequestParam("serverId") Long serverId) {
+        log.info("MCP工作台查询开始，serverId={}", serverId);
        return RequestResult.success(mcpWorkspaceService.getWorkspace(serverId));
    }
 }
--- a/common-agent-modelprovider/src/main/java/com/bruce/modelprovider/service/impl/ModelRouteServiceImpl.java
+++ b/common-agent-modelprovider/src/main/java/com/bruce/modelprovider/service/impl/ModelRouteServiceImpl.java
@@ -8,6 +8,7 @@ import com.bruce.modelprovider.service.IModelConfigService;
 import com.bruce.modelprovider.service.IModelRouteRuleService;
 import com.bruce.modelprovider.service.IModelRouteService;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;

 import java.util.ArrayList;
@@ -25,9 +26,7 @@ import java.util.stream.Collectors;
 */
@Service
@RequiredArgsConstructor
-/**
- * ModelRouteServiceImpl，负责模型平台对应层的职责。
- */
+@Slf4j
 public class ModelRouteServiceImpl implements IModelRouteService {

    private final IModelRouteRuleService modelRouteRuleService;
@@ -40,13 +39,12 @@ public class ModelRouteServiceImpl implements IModelRouteService {
     * @return 路由决策结果，包含主模型、备用模型和命中原因
     */
    @Override
-    /**
-     * 方法 route，用于执行业务逻辑处理。
-     */
    public ModelRouteDecision route(ModelRouteContext context) {
        if (context == null) {
            throw new IllegalArgumentException("路由上下文不能为空");
        }
+        log.info("模型路由决策开始，taskType={}, matchScope={}, scopeId={}, modelType={}",
+                context.getTaskType(), context.getMatchScope(), context.getScopeId(), context.getRequiredModelType());
        ModelRouteRule rule = selectRule(context);
        if (rule == null) {
            ModelConfig defaultModel = modelConfigService.lambdaQuery()
@@ -62,6 +60,8 @@ public class ModelRouteServiceImpl implements IModelRouteService {
            decision.setPrimaryModel(defaultModel);
            decision.setRouteStrategy("MANUAL");
            decision.setReason("命中模型类型默认模型");
+            log.info("模型路由决策完成，taskType={}, strategy={}, primaryModelId={}, reason={}",
+                    context.getTaskType(), decision.getRouteStrategy(), defaultModel.getId(), decision.getReason());
            return decision;
        }

@@ -98,6 +98,8 @@ public class ModelRouteServiceImpl implements IModelRouteService {
        decision.setFallbackModels(fallbackModels);
        decision.setRouteStrategy(rule.getRouteStrategy());
        decision.setReason("命中规则: " + rule.getRouteCode());
+        log.info("模型路由决策完成，taskType={}, routeCode={}, primaryModelId={}, fallbackCount={}",
+                context.getTaskType(), rule.getRouteCode(), primary.getId(), fallbackModels.size());
        return decision;
    }

--- a/common-agent-observability/src/main/java/com/bruce/observability/controller/ObservabilityTraceController.java
+++ b/common-agent-observability/src/main/java/com/bruce/observability/controller/ObservabilityTraceController.java
@@ -9,6 +9,7 @@ import com.bruce.observability.vo.ObservabilityModelCallSummaryVO;
 import com.bruce.observability.vo.ObservabilityRunSummaryVO;
 import com.bruce.observability.vo.ObservabilityTraceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -20,6 +21,7 @@ import java.util.List;
 /**
 * 运行观测控制器，聚合 Workflow、Agent 和模型调用信息，返回脱敏摘要。
 */
+@Slf4j
@RestController
@RequestMapping("/api/observability")
@RequiredArgsConstructor
@@ -31,21 +33,25 @@ public class ObservabilityTraceController {

    @GetMapping("/runs")
    public RequestResult<List<ObservabilityRunSummaryVO>> runs() {
+        log.info("运行观测列表查询开始");
        return RequestResult.success(observabilityRunService.listRecentRuns());
    }

    @GetMapping("/runs/{requestId}")
    public RequestResult<ObservabilityTraceVO> trace(@PathVariable("requestId") String requestId) {
+        log.info("运行追踪查询开始，requestId={}", requestId);
        return RequestResult.success(observabilityTraceService.getTrace(requestId));
    }

    @GetMapping("/model-calls")
    public RequestResult<List<ObservabilityModelCallSummaryVO>> modelCalls(@RequestParam("requestId") String requestId) {
+        log.info("模型调用摘要查询开始，requestId={}", requestId);
        return RequestResult.success(observabilityTraceService.listModelCalls(requestId));
    }

    @GetMapping("/runs/{requestId}/export")
    public RequestResult<ObservabilityExportVO> export(@PathVariable("requestId") String requestId) {
+        log.info("运行追踪导出开始，requestId={}", requestId);
        return RequestResult.success(observabilityExportService.exportTrace(requestId));
    }
 }
--- a/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkEmbeddingServiceImpl.java
+++ b/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkEmbeddingServiceImpl.java
@@ -4,9 +4,21 @@ import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.bruce.rag.entity.RagChunkEmbedding;
 import com.bruce.rag.mapper.RagChunkEmbeddingMapper;
 import com.bruce.rag.service.IRagChunkEmbeddingService;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;

+/**
+ * 切片向量服务基础实现。
+ * <p>
+ * 当前模块首轮以主数据补全为主，这里保留统一的服务落点，便于后续继续承接向量写入、
+ * 重建索引和状态审计日志。
+ */
+@Slf4j
@Service
 public class RagChunkEmbeddingServiceImpl extends ServiceImpl<RagChunkEmbeddingMapper, RagChunkEmbedding>
        implements IRagChunkEmbeddingService {
+
+    public RagChunkEmbeddingServiceImpl() {
+        log.debug("RAG切片向量服务初始化完成");
+    }
 }
--- a/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkServiceImpl.java
+++ b/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagChunkServiceImpl.java
@@ -4,8 +4,20 @@ import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.bruce.rag.entity.RagChunk;
 import com.bruce.rag.mapper.RagChunkMapper;
 import com.bruce.rag.service.IRagChunkService;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;

+/**
+ * 切片服务基础实现。
+ * <p>
+ * 当前阶段主要复用 MyBatis-Plus 通用能力承载切片主数据访问，
+ * 统一保留服务层入口以便后续扩展切片重建和日志审计。
+ */
+@Slf4j
@Service
 public class RagChunkServiceImpl extends ServiceImpl<RagChunkMapper, RagChunk> implements IRagChunkService {
+
+    public RagChunkServiceImpl() {
+        log.debug("RAG切片服务初始化完成");
+    }
 }
--- a/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagDocumentParseResultServiceImpl.java
+++ b/common-agent-rag/src/main/java/com/bruce/rag/service/impl/RagDocumentParseResultServiceImpl.java
@@ -7,6 +7,7 @@ import com.bruce.rag.entity.RagDocumentParseResult;
 import com.bruce.rag.mapper.RagDocumentParseResultMapper;
 import com.bruce.rag.service.IRagDocumentParseResultService;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 import org.springframework.util.DigestUtils;
 import org.springframework.util.StringUtils;
@@ -17,6 +18,12 @@ import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.Map;

+/**
+ * 文档解析快照服务实现。
+ * <p>
+ * 负责把解析结果固化为文档快照，供切片与后续索引链路复用。
+ */
+@Slf4j
@Service
@RequiredArgsConstructor
 public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentParseResultMapper, RagDocumentParseResult>
@@ -29,6 +36,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
        if (documentId == null) {
            return null;
        }
+        log.info("查询文档解析快照开始，documentId={}", documentId);
        return getOne(Wrappers.<RagDocumentParseResult>lambdaQuery()
                .eq(RagDocumentParseResult::getDocumentId, documentId)
                .last("limit 1"));
@@ -39,6 +47,8 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
        if (storeId == null || documentId == null || parseResult == null) {
            throw new IllegalArgumentException("保存解析快照参数不完整");
        }
+        log.info("保存文档解析快照开始，storeId={}, documentId={}, textLength={}",
+                storeId, documentId, parseResult.getTextLength());
        RagDocumentParseResult existing = getByDocumentId(documentId);
        RagDocumentParseResult snapshot = existing == null ? new RagDocumentParseResult() : existing;
        snapshot.setStoreId(storeId);
@@ -56,6 +66,8 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
        } else {
            updateById(snapshot);
        }
+        log.info("保存文档解析快照完成，storeId={}, documentId={}, parseVersion={}, snapshotId={}",
+                storeId, documentId, snapshot.getParseVersion(), snapshot.getId());
    }

    @Override
@@ -91,6 +103,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
            Map<String, Object> payload = metadata == null ? new LinkedHashMap<>() : metadata;
            return objectMapper.writeValueAsString(payload);
        } catch (Exception e) {
+            log.error("解析元数据序列化失败，metadataKeys={}", metadata == null ? 0 : metadata.keySet(), e);
            throw new IllegalStateException("解析元数据序列化失败", e);
        }
    }
@@ -103,6 +116,7 @@ public class RagDocumentParseResultServiceImpl extends ServiceImpl<RagDocumentPa
            return objectMapper.readValue(metadataJson, new TypeReference<>() {
            });
        } catch (Exception e) {
+            log.error("解析元数据反序列化失败，metadataJson={}", metadataJson, e);
            throw new IllegalStateException("解析元数据反序列化失败", e);
        }
    }
--- a/common-agent-skill/src/main/java/com/bruce/skill/controller/SkillWorkspaceController.java
+++ b/common-agent-skill/src/main/java/com/bruce/skill/controller/SkillWorkspaceController.java
@@ -7,6 +7,7 @@ import com.bruce.skill.service.ISkillWorkspaceService;
 import com.bruce.skill.vo.SkillVersionVO;
 import com.bruce.skill.vo.SkillWorkspaceVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -18,6 +19,7 @@ import org.springframework.web.bind.annotation.RestController;
 /**
 * Skill 工作台接口，首轮对齐前端原型中的详情、草稿、测试、发布和归档能力。
 */
+@Slf4j
@RestController
@RequestMapping("/api/skills")
@RequiredArgsConstructor
@@ -28,30 +30,35 @@ public class SkillWorkspaceController {

    @GetMapping("/{skillCode}")
    public RequestResult<SkillWorkspaceVO> detail(@PathVariable("skillCode") String skillCode) {
+        log.info("Skill工作台详情查询开始，skillCode={}", skillCode);
        return RequestResult.success(skillWorkspaceService.getWorkspace(skillCode));
    }

    @PostMapping("/{skillCode}/draft")
    public RequestResult<Boolean> saveDraft(@PathVariable("skillCode") String skillCode,
                                            @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill草稿保存开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
        return RequestResult.success(skillVersionService.saveDraft(skillCode, request));
    }

    @PostMapping("/{skillCode}/test")
    public RequestResult<SkillVersionVO> test(@PathVariable("skillCode") String skillCode,
                                              @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill测试执行开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
        return RequestResult.success(skillVersionService.test(skillCode, request));
    }

    @PostMapping("/{skillCode}/publish")
    public RequestResult<Boolean> publish(@PathVariable("skillCode") String skillCode,
                                          @RequestBody SkillVersionSaveDTO request) {
+        log.info("Skill发布开始，skillCode={}, versionNo={}", skillCode, request.getVersionNo());
        return RequestResult.success(skillVersionService.publish(skillCode, request));
    }

    @PostMapping("/{skillCode}/archive")
    public RequestResult<Boolean> archive(@PathVariable("skillCode") String skillCode,
                                          @RequestParam("versionNo") Integer versionNo) {
+        log.info("Skill归档开始，skillCode={}, versionNo={}", skillCode, versionNo);
        return RequestResult.success(skillVersionService.archive(skillCode, versionNo));
    }
 }
--- a/common-agent-workflow/src/main/java/com/bruce/workflow/controller/ProjectController.java
+++ b/common-agent-workflow/src/main/java/com/bruce/workflow/controller/ProjectController.java
@@ -5,6 +5,7 @@ import com.bruce.workflow.dto.ProjectSaveDTO;
 import com.bruce.workflow.service.IProjectService;
 import com.bruce.workflow.vo.ProjectVO;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -14,6 +15,12 @@ import org.springframework.web.bind.annotation.RestController;

 import java.util.List;

+/**
+ * Studio 项目空间控制器。
+ * <p>
+ * 负责项目列表、详情和保存接口，对外统一返回 Project 相关 VO。
+ */
+@Slf4j
@RestController
@RequestMapping("/api/studio-projects")
@RequiredArgsConstructor
@@ -23,16 +30,19 @@ public class ProjectController {

    @GetMapping("/list")
    public RequestResult<List<ProjectVO>> list() {
+        log.info("Studio项目列表查询开始");
        return RequestResult.success(projectService.listProjects());
    }

    @GetMapping("/detail")
    public RequestResult<ProjectVO> detail(@RequestParam("id") Long id) {
+        log.info("Studio项目详情查询开始，projectId={}", id);
        return RequestResult.success(projectService.getProject(id));
    }

    @PostMapping("/save")
    public RequestResult<Boolean> save(@RequestBody ProjectSaveDTO request) {
+        log.info("Studio项目保存开始，projectId={}, projectCode={}", request.getId(), request.getProjectCode());
        return RequestResult.success(projectService.saveProject(request));
    }
 }