@lark-apaas/coding-template-nestjs-react-fullstack 0.1.54 → 0.1.55-alpha.20261030035108

package/package.json

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

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

@@ -517,3 +517,13 @@ 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 快捷键回调，发送、取消按钮及请求状态由页面组合，首次激活时动态加载 div 编辑器；支持选择/粘贴图片并在正文下方展示附件，使用 getImages/clearImages 管理。只读 `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,13 +10,7 @@ export const userProfileQueries = {
     queryOptions({
       queryKey: [...userProfileQueries.all(), 'byId', accountType, userId],
       queryFn: ({ signal }) => fetchUserProfile(userId, accountType, signal),
-      // staleTime 0：每次打开都在后台取一次新的，和飞书名片那条路保持一致
-      // ——「打开渲染缓存、后台乐观更新」。缓存命中时 isPending 为 false，
-      // 卡片瞬间渲出不转圈；新数据回来后 React 只 patch 变化的字段，不闪不跳。
-      //
-      // 之前是 60s：那段窗口内连请求都不发，远端改了最多要等 60 秒才看得到。
-      staleTime: 0,
-      // gcTime 决定缓存能留多久 —— 它才是「秒出」的来源，不要跟着一起调小。
+      staleTime: 1 * 60 * 1000,
       gcTime: 5 * 60 * 1000,
       enabled: !!userId,
     }),

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

@@ -0,0 +1,139 @@
+# 评论内容与输入组件
+
+面向 AI 生成的多维表格评论界面，只提供两个基础组件：
+
+- `CommentContent`：直接渲染 `reply.content`，内部补全人员与文档信息。
+- `CommentInput`：使用 contenteditable div 编辑文字、@人员与文档，支持独立图片附件区，暴露 ref API。按钮、请求、loading 和发送错误由页面组合。
+
+作者、时间、评论线程、回复、分页和解决状态均由业务页面处理。组件不包含这些业务包装。
+
+代码集中在 `business-ui/comment/`，输入、只读展示、数据源与类型均从该目录的对应文件导入。
+
+## 内容协议
+
+```ts
+type CommentApiContent =
+  | { type: 'text'; text: string }
+  | { type: 'mention'; userID?: number }
+  | { type: 'link'; url: string };
+```
+
+userID 是妙搭用户 ID，与 UserDisplay 一致。缺失 userID 的历史 mention 显示“引用信息缺失”，读取时仍原样返回，是否提交由页面决定。数字 ID 不得静默舍入。
+
+文档通过 link(url) 提交，内部 token、类型、标题和图标不进入接口数据。识别出的飞书文档 URL 可按 token 补全元数据；其他 URL 显示为普通链接。图片是正文下方的独立附件，不混入这三个 content 类型；旧 CCM `<at>` 内容格式不在组件范围内。
+
+## 使用
+
+```tsx
+import { useRef, useState } from 'react';
+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> }) {
+  const inputRef = useRef<CommentInputHandle>(null);
+  const busy = useRef(false);
+  const [value, setValue] = useState(emptyComment);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState('');
+  const handleSend = async () => {
+    const input = inputRef.current;
+    if (!input || busy.current) return;
+    busy.current = true;
+    input.setEditable(false);
+    setSending(true);
+    setError('');
+    try {
+      await save({ content: input.getContent() });
+      input.clear();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : '发送失败，请重试');
+    } finally {
+      input.setEditable(true);
+      busy.current = false;
+      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>;
+}
+```
+
+只读接口内容用 `<CommentContent content={reply.content} />`；回填编辑用 `fromApiContent(reply.content)`。受控 onChange 需同步更新 value；documentKey 仅在切换草稿时改变。
+
+## Ref 与快捷键
+
+- `getContent()`：读取最新接口 content，不做发送状态校验；编辑器尚未加载时也可读取草稿。
+- `clear()`：普通的正文清空操作，保留撤销历史，不重建编辑会话。
+- `getImages()`：读取附件状态与上传结果的快照，不自动转换成多维表格图片协议。
+- `clearImages()`：删除全部附件并取消/忽略上传，释放本地预览地址。附件独立于正文撤销历史。
+- `setEditable(boolean)`：控制正文、上传按钮及附件删除/重试；disabled prop 是外部硬禁用。
+- `focus()`：聚焦输入框，必要时加载编辑器。
+- `onSubmitRequest`：Enter（或 submitMode="mod-enter"）通知页面；输入法确认和 @候选选择优先处理，未配置时 Enter 换行。
+
+入口动态 import div 编辑器，首次激活时挂载；不依赖 Tiptap/ProseMirror。加载失败可重试。popover 挂在 Dialog/Sheet 时可传 portalContainer。React 管理外框、候选面板与附件，正文 DOM 由 DivEditor 独立管理，避免受控回写破坏光标和输入法。
+
+## 搜索与回显
+
+CommentProvider 默认复用 UserDisplay 的人员服务。页面传 content/userID 即可回显，不用自行查询姓名和头像。同页输入与列表共享批量解析、缓存及请求去重。自定义服务使用 MentionProvider source；切换用户、租户或权限范围时重建 source/scopeKey。
+
+recommend 用于刚输入 @ 或清空关键词；search 防抖 200ms，并忽略取消及过期响应。内置人员服务不提供空关键词推荐，需要宿主提供 `<CommentProvider recommend={loadPeople}>`。
+
+文档独立配置 `<CommentProvider documents={documents}>`，输入框再开启 enableDocuments：
+
+```ts
+import { createCcmDocumentSource, createBrowserCcmRequest } from '@/components/business-ui/comment/ccm-document-source';
+const documents = createCcmDocumentSource({
+  scopeKey: currentUserScope, token: hostDocumentToken, objType: hostDocumentType,
+  request: createBrowserCcmRequest(authenticatedProxyPath),
+  search: searchCloudDocuments, // 可选：宿主提供完整文档搜索
+});
+```
+
+在 useMemo 内创建并保持数据源稳定。宿主负责已鉴权的同源代理和文档上下文；组件不会创建代理。默认列表复用 recommend.v2，回显使用 meta/batch，嵌入权限使用 4096 权限位；无权限灰显仍保留原链接以便申请访问。未注入 search 时用 recommend.v2 的 content 查询，召回与 miaoda 桌面统一搜索可能不同。
+
+## 外观与人员卡片
+
+保留 miaoda 的布局：输入区最小 34px、上下 5px 留白、22px 行高；输入人员为蓝底白字 rounded-full 胶囊。只读人员为蓝色 @姓名，本人高亮。候选面板 360px 宽、417px 最大高度，48px 行高、32px 图标，隐藏分类栏。
+
+文档候选使用 UD V2 彩色类型图标，wiki 按子类型；行内 14px 图标与标题，新窗打开链接。只读与输入回显共享样式，文档卡片预渲染不在范围内。
+
+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 会重置正文历史。保留旧结构转换函数供已有调用方过渡，新实现不使用它们。

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/ccm-document-source.ts

@@ -0,0 +1,252 @@
+import { mentionKey, safeUrl } from './content';
+import type {
+  CommentDocumentSource,
+  MentionOption,
+  MentionRef,
+  MentionResult,
+} from './types';
+
+interface DocumentEntity {
+  title?: string;
+  url?: string;
+  sub_type?: number | string;
+  icon_info?: string;
+  edit_time?: number;
+  is_external?: boolean;
+  title_secure_key_deleted?: boolean;
+}
+interface CcmResponse {
+  code: number;
+  msg?: string;
+  data?: {
+    entities?: { notes?: Record<string, DocumentEntity> };
+    result_list?: { token: string; type: number }[];
+    perms?: Record<string, number>;
+    [token: string]: unknown;
+  };
+}
+export type CcmRequest = (
+  path: string,
+  options: {
+    signal: AbortSignal;
+    form?: Record<string, string | number | undefined>;
+    json?: unknown;
+  },
+) => Promise<CcmResponse>;
+
+function documentFields(entity: DocumentEntity) {
+  const subType =
+    entity.sub_type === undefined ? undefined : Number(entity.sub_type);
+  return {
+    label: entity.title || '未命名文档',
+    href: safeUrl(entity.url),
+    description: entity.edit_time
+      ? `最后更新：${formatDocumentTime(entity.edit_time < 1e12 ? entity.edit_time : entity.edit_time / 1000)}`
+      : undefined,
+    isExternal: entity.is_external === true,
+    document: {
+      subType: Number.isSafeInteger(subType) ? subType : undefined,
+      iconInfo: entity.icon_info,
+    },
+  };
+}
+
+/** Document-only CCM adapter. The host supplies document context and authenticated requests. */
+export function createCcmDocumentSource(options: {
+  scopeKey: string;
+  token: string;
+  objType: number;
+  request: CcmRequest;
+  search?: CommentDocumentSource['search'];
+}): CommentDocumentSource {
+  const { request, token, objType } = options;
+  const recommend: NonNullable<CommentDocumentSource['recommend']> = async (
+    args,
+  ) => searchRecommendations('', args.signal);
+  async function searchRecommendations(query: string, signal: AbortSignal) {
+    const response = await request('/space/api/mention/recommend.v2/', {
+      signal,
+      form: {
+        token,
+        obj_type: objType,
+        source: objType,
+        type: '0,1,3,7,8,11,12,16,22',
+        content: query || undefined,
+      },
+    });
+    signal.throwIfAborted();
+    if (response.code !== 0 || !response.data)
+      throw new Error(response.msg || '文档搜索失败');
+    const items: MentionOption[] = [];
+    for (const item of response.data.result_list || []) {
+      const entity = response.data.entities?.notes?.[item.token];
+      if (item.type !== 0 && entity)
+        items.push({
+          ref: {
+            kind: 'document',
+            id: item.token,
+            resourceType: String(item.type),
+          },
+          ...documentFields(entity),
+        });
+    }
+    return { items };
+  }
+  return {
+    scopeKey: JSON.stringify([options.scopeKey, token, objType]),
+    recommend,
+    search:
+      options.search ||
+      (({ query, signal }) => searchRecommendations(query, signal)),
+    async resolve(refs, signal) {
+      const docs = refs.filter(
+        (ref): ref is Extract<MentionRef, { kind: 'document' }> =>
+          ref.kind === 'document' && /^\d+$/.test(ref.resourceType),
+      );
+      const results = new Map<string, MentionResult>();
+      for (let offset = 0; offset < docs.length; offset += 100) {
+        const batch = docs.slice(offset, offset + 100);
+        const tokens: Record<string, string[]> = {};
+        for (const ref of batch) {
+          const type = ref.resourceType === '1' ? '2' : ref.resourceType;
+          (tokens[type] ||= []).push(ref.id);
+        }
+        try {
+          const response = await request('/space/api/meta/batch', {
+            signal,
+            json: { tokens },
+          });
+          for (const ref of batch) {
+            const entity = response.data?.[ref.id] as
+              | DocumentEntity
+              | undefined;
+            results.set(
+              mentionKey(ref),
+              response.code === 0 && entity && !entity.title_secure_key_deleted
+                ? { ref, status: 'resolved', ...documentFields(entity) }
+                : { ref, status: response.code === 4 ? 'forbidden' : 'error' },
+            );
+          }
+        } catch {
+          signal.throwIfAborted();
+        }
+      }
+      // Check the host's embed permission; a denial greys the link but keeps its access-request path.
+      for (let offset = 0; offset < docs.length; offset += 10) {
+        const batch = docs.slice(offset, offset + 10);
+        try {
+          const response = await request(
+            '/space/api/suite/permission/objects/embed/',
+            {
+              signal,
+              json: {
+                token,
+                type: objType,
+                perm: 4096,
+                child_objects: Object.fromEntries(
+                  batch.map((ref) => [
+                    ref.id,
+                    Number(ref.resourceType === '1' ? '2' : ref.resourceType),
+                  ]),
+                ),
+              },
+            },
+          );
+          if (response.code === 0 && response.data)
+            for (const ref of batch) {
+              const result = results.get(mentionKey(ref));
+              const permission = response.data.perms?.[ref.id];
+              if (result?.status === 'resolved')
+                results.set(mentionKey(ref), {
+                  ...result,
+                  readable:
+                    typeof permission === 'number' &&
+                    Boolean(permission & 4096),
+                });
+            }
+        } catch {
+          signal.throwIfAborted();
+        } // Unknown permission does not become a denial.
+      }
+      signal.throwIfAborted();
+      return refs.map(
+        (ref) =>
+          results.get(mentionKey(ref)) || { ref, status: 'error' as const },
+      );
+    },
+  };
+}
+
+function formatDocumentTime(createTime: number) {
+  const date = new Date(createTime * 1000);
+  const now = new Date();
+  const seconds = Math.max(
+    0,
+    Math.round((now.getTime() - date.getTime()) / 1000),
+  );
+  if (date.toDateString() === now.toDateString()) {
+    if (seconds <= 44) return '刚刚';
+    if (seconds <= 89) return '1 分钟前';
+    const minutes = Math.round(seconds / 60);
+    if (minutes <= 44) return `${minutes} 分钟前`;
+    if (minutes <= 89) return '1 小时前';
+    return `${Math.round(minutes / 60)} 小时前`;
+  }
+  const time = date.toLocaleTimeString('zh-CN', {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  });
+  const yesterday = new Date(now);
+  yesterday.setDate(now.getDate() - 1);
+  if (date.toDateString() === yesterday.toDateString()) return `昨天 ${time}`;
+  return date.getFullYear() === now.getFullYear()
+    ? `${date.getMonth() + 1}月${date.getDate()}日 ${time}`
+    : `${date.getFullYear()}年${date.getMonth() + 1}月${date.getDate()}日`;
+}
+
+/** The host must expose authenticated CCM routes under this same-origin proxy path. */
+export function createBrowserCcmRequest(basePath = ''): CcmRequest {
+  if (
+    basePath &&
+    (!basePath.startsWith('/') ||
+      basePath.startsWith('//') ||
+      /[?#\\\s]/.test(basePath))
+  )
+    throw new Error('云文档代理必须是同源路径');
+  return async (path, options) => {
+    if (!path.startsWith('/space/api/')) throw new Error('不支持的云文档接口');
+    const cookie = document.cookie
+      .split(';')
+      .map((part) => part.trim())
+      .find((part) => part.startsWith('_csrf_token='));
+    const headers: Record<string, string> = {};
+    if (cookie)
+      headers['x-csrftoken'] = decodeURIComponent(
+        cookie.slice('_csrf_token='.length),
+      );
+    let body: string;
+    if (options.form) {
+      headers['content-type'] = 'application/x-www-form-urlencoded';
+      const form = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.form))
+        if (value !== undefined) form.set(key, String(value));
+      body = form.toString();
+    } else {
+      headers['content-type'] = 'application/json';
+      body = JSON.stringify(options.json);
+    }
+    const response = await fetch(`${basePath.replace(/\/$/, '')}${path}`, {
+      method: 'POST',
+      headers,
+      body,
+      signal: options.signal,
+      credentials: 'include',
+    });
+    if (!response.ok) throw new Error('云文档服务请求失败，请重试');
+    const result: CcmResponse = await response.json();
+    if (typeof result.code !== 'number')
+      throw new Error('云文档服务响应格式无效');
+    return result;
+  };
+}