@lark-apaas/coding-template-nestjs-react-fullstack 0.1.55-alpha.20261030085054 → 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.20261030085054",
+  "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 快捷键回调，发送、取消按钮及请求状态由页面组合，首次激活时动态加载最小 Tiptap 编辑器。只读 `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 → record-comments}/app-source.ts

@@ -50,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',
           },
         ];
       });
@@ -85,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',
         };
       });
     },
@@ -125,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

@@ -3,21 +3,15 @@ import { fromApiContent } from './content';
 import {
   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-appearance';
 import * as React from 'react';
 import { cn } from '@/lib/utils';
-import {
-  mentionLabel,
-  normalizeValue,
-  safeUrl,
-} from './content';
+import { mentionLabel, normalizeValue, safeUrl } from './content';
 import {
   useMentionContext,
   useMentionEntity,
@@ -34,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') {
@@ -97,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>
@@ -147,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 }
@@ -154,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
@@ -172,6 +165,7 @@ export function CommentContent(props: CommentContentProps) {
     className,
     onMentionClick,
     mentionVariant,
+    trailing,
   });
 }
 
@@ -180,11 +174,13 @@ function ResolvedContent({
   className,
   onMentionClick,
   mentionVariant,
+  trailing,
 }: {
   value: CommentValue;
   className?: string;
   onMentionClick?: CommentMentionClickHandler;
   mentionVariant?: 'text' | 'pill';
+  trailing?: React.ReactNode;
 }) {
   useResolveComment(normalized);
   return (
@@ -229,6 +225,7 @@ function ResolvedContent({
             />
           ),
         )}
+        {trailing}
       </div>
     </div>
   );

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

