---
description: "Shadcn-ui 管理页开发指令"
---

## 概述
基于 `src/client/admin/pages/Users.tsx` 中用户管理页的实现，提取可复用的开发模式和最佳实践，适用于基于 Shadcn-ui 的管理后台页面开发。

## 页面结构规范

### 1. 文件位置
- **管理后台页面**: `src/client/admin/pages/[EntityName].tsx`

### 2. 页面组件结构
```typescript
// 1. 类型导入和定义
type CreateRequest = InferRequestType<typeof client.$post>['json'];
type UpdateRequest = InferRequestType<typeof client[':id']['$put']>['json'];
type EntityResponse = InferResponseType<typeof client.$get, 200>['data'][0];

// 2. 表单Schema直接使用后端定义
const createFormSchema = CreateEntityDto;
const updateFormSchema = UpdateEntityDto;

// 3. 主页面组件
export const EntityPage = () => {
  // 状态管理
  const [searchParams, setSearchParams] = useState({ page: 1, limit: 10, search: '' });
  const [isModalOpen, setIsModalOpen] = useState(false);
  const [editingEntity, setEditingEntity] = useState<any>(null);
  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
  const [entityToDelete, setEntityToDelete] = useState<number | null>(null);
  
  // 表单实例
  const createForm = useForm<CreateRequest>({...});
  const updateForm = useForm<UpdateRequest>({...});
  
  // 数据查询
  const { data, isLoading, refetch } = useQuery({...});
  
  // 业务逻辑函数
  const handleSearch = () => {...};
  const handleCreateEntity = () => {...};
  const handleEditEntity = () => {...};
  const handleDeleteEntity = () => {...};
  
  // 渲染
  return (...);
};
```

## 核心开发模式

### 1. 类型驱动的开发
- **RPC类型提取**: 使用 `InferRequestType` 和 `InferResponseType` 从后端API自动提取类型
- **Schema复用**: 直接使用后端定义的Zod Schema作为表单验证
- **类型安全**: 所有API调用都有完整的TypeScript类型支持

### 2. 状态管理模式
```typescript
// 分页和搜索参数
const [searchParams, setSearchParams] = useState({
  page: 1,
  limit: 10,
  search: '',
  // 其他筛选条件...
});

// 模态框状态
const [isModalOpen, setIsModalOpen] = useState(false);
const [editingEntity, setEditingEntity] = useState<any>(null);
const [isCreateForm, setIsCreateForm] = useState(true);
```

### 3. 数据获取模式
```typescript
const { data, isLoading, refetch } = useQuery({
  queryKey: ['entities', searchParams],
  queryFn: async () => {
    const res = await entityClient.$get({
      query: {
        page: searchParams.page,
        pageSize: searchParams.limit,
        keyword: searchParams.search,
        // 其他查询参数...
      }
    });
    if (res.status !== 200) throw new Error('获取列表失败');
    return await res.json();
  }
});
```

## 页面布局规范

### 1. 页面标题区域
```tsx
<div className="flex justify-between items-center">
  <h1 className="text-2xl font-bold">页面标题</h1>
  <Button onClick={handleCreateEntity}>
    <Plus className="mr-2 h-4 w-4" />
    创建实体
  </Button>
</div>
```

### 2. 搜索区域
```tsx
<Card>
  <CardHeader>
    <CardTitle>列表标题</CardTitle>
    <CardDescription>列表描述信息</CardDescription>
  </CardHeader>
  <CardContent>
    <div className="mb-4">
      <form onSubmit={handleSearch} className="flex gap-2">
        <div className="relative flex-1 max-w-sm">
          <Search className="absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
          <Input
            placeholder="搜索提示..."
            value={searchParams.search}
            onChange={(e) => setSearchParams(prev => ({ ...prev, search: e.target.value }))}
            className="pl-8"
          />
        </div>
        <Button type="submit" variant="outline">
          搜索
        </Button>
      </form>
    </div>
  </CardContent>
</Card>
```

