侧栏菜单（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。

修订记录