@@ -145,7 +145,7 @@ function InputSession(props: CommentInputProps) {
       />
     );
   return (
-    <div className={cn(COMMENT_THEME_CLASS, props.className)}>
+    <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

package/template/client/src/components/business-ui/record-comments/comment-panel-model.ts

@@ -0,0 +1,198 @@
+import { fromApiContent, readApiContent } from './content';
+import type { DiscussionDraft, DiscussionImage, DiscussionThread } from './discussion-types';
+import type { MentionRef } from './types';
+import type {
+  CommentImageInput, CommentPanelProps, CommentPagination, CommentTarget,
+  CommentWriteContent,
+} from './comment-panel.contract';
+
+const userRef = (id?: number): MentionRef | null =>
+  id != null && Number.isSafeInteger(id) && id > 0
+    ? { kind: 'user', idType: 'apaas-user', id: String(id) } : null;
+
+export function buildPanelThreads(props: CommentPanelProps): DiscussionThread[] {
+  return props.comments.map((comment) => ({
+    commentID: comment.commentID,
+    creator: userRef(comment.creator),
+    createTime: comment.createTime,
+    isSolved: comment.isSolved,
+    replies: comment.replies.map((reply, index) => {
+      const target = { recordID: props.recordID, commentID: comment.commentID, replyID: reply.replyID };
+      const images = props.images?.getImages(target) ?? [];
+      const policy = props.getReplyPermissions?.({ ...target, comment, reply, isBody: index === 0 });
+      return {
+        replyID: reply.replyID,
+        author: userRef(reply.creator),
+        createTime: reply.createTime,
+        updateTime: reply.updateTime && reply.updateTime >= reply.createTime ? reply.updateTime : undefined,
+        edited: Boolean(reply.updateTime && reply.updateTime > reply.createTime),
+        value: fromApiContent(reply.content.map((part) => part.type === 'mention' &&
+          (!Number.isSafeInteger(part.userID) || (part.userID ?? 0) <= 0)
+          ? { type: 'mention' } : part)),
+        images: images.map((image) => ({ ...image, name: image.name ?? '图片' })),
+        reactions: (props.reactions?.getReactions(target) ?? []).map((reaction) => ({
+          key: reaction.emojiKey, count: reaction.count, mine: reaction.reactedByMe,
+          users: (reaction.previewUserIDs ?? []).map(String),
+        })),
+        permissions: {
+          canReact: props.reactions?.canChange?.(target) ?? true,
+          canEdit: Boolean(policy?.canEdit && (images.length
+            ? props.images?.onUpdateComment : props.onUpdateComment || props.images?.onUpdateComment)),
+          canDelete: Boolean(policy?.canDelete && props.onDeleteComment),
+          canCopyLink: Boolean(props.getCommentLink?.(target)),
+        },
+      };
+    }),
+  }));
+}
+
+function assertID(id: string) {
+  if (!/^\d+$/.test(id)) throw new Error('评论或回复 ID 必须是非空数字字符串');
+}
+function assertRecord(props: CommentPanelProps) {
+  if (!props.recordID) throw new Error('记录 ID 不能为空');
+}
+function writeContent(draft: DiscussionDraft, allowEmpty: boolean): CommentWriteContent[] {
+  const content = readApiContent(draft.value);
+  if ((!allowEmpty && !content.length) || content.length > 50)
+    throw new Error('评论正文需要包含 1 至 50 个内容元素');
+  for (const part of content) {
+    if (part.type === 'mention' && (!Number.isSafeInteger(part.userID) || (part.userID ?? 0) <= 0))
+      throw new Error('请移除或重新选择无法识别的 @ 人员');
+    if ((part.type === 'text' && !part.text) || (part.type === 'link' && !part.url))
+      throw new Error('评论文本或链接不能为空');
+  }
+  return content as CommentWriteContent[];
+}
+function imageInputs(images: DiscussionImage[]): CommentImageInput[] {
+  return images.map((image) => image.file
+    ? { kind: 'local', localID: image.id, file: image.file }
+    : { kind: 'existing', image: {
+      id: image.id, url: image.url, name: image.name, width: image.width, height: image.height,
+    } });
+}
+function releaseSubmittedPreviews(images: DiscussionImage[]) {
+  // Public image callbacks receive File, never the editor's temporary object URL.
+  for (const image of images)
+    if (image.file && image.url.startsWith('blob:')) URL.revokeObjectURL(image.url);
+}
+export function preparePanelComment(props: CommentPanelProps, draft: DiscussionDraft) {
+  assertRecord(props);
+  if (draft.commentID !== undefined) {
+    assertID(draft.commentID);
+    if (!props.comments.some((thread) => thread.commentID === draft.commentID))
+      throw new Error('原讨论已不存在，请重新选择回复对象');
+  }
+  const base = {
+    recordID: props.recordID,
+    ...(draft.commentID === undefined ? {} : { commentID: draft.commentID }),
+    content: writeContent(draft, draft.images.length > 0),
+  };
+  const imageCommand = draft.images.length > 0 || !props.onAddComment;
+  if (imageCommand) {
+    if (!props.images?.onAddComment) throw new Error('未提供图片评论发送能力');
+    const command = props.images.onAddComment;
+    const input = { ...base, images: imageInputs(draft.images) };
+    return () => command(input);
+  }
+  const command = props.onAddComment!;
+  return () => command(base);
+}
+export async function submitPanelComment(props: CommentPanelProps, draft: DiscussionDraft) {
+  const result = await preparePanelComment(props, draft)();
+  releaseSubmittedPreviews(draft.images);
+  return result;
+}
+function findTarget(props: CommentPanelProps, commentID: string, replyID: string) {
+  assertRecord(props); assertID(commentID); assertID(replyID);
+  const comment = props.comments.find((item) => item.commentID === commentID);
+  const reply = comment?.replies.find((item) => item.replyID === replyID);
+  if (!comment || !reply) throw new Error('原评论已不存在，请刷新后重试');
+  const target = { recordID: props.recordID, commentID, replyID };
+  const policy = props.getReplyPermissions?.({ ...target, comment, reply, isBody: comment.replies[0] === reply });
+  return { target, comment, reply, policy };
+}
+export function preparePanelEdit(
+  props: CommentPanelProps, commentID: string, replyID: string, draft: DiscussionDraft,
+) {
+  const { target, policy } = findTarget(props, commentID, replyID);
+  if (!policy?.canEdit) throw new Error('没有编辑该评论的权限');
+  const hadImages = Boolean(props.images?.getImages(target).length);
+  const base = { ...target, content: writeContent(draft, draft.images.length > 0) };
+  if (hadImages || draft.images.length || !props.onUpdateComment) {
+    if (!props.images?.onUpdateComment) throw new Error('未提供图片评论编辑能力');
+    const command = props.images.onUpdateComment;
+    const input = { ...base, images: imageInputs(draft.images) };
+    return () => command(input);
+  }
+  const command = props.onUpdateComment;
+  return () => command(base);
+}
+export async function editPanelComment(props: CommentPanelProps, commentID: string, replyID: string, draft: DiscussionDraft) {
+  const result = await preparePanelEdit(props, commentID, replyID, draft)();
+  releaseSubmittedPreviews(draft.images);
+  return result;
+}
+export function preparePanelDeletion(props: CommentPanelProps, commentID: string, replyID: string) {
+  const { target, policy } = findTarget(props, commentID, replyID);
+  if (!policy?.canDelete || !props.onDeleteComment) throw new Error('没有删除该评论的权限');
+  const command = props.onDeleteComment;
+  const input = { recordID: target.recordID, commentID, replyID };
+  return () => command(input);
+}
+export async function deletePanelComment(props: CommentPanelProps, commentID: string, replyID: string) {
+  return preparePanelDeletion(props, commentID, replyID)();
+}
+
+/** Shared by intersection, scroll and retry triggers; its lock is synchronous. */
+export class CommentPageLoader {
+  pending = false;
+  error = '';
+  automaticLoads = 0;
+  async load(pagination: CommentPagination, manual = false): Promise<boolean> {
+    if (this.pending || pagination.loading || !pagination.hasMore) return false;
+    if (!manual && (this.error || pagination.error || this.automaticLoads >= 3)) return false;
+    if (manual) this.automaticLoads = 0;
+    else this.automaticLoads++;
+    this.pending = true;
+    this.error = '';
+    try {
+      await pagination.onLoadMore();
+      return true;
+    } catch (cause) {
+      this.error = cause instanceof Error ? cause.message : '加载失败，请重试';
+      return false;
+    } finally { this.pending = false; }
+  }
+}
+
+export async function loadPanelReactionDetails(props: CommentPanelProps, target: CommentTarget, signal: AbortSignal) {
+  const feature = props.reactions;
+  const reactions = feature?.getReactions(target) ?? [];
+  return Promise.all(reactions.map(async (reaction) => {
+    const users = new Set<number>();
+    let cursor: string | undefined;
+    const seen = new Set<string>();
+    if (!feature?.loadUsers) return {
+      key: reaction.emojiKey, count: reaction.count, mine: reaction.reactedByMe,
+      users: (reaction.previewUserIDs ?? []).map(String),
+    };
+    for (let page = 0; page < 100; page++) {
+      signal.throwIfAborted();
+      const result = await feature.loadUsers({ ...target, emojiKey: reaction.emojiKey, ...(cursor ? { cursor } : {}) }, signal);
+      result.userIDs.forEach((id) => users.add(id));
+      if (!result.nextCursor) return {
+        key: reaction.emojiKey, count: reaction.count, mine: reaction.reactedByMe, users: [...users].map(String),
+      };
+      if (seen.has(result.nextCursor)) throw new Error('回应人员分页游标未前进');
+      seen.add(result.nextCursor); cursor = result.nextCursor;
+    }
+    throw new Error('回应人员较多，请稍后重试');
+  }));
+}
+
+export function commentFailureMessage(cause: unknown, fallback: string): string {
+  const message = cause instanceof Error ? cause.message : fallback;
+  return cause instanceof Error && 'outcome' in cause && cause.outcome === 'unknown'
+    ? `${message}；操作结果未确认，请先刷新核对后再操作` : message;
+}

package/template/client/src/components/business-ui/record-comments/comment-panel-optimistic.ts

@@ -0,0 +1,171 @@
+import { normalizeValue, readApiContent } from './content';
+import { commentFailureMessage } from './comment-panel-model';
+import type { CommentIDs, DeleteCommentResult, CommentMutationFailure } from './comment-panel.contract';
+import type { DiscussionDraft, DiscussionImage, DiscussionReply, DiscussionThread } from './discussion-types';
+import type { MentionRef } from './types';
+
+export interface LocalCommentMutation {
+  id: string;
+  kind: 'add' | 'edit' | 'delete';
+  phase: 'sending' | 'failed' | 'uncertain' | 'confirmed';
+  message?: string;
+}
+interface Operation extends LocalCommentMutation {
+  thread: DiscussionThread;
+  commentID: string;
+  replyID: string;
+  draft?: DiscussionDraft;
+  author?: MentionRef;
+  createTime: number;
+  wholeThread?: boolean;
+  execute: () => Promise<CommentIDs | DeleteCommentResult>;
+}
+const contentKey = (reply: Pick<DiscussionReply, 'value'>) => JSON.stringify(readApiContent(reply.value));
+const imageKey = (images: readonly DiscussionImage[]) => JSON.stringify(images.map(({ id, url }) => [id, url]));
+const uncertain = (message: string) => Object.assign(new Error(message), { outcome: 'unknown' as const });
+
+/** Component-local overlay. Never writes the host's data or performs a request itself. */
+export class CommentMutations {
+  private operations: Operation[] = [];
+  private listeners = new Set<() => void>();
+  private version = 0;
+  private active = true;
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  getVersion = () => this.version;
+  private changed() { if (this.active) { this.version++; this.listeners.forEach((listener) => listener()); } }
+  activate() { this.active = true; }
+  private release(operation: Operation) {
+    for (const image of operation.draft?.images ?? [])
+      if (image.file && image.url.startsWith('blob:')) URL.revokeObjectURL(image.url);
+  }
+  dispose() {
+    this.active = false;
+    this.operations.forEach((operation) => this.release(operation));
+    this.operations = [];
+  }
+  replyID(id: string) { return this.operations.find((operation) => operation.id === id)?.replyID ?? id; }
+  private assertAvailable(commentID: string, replyID?: string) {
+    if (!this.active) throw new Error('评论会话已关闭');
+    if (this.operations.some((operation) => operation.commentID === commentID &&
+      (operation.wholeThread || (operation.kind === 'add' && !operation.draft?.commentID) || operation.replyID === replyID)))
+      throw new Error('该评论仍在处理中，请先完成同步或处理失败提示');
+  }
+  private start(operation: Operation) {
+    this.operations.push(operation); this.changed();
+    void this.run(operation);
+    return operation.id;
+  }
+  add(thread: DiscussionThread | undefined, draft: DiscussionDraft, author: MentionRef | undefined, execute: () => Promise<CommentIDs>) {
+    if (thread) this.assertAvailable(thread.commentID);
+    else if (!this.active) throw new Error('评论会话已关闭');
+    const id = `local:${crypto.randomUUID()}`;
+    const createTime = Math.floor(Date.now() / 1000);
+    const commentID = thread?.commentID ?? `local:thread:${crypto.randomUUID()}`;
+    return this.start({ id, kind: 'add', phase: 'sending', commentID, replyID: id,
+      thread: thread ?? { commentID, creator: author ?? null, createTime, isSolved: false, replies: [] },
+      draft: { ...draft, commentID: thread?.commentID, value: normalizeValue(draft.value), images: [...draft.images] }, author, createTime, execute });
+  }
+  edit(thread: DiscussionThread, replyID: string, draft: DiscussionDraft, execute: () => Promise<CommentIDs>) {
+    this.assertAvailable(thread.commentID, replyID);
+    return this.start({ id: `local:${crypto.randomUUID()}`, kind: 'edit', phase: 'sending',
+      thread, commentID: thread.commentID, replyID, createTime: Math.floor(Date.now() / 1000),
+      draft: { ...draft, value: normalizeValue(draft.value), images: [...draft.images] }, execute });
+  }
+  delete(thread: DiscussionThread, replyID: string, execute: () => Promise<DeleteCommentResult>) {
+    // The UI always deletes one selected message, including the current body.
+    const wholeThread = false;
+    this.assertAvailable(thread.commentID, replyID);
+    return this.start({ id: `local:${crypto.randomUUID()}`, kind: 'delete', phase: 'sending',
+      thread, commentID: thread.commentID, replyID, wholeThread, createTime: Math.floor(Date.now() / 1000), execute });
+  }
+  private async run(operation: Operation) {
+    operation.phase = 'sending'; operation.message = undefined; this.changed();
+    try {
+      const result = await operation.execute();
+      if (!this.active) return;
+      if (!/^\d+$/.test(result.commentID)) throw uncertain('提交结果缺少有效评论 ID');
+      if (operation.kind !== 'add' || operation.draft?.commentID !== undefined) {
+        if (result.commentID !== operation.commentID) throw uncertain('提交结果与目标讨论不一致');
+      }
+      if (operation.kind === 'delete') {
+        if (!('commentDeleted' in result) || typeof result.commentDeleted !== 'boolean') throw uncertain('删除结果未确认');
+        operation.wholeThread = result.commentDeleted;
+      } else {
+        if (!('replyID' in result) || !/^\d+$/.test(result.replyID)) throw uncertain('提交结果缺少有效回复 ID');
+        if (operation.kind === 'edit' && result.replyID !== operation.replyID) throw uncertain('编辑结果与目标回复不一致');
+        operation.replyID = result.replyID;
+      }
+      operation.commentID = result.commentID;
+      operation.phase = 'confirmed';
+    } catch (cause) {
+      if (!this.active) return;
+      operation.phase = (cause as CommentMutationFailure | null)?.outcome === 'unknown' ? 'uncertain' : 'failed';
+      operation.message = commentFailureMessage(cause, '操作失败，请重试');
+    }
+    this.changed();
+  }
+  retry(id: string) {
+    const operation = this.operations.find((item) => item.id === id);
+    if (!operation || operation.phase !== 'failed' || !this.active) return;
+    void this.run(operation);
+  }
+  dismiss(id: string) {
+    const operation = this.operations.find((item) => item.id === id);
+    if (!operation || !['failed', 'uncertain'].includes(operation.phase)) return;
+    this.operations = this.operations.filter((item) => item !== operation);
+    this.release(operation); this.changed();
+  }
+  private acknowledged(operation: Operation, base: readonly DiscussionThread[]) {
+    const thread = base.find((item) => item.commentID === operation.commentID);
+    const reply = thread?.replies.find((item) => item.replyID === operation.replyID);
+    if (operation.kind === 'delete') return operation.wholeThread ? !thread : !reply;
+    if (!reply) return false;
+    if (operation.kind === 'add') return true;
+    const before = operation.thread.replies.find((item) => item.replyID === operation.replyID)!;
+    // A later authoritative edit wins even when another editor changed the text.
+    // Compare server revisions, never the optimistic client wall clock.
+    if (operation.phase === 'confirmed' && reply.updateTime !== undefined &&
+      reply.updateTime > (before.updateTime ?? before.createTime)) return true;
+    if (contentKey(reply) !== contentKey({ value: operation.draft!.value })) return false;
+    const images = operation.draft!.images;
+    if (imageKey(images) === imageKey(before.images)) return true;
+    return images.some((image) => image.file)
+      ? reply.images.length === images.length && imageKey(reply.images) !== imageKey(before.images)
+      : imageKey(reply.images) === imageKey(images);
+  }
+  reconcile(base: readonly DiscussionThread[]) {
+    const finished = this.operations.filter((operation) => (operation.phase === 'confirmed' ||
+      (operation.phase === 'uncertain' && operation.kind !== 'add')) && this.acknowledged(operation, base));
+    if (!finished.length) return;
+    this.operations = this.operations.filter((operation) => !finished.includes(operation));
+    finished.forEach((operation) => this.release(operation)); this.changed();
+  }
+  view(base: readonly DiscussionThread[]): DiscussionThread[] {
+    let threads = base.map((thread) => ({ ...thread, replies: [...thread.replies] }));
+    for (const operation of this.operations) {
+      let thread = threads.find((item) => item.commentID === operation.commentID);
+      if (operation.kind === 'delete' && operation.phase === 'confirmed') {
+        if (operation.wholeThread) threads = threads.filter((item) => item !== thread);
+        else if (thread) thread.replies = thread.replies.filter((reply) => reply.replyID !== operation.replyID);
+        continue;
+      }
+      if (!thread) {
+        thread = { ...operation.thread, commentID: operation.commentID, replies: [...operation.thread.replies] };
+        threads.push(thread);
+      }
+      const index = thread.replies.findIndex((item) => item.replyID === operation.replyID);
+      const before = thread.replies[index] ?? operation.thread.replies.find((item) => item.replyID === operation.replyID);
+      const mutation: LocalCommentMutation = { id: operation.id, kind: operation.kind, phase: operation.phase, message: operation.message };
+      const reply: DiscussionReply = operation.kind === 'add'
+        ? { replyID: operation.replyID, author: operation.author ?? null, createTime: operation.createTime,
+          value: operation.draft!.value, images: operation.draft!.images, reactions: [], mutation }
+        : { ...before!, ...(operation.draft ? { value: operation.draft.value, images: operation.draft.images,
+          edited: before?.edited || operation.phase === 'confirmed',
+          updateTime: operation.phase === 'confirmed' ? operation.createTime : before?.updateTime } : {}), mutation };
+      if (index < 0) thread.replies.push(reply); else thread.replies[index] = reply;
+      if ((operation.kind === 'delete' && operation.wholeThread) || (operation.kind === 'add' && !operation.draft?.commentID))
+        thread.replies = thread.replies.map((item) => ({ ...item, mutationBlocked: true }));
+    }
+    return threads.filter((thread) => thread.replies.length > 0);
+  }
+}