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

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切片向量服务初始化完成");
+    }
 }

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切片服务初始化完成");
+    }
 }

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);
         }
     }