@done-coding/admin-core 0.18.0 → 0.19.0

package/src/components/form/docs/README-FormSubmitPanel.md

@@ -0,0 +1,97 @@
+# FormSubmitPanel（提交表单面板）
+
+> FormMain 的提交面：`stringifyData` 作初值 + 内置「校验 → 序列化 → 提交」管线 + 取消 / 重置 / 提交操作区（可插槽替换），success / fail / parseDataChange 三事件闭环。
+> 范式页：`apps/reference/src/pages/form/submit-panel/showcase/`
+
+## 定位
+
+- **空间一等公民**：纯表单提交空间首选（表单页 / 弹窗内表单）——业务层能用 FormMain 处用 FormSubmitPanel 替代
+- **何时用**：录入 / 编辑弹窗或页面的表单主体——需要完整提交管线 + 操作区
+- **何时不用**：纯查询 / 搜索用 `FormSearch`；仅录入无提交操作区用 `FormMain`；只要一个提交按钮（无面板壳）用 `FormSubmitBtn` 挂 FormMain
+- 与 FormMain 的差异：`data` 被 Omit——表单值由 `stringifyData` 初值内部管理（优先 `parseFormData` 回填，否则 `generateFormData` 初始化），消费方不持有 data
+- 内置组合：`FormSubmitBtn`（提交按钮，validate → stringify → submitFn → loading 管线）；`inheritAttrs: false`，attrs 转发内层 FormMain
+
+## 快速上手（最小可用）
+
+单面板最小形态（list + stringifyData 回填 + submitFn + 成功 / 失败回调即完整）：
+
+```html
+<FormSubmitPanel :list="list" :stringifyData="seed" :submitFn="submitFn"
+  @success="onSuccess" @fail="onFail" />
+```
+
+**要点**：
+
+- `submitFn` 收 `stringifyData` 返回 Promise——提交成功后 `@success` 直接透传同一 `stringifyData` 载荷（新增 / 编辑区分由消费方按上下文定）
+- `stringifyData` 作初值：回填数据直接给序列化形态，面板内部消化解析 / 初始化（不传则 `generateFormData(list)` 初始化）
+- 校验 → 序列化 → 提交 → loading 管线内置，消费方零接线；`@parse-data-change` 回传内部解析模型（如 reset 后），供外部联动
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`list` + `submitFn` + `@success` / `@fail` 即为完整提交面板**（无回填时 `stringifyData` 可省，内部 `generateFormData` 初始化）。
+- `cancelBtn` / `resetBtn`：默认未设 = 不展示；仅当需要取消 / 重置操作才设按钮文字（按钮顺序固定：取消 → 重置 → 提交）。
+- `operationPosition`：默认 `bottom-center` 即够用；仅当面板布局需要（如页内表单放右下）才改。
+- `operationAffix`：默认关；仅当长表单提交区需要吸底固定才开（`true`=吸底 `position: "bottom"`，对象=ElAffix 原样透传）。
+- `submitBtnProps`：默认 primary 即够用；仅当需改提交按钮形态（size / 其他 ButtonProps）才设。
+- `#cancelBtn` / `#resetBtn` / `#submitBtn` 三插槽：默认关；仅当按钮需完全自定义时开（`#submitBtn` 接内置校验 + 序列化 + 提交管线）。
+- `divider` / `bare` / `rootClass`：默认即够用；仅当面板视觉定制（去分割线 / 去内边距 / 根类定向）才动。
+- **完整能力演示**（操作区三态 + 插槽替换 + 图钉）：`apps/reference/src/pages/form/submit-panel/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `PO` 解析 / `SO` 格式化，`FormSubmitPanelProps<PO, SO>` = `Omit<FormMainProps, "data">` + 提交相关）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `list` | `FormItemConfigList`（必填） | — | 透传 FormMain |
+| `layout` | `Partial<ColProps>` | `{span: 24}` | 透传（默认单列） |
+| `rowGutter` / `layoutScale` | 同 FormMain | — | 已声明 prop 不入 attrs 且未显式转发——**实际被丢弃**（layoutScale / layoutByContainer 均不生效） |
+| `stringifyData` | `ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>` | 未设 | 序列化数据作初值（优先 `parseFormData` 回填，否则 `generateFormData` 初始化） |
+| `submitText` | `string` | 未设 | 提交按钮文本 |
+| `submitFn` | `(stringifyData) => Promise<unknown>`（必填） | — | 提交方法 |
+| `submitBtnProps` | `Omit<FormSubmitBtnProps, "submitText" \| "submitFn" \| "formMainInstance">` | 未设 | 内置 FormSubmitBtn 的额外 ButtonProps（如 `{ type: 'primary' }`） |
+| `labelPosition` | `"right" \| "left" \| "top"` | `"right"` | 标签位置 |
+| `labelWidth` | `string` | `"auto"` | 标签宽度 |
+| `cancelBtn` | `string` | 未设 | 取消按钮文字（空则不展示；同名插槽优先） |
+| `resetBtn` | `string` | 未设 | 重置按钮文字（警告色；同名插槽优先） |
+| `operationPosition` | `"bottom-center" \| "bottom-right" \| "top-right"` | `"bottom-center"` | 操作区位置 |
+| `operationAffix` | `boolean \| AffixProps` | `false` | 操作区图钉（`true`=吸底 `position: "bottom"`；对象=原样透传 ElAffix） |
+| `divider` | `boolean` | `true` | 操作区分隔线 + 圆角 |
+| `bare` | `boolean` | `false` | 去操作区内边距（与 divider 正交） |
+| `rootClass` | `string \| string[] \| Record<string, boolean>` | 未设 | 根面板自定义 class（`inheritAttrs: false` 下 class 会透传内层 FormMain，本 prop 是显式根出口） |
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `cancel` | — | 取消触发 |
+| `fail` | `error: any` | 提交失败（submitFn reject） |
+| `success` | `FormDataInfo["stringifyData"]` | 提交成功（submitFn resolve，透传 stringifyData 载荷） |
+| `parseDataChange` | `PO` | 内部 parseData 变化（reset 只内部 set parseData，经此事件通知外部） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#cancelBtn` | `{ cancel }` | 替换取消按钮（cancelBtn 为空时也可经此插自定义取消） |
+| `#resetBtn` | `{ reset }` | 替换重置按钮 |
+| `#submitBtn` | `{ submit, submitting }` | 替换提交按钮（接内置校验 + 序列化 + 提交管线，可全替换按钮） |
+| `#<config.key>` | FormItem 内部 mainProps | 覆盖单项（透传 FormMain） |
+
+### Expose
+
+无（表单实例内置，不对外暴露 ref 方法）。
+
+## 反模式 / 注意
+
+- **外部传 `data`**：类型已 Omit（`Omit<FormMainProps, "data">`）——表单值由 `stringifyData` 初值内部管理，外部回填走 `stringifyData`，联动走 `@parse-data-change`
+- **`layoutByContainer` / `layoutScale` 无效**：已声明 prop 不入 attrs 且未显式转发——确定不生效；容器断点场景用 FormMain 或 FormSearch（其 layoutByContainer 显式转发）
+- **手工拼提交载荷**：`submitFn` 收的即是序列化形态，`@success` 同载荷透传——提交 / 回传 / 回填三段共用同一 `stringifyData`，勿在中间自造转换
+- **reset 语义**：reset 只内部 set parseData（回到初值快照，初值来自 `stringifyData` 或缺省 `generateFormData`），非清空到空白——需要空白态直接重给 `stringifyData`
+
+## 关联
+
+- 表单族：`FormMain`（底座）、`FormSubmitBtn`（内置提交按钮，经 `submitBtnProps` 定制）、`FormSearch`（搜索面）
+- 类型：`FormDataInfo<PO, SO>` = `{ parseData, stringifyData }`（success / parseDataChange 载荷）；`ExtractFormStringifyRawFromObject`（类型级提取）
+- 范式页：`apps/reference/src/pages/form/submit-panel/showcase/`

