update 优化 翻译模块 增加逻辑注释和相关警告日志

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/enhance/JsonEnhancementContext.java

@@ -3,8 +3,8 @@ package org.dromara.common.json.enhance;
 import lombok.Getter;
 import tools.jackson.databind.json.JsonMapper;
 
+import java.util.LinkedHashMap;
 import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
 
 /**
  * 单次响应增强上下文。
@@ -14,7 +14,7 @@ public class JsonEnhancementContext {
 
     private final JsonMapper jsonMapper;
 
-    private final Map<String, Object> attributes = new ConcurrentHashMap<>();
+    private final Map<String, Object> attributes = new LinkedHashMap<>();
 
     public JsonEnhancementContext(JsonMapper jsonMapper) {
         this.jsonMapper = jsonMapper;

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/enhance/JsonFieldProcessor.java

@@ -2,15 +2,42 @@ package org.dromara.common.json.enhance;
 
 /**
  * 响应字段处理器。
+ *
+ * <p>生命周期按顺序分为三个阶段，由 {@link JsonValueEnhancer} 统一驱动：
+ * <ol>
+ *   <li><b>collect</b>（收集阶段）：递归扫描响应对象树时，对每个字段调用一次。
+ *       用于采集需要处理的字段 key，存入 {@link JsonEnhancementContext} 供下一阶段批量处理。</li>
+ *   <li><b>prepare</b>（预处理阶段）：collect 全部完成后调用一次。
+ *       用于执行批量 IO（如批量查询数据库），将结果写入 {@link JsonEnhancementContext}。
+ *       此阶段应消除 N+1 查询问题。</li>
+ *   <li><b>process</b>（处理阶段）：渲染响应 JSON 树时，对每个字段调用一次。
+ *       从 {@link JsonEnhancementContext} 取出 prepare 阶段写入的结果，返回替换后的字段值。
+ *       返回原 {@code value} 表示不修改；返回 {@code null} 表示将字段值置为 null。</li>
+ * </ol>
+ *
+ * <p>实现类通过 {@link JsonEnhancementContext#setAttribute} / {@link JsonEnhancementContext#getAttribute}
+ * 在三个阶段之间共享数据，建议以实现类全限定名作为 attribute key 前缀以避免冲突。
  */
 public interface JsonFieldProcessor {
 
+    /**
+     * 收集阶段：扫描字段，将需要处理的 key 存入 context。
+     * 每个字段调用一次，整个对象树扫描完成后才会进入 prepare 阶段。
+     */
     default void collect(JsonFieldContext fieldContext, JsonEnhancementContext context) {
     }
 
+    /**
+     * 预处理阶段：基于 collect 阶段收集到的数据执行批量处理（如批量查询），结果写入 context。
+     * 每次响应只调用一次。
+     */
     default void prepare(JsonEnhancementContext context) {
     }
 
+    /**
+     * 处理阶段：根据 prepare 阶段写入的结果，对字段值进行替换并返回。
+     * 返回原 {@code value} 表示不修改该字段；返回 {@code null} 表示将字段值置为 null。
+     */
     default Object process(JsonFieldContext fieldContext, Object value, JsonEnhancementContext context) {
         return value;
     }

ruoyi-common/ruoyi-common-translation/src/main/java/org/dromara/common/translation/core/TranslationInterface.java

@@ -4,6 +4,8 @@ import cn.hutool.core.convert.Convert;
 import org.dromara.common.core.utils.StreamUtils;
 import org.dromara.common.core.utils.StringUtils;
 import org.dromara.common.translation.annotation.TranslationType;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.Arrays;
 import java.util.Collection;
@@ -21,6 +23,8 @@ import java.util.function.Function;
  */
 public interface TranslationInterface<T> {
 
+    Logger log = LoggerFactory.getLogger(TranslationInterface.class);
+
     /**
      * 按翻译键执行转换。
      *
@@ -38,6 +42,9 @@ public interface TranslationInterface<T> {
      * @return 翻译结果映射
      */
     default Map<Object, T> translationBatch(Set<Object> keys, String other) {
+        TranslationType annotation = this.getClass().getAnnotation(TranslationType.class);
+        String type = annotation != null ? annotation.type() : this.getClass().getSimpleName();
+        log.warn("翻译类型 [{}] 未覆盖 translationBatch 方法，已退化为逐条查询，建议实现批量查询以提升性能", type);
         Map<Object, T> result = new LinkedHashMap<>(keys.size());
         for (Object key : keys) {
             result.put(key, translation(key, other));

ruoyi-common/ruoyi-common-translation/src/main/java/org/dromara/common/translation/core/handler/TranslationJsonFieldProcessor.java

@@ -88,7 +88,7 @@ public class TranslationJsonFieldProcessor implements JsonFieldProcessor {
         }
         Object sourceValue = resolveSourceValue(fieldContext, translation);
         if (sourceValue == null) {
-            return null;
+            return value;
         }
         TranslationBatchKey batchKey = new TranslationBatchKey(translation.type(), translation.other());
         Map<TranslationBatchKey, Map<Object, Object>> results = context.getAttribute(ATTR_RESULTS);