### 3. 数据表格
```tsx
<div className="rounded-md border">
  <Table>
    <TableHeader>
      <TableRow>
        <TableHead>列标题1</TableHead>
        <TableHead>列标题2</TableHead>
        <TableHead className="text-right">操作</TableHead>
      </TableRow>
    </TableHeader>
    <TableBody>
      {data.map((item) => (
        <TableRow key={item.id}>
          <TableCell>{item.field1}</TableCell>
          <TableCell>{item.field2}</TableCell>
          <TableCell className="text-right">
            <div className="flex justify-end gap-2">
              <Button variant="ghost" size="icon" onClick={() => handleEdit(item)}>
                <Edit className="h-4 w-4" />
              </Button>
              <Button variant="ghost" size="icon" onClick={() => handleDelete(item.id)}>
                <Trash2 className="h-4 w-4" />
              </Button>
            </div>
          </TableCell>
        </TableRow>
      ))}
    </TableBody>
  </Table>
</div>

{data?.data.length === 0 && !isLoading && (
  <div className="text-center py-8">
    <p className="text-muted-foreground">暂无数据</p>
  </div>
)}

<DataTablePagination
  currentPage={searchParams.page}
  pageSize={searchParams.limit}
  totalCount={data?.pagination.total || 0}
  onPageChange={(page, limit) => setSearchParams(prev => ({ ...prev, page, limit }))}
/>
```

## 表单开发模式

### 1. 表单组件结构
```typescript
// 创建表单
const createForm = useForm<CreateRequest>({
  resolver: zodResolver(createFormSchema),
  defaultValues: {
    // 默认值设置
  },
});

// 更新表单
const updateForm = useForm<UpdateRequest>({
  resolver: zodResolver(updateFormSchema),
  defaultValues: {
    // 更新时默认值
  },
});
```

### 2. 模态框表单（创建/编辑分离模式）

将 创建/编辑表单分离
不要 <Form {...(isCreateForm ? createForm : updateForm)}></Form>
要     
{isCreateForm ? (
  // 创建表单（独立渲染）
  <Form {...createForm}>
  </Form>
) : (
  // 编辑表单（独立渲染）
  <Form {...updateForm}>
  </Form>
)}

```tsx
<Dialog open={isModalOpen} onOpenChange={setIsModalOpen}>
  <DialogContent className="sm:max-w-[500px] max-h-[90vh] overflow-y-auto">
    <DialogHeader>
      <DialogTitle>{isCreateForm ? '创建实体' : '编辑实体'}</DialogTitle>
      <DialogDescription>
        {isCreateForm ? '创建一个新的实体' : '编辑现有实体信息'}
      </DialogDescription>
    </DialogHeader>
    
    {isCreateForm ? (
      // 创建表单（独立渲染）
      <Form {...createForm}>
        <form onSubmit={createForm.handleSubmit(handleCreateSubmit)} className="space-y-4">
          {/* 创建专用字段 */}
          <DialogFooter>
            <Button type="button" variant="outline" onClick={() => setIsModalOpen(false)}>
              取消
            </Button>
            <Button type="submit">创建</Button>
          </DialogFooter>
        </form>
      </Form>
    ) : (
      // 编辑表单（独立渲染）
      <Form {...updateForm}>
        <form onSubmit={updateForm.handleSubmit(handleUpdateSubmit)} className="space-y-4">
          {/* 编辑专用字段 */}
          <DialogFooter>
            <Button type="button" variant="outline" onClick={() => setIsModalOpen(false)}>
              取消
            </Button>
            <Button type="submit">更新</Button>
          </DialogFooter>
        </form>
      </Form>
    )}
  </DialogContent>
</Dialog>
```

### 3. 表单字段模式
```tsx
<FormField
  control={form.control}
  name="fieldName"
  render={({ field }) => (
    <FormItem>
      <FormLabel className="flex items-center">
        字段标签
        {isRequired && <span className="text-red-500 ml-1">*</span>}
      </FormLabel>
      <FormControl>
        <Input placeholder="请输入..." {...field} />
      </FormControl>
      <FormDescription>字段描述信息</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

## 图片上传集成

### 1. ImageSelector组件使用
```tsx
import { ImageSelector } from '@/client/admin/components/ImageSelector';

<FormField
  control={form.control}
  name="avatarFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>头像</FormLabel>
      <FormControl>
        <ImageSelector
          value={field.value || undefined}
          onChange={(value) => field.onChange(value)}
          maxSize={2} // MB
          uploadPath="/avatars"
          uploadButtonText="上传头像"
          previewSize="medium"
          placeholder="选择头像"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

## 文件上传集成

