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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-nestjs-react-fullstack",
-  "version": "0.1.51",
+  "version": "0.1.52-alpha.20261027082821",
   "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-profile/lark-card-pool.ts

@@ -0,0 +1,216 @@
+/**
+ * 飞书名片 `<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()` 回去，
+ * 内容是否仍在、交互是否仍可用。失效时本模块应整体降级为「每次重建」。
+ */
+
+/** 池容量上限，超出按最近使用顺序淘汰 */
+let maxEntries = 5;
+
+/**
+ * 调整缓存策略：需要同时备好更多人的卡片时调大 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

@@ -5,11 +5,20 @@ import { logger } from '@lark-apaas/client-toolkit/logger';
 import React, { useCallback, useEffect, 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 +76,6 @@ function generateRandomString(length: number): string {
   return result;
 }
 
-type BaseUserProfileProps = BaseSimpleProfileProps | BaseOfficialProfileProps;
-
 const ACCOUNT_STATUS = {
   UNSPECIFIED: 0,
   Inactive: 1,
@@ -90,28 +97,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 +132,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 +196,17 @@ 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;
 }
 
 function UserProfile(props: UserProfileProps) {
@@ -172,96 +219,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 +250,276 @@ 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;
 
-function BaseUserProfile(props: BaseUserProfileProps) {
-  const { useLarkCard } = props;
-  if (!useLarkCard) {
-    const { userProfileInfo } = props as BaseSimpleProfileProps;
+  const hostRef = useRef<HTMLDivElement>(null);
+  // 初值在渲染期就定下来：有备用卡就不该出现转圈。effect 在首次绘制之后
+  // 才跑，若初值恒为 true，命中缓存也会先闪一帧 loading。
+  const [showSpinner, setShowSpinner] = useState(() =>
+    !hasSpare(larkCardParam.targetLarkOpenID),
+  );
 
-    return <SimpleUserProfile userProfileInfo={userProfileInfo} />;
-  }
+  // 这次挂载取到的备用卡。effect 可能在一次打开中跑多次（依赖变化、
+  // React 开发期双调用），而 takeSpare 是「取走」语义 —— 不记在 ref 里的话，
+  // 第二次就拿不到，会误判成没有缓存而走完整 loading。
+  const spareRef = useRef<Element | null>(null);
 
-  const { larkCardParam } = props;
-  const { needRedirect, redirectURL } = larkCardParam;
-  if (needRedirect) {
-    if (!redirectURL) {
-      return null;
+  // 渲染失败（含就绪超时）。只在「屏幕上还什么都没有」时才需要告诉用户，
+  // 已经挂着备用卡的话保持现状即可。
+  const [renderFailed, setRenderFailed] = useState(false);
+  const [retryToken, setRetryToken] = useState(0);
+
+  // 挂上卡片那一刻、**本人那一屏**的文字。关闭时拿它和当前值比，就知道用户
+  // 有没有改过本人的数据（最典型的是编辑自己的个性签名）。只看本人那一屏，
+  // 是为了不把「点进上级的名片」这种纯导航误判成数据变化。
+  //
+  // 这是「同一个元素的前后两个时刻」比对，不是比两张独立渲染的卡 —— 后者
+  // 会被 CDN 分片轮换、图片懒加载时序等噪声污染，前者不会。
+  const attachedTextRef = useRef<string>('');
+
+  const scriptOptions = useMemo(
+    () => ({ onloadCallback: registerLarkAuthHandler }),
+    [],
+  );
+  const scriptStatus = useExternalScript(LARK_SDK_URL, scriptOptions);
+
+  // 需要走鉴权重定向时整页跳转，不渲染名片
+  useEffect(() => {
+    if (needRedirect && redirectURL) {
+      globalThis.location.replace(redirectURL);
     }
+  }, [needRedirect, redirectURL]);
 
-    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();
+
+    let cancelled = false;
+
+    /**
+     * 把元素挂到当前容器，并移除容器里原有的那张。
+     * 用 replaceChildren 而不是 appendChild —— 后台换新时新旧两张都存在，
+     * 必须显式只留一张，不能依赖 putCard 内部清理旧元素的顺序。
+     * effect 已失效则什么都不做，元素留在池里等下次打开。
+     */
+    const attach = (el: Element | null) => {
+      if (cancelled || !el) return;
+      host.replaceChildren(el);
+      attachedTextRef.current = ownProfileText(el);
+      setShowSpinner(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 (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;
+          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;
+
+      // 用过的那张直接丢弃 —— 它可能被滚动过、点进过别人的名片，
+      // 而这些状态有一半在飞书 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);
+      });
+    };
+  }, [
+    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/hooks/use-example.ts

@@ -1,52 +1,43 @@
-// import { useState, useEffect } from 'react';
+// /* 模板代码 仅作示例 */
+// import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+// import { toast } from 'sonner';
 // import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBackend';
-// import { logger } from '@lark-apaas/client-toolkit/logger';
+// import { getApiErrorMessage } from '@/lib/api-error';
+
+// // 接口的请求 / 响应类型先写在 shared/api.interface.ts，再从 @shared/api.interface 导入
+// interface RecordItem {
+//   id: string;
+//   title?: string;
+//   type?: string;
+//   creator?: string;
+//   speakDate?: string;
+// }
 
-// interface RecordData {
-//   title?: string,
-//   type?: string,
-//   creator?: string,
-//   speakDate?: string,
-// record: any;
-// loading: boolean;
-// error?: string;
+// interface RecordListParams {
+//   limit?: number;
+//   type?: string; // 筛选选「全部」时不传
 // }
 
-// export function useRecordData() {
-//   const [data, setData] = useState<RecordData>({
-//     record: {},
-//     loading: true,
-//     error: null,
+// // 读：useQuery，状态用返回的 isLoading / isError / error，不手写 loading/error state
+// export function useRecordList(params: RecordListParams) {
+//   return useQuery({
+//     queryKey: ['records', params],
+//     queryFn: () =>
+//       axiosForBackend
+//         .get<RecordItem[]>('/api/hello/test', { params })
+//         .then((r) => r.data),
 //   });
+// }
 
-//   useEffect(() => {
-//     fetchRecordData();
-//   }, []);
-
-//   const fetchRecordData = async () => {
-//     try {
-//       setData(prev => ({ ...prev, loading: true, error: null }));
-
-//       // 使用axios实例获取数据
-//       const response = await axiosForBackend.get('/api/hello');
-
-//       // 提取响应数据中的 data 字段
-//       const record = response.data.data;
-
-//       setData({
-//         record,
-//         loading: false,
-//         error: null,
-//       });
-//     } catch (error) {
-//       logger.error('获取数据失败', error);
-//       setData(prev => ({
-//         ...prev,
-//         loading: false,
-//         error: '获取数据失败，请稍后重试',
-//       }));
-//     }
-//   };
-
-//   return { ...data, refetch: fetchRecordData };
+// // 写：useMutation 必须 retry: false（避免重复提交），成功后刷新相关查询
+// // method 和 path 必须与后端 controller 一致（此处假设后端有 POST /api/hello）
+// export function useCreateRecord() {
+//   const queryClient = useQueryClient();
+//   return useMutation({
+//     mutationFn: (body: Omit<RecordItem, 'id'>) =>
+//       axiosForBackend.post<RecordItem>('/api/hello', body).then((r) => r.data),
+//     retry: false,
+//     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['records'] }),
+//     onError: (error) => toast.error(getApiErrorMessage(error, '保存失败，请稍后重试')),
+//   });
 // }

package/template/client/src/lib/api-error.ts

@@ -0,0 +1,36 @@
+/**
+ * 从接口错误中取出给用户看的文案（catch、toast.error、页面错误态统一用它）。
+ *
+ * 后端异常结构：{ error: { code, message, fieldErrors?: { 字段: ['错误'] } } }，顶层没有 message。
+ * 读取顺序：error.response.data.error.message → 第一条 fieldErrors 文案 → 调用方兜底文案。
+ * 不读 axios 的 error.message（它是 "Request failed with status code 400" 这类英文）。
+ */
+interface ApiErrorBody {
+  error?: {
+    code?: string;
+    message?: string;
+    fieldErrors?: Record<string, string[] | undefined>;
+  };
+}
+
+export function getApiErrorMessage(
+  error: unknown,
+  fallback = '操作失败，请稍后重试',
+): string {
+  if (typeof error !== 'object' || error === null) return fallback;
+  const body = (error as { response?: { data?: ApiErrorBody } }).response?.data;
+  const detail = body?.error;
+
+  if (typeof detail?.message === 'string' && detail.message.trim()) {
+    return detail.message;
+  }
+
+  for (const messages of Object.values(detail?.fieldErrors ?? {})) {
+    const first = Array.isArray(messages)
+      ? messages.find((m) => typeof m === 'string' && m.trim())
+      : undefined;
+    if (first) return first;
+  }
+
+  return fallback;
+}

package/template/client/src/pages/ExamplePage/ExamplePage.tsx

@@ -3,13 +3,14 @@
 // import { Button } from '@/components/ui/button';
 // import { RefreshCw, TrendingUp, PieChart, Clock } from 'lucide-react';
 // import { Link } from 'react-router-dom';
-// import { useRecordData } from '@/hooks/use-example';
+// import { useRecordList } from '@/hooks/use-example';
+// import { getApiErrorMessage } from '@/lib/api-error';
 
 // export default function ExamplePage() {
-//   const { record, loading, error, refetch } = useRecordData();
+//   const { data: records, isLoading, isError, error, refetch } = useRecordList({ limit: 5 });
 //   const [dimension, setDimension] = useState<'month' | 'quarter' | 'year'>('month');
 
-//   if (loading) {
+//   if (isLoading) {
 //     return (
 //       <div className="flex items-center justify-center h-64">
 //         <div className="text-muted-foreground">加载中...</div>
@@ -17,11 +18,11 @@
 //     );
 //   }
 
-//   if (error) {
+//   if (isError) {
 //     return (
 //       <div className="flex flex-col items-center justify-center h-64 space-y-4">
-//         <div className="text-destructive">{error}</div>
-//         <Button onClick={refetch} variant="outline" size="sm">
+//         <div className="text-destructive">{getApiErrorMessage(error, '获取数据失败，请稍后重试')}</div>
+//         <Button onClick={() => refetch()} variant="outline" size="sm">
 //           <RefreshCw className="h-4 w-4 mr-2" />
 //           重试
 //         </Button>
@@ -31,7 +32,7 @@
 
 //   return (
 //     <div className="space-y-6">
-//       {/* 页面内容 */}
+//       {/* 页面内容，records 可能为空，渲染前检查 */}
 //     </div>
 //   );
 // }

package/template/client/src/tailwind-theme.css

@@ -213,11 +213,12 @@
     inset: -1px;
   }
 
