生产管理系统 - 企业管理和用户管理列表重构

2025-11-06 17:47:14 +08:00
parent 191d218ec4
commit 008fc12db9
8 changed files with 1154 additions and 499 deletions
--- a/crop-x/docs/开发项目规范.md
+++ b/crop-x/docs/开发项目规范.md
@@ -234,6 +234,56 @@ import {
  getTenantAuditLogsApiV1TenantsAuditLogsGet,
 } from "@/lib/api/sdk.gen"; 这个引入和用法。

+### 11.Next.js 文件命名规范原则
+
+**规范要求：**
+所有文件名必须严格遵循 Next.js 的文件命名规范，确保路由系统和页面组件能够正确识别。
+
+**规范标准：**
+
+#### 页面文件命名规范
+- **页面文件**：必须使用 `page.tsx` 作为页面文件名
+- **布局文件**：必须使用 `layout.tsx` 作为布局文件名
+- **加载状态**：必须使用 `loading.tsx` 作为加载状态文件名
+- **错误处理**：必须使用 `error.tsx` 作为错误处理文件名
+- **未找到页面**：必须使用 `not-found.tsx` 作为404页面文件名
+
+#### 路由参数文件命名规范
+- **动态路由**：使用 `[param].tsx` 格式，如 `[id].tsx`
+- **可选参数**：使用 `[[param]].tsx` 格式
+- **全部匹配**：使用 `[...param].tsx` 格式
+- **可选全部匹配**：使用 `[[...param]].tsx` 格式
+
+#### 组件和工具文件命名规范
+- **React 组件**：使用 PascalCase 命名，如 `UserProfile.tsx`
+- **工具函数**：使用 camelCase 命名，如 `dateUtils.ts`
+- **类型定义**：使用 camelCase 命名，如 `userTypes.ts`
+- **常量文件**：使用 UPPER_SNAKE_CASE 命名，如 `API_CONSTANTS.ts`
+
+**示例目录结构：**
+```
+src/app/(app)/land-information/
+├── layout.tsx                    # 布局文件
+├── page.tsx                      # 主页面
+├── loading.tsx                   # 加载状态
+├── error.tsx                     # 错误处理
+└── archive/
+    ├── page.tsx                  # 归档页面
+    ├── statistics/
+    │   ├── page.tsx              # 统计页面
+    │   └── components/
+    │       ├── FilterPanel.tsx   # 组件：PascalCase
+    │       └── statisticsReducer.tsx  # 工具文件：camelCase
+    └── [id]/
+        └── page.tsx              # 动态路由页面
+```
+
+**实施要点：**
+- 严格遵循文件命名规范，不得随意修改文件名
+- 页面文件必须使用 `page.tsx`，不能使用其他名称
+- 动态路由参数必须使用方括号 `[param]` 格式
+- 组件和工具文件遵循通用的 JavaScript/TypeScript 命名规范
+
 ## path：land-information/archive/statistics，name：统计分析页面开发经验与问题解决

 ### 问题1：图表横轴显示不完整
@@ -819,4 +869,609 @@ engine.addMarker(marker);
 - **插件化架构**：编辑工具采用插件化设计，易于扩展新功能
 - **接口标准化**：统一的接口设计，便于功能模块替换
 - **配置化开发**：支持通过配置文件调整功能和行为