### 1. FileSelector组件使用
```tsx
import { FileSelector } from '@/client/admin/components/FileSelector';

<FormField
  control={form.control}
  name="avatarFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>头像</FormLabel>
      <FormControl>
        <FileSelector
          value={field.value || undefined}
          onChange={(value) => field.onChange(value)}
          maxSize={2} // MB
          uploadPath="/avatars"
          uploadButtonText="上传头像"
          previewSize="medium"
          placeholder="选择头像"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

## 状态管理最佳实践

### 1. 状态提升策略
- **表单状态**: 使用React Hook Form管理
- **UI状态**: 使用useState管理模态框、加载状态等
- **服务器状态**: 使用React Query管理数据获取和缓存

### 2. 数据刷新策略
```typescript
// 操作成功后刷新数据
const handleCreateSubmit = async (data: CreateRequest) => {
  try {
    const res = await entityClient.$post({ json: data });
    if (res.status !== 201) throw new Error('创建失败');
    toast.success('创建成功');
    setIsModalOpen(false);
    refetch(); // 刷新数据
  } catch (error) {
    toast.error('操作失败，请重试');
  }
};
```

## 加载状态处理

### 1. 骨架屏模式

#### 1.1 导入依赖
```typescript
import { Skeleton } from '@/client/components/ui/skeleton';
```

#### 1.2 完整骨架屏实现
```tsx
if (isLoading) {
  return (
    <div className="space-y-4">
      {/* 标题区域骨架 */}
      <div className="flex justify-between items-center">
        <Skeleton className="h-8 w-48" />
        <Skeleton className="h-10 w-32" />
      </div>
      
      {/* 搜索区域骨架 */}
      <Card>
        <CardHeader>
          <Skeleton className="h-6 w-1/4" />
        </CardHeader>
        <CardContent>
          <Skeleton className="h-10 w-full max-w-sm" />
        </CardContent>
      </Card>
      
      {/* 表格骨架 */}
      <Card>
        <CardHeader>
          <Skeleton className="h-6 w-1/3" />
        </CardHeader>
        <CardContent>
          <Table>
            <TableHeader>
              <TableRow>
                {[...Array(5)].map((_, i) => (
                  <TableHead key={i}>
                    <Skeleton className="h-4 w-full" />
                  </TableHead>
                ))}
              </TableRow>
            </TableHeader>
            <TableBody>
              {[...Array(5)].map((_, i) => (
                <TableRow key={i}>
                  {[...Array(5)].map((_, j) => (
                    <TableCell key={j}>
                      <Skeleton className="h-4 w-full" />
                    </TableCell>
                  ))}
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </CardContent>
      </Card>
    </div>
  );
}
```

#### 1.3 简化骨架屏（推荐）
```tsx
if (isLoading) {
  return (
    <div className="space-y-4">
      <div className="flex justify-between items-center">
        <Skeleton className="h-8 w-48" />
        <Skeleton className="h-10 w-32" />
      </div>
      
      <Card>
        <CardContent className="pt-6">
          <div className="space-y-3">
            {[...Array(5)].map((_, i) => (
              <div key={i} className="flex gap-4">
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 w-20" />
              </div>
            ))}
          </div>
        </CardContent>
      </Card>
    </div>
  );
}
```

### 2. 空数据状态
```tsx
{users.length === 0 && !isLoading && (
  <div className="text-center py-8">
    <p className="text-muted-foreground">暂无数据</p>
  </div>
)}
```

## 错误处理模式

### 1. API错误处理
```typescript
try {
  const res = await entityClient.$post({ json: data });
  if (res.status !== 201) throw new Error('操作失败');
  toast.success('操作成功');
} catch (error) {
  console.error('操作失败:', error);
  toast.error('操作失败，请重试');
}
```

### 2. 删除确认模式
```tsx
const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
const [entityToDelete, setEntityToDelete] = useState<number | null>(null);

// 删除确认对话框
<Dialog open={deleteDialogOpen} onOpenChange={setDeleteDialogOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>确认删除</DialogTitle>
      <DialogDescription>
        确定要删除这个实体吗？此操作无法撤销。
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline" onClick={() => setDeleteDialogOpen(false)}>
        取消
      </Button>
      <Button variant="destructive" onClick={confirmDelete}>
        删除
      </Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// 删除成功状态码为204
const confirmDelete = async () => {
  if (!entityToDelete) return;
  
  try {
    const res = await entityClient[':id']['$delete']({
      param: { id: entityToDelete.toString() }
    });
    
    if (res.status === 204) {
      toast.success('删除成功');
      setDeleteDialogOpen(false);
      refetch(); // 刷新数据
    } else {
      throw new Error('删除失败');
    }
  } catch (error) {
    toast.error('删除失败，请重试');
  }
};
```

## 样式规范

### 1. 间距系统
- 页面标题区域: `space-y-4`
- 卡片内容: `space-y-4`
- 表单字段: `space-y-4`
- 按钮组: `gap-2`

### 2. 响应式设计
- 模态框最大宽度: `sm:max-w-[500px]`
- 模态框最大高度: `max-h-[90vh]`
- 搜索输入框: `max-w-sm`

### 3. 视觉层次
- 标题: `text-2xl font-bold`
- 卡片标题: `text-lg font-semibold`
- 描述文字: `text-sm text-muted-foreground`

## 开发流程

### 1. 创建新管理页面
1. 复制 `Users.tsx` 作为模板
2. 替换以下部分：
   - API客户端导入
   - 类型定义
   - 表单Schema引用
   - 页面标题和描述
   - 表格列定义
   - 表单字段定义
3. 根据业务需求调整字段和逻辑

### 2. 字段映射规范
- **文本字段**: 使用 `Input`
- **长文本**: 使用 `Textarea`
- **选择字段**: 使用 `Select`
- **开关字段**: 使用 `Switch`
- **日期字段**: 使用 `DatePicker`
- **图片字段**: 使用 `ImageSelector`

### 3. 业务逻辑复用
- 保持相同的CRUD操作模式
- 复用分页、搜索、排序逻辑
- 统一的状态管理模式
- 一致的表单验证和错误处理

## 高级组件集成

### 1. DataTablePagination 分页组件

#### 1.1 使用方式
```tsx
import { DataTablePagination } from '@/client/admin/components/DataTablePagination';

<DataTablePagination
  currentPage={searchParams.page}
  pageSize={searchParams.limit}
  totalCount={data?.pagination.total || 0}
  onPageChange={(page, limit) => setSearchParams(prev => ({ ...prev, page, limit }))}
/>
```

#### 1.2 参数说明
| 参数 | 类型 | 描述 |
|------|------|------|
| currentPage | number | 当前页码 |
| pageSize | number | 每页显示条数 |
| totalCount | number | 总记录数 |
| onPageChange | function | 页码变化回调函数 |

#### 1.3 集成到状态管理
```typescript
const [searchParams, setSearchParams] = useState({
  page: 1,
  limit: 10,
  search: ''
});

// 在数据查询中
const { data } = useQuery({
  queryKey: ['entities', searchParams],
  queryFn: async () => {
    const res = await client.$get({
      query: {
        page: searchParams.page,
        pageSize: searchParams.limit,
        keyword: searchParams.search
      }
    });
    return await res.json();
  }
});
```

### 2. 关联实体Selector组件

#### 2.1 AdvertisementTypeSelector 示例
```tsx
import AdvertisementTypeSelector from '@/client/admin/components/AdvertisementTypeSelector';

<FormField
  control={form.control}
  name="typeId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告类型</FormLabel>
      <FormControl>
        <AdvertisementTypeSelector
          value={field.value}
          onChange={field.onChange}
          placeholder="请选择广告类型"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

#### 2.2 自定义Selector开发模式
```typescript
// 通用Selector接口设计
interface EntitySelectorProps {
  value?: number;
  onChange?: (value: number) => void;
  placeholder?: string;
  disabled?: boolean;
}

// 实现模式
const EntitySelector: React.FC<EntitySelectorProps> = ({
  value,
  onChange,
  placeholder = "请选择",
  disabled
}) => {
  const { data } = useQuery({
    queryKey: ['entities'],
    queryFn: async () => {
      const res = await entityClient.$get();
      return await res.json();
    }
  });

  return (
    <Select value={value?.toString()} onValueChange={(v) => onChange?.(parseInt(v))}>
      <SelectTrigger disabled={disabled}>
        <SelectValue placeholder={placeholder} />
      </SelectTrigger>
      <SelectContent>
        {data?.data.map((item) => (
          <SelectItem key={item.id} value={item.id.toString()}>
            {item.name}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  );
};
```

#### 2.3 图片选择器集成
```tsx
import ImageSelector from '@/client/admin/components/ImageSelector';

<FormField
  control={form.control}
  name="imageFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告图片</FormLabel>
      <FormControl>
        <ImageSelector
          value={field.value || undefined}
          onChange={field.onChange}
          maxSize={2} // MB
          uploadPath="/advertisements"
          uploadButtonText="上传广告图片"
          previewSize="medium"
          placeholder="选择广告图片"
          title="选择广告图片"
          description="上传新图片或从已有图片中选择"
        />
      </FormControl>
      <FormDescription>推荐尺寸：1200x400px，支持jpg、png格式</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

### 3. 复杂字段展示模式

#### 3.1 关联实体字段展示
```tsx
<TableCell>
  {advertisement.advertisementType?.name || '-'}
</TableCell>
```

#### 3.2 状态字段展示
```tsx
<TableCell>
  <Badge variant={advertisement.status === 1 ? 'default' : 'secondary'}>
    {advertisement.status === 1 ? '启用' : '禁用'}
  </Badge>
</TableCell>
```

#### 3.3 图片字段展示
```tsx
<TableCell>
  {advertisement.imageFile?.fullUrl ? (
    <img
      src={advertisement.imageFile.fullUrl}
      alt={advertisement.title || '图片'}
      className="w-16 h-10 object-cover rounded"
      onError={(e) => {
        e.currentTarget.src = '/placeholder.png';
      }}
    />
  ) : (
    <span className="text-muted-foreground text-xs">无图片</span>
  )}
</TableCell>
```

### 4. 表单字段类型映射

#### 4.1 标准字段映射
| 字段类型 | 组件 | 示例 |
|----------|------|------|
| 文本输入 | Input | `<Input placeholder="请输入标题" {...field} />` |
| 长文本 | Textarea | `<Textarea placeholder="请输入描述" {...field} />` |
| 选择器 | Select | `<Select value={field.value} onValueChange={field.onChange}>` |
| 数字输入 | Input | `<Input type="number" {...field} />` |
| 日期选择 | DatePicker | `<DatePicker selected={field.value} onChange={field.onChange} />` |
| 开关 | Switch | `<Switch checked={field.value} onCheckedChange={field.onChange} />` |
| 文件上传 | ImageSelector | `<ImageSelector value={field.value} onChange={field.onChange} />` |

#### 4.2 关联实体选择
```tsx
// 直接使用Selector组件
<FormField
  control={form.control}
  name="typeId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告类型</FormLabel>
      <FormControl>
        <AdvertisementTypeSelector {...field} />
      </FormControl>
    </FormItem>
  )}
/>
```

### 4.3 日期格式化规范

#### 4.3.1 导入依赖
```typescript
import { format } from 'date-fns';
```

#### 4.3.2 日期显示格式
```tsx
// 标准日期时间格式：yyyy-MM-dd HH:mm
<TableCell>
  {user.createdAt ? format(new Date(user.createdAt), 'yyyy-MM-dd HH:mm') : '-'}
</TableCell>

// 仅日期格式：yyyy-MM-dd
<TableCell>
  {user.birthday ? format(new Date(user.birthday), 'yyyy-MM-dd') : '-'}
</TableCell>

// 完整时间格式：yyyy-MM-dd HH:mm:ss
<TableCell>
  {user.updatedAt ? format(new Date(user.updatedAt), 'yyyy-MM-dd HH:mm:ss') : '-'}
</TableCell>
```

#### 4.3.3 日期输入格式
```tsx
// 在表单中使用日期选择器
<FormField
  control={form.control}
  name="startDate"
  render={({ field }) => (
    <FormItem>
      <FormLabel>开始日期</FormLabel>
      <FormControl>
        <Input
          type="date"
          {...field}
          value={field.value ? format(new Date(field.value), 'yyyy-MM-dd') : ''}
          onChange={(e) => field.onChange(e.target.value)}
        />
      </FormControl>
    </FormItem>
  )}
/>
```

#### 4.3.4 相对时间显示（可选）
```typescript
import { formatDistanceToNow } from 'date-fns';
import { zhCN } from 'date-fns/locale';

// 相对时间显示
<TableCell>
  {user.createdAt ? formatDistanceToNow(new Date(user.createdAt), { addSuffix: true, locale: zhCN }) : '-'}
</TableCell>
```

### 4.4 消息通知规范

#### 4.4.1 导入依赖
```typescript
import { toast } from 'sonner';
```

#### 4.4.2 使用规范
```typescript
// 成功通知
toast.success('操作成功');
toast.success('用户创建成功');

// 错误通知
toast.error('操作失败');
toast.error('创建用户失败，请重试');

// 警告通知
toast.warning('请确认操作');
toast.warning('该操作将删除所有相关数据');

// 信息通知
toast.info('操作提示');
toast.info('正在处理中，请稍候...');
```

#### 4.4.3 与API响应集成
```typescript
try {
  const res = await entityClient.$post({ json: data });
  if (res.status === 201) {
    toast.success('创建成功');
    setIsModalOpen(false);
    refetch();
  } else {
    const error = await res.json();
    toast.error(error.message || '操作失败');
  }
} catch (error) {
  console.error('操作失败:', error);
  toast.error('网络错误，请重试');
}
```