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