package/src/components/list-page/README.md

@@ -0,0 +1,16 @@
+# list-page 列表族
+
+单组件族：`ListPage` =「FormSearch + TableMain」组合页，一个组件承接搜索、列表、分页、工具栏、粘性吸附全链路；双子 props 扁平化 + 常用项提升直属。
+
+## 组件文档（docs/）
+
+- [ListPage](./docs/README-ListPage.md) — 列表页（表单侧 / 表格侧双子配置 + injectInfo 注入 + 三件套粘性）
+
+## 关键类型
+
+- `ListPageProps` / `ListPageInstance`（= FormSearchInstance + TableMainInstance + update）/ `ListPageInnerInjectInfo`（列插槽注入：triggerSearch / triggerReset / update）
+- 内部不导出：`use-sticky`
+
+## 范式页（apps/reference）
+
+- `/list-page/guide`（最佳实践：搜索 + 弹窗 CRUD + 分离侧栏）/ `/list-page/sticky`（三件套粘性）/ `/list-page/module-demo`（keepAlive 模块组合）

package/src/components/list-page/docs/README-ListPage.md

@@ -0,0 +1,136 @@
+# ListPage（列表页）
+
+> 「FormSearch + TableMain」组合页：一个组件承接搜索、列表、分页、工具栏、粘性吸附全链路。
+> 范式页：`apps/reference/src/pages/list-page/guide/`（最佳实践）、`pages/list-page/sticky/`（粘性）、`pages/list-page/module-demo/`（keepAlive 模块组合）
+
+## 定位
+
+- **空间一等公民**：列表空间首选（搜索 + 表格 + 分页 + 粘性全链路），常规列表页 [MUST] 用它
+- **何时用**：标准列表页（搜索 + 表格 + 分页 + 操作列），是最常用页面骨架
+- **何时不用**：纯表格（无搜索）用 `TableMain`；纯搜索表单用 `FormSearch`
+- 内部组合：`FormSearch`（搜索区）+ `TableMain`（表格区），props 按「表单侧 / 表格侧」双子配置扁平化，常用项提升为直属 prop
+
+## 快速上手（最小可用）
+
+配置面（`guide/config.tsx` 范式 A 摘要——标准列表页最低配置，默认行为即够用）：
+
+```tsx
+const listPageConfig = {
+  api: userListApi,          // 列表取数（TableApiParams / TableApiResult 契约）
+  list: userSearchFormList,  // 搜索表单配置（FormItemConfigList）
+  columns,                   // 列配置（ElTableColumnProps 超集，render 三态）
+  rowKey: "id",
+  injectInfo,                // 自定义只读上下文，列 render 里 scope.injectInfo 消费
+};
+```
+
+挂载 + 注入触发（`module-demo/list/Index.vue` 最小闭环）：
+
+```ts
+import { ListPage } from "@done-coding/admin-core";
+import type { ListPageInstance } from "@done-coding/admin-core";
+const listPage = ref<ListPageInstance>();
+const { listPageConfig } = useSpaceConfig({
+  goDetail: (id?: number) =>
+    router.push({ path: "/list-page/module-demo/detail",
+      query: id === undefined ? {} : { id: String(id) } }),
+  reloadList: () => listPage.value?.reload(),   // 增删改成功后触发
+});
+```
+
+```html
+<AppPage>
+  <ListPage ref="listPage" v-bind="listPageConfig" />
+</AppPage>
+```
+
+**要点**：
+
+- `staticQuery` 是扁平 prop，**禁放 `formSearchProps` 内**（类型已 Omit）
+- keepAlive 返回刷新由 core 内置承担（TableMain onActivated 自动 refresh 留页码）——**[MUST NOT]** app 侧再手写刷新信号补偿（双重请求反模式）
+
+## 能力边界 / 按需使用
+
+- **`toolbar`（工具栏）：默认无即够用。** 仅当需要新增 / 批量删除等操作按钮才配 `leftExtraButtons`（ActionBtnGroup 配置形态）；操作依赖选中行时经 `ctx.selectedList` 联动 disabled。
+- **`separateSearch`（分离侧栏）：默认关（搜索在表格上方一体布局）。** 仅当搜索项多、需「搜索独立侧栏 + 主区纯表格」才开——开启后 header/搜索/操作区整体入侧栏，aside 与表格 maxHeight 同源；⚠️ 分离态下 `searchSticky` 被无视。
+- **`searchSticky` / `toolbarSticky` / `pagerSticky`（三件套粘性）：默认全关。** 仅当页面长滚时需搜索 / 工具栏 / 分页吸附才按需开（toolbarSticky 叠钉搜索区下方）。
+- **`showSwitchView`（双视图切换）：默认关（表格单一视图）。** 仅当需要「列表 / 卡片」双视图切换才开（配 `#custom-view-item` 卡片渲染）。
+- **`isAutoRefresh` / `refreshInterval`：默认关（不自动刷新）。** 仅当列表需轮询刷新（任务态实时变化等）才开。
+- **高度链 prop（`refine` / `viewportHeight` / `parentChannel`）：默认 ListPage 内部已接管**（refine 默认 true）——常规无需干预，仅特殊高度场景覆写。
+- **完整能力演示**（toolbar 全形态 + 粘性三件套 + keepAlive 组合）：`apps/reference/src/pages/list-page/guide/`（最佳实践）、`pages/list-page/sticky/`（粘性）、`pages/list-page/module-demo/`（keepAlive 模块组合）——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（泛型 `T` 行 / `PO` 解析 / `SO` 格式化 / `SQ` 静态 / `F` 注入）
+
+**表单侧（FormSearch 双子）**
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `list` | `FormItemConfigList<PO, SO>` | `[]` | 搜索表单配置（ListPage 据此推 PO/SO，data 内部生成） |
+| `staticQuery` | `SQ` | `{}` | 静态参数（扁平顶到 ListPage，禁放 formSearchProps 内） |
+| `formSearchProps` | `Partial<Omit<FormSearchProps<PO,SO,{}>, "staticQuery"\|"list"\|"compact">>` | 未设 | FormSearch 透传袋（compact 由内部 separateSearch 驱动，外部 [MUST NOT] 覆盖） |
+
+**表格侧（TableMain 双子）**
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `columns` | `TableMainProps["columns"]`（必填） | — | 列配置（扁平等级） |
+| `rowKey` | `Extract<keyof T, string> \| ((row:T)=>string)`（必填） | — | 行键 |
+| `api` | `(params: TableApiParams<ExtractFormStringifyFromObject<PO,SO> & SQ>) => Promise<TableApiResult<T>>`（必填） | — | 列表取数 |
+| `refine` / `refineReduceHeight` / `viewportHeight` / `parentChannel` / `toolbar` / `showSwitchView` | 同 TableMain | refine `true`、refineReduceHeight `0` | 常用配置提升为直属扁平 prop（内部自行消化视口高度链；TableMain 恒收 `:refine="false"`，高度计算由 ListPage 接管） |
+| `tableMainProps` | `Partial<Omit<TableMainProps, 上述 6 键 \| "api" \| "query" \| "injectInfo">>` | 未设 | TableMain 透传袋 |
+
+**直属行为 props**
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `query` | `SQ` | — | ⚠️ types 声明但组件内未消费（疑似历史残留），勿依赖 |
+| `injectInfo` | `F` | 未设 | 自定义只读上下文，合并进列插槽 scope.injectInfo（只读消费通道） |
+| `beforeSearch` | `(data, type) => data` | 未设 | 搜索前同步回调（可改写参数） |
+| `clearTableFilterOnReset` | `boolean` | 未设 | 重置时同时清空表头过滤 |
+| `separateSearch` | `boolean` | `false` | 搜索/header/操作区整体移入侧栏 |
+| `separateSearchConfig` | `Pick<SlotLayoutFlowAsideProps, "type"\|"gap"\|"asideWidth">` | 未设 | 分离侧栏布局 |
+| `searchSticky` / `toolbarSticky` / `pagerSticky` | `boolean` | 均 `false` | 三件套粘性（分离态下 searchSticky 被无视） |
+| `headerObserveResize` / `operationObserveResize` | `boolean` | 均 `false` | header/操作槽量高 ResizeObserver |
+
+**v-model**：`isAutoRefresh`、`refreshInterval`、`customView`（配合 `#custom-view-item` 卡片渲染）
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `dataChange` | `T[]` | 数据变更 |
+| `pageInfoChange` | `TablePageInfo` | 分页信息（pageSize/currentPage/total） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#header` / `#operation` | 无 | 搜索区上下扩展 |
+| `#custom-view-item` | `DataListViewItemScope<T>` | customView 模式单项卡片渲染 |
+| `#form-<key>` | `FormScope` | 覆盖搜索表单单项 |
+| `#table-<prop>` | `TableColumnDefaultScope<T, ListPageInnerInjectInfo<PO,F>>` | 覆盖列单元格 |
+| `#table-header-<prop>` | `TableColumnHeaderScope & { searchFormData: PO; triggerSearch?: () => void }` | 覆盖列表头（可联动搜索） |
+
+### Expose（`ListPageInstance` = FormSearchInstance + TableMainInstance + update）
+
+`refresh(silent?)` / `reload(silent?)` / `getTableInstance()` / `validate()` / `resetFields()` / `clearValidate(key?)` / `triggerReset()` / `triggerSearch()` / `toggleCollapse(next?)` / `isCollapsed` / `update(key, value)`（改内部表单数据）
+
+**注入机制**：`injectInfoAdjust` 把 `triggerReset` / `triggerSearch` / `update` 合并进 TableMain `:injectInfo` —— 列插槽 `scope.injectInfo` 可直接 `triggerSearch()` / `triggerReset()` / `update(key, value)`（类型 `ListPageInnerInjectInfo<PO,F>`）。
+
+## 反模式 / 注意
+
+- **搜索表单用 FormSearch 的 `#default`**：被内置按钮盒占用，消费方默认插槽不渲染
+- **`query` prop 勿用**：声明未消费（疑似历史残留）
+- **keepAlive 页返回刷新**：core 内置（onActivated refresh 留页码），app 侧 [MUST NOT] 补偿
+- **formSearchProps 塞 staticQuery/compact**：类型已 Omit，编译即拦
+- 搜索/表格的双子 props 与 TableMain 直属 prop 重复时，**以 ListPage 直属为准**（TableMain 恒收 refine=false）
+
+## 关联
+
+- 内部组件：`FormSearch`（form 族）、`TableMain`（table 族）
+- 列表接口模型：`APP_API_LIST_MODEL_KEY_CONFIG`（core config 单源，api 参数/结果类型由它推导）
+- 高度链：`refine` + `viewportHeight`/`parentChannel`（见 TableMain 文档）
+- 范式页：`apps/reference/src/pages/list-page/guide/`、`pages/list-page/sticky/`、`pages/list-page/module-demo/`

