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

package/package.json

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

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

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

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

@@ -13,18 +13,6 @@ import {
   PopoverTrigger,
 } from '@client/src/components/ui/popover';
 
-/**
- * 阻止 Popover 打开时的自动聚焦。
- *
- * Radix 的 FocusScope 在弹层挂载时会把焦点给容器里第一个可聚焦元素。人员卡片
- * 挂载那一刻内容就已经在了（飞书名片里有「消息」等按钮），于是一打开就有个
- * 按钮带上焦点环。这是张只读预览卡，焦点应该留在触发器上 —— Radix 自己的
- * HoverCard 也是这么处理的。
- */
-const handleProfileOpenAutoFocus = (event: Event) => {
-  event.preventDefault();
-};
-
 export interface IUserDisplayProps {
   /**
    * 用户列表
@@ -100,7 +88,6 @@ 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/user-profile.tsx

@@ -2,30 +2,14 @@
 
 import { logger } from '@lark-apaas/client-toolkit/logger';
 
-import React, {
-  useCallback,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import SHA1 from 'crypto-js/sha1';
 
-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';
+  fetchUserProfile,
+  getAssetsUrl,
+} from '@client/src/components/business-ui/api/user-profiles/service';
+import { ErrorImage } from '@client/src/components/business-ui/user-profile/error-image';
 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';
@@ -83,6 +67,8 @@ function generateRandomString(length: number): string {
   return result;
 }
 
+type BaseUserProfileProps = BaseSimpleProfileProps | BaseOfficialProfileProps;
+
 const ACCOUNT_STATUS = {
   UNSPECIFIED: 0,
   Inactive: 1,
@@ -104,31 +90,28 @@ const AccountStatusMap: Record<AccountStatus, string> = {
   [ACCOUNT_STATUS.Resigned]: '已停用',
 };
 
-interface SimpleProfileInfo {
-  readonly name?: string;
-  readonly avatar?: string;
-  readonly email?: string;
-  readonly userStatus: AccountStatus;
-  readonly userType: '_employee' | '_externalUser';
-}
-
-interface SimpleProfileData {
+interface BaseSimpleProfileProps {
   readonly useLarkCard: false;
-  readonly userProfileInfo: SimpleProfileInfo;
+  readonly userProfileInfo: {
+    readonly name?: string;
+    readonly avatar?: string;
+    readonly email?: string;
+    //
+    readonly userStatus: AccountStatus;
+    readonly userType: '_employee' | '_externalUser';
+  };
 }
 
-interface OfficialProfileData {
+interface BaseOfficialProfileProps {
   readonly useLarkCard: true;
-  readonly larkCardParam: LarkCardParam;
-}
-
-interface LarkCardParam {
-  readonly needRedirect?: boolean;
-  readonly redirectURL?: string;
-  readonly larkAppID: string;
-  readonly jsAPITicket: string;
-  readonly larkOpenID: string;
-  readonly targetLarkOpenID: string;
+  readonly larkCardParam: {
+    readonly needRedirect?: boolean;
+    readonly redirectURL?: string;
+    readonly larkAppID: string;
+    readonly jsAPITicket: string;
+    readonly larkOpenID: string;
+    readonly targetLarkOpenID: string;
+  };
 }
 
 /**
@@ -139,55 +122,15 @@ export interface WithCommonResponse<T> {
   data: T;
 }
 
-// 按需注入飞书 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;
-
+async function renderLarkProfile({
+  larkAppID,
+  jsAPITicket,
+  larkOpenID,
+  cardRef,
+  targetLarkOpenID,
+}: BaseOfficialProfileProps['larkCardParam'] & {
+  cardRef: React.RefObject<HTMLDivElement | null>;
+}) {
   const timestamp = Date.now().toString();
   const nonceStr = generateRandomString(10);
   const url = globalThis.location.href.split('#')[0] ?? '';
@@ -203,53 +146,20 @@ async function renderLarkProfile(
     url,
     jsApiList: ['user_profile'],
     locale: ['zh_cn'],
-    ...(getEnv() === 'BOE' ? { env: 'feishu_boe' } : {}),
+    ...(getEnv() === 'BOE'
+      ? { env: 'feishu_boe' }
+      : {}),
   });
 
-  await globalThis.webComponent.render(
+  const myComponent = await globalThis.webComponent.render(
     'UserProfile',
-    { openId: targetLarkOpenID },
-    host,
+    {
+      openId: targetLarkOpenID,
+    },
+    cardRef.current,
   );
 
-  // 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;
+  return myComponent;
 }
 
 function UserProfile(props: UserProfileProps) {
@@ -262,30 +172,96 @@ function UserProfile(props: UserProfileProps) {
     user_id ||
     originUserId;
 
-  const { data, isPending, isError, refetch } = useUserProfile({
-    userId: userId ?? '',
-    accountType,
-    enabled: Boolean(userId),
-  });
+  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);
+    });
+  }, []);
 
-  const handleRetry = useCallback(() => {
-    void refetch();
-  }, [refetch]);
+  // 按需注入飞书 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);
 
-  // 没有 userId 时不渲染任何东西。旧实现在这里会停在 loading 上永远转圈。
-  if (!userId) return null;
+  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]);
 
-  if (isError) {
+  useEffect(() => {
+    if (scriptStatus !== 'ready') return;
+
+    void fetchData();
+  }, [fetchData, scriptStatus]);
+
+  if (error) {
     return (
-      <Card className="flex min-h-124 w-80 flex-col items-center justify-center gap-4 border-0 p-0">
+      <Card
+        ref={cardRef}
+        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={handleRetry}
+            onClick={fetchData}
           >
             重试
           </Button>
@@ -293,269 +269,42 @@ 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 (
-    <LarkProfileCard
-      key={larkCardParam.targetLarkOpenID}
-      larkCardParam={larkCardParam}
-    />
+    <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>
   );
 }
 
-/**
- * 飞书名片分支。
- *
- * 人员数据由 `<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);
-
-  const scriptOptions = useMemo(
-    () => ({ onloadCallback: registerLarkAuthHandler }),
-    [],
-  );
-  const scriptStatus = useExternalScript(LARK_SDK_URL, scriptOptions);
-
-  // 卸载清理需要的值走 ref，避免为了它们把依赖写宽
-  const teardownRef = useRef({ param: larkCardParam, scriptReady: false });
-  teardownRef.current = {
-    param: larkCardParam,
-    scriptReady: scriptStatus === 'ready',
-  };
+function LoadingComponent() {
+  return <Spinner className="size-8 animate-spin text-primary" />;
+}
 
-  // 需要走鉴权重定向时整页跳转，不渲染名片
-  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);
-      });
-    };
-  }, []);
+function BaseUserProfile(props: BaseUserProfileProps) {
+  const { useLarkCard } = props;
+  if (!useLarkCard) {
+    const { userProfileInfo } = props as BaseSimpleProfileProps;
 
-  // 主逻辑。对重复执行幂等：已经挂了东西就不再顶备用卡，已经发起过的渲染
-  // 不重复发起。
-  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);
-    }
+    return <SimpleUserProfile userProfileInfo={userProfileInfo} />;
+  }
 
-    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);
-      });
+  const { larkCardParam } = props;
+  const { needRedirect, redirectURL } = larkCardParam;
+  if (needRedirect) {
+    if (!redirectURL) {
+      return null;
     }
-  }, [
-    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>
-  );
+    globalThis.location.replace(redirectURL);
+    return null;
+  }
 }
 
 function SimpleUserProfile(props: {
-  readonly userProfileInfo: SimpleProfileInfo;
+  readonly userProfileInfo: BaseSimpleProfileProps['userProfileInfo'];
 }) {
   const { userProfileInfo } = props;
 

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

@@ -16,18 +16,6 @@ import {
   PopoverTrigger,
 } from '@client/src/components/ui/popover';
 
-/**
- * 阻止 Popover 打开时的自动聚焦。
- *
- * Radix 的 FocusScope 在弹层挂载时会把焦点给容器里第一个可聚焦元素。人员卡片
- * 挂载那一刻内容就已经在了（飞书名片里有「消息」等按钮），于是一打开就有个
- * 按钮带上焦点环。这是张只读预览卡，焦点应该留在触发器上 —— Radix 自己的
- * HoverCard 也是这么处理的。
- */
-const handleProfileOpenAutoFocus = (event: Event) => {
-  event.preventDefault();
-};
-
 export type UserPillProps = {
   /**
    * 用户 ID，用于 UserProfile 展示
@@ -129,7 +117,6 @@ 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.67",
+        "@lark-apaas/fullstack-nestjs-core": "^1.1.69",
         "@nestjs/axios": "^4.0.1",
         "@nestjs/cache-manager": "^3.1.3",
         "@nestjs/common": "^10.4.20",
@@ -1110,9 +1110,9 @@
       "license": "MIT"
     },
     "node_modules/@grpc/grpc-js": {
-      "version": "1.14.4",
-      "resolved": "https://registry.npmmirror.com/@grpc/grpc-js/-/grpc-js-1.14.4.tgz",
-      "integrity": "sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==",
+      "version": "1.14.6",
+      "resolved": "https://registry.npmmirror.com/@grpc/grpc-js/-/grpc-js-1.14.6.tgz",
+      "integrity": "sha512-SgC/B3/VZ8lTyOZ4Cwk6f1skWhmkNAaVfiX90qd5u1rRXGKk1//8FTUEN9GvOUq7rfWIqAYkA3CoyumYVpOS6g==",
       "license": "Apache-2.0",
       "dependencies": {
         "@grpc/proto-loader": "^0.8.0",
@@ -1546,9 +1546,9 @@
       }
     },
     "node_modules/@lark-apaas/cache-service": {
-      "version": "0.1.2",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/cache-service/-/cache-service-0.1.2.tgz",
-      "integrity": "sha512-0n24sTo1QyH/8lHs8GUcM/E+zeDau2d5Wqga8QY0A/VbjxctCtmDc8SwN1Zl8mioLNalF3QotnBsNWnOHuOw/A==",
+      "version": "0.1.3",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/cache-service/-/cache-service-0.1.3.tgz",
+      "integrity": "sha512-PG6h0IixK6J1aMUOu8g5vR2Zgis7qq2TBv1XxA/tGvwcxaE23ytLCpQq7+cwcSLtXFji9O82iOaAkfoe4bpRWQ==",
       "license": "MIT",
       "dependencies": {
         "@keyv/redis": "^5.1.6",
@@ -1562,8 +1562,8 @@
       },
       "peerDependencies": {
         "@lark-apaas/nestjs-common": "^0.1.9",
-        "@lark-apaas/nestjs-logger": "^1.0.18",
-        "@lark-apaas/nestjs-observable": "^0.0.12",
+        "@lark-apaas/nestjs-logger": "^1.0.19",
+        "@lark-apaas/nestjs-observable": "^0.0.13",
         "@nestjs/common": "^10.0.0",
         "@nestjs/core": "^10.0.0"
       }
@@ -1697,23 +1697,23 @@
       }
     },
     "node_modules/@lark-apaas/fullstack-nestjs-core": {
-      "version": "1.1.67",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.67.tgz",
-      "integrity": "sha512-OD30GFcx1+7cqE0c7bkoQaj/zJTTiQ3rU131gjCzm9eKEedwepbsAzDhusNirMdPyKlkQ7IJVWXw2UL9hHFJVg==",
+      "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==",
       "license": "MIT",
       "dependencies": {
-        "@lark-apaas/cache-service": "^0.1.2",
+        "@lark-apaas/cache-service": "^0.1.3",
         "@lark-apaas/file-service": "^0.1.2",
-        "@lark-apaas/http-client": "^0.1.8",
+        "@lark-apaas/http-client": "^0.1.9",
         "@lark-apaas/nestjs-authnpaas": "^1.0.9",
         "@lark-apaas/nestjs-authzpaas": "^0.1.16",
         "@lark-apaas/nestjs-capability": "^0.1.14",
         "@lark-apaas/nestjs-common": "^0.1.9",
-        "@lark-apaas/nestjs-datapaas": "^1.0.21",
+        "@lark-apaas/nestjs-datapaas": "^1.0.23",
         "@lark-apaas/nestjs-http-forwarder": "^0.1.3",
-        "@lark-apaas/nestjs-logger": "^1.0.18",
+        "@lark-apaas/nestjs-logger": "^1.0.19",
         "@lark-apaas/nestjs-mcp": "^0.1.2",
-        "@lark-apaas/nestjs-observable": "^0.0.12",
+        "@lark-apaas/nestjs-observable": "^0.0.13",
         "@lark-apaas/nestjs-openapi-devtools": "^1.0.10",
         "@lark-apaas/nestjs-trigger": "^0.0.3",
         "@nestjs/axios": "^4.0.1",
@@ -1773,9 +1773,9 @@
       }
     },
     "node_modules/@lark-apaas/http-client": {
-      "version": "0.1.8",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/http-client/-/http-client-0.1.8.tgz",
-      "integrity": "sha512-A7TPW0sEz1CsFKTc/fDnwEpFfuDEmfkT/zBTu/7DIjQdhk4J46d9vyzmlRC8wqd1n1cdojjt5iMhUtzg3zvSHw==",
+      "version": "0.1.9",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/http-client/-/http-client-0.1.9.tgz",
+      "integrity": "sha512-mcxd4skrQgMu6AYuy2TFe9Vvx9OSjAi3quONYLSEFq+LXe1IHaGkveuM0XlXBPxku5/pM1ryfIFP6fRImveQ2A==",
       "license": "MIT",
       "engines": {
         "node": ">=18.0.0"
@@ -1887,9 +1887,9 @@
       }
     },
     "node_modules/@lark-apaas/nestjs-datapaas": {
-      "version": "1.0.22",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-datapaas/-/nestjs-datapaas-1.0.22.tgz",
-      "integrity": "sha512-UTdYnZGVpVTv5iB9HEiUJTyFmTvEX+QJd/qlJK2CsnyF2MS8YQhyWTSlJZ375DcBpxSngFBhkRfZXHNs1OFp0w==",
+      "version": "1.0.23",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-datapaas/-/nestjs-datapaas-1.0.23.tgz",
+      "integrity": "sha512-7xCye2jg5O0qiw+l6L4j9HfrN5dbBcUTlJ1LhniX4RHi9Ds7tZlhLhsO+nqZrWoK9GXDc0jdZ61E7EMwHduJ4w==",
       "license": "MIT",
       "dependencies": {
         "@types/pg": "^8.10.9",
@@ -1901,7 +1901,7 @@
       },
       "peerDependencies": {
         "@lark-apaas/nestjs-common": "^0.1.9",
-        "@lark-apaas/nestjs-observable": "^0.0.12",
+        "@lark-apaas/nestjs-observable": "^0.0.13",
         "@nestjs/common": "^10.0.0",
         "@nestjs/core": "^10.0.0",
         "drizzle-orm": "0.44.6"
@@ -1926,13 +1926,13 @@
       }
     },
     "node_modules/@lark-apaas/nestjs-logger": {
-      "version": "1.0.18",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-logger/-/nestjs-logger-1.0.18.tgz",
-      "integrity": "sha512-RjucJd+TmACoNfTFw20/ppAT3gaztm3qZagPDHEZabiZxg8UpF1twbmN/VLXTF/fgpyoRFS09CMxa7nfFnrT2A==",
+      "version": "1.0.19",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-logger/-/nestjs-logger-1.0.19.tgz",
+      "integrity": "sha512-AGuEd0NiUS1TEywHV8TeG+KBZ0QoMbVuCi6exjIzIsHoSsGiy5fImAt5LV1osAG/OHYrdDWy1zYGZBVhUNYAaw==",
       "license": "MIT",
       "dependencies": {
         "@lark-apaas/nestjs-common": "^0.1.9",
-        "@lark-apaas/nestjs-observable": "^0.0.12",
+        "@lark-apaas/nestjs-observable": "^0.0.13",
         "pino": "^10.0.0",
         "rotating-file-stream": "^3.2.9"
       },
@@ -1965,13 +1965,13 @@
       }
     },
     "node_modules/@lark-apaas/nestjs-observable": {
-      "version": "0.0.12",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-observable/-/nestjs-observable-0.0.12.tgz",
-      "integrity": "sha512-hAeP8llTThH//3yo4RQL6VhsX5D7L8DE8nWlt6xJf3VoxTwB5vZCOdI0em1vENmbROmxRMskphyS2H1wRpqcDw==",
+      "version": "0.0.13",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-observable/-/nestjs-observable-0.0.13.tgz",
+      "integrity": "sha512-HzrPsE1QdNRqk2PxArOazRJWkJCP5Y6IMnhrJWVCnQoPCyDewUpBAoU+15eqSgaXYOONrDiU3Dm9RfCdYt3w8A==",
       "license": "MIT",
       "dependencies": {
         "@lark-apaas/nestjs-common": "^0.1.9",
-        "@lark-apaas/observable": "^1.0.6"
+        "@lark-apaas/observable": "^1.0.7"
       },
       "peerDependencies": {
         "@nestjs/common": "^10.4.20",
@@ -2011,9 +2011,9 @@
       }
     },
     "node_modules/@lark-apaas/observable": {
-      "version": "1.0.6",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/observable/-/observable-1.0.6.tgz",
-      "integrity": "sha512-zMtTdWXEKjhpaC9M0mnv3uP68R+UAwNdctApmpzPhhOaNPjDGSYdvsQtMEMdr8/+tlETx+7OuXN47sYj2lmKAQ==",
+      "version": "1.0.7",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/observable/-/observable-1.0.7.tgz",
+      "integrity": "sha512-PcUdzLmDTQ7VcP3mcN1IijT68BSVkvGD300DVOhuzCX3d0kPihAtR0khTacRoaiwPlUQdFhhtctKB3KRhKx2+g==",
       "license": "MIT",
       "dependencies": {
         "@opentelemetry/api": "^1.9.0",
@@ -10999,9 +10999,9 @@
       }
     },
     "node_modules/cjs-module-lexer": {
-      "version": "2.2.1",
-      "resolved": "https://registry.npmmirror.com/cjs-module-lexer/-/cjs-module-lexer-2.2.1.tgz",
-      "integrity": "sha512-Ca8swihM+/4yKecYHY52kgJd300hi2lADU/a1RxNTRe+RJ9jvqQlESpbz9DnG9mowez8qwXHB8qYdIUw9e+F5Q==",
+      "version": "2.3.0",
+      "resolved": "https://registry.npmmirror.com/cjs-module-lexer/-/cjs-module-lexer-2.3.0.tgz",
+      "integrity": "sha512-lmNyBzi6iYiqyrExTctfmjd8tInx+dHu9PBomTfH5RXS53c27JMFJgzNv5TyAnm3PgGf+MLy0+Ws41/HlVxdKQ==",
       "license": "MIT"
     },
     "node_modules/class-transformer": {
@@ -18600,9 +18600,9 @@
       }
     },
     "node_modules/pino": {
-      "version": "10.3.1",
-      "resolved": "https://registry.npmmirror.com/pino/-/pino-10.3.1.tgz",
-      "integrity": "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg==",
+      "version": "10.4.0",
+      "resolved": "https://registry.npmmirror.com/pino/-/pino-10.4.0.tgz",
+      "integrity": "sha512-bk1ZMTwG/Vymx+zPoa28MhNzucFvXJWp3csrSuxuHPSMeUettaCoQ5Jvg07mtC4JGNpcfTwz41oVCnNgBK9+vA==",
       "license": "MIT",
       "dependencies": {
         "@pinojs/redact": "^0.4.0",
@@ -18612,7 +18612,7 @@
         "pino-std-serializers": "^7.0.0",
         "process-warning": "^5.0.0",
         "quick-format-unescaped": "^4.0.3",
-        "real-require": "^0.2.0",
+        "real-require": "^1.0.0",
         "safe-stable-stringify": "^2.3.1",
         "sonic-boom": "^4.0.1",
         "thread-stream": "^4.0.0"
@@ -18964,9 +18964,9 @@
       }
     },
     "node_modules/process-warning": {
-      "version": "5.1.0",
-      "resolved": "https://registry.npmmirror.com/process-warning/-/process-warning-5.1.0.tgz",
-      "integrity": "sha512-jQSaVHsPgtyw60e1rQ/A+/ArPEj/S8pS/vFnyGa/gYFXrKk/6RuDkoqVDQ5NI5MmS01698ltlAk0NoDBNLujRw==",
+      "version": "5.1.1",
+      "resolved": "https://registry.npmmirror.com/process-warning/-/process-warning-5.1.1.tgz",
+      "integrity": "sha512-oCkNVj4OKnKEcocVBcDfiIugN1/cE6rgfT3nCtzeqZPA8+rIxMaQ0xXzIkGP8Gj2qUaP1UR7uhJ1VD8lUCpzCg==",
       "funding": [
         {
           "type": "github",
@@ -19931,13 +19931,10 @@
       }
     },
     "node_modules/real-require": {
-      "version": "0.2.0",
-      "resolved": "https://registry.npmmirror.com/real-require/-/real-require-0.2.0.tgz",
-      "integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 12.13.0"
-      }
+      "version": "1.0.0",
+      "resolved": "https://registry.npmmirror.com/real-require/-/real-require-1.0.0.tgz",
+      "integrity": "sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g==",
+      "license": "MIT"
     },
     "node_modules/recharts": {
       "version": "2.15.4",
@@ -22014,12 +22011,6 @@
         "node": ">=20"
       }
     },
-    "node_modules/thread-stream/node_modules/real-require": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmmirror.com/real-require/-/real-require-1.0.0.tgz",
-      "integrity": "sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g==",
-      "license": "MIT"
-    },
     "node_modules/throttle-debounce": {
       "version": "5.0.2",
       "resolved": "https://registry.npmmirror.com/throttle-debounce/-/throttle-debounce-5.0.2.tgz",

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.67",
+    "@lark-apaas/fullstack-nestjs-core": "^1.1.69",
     "@nestjs/axios": "^4.0.1",
     "@nestjs/cache-manager": "^3.1.3",
     "@nestjs/common": "^10.4.20",

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

@@ -1,217 +0,0 @@
-/**
- * 飞书名片 `<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;
-}