-   - 理解了复杂应用中的组件分层和职责划分
+   - 理解了复杂应用中的组件分层和职责划分
+
+---
+
+## path：src/components/common/searchFormPagination，name：搜索、表格、分页三合一组件使用心得
+
+### 组件概述
+
+SearchFormPagination 是一个高度可配置的复合组件，集成了搜索表单、数据表格和分页功能。该组件采用了现代React开发模式，通过配置驱动的方式实现复杂数据展示页面的快速开发。
+
+### 架构设计
+
+#### 1. 组件层次结构
+
+```
+SearchFormPagination (主组件)
+├── SearchFormComponent (搜索表单)
+│   ├── Input (文本搜索框)
+│   └── Select (下拉选择框)
+├── Card (表格容器)
+│   ├── Table (数据表格)
+│   │   ├── TableHeader (表头)
+│   │   └── TableBody (表体)
+│   └── PaginationComponent (分页组件)
+└── LoadingOverlay (加载遮罩)
+```
+
+#### 2. 核心文件结构
+
+```
+src/components/common/searchFormPagination/
+├── index.ts                              # 主组件导出
+├── page.tsx                             # SearchFormPagination主组件
+├── components/
+│   ├── SearchFormComponent.tsx          # 搜索表单组件
+│   ├── PaginationComponent.tsx          # 分页组件
+│   └── searchFormPaginationReducer.tsx  # 状态管理（可选）
+```
+
+### 核心功能特性
+
+#### 1. 搜索表单功能
+
+**防抖搜索机制**：
+```tsx
+// 关键实现：300ms防抖，避免频繁API调用
+useEffect(() => {
+  const timer = setTimeout(() => {
+    onFiltersChangeRef.current(localFilters);
+  }, 300);
+
+  return () => clearTimeout(timer);
+}, [localFilters]);
+```
+
+**多字段配置支持**：
+```tsx
+const searchFields: SearchFieldConfig[] = [
+  {
+    key: 'search',
+    type: 'text',
+    placeholder: '搜索企业名称、编码...',
+  },
+  {
+    key: 'audit_status',
+    type: 'select',
+    defaultValue: 'all',
+    options: [
+      { value: 'all', label: '全部状态' },
+      { value: 'draft', label: '草稿' },
+      // ...更多选项
+    ],
+  },
+];
+```
+
+#### 2. 表格展示功能
+
+**动态列配置**：
+```tsx
+const columns: TableColumnConfig[] = [
+  {
+    key: 'name',
+    label: '企业名称',
+    sortable: true,  // 支持排序
+    render: (value, row) => (
+      <div className="font-medium">{value}</div>
+    ),
+  },
+  {
+    key: 'status',
+    label: '状态',
+    render: (value) => getStatusBadge(value),  // 自定义渲染
+  },
+];
+```
+
+**加载状态处理**：
+```tsx
+// 表格加载遮罩 - 提升用户体验
+{loading && (
+  <div className="absolute inset-0 bg-white/50 dark:bg-black/50 backdrop-blur-sm z-10">
+    <div className="flex items-center justify-center">
+      <RefreshCw className="w-6 h-6 animate-spin" />
+      <span>加载中...</span>
+    </div>
+  </div>
+)}
+```
+
+#### 3. 分页功能
+
+**完整分页配置**：
+```tsx
+interface PaginationConfig {
+  page: number;
+  size: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+<PaginationComponent
+  pagination={pagination}
+  onPageChange={handlePageChange}
+  onSizeChange={handleSizeChange}
+  sizeOptions={[10, 30, 50, 100]}  // 可配置每页条数
+  showSizeSelector={true}
+  showPageInfo={true}
+/>
+```
+
+**智能分页逻辑**：
+- 当只有一页数据时，分页按钮隐藏但每页条数选择器仍显示
+- 支持页码跳转和快速导航
+- 分页操作时保持当前搜索条件
+
+### 使用示例
+
+#### 完整调用示例
+
+```tsx
+import { SearchFormPagination } from '@/components/common/searchFormPagination';
+
+export default function EnterpriseManagement() {
+  const [enterprises, setEnterprises] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [pagination, setPagination] = useState({
+    page: 1,
+    size: 10,
+    total: 0,
+    totalPages: 0,
+    hasNext: false,
+    hasPrev: false,
+  });
+
+  // 搜索字段配置
+  const searchFields = [
+    {
+      key: 'search',
+      label: '搜索',
+      type: 'text',
+      placeholder: '搜索企业名称、编码...',
+    },
+    {
+      key: 'audit_status',
+      label: '审核状态',
+      type: 'select',
+      defaultValue: 'all',
+      options: [
+        { value: 'all', label: '全部状态' },
+        { value: 'draft', label: '草稿' },
+        { value: 'pending', label: '待审核' },
+        { value: 'approved', label: '审核通过' },
+      ],
+    },
+  ];
+
+  // 表格列配置
+  const columns = [
+    {
+      key: 'name',
+      label: '企业名称',
+      sortable: true,
+      render: (value) => <div className="font-medium">{value}</div>,
+    },
+    {
+      key: 'auditStatus',
+      label: '审核状态',
+      render: (value) => getAuditStatusBadge(value),
+    },
+    {
+      key: 'actions',
+      label: '操作',
+      render: (_, row) => (
+        <div className="flex gap-2">
+          <Button size="sm" onClick={() => handleView(row)}>
+            查看
+          </Button>
+          <Button size="sm" variant="outline" onClick={() => handleEdit(row)}>
+            编辑
+          </Button>
+        </div>
+      ),
+    },
+  ];
+
+  // 数据加载函数
+  const loadEnterprises = useCallback(async (params) => {
+    try {
+      setLoading(true);
+      const response = await fetchTenants(params);
+      setEnterprises(response.data);
+      setPagination({
+        page: response.page,
+        size: response.size,
+        total: response.total,
+        totalPages: response.total_pages,
+        hasNext: response.has_next,
+        hasPrev: response.has_prev,
+      });
+    } catch (error) {
+      console.error('Failed to load enterprises:', error);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  // 搜索处理
+  const handleSearch = useCallback((filters) => {
+    loadEnterprises({
+      filters,
+      pagination: { page: 1, size: pagination.size },
+    });
+  }, [loadEnterprises, pagination.size]);
+
+  // 分页处理
+  const handlePageChange = useCallback((page) => {
+    setPagination(prev => ({ ...prev, page }));
+    loadEnterprises({
+      pagination: { page, size: pagination.size },
+      filters: searchFilters,
+    });
+  }, [loadEnterprises, pagination.size]);
+
+  return (
+    <div className="space-y-6">
+      <SearchFormPagination
+        formTitle="企业列表"
+        formRightContent={<Button onClick={handleCreate}>新建企业</Button>}
+        searchFields={searchFields}
+        columns={columns}
+        data={enterprises}
+        loading={loading}
+        error={null}
+        pagination={pagination}
+        onPageChange={handlePageChange}
+        onSizeChange={handleSizeChange}
+        onSearch={handleSearch}
+        emptyIcon={<Building2 className="w-12 h-12" />}
+        emptyText="暂无企业数据"
+      />
+    </div>
+  );
+}
+```
+
+### 接口定义
+
+#### SearchFieldConfig - 搜索字段配置
+
+```tsx
+interface SearchFieldConfig {
+  key: string;                                    // 字段标识
+  label: string;                                  // 显示标签
+  type: 'text' | 'select';                        // 字段类型
+  placeholder?: string;                           // 占位符文本
+  options?: Array<{ value: string; label: string }>;  // 下拉选项
+  defaultValue?: string;                          // 默认值
+}
+```
+
+#### TableColumnConfig - 表格列配置
+
+```tsx
+interface TableColumnConfig {
+  key: string;                                    // 数据字段名
+  label: string;                                  // 表头显示文本
+  sortable?: boolean;                             // 是否支持排序
+  width?: string;                                 // 列宽设置
+  render?: (value: any, row: any, index: number) => React.ReactNode;  // 自定义渲染
+}
+```
+
+#### SearchFormPaginationProps - 主组件属性
+
+```tsx
+interface SearchFormPaginationProps<T = any> {
+  // 搜索配置
+  searchFields: SearchFieldConfig[];
+  onSearch?: (filters: Record<string, string>) => void;
+
+  // 表格配置
+  columns: TableColumnConfig[];
+  data?: T[];
+  loading?: boolean;
+  error?: string | null;
+
+  // 分页配置
+  pagination?: PaginationConfig;
+  onPageChange?: (page: number) => void;
+  onSizeChange?: (size: number) => void;
+  onSort?: (sortBy: string, sortOrder: 'asc' | 'desc') => void;
+
+  // UI配置
+  formTitle?: string;
+  formRightContent?: React.ReactNode;
+  emptyIcon?: React.ReactNode;
+  emptyText?: string;
+  showSizeSelector?: boolean;
+  showPageInfo?: boolean;
+}
+```
+
+### 最佳实践
+
+#### 1. 性能优化
+
+**使用 useCallback 优化函数引用**：
+```tsx
+// ✅ 正确做法：使用 useCallback 避免重复渲染
+const handleSearch = useCallback((filters) => {
+  loadEnterprises({ filters });
+}, [loadEnterprises]);
+
+const handlePageChange = useCallback((page) => {
+  loadEnterprises({ page, size: pagination.size });
+}, [loadEnterprises, pagination.size]);
+
+// ❌ 错误做法：每次渲染都创建新函数
+const handleSearch = (filters) => {
+  loadEnterprises({ filters });
+};
+```
+
+**统一数据重载函数**：
+```tsx
+// ✅ 推荐：统一的数据重载逻辑，避免代码重复
+const reloadData = useCallback(() => {
+  const reloadParams = {
+    filters: searchFilters,
+    pagination: {
+      page: pagination.page,
+      size: pagination.size
+    }
+  };
+  loadEnterprises(reloadParams);
+}, [loadEnterprises, searchFilters, pagination]);
+
+// 在多个地方使用
+const handleCreateSuccess = () => reloadData();
+const confirmStatusChange = async () => {
+  await enableTenant(tenantId);
+  reloadData();
+};
+```
+
+#### 2. 状态管理
+
+**合理的状态依赖**：
+```tsx
+// ✅ 正确：包含所有必要的依赖
+const handlePageChange = useCallback((page: number) => {
+  loadEnterprises({
+    filters: searchFilters,  // 确保搜索条件不会丢失
+    pagination: { page, size: pagination.size }
+  });
+}, [loadEnterprises, searchFilters, pagination.size]);
+```
+
+#### 3. 错误处理
+
+**完善的错误状态处理**：
+```tsx
+<SearchFormPagination
+  // ...
+  error={error}
+  // 组件会自动显示错误状态
+/>
+```
+
+#### 4. 扩展性设计
+
+**新增字段的简单步骤**：
+1. 在 `searchFields` 数组中添加新配置
+2. 确保后端API支持新的查询参数
+3. 无需修改任何组件逻辑
+
+```tsx
+// 添加新的下拉框只需一行配置
+{
+  key: 'enterprise_status',
+  label: '企业状态',
+  type: 'select',
+  defaultValue: 'all',
+  options: [
+    { value: 'all', label: '全部状态' },
+    { value: 'active', label: '启用' },
+    { value: 'inactive', label: '禁用' },
+  ],
+}
+```
+
+### 技术特点
+
+#### 1. 类型安全
+- 完整的 TypeScript 类型定义
+- 泛型支持，确保数据类型一致性
+- 严格的接口约束
+
+#### 2. 用户体验优化
+- 防抖搜索，避免频繁请求
+- 加载状态遮罩，提供视觉反馈
+- 分页状态保持，避免搜索条件丢失
+- 响应式设计，适配不同屏幕尺寸
+
+#### 3. 可维护性
+- 配置驱动，减少硬编码
+- 组件化设计，职责单一
+- 完善的错误处理机制
+
+#### 4. 可扩展性
+- 插件化的字段配置
+- 自定义渲染函数支持
+- 多种配置选项
+
+### 常见问题解决
+
+#### 1. 分页后搜索条件丢失
+
+**问题**：切换页码或每页条数时，搜索条件被重置
+
+**解决方案**：
+```tsx
+const handlePageChange = useCallback((page) => {
+  // 确保传递当前的搜索条件
+  loadEnterprises({
+    filters: searchFilters,  // 关键：传递搜索条件
+    pagination: { page, size: pagination.size }
+  });
+}, [loadEnterprises, searchFilters, pagination.size]);
+```
+
+#### 2. 频繁API调用问题
+
+**问题**：用户快速输入时触发过多API请求
+
+**解决方案**：组件内置300ms防抖机制，无需额外处理
+
+#### 3. 加载状态处理
+
+**问题**：数据加载时用户体验不佳
+
+**解决方案**：
+```tsx
+<SearchFormPagination
+  loading={loading}  // 自动显示加载遮罩和状态
+  // ...
+/>
+```
+
+### 性能优化最佳实践
+
+#### 1. 事件驱动模式
+
+**原则**：避免使用setTimeout，尽可能减少useEffect，使用事件驱动来实现状态更新。
+
+**最佳实践**：
+```tsx
+// ❌ 避免写法：使用setTimeout和过多useEffect
+useEffect(() => {
+  const timer = setTimeout(() => {
+    loadData();
+  }, 300);
+  return () => clearTimeout(timer);
+}, [filters]);
+
+useEffect(() => {
+  if (page > 1) {
+    loadData();
+  }
+}, [page]);
+
+// ✅ 推荐写法：事件驱动，直接调用
+const handleSearch = useCallback((filters) => {
+  setSearchFilters(filters);
+  loadData({ filters, pagination: { page: 1, size: pagination.size } });
+}, [loadData, pagination.size]);
+
+const handlePageChange = useCallback((page) => {
+  setPagination(prev => ({ ...prev, page }));
+  loadData({ filters: searchFilters, pagination: { page, size: pagination.size } });
+}, [loadData, searchFilters, pagination.size]);
+```
+
+#### 2. 函数依赖优化
+
+**原则**：减少useCallback和useMemo的依赖项，通过参数传递而非依赖外部状态。
+
+**最佳实践**：
+```tsx
+// ❌ 避免写法：过多依赖项导致函数频繁重新创建
+const loadData = useCallback(async () => {
+  // 依赖filters, pagination, sortBy等
+}, [filters, pagination, sortBy]);
+
+// ✅ 推荐写法：无依赖项，通过参数传递
+const loadData = useCallback(async (params) => {
+  // 使用params.filters, params.pagination等
+}, []); // 空依赖数组
+```
+
+#### 3. 搜索防抖优化
+
+**原则**：下拉框选择立即触发，文本输入使用防抖，避免不必要的延迟。
+
+**实现方式**：
+```tsx
+// SearchFormComponent中的优化实现
+const handleInputChange = (key: string, value: string, fieldType: 'text' | 'select') => {
+  const newFilters = { ...localFilters, [key]: value };
+  setLocalFilters(newFilters);
+
+  // 下拉框选择立即触发查询，文本输入使用防抖
+  if (fieldType === 'select') {
+    onFiltersChangeRef.current(newFilters); // 立即执行
+  }
+  // 文本输入的防抖在useEffect中处理
+};
+```
+
+### 组件设计原则
+
+#### 1. 排序功能简化
+
+**设计决策**：SearchFormPagination组件不再支持表头排序功能。
+
+**原因**：
+- 简化组件复杂度，提高性能
+- 减少不必要的交互，专注核心功能（搜索、展示、分页）
+- 避免排序逻辑与业务逻辑耦合
+
+**替代方案**：
+- 如需排序功能，在业务页面层面实现
+- 通过下拉框或其他UI控件提供排序选项
+
+#### 2. 接口简化
+
+**删除的排序相关接口**：
+```tsx
+// ❌ 已删除的接口
+interface TableColumnConfig {
+  sortable?: boolean; // 删除
+  // ...
+}
+
+interface SearchFormPaginationProps {
+  sortBy?: string; // 删除
+  sortOrder?: 'asc' | 'desc'; // 删除
+  onSort?: (sortBy: string, sortOrder: 'asc' | 'desc') => void; // 删除
+  // ...
+}
+```
+
+#### 3. 表头渲染简化
+
+**删除的排序交互**：
+- 删除了表头的点击事件处理
+- 删除了排序箭头图标显示
+- 删除了鼠标悬停样式效果
+
+### 重构指南
+
+如果要重构或基于此组件开发新功能，请遵循以下原则：
+
+1. **保持接口兼容性**：不要破坏现有的props接口
+2. **扩展而非修改**：通过新的配置项而非修改现有逻辑来添加功能
+3. **类型安全**：确保所有新功能都有完整的TypeScript类型定义
+4. **测试覆盖**：新功能应该有相应的测试用例
+5. **文档更新**：及时更新使用文档和接口说明
+6. **性能优先**：采用事件驱动模式，避免不必要的useEffect和setTimeout
+7. **功能专注**：保持组件职责单一，避免功能过度复杂化
+
+### 总结
+
+SearchFormPagination 组件通过配置驱动的方式，极大地简化了复杂数据展示页面的开发工作。其核心优势在于：
+
+- **高度可配置**：通过配置而非代码实现功能定制
+- **性能优化**：事件驱动模式，无setTimeout依赖，最小化useEffect使用
+- **用户体验**：下拉框立即响应，文本输入智能防抖
+- **易于扩展**：新增功能只需要修改配置，无需修改组件逻辑
+- **类型安全**：完整的 TypeScript 支持
+- **功能专注**：专注搜索、展示、分页核心功能，避免过度设计
+
+该组件可以作为项目中所有数据展示页面的标准解决方案，显著提升开发效率和代码质量。