package/src/components/menu/README.md

@@ -0,0 +1,19 @@
+# menu 菜单族
+
+配置化菜单族：`MenuTree`（基于 ElMenu 的树形菜单）+ `MenuItemSub`（递归子菜单分组件，MenuTree 内部递归用）。
+
+## 组件文档（docs/）
+
+- [MenuTree](./docs/README-MenuTree.md) — 树形菜单（menus 递归出 ElSubMenu + routerMode / autoClose / collapse + open/close expose）
+- [MenuItemSub](./docs/README-MenuItemSub.md) — 递归子菜单分组件（ElSubMenu 递归节点，一般由 MenuTree 自用）
+
+## 关键类型
+
+- `RouteMetaResolveRaw`（@/types，menus / menuFlatList 数据契约）
+- 内部不导出：无（MenuTree / MenuItemSub 均进 core 顶层，无 types.ts）
+
+## 范式页（apps/reference）
+
+- 真实消费方：`AppSidebar`（packages/core/src/components/app-layout/AppSidebar.vue）——生产级驱动点
+- 菜单数据契约范式：`apps/reference/src/router/modules/test.ts`（meta.menu 的 show / icon / sort 驱动渲染与排序）
+- 注意：`/menu/showcase/Page1/2/3` 是菜单渲染出的叶子路由页，不是 MenuTree 的用法示范

