@lark-apaas/coding-template-nestjs-react-fullstack 0.1.0-alpha.1

package/template/client/src/components/business-ui/api/user-profiles/queries.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { useQuery, queryOptions, type QueryClient } from '@tanstack/react-query';
+
+import { fetchUserProfile, type AccountType } from './service';
+
+export const userProfileQueries = {
+  all: () => ['userProfiles'] as const,
+  byId: (userId: string, accountType: AccountType = 'apaas') =>
+    queryOptions({
+      queryKey: [...userProfileQueries.all(), 'byId', accountType, userId],
+      queryFn: ({ signal }) => fetchUserProfile(userId, accountType, signal),
+      staleTime: 1 * 60 * 1000,
+      gcTime: 5 * 60 * 1000,
+      enabled: !!userId,
+    }),
+};
+
+export type UseUserProfileOptions = {
+  userId: string;
+  accountType?: AccountType;
+  enabled?: boolean;
+};
+
+/**
+ * 获取用户 Profile 卡片数据的 hook
+ */
+export function useUserProfile(options: UseUserProfileOptions) {
+  const { userId, accountType = 'apaas', enabled = true } = options;
+
+  return useQuery({
+    ...userProfileQueries.byId(userId, accountType),
+    enabled: enabled && !!userId,
+  });
+}
+
+/**
+ * 清除用户 Profile 缓存
+ */
+export function clearUserProfileCache(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: userProfileQueries.all() });
+}

package/template/client/src/components/business-ui/api/user-profiles/service.ts

@@ -0,0 +1,23 @@
+import {
+  UserProfileService,
+  getAssetsUrl,
+  type AccountType,
+  type UserProfileData,
+} from '@lark-apaas/client-toolkit/tools/services';
+
+const userProfileService = new UserProfileService();
+
+/**
+ * 获取用户 Profile 卡片数据
+ */
+export async function fetchUserProfile(
+  userId: string,
+  accountType: AccountType = 'apaas',
+  signal?: AbortSignal,
+): Promise<UserProfileData> {
+  return userProfileService.getUserProfile(userId, accountType, signal);
+}
+
+// Re-export for convenience
+export { getAssetsUrl };
+export type { AccountType, UserProfileData };

package/template/client/src/components/business-ui/api/users/queries.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useQuery, queryOptions, type QueryClient } from '@tanstack/react-query';
+
+import { listUsersByIds, type AccountType } from './service';
+
+export const userQueries = {
+  all: () => ['users'] as const,
+  byIds: (userIds: string[], accountType: AccountType = 'apaas') =>
+    queryOptions({
+      queryKey: [...userQueries.all(), 'byIds', accountType, userIds.join(',')],
+      queryFn: () => listUsersByIds(userIds),
+      staleTime: 1 * 60 * 1000,
+      gcTime: 5 * 60 * 1000,
+      enabled: userIds.length > 0,
+    }),
+};
+
+/**
+ * 批量获取用户信息的 hook
+ */
+export function useUsersByIds(
+  userIds: string[],
+  accountType: AccountType = 'apaas',
+) {
+  return useQuery(userQueries.byIds(userIds, accountType));
+}
+
+/**
+ * 清除用户缓存
+ */
+export function clearUserCache(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: userQueries.all() });
+}

package/template/client/src/components/business-ui/api/users/service.ts

@@ -0,0 +1,40 @@
+import {
+  UserService,
+  type AccountType,
+  type SearchUsersParams,
+  type SearchUsersResponse,
+  type BatchGetUsersResponse,
+  type ConvertExternalContactResponse,
+} from '@lark-apaas/client-toolkit/tools/services';
+
+const userService = new UserService();
+
+/**
+ * 搜索用户
+ */
+export async function searchUsers(
+  params: SearchUsersParams,
+): Promise<SearchUsersResponse> {
+  return userService.searchUsers({ ...params, searchExternalContact: true });
+}
+
+/**
+ * 批量根据用户 ID 查询用户信息
+ */
+export async function listUsersByIds(
+  userIds: string[],
+): Promise<BatchGetUsersResponse> {
+  const numericIds = userIds.filter((id) => !isNaN(Number(id)));
+  return userService.listUsersByIds(numericIds);
+}
+
+/**
+ * 调用开户接口，将外部联系人的 larkUserID 转换为已注册用户
+ */
+export async function convertExternalContact(
+  larkUserID: string,
+): Promise<ConvertExternalContactResponse> {
+  return userService.convertExternalContact(larkUserID);
+}
+
+export type { AccountType, SearchUsersParams, SearchUsersResponse, BatchGetUsersResponse, ConvertExternalContactResponse };

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

