@lark-apaas/coding-template-nestjs-react-fullstack 0.1.55-alpha.20261030085054 → 0.1.55-alpha.20261101050259

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.20261101050259",
   "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,83 @@
+# Record comments
+
+完整受控记录评论组件，入口 `CommentPanel`。公共合同见 `comment-panel.contract.ts`、`types.ts`，统一从 `index.ts` 导入；目录内 internal 实现、集中样式和 `assets/reaction-sprite.png` 必须整体分发。不依赖旧 comment 目录，不包含测试应用、插件实例或表格配置。模板已配置 React、Tiptap 3.20.0、floating-ui 及 ui primitives 依赖。
+
+组件管理现有样式、回复归属、编辑器、人员弹层、菜单、分页触发和乐观更新；评论 CRUD、身份、权限、插件调用、服务端缓存、分页游标、表情及文档请求由宿主提供。
+
+## Agent 接入与维护路径
+
+普通接入只读本说明和 `comment-panel.contract.ts`，从目录入口导入；人员/文档来源的详细类型按需查 `types.ts`。新增页面只在宿主 hook 中实现读取与写入，不需要遍历或修改内部编辑器。
+
+| 位置 | 职责 |
+| --- | --- |
+| `index.ts` | 唯一推荐导入入口：组件、公共类型、目录适配器和 URL 工具 |
+| `comment-panel.contract.ts` / `types.ts` | 评论受控接口及提及来源类型 |
+| `comment-panel.tsx` | 装配受控数据、分页和乐观更新 |
+| `app-source.ts` | 可选的妙搭人员目录适配器，不含评论 CRUD |
+| `internal/model.ts` / `mutations.ts` | 内容转换、命令校验、时间/提及规则、乐观更新状态 |
+| `internal/discussion.tsx` / `composer.tsx` | 评论展示、菜单、回复和输入区 |
+| `internal/editor.tsx` / `suggestions.tsx` / `mentions.tsx` | Tiptap、候选选择与引用解析缓存 |
+| `internal/content.tsx` / `icons.tsx` / `images.tsx` / `reactions.tsx` | 内容展示、图标、图片扩展和表情回应 |
+| `internal/view-types.ts` / `reaction-catalog.ts` / `styles.css` | 内部视图类型、静态表情数据、集中样式 |
+
+`internal/` 只由组件实现与组件测试引用；应用代码不深引其内部文件。文档适配器如需 URL 校验/识别，从入口（纯数据适配器也可从 `app-source.ts`）导入 `safeUrl/documentRefFromUrl`。样式由 `CommentPanel` 一次加载，分发时保留整个目录和 assets；不需要逐个导入 CSS。修复内部行为时沿上表定位一个职责，不为每个小工具再拆文件。
+
+## 接入
+
+必填 `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 通过不能声称真实链路完成。
+
+人员提及悬浮沿用官方颜色：普通人员浅蓝底、自身蓝色胶囊变亮、无权限人员灰底。样式由 internal/styles.css 的组件专属类提供，不依赖宿主 accent 配色。
+
+
+## 交互接入约束
+
+宿主复用组件已有交互，不额外包装删除确认、成功 toast 或“已显示全部评论”提示。复制链接成功后只关闭菜单；编辑操作按钮保持“确认”，等待态不新增“保存中”文字。回复自己也会插入自身提及；未知作者不能伪造提及。保持人员搜索和提及悬浮样式，不用宿主全局 button/a/p 样式覆盖组件。
+
+保留读写失败的恢复入口和无障碍状态；未知写入结果不得开放盲目重试。新增提示或改变状态流前，应取得官方对应状态的操作证据；本地受控故障测试不等同于真实 Action 验收，未覆盖的权限/网络/图片能力需明确标注。
+
+
+初始无数据时，加载、空态和读取错误共用同一个 118px 状态占位（沿用原空态高度），长错误在占位内滚动；状态切换不会移动输入框。已有评论的后台读取错误保留列表并使用紧凑提示。宿主仍控制整体 height/maxHeight，不需要为三种状态分别补高度。重试失败后，外部 error 清除会同时清理旧的重试错误。
+
+空列表的分页提示也计入同一个读取占位区；后续页耗尽不会额外收缩面板。受限高度容器中该区域可随可用空间收缩，长分页错误在区域内滚动。
+
+若宿主在身份或权限查询完成后才提供写回调，输入框会稍后挂载；宿主可通过 `style={{ minHeight: 'min(250px, 60vh)', maxHeight: '60vh' }}` 预留整体空间，避免身份加载引起的高度变化。不要为占位提前开放写入能力。

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

@@ -1,12 +1,7 @@
-import { listUsersByIds, searchUsers } from '../api/users/service';
+import type { CommentDataSource, CommentDocumentSource, MentionOption, MentionResult } from './types';
+import { mentionKey } from './internal/model';
 import { getI18nText } from '../utils/user';
-import { mentionKey } from './content';
-import type {
-  CommentDataSource,
-  CommentDocumentSource,
-  MentionOption,
-  MentionResult,
-} from './types';
+import { listUsersByIds, searchUsers } from '../api/users/service';
 
 function avatarUrl(avatar: unknown): string | undefined {
   if (typeof avatar === 'string') return avatar;
@@ -50,6 +45,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 +81,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 +123,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'),
@@ -173,3 +178,5 @@ export function withDocumentSource(
     },
   };
 }
+
+export { documentRefFromUrl, safeUrl } from './internal/model';

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

@@ -0,0 +1,223 @@
+import type { CommentDataSource, CommentMentionClickHandler } from './types';
+import type { CSSProperties } from 'react';
+
+/**
+ * Public contract for the controlled CommentPanel entry point.
+ * Requests, credentials, pagination cursors and server caches belong to the host.
+ * The panel owns optimistic drafts and per-message mutation state.
+ */
+
+
+
+
+export type CommentReadContent =
+  | { type: 'text'; text: string }
+  | { type: 'mention'; userID?: number }
+  | { type: 'link'; url: string };
+
+export type CommentWriteContent =
+  | { type: 'text'; text: string }
+  | { type: 'mention'; userID: number }
+  | { type: 'link'; url: string };
+
+export interface RecordCommentReply {
+  replyID: string;
+  creator?: number;
+  /** Unix seconds, not milliseconds. */
+  createTime: number;
+  /** Authoritative per-reply last update, Unix seconds. Omit when unavailable. */
+  updateTime?: number;
+  content: CommentReadContent[];
+  /** Omission means reactions were not loaded or are unavailable in this identity mode. */
+  reactions?: Array<{ key: string; count: number; mine: boolean; userIDs: number[] }>;
+}
+
+export interface RecordComment {
+  commentID: string;
+  creator?: number;
+  createTime: number;
+  isSolved: boolean;
+  /** First reply is the body; subsequent replies belong to the same discussion. */
+  replies: RecordCommentReply[];
+}
+
+export interface ListRecordCommentsInput {
+  recordID: string;
+  commentID?: string;
+  needReaction?: boolean;
+  pageSize?: number;
+  pageToken?: string;
+}
+
+export interface RecordCommentPage {
+  comments: RecordComment[];
+  hasMore: boolean;
+  pageToken: string;
+}
+
+export interface AddRecordCommentInput {
+  recordID: string;
+  /** Omit for a new discussion. Never send an empty string. */
+  commentID?: string;
+  content: CommentWriteContent[];
+}
+
+export interface UpdateRecordCommentInput {
+  recordID: string;
+  commentID: string;
+  replyID: string;
+  content: CommentWriteContent[];
+}
+
+export interface DeleteRecordCommentInput {
+  recordID: string;
+  commentID: string;
+  /** Always supplied by the panel to delete one message, including the body.
+   * Omission is a legacy explicit whole-discussion command for external callers. */
+  replyID?: string;
+}
+
+export interface CommentIDs {
+  commentID: string;
+  replyID: string;
+}
+
+export interface DeleteCommentResult {
+  commentID: string;
+  commentDeleted: boolean;
+}
+
+export interface CommentTarget {
+  recordID: string;
+  commentID: string;
+  replyID: string;
+}
+
+export interface CommentPermissionContext extends CommentTarget {
+  comment: RecordComment;
+  reply: RecordCommentReply;
+  isBody: boolean;
+}
+
+export interface CommentPagination {
+  hasMore: boolean;
+  /** Host state, in addition to the panel's immediate in-flight guard. */
+  loading?: boolean;
+  /** An external page-load failure. Does not replace already loaded comments. */
+  error?: string;
+  /** Append to comments before resolving; reject on failure. Cursors stay outside. */
+  onLoadMore: () => Promise<void>;
+}
+
+export interface CommentReaction {
+  emojiKey: string;
+  count: number;
+  /** Authoritative membership. Never infer this from a truncated users list. */
+  reactedByMe: boolean;
+  previewUserIDs?: readonly number[];
+}
+
+export interface ChangeCommentReactionInput extends CommentTarget {
+  emojiKey: string;
+  action: 'add' | 'remove';
+}
+
+export interface CommentReactionFeature {
+  canChange?: (target: CommentTarget) => boolean;
+  getReactions: (target: CommentTarget) => readonly CommentReaction[];
+  /** Host updates its controlled reaction data before resolving. */
+  onChange?: (input: ChangeCommentReactionInput) => Promise<void>;
+  /** Optional paginated users; an absent loader means no complete-members claim. */
+  loadUsers?: (
+    input: CommentTarget & { emojiKey: string; cursor?: string },
+    signal: AbortSignal,
+  ) => Promise<{ userIDs: number[]; nextCursor?: string }>;
+}
+
+export interface CommentImage {
+  id: string;
+  url: string;
+  name?: string;
+  width?: number;
+  height?: number;
+}
+
+/** A retained image or a newly selected local file. Never a Bitable Action element. */
+export type CommentImageInput =
+  | { kind: 'existing'; image: CommentImage }
+  | { kind: 'local'; localID: string; file: File };
+
+/** Separate image-bearing command: content may be empty when images are present. */
+export interface AddImageCommentInput {
+  recordID: string;
+  commentID?: string;
+  content: CommentWriteContent[];
+  images: readonly CommentImageInput[];
+}
+
+export interface UpdateImageCommentInput extends AddImageCommentInput {
+  commentID: string;
+  replyID: string;
+}
+
+export interface CommentImageFeature {
+  /** UI cannot derive images from the official plugin's empty content array. */
+  getImages: (target: CommentTarget) => readonly CommentImage[];
+  /** Enables file selection for new comments/replies. Owns the entire command. */
+  onAddComment?: (input: AddImageCommentInput) => Promise<CommentIDs>;
+  /** Required to edit an existing image-bearing reply without losing its images. */
+  onUpdateComment?: (input: UpdateImageCommentInput) => Promise<CommentIDs>;
+}
+
+/** Plain Error means a rejected write. Mark outcome=unknown for a timeout or
+ * transport failure that may have committed; the panel then prevents blind retry. */
+export interface CommentMutationFailure extends Error {
+  outcome?: 'not-applied' | 'unknown';
+}
+
+export interface CommentPanelProps {
+  /** Stable app/tenant/identity/data-source scope. No credentials. */
+  scopeKey: string;
+  recordID: string;
+  /** Controlled server data; the panel never mutates this array. */
+  comments: readonly RecordComment[];
+  /** Externally supplied @ lookup/resolution; contains no comment CRUD methods. */
+  mentionSource: CommentDataSource;
+  /** Enable document suggestions only with a user-authorized document source. Writes remain link elements. */
+  enableDocuments?: boolean;
+  /** Miaoda user ID; used for presentation, not authorization. */
+  currentUserID?: number;
+
+  /** Initial read is initiated by the host. */
+  loading?: boolean;
+  /** Initial/background read error; existing comments remain visible. */
+  error?: string;
+  onRetry?: () => Promise<void>;
+  /** Omit when the host has already supplied the entire list. */
+  pagination?: CommentPagination;
+
+  /** Resolve with real IDs on write success; comments may be updated later.
+   * The panel immediately renders a local overlay, owns pending/error/retry state,
+   * and reconciles it when matching controlled data arrives. Refresh failures must
+   * not reject a committed write. Mark ambiguous failures with outcome=unknown. */
+  onAddComment?: (input: AddRecordCommentInput) => Promise<CommentIDs>;
+  onUpdateComment?: (input: UpdateRecordCommentInput) => Promise<CommentIDs>;
+  onDeleteComment?: (input: DeleteRecordCommentInput) => Promise<DeleteCommentResult>;
+  /** Absent policy means edit/delete are hidden. Backend remains authoritative. */
+  getReplyPermissions?: (
+    context: CommentPermissionContext,
+  ) => { canEdit: boolean; canDelete: boolean };
+
+  /** Absent callback means no copy-link menu item. */
+  getCommentLink?: (target: CommentTarget) => string | undefined;
+  onMentionClick?: CommentMentionClickHandler;
+  /** All real/mocked extension requests are also supplied by the host. */
+  reactions?: CommentReactionFeature;
+  images?: CommentImageFeature;
+
+  /** Default: nearest scrollable ancestor of the bottom sentinel, else viewport. */
+  getScrollContainer?: () => HTMLElement | null;
+  className?: string;
+  /** Layout only; current internal design tokens and visual styles are preserved. */
+  style?: CSSProperties;
+}

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

@@ -0,0 +1,202 @@
+import type { CommentPanelProps, CommentTarget } from './comment-panel.contract';
+import { CommentMutations } from './internal/mutations';
+import { buildPanelThreads, CommentPageLoader, preparePanelDeletion, preparePanelEdit, loadPanelReactionDetails, preparePanelComment } from './internal/model';
+import { DiscussionPanel } from './internal/discussion';
+import { LoaderCircle } from 'lucide-react';
+import { useCallback, useEffect, useReducer, useRef, useState, useSyncExternalStore } from 'react';
+import './internal/styles.css';
+
+function ReadStatus({ loading, error, onRetry, empty, hasMore }: Pick<CommentPanelProps, 'loading' | 'error' | 'onRetry'> & { empty: boolean; hasMore?: boolean }) {
+  const [failure, setFailure] = useState('');
+  const [retrying, setRetrying] = useState(false);
+  const busy = useRef(false);
+  // A successful external read must clear a previous retry failure as well.
+  useEffect(() => setFailure(''), [error]);
+  const pending = loading || retrying;
+  const message = failure || error;
+  if (!empty && !pending && !message) return null;
+  const state = pending ? 'loading' : message ? 'error' : 'empty';
+  return <div className={`replica-panel-status${empty ? ' replica-panel-placeholder' : ''}`}
+    data-state={state} role={state === 'error' ? 'alert' : 'status'} aria-busy={pending}>
+    <div className="replica-panel-status-content">
+      <span>{pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载评论" />
+        : message || (empty && !hasMore ? '当前记录暂无评论' : null)}</span>
+      {!pending && message && onRetry && <button type="button" onClick={async () => {
+        if (busy.current) return;
+        busy.current = true; setRetrying(true); setFailure('');
+        try { await onRetry(); }
+        catch (cause) { setFailure(cause instanceof Error ? cause.message : '刷新失败，请重试'); }
+        finally { busy.current = false; setRetrying(false); }
+      }}>重试刷新</button>}
+    </div>
+  </div>;
+}
+
+function nearestScrollContainer(node: HTMLElement): HTMLElement | null {
+  for (let parent = node.parentElement; parent; parent = parent.parentElement) {
+    if (/(auto|scroll)/.test(getComputedStyle(parent).overflowY) && parent.clientHeight > 0) return parent;
+  }
+  return null;
+}
+
+function PaginationFooter({ pagination, loading, getScrollContainer }: Pick<CommentPanelProps, 'pagination' | 'loading' | 'getScrollContainer'>) {
+  const sentinel = useRef<HTMLDivElement>(null);
+  const root = useRef<HTMLElement | null>(null);
+  const [gate] = useState(() => new CommentPageLoader());
+  const [, refresh] = useReducer((value: number) => value + 1, 0);
+  const latest = useRef({ pagination, loading });
+  latest.current = { pagination, loading };
+  const alive = useRef(true);
+  const run = useRef((manual = false) => { void manual; });
+  run.current = (manual = false) => {
+    const current = latest.current;
+    if (!alive.current || current.loading || !current.pagination?.hasMore || current.pagination.loading || gate.pending) return;
+    if (!manual && (gate.error || current.pagination.error || gate.automaticLoads >= 3)) return;
+    const promise = gate.load(current.pagination, manual);
+    refresh();
+    void promise.finally(() => { if (alive.current) refresh(); });
+  };
+  const check = useCallback(() => {
+    const element = sentinel.current;
+    if (!element) return;
+    const bounds = element.getBoundingClientRect();
+    const viewport = root.current?.getBoundingClientRect();
+    const visibleTop = Math.max(0, viewport?.top ?? 0);
+    const visibleBottom = Math.min(window.innerHeight, viewport?.bottom ?? window.innerHeight);
+    if (visibleBottom > visibleTop && bounds.top <= visibleBottom + 200 && bounds.bottom >= visibleTop)
+      run.current();
+  }, []);
+  useEffect(() => {
+    alive.current = true;
+    const element = sentinel.current;
+    if (!element) return;
+    root.current = getScrollContainer ? getScrollContainer() : nearestScrollContainer(element);
+    const container = root.current ?? window;
+    const observer = new IntersectionObserver(() => check(), { root: root.current, rootMargin: '0px 0px 200px 0px' });
+    observer.observe(element);
+    const resize = new ResizeObserver(check);
+    resize.observe(root.current ?? document.documentElement);
+    const resume = (event: Event) => {
+      if (event instanceof WheelEvent && event.deltaY > 0) gate.automaticLoads = 0;
+      if (event instanceof KeyboardEvent && ['PageDown', 'End', 'ArrowDown'].includes(event.key)) gate.automaticLoads = 0;
+      check();
+    };
+    container.addEventListener('scroll', check, { passive: true });
+    if (root.current) window.addEventListener('scroll', check, { passive: true });
+    container.addEventListener('wheel', resume, { passive: true });
+    container.addEventListener('keydown', resume);
+    return () => {
+      alive.current = false;
+      observer.disconnect(); resize.disconnect();
+      container.removeEventListener('scroll', check);
+      window.removeEventListener('scroll', check);
+      container.removeEventListener('wheel', resume);
+      container.removeEventListener('keydown', resume);
+    };
+  }, [check, gate, getScrollContainer]);
+  useEffect(() => {
+    const frame = requestAnimationFrame(check);
+    return () => cancelAnimationFrame(frame);
+  });
+  const error = pagination?.hasMore && (gate.error || pagination.error);
+  const pending = gate.pending || pagination?.loading;
+  return <div ref={sentinel} className={pagination?.hasMore ? 'replica-panel-pagination' : undefined} aria-live="polite">
+    {pagination?.hasMore && (error ? <><span role="alert">{error}</span><button type="button" disabled={pending} onClick={() => run.current(true)}>重试加载</button></>
+      : pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载更多评论" />
+        : pagination?.hasMore ? <button type="button" disabled={loading} onClick={() => run.current(true)}>继续加载</button>
+          : null)}
+  </div>;
+}
+
+function PanelSession(props: CommentPanelProps) {
+  const latest = useRef(props);
+  latest.current = props;
+  const root = useRef<HTMLDivElement>(null);
+  const locks = useRef(new Set<string>());
+  const [submitted, setSubmitted] = useState<string>();
+  const [mutations] = useState(() => new CommentMutations());
+  useSyncExternalStore(mutations.subscribe, mutations.getVersion, mutations.getVersion);
+  const base = buildPanelThreads(props);
+  const comments = mutations.view(base);
+  useEffect(() => {
+    mutations.activate();
+    return () => mutations.dispose();
+  }, [mutations]);
+  useEffect(() => { mutations.reconcile(base); }, [base, mutations]);
+  useEffect(() => {
+    if (!submitted) return;
+    const target = root.current?.querySelector(`[data-reply-id="${CSS.escape(mutations.replyID(submitted))}"]`);
+    if (target) { target.scrollIntoView({ block: 'nearest', behavior: 'smooth' }); setSubmitted(undefined); }
+  }, [comments, submitted, mutations]);
+  async function locked<T>(key: string, action: () => Promise<T>): Promise<T> {
+    if (locks.current.has(key)) throw new Error('该评论正在处理中，请稍后重试');
+    locks.current.add(key);
+    try { return await action(); }
+    finally { locks.current.delete(key); }
+  }
+  const allowCompose = Boolean(props.onAddComment || props.images?.onAddComment);
+  const currentUser = props.currentUserID == null ? undefined
+    : { kind: 'user' as const, idType: 'apaas-user' as const, id: String(props.currentUserID) };
+  return <div ref={root} className={`replica-comment-panel ${props.className ?? ''}`} style={props.style}>
+    <DiscussionPanel
+      source={props.mentionSource}
+      currentUser={currentUser}
+      comments={comments}
+      allowCompose={allowCompose}
+      optimisticMutations
+      onRetryMutation={(id) => mutations.retry(id)}
+      showReactions={Boolean(props.reactions)}
+      allowReact={Boolean(props.reactions?.onChange)}
+      enableImages={Boolean(props.images?.onAddComment)}
+      enableEditImages={Boolean(props.images?.onUpdateComment)}
+      enablePrivateComments={false}
+      enableDocuments={props.enableDocuments ?? false}
+      autoScrollNewReplies={false}
+      emptyState={null}
+      listHeader={<ReadStatus loading={props.loading} error={props.error} onRetry={props.onRetry}
+        empty={!comments.some((thread) => thread.replies.length > 0)} hasMore={props.pagination?.hasMore} />}
+      listFooter={props.pagination && <PaginationFooter pagination={props.pagination} loading={props.loading || Boolean(props.error)} getScrollContainer={props.getScrollContainer} />}
+      onMentionClick={props.onMentionClick}
+      getCommentLink={(commentID, reply) => props.getCommentLink?.({ recordID: props.recordID, commentID, replyID: reply.replyID }) ?? ''}
+      onSubmit={(draft) => {
+        const current = latest.current;
+        preparePanelComment(current, draft); // Validate before accepting/clearing the draft.
+        const thread = base.find((item) => item.commentID === draft.commentID);
+        const id = mutations.add(thread, draft, currentUser, () => preparePanelComment(latest.current, draft)());
+        setSubmitted(id);
+      }}
+      onEdit={(commentID, replyID, value, images) => {
+        const draft = { value, images, private: false };
+        preparePanelEdit(latest.current, commentID, replyID, draft);
+        const thread = base.find((item) => item.commentID === commentID)!;
+        mutations.edit(thread, replyID, draft, () => preparePanelEdit(latest.current, commentID, replyID, draft)());
+      }}
+      onDelete={(commentID, replyID) => {
+        if (!replyID) throw new Error('未选择要删除的评论');
+        preparePanelDeletion(latest.current, commentID, replyID);
+        const thread = base.find((item) => item.commentID === commentID)!;
+        mutations.delete(thread, replyID, () => preparePanelDeletion(latest.current, commentID, replyID)());
+      }}
+      onToggleReaction={async (commentID, replyID, emojiKey) => {
+        await locked(replyID, async () => {
+          const current = latest.current;
+          const feature = current.reactions;
+          if (!feature?.onChange) throw new Error('未提供回应写入能力');
+          const target: CommentTarget = { recordID: current.recordID, commentID, replyID };
+          if (feature.canChange?.(target) === false) throw new Error('表情状态尚未加载或当前身份不可用');
+          const existing = feature.getReactions(target).find((reaction) => reaction.emojiKey === emojiKey ||
+            (emojiKey === 'THUMBSUP' && reaction.emojiKey === 'MediumThumbsup'));
+          await feature.onChange({ ...target, emojiKey: existing?.emojiKey ?? emojiKey, action: existing?.reactedByMe ? 'remove' : 'add' });
+        });
+      }}
+      loadReactionDetails={props.reactions?.loadUsers ? (commentID, replyID, signal) => loadPanelReactionDetails(
+        latest.current, { recordID: props.recordID, commentID, replyID }, signal,
+      ) : undefined}
+    />
+  </div>;
+}
+
+/** Controlled full comment UI; all persistence is supplied by the host. */
+export function CommentPanel(props: CommentPanelProps) {
+  return <PanelSession key={JSON.stringify([props.scopeKey, props.recordID])} {...props} />;
+}

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

@@ -0,0 +1,7 @@
+export { CommentPanel } from './comment-panel';
+export { createAppCommentSource, withDocumentSource } from './app-source';
+export type * from './comment-panel.contract';
+export type { CommentDataSource, CommentDocumentSource, CommentMentionClickHandler, MentionRef, MentionOption, MentionResult, MentionKind, DocumentMentionMetadata } from './types';
+
+// URL helpers for external document adapters; no requests or permissions inside.
+export { documentRefFromUrl, safeUrl } from './internal/model';