package/src/components/menu/docs/README-MenuItemSub.md

@@ -0,0 +1,53 @@
+# MenuItemSub（递归子菜单分组件）
+
+> ElSubMenu 递归分组：含 children 的节点递归渲染子菜单、叶子渲染 ElMenuItem；由 MenuTree 递归自用。
+> 范式页：`packages/core/src/components/menu/MenuTree.vue`（内部消费方）
+
+## 定位
+
+- 递归子菜单分组件：节点含 `children` → `ElSubMenu` + 递归子级；叶子 → `ElMenuItem`
+- 组件自引用：`MenuItemSub` prop 传入组件自身，供 children 递归再实例化
+- 一般由 `MenuTree` 内部使用，独立消费场景少见
+
+## 快速上手（最小可用）
+
+MenuTree 内部驱动（menu/MenuTree.vue 片段）：
+
+```html
+<MenuItemSub :menu="menu!" :MenuItemSub="MenuItemSub" />
+```
+
+## 能力边界 / 按需使用
+
+- **内部递归件，勿直用：MenuTree 递归自用的分组件，独立消费场景少见。** 业务侧 [MUST NOT] 直接 import 消费——children 递归靠 `MenuItemSub` prop 自引用再实例化，仅由 MenuTree 内部驱动。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `menu` | `RouteMetaResolveRaw`（必填） | — | 当前分组节点 |
+| `MenuItemSub` | `any`（必填） | — | 组件自引用，供 children 递归再实例化 |
+
+### Emits
+
+无
+
+### Slots
+
+无（ElSubMenu 标题与子项均由 menu 数据驱动）
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **缺自引用 prop**：children 递归靠 `MenuItemSub` prop 再实例化，缺它无法递归展开子级
+
+## 关联
+
+- 消费方：`MenuTree`（menu 族）
+- 数据契约：`RouteMetaResolveRaw`（@/types）