@@ -0,0 +1,128 @@
+# ChatSelect 群组选择组件
+
+**组件路径**：`@/components/business-ui/chat-select`
+
+---
+
+## 群组类型
+
+```typescript
+/** 群组数据结构 */
+interface Chat {
+  /** 唯一标识：对应 chatID */
+  id: string;
+  /** 群组名称：内部优先 zh_cn，其次 en_us */
+  name: string;
+  /** 头像：URL 或 16 进制 RGB 颜色 */
+  avatar: string;
+}
+```
+
+---
+
+## 功能概述
+
+- 群组字段选择组件，用于表单中录入"群组"字段
+- 通过触发器打开弹层，弹层内置搜索功能（始终可用）
+- **仅支持 ID 模式**：`value/onChange` 只使用群组 `chatID`（string），该 ID 为飞书群聊 ID。
+- 组件在 UI 上可展示群组信息（头像/名称），但对外值仅返回/接收 `chatID`
+- 选择后自动回显已选群组信息：群头像 + 群名称（多选以 tag 形式展示）
+- 组件自带群组检索能力，无需额外传搜索接口/数据源
+
+## 类型定义
+
+```typescript
+/** 触发器类型 */
+type TriggerType = 'button' | 'search' | 'custom';
+
+/** 单选模式 Props */
+interface ChatSelectSingleProps {
+  /** 当前选中的群组 ID，空值为 null */
+  value: string | null;
+  /** 选中变化回调 */
+  onChange: (value: string | null) => void;
+  /** 是否多选，单选时为 false 或不传 */
+  multiple?: false;
+  /** 触发器类型，仅影响样式，不影响搜索功能 */
+  triggerType?: TriggerType;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 占位文本 */
+  placeholder?: string;
+}
+
+/** 多选模式 Props */
+interface ChatSelectMultipleProps {
+  /** 当前选中的群组 ID 列表，空值为 [] */
+  value: string[];
+  /** 选中变化回调 */
+  onChange: (value: string[]) => void;
+  /** 是否多选，多选时为 true */
+  multiple: true;
+  /** 触发器类型 */
+  triggerType?: TriggerType;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 占位文本 */
+  placeholder?: string;
+}
+
+type ChatSelectProps = ChatSelectSingleProps | ChatSelectMultipleProps;
+```
+
+## Props 说明
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string \| null` / `string[]` | - | **必填**。单选传 `string \| null`（群组 ID），多选传 `string[]` |
+| `onChange` | `function` | - | **必填**。值变化回调，返回值形态与 `value` 匹配 |
+| `multiple` | `boolean` | `false` | 是否多选 |
+| `triggerType` | `'button' \| 'search' \| 'custom'` | `'button'` | 触发器类型，仅影响样式 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `placeholder` | `string` | `'请选择'` | 占位文本 |
+| `getOptionDisabled` | `(chat) => boolean` | - | 判断选项是否禁用 |
+
+## 受控规范
+
+> ⚠️ **强约束**
+
+1. **必须受控**：始终传 `value` + `onChange`
+2. **禁止传**：`undefined` / 群组对象 / 其他类型
+3. **空值规则**：
+   - 单选清空：`null`
+   - 多选清空：`[]`
+
+## 使用示例
+
+```tsx
+import { useState } from 'react';
+import { ChatSelect } from '@/components/business-ui/chat-select';
+
+// 单选
+function SingleSelectExample() {
+  const [chatId, setChatId] = useState<string | null>(null);
+
+  return (
+    <ChatSelect
+      value={chatId}
+      onChange={setChatId}
+      placeholder="请选择群组"
+    />
+  );
+}
+
+// 多选
+function MultipleSelectExample() {
+  const [chatIds, setChatIds] = useState<string[]>([]);
+
+  return (
+    <ChatSelect
+      multiple
+      value={chatIds}
+      onChange={setChatIds}
+      placeholder="请选择群组"
+      getOptionDisabled={(chat) => chat.id === 'disabled-id'}
+    />
+  );
+}
+```

package/template/client/src/components/business-ui/chat-select/chat-item.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import React from 'react';
+
+import type { Chat } from '@client/src/components/business-ui/chat-select/types';
+import { BaseComboboxItem } from '@client/src/components/business-ui/entity-combobox/base-combobox-item';
+import { HighlightText } from '@client/src/components/business-ui/entity-combobox/highlight-text';
+import { isHexColor } from '@client/src/components/business-ui/entity-combobox/item-pill';
+import {
+  listItemAvatarVariants,
+  listItemNameVariants,
+  listItemSubTextVariants,
+  listItemVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import { cn } from '@/lib/utils';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+
+const ExternalChatTag = () => (
+  <span className="inline-flex shrink-0 items-center rounded-sm bg-blue-500/20 px-1.5 py-0.5 text-xs leading-4 text-blue-900 dark:text-blue-200">
+    外部
+  </span>
+);
+
+export const ChatItem = ({
+  chatValue,
+  isSelected,
+  className,
+  size = 'medium',
+  searchKeyword,
+  disabled,
+}: {
+  chatValue: Chat;
+  isSelected: boolean;
+  className?: string;
+  size?: ComboboxSize;
+  searchKeyword?: string;
+  disabled?: boolean;
+}) => {
+  const chat = chatValue.raw;
+  const displayName = chat?.name?.zh_cn || chat?.name?.en_us || chatValue.name;
+  const userCount = chat?.userCount;
+  const isExternal = chat?.isExternal;
+
+  const isHex = isHexColor(chat?.avatar);
+
+  const avatarImage = !isHex ? (
+    <AvatarImage src={chat?.avatar} alt={displayName} loading="eager" />
+  ) : (
+    <AvatarFallback style={{ backgroundColor: chat?.avatar }}>
+      {displayName?.charAt?.(0).toUpperCase()}
+    </AvatarFallback>
+  );
+
+  return (
+    <BaseComboboxItem
+      item={chatValue}
+      getItemValue={(item) => item}
+      isSelected={isSelected}
+      className={cn(listItemVariants({ size }), className)}
+      disabled={disabled}
+    >
+      <Avatar className={listItemAvatarVariants({ size })}>
+        {chat?.avatar ? (
+          avatarImage
+        ) : (
+          <AvatarFallback>{displayName?.charAt?.(0)}</AvatarFallback>
+        )}
+      </Avatar>
+      <div className="flex min-w-0 flex-1 items-center gap-1">
+        <HighlightText
+          text={chatValue.name}
+          highlight={searchKeyword}
+          className={cn(listItemNameVariants({ size }), 'truncate')}
+        />
+        {userCount != null && (
+          <span className={cn(listItemSubTextVariants({ size }), 'shrink-0')}>
+            ({userCount})
+          </span>
+        )}
+        {isExternal && <ExternalChatTag />}
+      </div>
+    </BaseComboboxItem>
+  );
+};

package/template/client/src/components/business-ui/chat-select/chat-select-tag.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+import React from 'react';
+
+import { X } from 'lucide-react';
+
+import type { Chat } from '@client/src/components/business-ui/chat-select/types';
+import {
+  ItemPill,
+  renderPillAvatar,
+} from '@client/src/components/business-ui/entity-combobox/item-pill';
+import {
+  tagCloseIconVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import { Skeleton } from '@/components/ui/skeleton';
+
+export const ChatSelectTag = ({
+  chatValue,
+  onClose,
+  maxTextLength,
+  className,
+  size = 'medium',
+  disabled,
+  isLoading,
+}: {
+  chatValue: Chat;
+  onClose: (value: Chat, e: React.MouseEvent) => void;
+  maxTextLength?: number;
+  className?: string;
+  size?: ComboboxSize;
+  disabled?: boolean;
+  /**
+   * 是否正在加载群组信息（ID 模式下查询中）
+   */
+  isLoading?: boolean;
+}) => {
+  const chat = chatValue.raw;
+
+  const handleClose = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onClose(chatValue, e);
+  };
+
+  const closeButton = !disabled ? (
+    <button
+      type="button"
+      className="rounded-sm text-foreground opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none"
+      onClick={handleClose}
+    >
+      <X className={tagCloseIconVariants({ size })} />
+      <span className="sr-only">移除 {chatValue.name}</span>
+    </button>
+  ) : null;
+
+  // 加载中状态显示 Skeleton
+  if (isLoading && !chat) {
+    return (
+      <div className="inline-flex items-center gap-1 rounded-md bg-secondary px-1.5 py-0.5">
+        <Skeleton className="h-4 w-4 rounded-full" />
+        <Skeleton className="h-3 w-12" />
+      </div>
+    );
+  }
+
+  const avatarElement = renderPillAvatar({
+    avatarUrl: chatValue.avatar || chat?.avatar,
+    label: chatValue.name,
+    size,
+  });
+
+  return (
+    <ItemPill
+      label={chatValue.name}
+      avatar={avatarElement}
+      className={className}
+      maxTextLength={maxTextLength}
+      suffix={closeButton}
+      size={size}
+      disabled={disabled}
+    />
+  );
+};

package/template/client/src/components/business-ui/chat-select/chat-select.tsx

@@ -0,0 +1,197 @@
+'use client';
+
+import React, { useCallback, useMemo } from 'react';
+
+import { searchChats } from '@client/src/components/business-ui/api/chats/service';
+import { ChatItem } from '@client/src/components/business-ui/chat-select/chat-item';
+import { ChatSelectTag } from '@client/src/components/business-ui/chat-select/chat-select-tag';
+import type {
+  Chat,
+  ChatSelectProps,
+} from '@client/src/components/business-ui/chat-select/types';
+import { useChatValue } from '@client/src/components/business-ui/chat-select/use-chat-value';
+import { chatInfoToChat } from '@client/src/components/business-ui/chat-select/utils';
+import { BaseCombobox } from '@client/src/components/business-ui/entity-combobox/base-combobox';
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+
+function createChatsFetcher(pageSize: number = 100) {
+  return async (search: string) => {
+    const response = await searchChats({ query: search, pageSize });
+    const chatList = response?.data?.result?.chatResult?.items || [];
+    return { items: chatList.map((chat) => chatInfoToChat(chat)) };
+  };
+}
+
+// 内部包装组件用于获取 context 中的 size
+const ChatItemWrapper = ({
+  chatValue,
+  isSelected,
+  className,
+  disabled,
+}: {
+  chatValue: Chat;
+  isSelected: boolean;
+  className?: string;
+  disabled?: boolean;
+}) => {
+  const { size, searchValue } = useEntityComboboxContext();
+  return (
+    <ChatItem
+      chatValue={chatValue}
+      isSelected={isSelected}
+      className={className}
+      size={size}
+      searchKeyword={searchValue}
+      disabled={disabled}
+    />
+  );
+};
+
+const ChatSelectTagWrapper = ({
+  chatValue,
+  onClose,
+  className,
+  disabled,
+  isLoading,
+}: {
+  chatValue: Chat;
+  onClose: (value: Chat, e: React.MouseEvent) => void;
+  className?: string;
+  disabled?: boolean;
+  isLoading?: boolean;
+}) => {
+  const { size } = useEntityComboboxContext();
+  return (
+    <ChatSelectTag
+      chatValue={chatValue}
+      onClose={onClose}
+      className={className}
+      size={size}
+      disabled={disabled}
+      isLoading={isLoading}
+    />
+  );
+};
+
+export const ChatSelect: React.FC<ChatSelectProps> = (props) => {
+  const {
+    size = 'medium',
+    triggerType = 'button',
+    renderTrigger,
+    multiple = false,
+    value,
+    valueType = 'string',
+    defaultValue,
+    onChange,
+    defaultOpen,
+    disabled,
+    autoFocus,
+    required,
+    name,
+    className,
+    classNames,
+    placeholder = '请选择',
+    emptyText = '没有匹配结果，换个关键词试试吧',
+    tagClosable,
+    maxTagCount,
+    onSelect,
+    onDeselect,
+    onClear,
+    onFocus,
+    onBlur,
+    slotProps,
+    getOptionDisabled,
+  } = props;
+
+  const isControlled = value !== undefined;
+
+  // 使用 useChatValue 处理不同类型的 value（包括 defaultValue）
+  const { internalValue, isLoading, toExternalValue } = useChatValue(
+    value ?? null,
+    multiple,
+    valueType,
+  );
+
+  // 同样处理 defaultValue，确保 ID 字符串类型的 defaultValue 也能正确解析
+  const { internalValue: internalDefaultValue } = useChatValue(
+    defaultValue ?? null,
+    multiple,
+    valueType,
+  );
+
+  const fetchFn = useMemo(() => createChatsFetcher(), []);
+
+  // 包装 onChange，根据输入模式转换输出格式
+  const handleChange = useCallback(
+    (newValue: Chat | Chat[] | null) => {
+      if (!onChange) return;
+
+      const externalValue = toExternalValue(newValue, multiple);
+      (onChange as (value: unknown) => void)(externalValue);
+    },
+    [onChange, toExternalValue, multiple],
+  );
+
+  const renderTagWithLoading = useCallback(
+    (
+      chatValue: Chat,
+      onClose: (value: Chat, e: React.MouseEvent) => void,
+      tagDisabled?: boolean,
+    ) => (
+      <ChatSelectTagWrapper
+        key={chatValue.id}
+        chatValue={chatValue}
+        onClose={onClose}
+        disabled={tagDisabled}
+        isLoading={isLoading}
+      />
+    ),
+    [isLoading],
+  );
+
+  return (
+    <BaseCombobox
+      autoFocus={autoFocus}
+      className={className}
+      classNames={classNames}
+      debounce={300}
+      defaultOpen={defaultOpen}
+      defaultValue={internalDefaultValue}
+      disabled={disabled}
+      emptyText={emptyText}
+      fetchFn={fetchFn}
+      getItemLabel={(chatValue: Chat) => chatValue.name}
+      getItemValue={(chatValue: Chat) => chatValue}
+      getOptionDisabled={getOptionDisabled}
+      maxTagCount={maxTagCount}
+      multiple={multiple}
+      name={name}
+      onBlur={onBlur}
+      onChange={handleChange}
+      onClear={onClear}
+      onDeselect={onDeselect}
+      onFocus={onFocus}
+      onSelect={onSelect}
+      placeholder={placeholder}
+      renderItem={(chatValue, isSelected, itemClassName, itemDisabled) => (
+        <ChatItemWrapper
+          key={chatValue.id}
+          chatValue={chatValue}
+          isSelected={isSelected}
+          className={itemClassName}
+          disabled={itemDisabled}
+        />
+      )}
+      renderTag={renderTagWithLoading}
+      renderTrigger={renderTrigger}
+      required={required}
+      searchPlaceholder=""
+      showSearch
+      size={size}
+      slotProps={slotProps}
+      tagClosable={tagClosable}
+      triggerType={triggerType}
+      value={isControlled ? internalValue : undefined}
+    />
+  );
+};

package/template/client/src/components/business-ui/chat-select/index.tsx

@@ -0,0 +1,12 @@
+export { ChatSelect } from '@client/src/components/business-ui/chat-select/chat-select';
+export type {
+  ChatInfo,
+  Chat,
+  ChatSelectProps,
+  ChatSelectValue,
+  ValueType as ChatSelectValueType,
+} from '@client/src/components/business-ui/chat-select/types';
+export {
+  extractIdsFromValue,
+  isIdModeValue,
+} from '@client/src/components/business-ui/chat-select/utils';