# SupplierSelector 供应商选择器组件

供应商选择器组件，用于从系统中选择供应商数据。提供双列表交互方式，支持搜索、分页和多选功能。

## 组件特点

- 支持搜索过滤供应商：可按名称、部门、公司名称和品类筛选
- 支持分页加载更多供应商数据
- 双列表展示（待选列表和已选列表），直观且易用
- 支持初始化已选供应商
- 支持多选和批量操作
- 自动去重，避免重复选择同一供应商
- 支持按部门列表筛选供应商
- 可自定义显示的字段列

## 使用场景

- 供应商评估任务选择供应商
- 供应商准入管理
- 任何需要从多个供应商中选择一个或多个的场景

## 使用方法

### 基础用法

```jsx
import React, { useState } from 'react';
import SupplierSelector from '@/components/SupplierSelector';

const Demo = () => {
  const [selectedSuppliers, setSelectedSuppliers] = useState([]);

  const handleSupplierSelect = (suppliers) => {
    setSelectedSuppliers(suppliers);
    console.log('已选择的供应商:', suppliers);
  };

  return (
    <SupplierSelector
      selectedSuppliers={selectedSuppliers} 
      onSelect={handleSupplierSelect}
    />
  );
};
```

### 配合表单使用

```jsx
import React from 'react';
import { Form, Button, Card } from 'antd';
import SupplierSelector from '@/components/SupplierSelector';

const FormDemo = () => {
  const [form] = Form.useForm();

  const handleFinish = (values) => {
    console.log('表单提交的值:', values);
  };

  return (
    <Form form={form} onFinish={handleFinish}>
      <Card title="选择供应商">
        <Form.Item
          name="suppliers"
          label="请选择供应商"
          rules={[{ required: true, message: '请至少选择一个供应商' }]}
        >
          <SupplierSelector />
        </Form.Item>
      </Card>
      
      <Form.Item>
        <Button type="primary" htmlType="submit">
          提交
        </Button>
      </Form.Item>
    </Form>
  );
};
```

### 按部门筛选供应商

```jsx
import React, { useState } from 'react';
import SupplierSelector from '@/components/SupplierSelector';

const DepartmentFilterDemo = () => {
  const [selectedSuppliers, setSelectedSuppliers] = useState([]);
  
  // 部门ID列表，用于筛选供应商
  const deptList = ['1', '2', '3'];

  return (
    <SupplierSelector
      selectedSuppliers={selectedSuppliers}
      onSelect={setSelectedSuppliers}
      deptList={deptList}
      showDeptFilter={true}
      showCompanyFilter={true}
    />
  );
};
```

### 带初始值的用法

```jsx
import React, { useState, useEffect } from 'react';
import SupplierSelector from '@/components/SupplierSelector';
import { getSuppliersByIds } from '@/servers/api/supplier';

const InitialValueDemo = () => {
  const [selectedSuppliers, setSelectedSuppliers] = useState([]);
  const [loading, setLoading] = useState(true);

  // 加载初始已选供应商
  useEffect(() => {
    const loadInitialSuppliers = async () => {
      setLoading(true);
      try {
        // 假设我们有一些预先选择的供应商ID
        const initialIds = ['1', '2', '3'];
        const response = await getSuppliersByIds(initialIds);
        
        if (response.code === 200) {
          setSelectedSuppliers(response.data);
        }
      } catch (error) {
        console.error('加载初始供应商失败:', error);
      } finally {
        setLoading(false);
      }
    };

    loadInitialSuppliers();
  }, []);

  const handleSupplierSelect = (suppliers) => {
    setSelectedSuppliers(suppliers);
  };

  return (
    <div>
      {loading ? (
        <div>加载中...</div>
      ) : (
        <SupplierSelector
          selectedSuppliers={selectedSuppliers}
          onSelect={handleSupplierSelect}
        />
      )}
    </div>
  );
};
```

## API

### 组件属性

| 参数 | 说明 | 类型 | 默认值 | 是否必填 |
|------|------|------|--------|----------|
| selectedSuppliers | 已选择的供应商列表 | `Array<SupplierItem>` | `[]` | 否 |
| onSelect | 选择后的回调函数 | `(suppliers: SupplierItem[]) => void` | - | 否 |
| deptList | 部门ID列表，用于筛选供应商 | `string[]` | `[]` | 否 |
| showDeptFilter | 是否显示部门筛选条件 | `boolean` | `true` | 否 |
| showCompanyFilter | 是否显示公司名称筛选条件 | `boolean` | `false` | 否 |

### 数据结构

#### SupplierItem 

供应商数据项结构，对应后端 SupplierPageVo

```typescript
interface SupplierItem {
  id: string;                // 供应商ID
  name: string;              // 供应商名称
  deptId?: string;           // 部门ID
  deptName?: string;         // 部门名称
  companyName?: string;      // 公司名称
  categoryName?: string;     // 所属品类
  levelName?: string;        // 最新评价等级
  admissionTime?: Date;      // 准入时间
  evaluationTime?: Date;     // 最新评价时间
  [key: string]: any;        // 其他属性
}
```

## 后端接口对接

组件已对接 `/coscoSupplierBase/getSupplierPage` 接口，使用 POST 方法。请求参数格式：

```javascript
{
  // 查询条件
  name: "供应商名称",            // 可选，供应商名称
  deptId: "部门ID",             // 可选，部门ID
  deptName: "部门名称",          // 可选，部门名称
  companyName: "公司名称",       // 可选，公司名称
  categoryName: "所属品类",      // 可选，所属品类
  
  // 筛选条件
  deptList: ["部门ID1", "部门ID2"], // 可选，部门ID列表
  
  // 分页信息
  basePageRequest: {
    pageNo: 1,                // 页码
    pageSize: 10               // 每页条数
  }
}
```

预期的响应格式：

```javascript
{
  code: 200,                   // 状态码
  message: "success",          // 消息
  data: {
    records: [                 // 供应商记录数组
      {
        id: "1",               // 供应商ID
        name: "供应商A",        // 供应商名称
        deptId: "1",           // 部门ID
        deptName: "采购部",     // 部门名称
        companyName: "公司A",   // 公司名称
        categoryName: "润滑油", // 所属品类
        levelName: "A",        // 最新评价等级
        admissionTime: "2023-01-01", // 准入时间
        evaluationTime: "2023-06-01" // 最新评价时间
      }
      // ...更多记录
    ],
    total: 100                 // 总记录数
  }
}
```

## 常见问题

### 1. 如何处理大量数据的情况？

组件内部已实现分页加载，可以有效处理大量数据。API请求会自动附带分页参数。

### 2. 如何自定义显示的列？

组件提供了 `showDeptFilter` 和 `showCompanyFilter` 属性来控制是否显示部门和公司名称列。如需更多自定义，可以通过修改组件源码中的 `columns` 配置实现。

### 3. 如何限制只从特定部门选择供应商？

使用 `deptList` 属性可以限制只显示特定部门的供应商。例如：

```jsx
<SupplierSelector deptList={['1', '2']} />
```

这样将只显示部门ID为1和2的供应商。

### 4. 如何处理接口错误情况？

组件内置了错误处理机制，当接口请求失败时会显示错误提示，并使用模拟数据作为备用，确保界面不会崩溃。

## 设计考量

1. **双列表设计**：采用左右双列表设计，符合用户选择多项时的直觉操作
2. **错误处理**：内置错误处理和备用数据，提高组件稳定性
3. **性能优化**：使用Set进行去重操作，提高大数据量下的性能
4. **灵活配置**：通过属性控制显示哪些列和筛选条件，适应不同场景需求
