@lark-apaas/coding-template-nestjs-react-fullstack 0.1.55-alpha.20261030081308 → 0.1.55-alpha.20261101040602

package/package.json

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

package/template/client/src/components/business-ui/README.md

@@ -1,5 +1,7 @@
 # 业务组件文档
 
+记录评论组件入口：`@/components/business-ui/record-comments`。使用前阅读 [组件接口与接入说明](record-comments/README.md)。评论请求与分页游标留在宿主，组件负责回复、编辑删除、人员提及、乐观更新及可选表情/文档引用。
+
 本文档包含用户选择、部门选择、群组选择、用户展示等业务组件的使用说明。
 
 ---
@@ -517,13 +519,3 @@ function BasicExample() {
   return <UserProfile value="user-123" />;
 }
 ```
-
-## 评论输入与展示
-
-`comment/comment-content.tsx` 提供不依赖 Tiptap 的只读展示，配合 `comment/mention-provider.tsx` 批量补全人员和文档信息。
-
-评论输入框已内置。从 `@/components/business-ui/comment/comment-input` 直接导入 `CommentInput`，组件提供 getContent/clear/setEditable/focus ref API 和 onSubmitRequest 快捷键回调，发送、取消按钮及请求状态由页面组合，原生 div 编辑器直接可编辑；支持选择/粘贴图片并在正文下方展示附件，使用 getImages/clearImages 管理。只读 `CommentContent` 不依赖编辑器。作者、时间、线程与接口调用由消费页面组合。
-
-数据源和真实服务的接入要求见 [CommentInput 使用说明](./comment/README.md)。输入与只读列表应共享同一 CommentProvider；CCM 的 Lark ID 与模板的 apaas ID 不能混用。
-
-人员服务使用 `CommentProvider` 的内置 UserDisplay 数据源。文档服务通过 `CommentProvider documents={documentSource}` 单独提供，再为输入框设置 `enableDocuments`；可复用 `createCcmDocumentSource` 接入 miaoda 的推荐、元数据与嵌入权限接口。文档显示类型图标与标题，点击新窗打开链接，编辑态与只读态共享样式。接口协议为 text、mention(userID) 和 link(url)，文档输出 link 节点；缺少 userID 的历史 mention 使用可见占位，不影响同条评论的其他内容。仅支持这三类内容，不包含图片与旧 CCM 评论格式兼容。

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/record-comments/README.md

@@ -0,0 +1,58 @@
+# Record comments
+
+完整受控记录评论组件，入口 `CommentPanel`。公共合同见 `comment-panel.contract.ts`、`types.ts`，统一从 `index.ts` 导入；目录内实现、CSS 和 `assets/reaction-sprite.png` 必须整体分发。不依赖旧 comment 目录，不包含测试应用、插件实例或表格配置。模板已配置 React、Tiptap 3.20.0、floating-ui 及 ui primitives 依赖。
+
+组件管理现有样式、回复归属、编辑器、人员弹层、菜单、分页触发和乐观更新；评论 CRUD、身份、权限、插件调用、服务端缓存、分页游标、表情及文档请求由宿主提供。
+
+## 接入
+
+必填 `scopeKey/recordID/comments/mentionSource`。可选参数完整类型见 `CommentPanelProps`。
+
+```tsx
+import { useMemo } from 'react';
+import { CommentPanel, createAppCommentSource, type CommentPanelProps } from '@/components/business-ui/record-comments';
+
+type Props = Omit<CommentPanelProps, 'mentionSource'>;
+export function RecordComments(props: Props) {
+  const source = useMemo(() => createAppCommentSource(props.scopeKey), [props.scopeKey]);
+  return <CommentPanel {...props} mentionSource={source} />;
+}
+```
+
+数据和回调接宿主真实 API hook。`createAppCommentSource` 是可选的妙搭人员目录适配器，不含评论请求；其他目录直接实现 `CommentDataSource`。默认没有空查询推荐，可由宿主补 `recommend`。scopeKey 必须覆盖应用、租户、身份、插件、数据源及权限；上述上下文变化时更换。mentionSource 用 useMemo 稳定，scopeKey/recordID 变化会清理旧会话。
+
+`commentID/replyID` 保留字符串；`createTime/updateTime` 为 Unix 秒。每条 comments 是讨论，第一条 reply 为正文，其余为同讨论回复。回复必须带原 commentID，不拆成独立消息。缺失 mention.userID 保留缺失引用，不猜人员。写 content 只含 text、mention.userID、link.url，不含编辑器元数据或文件。
+
+编辑/删除须显式提供 `getReplyPermissions`，缺省隐藏；前端菜单不替代后端鉴权。消息菜单点击“删除”即发起请求，无二次确认；始终传所选 replyID（含首条），只删除该消息。删除首条后第二条在原 commentID 下顺位成为正文，保留其 replyID/作者/时间，其他回复不变；最后一条删除后移除空讨论。省略 replyID 的历史整串删除仅供显式外部调用，组件菜单不使用。
+
+## 乐观更新与时间
+
+写回调只负责真实写入，成功返回真实 ID（删除返回 commentDeleted）；后续回读单独执行，不因回读失败 reject 已提交写入，不在宿主重复插入临时消息。
+
+新增/回复立即显示并清空编辑器，编辑立即显示新文本并退出编辑。提交期间隐藏时间；新增/回复纯文字消息等待 500ms 后显示蓝色 loading，编辑不显示该 spinner；成功立即结束等待，不等回读。明确失败保留灰色内容、错误图标/文案与点击重试。未确认消息禁止继续编辑、回复或回应，其他消息与输入正常可用。
+
+普通 Error 仅表示确认未应用；超时/连接中断可能已写入时抛 `Object.assign(new Error(message), {outcome:'unknown'})`，组件保留内容并阻止盲目重发，宿主先刷新核对。只有确认请求未发出时使用 not-applied。
+
+匹配快照接管前，本地层保留消息防闪回；接管后去重。宿主须保护缓存读取顺序，组件不能从无版本号数组识别旧快照。传入 comments 不会被修改。卸载清理本地预览，旧回调不能更新新会话。
+
+显示时间取 `updateTime ?? createTime`，编辑标记取 `updateTime > createTime`，排序仍用创建时间。编辑确认、回读前临时用本次操作时间，回读后以服务端回复级 updateTime 为准。服务端新编辑可接管已确认草稿。秒级时间不是严格版本号，缺 updateTime 不能伪造历史编辑时间。
+
+## 分页和扩展
+
+宿主首屏读取；传 `pagination={hasMore,loading,error,onLoadMore}` 时组件接近底部自动触发。宿主保留游标，先追加 comments 再 resolve，失败 reject。组件有即时并发锁和连续自动加载上限，可滚动或手动继续。不传 pagination 表示外部已提供完整列表。
+
+- **表情**：传 reactions 的 getReactions/onChange，可选 canChange/loadUsers。缺回应数据表示未知，不能从截断 userIDs 推断 mine。宿主按回复串行，显式添加/撤回；成功更新缓存，失败只回退目标，回读失败不回退成功动作。历史表情键保留。
+- **文档**：宿主实现当前用户授权的 CommentDocumentSource，用 withDocumentSource 与人员来源合并并传 enableDocuments。推荐/搜索/解析均外置，持久化仅 link.url。无权限不得回退 owner 查询私密标题，插入引用不改变分享权限。文档不可用时保留人员结果。
+- **图片**：当前多维表格插件未接入，默认不传 images。该扩展仅面向宿主自备完整上传/持久化/回读能力，不得把 File/blob URL 写入插件 content。预览保留到快照接管或会话卸载。
+- **人员卡片/链接**：由 onMentionClick/getCommentLink 承接，缺回调不展示无效操作。
+
+完整 Action 映射、身份约束和接入验收见配套 `plugin-guide/references/record-comments.md`。模板不含 mock 路由；仅 mock 通过不能声称真实链路完成。
+
+人员提及悬浮沿用官方颜色：普通人员浅蓝底、自身蓝色胶囊变亮、无权限人员灰底。样式由 mention-appearance.css 的组件专属类提供，不依赖宿主 accent 配色。
+
+
+## 交互接入约束
+
+宿主复用组件已有交互，不额外包装删除确认、成功 toast 或“已显示全部评论”提示。复制链接成功后只关闭菜单；编辑操作按钮保持“确认”，等待态不新增“保存中”文字。回复自己也会插入自身提及；未知作者不能伪造提及。保持人员搜索和提及悬浮样式，不用宿主全局 button/a/p 样式覆盖组件。
+
+保留读写失败的恢复入口和无障碍状态；未知写入结果不得开放盲目重试。新增提示或改变状态流前，应取得官方对应状态的操作证据；本地受控故障测试不等同于真实 Action 验收，未覆盖的权限/网络/图片能力需明确标注。

package/template/client/src/components/business-ui/{comment/comment-provider.tsx → record-comments/app-source.ts}

@@ -1,50 +1,12 @@
-import { useMemo, type ReactNode } from 'react';
-import * as React from 'react';
-import { getAppId } from '../user-select/utils';
-import { useCurrentUserProfile } from '@lark-apaas/client-toolkit/hooks/useCurrentUserProfile';
-import { MentionProvider } from './mention-provider';
+import { listUsersByIds, searchUsers } from '../api/users/service';
+import { getI18nText } from '../utils/user';
+import { mentionKey } from './content';
 import type {
   CommentDataSource,
   CommentDocumentSource,
   MentionOption,
   MentionResult,
 } from './types';
-import { listUsersByIds, searchUsers } from '../api/users/service';
-import { getI18nText } from '../utils/user';
-import { mentionKey } from './content';
-
-/** Configure the built-in UserDisplay data service once for the input and list. */
-export function CommentProvider({
-  children,
-  scopeKey,
-  currentUserID,
-  recommend,
-  documents,
-}: {
-  children: ReactNode;
-  scopeKey?: string;
-  currentUserID?: string;
-  recommend?: CommentDataSource['recommend'];
-  documents?: CommentDocumentSource;
-}) {
-  const user = useCurrentUserProfile();
-  const scope = JSON.stringify([
-    typeof window === 'undefined' ? null : getAppId(window.location.pathname),
-    scopeKey || user.user_id || 'pending',
-  ]);
-  const source = useMemo(() => {
-    const people = { ...createAppCommentSource(scope), recommend };
-    return documents ? withDocumentSource(people, documents) : people;
-  }, [scope, recommend, documents]);
-  return (
-    <MentionProvider
-      source={source}
-      currentUserID={currentUserID || user.user_id}
-    >
-      {children}
-    </MentionProvider>
-  );
-}
 
 function avatarUrl(avatar: unknown): string | undefined {
   if (typeof avatar === 'string') return avatar;
@@ -88,6 +50,7 @@ export function createAppCommentSource(scopeKey: string): CommentDataSource {
             label: getI18nText(user.name) || '未命名人员',
             avatarUrl: avatarUrl(user.avatar),
             description: getI18nText(user.department?.name) || user.tenantName,
+            isExternal: user.userType === '_externalUser',
           },
         ];
       });
@@ -123,6 +86,8 @@ export function createAppCommentSource(scopeKey: string): CommentDataSource {
           status: 'resolved',
           label: getI18nText(user.name) || '未命名人员',
           avatarUrl: avatarUrl(user.avatar),
+          description: getI18nText(user.department?.name),
+          isExternal: user.userType === '_externalUser',
         };
       });
     },
@@ -163,14 +128,21 @@ export function withDocumentSource(
     const exhausted: Awaited<ReturnType<CommentDataSource['search']>> = {
       items: [],
     };
-    const [users, docs] = await Promise.all([
-      !args.cursor || cursor.user !== undefined
+    const requestUsers = !args.cursor || cursor.user !== undefined;
+    const requestDocs = !args.cursor || cursor.document !== undefined;
+    const pages = await Promise.allSettled([
+      requestUsers
         ? fetchSource(people, 'user', cursor.user)
         : exhausted,
-      !args.cursor || cursor.document !== undefined
+      requestDocs
         ? fetchSource(documents, 'document', cursor.document)
         : exhausted,
     ]);
+    if ((!requestUsers || pages[0].status === 'rejected') && (!requestDocs || pages[1].status === 'rejected'))
+      throw new Error('人员和文档搜索失败，请重试');
+    // A disabled/unavailable document capability must not break existing @people.
+    const users = pages[0].status === 'fulfilled' ? pages[0].value : exhausted;
+    const docs = pages[1].status === 'fulfilled' ? pages[1].value : exhausted;
     return {
       items: [
         ...users.items.filter((item) => item.ref.kind === 'user'),

package/template/client/src/components/business-ui/{comment → record-comments}/comment-content.tsx

@@ -1,16 +1,14 @@
+import { DocumentIcon } from './document-icon';
 import { fromApiContent } from './content';
 import {
-  DocumentIcon,
   USER_MENTION_CLASS,
   INPUT_USER_MENTION_CLASS,
-  INPUT_USER_MENTION_LABEL_CLASS,
   COMMENT_THEME_CLASS,
-  USER_MENTION_SELF_CLASS,
+  userMentionLabelClass,
   atUserLabel,
-  USER_MENTION_LABEL_CLASS,
   DOCUMENT_MENTION_CLASS,
   DOCUMENT_MENTION_UNREADABLE_CLASS,
-} from './mention-view';
+} from './mention-appearance';
 import * as React from 'react';
 import { cn } from '@/lib/utils';
 import { mentionLabel, normalizeValue, safeUrl } from './content';
@@ -30,12 +28,15 @@ function Mention({
   part,
   onMentionClick,
   mentionVariant,
+  trailing,
 }: {
   part: Extract<CommentPart, { type: 'mention' }>;
   onMentionClick?: CommentMentionClickHandler;
   mentionVariant?: 'text' | 'pill';
+  trailing?: React.ReactNode;
 }) {
-  const { strict, store, currentUserID } = useMentionContext();
+  const { strict, store, currentUserID, highlightUserIDs } =
+    useMentionContext();
   const result = useMentionEntity(part.ref);
   const label = mentionLabel(part.ref, part.label, result, strict);
   if (part.ref.kind === 'document') {
@@ -93,18 +94,13 @@ function Mention({
       );
     return <span className={DOCUMENT_MENTION_CLASS}>{body}</span>;
   }
-  const userLabelClass =
-    mentionVariant === 'pill'
-      ? INPUT_USER_MENTION_LABEL_CLASS
-      : part.ref.id === currentUserID
-        ? USER_MENTION_SELF_CLASS
-        : USER_MENTION_LABEL_CLASS;
+  const userLabelClass = userMentionLabelClass(
+    part.ref.id === currentUserID || Boolean(highlightUserIDs?.includes(part.ref.id)),
+    result?.status === 'forbidden',
+  );
   const body = (
     <span
-      className={cn(
-        userLabelClass,
-        result?.status === 'forbidden' && 'text-muted-foreground',
-      )}
+      className={userLabelClass}
     >
       {atUserLabel(label)}
     </span>
@@ -143,6 +139,7 @@ export type CommentContentProps = {
   className?: string;
   onMentionClick?: CommentMentionClickHandler;
   mentionVariant?: 'text' | 'pill';
+  trailing?: React.ReactNode;
 } & (
   | { value: CommentValue; content?: never }
   | { content: readonly CommentApiContent[]; value?: never }
@@ -150,7 +147,7 @@ export type CommentContentProps = {
 
 /** Pass API content with userID only; metadata is fetched internally in batches. */
 export function CommentContent(props: CommentContentProps) {
-  const { className, onMentionClick, mentionVariant = 'text' } = props;
+  const { className, onMentionClick, mentionVariant = 'text', trailing } = props;
   let normalized: CommentValue;
   try {
     normalized = props.value
@@ -168,6 +165,7 @@ export function CommentContent(props: CommentContentProps) {
     className,
     onMentionClick,
     mentionVariant,
+    trailing,
   });
 }
 
@@ -176,11 +174,13 @@ function ResolvedContent({
   className,
   onMentionClick,
   mentionVariant,
+  trailing,
 }: {
   value: CommentValue;
   className?: string;
   onMentionClick?: CommentMentionClickHandler;
   mentionVariant?: 'text' | 'pill';
+  trailing?: React.ReactNode;
 }) {
   useResolveComment(normalized);
   return (
@@ -225,6 +225,7 @@ function ResolvedContent({
             />
           ),
         )}
+        {trailing}
       </div>
     </div>
   );

package/template/client/src/components/business-ui/record-comments/comment-input.tsx

@@ -0,0 +1,190 @@
+import {
+  useEffect,
+  useImperativeHandle,
+  useCallback,
+  useRef,
+  useState,
+  type ComponentType,
+} from 'react';
+import * as React from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+import { COMMENT_THEME_CLASS } from './mention-appearance';
+import { CommentContent } from './comment-content';
+import { useMentionContext } from './mention-provider';
+import type {
+  CommentInputProps,
+  CommentInputHandle,
+  CommentEditorProps,
+} from './types';
+import {
+  emptyComment,
+  normalizeValue,
+  readApiContent,
+} from './content';
+
+let modulePromise: Promise<typeof import('./editor')> | undefined;
+function loadEditor() {
+  // Reset rejected imports so explicit retry actually executes import again.
+  return (modulePromise ||= import('./editor').catch((error) => {
+    modulePromise = undefined;
+    throw error;
+  }));
+}
+export function preloadCommentEditor() {
+  void loadEditor().catch(() => {});
+}
+
+/** Public entry contains no static import of Tiptap. A session change resets all work. */
+export function CommentInput(props: CommentInputProps) {
+  const { store } = useMentionContext();
+  try {
+    normalizeValue(props.value);
+  } catch {
+    return (
+      <p role="alert" className="text-sm text-destructive">
+        评论内容格式无效，无法编辑
+      </p>
+    );
+  }
+  return (
+    <ErrorBoundary
+      key={JSON.stringify([store.source.scopeKey, props.documentKey])}
+      fallbackRender={({ resetErrorBoundary }) => (
+        <div
+          role="alert"
+          className="rounded-lg border p-3 text-sm text-destructive"
+        >
+          编辑器发生错误，输入内容已保留。
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={resetErrorBoundary}
+          >
+            重新加载
+          </Button>
+        </div>
+      )}
+    >
+      <InputSession {...props} />
+    </ErrorBoundary>
+  );
+}
+
+function InputSession(props: CommentInputProps) {
+  const [Editor, setEditor] =
+    React.useState<ComponentType<CommentEditorProps> | null>(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const editorRef = useRef<CommentInputHandle | null>(null);
+  const editable = useRef(true);
+  const [enabled, setEnabled] = useState(true);
+  const loadingRef = useRef(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+  const activate = useCallback(async () => {
+    if (loadingRef.current || latest.current.disabled || !editable.current)
+      return;
+    loadingRef.current = true;
+    setLoading(true);
+    setError('');
+    try {
+      const module = await loadEditor();
+      if (alive.current) setEditor(() => module.default);
+    } catch {
+      if (alive.current) setError('编辑器加载失败，请重试');
+    } finally {
+      loadingRef.current = false;
+      if (alive.current) setLoading(false);
+    }
+  }, []);
+  useImperativeHandle(
+    props.ref,
+    () => ({
+      getContent: () =>
+        editorRef.current?.getContent() ?? readApiContent(latest.current.value),
+      clear() {
+        if (!alive.current) return;
+        if (editorRef.current) editorRef.current.clear();
+        else {
+          const value = emptyComment();
+          latest.current = { ...latest.current, value };
+          latest.current.onChange(value);
+        }
+      },
+      setEditable(next) {
+        if (!alive.current) return;
+        editable.current = next;
+        editorRef.current?.setEditable(next && !latest.current.disabled);
+        setEnabled(next);
+      },
+      focus() {
+        if (!alive.current) return;
+        if (editorRef.current) editorRef.current.focus();
+        else void activate();
+      },
+    }),
+    [activate],
+  );
+  const { ref: _ref, ...editorProps } = props;
+  if (Editor)
+    return (
+      <Editor
+        {...editorProps}
+        disabled={props.disabled || !enabled}
+        editorRef={editorRef}
+      />
+    );
+  return (
+    <div className={cn(COMMENT_THEME_CLASS, 'replica-input', props.className)}>
+      <div className="relative flex min-h-[34px] flex-col justify-center rounded-[6px] border-[0.5px] border-border bg-card px-3 py-[5px] transition-colors hover:border-primary focus-within:border-primary">
+        <div
+          aria-hidden
+          className="pointer-events-none w-full text-sm leading-[22px]"
+        >
+          {loading || error ? (
+            <span className="text-muted-foreground">
+              {loading ? '正在加载编辑器…' : '重试加载编辑器'}
+            </span>
+          ) : props.value.content.length ? (
+            <CommentContent value={props.value} mentionVariant="pill" />
+          ) : (
+            <span className="text-muted-foreground">
+              {props.placeholder || '输入评论'}
+            </span>
+          )}
+        </div>
+        <Button
+          type="button"
+          variant="ghost"
+          className="no-default-hover-elevate no-default-active-elevate absolute inset-0 h-full min-h-0 w-full rounded-[6px] p-0"
+          disabled={props.disabled || !enabled || loading}
+          aria-busy={loading}
+          onPointerEnter={preloadCommentEditor}
+          onFocus={preloadCommentEditor}
+          onClick={() => {
+            void activate();
+          }}
+        >
+          <span className="sr-only">
+            {error ? '重试加载编辑器' : props.placeholder || '输入评论'}
+          </span>
+        </Button>
+      </div>
+      {error ? (
+        <p role="alert" className="mt-2 text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}