@lark-apaas/coding-template-nestjs-react-fullstack 0.1.60-alpha.20261105131051 → 0.1.60-alpha.20261105142153

package/package.json

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

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

@@ -1,36 +1,101 @@
-# 通用评论入口（OpenAPI pilot）
+# 评论组件
 
-与 `record-comments` 共享 UI/CSS 和乐观更新逻辑。新的公开数据契约不包含 Action、插件实例或飞书数字用户 ID。旧入口继续兼容；此试接入不搬迁全部内部文件，不自动迁移应用。
+默认通过 `useComments` 接入。页面只提供业务对象、当前用户和 adapter；请求方法、认证及服务协议由应用自己实现。UI、回复/编辑/删除、乐观更新仍由同一套组件管理。
 
 ```tsx
-import { CommentsProvider, CommentList, CommentComposer, commentReactions } from '@/components/business-ui/comments';
-
-<CommentsProvider
-  scopeKey="feishu:my-app:account"
-  subjectKey={documentToken}
-  threads={threads}
-  currentUser={currentUser}
-  actions={adapter.actions}
-  input={{ userMentions: ref => ref.namespace === userNamespace, links: true }}
-  actors={directory}
-  extensions={[commentReactions({ allowedKeys: ['THUMBSUP'], onChange: adapter.changeReaction })]}
->
-  <div className="min-h-0 flex-1 overflow-y-auto"><CommentList /></div>
-  <CommentComposer />
-</CommentsProvider>
+import {
+  useComments,
+  CommentsProvider,
+  CommentList,
+  CommentComposer,
+} from '@/components/business-ui/comments';
+
+function Comments({ recordId, currentUser, adapter }) {
+  const comments = useComments({ resourceKey: recordId, currentUser, adapter });
+  return (
+    <CommentsProvider value={comments}>
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        <CommentList />
+      </div>
+      <CommentComposer />
+    </CommentsProvider>
+  );
+}
 ```
 
-`CommentsProvider` 不输出布局 DOM。也可用 `CommentPanel` 提供默认完整布局。类型以 `contracts.ts` 为准。
+Provider 不输出布局 DOM。标题、边框、尺寸、滚动容器归页面。也可 `<CommentPanel value={comments} />` 使用默认完整布局。主输入框在同一个 Provider 内挂一次，行内编辑由列表承载。
+
+## 最小 adapter
+
+```ts
+import type { CommentAdapter } from '@/components/business-ui/comments';
+
+const adapter: CommentAdapter = {
+  scopeKey: 'my-api:tenant:authenticated-account',
+  async list({ resourceKey, cursor, signal }) {
+    // 调用应用自己的 API，并映射为 CommentPage；不要把后端原始结构直接返回。
+    return api.listComments({ recordId: resourceKey, cursor, signal });
+  },
+  async create(
+    { resourceKey, threadId, replyToMessageId, content, attachments },
+    context,
+  ) {
+    return api.createComment(
+      {
+        recordId: resourceKey,
+        threadId,
+        replyToMessageId,
+        content,
+        attachments,
+      },
+      context,
+    );
+  },
+};
+```
+
+`api` 是应用自身代码，不是组件内置客户端。只有 list 就是只读；提供 create 才能新增/回复，update/remove 配合每条消息权限启用编辑/删除。不要用组件参数替代后端鉴权。
+
+- scopeKey 隔离提供方、租户和认证上下文，不含凭证；切换连接或权限身份时变化。hook 额外根据 resourceKey 和 currentUser 的完整引用隔离会话。推荐用 useMemo 或模块变量保持 adapter 稳定；同一 scope 的新对象本身不会反复加载。
+- list 返回 `{threads,nextCursor?}`；讨论包含 id/messages，第一条为正文。messages 使用字符串 ID 和毫秒时间。nextCursor 省略表示没有下一页，不自行生成游标。
+- 单个讨论未读全时返回 nextReplyCursor，并提供 listReplies，返回 `{messages,nextCursor?}`。hook 接管两层分页、去重、游标保护，以及刷新后保留已加载页数。
+- create/update 返回 `{threadId,messageId,message?}`，message 是可选权威回读。create 不传 threadId 表示新讨论；回复同时带 threadId 和精确 replyToMessageId，后端只支持线性讨论时可以忽略后者。
+- remove 接收选中消息 ID，包括首条。删除后第二条自然提升；返回 `{threadId,threadDeleted?}`，不能确定讨论是否为空就省略该字段，不凭局部列表推断。
+- hook 自动首屏读取；写入前丢弃旧读取，等并发写入完成再静默刷新。正常写后回读不触发整体 loading，刷新失败不反转已成功写入。`comments.refresh()` 是主动刷新，`comments.refreshing` 可供宿主显示后台读取状态。
+- 每次写操作收到 `{operationId,signal}`；同一次重试保持 operationId。确定未写入可抛 Error 并设置 outcome:'not-applied'；超时/回包丢失为 outcome:'unknown'，普通未标注异常也按未知处理，不能盲重发。
+- 服务支持客户端幂等标识时，adapter 将 context.operationId 写入并在读取消息上返回 clientOperationId，组件据此核对未知新增结果。没有服务端关联证据时不按正文去重，也不宣称能自动恢复所有未知结果。
+
+## 可选能力都放 adapter
+
+| 字段                        | 作用                                                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| people.source               | search/recommend/resolve；search 或 recommend 可用时启用 @；只有 resolve 时只补展示资料                                  |
+| people.canMention / onClick | 可选人员插入策略、人员卡片回调                                                                                           |
+| documents                   | `{source,canInsert?}`，注册后默认可插入；canInsert:false 只提供元数据解析                                                |
+| reactions                   | `{catalog?,allowedKeys?,onChange?}`，无 onChange 为只读，onChange 接收 resourceKey、threadId、messageId、key、add/remove |
+| images                      | 设 true 才启用文件选择；create/update 必须能上传并持久化完整消息，注册不会自动上传                                       |
+| links                       | 是否允许插入结构化普通链接，默认 false                                                                                   |
+| validateDraft               | 服务特有正文限制；返回错误文案或 undefined                                                                               |
+| getMessageLink              | 提供消息链接时显示复制链接菜单                                                                                           |
+
+catalog 项为 `{key,label,text?,url?,group?}`；不传时沿用现有表情资产。allowedKeys 同时约束快捷点击和选择列表。回应数据放 message.reactions，undefined 表示未读取、[] 表示权威为空、mine 省略表示本人状态未知，不根据截断人员名单推断 false。
+
+正文是 CommentContent，不是 Tiptap JSON 或服务 wire schema。读取遇到不支持的节点要保留为 unsupported 并禁用编辑。不能丢图片或未知节点后保存。禁用插入新引用时，编辑可原样保留已有引用，最终仍由 validateDraft/后端确认支持。
+
+用户引用当前为 `{kind:'user',namespace,id}`。不能把 open_id 当妙搭 userId；需要对接平台人员体系时在服务端 adapter 转换，统一目录、作者和 currentUser 的身份域。组件没有内置身份转换或 owner 权限兜底。
+
+## 高级受控方式继续可用
+
+已有 React Query、自有缓存或实时订阅时，可以继续传 `scopeKey/subjectKey/threads/actions/loading/error/pagination/actors/input/extensions` 等原始 props，详见 contracts.ts。该模式由宿主维护读取、分页和写入屏障，组件仍管理乐观覆盖。不要同时传 value 和受控 props，不再另建一套临时消息队列。
+
+原 `business-ui/record-comments` 的多维表格合同与数字 ID/秒级时间入口保留兼容；不能与新入口的类型混用。新通用入口仍共享原 UI 内部实现，未移动 CSS/assets。
+
+## 样式与验收
+
+项目入口需要模板自身的全局 `index.css`（Tailwind、主题与基础重置），组件会引入原内部 CSS。使用 hook 不改变任何视觉 token。
+
+真实 OpenAPI 验收示例位于仓库 `scripts/__tests__/fixtures/record-comments/openapi/`，使用同一个 useComments 入口。它是开发工具，不随模板运行时携带；运行中的应用不能 shell 执行 lark-cli 或把 token 放到浏览器。
 