package/src/components/menu/docs/README-MenuTree.md

@@ -0,0 +1,76 @@
+# MenuTree（树形菜单）
+
+> 基于 ElMenu 的配置化树形菜单：menus 树形数据递归出 ElSubMenu，叶子渲染 ElMenuItem；routerMode 路由联动、autoClose 选中收合、collapse 折叠透传。
+> 范式页：真实消费方为 `AppSidebar`（packages/core/src/components/app-layout/AppSidebar.vue）；菜单数据契约范式见 `apps/reference/src/router/modules/test.ts`
+
+## 定位
+
+- **何时用**：侧栏 / 导航需要配置驱动的树形菜单（递归子菜单、路由联动、折叠态）
+- **何时不用**：单层 / 少量菜单直接用 ElMenu；菜单数据不来自路由配置时自行组装数据再接入
+- 数据驱动：`menus` 树形节点含 `children` 递归出 `ElSubMenu`，叶子渲染 `ElMenuItem`；`menuFlatList` 拍平列表供 autoClose 沿 `parentPath` 递归算父链
+- 增强点：routerMode（defaultActive 取 route.path + ElMenu :router）、autoClose（选中一项收合其它展开子菜单）、collapse 透传、ElMenu 其余 attrs 整包透传、open / close expose
+
+## 快速上手（最小可用）
+
+必填只有 `menus` + `menuFlatList`——默认 ElMenu 主题、无路由联动、无选中收合：
+
+```html
+<MenuTree :menus="menus" :menuFlatList="menuFlatList" />
+```
+
+**要点**：
+
+- `menus` 必填：树形菜单数据；含 `children` 的节点递归出 `ElSubMenu`
+- `menuFlatList` 必填：拍平列表，autoClose 时沿 `parentPath` 算父链
+- 菜单数据契约（范式 `apps/reference/src/router/modules/test.ts`）：`meta.menu` 的 `show` / `icon` / `sort` 驱动渲染与排序；`/menu/showcase/page1|page3|page2` 三级嵌套演示递归子菜单，`sort` 1/2/3 演示排序
+
+## 能力边界 / 按需使用
+
+- **`routerMode`：默认关即够用。** 仅当菜单项与路由 path 联动高亮才开——开启后 `defaultActive` 自动取 `route.path`（useRoute）+ ElMenu `:router` 同步开启；注意依赖 vue-router 上下文。
+- **`autoClose`：默认关即够用。** 仅当「选中一项后收合其它展开子菜单」才开——父链沿 `menuFlatList` 的 `parentPath` 递归计算，数据缺失时路径链断裂、收合不全。
+- **`collapse`：默认不折叠即够用。** 仅当侧栏折叠态需要同步收起菜单才传（透传 ElMenu）。
+- **颜色 attrs（`background-color` / `text-color` / `active-text-color` 等）：默认 ElMenu 主题即够用。** 仅当需贴合页面主题配色才显式传。
+- **完整能力演示**（生产级驱动点 = AppSidebar 内部接线，含折叠 + 路由联动 + 主题配色）：`packages/core/src/components/app-layout/AppSidebar.vue`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `menus` | `RouteMetaResolveRaw[]`（必填） | — | 树形菜单数据；含 children 的节点递归出 ElSubMenu |
+| `menuFlatList` | `RouteMetaResolveRaw[]`（必填） | — | 拍平列表，autoClose 时沿 parentPath 算父链 |
+| `routerMode?` | `boolean` | 未设 | 路由模式：true 时 defaultActive 取 route.path（useRoute）+ ElMenu :router 开启 |
+| `collapse?` | `boolean` | 未设 | 折叠态透传 ElMenu |
+| `autoClose?` | `boolean` | 未设 | 选中一项后关闭其它展开的 ElSubMenu |
+
+其余 attrs（`background-color` / `text-color` / `active-text-color` 等 ElMenu props）整包透传。
+
+### Emits
+
+无显式 defineEmits。模板 `v-bind="attrs"` 先展开、`@select` 后声明——外部 `onSelect` 无法覆盖内部 autoClose 逻辑（推断标注）。
+
+### Slots
+
+无（ElMenu default slot 被 menus v-for 占用）。
+
+### Expose
+
+| 方法 | 参数 | 语义 |
+| --- | --- | --- |
+| `open` | `index: string` | 打开指定菜单（代理 ElMenu 同名方法） |
+| `close` | `index: string` | 关闭指定菜单（代理 ElMenu 同名方法） |
+
+## 反模式 / 注意
+
+- **`/menu/showcase/Page1/2/3` 当用法示范**：它们是菜单渲染出的叶子路由页；MenuTree 的真实消费方是 AppSidebar
+- **autoClose 缺 parentPath 数据**：父链沿 `parentPath` 递归计算，数据缺失时路径链断裂、收合不全
+- **想覆盖内部 @select**：`v-bind="attrs"` 展开在前、`@select` 声明在后，外部 `onSelect` 无法覆盖内部 autoClose 逻辑（推断标注）
+- **依赖 vue-router 上下文**：routerMode 使用 `useRoute`，组件须在安装 vue-router 的上下文中使用
+
+## 关联
+
+- 内部递归：`MenuItemSub`（menu 族）
+- 消费方：`AppSidebar`（app-layout 族）
+- 数据契约：`RouteMetaResolveRaw`（@/types）、`apps/reference/src/router/modules/test.ts`（meta.menu show / icon / sort）

