# 侧栏菜单（Side Menu）— 架构 / 产品决策

**状态**：生效中

本文记录侧栏菜单相关**取舍**；行为细节以 `spec.md` 为准，**可勾选验收**以 `task.md` 为准。

---

### 同级手风琴式展开

- **状态**：生效
- **上下文**：多级菜单若允许多个同级分支同时展开，信息密度高、滚动长，且与常见后台导航习惯不一致。
- **决策**：在**同一父节点下**，同时仅保留一个展开子分支；用户显式收起时尊重其操作。
- **后果**：需在 Ant Design `Menu` 的 `onOpenChange` 与自定义子菜单层**两处**保持一致语义，避免二级与三级行为分裂。SPEC §4.2。

---

### 断点以下采用固定全宽 + 遮罩

- **状态**：生效
- **上下文**：窄屏下窄侧栏可读性与可点性差，且需让出主内容区。
- **决策**：低于 `lg` 量级断点时侧栏改为覆盖式（fixed），展开时配合全宽类表现与遮罩，点击遮罩关闭。
- **后果**：与宿主折叠状态强耦合；须通过回调同步。SPEC §3.2、§4.5。

---

### 固定模式下延迟导航

- **状态**：生效
- **上下文**：收起动画与立即路由/开页同时进行时易出现闪烁或竞态。
- **决策**：固定模式下先触发收起，再延迟约 300ms 调用「打开页」。
- **后果**：实现须严格保证顺序；延迟与壳子动画时长应对齐。SPEC §4.3。

---

### 自定义滚动条而非纯系统滚动条

- **状态**：生效
- **上下文**：深色主题侧栏与系统滚动条样式、宽度不一致时破坏视觉对齐；需统一轨道与滑块。
- **决策**：在内容可滚动时使用自绘轨道/滑块，并与 `scrollTop` 同步；resize 时重算。
- **后果**：实现复杂度高于原生滚动条；需处理拖拽与遮罩的交互冲突及多段动效。SPEC §4.4、§4.5、§5.3。

---

### 菜单数据由宿主注入

- **状态**：生效
- **上下文**：权限、租户、动态路由等差异应在壳子或数据层处理。
- **决策**：组件只消费树与运行态，不内置请求与策略。
- **后果**：SPEC 必须写清数据字段与回调语义，否则对接易歧义。SPEC §2、§6。

---

### 静态路径骨架与接口权限数据分离

- **状态**：生效
- **上下文**：常见做法是静态配置中的 `treePaths` 固定页面路径与分组，接口返回分组/条目做权限与展示控制，二者在宿主或数据层合并。
- **决策**：侧栏组件不直接读取静态配置文件；仅展示宿主传入的**已合并** `tree`。路径与 `pageName` 的权威定义在数据层。
- **后果**：「菜单从哪来」须在宿主或数据层单独说明；侧栏 TASK 以合并后数据验收。SPEC §2.3、§2.4。

---

### 侧栏外「按 pageName 找页」与多级树的潜在不一致（宿主债）

- **状态**：生效（已知限制）
- **上下文**：若宿主提供「按 `pageName` 打开页」的辅助逻辑，且实现为仅在每个分组下**一层** `items` 上线性扫描，则一旦静态或合并后的树出现**嵌套二级以上的可点击页**，会找不到或行为错误。
- **决策**：不在侧栏组件内解决；由宿主保证「按名开页」与真实树深度一致（必要时改为递归查找）。
- **后果**：侧栏实现三级 UI 时，应提醒宿主团队校对同类辅助方法。与 SPEC §2.1 层级支持配套。

---

### `onSetMenuCollapse` 支持 boolean 与无参两种调用

- **状态**：生效
- **上下文**：`Layout.Sider` 断点回调常传入 `broken`，顶栏按钮则多触发无参「切换」。
- **决策**：宿主统一处理：`boolean` 时设为对应折叠态，无参时按约定切换或收起。
- **后果**：侧栏须能触发上述两类调用，避免 antd@6 升级后只处理其中一种。SPEC §6.2。

---

## 修订记录

| 日期 | 摘要 |
|------|------|
| 2026-04-07 | 初稿 |
| 2026-04-07 | 明确验收以 task.md 为准 |
| 2026-04-07 | 补充路径骨架与 API 分离、折叠回调双形态、按 pageName 查找层级限制 |
| 2026-04-07 | 去除具体文件/类名，改为职责级描述 |
| 2026-04-07 | 节号随 SPEC §5 动效 / §6 契约调整 |