-- `threads[].messages[]` 中第一条为正文。删除只针对选中消息；剩余消息原位提升，讨论 ID 不变。`canReply:false` 隐藏回复入口（例如 OpenAPI 整篇文档评论）。
-- ID 一律非空字符串；人员用 `{kind:'user',namespace,id}`，namespace 应包含提供方、应用及 ID 类型。不能把 `ou_...` 转数字。时间为毫秒，缺 `updatedAt` 可以正常展示，不伪造编辑时间。
-- 读取、权限、分页、缓存和认证在宿主。加载更多通过外部 `pagination.onLoadMore` / `repliesPagination` 请求。权限未知就不显示修改入口；后端仍须鉴权。
-- `actions.create/update` 返回真实 `{threadId,messageId,message?}`。可选 message 为权威回读，用于接管乐观内容。`remove` 返回 `{threadId,threadDeleted?}`，缺少讨论状态时等待外部回读，不凭局部列表为空认定整串删除。
-- 写成功就 resolve；后续刷新失败不能把成功写入 reject。确定未写入的失败可抛 `{outcome:'not-applied'}`；超时/响应丢失等抛 `{outcome:'unknown'}`，不能盲目重发。`context.operationId` 在一次重试中稳定，但宿主只有下游确实支持时才能把它当幂等保证。
-- 外部读取需要请求序号和写入屏障：忽略写入前开始的过期读取。组件无法判断任意新数组是否更新，也不能独自解决远端最终一致性。
-- 作者快照可只有 ref；姓名缺失交 `actors.resolve`。开启输入 @ 要同时提供目录及 `input.userMentions` 策略；自己回复不自动插入本人 @。
-- 文档用 `commentDocuments({source,canInsert:true})`；source 负责解析 URL、搜索和权限状态。普通链接受 `input.links` 控制。无法解析、未授权、无权限是不同结果，不能把解析失败标成无权限。
-- 回应用 `commentReactions({allowedKeys,onChange})`。`reactions:undefined` 表示未加载，`[]` 表示已知为空，`mine:undefined` 表示本人状态未知，不根据截断名单推断 false。此次 pilot 在任意回应 membership 未知时保守禁用该消息的回应修改；写入结果未知时保留本地状态并锁定，等待权威回读确认。
-- `commentImages()` 只启用选择 UI，不提供上传。宿主自行完成上传、持久化和授权，再在 create/update 返回完整消息。此 OpenAPI 试接入没有图片功能；通用文件附件暂不编辑，避免丢失内容。
+本地完整能力示例在同级测试目录 `memory/`：用独立 adapter 验收人员选择、混合图片回复、文档、表情、确定失败重试和未知结果核对；图片仅在本地持久化，不代表 OpenAPI 图片接入。
 