package/src/components/misc/README.md

@@ -0,0 +1,21 @@
+# misc 杂项族
+
+> 单点杂项组件集合：不归属任何语义族（form / table / modal / panel…），各自独立、低耦合。
+> 内部消费范式：`packages/core/src/components/table/TableToolbar.vue`（AutoRefreshGroup 经此服务列表页工具栏）
+
+## 组件清单
+
+| 组件 | 一句话 | 文档 |
+| --- | --- | --- |
+| `AutoRefresh` | 自动刷新开关：开关 + 刷新间隔（秒），定时调用刷新方法 | [README-AutoRefresh](./docs/README-AutoRefresh.md) |
+| `AutoRefreshGroup` | 工具栏组：自动刷新开关 + 手动刷新按钮 + loading 联动 + 布局根控制 | [README-AutoRefreshGroup](./docs/README-AutoRefreshGroup.md) |
+| `SelectModule` | AppLayout 内模块下拉选择器（二级路由菜单 + 首项「全部」） | [README-SelectModule](./docs/README-SelectModule.md) |
+| `TriggerAutoImport`（`@deprecated`） | 仅为触发 unplugin 自动导入的占位组件，永不渲染 | 不写独立文档，见下 |
+
+`types.ts` 导出 `AutoRefreshProps` / `AutoRefreshGroupProps`；族 index.ts 导出 `{ AutoRefresh, AutoRefreshGroup, SelectModule, TriggerAutoImport }`，均进 core 顶层。
+
+## TriggerAutoImport（@deprecated）
+
+- 模板 `<slot v-if="showSlot">` 且 `showSlot` 恒 `false`——**永不渲染**，用途仅为触发 unplugin 自动导入（按需样式）
+- index.ts 导出处 JSDoc：全局样式引入后已无用——`main.ts` `import "element-plus/dist/index.css"` + `ElementPlusResolver importStyle: false` 即可；下个 MAJOR 删除
+- 全仓零消费者；新代码 [MUST NOT] 引入

package/src/components/misc/docs/README-AutoRefresh.md

