@lark-apaas/coding-template-nestjs-react-fullstack 0.1.52-alpha.20261027082821 → 0.1.52-alpha.20261027094037

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-nestjs-react-fullstack",
-  "version": "0.1.52-alpha.20261027082821",
+  "version": "0.1.52-alpha.20261027094037",
   "description": "NestJS + React fullstack template for miaoda coding",
   "type": "module",
   "files": [

package/template/client/src/components/business-ui/user-display/user-display.tsx

@@ -13,6 +13,18 @@ import {
   PopoverTrigger,
 } from '@client/src/components/ui/popover';
 
+/**
+ * 阻止 Popover 打开时的自动聚焦。
+ *
+ * Radix 的 FocusScope 在弹层挂载时会把焦点给容器里第一个可聚焦元素。人员卡片
+ * 挂载那一刻内容就已经在了（飞书名片里有「消息」等按钮），于是一打开就有个
+ * 按钮带上焦点环。这是张只读预览卡，焦点应该留在触发器上 —— Radix 自己的
+ * HoverCard 也是这么处理的。
+ */
+const handleProfileOpenAutoFocus = (event: Event) => {
+  event.preventDefault();
+};
+
 export interface IUserDisplayProps {
   /**
    * 用户列表
@@ -88,6 +100,7 @@ export const UserDisplay: React.FC<IUserDisplayProps> = ({
           <PopoverContent
             align="start"
             sideOffset={8}
+            onOpenAutoFocus={handleProfileOpenAutoFocus}
             className="w-[320px] border-0 border-border/50 bg-card p-0 shadow-[0px_8px_24px_8px_rgba(31,35,41,0.04),0px_6px_12px_rgba(31,35,41,0.04),0px_4px_8px_-8px_rgba(31,35,41,0.06)]"
           >
             <UserProfile value={user} />

package/template/client/src/components/business-ui/user-profile/lark-card-pool.ts

@@ -15,7 +15,8 @@
  */
 
 /** 池容量上限，超出按最近使用顺序淘汰 */
-let maxEntries = 5;
+/* 暂时放大到 20：观察同时备更多人时的内存与渲染开销，确认后再定最终值 */
+let maxEntries = 20;
 
 /**
  * 调整缓存策略：需要同时备好更多人的卡片时调大 maxEntries。

package/template/client/src/components/business-ui/user-profile/user-profile.tsx

@@ -2,7 +2,14 @@
 
 import { logger } from '@lark-apaas/client-toolkit/logger';
 
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import SHA1 from 'crypto-js/sha1';
 
 import { getAssetsUrl } from '@client/src/components/business-ui/api/user-profiles/service';
@@ -209,6 +216,42 @@ async function renderLarkProfile(
   return host.lastElementChild;
 }
 
+/**
+ * 渲染一张完整可用的名片。
+ *
+ * `visibleHost` 非空时直接渲进可见容器（首次打开，让用户看到飞书自己的骨架屏）；
+ * 否则开一个专属离屏插槽 —— 并发渲染共用容器会取错元素。插槽只用来隔离本次
+ * 渲染，拿到元素后就把它挪到离屏容器下并撤掉插槽，否则空壳 div 会累积。
+ *
+ * 放在模块级而不是 effect 内，是为了让「真正卸载时补备用卡」那条路径也能用，
+ * 不必把它写进 effect 的闭包、从而被迫放宽依赖。
+ */
+async function renderCard(
+  param: LarkCardParam,
+  visibleHost: HTMLElement | null,
+): Promise<Element | null> {
+  const slot = visibleHost ? null : createOffscreenSlot();
+  const live = await renderLarkProfile(param, visibleHost ?? slot!);
+
+  const settle = () => {
+    if (!slot) return;
+    if (live && live.parentNode === slot) getOffscreenHost().appendChild(live);
+    slot.remove();
+  };
+
+  if (!live) {
+    settle();
+    return null;
+  }
+  if (!(await waitForCardReady(live))) {
+    live.remove();
+    settle();
+    return null;
+  }
+  settle();
+  return live;
+}
+
 function UserProfile(props: UserProfileProps) {
   const { value, userId: originUserId, user_id, accountType = 'apaas' } = props;
 
@@ -292,30 +335,38 @@ function LarkProfileCard(props: { readonly larkCardParam: LarkCardParam }) {
   const { larkCardParam } = props;
   const { needRedirect, redirectURL, targetLarkOpenID } = larkCardParam;
 
+  // 「打开后更新」渲染出的元素由本实例独占 —— 它会被 attach 进本实例的容器，
+  // 取消时也由本实例回收。所以去重必须按实例隔离：ensureRender 的 key 是模块级的，
+  // 同一个人的两个实例共享一次渲染的话，两边会拿到同一个 DOM 元素，
+  // 后挂载的那个会把节点从前一个容器里抢走（前者变空白），先卸载的那个
+  // 还会把另一个正在显示的节点 remove 掉。
+  //
+  // 备用卡池仍然按人共享 —— 那条路径是 takeSpare 独占领取，不存在同一元素
+  // 被两个实例同时持有的问题。
+  const instanceId = useId();
+
   const hostRef = useRef<HTMLDivElement>(null);
   // 初值在渲染期就定下来：有备用卡就不该出现转圈。effect 在首次绘制之后
   // 才跑，若初值恒为 true，命中缓存也会先闪一帧 loading。
   const [showSpinner, setShowSpinner] = useState(() =>
-    !hasSpare(larkCardParam.targetLarkOpenID),
+    !hasSpare(targetLarkOpenID),
   );
-
-  // 这次挂载取到的备用卡。effect 可能在一次打开中跑多次（依赖变化、
-  // React 开发期双调用），而 takeSpare 是「取走」语义 —— 不记在 ref 里的话，
-  // 第二次就拿不到，会误判成没有缓存而走完整 loading。
-  const spareRef = useRef<Element | null>(null);
-
-  // 渲染失败（含就绪超时）。只在「屏幕上还什么都没有」时才需要告诉用户，
-  // 已经挂着备用卡的话保持现状即可。
   const [renderFailed, setRenderFailed] = useState(false);
   const [retryToken, setRetryToken] = useState(0);
 
-  // 挂上卡片那一刻、**本人那一屏**的文字。关闭时拿它和当前值比，就知道用户
-  // 有没有改过本人的数据（最典型的是编辑自己的个性签名）。只看本人那一屏，
-  // 是为了不把「点进上级的名片」这种纯导航误判成数据变化。
-  //
-  // 这是「同一个元素的前后两个时刻」比对，不是比两张独立渲染的卡 —— 后者
-  // 会被 CDN 分片轮换、图片懒加载时序等噪声污染，前者不会。
+  // 这次挂载取到的备用卡。takeSpare 是「取走」语义，effect 可能重复执行，
+  // 不记在 ref 里第二次就拿不到，会误判成没有缓存而走完整 loading。
+  const spareRef = useRef<Element | null>(null);
+  // 当前挂在容器里的那一张。卸载清理要用它，而那时 hostRef 可能已被置空。
+  const shownRef = useRef<Element | null>(null);
+  // 挂上那一刻、本人那一屏的文字。卸载时比对，判断用户有没有改过本人的数据。
   const attachedTextRef = useRef<string>('');
+  // 组件是否还活着。异步回调的归属是「组件实例」而不是「某一次 effect 执行」，
+  // 所以用它而不是 effect 内的 cancelled 标志 —— 否则依赖一变化，正在途中的
+  // 渲染结果就会被当成已取消而丢弃。
+  const aliveRef = useRef(true);
+  // 已经为哪一轮 retryToken 启动过渲染，保证依赖变化时不重复发起。
+  const startedRef = useRef(-1);
 
   const scriptOptions = useMemo(
     () => ({ onloadCallback: registerLarkAuthHandler }),
@@ -323,6 +374,13 @@ function LarkProfileCard(props: { readonly larkCardParam: LarkCardParam }) {
   );
   const scriptStatus = useExternalScript(LARK_SDK_URL, scriptOptions);
 
+  // 卸载清理需要的值走 ref，避免为了它们把依赖写宽
+  const teardownRef = useRef({ param: larkCardParam, scriptReady: false });
+  teardownRef.current = {
+    param: larkCardParam,
+    scriptReady: scriptStatus === 'ready',
+  };
+
   // 需要走鉴权重定向时整页跳转，不渲染名片
   useEffect(() => {
     if (needRedirect && redirectURL) {
@@ -330,6 +388,52 @@ function LarkProfileCard(props: { readonly larkCardParam: LarkCardParam }) {
     }
   }, [needRedirect, redirectURL]);
 
+  /**
+   * 只在**真正卸载**时回收。
+   *
+   * 不能放进主 effect 的 cleanup —— 那个 cleanup 在任何依赖变化时都会跑
+   * （scriptStatus 从 loading 变 ready、react-query 刷新导致 larkCardParam
+   * 换引用，都是必经路径）。在那里 remove 掉正在显示的卡片，会造成可见的
+   * 闪白回退，而且被摘掉的若是「打开后更新」那张，它既不在池里也不在容器里，
+   * 直接成了孤儿。
+   */
+  useEffect(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+
+      const shown = shownRef.current;
+      shownRef.current = null;
+      if (!shown) return;
+
+      const changed = ownProfileText(shown) !== attachedTextRef.current;
+      // 用过的那张直接丢弃 —— 它可能被滚动过、点进过别人的名片，
+      // 而这些状态有一半在飞书 React 内部，无法可靠恢复
+      shown.remove();
+
+      const { param, scriptReady } = teardownRef.current;
+      if (!changed || !scriptReady) return;
+
+      // 用户在卡片里改过本人的数据（最典型的是编辑个性签名）。已经备好的那张
+      // 是改动之前渲染的，内容已过时：丢掉，并立刻重新备一张 —— 只丢不补的话
+      // 下次打开会退回完整 loading。带时间戳的 key 绕开去重，确保拿到的是
+      // 改动之后重新渲染的结果。
+      dropSpare(param.targetLarkOpenID);
+      void ensureRender(
+        `${param.targetLarkOpenID}:spare:${String(Date.now())}`,
+        async () => {
+          const live = await renderCard(param, null);
+          if (live) putSpare(param.targetLarkOpenID, live);
+          return live;
+        },
+      ).catch((error: unknown) => {
+        logger.info('re-prepare spare lark profile failed', error);
+      });
+    };
+  }, []);
+
+  // 主逻辑。对重复执行幂等：已经挂了东西就不再顶备用卡，已经发起过的渲染
+  // 不重复发起。
   useEffect(() => {
     if (needRedirect) return;
 
@@ -337,145 +441,77 @@ function LarkProfileCard(props: { readonly larkCardParam: LarkCardParam }) {
     if (!host) return;
 
     currentRedirectURL = redirectURL ?? '';
-
     // 脚本已存在时 useExternalScript 会跳过 onloadCallback，这里补注册一次
     if (scriptStatus === 'ready') registerLarkAuthHandler();
 
-    let cancelled = false;
-
-    /**
-     * 把元素挂到当前容器，并移除容器里原有的那张。
-     * 用 replaceChildren 而不是 appendChild —— 后台换新时新旧两张都存在，
-     * 必须显式只留一张，不能依赖 putCard 内部清理旧元素的顺序。
-     * effect 已失效则什么都不做，元素留在池里等下次打开。
-     */
     const attach = (el: Element | null) => {
-      if (cancelled || !el) return;
+      if (!aliveRef.current || !el) return;
       host.replaceChildren(el);
+      shownRef.current = el;
       attachedTextRef.current = ownProfileText(el);
       setShowSpinner(false);
+      setRenderFailed(false);
     };
 
-    /**
-     * 渲染一张完整可用的名片。`visible` 为 true 时直接渲进可见容器（首次打开，
-     * 让用户看到飞书自己的骨架屏），否则开一个专属离屏插槽 —— 并发渲染共用
-     * 容器会取错元素。渲染不稳定（就绪超时）则判失败。
-     */
-    const renderInto = async (visible: boolean) => {
-      const slot = visible ? null : createOffscreenSlot();
-      const live = await renderLarkProfile(larkCardParam, slot ?? host);
-      // 插槽只用来隔离本次渲染，拿到元素后就把它挪到离屏容器下并撤掉插槽，
-      // 否则空壳 div 会一直累积
-      const settle = () => {
-        if (!slot) return;
-        if (live && live.parentNode === slot) getOffscreenHost().appendChild(live);
-        slot.remove();
-      };
-      if (!live) {
-        settle();
-        return null;
-      }
-      if (!(await waitForCardReady(live))) {
-        live.remove();
-        settle();
-        return null;
-      }
-      settle();
-      return live;
-    };
-
-    spareRef.current ??= takeSpare(targetLarkOpenID);
-    const spare = spareRef.current;
-
-    if (spare) {
-      // 备用卡是渲染好之后一直停在离屏、从没显示过的，所以必然是初始态，
-      // 而且它是活元素 —— 挂上即可交互，不是静态快照
-      attach(spare);
-    } else {
-      setShowSpinner(true);
+    if (!shownRef.current) {
+      // 备用卡是渲染好后一直停在离屏、从没显示过的，所以必然是初始态，
+      // 而且是活元素 —— 挂上即可交互，不是静态快照
+      spareRef.current ??= takeSpare(targetLarkOpenID);
+      if (spareRef.current) attach(spareRef.current);
     }
 
-    if (scriptStatus === 'ready') {
-      // 打开后更新一次：再渲染一张，就绪后换上去，让这次看到的是最新数据。
-      // 有备用卡顶着就离屏渲染（用户看不到骨架屏），没有就直接渲进可见容器。
-      void ensureRender(`${targetLarkOpenID}:update`, () => renderInto(!spare))
-        .then((live) => {
-          if (cancelled) {
-            // 组件已卸载（用户在新卡渲染完成前关掉了弹窗）。此时元素已经被
-            // renderInto 挪进常驻的离屏容器，既不会被 attach，也不进受
-            // maxEntries 约束的备用卡池 —— 放着不管就会随着反复开关一直累积。
-            live?.remove();
-            return;
-          }
-          if (live) {
-            attach(live);
-            return;
-          }
-          // 渲染没能就绪。屏幕上已经挂着备用卡就保持现状；什么都没有的话
-          // 必须收掉 loading 并给出重试入口，否则会一直转圈。
-          if (!host.firstElementChild) {
-            setShowSpinner(false);
-            setRenderFailed(true);
-          }
-        })
-        .catch((error: unknown) => {
-          logger.info('update lark profile failed', error);
-          if (cancelled) return;
+    if (scriptStatus !== 'ready') return;
+    if (startedRef.current === retryToken) return;
+    startedRef.current = retryToken;
+
+    const hadSpare = Boolean(shownRef.current);
+    if (!hadSpare) setShowSpinner(true);
+
+    // 打开后更新一次：再渲染一张，就绪后换上去，让这次看到的是最新数据。
+    // 有备用卡顶着就离屏渲染（用户看不到骨架屏），没有就直接渲进可见容器。
+    void ensureRender(
+      `${targetLarkOpenID}:update:${instanceId}:${String(retryToken)}`,
+      () => renderCard(larkCardParam, hadSpare ? null : host),
+    )
+      .then((live) => {
+        if (!aliveRef.current) {
+          // 组件已卸载。元素此时在常驻离屏容器里，既不会被 attach 也不进
+          // 受 maxEntries 约束的池 —— 放着不管会随反复开关一直累积。
+          live?.remove();
+          return;
+        }
+        if (live) {
+          attach(live);
+          return;
+        }
+        // 渲染没能就绪。已经挂着备用卡就保持现状；什么都没有的话必须收掉
+        // loading 并给出重试入口，否则会一直转圈。
+        if (!shownRef.current) {
           setShowSpinner(false);
-          if (!host.firstElementChild) setRenderFailed(true);
-        });
-
-      // 立刻开始备下一张。
-      //
-      // 这件事必须在「打开」时做，不能等到关闭 —— 真实环境里渲染一张要走
-      // 鉴权、render、飞书取数、图片加载，几秒起步。放在关闭时做的话，用户
-      // 稍微点快一点，下次打开就还没备好，又掉回完整 loading。放在打开时做，
-      // 它有「整个浏览时长 + 关闭后的间隔」来完成。
-      //
-      // 总开销不变，仍是一个开关周期两次渲染，只是把第二次提前了。
-      if (!hasSpare(targetLarkOpenID)) {
-        void ensureRender(`${targetLarkOpenID}:spare`, async () => {
-          const live = await renderInto(false);
-          if (live) putSpare(targetLarkOpenID, live);
-          return live;
-        }).catch((error: unknown) => {
-          logger.info('prepare spare lark profile failed', error);
-        });
-      }
-    }
-
-    return () => {
-      cancelled = true;
-
-      const shown = host.firstElementChild;
-      const changed =
-        !!shown && ownProfileText(shown) !== attachedTextRef.current;
+          setRenderFailed(true);
+        }
+      })
+      .catch((error: unknown) => {
+        logger.info('update lark profile failed', error);
+        if (!aliveRef.current) return;
+        setShowSpinner(false);
+        if (!shownRef.current) setRenderFailed(true);
+      });
 
-      // 用过的那张直接丢弃 —— 它可能被滚动过、点进过别人的名片，
-      // 而这些状态有一半在飞书 React 内部，我们无法可靠地恢复
-      shown?.remove();
-
-      if (!changed || scriptStatus !== 'ready') return;
-
-      // 用户在卡片里改过东西（最典型的是编辑自己的个性签名）。已经备好的
-      // 那张是改动之前渲染的，内容已经过时。
-      //
-      // 丢掉它，并**立刻重新备一张** —— 只丢不补的话，下次打开就退回完整
-      // loading，而「打开秒出」正是这套机制存在的理由。用带时间戳的 key
-      // 绕开去重，确保拿到的是改动之后重新渲染的结果。
-      dropSpare(targetLarkOpenID);
-      void ensureRender(
-        `${targetLarkOpenID}:spare:${String(Date.now())}`,
-        async () => {
-          const live = await renderInto(false);
-          if (live) putSpare(targetLarkOpenID, live);
-          return live;
-        },
-      ).catch((error: unknown) => {
-        logger.info('re-prepare spare lark profile failed', error);
+    // 立刻开始备下一张。必须在「打开」时做而不是「关闭」时 —— 真实环境渲染
+    // 一张要走鉴权、render、网关取数、图片加载，几秒起步；放在关闭时做的话，
+    // 用户点快一点下次打开就还没备好，又掉回完整 loading。
+    if (!hasSpare(targetLarkOpenID)) {
+      void ensureRender(`${targetLarkOpenID}:spare`, async () => {
+        const live = await renderCard(larkCardParam, null);
+        if (live) putSpare(targetLarkOpenID, live);
+        return live;
+      }).catch((error: unknown) => {
+        logger.info('prepare spare lark profile failed', error);
       });
-    };
+    }
   }, [
+    instanceId,
     larkCardParam,
     needRedirect,
     redirectURL,

package/template/client/src/components/business-ui/user-select/user-pill.tsx

@@ -16,6 +16,18 @@ import {
   PopoverTrigger,
 } from '@client/src/components/ui/popover';
 
+/**
+ * 阻止 Popover 打开时的自动聚焦。
+ *
+ * Radix 的 FocusScope 在弹层挂载时会把焦点给容器里第一个可聚焦元素。人员卡片
+ * 挂载那一刻内容就已经在了（飞书名片里有「消息」等按钮），于是一打开就有个
+ * 按钮带上焦点环。这是张只读预览卡，焦点应该留在触发器上 —— Radix 自己的
+ * HoverCard 也是这么处理的。
+ */
+const handleProfileOpenAutoFocus = (event: Event) => {
+  event.preventDefault();
+};
+
 export type UserPillProps = {
   /**
    * 用户 ID，用于 UserProfile 展示
@@ -117,6 +129,7 @@ export const UserPill: React.FC<UserPillProps> = ({
           side="bottom"
           align="start"
           sideOffset={8}
+          onOpenAutoFocus={handleProfileOpenAutoFocus}
           className="w-80 p-0"
         >
           <UserProfile userId={userId} accountType={accountType} />