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

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

@@ -0,0 +1,213 @@
+import { useMemo, type ReactNode } from 'react';
+import * as React from 'react';
+import { getAppId } from '../user-select/utils';
+import { useCurrentUserProfile } from '@lark-apaas/client-toolkit/hooks/useCurrentUserProfile';
+import { MentionProvider } from './mention-provider';
+import type {
+  CommentDataSource,
+  CommentDocumentSource,
+  MentionOption,
+  MentionResult,
+} from './types';
+import { listUsersByIds, searchUsers } from '../api/users/service';
+import { getI18nText } from '../utils/user';
+import { mentionKey } from './content';
+
+/** Configure the built-in UserDisplay data service once for the input and list. */
+export function CommentProvider({
+  children,
+  scopeKey,
+  currentUserID,
+  recommend,
+  documents,
+}: {
+  children: ReactNode;
+  scopeKey?: string;
+  currentUserID?: string;
+  recommend?: CommentDataSource['recommend'];
+  documents?: CommentDocumentSource;
+}) {
+  const user = useCurrentUserProfile();
+  const scope = JSON.stringify([
+    typeof window === 'undefined' ? null : getAppId(window.location.pathname),
+    scopeKey || user.user_id || 'pending',
+  ]);
+  const source = useMemo(() => {
+    const people = { ...createAppCommentSource(scope), recommend };
+    return documents ? withDocumentSource(people, documents) : people;
+  }, [scope, recommend, documents]);
+  return (
+    <MentionProvider
+      source={source}
+      currentUserID={currentUserID || user.user_id}
+    >
+      {children}
+    </MentionProvider>
+  );
+}
+
+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/content.ts

