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

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

@@ -0,0 +1,188 @@
+import type { UserInfo, SearchAvatar } from '@lark-apaas/client-toolkit/tools/services';
+
+import type { AccountType } from '@client/src/components/business-ui/api/users/service';
+import type {
+  UserSelectItemValue,
+  UserSelectValue,
+} from '@client/src/components/business-ui/user-select/types';
+import { getI18nText } from '@client/src/components/business-ui/utils/user';
+import type { User } from '@client/src/components/business-ui/types/user';
+
+export function getUserDisplayName(name: UserInfo['name']): string {
+  return name.zh_cn || name.en_us || '';
+}
+
+export function getUserId(
+  user: Pick<UserInfo, 'userID' | 'larkUserID'>,
+  accountType: AccountType,
+): string {
+  if (accountType === 'lark') {
+    return user.larkUserID || `_unknown_${Math.random().toString(36).slice(2)}`;
+  }
+  // 未注册外部联系人没有 userID，暂用 larkUserID 作为临时标识
+  return user.userID || user.larkUserID || `_unknown_${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * 判断用户是否为未注册的外部联系人
+ */
+export function isUnregisteredExternalContact(user: UserSelectItemValue): boolean {
+  const raw = user.raw;
+  return !!raw && !raw.user_id && !!raw.larkUserId;
+}
+
+export function createUnknownUser(id: string): UserSelectItemValue {
+  return {
+    id,
+    name: '未知用户',
+    avatar: undefined,
+    raw: undefined,
+  };
+}
+
+export function userInfoToUser(
+  userInfo: UserInfo & SearchAvatar,
+  accountType: AccountType,
+): UserSelectItemValue {
+  // 构建统一的 User 类型作为 raw 数据
+  const rawUser: User = {
+    user_id: userInfo.userID || undefined,
+    larkUserId: userInfo.larkUserID || undefined,
+    name: userInfo.name,
+    avatar: userInfo.avatar?.image?.large,
+    user_type: userInfo.userType,
+    department: userInfo.department as any,
+  };
+
+  return {
+    id: getUserId(userInfo, accountType),
+    name: getI18nText(userInfo.name),
+    avatar: userInfo.avatar?.image?.large,
+    raw: rawUser,
+  };
+}
+
+export function searchUserInfoToUser(
+  userInfo: UserInfo & { avatar?: string; tenantName?: string },
+  accountType: AccountType,
+): UserSelectItemValue {
+  // 构建统一的 User 类型作为 raw 数据
+  const rawUser: User = {
+    user_id: userInfo.userID || undefined,
+    larkUserId: userInfo.larkUserID || undefined,
+    name: userInfo.name,
+    avatar: userInfo.avatar,
+    user_type: userInfo.userType,
+    department: userInfo.department as any,
+    tenantName: userInfo.tenantName,
+  };
+
+  return {
+    id: getUserId(userInfo, accountType),
+    name: getI18nText(userInfo.name),
+    avatar: userInfo.avatar,
+    raw: rawUser,
+  };
+}
+
+declare global {
+  interface Window {
+    MIAODA_APP_ID?: string;
+    __platform__?: {
+      appId?: string;
+    };
+    appId?: string;
+  }
+}
+
+export function getAppId(path: string): string | null | undefined {
+  if (window?.__platform__?.appId) {
+    return window.__platform__.appId;
+  }
+
+  if (window.MIAODA_APP_ID) {
+    return window.MIAODA_APP_ID;
+  }
+
+  let prefix: string;
+
+  /**
+   * 从路径中提取 appId
+   * @example "/app/my-app/settings" → "my-app"
+   */
+  const appMatch = path.match(/\/app\/([^/]+)/);
+  if (appMatch) {
+    return appMatch[1];
+  }
+
+  // 检查路径是否以固定前缀开头
+  if (path.includes('/ai/feida/runtime/')) {
+    prefix = '/ai/feida/runtime/';
+  } else if (path.includes('/spark/r/')) {
+    prefix = '/spark/r/';
+  } else {
+    prefix = '/ai/miaoda/';
+  }
+
+  // 兼容全栈appId挂载在window上，作为兜底
+  const windowAppId = window.appId || null;
+
+  if (!path.startsWith(prefix)) {
+    return windowAppId;
+  }
+
+  // 截取前缀后的部分
+  const remainder = path.substring(prefix.length);
+
+  // 找到下一个斜杠的位置
+  const nextSlashIndex = remainder.indexOf('/');
+
+  // 如果没有斜杠，返回整个remainder；否则返回斜杠前的部分
+  if (nextSlashIndex === -1) {
+    return remainder || windowAppId;
+  }
+  return remainder.substring(0, nextSlashIndex) || windowAppId;
+}
+
+/**
+ * 从 value 中提取 ID 列表
+ * 支持 User 类型（user_id）和 UserSelectItemValue 类型（id）
+ */
+export function extractIdsFromValue(value: UserSelectValue): string[] {
+  if (value === null || value === undefined) {
+    return [];
+  }
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return [];
+    }
+    // 检查第一个元素判断类型
+    if (typeof value[0] === 'string') {
+      return value as string[];
+    }
+    // 对象数组：可能是 User[] 或 UserSelectItemValue[]
+    return value.map((item: any) => {
+      // UserSelectItemValue 有 id 字段（内部类型）
+      if ('id' in item && item.id) {
+        return item.id;
+      }
+      // User 有 user_id 字段（外部类型）
+      if ('user_id' in item && item.user_id) {
+        return item.user_id;
+      }
+      return '';
+    }).filter(Boolean);
+  }
+  // 单个对象：可能是 User 或 UserSelectItemValue
+  const item = value as any;
+  if ('id' in item && item.id) {
+    return [item.id];
+  }
+  if ('user_id' in item && item.user_id) {
+    return [item.user_id];
+  }
+  return [];
+}

package/template/client/src/components/business-ui/utils/user.ts

@@ -0,0 +1,72 @@
+// client/src/utils/user.ts
+
+import type { I18nText, User, UserInput } from '../types/user';
+
+/**
+ * 获取国际化文本的显示值
+ * @param text 国际化文本或普通字符串
+ * @param locale 语言，默认 zh_cn
+ */
+export function getI18nText(
+  text: I18nText | string | undefined,
+  locale: 'zh_cn' | 'en_us' | 'ja_jp' = 'zh_cn',
+): string {
+  if (!text) return '';
+  if (typeof text === 'string') return text;
+  // 添加更完整的 fallback 逻辑
+  return text[locale] || text.zh_cn || text.en_us || text.ja_jp || '';
+}
+
+/**
+ * 将任意格式的用户数据转换为标准 User 类型（下划线命名）
+ */
+export function normalizeUser(input: UserInput): User {
+  const data = input as any;
+
+  // 提取 user_id（兼容驼峰和下划线）
+  const user_id = data.user_id || data.userId || '';
+
+  // 提取其他字段
+  const larkUserId = data.larkUserId;  // larkUserId 保持驼峰
+  const name = data.name;
+  const avatar = data.avatar;
+  const email = data.email;
+
+  // 提取 user_type（兼容驼峰和下划线）
+  const user_type = data.user_type || data.userType;
+
+  const department = data.department;
+
+  return {
+    user_id,
+    larkUserId,
+    name,
+    avatar,
+    email,
+    user_type,
+    department,
+  };
+}
+
+/**
+ * 验证 user_id 是否有效
+ */
+export function isValidUserId(user_id: string | undefined): boolean {
+  if (!user_id) return false;
+  const trimmed = user_id.trim();
+  if (!trimmed) return false;
+  if (trimmed === '""') return false; // 过滤 AI 可能生成的 ""
+  return true;
+}
+
+/**
+ * 获取用户显示名称
+ * 自动处理 I18nText 类型
+ */
+export function getUserDisplayName(
+  user: User | undefined,
+  locale: 'zh_cn' | 'en_us' | 'ja_jp' = 'zh_cn',
+): string {
+  if (!user) return '';
+  return getI18nText(user.name, locale) || '无效人员';
+}

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

@@ -0,0 +1,134 @@
+# shadcn/ui 组件开发指南
+
+## 核心原则
+
+- 组件位置：`/client/src/components/ui/`
+- 图标库：必须使用 `lucide-react`，禁用 Emoji
+- 查阅源码实现：直接读取组件源码了解最新组件实现
+- 交互系统：Button、Badge 使用 elevate 遮罩系统处理 hover/active 状态（通过 `::after` 伪元素叠加 `--elevate-1` / `--elevate-2`）
+
+## 关键组件规范
+
+#### 1. Button 组件
+
+**导入路径**：`import { Button } from '@/components/ui/button'`
+
+**Props**：
+- `variant`: `"link" | "default" | "destructive" | "outline" | "secondary" | "ghost"` - 按钮样式变体
+
+```tsx
+// ✅ 使用变体
+<Button variant="secondary">标准按钮</Button>
+
+// ✅ 自定义颜色时必须配对前景色
+<Button className="bg-primary text-primary-foreground">自定义按钮</Button>
+```
+
+#### 2. Badge 组件
+
+**导入路径**：`import { Badge } from '@/components/ui/badge'`
+
+**Props**：
+- `variant`: `"default" | "destructive" | "outline" | "secondary"` - 样式变体
+
+```tsx
+// ✅ 使用变体
+<Badge>默认</Badge>
+<Badge variant="secondary">次要</Badge>
+<Badge variant="outline">边框</Badge>
+<Badge variant="destructive">危险</Badge>
+```
+
+#### 3. Alert 组件
+
+**导入路径**：`import { Alert, AlertTitle, AlertDescription, AlertAction } from '@/components/ui/alert'`
+
+**Props**：
+- `variant`: `"default" | "destructive" | "success" | "warning"` - 样式变体
+
+```tsx
+// ✅ default / destructive / success / warning 四种变体
+<Alert variant="success">
+  <CheckCircle className="size-4" />
+  <AlertTitle>操作成功</AlertTitle>
+  <AlertDescription>您的更改已保存</AlertDescription>
+</Alert>
+
+<Alert variant="warning">
+  <AlertTriangle className="size-4" />
+  <AlertTitle>警告</AlertTitle>
+  <AlertDescription>请注意检查</AlertDescription>
+</Alert>
+
+```
+
+#### 4. Empty 组件
+
+**导入路径**：`import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent } from '@/components/ui/empty'`
+
+**子组件 Props**：
+- `EmptyMedia` 组件的 `variant`: `"default" | "icon"` - 媒体展示方式
+
+```tsx
+// 标准结构：EmptyHeader 包含 EmptyMedia + EmptyTitle + EmptyDescription
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <SearchIcon className="size-6" />
+    </EmptyMedia>
+    <EmptyTitle>暂无数据</EmptyTitle>
+    <EmptyDescription>当前没有找到相关内容</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>添加数据</Button>
+  </EmptyContent>
+</Empty>
+```
+
+#### 5. Card Padding 系统
+
+**导入路径**：`import { CardHeader, CardContent, CardFooter } from '@/components/ui/card'`
+
+- `CardHeader`: `p-6` (24px 全方向)
+- `CardContent`: `p-6 pt-0` (与 header 无缝衔接)
+- `CardFooter`: `p-6 pt-0` (与 content 无缝衔接)
+
+#### 6. Dialog 组件
+
+**导入路径**：`import { Dialog, DialogContent } from '@/components/ui/dialog'`
+
+Dialog 默认提供了右上角的close能力，同时也提供了自定义关闭按钮的能力，即通过设置showCloseButton为false来关闭默认的关闭按钮。所以当默认存在close时，禁止在内容区域提供自定义的关闭按钮。
+
+#### 7. Image 组件
+
+**导入路径**：`import { Image } from '@/components/ui/image'`
+
+**Props**：支持原生 `<img>` 标签所有属性。
+
+```typescript
+interface ImageProps extends React.ImgHTMLAttributes<HTMLImageElement> 
+```
+
+**使用规范**：
+
+1. **响应式图片场景**：当图片尺寸需要根据视口宽度变化时，必须设置 `sizes` 属性
+2. **固定尺寸图片场景**：当图片有固定尺寸时，必须设置 `width` 属性（number 类型）
+3. **必须提供有意义的 `alt` 属性**
+
+```tsx
+// ✅ 响应式图片
+<Image
+  src="/path/to/image.jpg"
+  alt="描述文字"
+  sizes="(max-width: 768px) 100vw, 50vw"
+/>
+
+// ✅ 固定尺寸图片（width/height 使用 number）
+<Image
+  src="/path/to/image.jpg"
+  alt="描述文字"
+  width={300}
+  height={200}
+/>
+
+```

package/template/client/src/components/ui/accordion.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+import * as React from "react"
+import * as AccordionPrimitive from "@radix-ui/react-accordion"
+import { ChevronDownIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Accordion({
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("border-b last:border-b-0", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "focus-visible:border-ring focus-visible:ring-ring/20 flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none enabled:hover:underline focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 [&[data-state=open]>svg]:rotate-180",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down overflow-hidden text-sm"
+      {...props}
+    >
+      <div className={cn("pt-0 pb-4", className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }

package/template/client/src/components/ui/alert-dialog.tsx

@@ -0,0 +1,157 @@
+"use client"
+
+import * as React from "react"
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog"
+
+import { cn } from "@/lib/utils"
+import { buttonVariants } from "@/components/ui/button"
+
+function AlertDialog({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
+  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
+}
+
+function AlertDialogTrigger({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>) {
+  return (
+    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
+  )
+}
+
+function AlertDialogPortal({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Portal>) {
+  return (
+    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
+  )
+}
+
+function AlertDialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
+  return (
+    <AlertDialogPrimitive.Overlay
+      data-slot="alert-dialog-overlay"
+      className={cn(
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Content>) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Content
+        data-slot="alert-dialog-content"
+        className={cn(
+          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-sm:max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 max-w-lg",
+          className
+        )}
+        {...props}
+      />
+    </AlertDialogPortal>
+  )
+}
+
+function AlertDialogHeader({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn("text-lg font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogAction({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Action>) {
+  return (
+    <AlertDialogPrimitive.Action
+      className={cn(buttonVariants(), className)}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogCancel({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>) {
+  return (
+    <AlertDialogPrimitive.Cancel
+      className={cn(buttonVariants({ variant: "outline" }), className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  AlertDialog,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+}

package/template/client/src/components/ui/alert.tsx

@@ -0,0 +1,71 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  {
+    variants: {
+      variant: {
+        default: "bg-card text-card-foreground",
+        destructive:
+          "text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90",
+        // 新增语义化 success/warning variant
+        success:
+          "bg-success text-success-foreground border-success/50 [&>svg]:text-success-foreground *:data-[slot=alert-description]:text-success-foreground/90",
+        warning:
+          "bg-warning text-warning-foreground border-warning/50 [&>svg]:text-warning-foreground *:data-[slot=alert-description]:text-warning-foreground/90",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        "text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Alert, AlertTitle, AlertDescription }

package/template/client/src/components/ui/aspect-ratio.tsx

@@ -0,0 +1,11 @@
+"use client"
+
+import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio"
+
+function AspectRatio({
+  ...props
+}: React.ComponentProps<typeof AspectRatioPrimitive.Root>) {
+  return <AspectRatioPrimitive.Root data-slot="aspect-ratio" {...props} />
+}
+
+export { AspectRatio }