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

package/package.json

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

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

@@ -522,7 +522,7 @@ function BasicExample() {
 
 `comment/comment-content.tsx` 提供不依赖 Tiptap 的只读展示，配合 `comment/mention-provider.tsx` 批量补全人员和文档信息。
 
-评论输入框已内置。从 `@/components/business-ui/comment/comment-input` 直接导入 `CommentInput`，组件提供 getContent/clear/setEditable/focus ref API 和 onSubmitRequest 快捷键回调，发送、取消按钮及请求状态由页面组合，原生 div 编辑器直接可编辑；支持选择/粘贴图片并在正文下方展示附件，使用 getImages/clearImages 管理。只读 `CommentContent` 不依赖编辑器。作者、时间、线程与接口调用由消费页面组合。
+评论输入框已内置。从 `@/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 不能混用。
 

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

@@ -3,7 +3,7 @@
 面向 AI 生成的多维表格评论界面，只提供两个基础组件：
 
 - `CommentContent`：直接渲染 `reply.content`，内部补全人员与文档信息。
-- `CommentInput`：使用 contenteditable div 编辑文字、@人员与文档，支持独立图片附件区，暴露 ref API。按钮、请求、loading 和发送错误由页面组合。
+- `CommentInput`：编辑文字、@人员与文档，暴露 ref API。按钮、请求、loading 和发送错误由页面组合。
 
 作者、时间、评论线程、回复、分页和解决状态均由业务页面处理。组件不包含这些业务包装。
 
@@ -20,7 +20,7 @@ type CommentApiContent =
 
 userID 是妙搭用户 ID，与 UserDisplay 一致。缺失 userID 的历史 mention 显示“引用信息缺失”，读取时仍原样返回，是否提交由页面决定。数字 ID 不得静默舍入。
 
-文档通过 link(url) 提交，内部 token、类型、标题和图标不进入接口数据。识别出的飞书文档 URL 可按 token 补全元数据；其他 URL 显示为普通链接。图片是正文下方的独立附件，不混入这三个 content 类型；旧 CCM `<at>` 内容格式不在组件范围内。
+文档通过 link(url) 提交，内部 token、类型、标题和图标不进入接口数据。识别出的飞书文档 URL 可按 token 补全元数据；其他 URL 显示为普通链接。图片和旧 CCM `<at>` 内容格式不在组件范围内。
 
 ## 使用
 
@@ -30,16 +30,9 @@ import { CommentInput } from '@/components/business-ui/comment/comment-input';
 import { CommentContent } from '@/components/business-ui/comment/comment-content';
 import { CommentProvider } from '@/components/business-ui/comment/comment-provider';
 import { emptyComment } from '@/components/business-ui/comment/content';
-import type {
-  CommentInputHandle,
-  CommentSubmitPayload,
-} from '@/components/business-ui/comment/types';
-
-export function CommentExample({
-  save,
-}: {
-  save: (body: CommentSubmitPayload) => Promise<void>;
-}) {
+import type { CommentInputHandle, CommentSubmitPayload } from '@/components/business-ui/comment/types';
+
+export function CommentExample({ save }: { save: (body: CommentSubmitPayload) => Promise<void> }) {
   const inputRef = useRef<CommentInputHandle>(null);
   const busy = useRef(false);
   const [value, setValue] = useState(emptyComment);
@@ -63,32 +56,14 @@ export function CommentExample({
       setSending(false);
     }
   };
-  return (
-    <CommentProvider>
-      <CommentInput
-        ref={inputRef}
-        documentKey="new"
-        value={value}
-        onChange={setValue}
-        onSubmitRequest={() => {
-          void handleSend();
-        }}
-      />
-      <button disabled={sending} onClick={() => inputRef.current?.clear()}>
-        取消
-      </button>
-      <button
-        disabled={sending}
-        onClick={() => {
-          void handleSend();
-        }}
-      >
-        发送
-      </button>
-      {error ? <p role="alert">{error}</p> : null}
-      <CommentContent value={value} />
-    </CommentProvider>
-  );
+  return <CommentProvider>
+    <CommentInput ref={inputRef} documentKey="new" value={value}
+      onChange={setValue} onSubmitRequest={() => { void handleSend(); }} />
+    <button disabled={sending} onClick={() => inputRef.current?.clear()}>取消</button>
+    <button disabled={sending} onClick={() => { void handleSend(); }}>发送</button>
+    {error ? <p role="alert">{error}</p> : null}
+    <CommentContent value={value} />
+  </CommentProvider>;
 }
 ```
 
@@ -98,13 +73,11 @@ export function CommentExample({
 
 - `getContent()`：读取最新接口 content，不做发送状态校验；编辑器尚未加载时也可读取草稿。
 - `clear()`：普通的正文清空操作，保留撤销历史，不重建编辑会话。
-- `getImages()`：读取附件状态与上传结果的快照，不自动转换成多维表格图片协议。
-- `clearImages()`：删除全部附件并取消/忽略上传，释放本地预览地址。附件独立于正文撤销历史。
-- `setEditable(boolean)`：控制正文、上传按钮及附件删除/重试；disabled prop 是外部硬禁用。
-- `focus()`：聚焦输入框。
+- `setEditable(boolean)`：控制编辑；disabled prop 是外部硬禁用。
+- `focus()`：聚焦输入框，必要时加载编辑器。
 - `onSubmitRequest`：Enter（或 submitMode="mod-enter"）通知页面；输入法确认和 @候选选择优先处理，未配置时 Enter 换行。
 
-原生 div 编辑器直接挂载，输入区无需二次点击激活；不依赖 Tiptap/ProseMirror。图片存储 SDK 仍按需导入。popover 挂在 Dialog/Sheet 时可传 portalContainer。React 管理外框、候选面板与附件，正文 DOM 由 DivEditor 独立管理，避免受控回写破坏光标和输入法。
+入口动态 import 最小 Tiptap 3.20.0，首次激活时挂载编辑器；只读组件不导入 Tiptap。加载失败可重试。popover 挂在 Dialog/Sheet 时可传 portalContainer。
 
 ## 搜索与回显
 
@@ -115,14 +88,9 @@ recommend 用于刚输入 @ 或清空关键词；search 防抖 200ms，并忽略
 文档独立配置 `<CommentProvider documents={documents}>`，输入框再开启 enableDocuments：
 
 ```ts
-import {
-  createCcmDocumentSource,
-  createBrowserCcmRequest,
-} from '@/components/business-ui/comment/ccm-document-source';
+import { createCcmDocumentSource, createBrowserCcmRequest } from '@/components/business-ui/comment/ccm-document-source';
 const documents = createCcmDocumentSource({
-  scopeKey: currentUserScope,
-  token: hostDocumentToken,
-  objType: hostDocumentType,
+  scopeKey: currentUserScope, token: hostDocumentToken, objType: hostDocumentType,
   request: createBrowserCcmRequest(authenticatedProxyPath),
   search: searchCloudDocuments, // 可选：宿主提供完整文档搜索
 });
@@ -139,39 +107,3 @@ const documents = createCcmDocumentSource({
 CommentContent 的 onMentionClick(ref, anchor) 仅透出人员点击，由消费页面复用 UserProfile。元数据加载前也可点击，回显更新保持锚点 DOM 稳定。
 
 在生成应用中运行 `npm run type:check:client` 和 `npm run build:client`；浏览器中另行验证中文输入法、键盘候选操作、撤销、回填和弹层位置。类型检查与构建不代表真实接口鉴权或视觉验收完成。
-
-## 图片附件与权限意图
-
-```tsx
-<CommentInput
-  ref={inputRef}
-  documentKey="new"
-  value={value}
-  onChange={setValue}
-  enableDocuments
-  enableImages
-  onImagesChange={setImages}
-  grantMentionAccess={grantMentionAccess}
-  onGrantMentionAccessChange={setGrantMentionAccess}
-/>
-```
-
-图片区按参考图排列在正文下方，64px 缩略图、圆角与右上角删除按钮；点击缩略图可预览。选择文件、粘贴或拖入正文均追加到附件区，不占正文光标位置。支持 PNG/JPEG/WebP/GIF/AVIF/BMP；默认最多 9 张、单张 10 MiB，通过 maxImages/maxImageSize 调整。最多 3 个并发上传，上传中显示加载状态，失败可重试。
-
-默认延迟导入模板已有的 api/files/service 上传到妙搭存储。可通过 uploadImage(file, { signal }) 注入自定义服务，返回 `{ id, url, filePath?, bucketId? }`。删除、clearImages、切换 documentKey、切换数据源作用域和卸载都会取消或忽略迟到的上传结果；默认 SDK 不支持真正取消网络请求。删除和卸载时释放 Object URL；失败文件仅保留到重试或删除。
-
-getImages 返回 `{ id, name, size, previewUrl, status, result?, error? }[]`：id 是本地附件 ID，result.id 才是服务端文件 ID；previewUrl 是临时 Blob URL，不能提交或持久化。页面通过 onImagesChange 判断是否仍有 uploading/error 状态，自行控制发送按钮，并把 result 映射到真实接口。当前未确认多维表格图片提交协议，因此 getContent 继续只返回 text/mention/link，CommentContent 继续只渲染正文。
-
-如需在发送成功后重置整个输入区，依次调用 clear() 与 clearImages()。这两个方法不执行发送校验，也不处理发送失败；失败时是否保留内容由页面决定。切换 documentKey 表示新会话，正文撤销和附件都重置。
-
-“授予提及的人阅读权限”仅在传入 onGrantMentionAccessChange 时显示，属于受控的业务意图，组件不直接调用文档授权接口。消费页面负责结合勾选值执行真实授权。
-
-正文使用统一的自有撤销历史，覆盖文字、引用插入/删除、粘贴和 clear。连续文字合并为一组，输入法组合输入作为一组；元数据回显不产生编辑历史，外部替换 value 会重置正文历史。正文直接使用 CommentValue，不保留 Tiptap 文档结构转换层。
-
-## 文件组织
-
-comment-input.tsx 提供校验、错误边界与原生编辑交互，dom-editor.ts 管理正文与撤销，image-attachments.tsx 管理独立附件。comment-content.tsx 独立提供只读展示，不依赖编辑器。
-
-mention-provider.tsx 放上下文和缓存；comment-provider.tsx 放默认人员服务、文档混合数据源与便捷 Provider。mention-suggestions.tsx 放候选面板和搜索 Hook；mention-view.tsx 放引用样式与文档图标。content.ts/types.ts 放协议转换与类型，ccm-document-source.ts 是可选的宿主文档适配器。
-
-preloadCommentEditor 保留为兼容空操作；编辑器直接挂载后无需预加载。

package/template/client/src/components/business-ui/comment/app-source.ts

@@ -0,0 +1,175 @@
+import { listUsersByIds, searchUsers } from '../api/users/service';
+import { getI18nText } from '../utils/user';
+import { mentionKey } from './content';
+import type {
+  CommentDataSource,
+  CommentDocumentSource,
+  MentionOption,
+  MentionResult,
+} from './types';
+
+function avatarUrl(avatar: unknown): string | undefined {
+  if (typeof avatar === 'string') return avatar;
+  if (avatar && typeof avatar === 'object' && 'image' in avatar) {
+    const image = avatar.image;
+    if (
+      image &&
+      typeof image === 'object' &&
+      'large' in image &&
+      typeof image.large === 'string'
+    )
+      return image.large;
+  }
+  return undefined;
+}
+
+/** The same Miaoda user IDs and built-in service used by UserDisplay. */
+export function createAppCommentSource(scopeKey: string): CommentDataSource {
+  return {
+    scopeKey,
+    async search({ query, cursor, signal }) {
+      signal.throwIfAborted();
+      // The built-in directory has no empty-query recommendations. In a mixed
+      // source, leave that branch empty so document recommendations still load.
+      if (!query) return { items: [] };
+      const offset = Number(cursor || 0);
+      if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error('分页参数无效');
+      const response = await searchUsers({ query, offset, pageSize: 20 });
+      signal.throwIfAborted();
+      if (String(response.status_code) !== '0')
+        throw new Error('人员搜索失败，请重试');
+      const users = response.data.userList ?? [];
+      const items: MentionOption[] = users.flatMap((user) => {
+        // Unregistered contacts have no Miaoda ID; never substitute a Lark ID.
+        const id = String(user.userID || '');
+        if (!/^[1-9]\d*$/.test(id)) return [];
+        return [
+          {
+            ref: { kind: 'user' as const, idType: 'apaas-user' as const, id },
+            label: getI18nText(user.name) || '未命名人员',
+            avatarUrl: avatarUrl(user.avatar),
+            description: getI18nText(user.department?.name) || user.tenantName,
+          },
+        ];
+      });
+      const nextOffset = offset + users.length;
+      return {
+        items,
+        nextCursor:
+          users.length && nextOffset < response.data.total
+            ? String(nextOffset)
+            : undefined,
+      };
+    },
+    async resolve(refs, signal) {
+      signal.throwIfAborted();
+      const ids = refs.flatMap((ref) =>
+        ref.kind === 'user' && ref.idType === 'apaas-user' ? [ref.id] : [],
+      );
+      const response = ids.length ? await listUsersByIds(ids) : undefined;
+      signal.throwIfAborted();
+      const base = response?.data?.baseResp;
+      if (base?.statusCode)
+        throw new Error(base.statusMessage || '人员信息加载失败');
+      if (ids.length && !response?.data?.userInfoMap)
+        throw new Error('人员信息返回格式无效');
+      const people = response?.data?.userInfoMap || {};
+      return refs.map((ref): MentionResult => {
+        if (ref.kind !== 'user' || ref.idType !== 'apaas-user')
+          return { ref, status: 'error' };
+        const user = people[ref.id];
+        if (!user) return { ref, status: 'not-found' };
+        return {
+          ref,
+          status: 'resolved',
+          label: getI18nText(user.name) || '未命名人员',
+          avatarUrl: avatarUrl(user.avatar),
+        };
+      });
+    },
+  };
+}
+
+/** Keep Miaoda people IDs and cloud-document tokens in their own services. */
+export function withDocumentSource(
+  people: CommentDataSource,
+  documents: CommentDocumentSource,
+): CommentDataSource {
+  const load = async (
+    args: Parameters<CommentDataSource['search']>[0],
+    recommend: boolean,
+  ) => {
+    const fetchSource = (
+      source: CommentDataSource | CommentDocumentSource,
+      kind: 'user' | 'document',
+      cursor?: string,
+    ) =>
+      recommend && source.recommend
+        ? source.recommend({ ...args, kind, cursor })
+        : source.search({ ...args, kind, cursor });
+    if (args.kind === 'user') return fetchSource(people, 'user', args.cursor);
+    if (args.kind === 'document')
+      return fetchSource(documents, 'document', args.cursor);
+    const cursor: { user?: string; document?: string } = args.cursor
+      ? JSON.parse(args.cursor)
+      : {};
+    if (
+      !cursor ||
+      typeof cursor !== 'object' ||
+      [cursor.user, cursor.document].some(
+        (value) => value !== undefined && typeof value !== 'string',
+      )
+    )
+      throw new Error('分页参数无效');
+    const exhausted: Awaited<ReturnType<CommentDataSource['search']>> = {
+      items: [],
+    };
+    const [users, docs] = await Promise.all([
+      !args.cursor || cursor.user !== undefined
+        ? fetchSource(people, 'user', cursor.user)
+        : exhausted,
+      !args.cursor || cursor.document !== undefined
+        ? fetchSource(documents, 'document', cursor.document)
+        : exhausted,
+    ]);
+    return {
+      items: [
+        ...users.items.filter((item) => item.ref.kind === 'user'),
+        ...docs.items.filter((item) => item.ref.kind === 'document'),
+      ],
+      nextCursor:
+        users.nextCursor || docs.nextCursor
+          ? JSON.stringify({
+              user: users.nextCursor,
+              document: docs.nextCursor,
+            })
+          : undefined,
+    };
+  };
+  return {
+    ...people,
+    scopeKey: JSON.stringify([people.scopeKey, documents.scopeKey]),
+    search: (args) => load(args, false),
+    recommend: (args) => load({ ...args, query: '' }, true),
+    async resolve(refs, signal) {
+      const users = refs.filter((ref) => ref.kind === 'user');
+      const docs = refs.filter((ref) => ref.kind === 'document');
+      // One failed service must not hide successful metadata from the other.
+      const results = await Promise.allSettled([
+        users.length ? people.resolve(users, signal) : [],
+        docs.length ? documents.resolve(docs, signal) : [],
+      ]);
+      signal.throwIfAborted();
+      const byKey = new Map<string, MentionResult>();
+      for (const result of results)
+        if (result.status === 'fulfilled')
+          for (const item of result.value)
+            byKey.set(mentionKey(item.ref), item);
+      return refs.map(
+        (ref) =>
+          byKey.get(mentionKey(ref)) || { ref, status: 'error' as const },
+      );
+    },
+  };
+}

package/template/client/src/components/business-ui/comment/comment-content.tsx

@@ -1,6 +1,6 @@
+import { DocumentIcon } from './document-icon';
 import { fromApiContent } from './content';
 import {
-  DocumentIcon,
   USER_MENTION_CLASS,
   INPUT_USER_MENTION_CLASS,
   INPUT_USER_MENTION_LABEL_CLASS,
@@ -10,10 +10,14 @@ import {
   USER_MENTION_LABEL_CLASS,
   DOCUMENT_MENTION_CLASS,
   DOCUMENT_MENTION_UNREADABLE_CLASS,
-} from './mention-view';
+} from './mention-appearance';
 import * as React from 'react';
 import { cn } from '@/lib/utils';
-import { mentionLabel, normalizeValue, safeUrl } from './content';
+import {
+  mentionLabel,
+  normalizeValue,
+  safeUrl,
+} from './content';
 import {
   useMentionContext,
   useMentionEntity,