@@ -0,0 +1,261 @@
+import type {
+  CommentPart,
+  CommentApiContent,
+  CommentValue,
+  MentionRef,
+  MentionResult,
+} from './types';
+
+export const emptyComment = (): CommentValue => ({ version: 1, content: [] });
+
+export function mentionKey(ref: MentionRef): string {
+  return JSON.stringify([
+    ref.kind,
+    ref.kind === 'user' ? ref.idType : ref.resourceType,
+    ref.id,
+  ]);
+}
+
+export function isMentionRef(value: unknown): value is MentionRef {
+  if (!value || typeof value !== 'object') return false;
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref.id === 'string' &&
+    ref.id.length > 0 &&
+    ((ref.kind === 'user' && ref.idType === 'apaas-user') ||
+      (ref.kind === 'document' &&
+        typeof ref.resourceType === 'string' &&
+        ref.resourceType.length > 0))
+  );
+}
+
+export function safeUrl(url?: string): string | undefined {
+  if (!url) return undefined;
+  if (
+    url.startsWith('/') &&
+    !url.startsWith('//') &&
+    !/[\\\s\u0000-\u001f]/.test(url)
+  )
+    return url;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'https:' || parsed.protocol === 'http:'
+      ? parsed.href
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeValue(value: CommentValue): CommentValue {
+  if (!value || value.version !== 1 || !Array.isArray(value.content)) {
+    throw new Error('不支持的评论内容格式');
+  }
+  const content: CommentPart[] = [];
+  const text = (s: string) => {
+    if (!s) return;
+    const previous = content[content.length - 1];
+    if (previous?.type === 'text') previous.text += s;
+    else content.push({ type: 'text', text: s });
+  };
+  for (const part of value.content) {
+    if (part.type === 'text' && typeof part.text === 'string') {
+      part.text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .forEach((line, i) => {
+          if (i) content.push({ type: 'break' });
+          text(line);
+        });
+    } else if (part.type === 'break') content.push({ type: 'break' });
+    else if (part.type === 'link' && typeof part.url === 'string')
+      content.push({ type: 'link', url: part.url });
+    else if (part.type === 'unresolved-mention')
+      content.push({ type: 'unresolved-mention' });
+    else if (part.type === 'mention' && isMentionRef(part.ref)) {
+      if (part.label !== undefined && typeof part.label !== 'string')
+        throw new Error('评论引用名称无效');
+      content.push({
+        type: 'mention',
+        ref: { ...part.ref },
+        ...(part.label ? { label: part.label } : {}),
+        ...(part.ref.kind === 'document' ? documentSnapshot(part) : {}),
+      });
+    } else throw new Error('评论内容包含无效节点');
+  }
+  return { version: 1, content };
+}
+
+/** Preserve document presentation through editing/clipboard without trusting HTML or URLs. */
+export function documentSnapshot(value: {
+  href?: unknown;
+  document?: unknown;
+}) {
+  const href = typeof value.href === 'string' ? safeUrl(value.href) : undefined;
+  const meta =
+    value.document && typeof value.document === 'object'
+      ? (value.document as Record<string, unknown>)
+      : {};
+  const subType =
+    typeof meta.subType === 'number' && Number.isSafeInteger(meta.subType)
+      ? meta.subType
+      : undefined;
+  const iconInfo =
+    typeof meta.iconInfo === 'string' ? meta.iconInfo : undefined;
+  return {
+    ...(href ? { href } : {}),
+    ...(subType !== undefined || iconInfo
+      ? {
+          document: {
+            ...(subType !== undefined ? { subType } : {}),
+            ...(iconInfo ? { iconInfo } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+export function toPlainText(value: CommentValue): string {
+  return value.content
+    .map((part) =>
+      part.type === 'text'
+        ? part.text
+        : part.type === 'break'
+          ? '\n'
+          : part.type === 'link'
+            ? part.url
+            : part.type === 'unresolved-mention'
+              ? '引用信息缺失'
+              : part.ref.kind === 'user'
+                ? `@${part.label || '用户'}`
+                : part.label || part.href || '文档',
+    )
+    .join('');
+}
+
+export function collectMentionRefs(value: CommentValue): MentionRef[] {
+  const refs = new Map<string, MentionRef>();
+  for (const part of value.content)
+    if (part.type === 'mention') refs.set(mentionKey(part.ref), part.ref);
+  return [...refs.values()];
+}
+
+export function mentionLabel(
+  ref: MentionRef,
+  label: string | undefined,
+  result?: MentionResult,
+  strict = false,
+): string {
+  if (result?.status === 'resolved')
+    return result.label || (ref.kind === 'user' ? '用户' : '文档');
+  if (result?.status === 'forbidden')
+    return ref.kind === 'user' ? '无权查看的用户' : '无权查看的文档';
+  if (result?.status === 'not-found')
+    return ref.kind === 'user' ? '用户不存在' : '文档已失效';
+  return (!strict && label) || (ref.kind === 'user' ? '用户' : '文档');
+}
+
+const types: Record<string, string> = {
+  doc: '1',
+  docx: '22',
+  sheets: '3',
+  sheet: '3',
+  base: '8',
+  bitable: '8',
+  wiki: '16',
+  mindnotes: '11',
+  mindnote: '11',
+  slides: '30',
+  file: '12',
+  whiteboard: '38',
+};
+
+/** Only recognised cloud-document hosts/routes become metadata references. Other URLs stay links. */
+export function documentRefFromUrl(url: string): MentionRef | undefined {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+      return undefined;
+    if (
+      ![
+        'feishu.cn',
+        'feishu-boe.cn',
+        'feishu-pre.cn',
+        'larkoffice.com',
+        'larksuite.com',
+        'doubao.com',
+      ].some(
+        (domain) =>
+          parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`),
+      )
+    )
+      return undefined;
+    const match =
+      /^\/(doc|docx|sheets?|base|bitable|wiki|mindnotes?|slides|file|whiteboard)\/([a-zA-Z0-9_-]+)(?:\/|$)/.exec(
+        parsed.pathname,
+      );
+    return match
+      ? { kind: 'document', id: match[2], resourceType: types[match[1]] }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the exact text/mention/link protocol without send-state validation. */
+export function readApiContent(value: CommentValue): CommentApiContent[] {
+  const content: CommentApiContent[] = [];
+  for (const part of normalizeValue(value).content) {
+    if (part.type === 'text' || part.type === 'break') {
+      const text = part.type === 'text' ? part.text : '\n';
+      const previous = content.at(-1);
+      if (previous?.type === 'text') previous.text += text;
+      else content.push({ type: 'text', text });
+    } else if (part.type === 'unresolved-mention')
+      content.push({ type: 'mention' });
+    else if (part.type === 'link')
+      content.push({ type: 'link', url: part.url });
+    else if (part.ref.kind === 'document')
+      content.push({ type: 'link', url: part.href || '' });
+    else content.push({ type: 'mention', userID: apiUserID(part.ref.id) });
+  }
+  return content;
+}
+
+function apiUserID(id: string): number {
+  const number = Number(id);
+  if (
+    !/^[1-9]\d*$/.test(id) ||
+    !Number.isSafeInteger(number) ||
+    String(number) !== id
+  )
+    throw new Error('人员 userID 必须是可精确表示的正整数');
+  return number;
+}
+
+export function fromApiContent(
+  content: readonly CommentApiContent[],
+): CommentValue {
+  if (!Array.isArray(content)) throw new Error('评论 content 必须是数组');
+  const parts = content.map((part): CommentPart => {
+    if (part?.type === 'text' && typeof part.text === 'string')
+      return { type: 'text', text: part.text };
+    if (part?.type === 'mention') {
+      if (part.userID == null) return { type: 'unresolved-mention' };
+      const id = String(part.userID);
+      apiUserID(id);
+      return {
+        type: 'mention',
+        ref: { kind: 'user', id, idType: 'apaas-user' },
+      };
+    }
+    if (part?.type === 'link' && typeof part.url === 'string') {
+      const ref = documentRefFromUrl(part.url);
+      return ref
+        ? { type: 'mention', ref, href: part.url }
+        : { type: 'link', url: part.url };
+    }
+    throw new Error('评论 content 包含未支持的节点');
+  });
+  return normalizeValue({ version: 1, content: parts });
+}