-  /* Does not work on elements with overflow:hidden! */
-  .hover-elevate:not(.no-default-hover-elevate),
-  .active-elevate:not(.no-default-active-elevate),
-  .hover-elevate-2:not(.no-default-hover-elevate),
-  .active-elevate-2:not(.no-default-active-elevate) {
+  /* Does not work on elements with overflow:hidden!
+   * Wrap in :where() to zero out specificity so Tailwind position utilities (absolute/fixed/sticky) can override */
+  :where(.hover-elevate:not(.no-default-hover-elevate)),
+  :where(.active-elevate:not(.no-default-active-elevate)),
+  :where(.hover-elevate-2:not(.no-default-hover-elevate)),
+  :where(.active-elevate-2:not(.no-default-active-elevate)) {
     position: relative;
     z-index: 0;
   }

package/template/server/modules/hello/hello.controller.ts

@@ -1,16 +1,20 @@
 // /* 模板代码 仅作示例 */
-// import { Controller, Get, Post, Put, Delete, Body, Param, Query, Req, ParseIntPipe } from '@nestjs/common';
+// import { Controller, Get, Query, Req } from '@nestjs/common';
 // import type { Request } from 'express';
+// import { NeedLogin } from '@lark-apaas/fullstack-nestjs-core';
 // import { HelloService } from './hello.service';
+// import { HelloListQueryDto } from './hello.dto';
 
+// // 整个 controller 都需要登录：在类上写一次 @NeedLogin()
 // @Controller('api/hello')
+// @NeedLogin()
 // export class HelloController {
 //   constructor(private readonly helloService: HelloService) {}
 
+//   // 列表 / 筛选接口：用 @Query() 绑定 DTO，不逐个 @Query('xxx') + parseInt
 //   @Get('test')
-//   async test(@Req() req: Request, @Query('limit') limit?: string) {
+//   async test(@Req() req: Request, @Query() query: HelloListQueryDto) {
 //     const { userId } = req.userContext;
-//     const limitNum = limit ? parseInt(limit) : 5;
-//     return this.helloService.test(userId, limitNum);
+//     return this.helloService.test(userId, query.limit ?? 5, query.type);
 //   }
 // }

package/template/server/modules/hello/hello.dto.ts

@@ -0,0 +1,21 @@
+// /* 模板代码 仅作示例 */
+// import { Transform, Type } from 'class-transformer';
+// import { IsIn, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+// import { RECORD_TYPES } from '@shared/api.interface';
+
+// // 查询参数原始值都是字符串：数字字段加 @Type(() => Number)
+// // 可选筛选字段：前端「全部」可能发出空串，读原始值 obj[key]，空串当未传
+// export class HelloListQueryDto {
+//   @IsOptional()
+//   @Type(() => Number)
+//   @IsInt()
+//   @Min(1)
+//   @Max(100)
+//   limit?: number;
+
+//   @IsOptional()
+//   @Transform(({ obj, key, value }) => (obj[key] === '' ? undefined : value))
+//   @IsString()
+//   @IsIn(RECORD_TYPES)
+//   type?: 'meeting' | 'memo';
+// }

package/template/server/modules/hello/hello.service.ts

@@ -2,7 +2,7 @@
 // import { Injectable, Inject, Logger } from '@nestjs/common';
 // import { DRIZZLE_DATABASE, type PostgresJsDatabase } from '@lark-apaas/fullstack-nestjs-core';
 // import { record } from '@server/database/schema';
-// import { eq, and, count, desc, sql, gte, lte, or } from 'drizzle-orm';
+// import { eq, and, desc } from 'drizzle-orm';
 
 // @Injectable()
 // export class HelloService {
@@ -10,12 +10,14 @@
 
 //   constructor(@Inject(DRIZZLE_DATABASE) private readonly db: PostgresJsDatabase) {}
 
-//   async test(userId: string, limit: number = 5) {
+//   async test(userId: string, limit: number = 5, type?: string) {
 //     try {
+//       const conditions = [eq(record.userProfile, userId)];
+//       if (type) conditions.push(eq(record.type, type));
 //       const results = await this.db
 //         .select()
 //         .from(record)
-//         .where(eq(record.userProfile, userId))
+//         .where(and(...conditions))
 //         .orderBy(desc(record.speakDate))
 //         .limit(limit);
   

package/template/shared/api.interface.ts

@@ -1 +1,8 @@
-/* 前后端共享的类型写在这里 */
+/* 前后端共享的类型写在这里 */
+
+// 固定取值（状态、类型等）在这里定义一次，前后端都从这里导入，不另写取值数组或守卫：
+// export const RECORD_TYPES = ['meeting', 'memo'] as const;
+// export type RecordType = (typeof RECORD_TYPES)[number];
+// export const isRecordType = (v: string): v is RecordType =>
+//   (RECORD_TYPES as readonly string[]).includes(v);
+// export const RECORD_TYPE_LABELS: Record<RecordType, string> = { meeting: '会议', memo: '备忘' };