@@ -0,0 +1,74 @@
+# AutoRefresh（自动刷新开关）
+
+> 独立自动刷新开关：开关 + 刷新间隔（秒），按间隔定时调用刷新方法。
+> 消费范式：core 内无直接使用点，列表/表格场景经 `AutoRefreshGroup` 使用——内部消费者 `packages/core/src/components/table/TableToolbar.vue`（经 AutoRefreshGroup）即范例。
+
+## 定位
+
+- **何时用**：需要「按间隔自动刷新」的独立开关（不跟随工具栏整体布局的场景）
+- **何时不用**：列表/表格工具栏场景用 `AutoRefreshGroup`（自动刷新 + 手动刷新 + loading + 布局根一次拿齐）
+- 内部组合：`ElPopover`(hover) + `ElSwitch` + `ElInputNumber`
+- 刷新失败被 catch，不影响下轮定时
+
+## 快速上手（最小可用）
+
+直接使用场景较少；典型用法是经 `AutoRefreshGroup` 组合进工具栏（见 [README-AutoRefreshGroup](./README-AutoRefreshGroup.md)）。单独使用即开关 + 间隔双向绑定：
+
+```html
+<AutoRefresh v-model="open" v-model:interval="interval" />
+```
+
+```ts
+const open = ref(false);   // 开关（modelValue）
+const interval = ref(5);   // 刷新间隔，秒（v-model:interval）
+```
+
+**要点**：
+
+- `v-model` = 开关（modelValue）；`v-model:interval` = 间隔秒数
+- `refreshFn` 返回 Promise，失败被 catch——**不会**中断下轮定时
+- 防并发：`doRefresh` 未结算前重入共享同一 promise，不并发发请求
+- 激活语义：mounted 只 schedule 不立即刷新；仅 keep-alive 重激活（`triggerType === "activated"`）才立即刷新
+
+## 能力边界 / 按需使用
+
+- **直接使用 vs 走 `AutoRefreshGroup`：独立开关场景才直接用本组件。** 判据——只要「开关 + 刷新间隔」本身、不跟随工具栏整体布局；列表/表格工具栏场景 [MUST] 走 `AutoRefreshGroup`（自动刷新 + 手动刷新 + loading + 布局根一次拿齐，手拼两组件属重复造轮）。
+- **`refreshFn` 必填**：无刷新方法组件无意义——返回 Promise，失败被 catch 吞掉、不影响下轮定时，业务需感知失败请在 `refreshFn` 内自行处理。
+- **`disabled`：默认 `undefined`（开关正常可用）即够用。** 仅当「禁用自动刷新」（置 `true` 即 `openRefresh=false`：清 timer 且不排下轮）才设——注意不是灰化开关。
+- **完整能力演示**（组合进表格工具栏的标准接线）：`packages/core/src/components/table/TableToolbar.vue`（经 AutoRefreshGroup）——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `refreshFn` | `() => Promise<unknown>`（必填） | 无 | 刷新方法；失败被 catch，不影响下轮定时 |
+| `disabled` | `boolean` | `undefined` | `true` 时 `openRefresh=false`：清 timer 且不排下轮 |
+
+**v-model**：`modelValue: boolean`（默认 `false`，开关，`v-model`）；`interval: number`（默认 `5`，秒，`v-model:interval`）
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **`disabled` 不是灰化开关**：置 `true` 即 `openRefresh=false`（清 timer 且不排下轮），而非仅置灰不可点
+- **刷新失败勿在组件外兜**：失败被 catch 吞掉，业务需感知失败请在 `refreshFn` 内自行处理
+- **工具栏场景勿直接拼**：自动刷新 + 手动刷新成套能力（loading/布局根联动）在 `AutoRefreshGroup`，手拼两组件属重复造轮
+
+## 关联
+
+- 组合形态：`AutoRefreshGroup`（misc 族）
+- 内部消费者：`TableToolbar`（table 族，经 AutoRefreshGroup）
+- 激活语义：`useActivated`（core hooks）

package/src/components/misc/docs/README-AutoRefreshGroup.md

@@ -0,0 +1,74 @@
+# AutoRefreshGroup（工具栏自动刷新组）
+
+> 「自动刷新开关 + 手动刷新按钮」组合组：loading 联动、布局根可选，表格工具栏自动刷新能力即此组件。
+> 消费范式：`packages/core/src/components/table/TableToolbar.vue`（内部代表消费）；列表页经 TableMain/ListPage 工具栏生效。
+
+## 定位
+
+- **何时用**：工具栏/操作区需要「自动刷新开关 + 手动刷新按钮」成套能力
+- **何时不用**：只要自动刷新开关（不要手动按钮/布局控制）用 `AutoRefresh`
+- 组合：`AutoRefresh`（开关本体）+ 手动刷新按钮 + loading 联动 + 布局根控制；`refreshFn` 等核心 props 透传 `AutoRefresh`
+
+## 快速上手（最小可用）
+
+必填 `refreshFn` + 两个 v-model——开关 + 间隔 + 手动刷新一次拿齐：
+
+```html
+<AutoRefreshGroup
+  v-model:isAutoRefresh="isAutoRefresh"
+  v-model:interval="refreshInterval"
+  :refreshFn="tableExpose.refresh"
+/>
+```
+
+**要点**：
+
+- `v-model:isAutoRefresh` = 自动刷新开关；`v-model:interval` = 刷新间隔秒数
+- `showAutoRefresh` / `showRefresh` 可分别关掉开关 / 按钮——如只留手动刷新
+- `loading` 传入时：`AutoRefresh` 收 `:disabled` + 图标旋转动画（异步刷新免自管 loading）
+
+## 能力边界 / 按需使用
+
+- **`needRootNode`：默认 `true`（包布局根）即够用（独立使用）。** 嵌入既有布局（如表格工具栏）时 [MUST] 设 `false`——工具栏自身已是布局一部分，否则多包一层布局根（TableToolbar 标准接线即 `false`）。
+- **`showAutoRefresh` / `showRefresh`：默认全开即够用。** 仅当只要其中一半能力才关另一半——如只留手动刷新按钮（`showAutoRefresh={false}`）。
+- **`loading`：默认 `undefined` 即够用（不联动）。** 仅当异步刷新需要免自管 loading 态才传——传入后开关置 `disabled` + 图标旋转，[MUST NOT] 在消费方再手写 loading。
+- **完整能力演示**（表格工具栏标准接线 = TableToolbar 内部消费）：`packages/core/src/components/table/TableToolbar.vue`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `refreshFn` | `() => Promise<unknown>`（必填） | 无 | 透传 AutoRefresh |
+| `showAutoRefresh` | `boolean` | `true` | 是否显示自动刷新开关 |
+| `showRefresh` | `boolean` | `true` | 是否显示手动刷新按钮 |
+| `loading` | `boolean` | `undefined` | 加载中：传入 AutoRefresh `:disabled` + 图标旋转动画 |
+| `needRootNode` | `boolean` | `true` | 是否需要根节点（传 SlotLayoutTemplate `:disabled`，控制是否包布局根） |
+
+**v-model**：`isAutoRefresh: boolean`（`v-model:isAutoRefresh`）；`interval: number`（默认 `5`，秒，`v-model:interval`）
+
+### Emits
+
+无
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **异步刷新勿自管 loading**：`refreshFn` 返回 Promise，`loading` 传入即开关置 `disabled` + 图标旋转——[MUST NOT] 在消费方再手写 loading 态
+- **`needRootNode` 语义**：默认 `true`（传 SlotLayoutTemplate `:disabled`，包布局根）；嵌入既有布局（如工具栏）时 [MUST] 设 `false`，否则多包一层布局根
+- **工具栏场景勿手拼 AutoRefresh + ElButton**：成套能力已在此组件，重复造轮
+
+## 关联
+
+- 子组件：`AutoRefresh`（misc 族，开关本体）
+- 内部消费者：`TableToolbar`（table 族）
+- 布局根：`SlotLayoutTemplate`（slot-layout 族）

