# CSideMenu 组件规格说明

## 1. 概述与范围

本规格描述 `CSideMenu` 组件的技术契约：数据树、三级菜单、全局手风琴、响应式侧栏、antd `Layout.Sider` / `Menu` 的组合。

- **依赖**：React、antd v6、`@ant-design/icons`
- **范围**：侧栏容器、菜单渲染、遮罩
- **非目标**：路由与子页实现、自定义滚动条

---

## 2. 数据模型

### MenuTree（宿主传入）

```typescript
interface MenuItem {
  key: string | number;      // 唯一标识
  label: string;              // 显示文本
  children?: MenuItem[];      // 子菜单
  path?: string;              // 页面路径
  pageName?: string;         // 页面名称
  type?: 'chart' | 'setting' | 'folder' | 'file';  // 图标类型
}

interface MenuTree extends MenuItem {}
```

### 组件 Props

```typescript
interface CSideMenuProps {
  title: string;                           // 顶区标题
  tree?: MenuTree;                         // 合并后的菜单树
  collapsed: boolean;                      // 是否收起
  curActivePaneKey?: string | number;     // 当前选中键
  panesOnShelf?: Array<{ key: string }>; // 已打开页签列表
  onClickMenuItem: (item: MenuItem) => void;
  onSetMenuCollapse: (collapsed: boolean | void) => void;
}
```

---

## 3. 组件行为

### Requirement: 三级菜单树渲染
组件 SHALL 从注入的 `tree` 数据结构渲染三级菜单树。结构为 `key > label > children > key > label > children`。每个节点 SHALL 包含 `id`、`name`、可选 `type` 字段。当节点包含非空 `children` 时，SHALL 渲染为 SubMenu；否则为叶子项。

### Requirement: 全局手风琴展开
当用户展开一个节点时，组件 SHALL 关闭之前展开的节点。全局最多同时只有一个展开分支。

### Requirement: 响应式固定模式
当视口宽度低于 `lg` 断点时（移动端），侧边栏 SHALL 进入固定模式，以 `position: fixed` 悬浮覆盖在内容之上。当菜单展开时 SHALL 显示背景遮罩，点击遮罩 SHALL 触发收起。PC 端不启用覆盖模式。

### Requirement: 固定模式延迟导航
在固定模式下，当用户点击叶子项时，组件 SHALL 先触发收起（`onSetMenuCollapse(true)`），然后在约 300ms 延迟后调用 `onClickMenuItem`，以避免动画闪烁。

### Requirement: 菜单项点击回调
当用户点击叶子菜单项时，组件 SHALL 调用 `onClickMenuItem`，传入完整的菜单项对象，至少包含 `id`、`name`、`path`、`pageName` 字段。

### Requirement: 折叠状态回调
组件 SHALL 支持 `onSetMenuCollapse` 的两种调用模式：boolean 参数（设置精确折叠状态）和无参调用（切换）。宿主应用 SHALL 处理这两种模式。

### Requirement: 空树处理
当注入的 `tree` 为空或 undefined 时，组件 SHALL 渲染标题区域和空菜单区域，且不抛出错误。

### Requirement: 当前选中键高亮
当 `curActivePaneKey` 与菜单节点的 `id` 或 `key` 匹配时，该节点 SHALL 显示选中样式。当叶子项被选中时，其所属 SubMenu SHALL 显示子树选中样式。

### Requirement: 已打开标签指示器
当 `panesOnShelf` 中的某个条目的 `key` 与叶子节点的 `id` 匹配时，该叶子 SHALL 显示"已打开"指示器样式。

---

## 4. 图标映射

| type 值 | 图标 |
|---------|------|
| chart | PieChartOutlined |
| setting | SettingOutlined |
| folder | FolderOutlined |
| file (默认) | FileOutlined |

---

## 5. 响应式断点

- **PC 端**：`breakpoint="lg"` (992px) 以上，使用 antd Layout.Sider
- **移动端**：992px 及以下，使用固定定位覆盖层 + 遮罩