@lark-apaas/coding-template-nestjs-react-fullstack 0.1.60-alpha.20261105085132 → 0.1.60-alpha.20261105123111

package/package.json

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

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

@@ -0,0 +1,36 @@
+# 通用评论入口（OpenAPI pilot）
+
+与 `record-comments` 共享 UI/CSS 和乐观更新逻辑。新的公开数据契约不包含 Action、插件实例或飞书数字用户 ID。旧入口继续兼容；此试接入不搬迁全部内部文件，不自动迁移应用。
+
+```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>
+```
+
+`CommentsProvider` 不输出布局 DOM。也可用 `CommentPanel` 提供默认完整布局。类型以 `contracts.ts` 为准。
+
+- `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 试接入没有图片功能；通用文件附件暂不编辑，避免丢失内容。
+
+真实 OpenAPI 示例和验收工具在 `scripts/__tests__/fixtures/record-comments/openapi/`（仓库测试资产，不随模板运行时携带）。不要让部署后的应用执行 lark-cli，也不要把 token/app secret 放到浏览器。生产应用用自己的后端 OAuth/OpenAPI SDK 替换示例 request。

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

@@ -0,0 +1,626 @@
+import type {
+  CommentsProviderProps,
+  CommentThread,
+  CommentContent,
+  CommentDraft,
+  EntityRef,
+  UserRef,
+  CommentEntitySource,
+  CommentReaction,
+  CommentTarget,
+  CommentWriteResult,
+  CommentMessage,
+} from './contracts';
+import type {
+  CommentDataSource,
+  CommentValue,
+  MentionRef,
+  MentionOption,
+} from '../record-comments/types';
+import type {
+  DiscussionThread,
+  DiscussionDraft,
+  DiscussionReply,
+} from '../record-comments/internal/view-types';
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { CommentMutations } from '../record-comments/internal/mutations';
+import {
+  DiscussionProvider,
+  DiscussionLayout,
+} from '../record-comments/internal/discussion';
+import { ReadStatus, PaginationFooter } from '../record-comments/comment-panel';
+import { withDocumentSource } from '../record-comments/extensions';
+import { DEFAULT_REACTION_EMOJIS } from '../record-comments/internal/reactions';
+import { normalizeValue } from '../record-comments/internal/model';
+
+// Encoding is private UI identity, not a backend ID conversion. Namespace stays lossless.
+const toRef = (ref: EntityRef): MentionRef => {
+  if (!ref.id || !ref.namespace) throw new Error('引用标识不能为空');
+  return ref.kind === 'user'
+    ? {
+        kind: 'user',
+        idType: 'generic',
+        id: JSON.stringify([ref.namespace, ref.id]),
+      }
+    : { kind: 'document', resourceType: ref.namespace, id: ref.id };
+};
+const fromRef = (ref: MentionRef): EntityRef => {
+  if (ref.kind === 'document')
+    return { kind: 'document', namespace: ref.resourceType, id: ref.id };
+  if (ref.idType !== 'generic')
+    return { kind: 'user', namespace: ref.idType, id: ref.id };
+  const [namespace, id] = JSON.parse(ref.id);
+  return { kind: 'user', namespace, id };
+};
+const value = (content: CommentContent): CommentValue =>
+  normalizeValue({
+    version: 1,
+    content: content.nodes.map((n) =>
+      n.type === 'mention'
+        ? { ...n, ref: toRef(n.ref) }
+        : n.type === 'unsupported'
+          ? { type: 'text', text: n.label }
+          : n,
+    ),
+  });
+const content = (v: CommentValue): CommentContent => ({
+  version: 1,
+  nodes: normalizeValue(v).content.map((n) =>
+    n.type === 'mention' ? { ...n, ref: fromRef(n.ref) } : n,
+  ),
+});
+const fail = (message: string) =>
+  Object.assign(new Error(message), { outcome: 'not-applied' });
+const reactionState = (items: CommentReaction[]) =>
+  JSON.stringify(
+    items
+      .map((r) => [r.key, r.count, r.mine])
+      .sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
+  );
+const key = (ref: EntityRef) =>
+  JSON.stringify([ref.kind, ref.namespace, ref.id]);
+export function CommentsProvider(props: CommentsProviderProps) {
+  return (
+    <Session
+      key={JSON.stringify([props.scopeKey, props.subjectKey])}
+      {...props}
+    />
+  );
+}
+function Session(props: CommentsProviderProps) {
+  const latest = useRef(props);
+  latest.current = props;
+  const [mutations] = useState(
+    () =>
+      new CommentMutations({
+        opaqueIDs: true,
+        unknownDeletion: true,
+        unknownErrors: true,
+        removePending: true,
+      }),
+  );
+  useSyncExternalStore(
+    mutations.subscribe,
+    mutations.getVersion,
+    mutations.getVersion,
+  );
+  useEffect(() => {
+    mutations.activate();
+    return () => mutations.dispose();
+  }, [mutations]);
+  const abort = useRef(new AbortController());
+  useEffect(() => {
+    const controller = new AbortController();
+    abort.current = controller;
+    return () => controller.abort();
+  }, []);
+  const context = () => ({
+    operationId: crypto.randomUUID(),
+    signal: abort.current.signal,
+  });
+  const extensions = new Map(props.extensions?.map((x) => [x.type, x]));
+  if (extensions.size !== (props.extensions?.length ?? 0))
+    throw new Error('同种评论扩展只能注册一次');
+  const documents = props.extensions?.find((x) => x.type === 'documents');
+  const reactions = props.extensions?.find((x) => x.type === 'reactions');
+  const images = extensions.has('images');
+  const names = useRef(new Map<string, MentionOption>());
+  names.current = new Map();
+  for (const author of [
+    props.currentUser,
+    ...props.threads.flatMap((t) =>
+      t.messages.flatMap((m) => [
+        m.author,
+        ...(m.reactions ?? []).flatMap((r) => r.previewUsers ?? []),
+      ]),
+    ),
+  ])
+    if (author?.name)
+      names.current.set(key(author.ref), {
+        ref: toRef(author.ref),
+        label: author.name || '用户',
+        avatarUrl: author.avatarUrl,
+      });
+  const source = useMemo(() => {
+    function wrap(
+      external: CommentEntitySource | undefined,
+      user: boolean,
+    ): CommentDataSource {
+      const option = (o: import('./contracts').CommentEntityOption) => ({
+        ...o,
+        ref: toRef(o.ref),
+      });
+      const allowed = (o: import('./contracts').CommentEntityOption) =>
+        o.ref.kind === 'user'
+          ? Boolean(latest.current.input?.userMentions?.(o.ref as UserRef))
+          : true;
+      return {
+        scopeKey: props.scopeKey + (user ? ':actors' : ':documents'),
+        allowLinks: props.input?.links ?? false,
+        search: async (args) => {
+          if (user && !latest.current.input?.userMentions) return { items: [] };
+          const result = await external?.search?.(args);
+          return {
+            items: (result?.items ?? []).filter(allowed).map(option),
+            nextCursor: result?.nextCursor,
+          };
+        },
+        ...(external?.recommend
+          ? {
+              recommend: async (args) => {
+                if (user && !latest.current.input?.userMentions)
+                  return { items: [] };
+                const r = await external.recommend!(args);
+                return {
+                  items: r.items.filter(allowed).map(option),
+                  nextCursor: r.nextCursor,
+                };
+              },
+            }
+          : {}),
+        parseLink: (url) => {
+          const ref = external?.parseUrl?.(url);
+          return ref
+            ? { type: 'mention', ref: toRef(ref), href: url }
+            : undefined;
+        },
+        resolve: async (refs, signal) => {
+          const found = new Map(
+            refs.flatMap((ref) => {
+              const r = names.current.get(key(fromRef(ref)));
+              return r
+                ? [
+                    [
+                      key(fromRef(ref)),
+                      { ...r, status: 'resolved' as const },
+                    ] as const,
+                  ]
+                : [];
+            }),
+          );
+          const missing = refs.filter((r) => !found.has(key(fromRef(r))));
+          if (missing.length && external)
+            for (const r of await external.resolve(
+              missing.map(fromRef),
+              signal,
+            ))
+              found.set(key(r.ref), { ...r, ref: toRef(r.ref) } as never);
+          signal.throwIfAborted();
+          return refs.map(
+            (ref) =>
+              found.get(key(fromRef(ref))) ?? { ref, status: 'error' as const },
+          );
+        },
+      };
+    }
+    const people = wrap(props.actors, true);
+    return documents
+      ? {
+          ...withDocumentSource(people, wrap(documents.source, false)),
+          allowLinks: props.input?.links ?? false,
+        }
+      : people;
+  }, [props.actors, props.scopeKey, props.input?.links, documents?.source]);
+  const [submitted, setSubmitted] = useState<string>();
+  const [reactionVersion, setReactionVersion] = useState(0);
+  const reactionOverlays = useRef(
+    new Map<
+      string,
+      {
+        data: CommentReaction[];
+        before: CommentReaction[];
+        confirmed: boolean;
+        uncertain?: boolean;
+        key: string;
+        action: 'add' | 'remove';
+      }
+    >(),
+  );
+  const reactionBusy = useRef(new Set<string>());
+  const reactKey = (target: CommentTarget) =>
+    JSON.stringify([target.threadId, target.messageId]);
+  const dataToReaction = (data: CommentReaction[]) =>
+    data
+      .filter((r) => r.count > 0)
+      .map((r) => ({
+        key: r.key,
+        count: r.count,
+        mine: r.mine === true,
+        users: (r.previewUsers ?? []).map((u) => toRef(u.ref).id),
+      }));
+  const toMessage = (m: CommentMessage, threadId: string): DiscussionReply => {
+    const target = { threadId, messageId: m.id };
+    const overlay = reactionOverlays.current.get(reactKey(target));
+    const canEdit = Boolean(
+      m.permissions?.edit &&
+      props.actions?.update &&
+      !m.content.nodes.some((n) => n.type === 'unsupported') &&
+      (!m.attachments?.length ||
+        (images &&
+          m.attachments.every((a) => a.kind === 'image' && Boolean(a.url)))),
+    );
+    return {
+      replyID: m.id,
+      author: m.author ? toRef(m.author.ref) : null,
+      createTime: m.createdAt / 1000,
+      updateTime: m.updatedAt === undefined ? undefined : m.updatedAt / 1000,
+      edited: m.edited || Boolean(m.updatedAt && m.updatedAt > m.createdAt),
+      value: value({
+        version: 1,
+        nodes: [
+          ...m.content.nodes,
+          ...(m.attachments ?? [])
+            .filter((a) => a.kind !== 'image' || !a.url)
+            .map((a) => ({
+              type: 'unsupported' as const,
+              label: `[附件暂未接入：${a.name}]`,
+            })),
+        ],
+      }),
+      images: (m.attachments ?? [])
+        .filter((a) => a.kind === 'image' && a.url)
+        .map((a) => ({ ...a, url: a.url! })),
+      reactions: dataToReaction(overlay?.data ?? m.reactions ?? []),
+      permissions: {
+        canEdit,
+        canDelete: Boolean(m.permissions?.delete && props.actions?.remove),
+        canCopyLink: Boolean(props.getMessageLink?.(target)),
+        canReact: Boolean(
+          reactions?.options.onChange &&
+          m.permissions?.react &&
+          !overlay?.uncertain &&
+          m.reactions !== undefined &&
+          !m.reactions.some((r) => r.mine === undefined),
+        ),
+      },
+    };
+  };
+  const base: DiscussionThread[] = props.threads.map((t) => ({
+    commentID: t.id,
+    canReply: t.canReply,
+    creator: t.messages[0]?.author ? toRef(t.messages[0].author.ref) : null,
+    createTime: (t.messages[0]?.createdAt ?? 0) / 1000,
+    isSolved: !!t.resolved,
+    listFooter: t.repliesPagination?.hasMore ? (
+      <PaginationFooter pagination={t.repliesPagination} />
+    ) : undefined,
+    replies: t.messages.map((m) => toMessage(m, t.id)),
+  }));
+  useEffect(() => {
+    mutations.reconcile(base);
+  });
+  useEffect(() => {
+    for (const [k, o] of reactionOverlays.current)
+      if (o.confirmed) {
+        const [tid, mid] = JSON.parse(k);
+        const data = props.threads
+          .find((t) => t.id === tid)
+          ?.messages.find((m) => m.id === mid)?.reactions;
+        if (
+          data &&
+          (reactionState(data) === reactionState(o.data) ||
+            (o.action === 'add'
+              ? data.find((r) => r.key === o.key)?.mine === true
+              : !data.some((r) => r.key === o.key) ||
+                data.find((r) => r.key === o.key)?.mine === false))
+        ) {
+          reactionOverlays.current.delete(k);
+          reactionBusy.current.delete(k);
+          setReactionVersion((v) => v + 1);
+        }
+      }
+  }, [props.threads, reactionVersion]);
+  const readDraft = (
+    draft: DiscussionDraft,
+    mode: 'create' | 'update',
+    target: Partial<CommentTarget>,
+  ): CommentDraft => {
+    const result: CommentDraft = {
+      content: content(draft.value),
+      attachments: draft.images.map((i) =>
+        i.file
+          ? { kind: 'local', localId: i.id, file: i.file }
+          : {
+              kind: 'existing',
+              attachment: {
+                id: i.id,
+                kind: 'image',
+                name: i.name,
+                url: i.url,
+                width: i.width,
+                height: i.height,
+              },
+            },
+      ),
+    };
+    for (const n of result.content.nodes) {
+      if (n.type === 'link' && !latest.current.input?.links)
+        throw fail('当前接口不支持结构化链接');
+      if (
+        n.type === 'mention' &&
+        n.ref.kind === 'document' &&
+        !documents?.canInsert
+      )
+        throw fail('当前接口不支持插入文档引用');
+      if (n.type === 'unresolved-mention' || n.type === 'unsupported')
+        throw fail('请重新选择无法识别的引用');
+      if (
+        n.type === 'mention' &&
+        n.ref.kind === 'user' &&
+        !latest.current.input?.userMentions?.(n.ref as UserRef)
+      )
+        throw fail('当前接口不支持此人员引用');
+    }
+    const error = latest.current.validateDraft?.(result, { mode, ...target });
+    if (error) throw fail(error);
+    return result;
+  };
+  const accept = async (result: CommentWriteResult, target?: CommentTarget) => {
+    if (
+      target &&
+      (result.threadId !== target.threadId ||
+        result.messageId !== target.messageId)
+    )
+      throw Object.assign(new Error('写入目标不匹配'), { outcome: 'unknown' });
+    if (result.message && result.message.id !== result.messageId)
+      throw Object.assign(new Error('回读消息 ID 不匹配'), {
+        outcome: 'unknown',
+      });
+    return {
+      commentID: result.threadId,
+      replyID: result.messageId,
+      ...(result.message
+        ? { authoritativeReply: toMessage(result.message, result.threadId) }
+        : {}),
+    };
+  };
+  return (
+    <DiscussionProvider
+      panel={{
+        source,
+        currentUser: props.currentUser
+          ? toRef(props.currentUser.ref)
+          : undefined,
+        comments: mutations.view(base),
+        allowCompose: !!props.actions?.create,
+        optimisticMutations: true,
+        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),
+            )
+          : undefined,
+        showReactions: !!reactions,
+        allowReact: !!reactions?.options.onChange,
+        enableImages: images && !!props.actions?.create,
+        enableEditImages: images && !!props.actions?.update,
+        enableDocuments: documents?.canInsert ?? false,
+        submittedReplyID: submitted ? mutations.replyID(submitted) : undefined,
+        onScrolledToReply: () => setSubmitted(undefined),
+        onRetryMutation: (id) => mutations.retry(id),
+        autoScrollNewReplies: false,
+        listHeader: (
+          <ReadStatus
+            loading={props.loading}
+            error={props.error}
+            onRetry={props.onRetry}
+            empty={
+              !base.some((t) => t.replies.length) &&
+              !mutations.view(base).length
+            }
+            hasMore={props.pagination?.hasMore}
+          />
+        ),
+        listFooter: props.pagination ? (
+          <PaginationFooter
+            pagination={props.pagination}
+            loading={props.loading || !!props.error}
+          />
+        ) : undefined,
+        emptyState: null,
+        onMentionClick: (ref, anchor) => {
+          if (ref.kind === 'user')
+            props.onActorClick?.(fromRef(ref) as UserRef, anchor);
+        },
+        getCommentLink: (threadId, m) =>
+          props.getMessageLink?.({ threadId, messageId: m.replyID }) ?? '',
+        resolveUserRef: (id) => ({ kind: 'user', idType: 'generic', id }),
+        onSubmit: (draft) => {
+          if (
+            draft.commentID &&
+            !latest.current.threads.some(
+              (t) =>
+                t.id === draft.commentID && t.canReply !== false && !t.resolved,
+            )
+          )
+            throw fail('该讨论当前不可回复');
+          const input = readDraft(
+            draft,
+            'create',
+            draft.commentID ? { threadId: draft.commentID } : {},
+          );
+          const ctx = context();
+          const id = mutations.add(
+            base.find((t) => t.commentID === draft.commentID),
+            draft,
+            props.currentUser ? toRef(props.currentUser.ref) : undefined,
+            async () =>
+              accept(
+                await latest.current.actions!.create!(
+                  {
+                    ...input,
+                    ...(draft.commentID ? { threadId: draft.commentID } : {}),
+                  },
+                  ctx,
+                ),
+              ),
+          );
+          setSubmitted(id);
+        },
+        onEdit: (threadId, messageId, v, attachments) => {
+          const input = readDraft(
+            { value: v, images: attachments, private: false },
+            'update',
+            { threadId, messageId },
+          );
+          const ctx = context();
+          mutations.edit(
+            base.find((t) => t.commentID === threadId)!,
+            messageId,
+            { value: v, images: attachments, private: false },
+            async () =>
+              accept(
+                await latest.current.actions!.update!(
+                  { ...input, threadId, messageId },
+                  ctx,
+                ),
+                { threadId, messageId },
+              ),
+          );
+        },
+        onDelete: (threadId, messageId) => {
+          if (!messageId) throw fail('未选择消息');
+          const ctx = context();
+          mutations.delete(
+            base.find((t) => t.commentID === threadId)!,
+            messageId,
+            async () => {
+              const r = await latest.current.actions!.remove!(
+                { threadId, messageId },
+                ctx,
+              );
+              return {
+                commentID: r.threadId,
+                ...(r.threadDeleted === undefined
+                  ? {}
+                  : { commentDeleted: r.threadDeleted }),
+              } as never;
+            },
+          );
+        },
+        onToggleReaction: async (threadId, messageId, emoji) => {
+          const target = { threadId, messageId };
+          const k = reactKey(target);
+          if (reactionBusy.current.has(k)) return;
+          const m = latest.current.threads
+            .find((t) => t.id === threadId)
+            ?.messages.find((m) => m.id === messageId);
+          if (
+            !m?.permissions?.react ||
+            !m.reactions ||
+            m.reactions.some((r) => r.mine === undefined) ||
+            !reactions?.options.onChange
+          )
+            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';
+          const next = before.filter((r) => r.key !== emoji);
+          const count = (old?.count ?? 0) + (action === 'add' ? 1 : -1);
+          if (count > 0)
+            next.push({
+              key: emoji,
+              count,
+              mine: action === 'add',
+              previewUsers:
+                action === 'add' && props.currentUser
+                  ? [
+                      props.currentUser,
+                      ...(old?.previewUsers ?? []).filter(
+                        (u) => key(u.ref) !== key(props.currentUser!.ref),
+                      ),
+                    ]
+                  : (old?.previewUsers ?? []).filter(
+                      (u) =>
+                        !props.currentUser ||
+                        key(u.ref) !== key(props.currentUser.ref),
+                    ),
+            });
+          reactionBusy.current.add(k);
+          reactionOverlays.current.set(k, {
+            data: next,
+            before,
+            confirmed: false,
+            key: emoji,
+            action,
+          });
+          setReactionVersion((v) => v + 1);
+          try {
+            const r = await reactions.options.onChange(
+              { ...target, key: emoji, action },
+              context(),
+            );
+            if (!abort.current.signal.aborted) {
+              reactionOverlays.current.set(k, {
+                data: r.reactions ?? next,
+                before,
+                confirmed: true,
+                key: emoji,
+                action,
+              });
+              setReactionVersion((v) => v + 1);
+            }
+          } catch (e) {
+            if (!abort.current.signal.aborted) {
+              if ((e as { outcome?: string })?.outcome === 'not-applied')
+                reactionOverlays.current.delete(k);
+              else
+                reactionOverlays.current.set(k, {
+                  data: next,
+                  before,
+                  confirmed: true,
+                  uncertain: true,
+                  key: emoji,
+                  action,
+                });
+              setReactionVersion((v) => v + 1);
+            }
+            throw e;
+          } finally {
+            if (!reactionOverlays.current.get(k)?.uncertain)
+              reactionBusy.current.delete(k);
+          }
+        },
+      }}
+    >
+      {props.children}
+    </DiscussionProvider>
+  );
+}
+export function CommentPanel(props: Omit<CommentsProviderProps, 'children'>) {
+  return (
+    <CommentsProvider {...props}>
+      <div className="replica-comment-panel">
+        <DiscussionLayout />
+      </div>
+    </CommentsProvider>
+  );
+}

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

@@ -0,0 +1,165 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+export type EntityRef = {
+  kind: 'user' | 'document';
+  namespace: string;
+  id: string;
+};
+export type UserRef = EntityRef & { kind: 'user' };
+export interface CommentAuthor {
+  ref: UserRef;
+  name?: string;
+  avatarUrl?: string;
+}
+export type CommentNode =
+  | { type: 'text'; text: string }
+  | { type: 'break' }
+  | { type: 'link'; url: string; label?: string }
+  | { type: 'mention'; ref: EntityRef; label?: string; href?: string }
+  | { type: 'unresolved-mention' }
+  | { type: 'unsupported'; label: string };
+export interface CommentContent {
+  version: 1;
+  nodes: CommentNode[];
+}
+export interface CommentAttachment {
+  id: string;
+  kind: 'image' | 'file';
+  name: string;
+  url?: string;
+  mimeType?: string;
+  width?: number;
+  height?: number;
+}
+export type CommentAttachmentInput =
+  | { kind: 'existing'; attachment: CommentAttachment }
+  | { kind: 'local'; localId: string; file: File };
+export interface CommentReaction {
+  key: string;
+  count: number;
+  mine?: boolean;
+  previewUsers?: CommentAuthor[];
+}
+export interface CommentMessage {
+  id: string;
+  author: CommentAuthor | null;
+  content: CommentContent;
+  createdAt: number;
+  updatedAt?: number;
+  edited?: boolean;
+  attachments?: CommentAttachment[];
+  reactions?: CommentReaction[];
+  permissions?: { edit: boolean; delete: boolean; react?: boolean };
+}
+export interface CommentPagination {
+  hasMore: boolean;
+  loading?: boolean;
+  error?: string;
+  onLoadMore(): Promise<void>;
+}
+export interface CommentThread {
+  id: string;
+  messages: CommentMessage[];
+  resolved?: boolean;
+  canReply?: boolean;
+  repliesPagination?: CommentPagination;
+}
+export interface CommentTarget {
+  threadId: string;
+  messageId: string;
+}
+export interface CommentDraft {
+  content: CommentContent;
+  attachments: CommentAttachmentInput[];
+}
+export interface CommentMutationContext {
+  operationId: string;
+  signal: AbortSignal;
+}
+export interface CommentWriteResult extends CommentTarget {
+  message?: CommentMessage;
+}
+export interface CommentActions {
+  create?(
+    input: CommentDraft & { threadId?: string },
+    context: CommentMutationContext,
+  ): Promise<CommentWriteResult>;
+  update?(
+    input: CommentDraft & CommentTarget,
+    context: CommentMutationContext,
+  ): Promise<CommentWriteResult>;
+  remove?(
+    target: CommentTarget,
+    context: CommentMutationContext,
+  ): Promise<{ threadId: string; threadDeleted?: boolean }>;
+}
+export interface CommentEntityOption {
+  ref: EntityRef;
+  label: string;
+  avatarUrl?: string;
+  description?: string;
+  href?: string;
+  readable?: boolean;
+}
+export type CommentEntityResult =
+  | (CommentEntityOption & { status: 'resolved' })
+  | { ref: EntityRef; status: 'forbidden' | 'not-found' | 'error' };
+export interface CommentEntitySource {
+  search?(args: {
+    query: string;
+    cursor?: string;
+    signal: AbortSignal;
+  }): Promise<{ items: CommentEntityOption[]; nextCursor?: string }>;
+  recommend?(args: {
+    cursor?: string;
+    signal: AbortSignal;
+  }): Promise<{ items: CommentEntityOption[]; nextCursor?: string }>;
+  resolve(
+    refs: EntityRef[],
+    signal: AbortSignal,
+  ): Promise<CommentEntityResult[]>;
+  parseUrl?(url: string): EntityRef | undefined;
+}
+export interface CommentReactionFeature {
+  allowedKeys?: readonly string[];
+  onChange?(
+    input: CommentTarget & { key: string; action: 'add' | 'remove' },
+    context: CommentMutationContext,
+  ): Promise<{ reactions?: CommentReaction[] }>;
+}
+export type CommentExtension =
+  | { type: 'reactions'; options: CommentReactionFeature }
+  | { type: 'documents'; source: CommentEntitySource; canInsert: boolean }
+  | { type: 'images' };
+export interface CommentsProviderProps {
+  scopeKey: string;
+  subjectKey: string;
+  threads: readonly CommentThread[];
+  currentUser?: CommentAuthor;
+  actions?: CommentActions;
+  loading?: boolean;
+  error?: string;
+  onRetry?: () => Promise<void>;
+  pagination?: CommentPagination;
+  actors?: CommentEntitySource;
+  input?: { userMentions?: (ref: UserRef) => boolean; links?: boolean };
+  extensions?: readonly CommentExtension[];
+  onActorClick?: (ref: UserRef, anchor: HTMLElement) => void;
+  getMessageLink?: (target: CommentTarget) => string | undefined;
+  validateDraft?: (
+    draft: CommentDraft,
+    target: {
+      mode: 'create' | 'update';
+      threadId?: string;
+      messageId?: string;
+    },
+  ) => string | undefined;
+  children: ReactNode;
+}
+export type CommentListProps = Omit<
+  ComponentPropsWithoutRef<'div'>,
+  'children' | 'dangerouslySetInnerHTML'
+>;
+export type CommentComposerProps = CommentListProps & {
+  placeholder?: string;
+  disabled?: boolean;
+};

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

@@ -0,0 +1,19 @@
+export { CommentsProvider, CommentPanel } from './comments';
+export { CommentList, CommentComposer } from '../record-comments/comment-panel';
+export type * from './contracts';
+import type {
+  CommentEntitySource,
+  CommentExtension,
+  CommentReactionFeature,
+} from './contracts';
+export const commentReactions = (
+  options: CommentReactionFeature = {},
+): CommentExtension => ({ type: 'reactions', options });
+export const commentDocuments = ({
+  source,
+  canInsert = false,
+}: {
+  source: CommentEntitySource;
+  canInsert?: boolean;
+}): CommentExtension => ({ type: 'documents', source, canInsert });
+export const commentImages = (): CommentExtension => ({ type: 'images' });

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

@@ -129,7 +129,7 @@ const extensions = useMemo(() => [
 
 ## 交互接入约束
 
-宿主复用组件已有交互，不额外包装删除确认、成功 toast 或“已显示全部评论”提示。复制链接成功后只关闭菜单；编辑操作按钮保持“确认”，等待态不新增“保存中”文字。回复自己也会插入自身提及；未知作者不能伪造提及。保持人员搜索和提及悬浮样式，不用宿主全局 button/a/p 样式覆盖组件。
+宿主复用组件已有交互，不额外包装删除确认、成功 toast 或“已显示全部评论”提示。复制链接成功后只关闭菜单；编辑操作按钮保持“确认”，等待态不新增“保存中”文字。回复自己不自动插入本人提及；未知作者不能伪造提及。保持人员搜索和提及悬浮样式，不用宿主全局 button/a/p 样式覆盖组件。
 
 保留读写失败的恢复入口和无障碍状态；未知写入结果不得开放盲目重试。新增提示或改变状态流前，应取得官方对应状态的操作证据；本地受控故障测试不等同于真实 Action 验收，未覆盖的权限/网络/图片能力需明确标注。
 

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

@@ -8,7 +8,7 @@ import { LoaderCircle } from 'lucide-react';
 import { forwardRef, useCallback, useEffect, useMemo, 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 }) {
+export 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);
@@ -41,7 +41,7 @@ function nearestScrollContainer(node: HTMLElement): HTMLElement | null {
   return null;
 }
 
-function PaginationFooter({ pagination, loading, getScrollContainer }: Pick<CommentPanelProps, 'pagination' | 'loading' | 'getScrollContainer'>) {
+export 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());

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

@@ -1,6 +1,6 @@
 import type { CommentImageFeature, CommentReactionFeature } from './comment-panel.contract';
 import type { CommentDataSource, CommentDocumentSource, MentionResult } from './types';
-import { mentionKey } from './internal/model';
+import { mentionKey, documentRefFromUrl } from './internal/model';
 
 /** Per-provider capabilities. No global registration, credentials or requests. */
 export type CommentExtension =
@@ -104,6 +104,7 @@ export function withDocumentSource(
   return {
     ...people,
     scopeKey: JSON.stringify([people.scopeKey, documents.scopeKey]),
+    parseLink: documents.parseLink ?? ((url) => { const ref = documentRefFromUrl(url); return ref ? { type: 'mention' as const, ref, href: url } : undefined; }),
     search: (args) => load(args, false),
     recommend: (args) => load({ ...args, query: '' }, true),
     async resolve(refs, signal) {

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

@@ -1,6 +1,6 @@
 import type { DiscussionReply, DiscussionImage, DiscussionPanelProps } from './view-types';
 import type { MentionRef } from '../types';
-import { COMMENT_THEME_CLASS, formatCommentTime, commentFailureMessage } from './model';
+import { COMMENT_THEME_CLASS, formatCommentTime, commentFailureMessage, mentionKey } from './model';
 import { DiscussionIcon } from './icons';
 import { DiscussionImageViewer } from './images';
 import { DiscussionComposer } from './composer';
@@ -160,6 +160,7 @@ function ReplyItem({
           )}
           <div className="replica-reply-controls" hidden={editing}>
             {panel.showReactions !== false && canReact && <CommentReactionEntry
+              emojis={panel.reactionEmojis}
               disabled={reacting}
               onToggle={(key) => { void handleToggleReaction(key); }}
               onOpenChange={setPicker}
@@ -473,12 +474,14 @@ export const DiscussionList = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivE
       {panel.comments.map((thread) => (
         <div className="replica-thread" key={thread.commentID} data-thread-id={thread.commentID}>
           {thread.isSolved && <span className="replica-panel-solved">已解决</span>}
+          {thread.verificationPending && <div className="replica-panel-status" role="status" aria-label="正在核对讨论"><span>正在加载评论</span></div>}
           {thread.replies.map((comment, index) => (
             <ReplyItem key={comment.replyID} comment={comment} commentID={thread.commentID} child={index > 0}
-              panel={itemPanel} replying={replyTarget?.commentID === thread.commentID && replyTarget.reply.replyID === comment.replyID}
+              panel={{...itemPanel, allowCompose: itemPanel.allowCompose && thread.canReply !== false}} replying={replyTarget?.commentID === thread.commentID && replyTarget.reply.replyID === comment.replyID}
               replyDisabled={composing} onReply={() => reply(thread.commentID, comment)}
               onPreviewImage={(images, index) => setGallery({ images, index })} />
           ))}
+          {thread.listFooter}
         </div>
       ))}
       {!replies.length && (panel.emptyState === undefined ? <div className="replica-empty">当前记录暂无评论</div> : panel.emptyState)}
@@ -495,9 +498,11 @@ export function DiscussionComposerView({ placeholder, disabled }: { placeholder?
   const replyPerson = useMentionEntity(replyTarget?.reply.author || { kind: 'user', idType: 'snapshot', id: 'unknown' });
   if (!allowCompose) return null;
   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}
     replyIntentKey={replyTarget ? `${replyTarget.commentID}:${replyTarget.reply.replyID}:${replyRevision}` : undefined}
-    replyMention={replyTarget?.reply.author ? { type: 'mention', ref: replyTarget.reply.author,
+    replyMention={mentionAuthor && author ? { type: 'mention', ref: author,
       label: replyPerson?.status === 'resolved' ? replyPerson.label : undefined } : undefined}
     enableDocuments={panel.enableDocuments} enableImages={panel.enableImages} enablePrivateComments={panel.enablePrivateComments}
     replyName={name} placeholder={name ? `回复 ${name}...` : placeholder || '添加新的评论...'}

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

@@ -1,6 +1,6 @@
 import type { MentionOption, MentionRef, DocumentMentionMetadata, CommentEditorProps, CommentValue } from '../types';
 import type { EntityStore } from './mentions';
-import { INPUT_USER_MENTION_CLASS, userMentionLabelClass, atUserLabel, DOCUMENT_MENTION_CLASS, DOCUMENT_MENTION_UNREADABLE_CLASS, documentSnapshot, isMentionRef, mentionLabel, safeUrl, fromApiContent, readApiContent, fromEditorDocument, emptyComment, normalizeValue, toEditorDocument, toPlainText, COMMENT_THEME_CLASS } from './model';
+import { INPUT_USER_MENTION_CLASS, userMentionLabelClass, atUserLabel, DOCUMENT_MENTION_CLASS, DOCUMENT_MENTION_UNREADABLE_CLASS, documentSnapshot, isMentionRef, mentionLabel, safeUrl, readApiContent, fromEditorDocument, emptyComment, normalizeValue, toEditorDocument, toPlainText, COMMENT_THEME_CLASS } from './model';
 import { documentEmoji, documentIconSvg } from './icons';
 import { Suggestion, type SuggestionProps, exitSuggestion } from '@tiptap/suggestion';
 import { Node, Extension } from '@tiptap/core';
@@ -502,9 +502,9 @@ export default function CommentEditor(props: CommentEditorProps) {
       const text = clipboardPlainText(data);
       if (text) {
         const pasted: CommentValue =
-          /^https?:\/\/\S+$/.test(text) && safeUrl(text)
+          /^https?:\/\/\S+$/.test(text) && safeUrl(text) && store.source.allowLinks !== false
             ? props.enableDocuments
-              ? fromApiContent([{ type: 'link', url: text }])
+              ? { version: 1, content: [store.source.parseLink?.(text) || { type: 'link', url: text }] }
               : { version: 1, content: [{ type: 'link', url: text }] }
             : { version: 1, content: [{ type: 'text', text }] };
         editor.commands.insertContent(

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

@@ -18,7 +18,7 @@ export function isMentionRef(value: unknown): value is MentionRef {
   return (
     typeof ref.id === 'string' &&
     ref.id.length > 0 &&
-    ((ref.kind === 'user' && ['apaas-user', 'lark-user', 'snapshot'].includes(String(ref.idType))) ||
+    ((ref.kind === 'user' && ['apaas-user', 'lark-user', 'snapshot', 'generic'].includes(String(ref.idType))) ||
       (ref.kind === 'document' &&
         typeof ref.resourceType === 'string' &&
         ref.resourceType.length > 0))

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

@@ -1,7 +1,7 @@
 import type { MentionRef } from '../types';
 import type { DiscussionDraft, DiscussionImage, DiscussionReply, DiscussionThread } from './view-types';
 import type { CommentIDs, DeleteCommentResult, CommentMutationFailure } from '../comment-panel.contract';
-import { commentFailureMessage, normalizeValue, readApiContent } from './model';
+import { commentFailureMessage, normalizeValue, mentionKey } from './model';
 
 export interface LocalCommentMutation {
   id: string;
@@ -17,14 +17,21 @@ interface Operation extends LocalCommentMutation {
   author?: MentionRef;
   createTime: number;
   wholeThread?: boolean;
+  deletionUnknown?: boolean;
+  authoritativeReply?: DiscussionReply;
   execute: () => Promise<CommentIDs | DeleteCommentResult>;
 }
-const contentKey = (reply: Pick<DiscussionReply, 'value'>) => JSON.stringify(readApiContent(reply.value));
+const contentKey = (reply: Pick<DiscussionReply, 'value'>) => JSON.stringify(normalizeValue(reply.value).content.map(part =>
+  part.type === 'mention' ? part.ref.kind === 'document' && part.href ? ['link', part.href] : ['mention', mentionKey(part.ref)]
+    : part.type === 'link' ? ['link', part.url] : part.type === 'text' ? ['text', part.text] : [part.type]));
 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 readonly options: { opaqueIDs?: boolean; unknownDeletion?: boolean; unknownErrors?: boolean; removePending?: boolean };
+  constructor(options: { opaqueIDs?: boolean; unknownDeletion?: boolean; unknownErrors?: boolean; removePending?: boolean } = {}) { this.options = options; }
+  private validID(id: unknown): id is string { return typeof id === 'string' && (this.options.opaqueIDs ? id.trim().length > 0 : /^\d+$/.test(id)); }
   private operations: Operation[] = [];
   private listeners = new Set<() => void>();
   private version = 0;
@@ -82,23 +89,27 @@ export class CommentMutations {
     try {
       const result = await operation.execute();
       if (!this.active) return;
-      if (!/^\d+$/.test(result.commentID)) throw uncertain('提交结果缺少有效评论 ID');
+      if (!this.validID(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;
+        if (!('commentDeleted' in result) || typeof result.commentDeleted !== 'boolean') {
+          if (!this.options.unknownDeletion) throw uncertain('删除结果未确认');
+          operation.deletionUnknown = true;
+        } else operation.wholeThread = result.commentDeleted;
       } else {
-        if (!('replyID' in result) || !/^\d+$/.test(result.replyID)) throw uncertain('提交结果缺少有效回复 ID');
+        if (!('replyID' in result) || !this.validID(result.replyID)) throw uncertain('提交结果缺少有效回复 ID');
         if (operation.kind === 'edit' && result.replyID !== operation.replyID) throw uncertain('编辑结果与目标回复不一致');
         operation.replyID = result.replyID;
       }
+      if ('authoritativeReply' in result && result.authoritativeReply) operation.authoritativeReply = result.authoritativeReply as DiscussionReply;
       operation.commentID = result.commentID;
       operation.phase = 'confirmed';
     } catch (cause) {
       if (!this.active) return;
-      operation.phase = (cause as CommentMutationFailure | null)?.outcome === 'unknown' ? 'uncertain' : 'failed';
+      const outcome = (cause as CommentMutationFailure | null)?.outcome;
+      operation.phase = outcome === 'unknown' || (this.options.unknownErrors && outcome !== 'not-applied') ? 'uncertain' : 'failed';
       operation.message = commentFailureMessage(cause, '操作失败，请重试');
     }
     this.changed();
@@ -125,7 +136,7 @@ export class CommentMutations {
     // 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;
+    if (contentKey(reply) !== contentKey(operation.authoritativeReply ?? { 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)
@@ -143,9 +154,12 @@ export class CommentMutations {
     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.kind === 'delete' && (operation.phase === 'confirmed' || (this.options.removePending && operation.phase === 'sending'))) {
         if (operation.wholeThread) threads = threads.filter((item) => item !== thread);
-        else if (thread) thread.replies = thread.replies.filter((reply) => reply.replyID !== operation.replyID);
+        else if (thread) {
+          thread.replies = thread.replies.filter((reply) => reply.replyID !== operation.replyID);
+          if (!thread.replies.length && (operation.deletionUnknown || operation.phase === 'sending')) thread.verificationPending = true;
+        }
         continue;
       }
       if (!thread) {
@@ -155,7 +169,7 @@ export class CommentMutations {
       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'
+      const reply: DiscussionReply = operation.authoritativeReply ? {...operation.authoritativeReply, mutation} : 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,
@@ -165,6 +179,6 @@ export class CommentMutations {
       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);
+    return threads.filter((thread) => thread.replies.length > 0 || thread.verificationPending || thread.listFooter);
   }
 }

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

@@ -1,4 +1,4 @@
-import type { CommentReaction } from './reactions';
+import type { CommentReaction, CommentEmoji } from './reactions';
 import type { CommentDataSource, CommentMentionClickHandler, CommentValue, MentionRef } from '../types';
 import type { LocalCommentMutation } from './mutations';
 import type { ReactNode } from 'react';
@@ -30,6 +30,9 @@ export interface DiscussionReply {
   reactions: CommentReaction[];
 }
 export interface DiscussionThread {
+  canReply?: boolean;
+  listFooter?: ReactNode;
+  verificationPending?: boolean;
   commentID: string;
   creator: MentionRef | null;
   createTime: number;
@@ -66,6 +69,7 @@ export interface DiscussionPanelProps {
   onRetryMutation?: (id: string) => void;
   allowReact?: boolean;
   showReactions?: boolean;
+  reactionEmojis?: readonly CommentEmoji[];
   enableImages?: boolean;
   enableEditImages?: boolean;
   enablePrivateComments?: boolean;
@@ -77,6 +81,7 @@ export interface DiscussionPanelProps {
   onMentionClick?: CommentMentionClickHandler;
   resolveUserRef?: (id: string) => MentionRef;
   getCommentLink?: (commentID: string, reply: DiscussionReply) => string;
+  canMentionUser?: (ref: MentionRef) => boolean;
   enableDocuments?: boolean;
   className?: string;
   submittedReplyID?: string;

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

@@ -1,7 +1,7 @@
 import type { Ref } from 'react';
 
 export type MentionRef =
-  | { kind: 'user'; id: string; idType: 'apaas-user' | 'lark-user' | 'snapshot' }
+  | { kind: 'user'; id: string; idType: 'apaas-user' | 'lark-user' | 'snapshot' | 'generic' }
   | { kind: 'document'; id: string; resourceType: string };
 
 export interface MentionOption {
@@ -41,7 +41,7 @@ export type CommentPart =
 /** A host supplies authenticated document search and metadata, independently of user IDs. */
 export type CommentDocumentSource = Pick<
   CommentDataSource,
-  'scopeKey' | 'search' | 'resolve' | 'recommend'
+  'scopeKey' | 'search' | 'resolve' | 'recommend' | 'parseLink'
 >;
 
 export interface CommentValue {
@@ -64,6 +64,9 @@ export type MentionKind = 'all' | 'user' | 'document';
 /** Keep this object stable. Change scopeKey when the user/tenant/app/permissions change. */
 export interface CommentDataSource {
   scopeKey: string;
+  /** Optional externally supplied URL-to-document reference conversion. */
+  allowLinks?: boolean;
+  parseLink?: (url: string) => CommentPart | undefined;
   /** Bare @ default list, independent of keyword search. Failures must reject. */
   recommend?: (args: {
     kind: MentionKind;