-真实 OpenAPI 示例和验收工具在 `scripts/__tests__/fixtures/record-comments/openapi/`（仓库测试资产，不随模板运行时携带）。不要让部署后的应用执行 lark-cli，也不要把 token/app secret 放到浏览器。生产应用用自己的后端 OAuth/OpenAPI SDK 替换示例 request。
+多维表格插件的真实应用 adapter 示例位于 `scripts/__tests__/fixtures/record-comments/bitable/`，使用与 OpenAPI 相同的 useComments 接口，保留服务自身身份域和权限。

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

@@ -1,5 +1,7 @@
 import type {
   CommentsProviderProps,
+  CommentsProviderInput,
+  CommentPanelInput,
   CommentThread,
   CommentContent,
   CommentDraft,
@@ -85,7 +87,11 @@ const reactionState = (items: CommentReaction[]) =>
   );
 const key = (ref: EntityRef) =>
   JSON.stringify([ref.kind, ref.namespace, ref.id]);
-export function CommentsProvider(props: CommentsProviderProps) {
+export function CommentsProvider(input: CommentsProviderInput) {
+  const props: CommentsProviderProps =
+    input.value !== undefined
+      ? { ...input.value.props, children: input.children }
+      : (input as CommentsProviderProps);
   return (
     <Session
       key={JSON.stringify([props.scopeKey, props.subjectKey])}
@@ -267,6 +273,7 @@ function Session(props: CommentsProviderProps) {
     );
     return {
       replyID: m.id,
+      clientOperationId: m.clientOperationId,
       author: m.author ? toRef(m.author.ref) : null,
       createTime: m.createdAt / 1000,
       updateTime: m.updatedAt === undefined ? undefined : m.updatedAt / 1000,
@@ -359,13 +366,33 @@ function Session(props: CommentsProviderProps) {
             },
       ),
     };
+    const signature = (n: import('./contracts').CommentNode) =>
+      n.type === 'link'
+        ? JSON.stringify(['link', n.url])
+        : n.type === 'mention'
+          ? JSON.stringify(['mention', key(n.ref), n.href ?? ''])
+          : '';
+    const retained = new Map<string, number>();
+    if (mode === 'update')
+      for (const n of latest.current.threads
+        .find((t) => t.id === target.threadId)
+        ?.messages.find((m) => m.id === target.messageId)?.content.nodes ??
+        []) {
+        const k = signature(n);
+        if (k) retained.set(k, (retained.get(k) ?? 0) + 1);
+      }
     for (const n of result.content.nodes) {
-      if (n.type === 'link' && !latest.current.input?.links)
+      const k = signature(n),
+        remaining = retained.get(k) ?? 0;
+      const existing = remaining > 0;
+      if (existing) retained.set(k, remaining - 1);
+      if (n.type === 'link' && !latest.current.input?.links && !existing)
         throw fail('当前接口不支持结构化链接');
       if (
         n.type === 'mention' &&
         n.ref.kind === 'document' &&
-        !documents?.canInsert
+        !documents?.canInsert &&
+        !existing
       )
         throw fail('当前接口不支持插入文档引用');
       if (n.type === 'unresolved-mention' || n.type === 'unsupported')
@@ -373,7 +400,8 @@ function Session(props: CommentsProviderProps) {
       if (
         n.type === 'mention' &&
         n.ref.kind === 'user' &&
-        !latest.current.input?.userMentions?.(n.ref as UserRef)
+        !latest.current.input?.userMentions?.(n.ref as UserRef) &&
+        !existing
       )
         throw fail('当前接口不支持此人员引用');
     }
@@ -413,13 +441,16 @@ function Session(props: CommentsProviderProps) {
         canMentionUser: (r) =>
           r.kind === 'user' &&
           Boolean(latest.current.input?.userMentions?.(fromRef(r) as UserRef)),
-        reactionEmojis: reactions?.options.allowedKeys
-          ? DEFAULT_REACTION_EMOJIS.filter((e) =>
-              reactions.options.allowedKeys!.includes(e.key),
+        reactionEmojis: reactions
+          ? (reactions.options.catalog ?? DEFAULT_REACTION_EMOJIS).filter(
+              (e) =>
+                !reactions.options.allowedKeys ||
+                reactions.options.allowedKeys.includes(e.key),
             )
           : undefined,
         showReactions: !!reactions,
         allowReact: !!reactions?.options.onChange,
+        enablePrivateComments: false,
         enableImages: images && !!props.actions?.create,
         enableEditImages: images && !!props.actions?.update,
         enableDocuments: documents?.canInsert ?? false,
@@ -477,11 +508,19 @@ function Session(props: CommentsProviderProps) {
                 await latest.current.actions!.create!(
                   {
                     ...input,
-                    ...(draft.commentID ? { threadId: draft.commentID } : {}),
+                    ...(draft.commentID
+                      ? {
+                          threadId: draft.commentID,
+                          ...(draft.replyToMessageId
+                            ? { replyToMessageId: draft.replyToMessageId }
+                            : {}),
+                        }
+                      : {}),
                   },
                   ctx,
                 ),
               ),
+            ctx.operationId,
           );
           setSubmitted(id);
         },
@@ -540,6 +579,11 @@ function Session(props: CommentsProviderProps) {
             !reactions?.options.onChange
           )
             throw fail('回应状态或权限未知');
+          if (
+            reactions.options.allowedKeys &&
+            !reactions.options.allowedKeys.includes(emoji)
+          )
+            throw fail('该表情未启用');
           const before = reactionOverlays.current.get(k)?.data ?? m.reactions;
           const old = before.find((r) => r.key === emoji);
           const action = old?.mine ? 'remove' : 'add';
@@ -615,7 +659,7 @@ function Session(props: CommentsProviderProps) {
     </DiscussionProvider>
   );
 }
-export function CommentPanel(props: Omit<CommentsProviderProps, 'children'>) {
+export function CommentPanel(props: CommentPanelInput) {
   return (
     <CommentsProvider {...props}>
       <div className="replica-comment-panel">

package/template/client/src/components/business-ui/comments/contracts.ts

@@ -40,6 +40,8 @@ export interface CommentReaction {
   previewUsers?: CommentAuthor[];
 }
 export interface CommentMessage {
+  /** Optional server-echoed idempotency correlation; never synthesize from matching text. */
+  clientOperationId?: string;
   id: string;
   author: CommentAuthor | null;
   content: CommentContent;
@@ -80,7 +82,7 @@ export interface CommentWriteResult extends CommentTarget {
 }
 export interface CommentActions {
   create?(
-    input: CommentDraft & { threadId?: string },
+    input: CommentDraft & { threadId?: string; replyToMessageId?: string },
     context: CommentMutationContext,
   ): Promise<CommentWriteResult>;
   update?(
@@ -119,7 +121,15 @@ export interface CommentEntitySource {
   ): Promise<CommentEntityResult[]>;
   parseUrl?(url: string): EntityRef | undefined;
 }
+export interface CommentEmoji {
+  key: string;
+  label: string;
+  text?: string;
+  url?: string;
+  group?: string;
+}
 export interface CommentReactionFeature {
+  catalog?: readonly CommentEmoji[];
   allowedKeys?: readonly string[];
   onChange?(
     input: CommentTarget & { key: string; action: 'add' | 'remove' },
@@ -163,3 +173,84 @@ export type CommentComposerProps = CommentListProps & {
   placeholder?: string;
   disabled?: boolean;
 };
+
+/** Adapter reads return data and cursors, never React callbacks or loading state. */
+export type CommentPageThread = Omit<CommentThread, 'repliesPagination'> & {
+  nextReplyCursor?: string;
+};
+export interface CommentPage {
+  threads: CommentPageThread[];
+  nextCursor?: string;
+}
+export interface CommentRepliesPage {
+  messages: CommentMessage[];
+  nextCursor?: string;
+}
+export interface CommentResource {
+  resourceKey: string;
+}
+export interface CommentListRequest extends CommentResource {
+  cursor?: string;
+  signal: AbortSignal;
+}
+export interface CommentAdapter {
+  /** Stable backend/tenant/auth scope. Current-user identity is additionally isolated by the hook. */
+  scopeKey: string;
+  list(input: CommentListRequest): Promise<CommentPage>;
+  listReplies?(
+    input: CommentListRequest & { threadId: string },
+  ): Promise<CommentRepliesPage>;
+  create?(
+    input: CommentDraft &
+      CommentResource & { threadId?: string; replyToMessageId?: string },
+    context: CommentMutationContext,
+  ): Promise<CommentWriteResult>;
+  update?(
+    input: CommentDraft & CommentTarget & CommentResource,
+    context: CommentMutationContext,
+  ): Promise<CommentWriteResult>;
+  remove?(
+    input: CommentTarget & CommentResource,
+    context: CommentMutationContext,
+  ): Promise<{ threadId: string; threadDeleted?: boolean }>;
+  people?: {
+    source: CommentEntitySource;
+    canMention?: (ref: UserRef) => boolean;
+    onClick?: CommentsProviderProps['onActorClick'];
+  };
+  documents?: { source: CommentEntitySource; canInsert?: boolean };
+  reactions?: Omit<CommentReactionFeature, 'onChange'> & {
+    onChange?(
+      input: CommentTarget &
+        CommentResource & { key: string; action: 'add' | 'remove' },
+      context: CommentMutationContext,
+    ): Promise<{ reactions?: CommentReaction[] }>;
+  };
+  /** Enable only when create/update can persist the complete image-bearing message. */
+  images?: boolean;
+  links?: boolean;
+  getMessageLink?(target: CommentTarget & CommentResource): string | undefined;
+  validateDraft?: CommentsProviderProps['validateDraft'];
+}
+export interface UseCommentsOptions {
+  resourceKey: string;
+  currentUser?: CommentAuthor;
+  adapter: CommentAdapter;
+}
+export interface CommentsController {
+  readonly props: Omit<CommentsProviderProps, 'children'>;
+  readonly refreshing: boolean;
+  refresh(): Promise<void>;
+  loadMore(): Promise<void>;
+}
+type ManagedInput<Controlled> = { value: CommentsController } & {
+  [K in keyof Controlled]?: never;
+};
+export type CommentsProviderInput =
+  | (CommentsProviderProps & { value?: never })
+  | (ManagedInput<Omit<CommentsProviderProps, 'children'>> & {
+      children: ReactNode;
+    });
+export type CommentPanelInput =
+  | (Omit<CommentsProviderProps, 'children'> & { value?: never })
+  | ManagedInput<Omit<CommentsProviderProps, 'children'>>;

package/template/client/src/components/business-ui/comments/index.ts

@@ -1,3 +1,4 @@
+export { useComments } from './use-comments';
 export { CommentsProvider, CommentPanel } from './comments';
 export { CommentList, CommentComposer } from '../record-comments/comment-panel';
 export type * from './contracts';

package/template/client/src/components/business-ui/comments/use-comments.ts

@@ -0,0 +1,492 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+import type {
+  CommentAdapter,
+  CommentActions,
+  CommentsController,
+  CommentExtension,
+  CommentMessage,
+  CommentPageThread,
+  CommentPagination,
+  CommentMutationContext,
+  UseCommentsOptions,
+} from './contracts';
+
+type ReadState = {
+  threads: CommentPageThread[];
+  loading: boolean;
+  refreshing: boolean;
+  error?: string;
+  nextCursor?: string;
+  moreLoading: boolean;
+  moreError?: string;
+  replyBusy: Set<string>;
+  replyErrors: Map<string, string>;
+};
+const message = (e: unknown) =>
+  e instanceof Error ? e.message : '评论读取失败';
+const failure = (text: string) =>
+  Object.assign(new Error(text), { outcome: 'not-applied' });
+const mergeMessages = (a: CommentMessage[], b: CommentMessage[]) => [
+  ...new Map([...a, ...b].map((m) => [m.id, m])).values(),
+];
+const mergeThreads = (
+  a: CommentPageThread[],
+  b: CommentPageThread[],
+  keepReplyProgress = false,
+) => {
+  const map = new Map(a.map((t) => [t.id, t]));
+  for (const t of b) {
+    const old = map.get(t.id);
+    map.set(
+      t.id,
+      old
+        ? {
+            ...t,
+            messages: mergeMessages(old.messages, t.messages),
+            ...(keepReplyProgress
+              ? { nextReplyCursor: old.nextReplyCursor }
+              : {}),
+          }
+        : t,
+    );
+  }
+  return [...map.values()];
+};
+/** Read orchestration only. The Provider remains the sole optimistic-mutation owner. */
+class ReadSession {
+  adapter: CommentAdapter;
+  private state: ReadState = {
+    threads: [],
+    loading: true,
+    refreshing: false,
+    moreLoading: false,
+    replyBusy: new Set(),
+    replyErrors: new Map(),
+  };
+  private listeners = new Set<() => void>();
+  private readers = new Set<AbortController>();
+  private lifecycle = new AbortController();
+  private generation = 0;
+  private active = true;
+  private hasSnapshot = false;
+  private pages = 1;
+  private pageCursors = new Set<string>();
+  private replyCursors = new Map<string, Set<string>>();
+  private replyPages = new Map<string, number>();
+  private writes = 0;
+  private waiters = new Set<() => void>();
+  constructor(
+    adapter: CommentAdapter,
+    readonly resourceKey: string,
+  ) {
+    this.adapter = adapter;
+  }
+  subscribe = (fn: () => void) => {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  };
+  snapshot = () => this.state;
+  private patch(p: Partial<ReadState>) {
+    if (!this.active) return;
+    this.state = { ...this.state, ...p };
+    this.listeners.forEach((fn) => fn());
+  }
+  activate() {
+    this.active = true;
+    this.lifecycle = new AbortController();
+  }
+  dispose() {
+    this.active = false;
+    this.lifecycle.abort();
+    this.invalidate();
+    this.waiters.forEach((fn) => fn());
+    this.waiters.clear();
+  }
+  private invalidate() {
+    this.generation++;
+    this.readers.forEach((c) => c.abort());
+    this.readers.clear();
+  }
+  private reader() {
+    const c = new AbortController();
+    this.readers.add(c);
+    return c;
+  }
+  private valid(version: number) {
+    return this.active && version === this.generation && this.writes === 0;
+  }
+  private cursor(
+    next: string | undefined,
+    previous: string | undefined,
+    seen: Set<string>,
+  ) {
+    if (next && (next === previous || seen.has(next)))
+      throw new Error('评论分页游标未前进');
+    if (next) seen.add(next);
+  }
+  refresh = async (options: { background?: boolean } = {}) => {
+    while (this.active && this.writes) {
+      await new Promise<void>((resolve) => this.waiters.add(resolve));
+    }
+    if (!this.active) return;
+    this.invalidate();
+    const version = this.generation;
+    const c = this.reader();
+    this.patch({
+      loading: !options.background,
+      refreshing: this.hasSnapshot,
+      error: undefined,
+      moreLoading: false,
+      replyBusy: new Set(),
+    });
+    try {
+      const adapter = this.adapter;
+      let cursor: string | undefined;
+      let rows: CommentPageThread[] = [];
+      const seen = new Set<string>();
+      let count = 0;
+      do {
+        const page = await adapter.list({
+          resourceKey: this.resourceKey,
+          cursor,
+          signal: c.signal,
+        });
+        if (!this.valid(version)) return;
+        this.cursor(page.nextCursor, cursor, seen);
+        rows = mergeThreads(rows, page.threads);
+        cursor = page.nextCursor;
+        count++;
+      } while (cursor && count < this.pages);
+      const replyCursors = new Map<string, Set<string>>();
+      for (let i = 0; i < rows.length; i++) {
+        let t = rows[i];
+        let next = t.nextReplyCursor;
+        const seenReplies = new Set<string>();
+        if (next) seenReplies.add(next);
+        for (let n = 1; n < (this.replyPages.get(t.id) ?? 1) && next; n++) {
+          if (!adapter.listReplies)
+            throw new Error('adapter 返回回复游标但未提供 listReplies');
+          const p = await adapter.listReplies({
+            resourceKey: this.resourceKey,
+            threadId: t.id,
+            cursor: next,
+            signal: c.signal,
+          });
+          if (!this.valid(version)) return;
+          this.cursor(p.nextCursor, next, seenReplies);
+          t = {
+            ...t,
+            messages: mergeMessages(t.messages, p.messages),
+            nextReplyCursor: p.nextCursor,
+          };
+          next = p.nextCursor;
+        }
+        replyCursors.set(t.id, seenReplies);
+        rows[i] = t;
+      }
+      if (this.valid(version)) {
+        this.replyCursors = replyCursors;
+        this.pages = count;
+        this.pageCursors = seen;
+        this.hasSnapshot = true;
+        this.patch({
+          threads: rows,
+          nextCursor: cursor,
+          moreError: undefined,
+          replyErrors: new Map(),
+        });
+      }
+    } catch (e) {
+      if (this.valid(version)) {
+        this.patch({ error: message(e) });
+        throw e;
+      }
+    } finally {
+      this.readers.delete(c);
+      if (this.valid(version))
+        this.patch({ loading: false, refreshing: false });
+    }
+  };
+  loadMore = async () => {
+    if (
+      !this.active ||
+      this.writes ||
+      this.state.refreshing ||
+      this.state.loading ||
+      this.state.moreLoading ||
+      !this.state.nextCursor
+    )
+      return;
+    const cursor = this.state.nextCursor,
+      version = this.generation,
+      c = this.reader();
+    this.patch({ moreLoading: true, moreError: undefined });
+    try {
+      const page = await this.adapter.list({
+        resourceKey: this.resourceKey,
+        cursor,
+        signal: c.signal,
+      });
+      if (!this.valid(version)) return;
+      this.cursor(page.nextCursor, cursor, this.pageCursors);
+      this.pages++;
+      this.patch({
+        threads: mergeThreads(this.state.threads, page.threads, true),
+        nextCursor: page.nextCursor,
+      });
+    } catch (e) {
+      if (this.valid(version)) {
+        this.patch({ moreError: message(e) });
+        throw e;
+      }
+    } finally {
+      this.readers.delete(c);
+      if (this.valid(version)) this.patch({ moreLoading: false });
+    }
+  };
+  loadReplies = async (threadId: string) => {
+    const thread = this.state.threads.find((t) => t.id === threadId),
+      cursor = thread?.nextReplyCursor;
+    if (
+      !this.active ||
+      this.writes ||
+      this.state.loading ||
+      this.state.refreshing ||
+      this.state.replyBusy.has(threadId) ||
+      !cursor
+    )
+      return;
+    if (!this.adapter.listReplies)
+      throw new Error('adapter 返回回复游标但未提供 listReplies');
+    const version = this.generation,
+      c = this.reader(),
+      busy = new Set(this.state.replyBusy),
+      errors = new Map(this.state.replyErrors);
+    busy.add(threadId);
+    errors.delete(threadId);
+    this.patch({ replyBusy: busy, replyErrors: errors });
+    try {
+      const page = await this.adapter.listReplies({
+        resourceKey: this.resourceKey,
+        threadId,
+        cursor,
+        signal: c.signal,
+      });
+      if (!this.valid(version)) return;
+      const seen = new Set(this.replyCursors.get(threadId) ?? [cursor]);
+      this.cursor(page.nextCursor, cursor, seen);
+      this.replyCursors.set(threadId, seen);
+      this.replyPages.set(threadId, (this.replyPages.get(threadId) ?? 1) + 1);
+      this.patch({
+        threads: this.state.threads.map((t) =>
+          t.id === threadId
+            ? {
+                ...t,
+                messages: mergeMessages(t.messages, page.messages),
+                nextReplyCursor: page.nextCursor,
+              }
+            : t,
+        ),
+      });
+    } catch (e) {
+      if (this.valid(version)) {
+        const errors = new Map(this.state.replyErrors);
+        errors.set(threadId, message(e));
+        this.patch({ replyErrors: errors });
+        throw e;
+      }
+    } finally {
+      this.readers.delete(c);
+      if (this.valid(version)) {
+        const busy = new Set(this.state.replyBusy);
+        busy.delete(threadId);
+        this.patch({ replyBusy: busy });
+      }
+    }
+  };
+  async write<T>(
+    execute: (context: CommentMutationContext) => Promise<T>,
+    context: CommentMutationContext,
+  ): Promise<T> {
+    if (!this.active || context.signal.aborted) throw failure('评论会话已关闭');
+    this.writes++;
+    this.invalidate();
+    this.patch({
+      loading: false,
+      refreshing: false,
+      moreLoading: false,
+      replyBusy: new Set(),
+    });
+    const c = new AbortController(),
+      cancel = () => c.abort();
+    context.signal.addEventListener('abort', cancel, { once: true });
+    this.lifecycle.signal.addEventListener('abort', cancel, { once: true });
+    try {
+      return await execute({ ...context, signal: c.signal });
+    } finally {
+      context.signal.removeEventListener('abort', cancel);
+      this.lifecycle.signal.removeEventListener('abort', cancel);
+      this.writes--;
+      if (!this.writes) {
+        this.waiters.forEach((fn) => fn());
+        this.waiters.clear();
+        if (this.active)
+          void this.refresh({ background: true }).catch(() => {});
+      }
+    }
+  }
+}
+
+export function useComments({
+  resourceKey,
+  currentUser,
+  adapter,
+}: UseCommentsOptions): CommentsController {
+  if (!resourceKey || !adapter.scopeKey)
+    throw new Error('评论 resourceKey 和 adapter.scopeKey 不能为空');
+  const identity = currentUser
+    ? JSON.stringify([
+        currentUser.ref.kind,
+        currentUser.ref.namespace,
+        currentUser.ref.id,
+      ])
+    : '';
+  const session = useMemo(
+    () => new ReadSession(adapter, resourceKey),
+    [adapter.scopeKey, resourceKey, identity],
+  );
+  session.adapter = adapter;
+  const state = useSyncExternalStore(
+    session.subscribe,
+    session.snapshot,
+    session.snapshot,
+  );
+  useEffect(() => {
+    session.activate();
+    void session.refresh().catch(() => {});
+    return () => session.dispose();
+  }, [session]);
+  const actions: CommentActions = useMemo(
+    () => ({
+      ...(adapter.create
+        ? {
+            create: (input, ctx) =>
+              session.write(
+                (c) => session.adapter.create!({ ...input, resourceKey }, c),
+                ctx,
+              ),
+          }
+        : {}),
+      ...(adapter.update
+        ? {
+            update: (input, ctx) =>
+              session.write(
+                (c) => session.adapter.update!({ ...input, resourceKey }, c),
+                ctx,
+              ),
+          }
+        : {}),
+      ...(adapter.remove
+        ? {
+            remove: (input, ctx) =>
+              session.write(
+                (c) => session.adapter.remove!({ ...input, resourceKey }, c),
+                ctx,
+              ),
+          }
+        : {}),
+    }),
+    [
+      session,
+      Boolean(adapter.create),
+      Boolean(adapter.update),
+      Boolean(adapter.remove),
+    ],
+  );
+  const props = useMemo<CommentsController['props']>(() => {
+    const extensions: CommentExtension[] = [];
+    if (adapter.documents)
+      extensions.push({
+        type: 'documents',
+        source: adapter.documents.source,
+        canInsert: adapter.documents.canInsert ?? true,
+      });
+    if (adapter.images) extensions.push({ type: 'images' });
+    if (adapter.reactions)
+      extensions.push({
+        type: 'reactions',
+        options: {
+          ...adapter.reactions,
+          ...(adapter.reactions.onChange
+            ? {
+                onChange: (input, ctx) =>
+                  session.write(
+                    (c) =>
+                      session.adapter.reactions!.onChange!(
+                        { ...input, resourceKey },
+                        c,
+                      ),
+                    ctx,
+                  ),
+              }
+            : {}),
+        },
+      });
+    const people = adapter.people;
+    return {
+      scopeKey: JSON.stringify([adapter.scopeKey, identity]),
+      subjectKey: resourceKey,
+      currentUser,
+      threads: state.threads.map((t) => ({
+        ...t,
+        ...(t.nextReplyCursor
+          ? {
+              repliesPagination: {
+                hasMore: true,
+                loading: state.replyBusy.has(t.id),
+                error: state.replyErrors.get(t.id),
+                onLoadMore: () => session.loadReplies(t.id),
+              },
+            }
+          : {}),
+      })),
+      actions,
+      loading: state.loading,
+      error: state.error,
+      onRetry: session.refresh,
+      pagination: state.nextCursor
+        ? {
+            hasMore: true,
+            loading: state.moreLoading,
+            error: state.moreError,
+            onLoadMore: session.loadMore,
+          }
+        : undefined,
+      actors: people?.source,
+      input: {
+        links: adapter.links ?? false,
+        ...(people && (people.source.search || people.source.recommend)
+          ? { userMentions: people.canMention ?? (() => true) }
+          : {}),
+      },
+      extensions,
+      onActorClick: people?.onClick,
+      getMessageLink: adapter.getMessageLink
+        ? (target) =>
+            session.adapter.getMessageLink!({ ...target, resourceKey })
+        : undefined,
+      validateDraft: adapter.validateDraft,
+    };
+  }, [session, state, adapter, currentUser, identity, actions, resourceKey]);
+  return useMemo(
+    () => ({
+      props,
+      refreshing: state.refreshing,
+      refresh: session.refresh,
+      loadMore: session.loadMore,
+    }),
+    [props, state.refreshing, session],
+  );
+}

package/template/client/src/components/business-ui/record-comments/internal/composer.tsx

@@ -187,6 +187,7 @@ export function DiscussionComposer({
   replyMention,
   replyIntentKey,
   commentID,
+  replyToMessageId,
   onCancel,
   onSubmit,
   disabled,
@@ -202,6 +203,7 @@ export function DiscussionComposer({
   replyName?: string;
   replyIntentKey?: string;
   commentID?: string;
+  replyToMessageId?: string;
   replyMention?: Extract<CommentValue['content'][number], { type: 'mention' }>;
   onCancel?: () => void;
   onSubmit: (draft: DiscussionDraft) => Promise<void> | void;
@@ -280,7 +282,7 @@ export function DiscussionComposer({
       ownedUrls.current.delete(image.url),
     );
     try {
-      await onSubmit({ value, images, private: privateComment, commentID });
+      await onSubmit({ value, images, private: privateComment, commentID, replyToMessageId });
       if (!alive.current) return;
       setImages([]);
       setValue(emptyComment());

package/template/client/src/components/business-ui/record-comments/internal/discussion.tsx

@@ -329,6 +329,7 @@ function ReplyItem({
             )}
             <div className="replica-reactions">
               <CommentReactionList
+                emojis={panel.reactionEmojis}
                 replyId={comment.replyID}
                 reactions={comment.reactions}
                 onToggle={
@@ -500,7 +501,7 @@ export function DiscussionComposerView({ placeholder, disabled }: { placeholder?
   const name = replyTarget ? replyPerson?.status === 'resolved' ? replyPerson.label : '评论者' : undefined;
   const author = replyTarget?.reply.author;
   const mentionAuthor = author && (!panel.currentUser || mentionKey(author) !== mentionKey(panel.currentUser)) && (panel.canMentionUser?.(author) ?? true);
-  return <DiscussionComposer sessionKey="new" commentID={replyTarget?.commentID}
+  return <DiscussionComposer sessionKey="new" commentID={replyTarget?.commentID} replyToMessageId={replyTarget?.reply.replyID}
     replyIntentKey={replyTarget ? `${replyTarget.commentID}:${replyTarget.reply.replyID}:${replyRevision}` : undefined}
     replyMention={mentionAuthor && author ? { type: 'mention', ref: author,
       label: replyPerson?.status === 'resolved' ? replyPerson.label : undefined } : undefined}

package/template/client/src/components/business-ui/record-comments/internal/mutations.ts

@@ -15,6 +15,7 @@ interface Operation extends LocalCommentMutation {
   replyID: string;
   draft?: DiscussionDraft;
   author?: MentionRef;
+  operationId?: string;
   createTime: number;
   wholeThread?: boolean;
   deletionUnknown?: boolean;
@@ -61,13 +62,13 @@ export class CommentMutations {
     void this.run(operation);
     return operation.id;
   }
-  add(thread: DiscussionThread | undefined, draft: DiscussionDraft, author: MentionRef | undefined, execute: () => Promise<CommentIDs>) {
+  add(thread: DiscussionThread | undefined, draft: DiscussionDraft, author: MentionRef | undefined, execute: () => Promise<CommentIDs>, operationId?: string) {
     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,
+    return this.start({ id, operationId, 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 });
   }
@@ -126,6 +127,19 @@ export class CommentMutations {
     this.release(operation); this.changed();
   }
   private acknowledged(operation: Operation, base: readonly DiscussionThread[]) {
+    // Only a server-echoed operation ID can correlate a write whose response was lost.
+    if (operation.kind === 'add' && operation.operationId) {
+      const matches = base.flatMap(thread => thread.replies.filter(reply =>
+        reply.clientOperationId === operation.operationId &&
+        (!operation.draft?.commentID || thread.commentID === operation.draft.commentID) &&
+        (!operation.author || (reply.author && mentionKey(reply.author) === mentionKey(operation.author)))
+      ).map(reply => ({ thread, reply })));
+      if (matches.length === 1) {
+        operation.commentID = matches[0].thread.commentID;
+        operation.replyID = matches[0].reply.replyID;
+        return true;
+      }
+    }
     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;
@@ -145,7 +159,7 @@ export class CommentMutations {
   }
   reconcile(base: readonly DiscussionThread[]) {
     const finished = this.operations.filter((operation) => (operation.phase === 'confirmed' ||
-      (operation.phase === 'uncertain' && operation.kind !== 'add')) && this.acknowledged(operation, base));
+      (operation.phase === 'uncertain' && (operation.kind !== 'add' || Boolean(operation.operationId)))) && 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();

package/template/client/src/components/business-ui/record-comments/internal/reactions.tsx

@@ -21,6 +21,7 @@ export interface CommentReaction {
 }
 
 export interface CommentEmoji {
+  text?: string;
   key: string;
   label: string;
   group?: string;
@@ -55,10 +56,10 @@ export function CommentReactionEmoji({
         style={{ height: size, width: 'auto' }}
       />
     );
-  if (!entry)
+  if (emoji?.text || !entry)
     return (
       <span className="text-xs" role="img" aria-label={label}>
-        [{label}]
+        {emoji?.text || `[${label}]`}
       </span>
     );
   const [, , x, y, width, height] = entry;
@@ -273,6 +274,7 @@ export function CommentReactionEntry({
   const { store } = useMentionContext();
   const hover = useReactionHover();
   const keyboardOpen = useRef(false);
+  const quick = emojis.find(e=>e.key==='THUMBSUP') ?? emojis[0];
   useEffect(() => {
     onOpenChange?.(hover.open);
   }, [hover.open, onOpenChange]);
@@ -290,7 +292,7 @@ export function CommentReactionEntry({
           type="button"
           aria-label="表情回复"
           title="表情回复（点击点赞，悬停选择）"
-          disabled={disabled}
+          disabled={disabled || !quick}
           className={cn(
             COMMENT_THEME_CLASS,
             'inline-flex size-[14px] items-center justify-center text-[var(--subtle-foreground)] hover:text-foreground disabled:text-muted-foreground',
@@ -311,7 +313,7 @@ export function CommentReactionEntry({
             event.preventDefault();
             event.stopPropagation();
             hover.close();
-            onToggle('THUMBSUP');
+            if(quick)onToggle(quick.key);
           }}
         >
           <ReactionIcon />

package/template/client/src/components/business-ui/record-comments/internal/view-types.ts

@@ -16,6 +16,7 @@ export interface DiscussionReply {
   mutation?: LocalCommentMutation;
   mutationBlocked?: boolean;
   replyID: string;
+  clientOperationId?: string;
   author: MentionRef | null;
   link?: string;
   /** Explicit capabilities supplied by the host/backend, independent of display names. */
@@ -41,6 +42,7 @@ export interface DiscussionThread {
   replies: DiscussionReply[];
 }
 export interface DiscussionDraft {
+  replyToMessageId?: string;
   commentID?: string;
   value: CommentValue;
   images: DiscussionImage[];