@lark-apaas/coding-template-nestjs-react-fullstack 0.1.52 → 0.1.54

package/package.json

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

package/template/client/src/components/business-ui/api/user-profiles/queries.ts

@@ -10,7 +10,13 @@ export const userProfileQueries = {
     queryOptions({
       queryKey: [...userProfileQueries.all(), 'byId', accountType, userId],
       queryFn: ({ signal }) => fetchUserProfile(userId, accountType, signal),
-      staleTime: 1 * 60 * 1000,
+      // staleTime 0：每次打开都在后台取一次新的，和飞书名片那条路保持一致
+      // ——「打开渲染缓存、后台乐观更新」。缓存命中时 isPending 为 false，
+      // 卡片瞬间渲出不转圈；新数据回来后 React 只 patch 变化的字段，不闪不跳。
+      //
+      // 之前是 60s：那段窗口内连请求都不发，远端改了最多要等 60 秒才看得到。
+      staleTime: 0,
+      // gcTime 决定缓存能留多久 —— 它才是「秒出」的来源，不要跟着一起调小。
       gcTime: 5 * 60 * 1000,
       enabled: !!userId,
     }),

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

@@ -0,0 +1,217 @@
+/**
+ * 飞书名片 `<tt-profile>` 的 DOM 池。
+ *
+ * 为什么 DOM 能被复用：
+ * 飞书 h5-js-sdk 的 `tt-profile` 在 `customRender()` 里把 React 渲染进元素自身
+ * （`ReactDOM.render(..., this)`），但 `disconnectedCallback()` 卸载的是
+ * `this.shadowRoot` —— 两者不是同一个节点，`unmountComponentAtNode` 打空，
+ * 所以把元素从文档里摘下来并不会销毁它的内容。又因为基类的 `componentRender()`
+ * 被 `_hasMounted` 一次性闸门挡住，重新挂回文档也不会触发二次渲染。
+ * 净效果：摘下来存着、下次挂回去，内容原样还在，且不会重新发请求。
+ *
+ * ⚠️ 这依赖 SDK 当前实现（h5-js-sdk 1.2.21）。升级 SDK 后必须重新验证：
+ * 把一个已渲染的 `<tt-profile>` `remove()` 再 `appendChild()` 回去，
+ * 内容是否仍在、交互是否仍可用。失效时本模块应整体降级为「每次重建」。
+ */
+
+/** 池容量上限，超出按最近使用顺序淘汰 */
+/* 暂时放大到 20：观察同时备更多人时的内存与渲染开销，确认后再定最终值 */
+let maxEntries = 20;
+
+/**
+ * 调整缓存策略：需要同时备好更多人的卡片时调大 maxEntries。
+ *
+ * 没有 TTL —— 每次打开都会重新渲染一次做更新，备用卡只决定「打开瞬间
+ * 显示什么」，不决定数据新鲜度。
+ */
+export function configureCardPool(options: { maxEntries?: number }): void {
+  if (typeof options.maxEntries === 'number') maxEntries = options.maxEntries;
+}
+
+/** 飞书名片渲染完成的标志节点：姓名有文字即认为内容已就绪（骨架屏阶段为空） */
+const READY_SELECTOR = '.larkw-userprofile__profile__alias-or-username-text';
+
+/** 等待渲染完成的上限，超时按失败处理，不替换当前展示的卡片 */
+const READY_TIMEOUT_MS = 8 * 1000;
+
+/**
+ * 备用卡池：每个 openId 一张**已渲染好、但从未显示过**的活 `<tt-profile>`，
+ * 停在离屏容器里。
+ *
+ * 为什么不直接缓存用户看过的那张：活元素会被用户操作 —— 滚动、点进上级的
+ * 名片、点开个性签名编辑框。这些状态一半在 DOM（inline 样式，能读能写），
+ * 一半在飞书 React 的内部 state（外部读不到也写不回）。既然无法可靠地把它
+ * 恢复成初始态，就干脆不复用它，而是另外备一张从没被碰过的。
+ *
+ * 代价是一个开关周期要渲染两次：一次换上去做更新，一次补充下次的备用卡。
+ */
+const pool = new Map<string, Element>();
+
+/** 取走某人的备用卡（取走即消耗，调用方负责挂载）。没有则返回 null。 */
+export function takeSpare(openId: string): Element | null {
+  const spare = pool.get(openId);
+  if (!spare) return null;
+  pool.delete(openId);
+  return spare;
+}
+
+/**
+ * 停放一张备用卡。元素应当停留在离屏容器里，不要挂进可见区域 ——
+ * 一旦被用户看到就可能被操作，就不再是初始态了。
+ */
+export function putSpare(openId: string, live: Element): void {
+  pool.get(openId)?.remove();
+  pool.delete(openId);
+  pool.set(openId, live);
+
+  while (pool.size > maxEntries) {
+    const oldest = pool.keys().next().value;
+    if (oldest === undefined) break;
+    pool.get(oldest)?.remove();
+    pool.delete(oldest);
+  }
+}
+
+/** 某人是否已经备好卡（用于决定要不要补渲染） */
+export function hasSpare(openId: string): boolean {
+  return pool.has(openId);
+}
+
+/** 同一个人同时在途的渲染任务，用于去重 */
+const inflight = new Map<string, Promise<Element | null>>();
+
+/**
+ * 保证同一个人同时只有一次渲染在途：重复调用复用同一个 Promise。
+ *
+ * 这不是优化而是正确性要求 —— effect 会被重复执行（React dev 下的双调用、
+ * 依赖变化、popover 快速开关），没有这层去重就会创建出多个 `<tt-profile>`，
+ * 每个都往飞书发一次请求。
+ *
+ * key 由调用方给 —— 同一个人的「打开后更新」和「补充备用卡」是两件独立的
+ * 事，不能互相去重，所以用 `<openId>:update` / `<openId>:spare` 区分。
+ */
+export function ensureRender(
+  key: string,
+  create: () => Promise<Element | null>,
+): Promise<Element | null> {
+  const existing = inflight.get(key);
+  if (existing) return existing;
+
+  const task = create().finally(() => {
+    inflight.delete(key);
+  });
+
+  inflight.set(key, task);
+  return task;
+}
+
+/** 丢弃某人的备用卡（渲染出错或需要强制重建时） */
+export function dropSpare(openId: string): void {
+  pool.get(openId)?.remove();
+  pool.delete(openId);
+}
+
+/** 清空整个池。页面级登出 / 切租户时调用。 */
+export function clearCardPool(): void {
+  pool.forEach((el) => {
+    el.remove();
+  });
+  pool.clear();
+}
+
+/**
+ * 等待一个 `<tt-profile>` 从骨架屏变成真实内容。
+ * 超时返回 false —— 调用方据此放弃替换，继续展示旧卡片。
+ */
+export function waitForCardReady(
+  el: Element,
+  timeoutMs: number = READY_TIMEOUT_MS,
+): Promise<boolean> {
+  const isReady = () => {
+    const node = el.querySelector(READY_SELECTOR);
+    return Boolean(node?.textContent?.trim());
+  };
+
+  if (isReady()) return Promise.resolve(true);
+
+  return new Promise<boolean>((resolve) => {
+    const observer = new MutationObserver(() => {
+      if (!isReady()) return;
+      clearTimeout(timer);
+      observer.disconnect();
+      resolve(true);
+    });
+
+    const timer = setTimeout(() => {
+      observer.disconnect();
+      resolve(false);
+    }, timeoutMs);
+
+    observer.observe(el, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  });
+}
+
+/**
+ * 取「卡片里本人那一屏」的文字，用来判断本人的数据有没有被改动过。
+ *
+ * 不能直接用整张卡的 textContent —— 飞书名片是个卡片栈，用户点进上级的
+ * 名片时会往里压入第二屏，整张卡的文字就变了，但**本人的数据一个字没动**。
+ * 把那种情况误判成「数据变了」会白白丢弃备用卡，下次打开退回完整 loading。
+ *
+ * 栈里第一个 `.larkw-userprofile__manager__profile` 就是本人那一屏。
+ * 找不到这个结构时退回整张卡，宁可偶尔多丢一次缓存，也不要漏掉真实改动。
+ */
+export function ownProfileText(el: Element): string {
+  const own =
+    el.querySelector('.larkw-userprofile__manager__profile') ?? el;
+  return own.textContent?.trim() ?? '';
+}
+
+const OFFSCREEN_ID = 'lark-profile-offscreen';
+
+/**
+ * 离屏渲染容器：后台渲染的 `<tt-profile>` 先在这里成形，就绪后再挂到
+ * 可见位置，这样用户看不到骨架屏。
+ *
+ * 用绝对定位移出视口而不是 `display:none` —— 后者会让元素没有布局盒，
+ * 飞书名片内部依赖尺寸的逻辑可能不工作。
+ */
+/**
+ * 为「一次渲染」开一个专属的离屏插槽。
+ *
+ * SDK 的 render() 只是把元素 append 到给定容器，不返回它，我们只能从容器
+ * 里取。多次渲染共用一个容器时（命中备用卡后，「打开后更新」和「预备下一张」
+ * 是并发的；一页多张卡片时更多），谁 append 在前无法保证，按「最后一个子节点」
+ * 取会张冠李戴 —— 两次渲染可能拿到同一个元素，甚至取到别人的名片。
+ *
+ * 每次渲染独占一个插槽，容器里就只会有本次创建的那一个。
+ */
+export function createOffscreenSlot(): HTMLElement {
+  const slot = document.createElement('div');
+  getOffscreenHost().appendChild(slot);
+  return slot;
+}
+
+export function getOffscreenHost(): HTMLElement {
+  const existing = document.getElementById(OFFSCREEN_ID);
+  if (existing) return existing;
+
+  const host = document.createElement('div');
+  host.id = OFFSCREEN_ID;
+  host.setAttribute('aria-hidden', 'true');
+  host.style.cssText = [
+    'position:absolute',
+    'top:0',
+    'left:-10000px',
+    'width:320px',
+    'height:520px',
+    'overflow:hidden',
+    'pointer-events:none',
+  ].join(';');
+  document.body.appendChild(host);
+  return host;
+}

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

@@ -2,14 +2,30 @@
 
 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 {
-  fetchUserProfile,
-  getAssetsUrl,
-} from '@client/src/components/business-ui/api/user-profiles/service';
+import { getAssetsUrl } from '@client/src/components/business-ui/api/user-profiles/service';
+import { useUserProfile } from '@client/src/components/business-ui/api/user-profiles/queries';
 import { ErrorImage } from '@client/src/components/business-ui/user-profile/error-image';
+import {
+  dropSpare,
+  ownProfileText,
+  ensureRender,
+  createOffscreenSlot,
+  getOffscreenHost,
+  hasSpare,
+  putSpare,
+  takeSpare,
+  waitForCardReady,
+} from '@client/src/components/business-ui/user-profile/lark-card-pool';
 import { getEnv } from '@lark-apaas/client-toolkit/utils/getEnv';
 import { useExternalScript } from '@client/src/components/business-ui/user-profile/user-external-script';
 import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
@@ -67,8 +83,6 @@ function generateRandomString(length: number): string {
   return result;
 }
 
-type BaseUserProfileProps = BaseSimpleProfileProps | BaseOfficialProfileProps;
-
 const ACCOUNT_STATUS = {
   UNSPECIFIED: 0,
   Inactive: 1,
@@ -90,28 +104,31 @@ const AccountStatusMap: Record<AccountStatus, string> = {
   [ACCOUNT_STATUS.Resigned]: '已停用',
 };
 
-interface BaseSimpleProfileProps {
+interface SimpleProfileInfo {
+  readonly name?: string;
+  readonly avatar?: string;
+  readonly email?: string;
+  readonly userStatus: AccountStatus;
+  readonly userType: '_employee' | '_externalUser';
+}
+
+interface SimpleProfileData {
   readonly useLarkCard: false;
-  readonly userProfileInfo: {
-    readonly name?: string;
-    readonly avatar?: string;
-    readonly email?: string;
-    //
-    readonly userStatus: AccountStatus;
-    readonly userType: '_employee' | '_externalUser';
-  };
+  readonly userProfileInfo: SimpleProfileInfo;
 }
 
-interface BaseOfficialProfileProps {
+interface OfficialProfileData {
   readonly useLarkCard: true;
-  readonly larkCardParam: {
-    readonly needRedirect?: boolean;
-    readonly redirectURL?: string;
-    readonly larkAppID: string;
-    readonly jsAPITicket: string;
-    readonly larkOpenID: string;
-    readonly targetLarkOpenID: string;
-  };
+  readonly larkCardParam: LarkCardParam;
+}
+
+interface LarkCardParam {
+  readonly needRedirect?: boolean;
+  readonly redirectURL?: string;
+  readonly larkAppID: string;
+  readonly jsAPITicket: string;
+  readonly larkOpenID: string;
+  readonly targetLarkOpenID: string;
 }
 
 /**
@@ -122,15 +139,55 @@ export interface WithCommonResponse<T> {
   data: T;
 }
 
-async function renderLarkProfile({
-  larkAppID,
-  jsAPITicket,
-  larkOpenID,
-  cardRef,
-  targetLarkOpenID,
-}: BaseOfficialProfileProps['larkCardParam'] & {
-  cardRef: React.RefObject<HTMLDivElement | null>;
-}) {
+// 按需注入飞书 H5 JS SDK，仅在走飞书名片分支时才加载
+const LARK_SDK_URL =
+  'https://lf3-cdn-tos.bytegoofy.com/obj/goofy/locl/lark/external_js_sdk/h5-js-sdk-1.2.21.js';
+
+/**
+ * 鉴权重定向地址放在模块级而不是组件 ref 里。
+ * 原因：useExternalScript 在「脚本已存在」时会跳过 onloadCallback，
+ * 所以 onAuthError 只会在页面首个实例挂载时注册一次。若闭包捕获的是
+ * 某个实例的 ref，该实例卸载后，后续实例的 redirectURL 就永远送不到
+ * 已注册的 handler 里。用模块级变量保证读到的始终是最新值。
+ */
+let currentRedirectURL = '';
+let authHandlerRegistered = false;
+
+function registerLarkAuthHandler(): void {
+  if (authHandlerRegistered) return;
+  if (typeof globalThis.webComponent === 'undefined') return;
+  authHandlerRegistered = true;
+
+  globalThis.webComponent.onAuthError(function (error: Error) {
+    let errorMessage: { msg?: { code?: number; msg?: string } } | undefined;
+    try {
+      errorMessage = JSON.parse(error.message);
+    } catch {
+      logger.info('webComponent onAuthError: 非 JSON 错误体', error);
+      return;
+    }
+    // 存在token过期情况，但后端无法识别，需要前端这边主动识别error，并进行鉴权重定向
+    if (
+      errorMessage?.msg?.code === 20442 &&
+      errorMessage?.msg?.msg === 'jsapi-ticket not exist' &&
+      currentRedirectURL
+    ) {
+      globalThis.location.replace(currentRedirectURL);
+    }
+  });
+
+  globalThis.webComponent.onError(function (error: Error) {
+    logger.info('webComponent onError', error);
+  });
+}
+
+/** 在指定容器里创建并渲染一个飞书名片，返回创建出来的 `<tt-profile>` 元素 */
+async function renderLarkProfile(
+  param: LarkCardParam,
+  host: HTMLElement,
+): Promise<Element | null> {
+  const { larkAppID, jsAPITicket, larkOpenID, targetLarkOpenID } = param;
+
   const timestamp = Date.now().toString();
   const nonceStr = generateRandomString(10);
   const url = globalThis.location.href.split('#')[0] ?? '';
@@ -146,20 +203,53 @@ async function renderLarkProfile({
     url,
     jsApiList: ['user_profile'],
     locale: ['zh_cn'],
-    ...(getEnv() === 'BOE'
-      ? { env: 'feishu_boe' }
-      : {}),
+    ...(getEnv() === 'BOE' ? { env: 'feishu_boe' } : {}),
   });
 
-  const myComponent = await globalThis.webComponent.render(
+  await globalThis.webComponent.render(
     'UserProfile',
-    {
-      openId: targetLarkOpenID,
-    },
-    cardRef.current,
+    { openId: targetLarkOpenID },
+    host,
   );
 
-  return myComponent;
+  // SDK 把 <tt-profile> append 到 host 上，取最后一个即本次创建的
+  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) {
@@ -172,96 +262,30 @@ function UserProfile(props: UserProfileProps) {
     user_id ||
     originUserId;
 
-  const cardRef = useRef<HTMLDivElement>(null);
-  const [loading, setLoading] = useState<boolean>(true);
-  const redirectURLRef = useRef<string>('');
-  const [response, setResponse] = useState<BaseUserProfileProps>(
-    {} as BaseUserProfileProps,
-  );
-  const [error, setError] = useState<boolean>(false);
-
-  const onAuthError = useCallback(() => {
-    globalThis.webComponent.onAuthError(function (error: Error) {
-      const errorMessage = JSON.parse(error.message);
-      // 存在token过期情况，但后端无法识别，需要前端这边主动识别error，并进行鉴权重定向
-      if (
-        errorMessage?.msg?.code === 20442 &&
-        errorMessage?.msg?.msg === 'jsapi-ticket not exist'
-      ) {
-        globalThis.location.replace(redirectURLRef.current);
-      }
-    });
-
-    globalThis.webComponent.onError(function (error: Error) {
-      logger.info('webComponent onError', error);
-    });
-  }, []);
-
-  // 按需注入飞书 H5 JS SDK，仅在组件使用时加载
-  const larkSdkURl =
-    'https://lf3-cdn-tos.bytegoofy.com/obj/goofy/locl/lark/external_js_sdk/h5-js-sdk-1.2.21.js';
-  const scriptOptions = useMemo(
-    () => ({ onloadCallback: onAuthError }),
-    [onAuthError],
-  );
-  const scriptStatus = useExternalScript(larkSdkURl, scriptOptions);
-
-  const fetchData = useCallback(async () => {
-    if (!userId) return;
-
-    const controller = new AbortController();
-
-    setLoading(true);
-    setError(false);
-
-    try {
-      const data = await fetchUserProfile(userId, accountType, controller.signal);
-      setResponse(data as BaseUserProfileProps);
-
-      if (data.useLarkCard && !data.larkCardParam.needRedirect) {
-        redirectURLRef.current = data.larkCardParam.redirectURL ?? '';
-        await renderLarkProfile({
-          ...data.larkCardParam,
-          cardRef,
-        });
-        setLoading(false);
-      } else {
-        setLoading(false);
-      }
-    } catch (error: unknown) {
-      if (error instanceof Error && error.name === 'AbortError') {
-        // 直接退出，不处理 AbortError
-      } else {
-        // 最终的UI反馈
-        setError(true);
-        setLoading(false);
-      }
-    }
-  }, [userId, accountType]);
+  const { data, isPending, isError, refetch } = useUserProfile({
+    userId: userId ?? '',
+    accountType,
+    enabled: Boolean(userId),
+  });
 
-  useEffect(() => {
-    if (scriptStatus !== 'ready') return;
+  const handleRetry = useCallback(() => {
+    void refetch();
+  }, [refetch]);
 
-    void fetchData();
-  }, [fetchData, scriptStatus]);
+  // 没有 userId 时不渲染任何东西。旧实现在这里会停在 loading 上永远转圈。
+  if (!userId) return null;
 
-  if (error) {
+  if (isError) {
     return (
-      <Card
-        ref={cardRef}
-        className="flex min-h-124 w-80 flex-col items-center justify-center gap-4 border-0 p-0"
-      >
+      <Card className="flex min-h-124 w-80 flex-col items-center justify-center gap-4 border-0 p-0">
         <ErrorImage />
-        {/* <Button variant="outline" className="border-red-500 text-black hover:bg-red-50" onClick={fetchData}>
-        加载失败 请重试
-      </Button> */}
         <div>
           <span className="text-sm">加载失败 请</span>
           <Button
             size="sm"
             variant="ghost"
             className="pr-1 pl-1 text-primary! not-disabled:hover:bg-primary/10 not-disabled:hover:text-primary/90 focus-visible:bg-primary/20"
-            onClick={fetchData}
+            onClick={handleRetry}
           >
             重试
           </Button>
@@ -269,42 +293,269 @@ function UserProfile(props: UserProfileProps) {
       </Card>
     );
   }
+
+  // isPending 只在「无缓存且首次请求中」为真。
+  // 命中缓存时直接跳过 loading，卡片零延迟出现，后台静默 revalidate。
+  if (isPending || !data) {
+    return (
+      <Card className="flex h-130 w-80 flex-col items-center justify-center gap-6 border-0 p-0">
+        <Spinner className="size-8 animate-spin text-primary" />
+      </Card>
+    );
+  }
+
+  // 业务仓的 tsconfig 继承自 fullstack-presets，是 strictNullChecks: false。
+  // TS 在该模式下不做判别联合窄化（本地现写的同形状联合一样窄化失败），
+  // 所以这里必须显式断言分支类型，不能简化成 data.userProfileInfo。
+  if (!data.useLarkCard) {
+    const { userProfileInfo } = data as SimpleProfileData;
+    return <SimpleUserProfile userProfileInfo={userProfileInfo} />;
+  }
+
+  const { larkCardParam } = data as OfficialProfileData;
+  // key 绑 openId：切换到另一个人时整个重挂，备用卡引用、文字基线、loading
+  // 状态一并重置。否则 spareRef 的 `??=` 会把上一个人的卡片留下来复用。
   return (
-    <Card
-      ref={cardRef}
-      className="flex h-130 w-80 flex-col items-center justify-center gap-6 border-0 p-0"
-    >
-      {loading ? <LoadingComponent /> : <BaseUserProfile {...response} />}
-    </Card>
+    <LarkProfileCard
+      key={larkCardParam.targetLarkOpenID}
+      larkCardParam={larkCardParam}
+    />
   );
 }
 
-function LoadingComponent() {
-  return <Spinner className="size-8 animate-spin text-primary" />;
-}
+/**
+ * 飞书名片分支。
+ *
+ * 人员数据由 `<tt-profile>` 自己拉取，不经过我们的 state，因此这里无法做
+ * 字段级的 stale-while-revalidate。退而求其次：缓存整个已渲染的 DOM，
+ * 命中即刻展示；内容陈旧时在离屏容器里渲染一份新的，就绪后整体替换，
+ * 这样换新过程中用户看到的始终是旧卡片，不会出现骨架屏。
+ */
+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(targetLarkOpenID),
+  );
+  const [renderFailed, setRenderFailed] = useState(false);
+  const [retryToken, setRetryToken] = useState(0);
+
+  // 这次挂载取到的备用卡。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);
 
-function BaseUserProfile(props: BaseUserProfileProps) {
-  const { useLarkCard } = props;
-  if (!useLarkCard) {
-    const { userProfileInfo } = props as BaseSimpleProfileProps;
+  const scriptOptions = useMemo(
+    () => ({ onloadCallback: registerLarkAuthHandler }),
+    [],
+  );
+  const scriptStatus = useExternalScript(LARK_SDK_URL, scriptOptions);
 
-    return <SimpleUserProfile userProfileInfo={userProfileInfo} />;
-  }
+  // 卸载清理需要的值走 ref，避免为了它们把依赖写宽
+  const teardownRef = useRef({ param: larkCardParam, scriptReady: false });
+  teardownRef.current = {
+    param: larkCardParam,
+    scriptReady: scriptStatus === 'ready',
+  };
 
-  const { larkCardParam } = props;
-  const { needRedirect, redirectURL } = larkCardParam;
-  if (needRedirect) {
-    if (!redirectURL) {
-      return null;
+  // 需要走鉴权重定向时整页跳转，不渲染名片
+  useEffect(() => {
+    if (needRedirect && redirectURL) {
+      globalThis.location.replace(redirectURL);
     }
+  }, [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);
+      });
+    };
+  }, []);
 
-    globalThis.location.replace(redirectURL);
-    return null;
-  }
+  // 主逻辑。对重复执行幂等：已经挂了东西就不再顶备用卡，已经发起过的渲染
+  // 不重复发起。
+  useEffect(() => {
+    if (needRedirect) return;
+
+    const host = hostRef.current;
+    if (!host) return;
+
+    currentRedirectURL = redirectURL ?? '';
+    // 脚本已存在时 useExternalScript 会跳过 onloadCallback，这里补注册一次
+    if (scriptStatus === 'ready') registerLarkAuthHandler();
+
+    const attach = (el: Element | null) => {
+      if (!aliveRef.current || !el) return;
+      host.replaceChildren(el);
+      shownRef.current = el;
+      attachedTextRef.current = ownProfileText(el);
+      setShowSpinner(false);
+      setRenderFailed(false);
+    };
+
+    if (!shownRef.current) {
+      // 备用卡是渲染好后一直停在离屏、从没显示过的，所以必然是初始态，
+      // 而且是活元素 —— 挂上即可交互，不是静态快照
+      spareRef.current ??= takeSpare(targetLarkOpenID);
+      if (spareRef.current) attach(spareRef.current);
+    }
+
+    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);
+          setRenderFailed(true);
+        }
+      })
+      .catch((error: unknown) => {
+        logger.info('update lark profile failed', error);
+        if (!aliveRef.current) return;
+        setShowSpinner(false);
+        if (!shownRef.current) setRenderFailed(true);
+      });
+
+    // 立刻开始备下一张。必须在「打开」时做而不是「关闭」时 —— 真实环境渲染
+    // 一张要走鉴权、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,
+    retryToken,
+    scriptStatus,
+    targetLarkOpenID,
+  ]);
+
+  const handleRetryRender = useCallback(() => {
+    setRenderFailed(false);
+    setShowSpinner(true);
+    setRetryToken((n) => n + 1);
+  }, []);
+
+  if (needRedirect) return null;
+
+  return (
+    <Card className="relative flex h-130 w-80 flex-col items-center justify-center gap-6 border-0 p-0">
+      <div ref={hostRef} className="h-full w-full" />
+      {showSpinner && (
+        <Spinner className="absolute size-8 animate-spin text-primary" />
+      )}
+      {renderFailed && (
+        <div className="absolute flex flex-col items-center gap-4">
+          <ErrorImage />
+          <div>
+            <span className="text-sm">加载失败 请</span>
+            <Button
+              size="sm"
+              variant="ghost"
+              className="pr-1 pl-1 text-primary! not-disabled:hover:bg-primary/10 not-disabled:hover:text-primary/90 focus-visible:bg-primary/20"
+              onClick={handleRetryRender}
+            >
+              重试
+            </Button>
+          </div>
+        </div>
+      )}
+    </Card>
+  );
 }
 
 function SimpleUserProfile(props: {
-  readonly userProfileInfo: BaseSimpleProfileProps['userProfileInfo'];
+  readonly userProfileInfo: SimpleProfileInfo;
 }) {
   const { userProfileInfo } = props;
 

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

package/template/package-lock.json

@@ -8,7 +8,7 @@
       "name": "fullstack-nestjs-template",
       "version": "2.3.0",
       "dependencies": {
-        "@lark-apaas/fullstack-nestjs-core": "^1.1.69",
+        "@lark-apaas/fullstack-nestjs-core": "^1.1.70",
         "@nestjs/axios": "^4.0.1",
         "@nestjs/cache-manager": "^3.1.3",
         "@nestjs/common": "^10.4.20",
@@ -32,7 +32,7 @@
       },
       "devDependencies": {
         "@hookform/resolvers": "^5.2.2",
-        "@lark-apaas/client-toolkit": "^1.2.75",
+        "@lark-apaas/client-toolkit": "^1.2.76",
         "@lark-apaas/coding-preset-vite-react": "^1.0.26",
         "@lark-apaas/fullstack-presets": "^1.1.25",
         "@nestjs/cli": "^10.4.9",
@@ -1579,9 +1579,9 @@
       }
     },
     "node_modules/@lark-apaas/client-toolkit": {
-      "version": "1.2.75",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/client-toolkit/-/client-toolkit-1.2.75.tgz",
-      "integrity": "sha512-whvXDWN+EQp8y89jqMVoSgyVHt5ZfDHhjbCd9/vm7CqJwQsNacAYaHMmjxKINqNRGPQ2mEdKeFK6K00+D125cw==",
+      "version": "1.2.76",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/client-toolkit/-/client-toolkit-1.2.76.tgz",
+      "integrity": "sha512-fLy76Om47vuxUjQvME7GzAOeXycfozi1SqG6HqfgZErUqjBdCmEAkZfD50S39Zhp2FMpeCpkt+Of93S12+gbDQ==",
       "dev": true,
       "dependencies": {
         "@ant-design/colors": "^7.2.1",
@@ -1589,7 +1589,7 @@
         "@lark-apaas/aily-web-sdk": "^0.0.12",
         "@lark-apaas/auth-sdk": "^0.1.5",
         "@lark-apaas/client-capability": "^0.1.7",
-        "@lark-apaas/dataloom": "^0.1.5",
+        "@lark-apaas/dataloom": "^0.1.6",
         "@lark-apaas/internal-slardar": "^0.0.3",
         "@lark-apaas/miaoda-inspector": "^1.0.25",
         "@lark-apaas/observable-web": "^1.0.6",
@@ -1679,9 +1679,9 @@
       }
     },
     "node_modules/@lark-apaas/dataloom": {
-      "version": "0.1.5",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/dataloom/-/dataloom-0.1.5.tgz",
-      "integrity": "sha512-pcVZeO7QtxjzcV1SXQtUSPHO88/f1rhc3Dp/ubXVHV92W+T65Z9Adlyh3f+OdGGMhhn2+hIUnYLsLyS9gS1vhA==",
+      "version": "0.1.6",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/dataloom/-/dataloom-0.1.6.tgz",
+      "integrity": "sha512-NaMLYODTYlp4ziH1memTuEnARQhlbwMBm+MaWYT2Ue/3nf729i13hjkvxdmMTJq2qyWAnAhgEZvJ4Sccy+rmEQ==",
       "dev": true,
       "dependencies": {
         "@lark-apaas/internal-slardar": "^0.0.3"
@@ -1697,9 +1697,9 @@
       }
     },
     "node_modules/@lark-apaas/fullstack-nestjs-core": {
-      "version": "1.1.69",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.69.tgz",
-      "integrity": "sha512-SBSBDVy0lSXdgVyTEMUnkLPig0jhdDEM8f0dU8KsI3r293dW579ZRNFtb7azkwY/ouo7TyKhVFFHn2DpOB2Yrg==",
+      "version": "1.1.70",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.70.tgz",
+      "integrity": "sha512-W3aHeHB8XH3DUmoSGHUEyJz5U+zGdXWDCK7ewNp/FSeUE0iZDF3A7lUYIgr4AEIbQsRj1CVfkbblqo1kxXrFlg==",
       "license": "MIT",
       "dependencies": {
         "@lark-apaas/cache-service": "^0.1.3",
@@ -1710,7 +1710,7 @@
         "@lark-apaas/nestjs-capability": "^0.1.14",
         "@lark-apaas/nestjs-common": "^0.1.9",
         "@lark-apaas/nestjs-datapaas": "^1.0.23",
-        "@lark-apaas/nestjs-http-forwarder": "^0.1.3",
+        "@lark-apaas/nestjs-http-forwarder": "^0.1.4",
         "@lark-apaas/nestjs-logger": "^1.0.19",
         "@lark-apaas/nestjs-mcp": "^0.1.2",
         "@lark-apaas/nestjs-observable": "^0.0.13",
@@ -1908,9 +1908,9 @@
       }
     },
     "node_modules/@lark-apaas/nestjs-http-forwarder": {
-      "version": "0.1.3",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-http-forwarder/-/nestjs-http-forwarder-0.1.3.tgz",
-      "integrity": "sha512-mhgTN0M1B0DdalZ5iJkccivqfvXA2CX1487YmbT27ywqXi36ZCMLhl6jm4OaqSzKXf5lacrpadOjkW0v/6N0ag==",
+      "version": "0.1.4",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-http-forwarder/-/nestjs-http-forwarder-0.1.4.tgz",
+      "integrity": "sha512-AOWaeHrZvXRsK/F+2KkEPDJYbNjeuFc2OqhWEWm7u+KSuDE2iQ0dgNm1fTCvf9tkqrLNWEczqDhsP+CNmKndEQ==",
       "license": "MIT",
       "dependencies": {
         "@lark-apaas/nestjs-common": "^0.1.9",
@@ -22463,9 +22463,9 @@
       }
     },
     "node_modules/undici": {
-      "version": "7.29.0",
-      "resolved": "https://registry.npmmirror.com/undici/-/undici-7.29.0.tgz",
-      "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==",
+      "version": "7.30.1",
+      "resolved": "https://registry.npmmirror.com/undici/-/undici-7.30.1.tgz",
+      "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==",
       "license": "MIT",
       "engines": {
         "node": ">=20.18.1"

package/template/package.json

@@ -28,7 +28,7 @@
     "upgrade": "npx -y @lark-apaas/fullstack-cli sync --disable-gen-openapi"
   },
   "dependencies": {
-    "@lark-apaas/fullstack-nestjs-core": "^1.1.69",
+    "@lark-apaas/fullstack-nestjs-core": "^1.1.70",
     "@nestjs/axios": "^4.0.1",
     "@nestjs/cache-manager": "^3.1.3",
     "@nestjs/common": "^10.4.20",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@hookform/resolvers": "^5.2.2",
-    "@lark-apaas/client-toolkit": "^1.2.75",
+    "@lark-apaas/client-toolkit": "^1.2.76",
     "@lark-apaas/coding-preset-vite-react": "^1.0.26",
     "@lark-apaas/fullstack-presets": "^1.1.25",
     "@nestjs/cli": "^10.4.9",