@pisell/private-materials 6.6.9 → 6.6.11

package/dist/es/pro/Selector/TEST.md

@@ -1,1029 +0,0 @@
-# Selector 组件测试计划文档
-
-## 1. 测试概述
-
-### 1.1 组件信息
-
-| 项目 | 内容 |
-|------|------|
-| 组件名称 | Selector |
-| 组件路径 | `packages/private-materials/src/pro/Selector` |
-| 组件类型 | React 函数组件 (forwardRef) |
-| 依赖 Hook | `useSelectionController` |
-| 子组件 | `CardItem`、`NumericStepper` |
-
-### 1.2 测试范围
-
-- ✅ **核心功能**：选择、切换、数量控制、校验
-- ✅ **UI 渲染**：不同变体、布局、样式
-- ✅ **交互行为**：点击、切换、输入
-- ✅ **边界条件**：空数据、极端值、异常输入
-- ✅ **集成场景**：与 SelectorGroup 组合使用
-
-### 1.3 测试策略
-
-| 测试类型 | 工具 | 优先级 | 覆盖率目标 |
-|---------|------|--------|-----------|
-| 单元测试 | Vitest + RTL | P0 | 80%+ |
-| 集成测试 | Vitest + RTL | P1 | 70%+ |
-| 交互测试 | RTL + user-event | P1 | 60%+ |
-| 快照测试 | Vitest | P2 | 核心组件 |
-| 可视化测试 | Storybook | P1 | 核心场景 |
-| E2E 测试 | Playwright (可选) | P2 | 关键流程 |
-
----
-
-## 2. 测试环境配置
-
-### 2.1 测试工具链
-
-```typescript
-// 测试框架
-- Vitest: ^1.6.0
-- @testing-library/react: ^12.1.5
-- @testing-library/user-event: ^14.6.1
-- @testing-library/jest-dom: ^5.16.5
-
-// 测试环境
-- jsdom: ^22.1.0 (浏览器环境模拟)
-```
-
-### 2.2 Mock 配置
-
-参考 `src/test/setup.ts` 中的 Mock 配置：
-- ✅ Ant Design 组件 Mock
-- ✅ 国际化 locales Mock
-- ✅ EngineContext Mock
-- ✅ CSS Modules Mock
-
-### 2.3 测试辅助函数
-
-```typescript
-// 测试工具函数示例
-export const renderSelector = (props: Partial<SelectorProps>) => {
-  return render(<Selector {...defaultProps} {...props} />);
-};
-
-export const createMockDataSource = (count: number) => {
-  return Array.from({ length: count }, (_, i) => ({
-    id: i + 1,
-    value: i + 1,
-    label: `选项${i + 1}`,
-    title: `选项${i + 1}`,
-  }));
-};
-```
-
----
-
-## 3. 测试数据准备
-
-### 3.1 基础测试数据
-
-```typescript
-// 最小数据集
-export const minimalDataSource = [
-  { id: 1, value: 1, label: '选项1', title: '选项1' },
-  { id: 2, value: 2, label: '选项2', title: '选项2' },
-];
-
-// 标准数据集
-export const standardDataSource = [
-  { id: 1, value: 1, label: '选项1', title: '选项1' },
-  { id: 2, value: 2, label: '选项2', title: '选项2' },
-  { id: 3, value: 3, label: '选项3', title: '选项3' },
-  { id: 4, value: 4, label: '选项4', title: '选项4' },
-  { id: 5, value: 5, label: '选项5', title: '选项5' },
-];
-
-// 带数量限制的数据集
-export const quantityDataSource = [
-  { 
-    id: 1, 
-    value: 1, 
-    label: '选项1', 
-    title: '选项1',
-    ruleConfig: { min: 1, max: 10 }
-  },
-  { 
-    id: 2, 
-    value: 2, 
-    label: '选项2', 
-    title: '选项2',
-    ruleConfig: { min: 0, max: 5 }
-  },
-];
-
-// 带互斥规则的数据集
-// 互斥规则说明：
-// - 选项1、2、3 属于互斥组1，同一组内只能选择一个
-// - 选项4、5、6 属于互斥组2，同一组内只能选择一个
-// 使用时需要在 ruleConfig 中配置：mutex: [[1, 2, 3], [4, 5, 6]]
-export const mutexDataSource = [
-  { id: 1, value: 1, label: '选项1（互斥组1）', title: '选项1' },
-  { id: 2, value: 2, label: '选项2（互斥组1）', title: '选项2' },
-  { id: 3, value: 3, label: '选项3（互斥组1）', title: '选项3' },
-  { id: 4, value: 4, label: '选项4（互斥组2）', title: '选项4' },
-  { id: 5, value: 5, label: '选项5（互斥组2）', title: '选项5' },
-  { id: 6, value: 6, label: '选项6（互斥组2）', title: '选项6' },
-];
-
-// 互斥规则配置示例（用于测试）
-export const mutexRuleConfig = {
-  mutex: [
-    [1, 2, 3],  // 互斥组1：选项1、2、3 只能选一个
-    [4, 5, 6],  // 互斥组2：选项4、5、6 只能选一个
-  ],
-};
-```
-
-### 3.2 边界测试数据
-
-```typescript
-// 空数据
-export const emptyDataSource: OptionItem[] = [];
-
-// 单条数据
-export const singleItemDataSource = [
-  { id: 1, value: 1, label: '唯一选项', title: '唯一选项' },
-];
-
-// 大量数据（性能测试）
-export const largeDataSource = Array.from({ length: 1000 }, (_, i) => ({
-  id: i + 1,
-  value: i + 1,
-  label: `选项${i + 1}`,
-  title: `选项${i + 1}`,
-}));
-
-// 异常数据
-export const invalidDataSource = [
-  { id: null, value: undefined, label: '', title: '' }, // 缺失必填字段
-  { id: 2, value: 2, label: '选项2', title: '选项2' },
-];
-```
-
-### 3.3 默认 Props
-
-```typescript
-export const defaultSelectorProps: Partial<SelectorProps> = {
-  id: 'test-selector',
-  title: '测试标题',
-  dataSource: standardDataSource,
-  mode: 'single',
-  valueType: 'primitive',
-  fieldNames: { value: 'value', label: 'label' },
-};
-```
-
----
-
-## 4. 功能测试用例
-
-### 4.1 基础渲染测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-F-001 | 组件正常渲染 | 渲染组件，传入基础 props | 组件成功渲染，无报错 | P0 |
-| TC-F-002 | 渲染选项列表 | 传入 dataSource，检查选项数量 | 所有选项正确渲染 | P0 |
-| TC-F-003 | 空数据源渲染 | 传入空数组 dataSource | 显示空状态或空列表，无报错 | P1 |
-| TC-F-004 | 自定义 fieldNames | 传入自定义 fieldNames | 选项使用自定义字段映射 | P1 |
-
-**测试代码示例**：
-```typescript
-describe('基础渲染测试', () => {
-  test('TC-F-001: 组件正常渲染', () => {
-    const { container } = render(<Selector {...defaultProps} />);
-    expect(container).toBeInTheDocument();
-  });
-
-  test('TC-F-002: 渲染选项列表', () => {
-    const { getAllByRole } = render(
-      <Selector dataSource={standardDataSource} />
-    );
-    const radios = getAllByRole('radio');
-    expect(radios).toHaveLength(standardDataSource.length);
-  });
-});
-```
-
-### 4.2 单选模式测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-S-001 | 单选模式渲染 | mode='single'，检查使用 Radio | 使用 Radio 组件 | P0 |
-| TC-S-002 | 选择选项 | 点击未选中选项 | 选项被选中，onChange 触发 | P0 |
-| TC-S-003 | 取消选择 | 点击已选中选项 | 选项被取消，值变为 undefined | P0 |
-| TC-S-004 | 切换选择 | 选择新选项 | 旧选项自动取消，新选项选中 | P0 |
-| TC-S-005 | 原始值返回 | valueType='primitive' | onChange 返回原始值 | P0 |
-| TC-S-006 | 对象值返回 | valueType='object' | onChange 返回对象值 | P0 |
-
-**测试代码示例**：
-```typescript
-describe('单选模式测试', () => {
-  test('TC-S-002: 选择选项', async () => {
-    const user = userEvent.setup();
-    const handleChange = vi.fn();
-    
-    const { getAllByRole } = render(
-      <Selector
-        dataSource={standardDataSource}
-        mode="single"
-        valueType="primitive"
-        onChange={handleChange}
-      />
-    );
-    
-    const radios = getAllByRole('radio');
-    await user.click(radios[0]);
-    
-    expect(handleChange).toHaveBeenCalledWith(1);
-    expect(radios[0]).toBeChecked();
-  });
-});
-```
-
-### 4.3 多选模式测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-M-001 | 多选模式渲染 | mode='multiple'，检查使用 Checkbox | 使用 Checkbox 组件 | P0 |
-| TC-M-002 | 多选选项 | 依次选择多个选项 | 多个选项同时选中 | P0 |
-| TC-M-003 | 取消单个选项 | 点击已选中选项 | 仅该选项取消，其他保持 | P0 |
-| TC-M-004 | 原始值数组返回 | valueType='primitive' | onChange 返回数组 | P0 |
-| TC-M-005 | 对象值数组返回 | valueType='object' | onChange 返回对象数组 | P0 |
-
-### 4.4 数量选择测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-Q-001 | 数量选择器显示 | 选项 max > 1，valueType='object' | 显示数量选择器 | P0 |
-| TC-Q-002 | 数量修改 | 修改数量值 | onChange 触发，值包含 quantity | P0 |
-| TC-Q-003 | 数量为 0 自动取消 | 将数量调为 0 | 选项自动取消选择 | P0 |
-| TC-Q-004 | 数量限制 min | 数量小于 min | 显示错误提示 | P1 |
-| TC-Q-005 | 数量限制 max | 数量大于 max | 显示错误提示 | P1 |
-| TC-Q-006 | 选项级数量限制 | 不同选项不同限制 | 各自限制生效 | P1 |
-
-### 4.5 校验规则测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-V-001 | required 必选校验 | required=1，未选择 | validate 失败，显示错误 | P0 |
-| TC-V-002 | min 最小数量校验 | min=2，选择少于 2 个 | validate 失败 | P0 |
-| TC-V-003 | max 最大数量校验 | max=3，选择超过 3 个 | validate 失败 | P0 |
-| TC-V-004 | mutex 互斥组校验 | 选择同组多个选项 | 自动取消同组其他选项 | P0 |
-| TC-V-005 | customValidator 自定义校验 | 传入自定义校验器 | 校验器逻辑生效 | P1 |
-| TC-V-006 | 自动校验 | autoValidate=true | 选择时自动校验 | P1 |
-
-**测试代码示例**：
-```typescript
-describe('校验规则测试', () => {
-  test('TC-V-001: required 必选校验', async () => {
-    const ref = React.createRef<any>();
-    
-    render(
-      <Selector
-        ref={ref}
-        dataSource={standardDataSource}
-        ruleConfig={{ required: 1 }}
-      />
-    );
-    
-    await expect(ref.current.validate()).rejects.toBeDefined();
-    const errors = ref.current.getErrors();
-    expect(errors.some(e => e.type === 'required')).toBe(true);
-  });
-});
-```
-
-### 4.6 Ref 方法测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-R-001 | validate 方法 | 调用 ref.validate() | 返回 Promise，执行校验 | P0 |
-| TC-R-002 | getErrors 方法 | 调用 ref.getErrors() | 返回错误数组 | P0 |
-| TC-R-003 | reset 方法 | 调用 ref.reset() | 重置为 defaultValue | P0 |
-| TC-R-004 | clear 方法 | 调用 ref.clear() | 清空所有选择 | P0 |
-
----
-
-## 5. UI/交互测试用例
-
-### 5.1 布局测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-U-001 | 默认布局 | 不传 grid | 垂直列表布局 | P1 |
-| TC-U-002 | 网格布局 2 列 | grid={{ columns: 2 }} | 选项呈 2 列排列 | P1 |
-| TC-U-003 | 网格布局 3 列 | grid={{ columns: 3 }} | 选项呈 3 列排列 | P1 |
-| TC-U-004 | 网格间距 | grid={{ gutter: 24 }} | 选项间距正确 | P2 |
-| TC-U-005 | 网格对齐 | grid={{ align: 'middle' }} | 对齐方式生效 | P2 |
-
-### 5.2 样式变体测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-SV-001 | default 变体 | variant='default' | 默认 Radio/Checkbox | P1 |
-| TC-SV-002 | card 变体 | variant='card' | 渲染卡片样式 | P1 |
-| TC-SV-003 | select 变体 | variant='select' | 渲染 Select 下拉 | P1 |
-| TC-SV-004 | 卡片布局 vertical | item={{ layout: 'vertical' }} | 垂直布局 | P1 |
-| TC-SV-005 | 卡片布局 horizontal | item={{ layout: 'horizontal' }} | 水平布局 | P1 |
-| TC-SV-006 | 选中态样式 filled | item={{ selectedTypeVariant: 'filled' }} | 填充样式 | P1 |
-| TC-SV-007 | 选中态样式 cornered | item={{ selectedTypeVariant: 'cornered' }} | 角标样式 | P1 |
-
-### 5.3 标题与提示测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-T-001 | 标题显示 | 传入 title | 标题正确显示 | P1 |
-| TC-T-002 | 标题隐藏 | titleProps={{ visible: false }} | 标题隐藏 | P1 |
-| TC-T-003 | 自定义标题 | titleProps={{ title: { text: '自定义' } }} | 显示自定义文本 | P1 |
-| TC-T-004 | 提示信息 | titleProps={{ tip: { text: '提示' } }} | 提示正确显示 | P1 |
-| TC-T-005 | 自动提示 | ruleConfig 有 min/max | 自动生成提示文本 | P1 |
-| TC-T-006 | 必选标签 | ruleConfig={{ required: 1 }} | 显示必选标签 | P1 |
-| TC-T-007 | 错误信息显示 | 校验失败 | 错误信息显示 | P0 |
-
-### 5.4 交互测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-I-001 | 点击选项选择 | 点击未选中选项 | 选项选中，状态更新 | P0 |
-| TC-I-002 | 点击已选项取消 | 点击已选中选项 | 选项取消，状态更新 | P0 |
-| TC-I-003 | 禁用选项不可点击 | 点击 disabled 选项 | 无响应，状态不变 | P1 |
-| TC-I-004 | 组件禁用 | disabled=true | 所有选项禁用 | P1 |
-| TC-I-005 | 数量步进器交互 | 点击 +/- 按钮 | 数量正确增减 | P0 |
-| TC-I-006 | 快速连续操作 | 快速点击多个选项 | 状态正确，无异常 | P1 |
-
-**测试代码示例**：
-```typescript
-describe('交互测试', () => {
-  test('TC-I-001: 点击选项选择', async () => {
-    const user = userEvent.setup();
-    const handleChange = vi.fn();
-    
-    const { getAllByRole } = render(
-      <Selector
-        dataSource={standardDataSource}
-        mode="single"
-        onChange={handleChange}
-      />
-    );
-    
-    const radios = getAllByRole('radio');
-    await user.click(radios[0]);
-    
-    expect(handleChange).toHaveBeenCalled();
-    expect(radios[0]).toBeChecked();
-  });
-});
-```
-
----
-
-## 6. 边界与异常测试用例
-
-### 6.1 数据边界测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-B-001 | 空数据源 | dataSource=[] | 正常渲染，不报错 | P1 |
-| TC-B-002 | 单条数据 | dataSource 只有 1 条 | 正常渲染 | P1 |
-| TC-B-003 | 大量数据 | dataSource 1000+ 条 | 性能可接受，正常渲染 | P2 |
-| TC-B-004 | 重复 value | 多个选项相同 value | 处理正确或提示错误 | P1 |
-| TC-B-005 | null/undefined 值 | value 为 null/undefined | 处理正确，不报错 | P1 |
-
-### 6.2 值边界测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-B-006 | 数量为 0 | quantity=0 | 选项取消或保持 | P1 |
-| TC-B-007 | 数量为负数 | quantity=-1 | 处理正确，不报错 | P1 |
-| TC-B-008 | 数量超大值 | quantity=999999 | 受 max 限制或处理正确 | P1 |
-| TC-B-009 | 无效 value | value 不在 dataSource | 处理正确，不报错 | P1 |
-
-### 6.3 异常场景测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-E-001 | onChange 抛出异常 | onChange 中 throw Error | 不影响组件状态 | P2 |
-| TC-E-002 | 校验器抛出异常 | customValidator throw | 错误正确处理 | P1 |
-| TC-E-003 | 数据源动态变化 | dataSource 从有到无 | 状态正确处理 | P1 |
-| TC-E-004 | 值动态变化 | value 外部变更 | 状态同步更新 | P0 |
-| TC-E-005 | 规则动态变化 | ruleConfig 变更 | 重新校验生效 | P1 |
-
----
-
-## 7. 性能测试用例
-
-### 7.1 渲染性能测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-P-001 | 100 选项渲染 | 渲染 100 个选项 | 渲染时间 < 500ms | P2 |
-| TC-P-002 | 1000 选项渲染 | 渲染 1000 个选项 | 渲染时间 < 2000ms | P2 |
-| TC-P-003 | 大数据集交互 | 1000 选项中选择 | 交互响应 < 100ms | P2 |
-
-### 7.2 内存测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-P-004 | 内存泄漏检测 | 创建销毁 100 次 | 无内存泄漏 | P2 |
-| TC-P-005 | 大数据集内存 | 1000 选项内存占用 | 内存占用 < 50MB | P2 |
-
----
-
-## 8. 可访问性测试用例
-
-### 8.1 键盘导航测试
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-A-001 | Tab 键导航 | 按 Tab 切换焦点 | 焦点正确切换 | P1 |
-| TC-A-002 | Space/Enter 选择 | 焦点在选项时按 Space | 选项选中/取消 | P1 |
-| TC-A-003 | 方向键导航 | 使用方向键切换 | 选项正确切换 | P1 |
-
-### 8.2 ARIA 与语义化测试
-
-> **说明**：屏幕阅读器测试主要用于验证组件对视觉障碍用户的可访问性。在单元测试中，我们主要通过检查 ARIA 属性和语义化 HTML 来确保可访问性。
-
-| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
-|--------|---------|---------|---------|--------|
-| TC-A-004 | ARIA 标签检查 | 检查 Radio/Checkbox 的 aria-label | 有正确的 ARIA 标签 | P1 |
-| TC-A-005 | 选中状态语义 | 检查 checked 状态 | aria-checked 正确反映状态 | P1 |
-| TC-A-006 | 禁用状态语义 | 检查 disabled 属性 | aria-disabled 正确 | P1 |
-| TC-A-007 | 错误信息语义 | 校验失败时检查 | 错误信息有适当的 ARIA 属性 | P2 |
-| TC-A-008 | 表单关联 | 检查 label 关联 | label 与 input 正确关联 | P1 |
-
-**测试代码示例**：
-```typescript
-describe('ARIA 可访问性测试', () => {
-  test('TC-A-004: ARIA 标签检查', () => {
-    const { getAllByRole } = render(
-      <Selector
-        dataSource={standardDataSource}
-        mode="single"
-        title="选择选项"
-      />
-    );
-    
-    const radios = getAllByRole('radio');
-    // Radio 组件应该自动处理 ARIA 属性
-    radios.forEach((radio, index) => {
-      expect(radio).toHaveAttribute('aria-label', standardDataSource[index].label);
-    });
-  });
-
-  test('TC-A-005: 选中状态语义', async () => {
-    const user = userEvent.setup();
-    const { getAllByRole } = render(
-      <Selector
-        dataSource={standardDataSource}
-        mode="single"
-      />
-    );
-    
-    const radios = getAllByRole('radio');
-    await user.click(radios[0]);
-    
-    expect(radios[0]).toHaveAttribute('aria-checked', 'true');
-    expect(radios[1]).toHaveAttribute('aria-checked', 'false');
-  });
-});
-```
-
-**注意**：
-- ✅ **单元测试中的可访问性测试**：主要检查 ARIA 属性和语义化 HTML，这是自动化的、可执行的
-- ⚠️ **真实屏幕阅读器测试**：需要使用真实屏幕阅读器软件（如 NVDA、JAWS、VoiceOver）进行人工测试，属于 E2E 测试范畴
-- 💡 **实际建议**：对于内部组件库，单元测试中的 ARIA 检查已足够；对于面向公众的产品，建议进行真实屏幕阅读器测试
-
----
-
-## 9. 测试用例执行清单
-
-### 9.1 测试用例分类统计
-
-| 类别 | 用例数量 | P0 | P1 | P2 | 完成状态 |
-|------|---------|-----|-----|-----|---------|
-| 基础渲染 | 4 | 2 | 2 | 0 | ⬜ |
-| 单选模式 | 6 | 6 | 0 | 0 | ⬜ |
-| 多选模式 | 5 | 5 | 0 | 0 | ⬜ |
-| 数量选择 | 6 | 2 | 4 | 0 | ⬜ |
-| 校验规则 | 6 | 3 | 3 | 0 | ⬜ |
-| Ref 方法 | 4 | 4 | 0 | 0 | ⬜ |
-| UI 布局 | 5 | 0 | 3 | 2 | ⬜ |
-| 样式变体 | 7 | 0 | 7 | 0 | ⬜ |
-| 标题提示 | 7 | 1 | 6 | 0 | ⬜ |
-| 交互测试 | 6 | 2 | 4 | 0 | ⬜ |
-| 边界测试 | 9 | 0 | 6 | 3 | ⬜ |
-| 异常测试 | 5 | 1 | 4 | 0 | ⬜ |
-| 性能测试 | 5 | 0 | 0 | 5 | ⬜ |
-| 可访问性 | 8 | 0 | 8 | 0 | ⬜ |
-| Storybook 测试 | 16 | 5 | 10 | 1 | ⬜ |
-| **总计** | **93** | **31** | **51** | **11** | **0%** |
-
-### 9.2 测试执行优先级
-
-#### Phase 1: 核心功能 (P0) - 31 个用例
-- [ ] 基础渲染测试（2）
-- [ ] 单选模式测试（6）
-- [ ] 多选模式测试（5）
-- [ ] 数量选择基础（2）
-- [ ] 校验规则核心（3）
-- [ ] Ref 方法测试（4）
-- [ ] 标题错误显示（1）
-- [ ] 交互核心（2）
-- [ ] 值同步更新（1）
-- [ ] Storybook 核心测试（5）
-
-#### Phase 2: 重要功能 (P1) - 48 个用例
-- [ ] 基础渲染扩展（2）
-- [ ] 数量选择扩展（4）
-- [ ] 校验规则扩展（3）
-- [ ] UI 布局测试（3）
-- [ ] 样式变体测试（7）
-- [ ] 标题提示测试（6）
-- [ ] 交互扩展（4）
-- [ ] 边界测试（6）
-- [ ] 异常测试（4）
-- [ ] 可访问性测试（5）
-- [ ] Storybook 测试（10）
-
-#### Phase 3: 优化与完善 (P2) - 11 个用例
-- [ ] UI 布局细节（2）
-- [ ] 性能测试（5）
-- [ ] 边界测试扩展（3）
-- [ ] Storybook 自定义功能（1）
-
----
-
-## 10. 测试覆盖率目标
-
-### 10.1 覆盖率指标
-
-| 指标 | 目标值 | 当前值 | 状态 |
-|------|--------|--------|------|
-| Statements | 80% | - | ⬜ |
-| Branches | 75% | - | ⬜ |
-| Functions | 80% | - | ⬜ |
-| Lines | 80% | - | ⬜ |
-
----
-
-## 11. 测试用例编写规范
-
-### 11.1 命名规范
-
-```typescript
-// 测试文件命名
-Selector.test.tsx
-SelectorGroup.test.tsx
-useSelectionController.test.ts
-
-// 测试套件命名
-describe('Selector 组件', () => {
-  describe('单选模式', () => {
-    // 测试用例
-  });
-});
-
-// 测试用例命名
-test('应该正确渲染组件', () => {});
-test('应该在单选模式下使用 Radio', () => {});
-```
-
-### 11.2 测试用例结构
-
-```typescript
-describe('功能描述', () => {
-  // Arrange: 准备测试数据和环境
-  const defaultProps = { ... };
-  
-  // 清理函数（可选）
-  afterEach(() => {
-    cleanup();
-  });
-
-  test('具体测试场景', () => {
-    // Arrange: 准备
-    const handleChange = vi.fn();
-    
-    // Act: 执行
-    const { ... } = render(<Selector {...props} />);
-    // 执行操作...
-    
-    // Assert: 断言
-    expect(...).toBe(...);
-  });
-});
-```
-
-### 11.3 断言最佳实践
-
-```typescript
-// ✅ 好的实践
-expect(element).toBeInTheDocument();
-expect(element).toHaveTextContent('文本');
-expect(handleChange).toHaveBeenCalledWith(expectedValue);
-expect(handleChange).toHaveBeenCalledTimes(1);
-
-// ❌ 避免的实践
-expect(element).not.toBeNull(); // 使用 toBeInTheDocument()
-expect(getByText('文本')).toBeTruthy(); // 直接使用查询结果
-```
-
-### 11.4 异步测试处理
-
-```typescript
-// 使用 waitFor
-test('异步更新测试', async () => {
-  const { getByText } = render(<Selector />);
-  
-  await waitFor(() => {
-    expect(getByText('更新后的文本')).toBeInTheDocument();
-  });
-});
-
-// 使用 findBy
-test('异步查询测试', async () => {
-  const { findByText } = render(<Selector />);
-  const element = await findByText('异步文本');
-  expect(element).toBeInTheDocument();
-});
-```
-
----
-
-## 12. Storybook 可视化测试
-
-### 12.1 Storybook 概述
-
-**Storybook** 是一个用于独立开发和测试 UI 组件的工具。它提供了一个隔离的环境来开发和测试组件，支持交互式组件预览、Props 调试、不同状态展示等。
-
-**在组件测试中的作用**：
-- ✅ **可视化验证**：直观查看组件在不同配置下的渲染效果
-- ✅ **交互测试**：手动测试组件的交互行为
-- ✅ **文档展示**：作为组件使用文档和示例
-- ✅ **回归测试**：通过视觉回归测试发现 UI 变化
-- ✅ **跨团队协作**：设计师和产品可以查看组件效果
-
-### 12.2 Storybook 环境配置
-
-#### 12.2.1 安装与启动
-
-```bash
-# 安装依赖（已在 package.json 中配置）
-pnpm install
-
-# 启动 Storybook
-cd packages/private-materials
-pnpm storybook
-
-# Storybook 将在 http://localhost:6006 启动
-```
-
-#### 12.2.2 配置文件
-
-**主要配置文件**：
-- `.storybook/main.js` - Storybook 主配置
-- `.storybook/preview.js` - Storybook 预览配置
-- `src/pro/Selector/Selector.stories.tsx` - Selector 组件的 Stories
-
-#### 12.2.3 依赖包
-
-```json
-{
-  "devDependencies": {
-    "@storybook/addon-essentials": "^7.6.19",
-    "@storybook/addon-interactions": "^7.6.19",
-    "@storybook/addon-links": "^7.6.19",
-    "@storybook/blocks": "^7.6.19",
-    "@storybook/react": "^7.6.19",
-    "@storybook/react-webpack5": "^7.6.19",
-    "storybook": "^7.6.19"
-  }
-}
-```
-
-### 12.3 Stories 测试用例
-
-#### 12.3.1 Stories 清单
-
-| Story 名称 | 测试场景 | 对应测试用例 | 优先级 |
-|-----------|---------|-------------|--------|
-| Default | 基础单选模式 | TC-S-001, TC-S-002 | P0 |
-| Multiple | 多选模式 | TC-M-001, TC-M-002 | P0 |
-| SingleWithQuantity | 单选 + 数量 | TC-Q-001, TC-Q-002 | P0 |
-| MultipleWithQuantity | 多选 + 数量 | TC-Q-001, TC-M-002 | P0 |
-| GridLayout2Columns | 2列网格布局 | TC-U-002 | P1 |
-| GridLayout3Columns | 3列网格布局 | TC-U-003 | P1 |
-| WithValidation | 校验规则 | TC-V-001 ~ TC-V-005 | P0 |
-| MutexGroups | 互斥组功能 | TC-V-004 | P0 |
-| Disabled | 禁用状态 | TC-I-003, TC-I-004 | P1 |
-| SelectVariant | Select 变体 | TC-SV-003 | P1 |
-| SelectVariantMultiple | 多选下拉 | TC-SV-003, TC-M-001 | P1 |
-| CardVariants | 卡片样式变体 | TC-SV-002, TC-SV-006, TC-SV-007 | P1 |
-| CustomIcon | 自定义图标 | - | P2 |
-| CustomRender | 自定义渲染 | - | P2 |
-| SelectorGroupBasic | 基础分组 | TC-G-001 | P1 |
-| SelectorGroupWithLinkage | 联动规则 | TC-G-002 | P1 |
-
-#### 12.3.2 Stories 使用示例
-
-**基础 Story 定义**：
-
-```typescript
-import type { Meta, StoryObj } from '@storybook/react';
-import Selector from './index';
-
-const meta: Meta<typeof Selector> = {
-  title: 'Pro Components/Selector',
-  component: Selector,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component: '高级选择器组件，支持单选/多选、数量控制、校验规则等功能。',
-      },
-    },
-  },
-  argTypes: {
-    mode: {
-      control: 'select',
-      options: ['single', 'multiple'],
-      description: '选择模式：单选或多选',
-    },
-    valueType: {
-      control: 'select',
-      options: ['primitive', 'object'],
-      description: '值类型：原始值或对象值',
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Selector>;
-
-// 基础 Story 示例
-export const Default: Story = {
-  args: {
-    id: 'default-selector',
-    title: '基础单选',
-    dataSource: [
-      { id: 1, value: 1, label: '选项1', title: '选项1' },
-      { id: 2, value: 2, label: '选项2', title: '选项2' },
-    ],
-    mode: 'single',
-    valueType: 'primitive',
-    fieldNames: { value: 'value', label: 'label' },
-  },
-  render: (args) => {
-    const [value, setValue] = useState<SelectionValue>(1);
-    return (
-      <Selector
-        {...args}
-        value={value}
-        onChange={(v) => {
-          setValue(v);
-          console.log('选中值:', v);
-        }}
-      />
-    );
-  },
-};
-```
-
-### 12.4 Storybook 测试方法
-
-#### 12.4.1 可视化测试
-
-**测试步骤**：
-1. 启动 Storybook：`pnpm storybook`
-2. 在浏览器中打开 `http://localhost:6006`
-3. 选择对应的 Story
-4. 验证组件的视觉呈现是否符合预期
-
-**测试检查项**：
-- ✅ 组件正确渲染，无错误提示
-- ✅ 样式正确显示（布局、颜色、间距等）
-- ✅ 交互状态正确（悬停、选中、禁用等）
-- ✅ 响应式布局正确（不同屏幕尺寸）
-
-#### 12.4.2 交互测试
-
-**使用 Storybook 的交互面板**：
-
-1. **手动交互测试**：
-   - 点击选项，验证选中状态
-   - 调整数量，验证数量控制
-   - 切换不同模式，验证行为差异
-
-2. **Controls 面板测试**：
-   - 调整 `mode` 属性，观察组件变化
-   - 修改 `valueType`，验证值类型切换
-   - 切换 `variant`，查看不同样式变体
-
-3. **Actions 面板**：
-   - 观察 `onChange` 回调的输出
-   - 验证事件触发的参数是否正确
-
-#### 12.4.3 边界场景测试
-
-在 Storybook 中可以方便地测试各种边界场景：
-
-```typescript
-// 空数据源测试
-export const EmptyDataSource: Story = {
-  args: {
-    dataSource: [],
-    title: '空数据源',
-  },
-};
-
-// 单条数据测试
-export const SingleItem: Story = {
-  args: {
-    dataSource: [
-      { id: 1, value: 1, label: '唯一选项', title: '唯一选项' },
-    ],
-  },
-};
-
-// 大量数据测试（性能验证）
-export const LargeDataset: Story = {
-  args: {
-    dataSource: Array.from({ length: 100 }, (_, i) => ({
-      id: i + 1,
-      value: i + 1,
-      label: `选项${i + 1}`,
-      title: `选项${i + 1}`,
-    })),
-  },
-};
-```
-
-#### 12.4.4 跨浏览器测试
-
-使用 Storybook 在不同浏览器中测试：
-- Chrome
-- Firefox
-- Safari
-- Edge
-
-**测试重点**：
-- ✅ 样式兼容性
-- ✅ 交互行为一致性
-- ✅ 性能表现
-
-### 12.5 Storybook 与单元测试的区别
-
-| 对比项 | Storybook | 单元测试 (Vitest) |
-|-------|-----------|-------------------|
-| **测试类型** | 可视化、手动验证 | 自动化、断言验证 |
-| **执行方式** | 手动运行，人工检查 | 自动运行，CI/CD |
-| **测试场景** | UI 渲染、交互体验 | 逻辑正确性、边界条件 |
-| **覆盖范围** | 核心场景、典型用例 | 全面覆盖、边界异常 |
-| **反馈速度** | 即时可视化 | 快速执行结果 |
-| **维护成本** | 需要人工检查 | 自动化维护 |
-| **适用场景** | 开发调试、UI 验收 | 回归测试、CI 集成 |
-
-**互补关系**：
-- ✅ **Storybook**：用于开发阶段的快速验证和 UI 验收
-- ✅ **单元测试**：用于保证逻辑正确性和自动化回归测试
-- ✅ **两者结合**：Storybook 确保 UI 正确，单元测试确保逻辑正确
-
-### 12.6 Storybook 测试用例执行清单
-
-#### 12.6.1 基础功能验证
-
-- [ ] **Default**: 单选模式正常渲染
-- [ ] **Multiple**: 多选模式正常渲染
-- [ ] **SingleWithQuantity**: 单选 + 数量功能正常
-- [ ] **MultipleWithQuantity**: 多选 + 数量功能正常
-
-#### 12.6.2 布局验证
-
-- [ ] **GridLayout2Columns**: 2列布局正确
-- [ ] **GridLayout3Columns**: 3列布局正确
-- [ ] 响应式布局在不同屏幕尺寸下正常
-
-#### 12.6.3 校验功能验证
-
-- [ ] **WithValidation**: 校验规则生效
-- [ ] **MutexGroups**: 互斥组功能正确
-- [ ] 错误信息正确显示
-
-#### 12.6.4 样式变体验证
-
-- [ ] **SelectVariant**: Select 变体正常
-- [ ] **CardVariants**: 卡片样式变体正确
-- [ ] **CustomIcon**: 自定义图标正常显示
-- [ ] **CustomRender**: 自定义渲染正确
-
-#### 12.6.5 分组组件验证
-
-- [ ] **SelectorGroupBasic**: 基础分组功能
-- [ ] **SelectorGroupWithLinkage**: 联动规则生效
-
-### 12.7 Storybook 测试最佳实践
-
-#### 12.7.1 Story 组织原则
-
-```typescript
-// ✅ 好的实践：按功能分组
-export default {
-  title: 'Pro Components/Selector',
-  component: Selector,
-};
-
-// ✅ 好的实践：清晰的 Story 命名
-export const SingleSelection = { ... };
-export const MultipleSelection = { ... };
-export const WithQuantity = { ... };
-
-// ❌ 避免的实践：模糊的命名
-export const Test1 = { ... };
-export const Example = { ... };
-```
-
-#### 12.7.2 Story 参数配置
-
-```typescript
-// ✅ 好的实践：提供完整的 argTypes
-const meta: Meta<typeof Selector> = {
-  argTypes: {
-    mode: {
-      control: 'select',
-      options: ['single', 'multiple'],
-      description: '选择模式',
-      table: {
-        type: { summary: 'single | multiple' },
-        defaultValue: { summary: 'single' },
-      },
-    },
-  },
-};
-
-// ✅ 好的实践：使用真实数据
-export const RealWorldExample: Story = {
-  args: {
-    dataSource: realisticDataSource, // 使用真实业务数据
-  },
-};
-```
-
-#### 12.7.3 交互式测试
-
-```typescript
-// ✅ 好的实践：使用 Controls 进行交互测试
-export const InteractiveExample: Story = {
-  args: {
-    // 所有 props 都可以通过 Controls 面板调整
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: '使用 Controls 面板调整属性，实时查看组件变化。',
-      },
-    },
-  },
-};
-```
----
-
-## 13. 测试维护指南
-
-### 13.1 测试用例更新
-
-当组件发生变更时：
-1. ✅ 检查现有测试用例是否需要更新
-2. ✅ 添加新功能的测试用例
-3. ✅ 更新测试数据以覆盖新场景
-4. ✅ 确保所有测试通过
-
-### 13.2 测试用例审查清单
-
-- [ ] 测试用例覆盖核心功能
-- [ ] 边界条件有测试覆盖
-- [ ] 异常情况有处理
-- [ ] 测试代码可读性强
-- [ ] 测试数据合理
-- [ ] 断言准确明确
-- [ ] 无冗余测试
-
----
-
-## 14. 附录
-
-### 14.1 测试工具参考
-
-- [Vitest 文档](https://vitest.dev/)
-- [React Testing Library 文档](https://testing-library.com/react)
-- [Testing Library 查询优先级](https://testing-library.com/docs/queries/about/#priority)
-- [Storybook 文档](https://storybook.js.org/)
-- [Storybook React 文档](https://storybook.js.org/docs/react/get-started/introduction)
-
-### 14.2 相关文档
-
-- [开发文档](https://studio.picoding-dev.com/pro-components/selector?tab=dev)
-- [设计文档](https://m1ed09stz4r.feishu.cn/wiki/NL5AwOs0ei5ZBekT4i6cuzIOnoM)
-- [Storybook 使用指南](./STORYBOOK.md)