From 53c284e2436985e919bb63972de99512be6969cb Mon Sep 17 00:00:00 2001
From: LostInTwilight <1652154451@qq.com>
Date: Fri, 4 Sep 2026 13:44:38 +0800
Subject: [PATCH] docs(@vben-core/shared): correct filterTree
 reference-semantics comment

filterTree does not write its result back into the input tree, but childless
matched nodes are still returned by reference. The previous comment claimed no
source node is ever returned, which contradicted the implementation and could
mislead callers.
---
 packages/@core/base/shared/src/utils/tree.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/@core/base/shared/src/utils/tree.ts b/packages/@core/base/shared/src/utils/tree.ts
index ce43dc527..ca772815d 100644
--- a/packages/@core/base/shared/src/utils/tree.ts
+++ b/packages/@core/base/shared/src/utils/tree.ts
@@ -43,7 +43,9 @@ function traverseTreeValues<T, V>(
 /**
  * 根据条件过滤给定树结构的节点，并以原有顺序返回所有匹配节点的数组。
  *
- * 该函数是纯函数：不会修改传入的树，也不会把源节点直接放进结果里。
+ * 该函数是纯函数：不会把过滤后的结果写回传入的树（源数据不被修改）。
+ * 只有命中且带有子节点的节点会被浅拷贝，并用过滤后的子数组替换 children；
+ * 没有子节点的命中节点仍按引用返回，以保留原有的引用语义。
  * 否则第二次用不同条件过滤同一棵树时（例如切换用户角色后重新生成路由），
  * 上一次被过滤掉的子节点将永久丢失。
  *