package/src/components/misc/docs/README-SelectModule.md

@@ -0,0 +1,72 @@
+# SelectModule（模块选择器）
+
+> AppLayout 内「路由模块」下拉选择器：二级菜单选项 + 首项固定「全部」，v-model 透传 ElSelect。
+> 范式页：`apps/reference/src/pages/home/Home.vue`
+
+## 定位
+
+- **何时用**：AppLayout 布局内需要「按路由模块切换」的下拉选择
+- **前置**：必须挂在 `AppLayout` 内——inject `APP_LAYOUT_BRIDGE_KEY`，缺失即 throw「必须在 AppLayout 内使用」
+- 数据源：`generateRouteMetaRawTree(getRoutes(), { filterFn: menuShow, sortFn: menuSort })`，仅二级（`ElOptionGroup`，注释明示未递归）
+- 首项固定「全部」= `FORM_CONFIG_SELECT_ALL_VALUE`；选项 `value` = 路由 `path`
+- **props/emits 面为空是设计使然**：无 defineProps / defineEmits / defineModel / defineExpose（`defineOptions({ name: "SelectModule", inheritAttrs: true })`），`v-model` 经 `inheritAttrs` 透传 `ElSelect`
+
+## 快速上手（最小可用）
+
+挂载于 AppLayout 内，单个 `v-model` 即够用：
+
+```html
+<SelectModule v-model="module" />
+```
+
+```ts
+import { SelectModule } from "@done-coding/admin-core";
+
+const module = ref<string>();
+```
+
+**要点**：
+
+- `v-model` 绑定选中的路由 `path`；首项「全部」内置，无需特殊处理
+- 挂载点必须在 `AppLayout` 内（bridge 注入契约）
+- `inheritAttrs` 透传——ElSelect 属性（如 `placeholder`）照常传入
+
+## 能力边界 / 按需使用
+
+- **仅二级：选项只到路由模块一级（`ElOptionGroup`，注释明示未递归），多级菜单不承载。** 判据——模块选择器的粒度就是「切换模块」，不是全量多级菜单导航。
+- **必须在 `AppLayout` 内使用：inject `APP_LAYOUT_BRIDGE_KEY`，缺失即 throw。** 挂载点脱离布局即报错，[MUST NOT] 在普通页面直接放。
+- **`v-model` 经 `inheritAttrs` 透传 ElSelect：props 面为空是设计使然（透传代理组件）。** 消费方照常传 ElSelect 属性（`placeholder` 等）即生效；选项 `value` = 路由 `path`——选中值即路由路径，勿期待是模块名 / id。
+- **完整能力演示**：`apps/reference/src/pages/home/Home.vue`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+无（props 面为空；`v-model` 经 `inheritAttrs` 透传 `ElSelect`，消费方照常传 ElSelect 属性）
+
+### Emits
+
+无（`v-model` 变更经 ElSelect 透传）
+
+### Slots
+
+无
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **[MUST NOT] 在 `AppLayout` 外使用**：inject `APP_LAYOUT_BRIDGE_KEY` 缺失即 throw
+- **仅二级**：注释明示未递归，不期望承载全量多级菜单
+- **无 props 面 ≠ 残缺**：透传代理组件设计使然，消费方用法即 `<SelectModule v-model="..." />`
+- 选项 `value` 是路由 `path`——选中值即路由路径，勿期待是模块名 / id
+
+## 关联
+
+- 注入契约：`APP_LAYOUT_BRIDGE_KEY`（core inject，跨包 `Symbol.for`）
+- 数据源：`generateRouteMetaRawTree`（core utils）+ 菜单显隐 / 排序 `menuShow` / `menuSort`
+- 常量：`FORM_CONFIG_SELECT_ALL_VALUE`（「全部」值）
+- 范式页：`apps/reference/src/pages/home/Home.vue`