@done-coding/admin-core 0.21.0 → 0.22.0

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

@@ -0,0 +1,108 @@
+# FormUpload（上传原语）
+
+> 基于 ElUpload 封装的上传字段：**先上传拿 URL，表单只提交 URL**（业界主流 + 本框架 JSON 提交链路结构必然）；`uploadFn` 注入上传接口（不焊后端）；上传中经 `FORM_ITEM_CHANGE_LOADING` 拦截提交；进度走 ElUpload 内置。
+> 对齐表单配置项契约（form 族：`render: FormUpload` + `props` 注入，值 = `string | string[]`）。
+> 范式页：`apps/reference/src/pages/form/upload/showcase/`
+
+## 定位
+
+- **何时用**：任意「表单内文件上传」场景——头像/附件/素材，值 = 已上传文件的 URL
+- **何时不用**：非表单命令式上传（无字段值语义）→ 直接用 ElUpload；需要倍速/字幕等播放能力 → 播放器组件
+- **模式裁定（只做「先上传再提交 url」）**：业界两模式——「文件 + 字段一次 multipart 提交」属整体表单体系（服务端 multipart 接口 + 表单引擎非 JSON），且组件库先例（ElUpload / antd Upload）均为 URL 入值；本框架 FormMain 提交链路 = validate → stringify → JSON，**先传拿 URL 是结构必然**（URL 是字符串，天然融入现有 JSON 契约）。**随表单直传不做**——需表单引擎 multipart 化，与配置化契约分叉、非主流
+- 职责分工：**数据职责注入式**（`uploadFn` 注入上传接口，不焊后端）/ **呈现职责声明式**（`showProgress` 开关 + 内置进度条）
+- 关键机制：`modelValue` = URL（单文件）/ URL 数组（多文件）——与 `uploadFn` 返回一致，表单 stringify 即提交 URL
+
+## 快速上手（最小可用）
+
+```ts
+// 表单配置项（render 契约：modelValue v-model + props 注入）
+{
+  key: "avatar",
+  label: "头像",
+  render: FormUpload,
+  props: {
+    uploadFn: (file) => uploadFile(file),   // 上传接口：入参 File，返回 Promise<URL>
+    loadingKey: "avatar",                    // 表单字段 key——上传期间拦提交（见「拦截机制」）
+  },
+}
+```
+
+**要点**：
+
+- `uploadFn` 必填：入参 `File`、返回 `Promise<string>`（文件 URL）——**只约定数据契约，不焊任何后端**
+- `loadingKey` = 本表单项的 `key`：上传期间提交被拦截（`FORM_ITEM_CHANGE_LOADING` 链路），上传完成自动放行
+- 值类型随 `multiple`：`false`（默认）= `string`；`true` = `string[]`
+- 进度条默认显示（ElUpload 内置），`showProgress=false` 关闭
+
+## 拦截机制（上传中禁提交）
+
+- **链路（FormMain validate 闸）**：FormUpload 上传在途数 0→1 时调 `changeLoading({ key: loadingKey, message: "上传中" })` → FormMain `loadingList` 记录 → **`validate()` 开头直接 reject**（错误文案 = `label+message`「xx上传中」）→ **提交被拦截**，错误经 reject 由提交方（FormSubmitBtn `@fail` / ElMessage 等）展示；在途数 →0 时 `changeLoading({ key: loadingKey })`（message 空）移除，恢复可提交
+- **[MUST NOT] 走 el-form 规则注入拦提交**：规则增删会触发 EP el-form-item `doValidateField` 的 `resetField`（validateState=error 且无 error 消息 → 字段重置为初始值）——上传完成移除规则时会把刚写入的 URL 重置清空（历史坑两次踩，FormMain 已收敛为 validate 闸，字段级错误提示不再由规则注入产生）
+- `loadingKey` 未传（裸用/非 FormMain 环境）→ `inject(FORM_ITEM_CHANGE_LOADING)` 未命中 no-op，**上传照常不拦**（组件不崩）
+- 判定在途 = **内部 `uploadingCount`**（起止对称计数，覆盖并发多文件）——ElUpload `v-model:file-list` 不回传 uploading 状态，不依赖它
+
+## 能力边界 / 按需使用
+
+- **默认即够用：单文件 + URL 值 + 进度条 + 上传中拦提交**——绝大多数场景只配 `uploadFn` + `loadingKey`。进度条由 `uploadFn` 可选第二参 `onProgress(percent)` 驱动（真实后端 XHR 转发 `upload.onprogress`；不调则进度条静态）。
+- `multiple` + `limit`：多文件上传（值变 `string[]`）+ 数量上限（默认按形态：单文件 1 / 多文件不限）；**满上限触发区隐藏**（`list.length < maxCount` 才显示——业界主流 maxCount 满即无上传入口，单文件上传后触发区消失，替换 = 删旧再传；自定义 default slot 同样隐藏）。
+- **布局 = 列表在前、触发在后**（text/picture 模式 flex order 重排）：每上传一个文件，文件项都在拖拽/点击二合一触发模块前面；picture-card 模式触发卡天然在网格末尾。
+- `accept` / `drag` / `disabled`：文件类型过滤 / 拖拽上传 / 禁用，透传 ElUpload。
+- `showProgress`：默认开（ElUpload 内置进度条：`on-progress` → `event.percent` → 自动更新显示）；**无需自造进度方法**——接口支持 XHR 上传进度即自动可用；仅自定义进度呈现时才需自行从 `on-progress` 拿 `event.percent`（本组件不提供进度插槽，YAGNI）。
+- **完整能力演示**：`apps/reference/src/pages/form/upload/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| string[] \| undefined`（必传） | — | v-model：已上传文件 URL；`multiple` 时为 URL 数组 |
+| `uploadFn` | `(file: File) => Promise<string>`（必传） | — | 上传接口注入：入参 File、返回 URL（数据职责，不焊后端） |
+| `loadingKey` | `string` | — | 表单字段 key——上传期间经 `FORM_ITEM_CHANGE_LOADING` 拦提交（FormMain 配置化场景传；裸用可不传） |
+| `maxCount` | `number` | `1` | **文件数量上限 + 多文件判定一体**（`>1` = 多文件追加兼上限；`1` = 单文件替换语义——业界主流 maxCount 即数量限制）；v-model 恒 `string[]`，配置表单提交转换经 stringify/parse |
+| `maxSize` | `number`（MB） | — | **单文件大小上限**（EP 无原生 size 限制，上传前校验 reject + ElMessage 提示；超限值不入） |
+| `accept` | `string` | — | 文件类型过滤（透传 ElUpload） |
+| `drag` | `boolean` | `false` | 拖拽上传（透传 ElUpload） |
+| `disabled` | `boolean` | `false` | 禁用（透传 ElUpload） |
+| `showProgress` | `boolean` | `true` | 上传进度条（ElUpload 内置 `show-progress`） |
+| `placeholder` | `string` | — | 空态提示文字（render 契约字段） |
+
+> **ElUpload UI 类属性全量透传**：`$attrs` 直达 ElUpload——`autoUpload` / `listType`（picture-card 等）/ `on-success` / `on-error` / `on-exceed` 等均可用。**网络类属性（`action` / `headers` / `data` / `with-credentials` / `http-request`）不适用**——上传行为已由 `uploadFn` 内部接管（`http-request` 内部固定走 uploadFn），外部传了被忽略。
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:modelValue` | `string \| string[]` | v-model 同步 |
+| `uploadSuccess` | `{ file: UploadFile, url: string }` | 单文件上传成功（URL 已入值） |
+| `uploadError` | `{ file: UploadFile, error: Error }` | 单文件上传失败（值不变，错误可展示） |
+| `triggerChangeLink` | `(value, attachInfo?)` | 联动透传（配置项 beLink 场景） |
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| 默认 | ElUpload 触发区 scope | 自定义触发区（透传 ElUpload）；**缺省 = 内置触发区**（上传图标 + 「点击上传」/drag 时「点击或拖拽上传」——无内容时 el-upload 触发区坍缩 0 尺寸不可点，兜底保证点击上传入口恒在） |
+| `#tip` | 无 | 提示区（透传 ElUpload） |
+| `#file` | `{ file, index, remove }` | 文件列表自定义渲染（透传 ElUpload 实际 slot scope；**`remove` = 删除当前项**，内部同步 v-model） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **值 = URL 不是 File**：`modelValue` 语义是「已上传文件的 URL」——外部塞 File 对象进值是错误用法（表单 stringify 提交的是 URL）；上传动作经 `uploadFn` 发生
+- **`loadingKey` 不传则上传中不拦提交**：裸用可接受（无 FormMain 环境）；FormMain 配置化场景忘传 = 上传中能提交（半成品 URL 进库）——配置时 [MUST] 传
+- **进度不自造**：ElUpload 内置进度条（on-progress → percent → 自动显示）——「把 onprogress 数据传给 getProgress 方法」是自造轮子；只有自定义进度呈现才需要自己拿 `event.percent`
+- **网络类属性无效**：`action` / `headers` / `http-request` 等传了被忽略（上传走 uploadFn）——别把后端上传配置塞 ElUpload 网络 props
+- **外部清空联动**：外部把值清空（`undefined` / 空数组）→ 文件列表同步清空——受控语义，别惊讶
+- **多文件去重**：同 URL 重复上传不做客户端去重（服务端职责），`limit` 只限数量
+
+## 关联
+
+- form 族：`FormMain`（宿主：validate 拦截闸 / stringify 序列化）、`FormSubmitPanel`（FormMain 容器 + 取消/重置/提交操作区，直接消费——上传中拦提交经内置提交管线照样生效，见范式页 ⓔ）、`FormItem`（render 契约宿主：modelValue + props 注入）
+- 拦截机制：`FORM_ITEM_CHANGE_LOADING`（FormMain 256 行 provide；loadingList → 恒失败规则 → validate reject）
+- 底层：`ElUpload`（element-plus；UI/进度/列表内置能力）
+- 范式页：`apps/reference/src/pages/form/upload/showcase/`

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

@@ -0,0 +1,80 @@
+# FormUploadAudio（音频上传组件）
+
+> 基于 `FormUpload` 的**音频专属薄封装**：类型限制（`accept="audio/*"`）+ 列表项体验优化（内联播放条即时试听）。
+> 与 `FormUploadImage` / `FormUploadVideo` 同族（媒体上传三件套）。
+> 范式页：`apps/reference/src/pages/form/guide/`（FormMain 配置化）、`apps/reference/src/pages/form/submit-panel/showcase/`（FormSubmitPanel 配置化）
+
+## 定位
+
+- **何时用**：任意「上传音频」场景——语音、配乐、素材；与 `FormUpload` 同契约（先上传拿 URL），只是类型限制 + 列表项按音频形态优化
+- **何时不用**：上传任意文件 → `FormUpload` 本体；图片 / 视频 → 同族 `FormUploadImage` / `FormUploadVideo`
+- 基座关系：**薄封装不改契约**——全部 props / emits / v-model 透传 `FormUpload`；仅两处覆写：ⓐ `accept` 默认 `"audio/*"`；ⓑ 默认 `#file` 列表项 = 行式（文件名/大小/进度 + **内联 `<audio controls>` 播放条** + 删除）
+- **音频不建弹窗（业界结论）**：音频语义是「试听」不是「观看」——业界主流（blueimp / Vue File Agent / 微信 / 播客产品）均为**内联播放条**，无「音频 lightbox」形态；故不新增 `AudioPreviewTrigger` / `ModalAudioPreview`，播放条直接内联列表项（上传中 blob URL 即时可试听）
+
+## 快速上手（最小可用）
+
+```vue
+<FormUploadAudio
+  v-model="audio"
+  :upload-fn="uploadFn"
+  loading-key="audio"
+  placeholder="点击上传音频（单文件 · 限音频）"
+/>
+```
+
+**要点**：
+
+- `uploadFn` 必填（同 `FormUpload`）；`loadingKey` = 本表单项 `key`（上传期间拦提交）
+- 单文件默认（`maxCount` 1 替换语义）；`maxCount` > 1 = 多文件追加（列表行）
+- 必传/非必传 = 表单配置项 `required`，与组件无关
+
+## 能力边界 / 按需使用
+
+- **默认即够用：行式列表 + 内联播放条**——绝大多数音频上传只传 `uploadFn` / `loadingKey`。
+- `maxCount` / `maxSize` / `drag`：多文件+数量上限 / 大小上限 / 拖拽（透传 FormUpload）。
+- `#file` 插槽（scope 含 `remove`）：完全自定义列表项（建议保留播放与删除）。
+- **完整能力演示**：范式页——单文件必传 / 多文件非必传组合见 FormMain 与 FormSubmitPanel reference。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（继承 FormUpload 全部 + 覆写默认值）
+
+| name | 默认 | 语义 |
+| --- | --- | --- |
+| `uploadFn` | （必填） | 上传接口注入 `(file: File) => Promise<string>`（透传 FormUpload） |
+| `loadingKey` | — | 本表单项 key，上传期间拦提交（透传 FormUpload） |
+| `accept` | `"audio/*"` | 文件类型过滤（**覆写默认**，可再覆盖） |
+| 其余 | 同 FormUpload | `maxCount`（默认 1，>1 多文件）/ `maxSize`（MB 大小上限）/ `drag` / `disabled` / `showProgress` / `placeholder` 等全透传 |
+
+> **ElUpload 属性经 `$attrs` 全量透传**，网络类属性被 FormUpload 忽略（上传行为由 uploadFn 接管）。
+
+### Emits
+
+同 `FormUpload`（`update:modelValue` / `uploadSuccess` / `uploadError` / `triggerChangeLink`）。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 上传触发区（默认「点击/拖拽上传」观感） |
+| `#file` | `{ file, index, remove }` | 列表项自定义；**默认 = 文件名/大小/进度 + 内联 `<audio controls>` 播放条 + 删除**；`remove` = 删除当前项 |
+| `#tip` | 无 | 列表下方提示（透传 FormUpload） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **[MUST NOT] 为音频造弹窗**：业界无「音频 lightbox」形态——试听语义用内联播放条（成本最低、交互最自然），弹窗沉浸是视频专利
+- **`accept` 只是过滤不是校验**：服务端仍须校验（同 FormUpload）
+- **`remove` 走基座值同步**：自定义 `#file` 删除须用 scope 的 `remove`，[MUST NOT] 直接改 fileList
+- **播放条直用原生 `<audio controls>`**：薄壳不内置波形/播放器增强（需要时消费方自拼，见反模式）
+
+## 关联
+
+- 基座：`FormUpload`（上传原语：uploadFn 注入 / validate 拦提交 / #file slot scope）
+- 同族：`FormUploadImage`（方形缩略图卡片 + 点击直达放大）、`FormUploadVideo`（封面占位 + 播放图标 + 弹窗决策链）
+- 拦截机制：`FORM_ITEM_CHANGE_LOADING`（FormMain validate 闸）
+- 范式页：`apps/reference/src/pages/form/guide/`、`apps/reference/src/pages/form/submit-panel/showcase/`

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

@@ -0,0 +1,83 @@
+# FormUploadImage（图片上传组件）
+
+> 基于 `FormUpload` 的**图片专属薄封装**：类型限制（`accept="image/*"`）+ 列表项体验优化（方形缩略图卡片 + 点击放大预览 + 悬停删除）。
+> 与 `FormUploadVideo` / `FormUploadAudio` 同族（媒体上传三件套）。
+> 范式页：`apps/reference/src/pages/form/guide/`（FormMain 配置化）、`apps/reference/src/pages/form/submit-panel/showcase/`（FormSubmitPanel 配置化）
+
+## 定位
+
+- **何时用**：任意「上传图片」场景——头像、封面、图库；与 `FormUpload` 同契约（先上传拿 URL，表单只提交 URL），只是对上传类型做了进一步限制 + 列表项按图片形态优化
+- **何时不用**：上传任意文件类型 → `FormUpload` 本体；上传视频 / 音频 → 同族 `FormUploadVideo` / `FormUploadAudio`
+- 基座关系：**薄封装不改契约**——全部 props / emits / v-model 透传 `FormUpload`；仅两处覆写：ⓐ `accept` 默认 `"image/*"`；ⓑ 默认 `#file` 列表项 = 方形缩略图卡片（点击经 `ImagePreviewTrigger` 直达 el-image-viewer 放大；悬停删除角标）
+- 列表形态：默认 `list-type="picture-card"`（EP 方形卡片网格），消费方可经 attrs 覆写
+- 预览链路：列表项 = `ImagePreviewTrigger`（`src=file.url`）——**点击直达 ElImage 原生预览**（零弹窗零决策链，与预览族图片约定一致）；上传中 blob URL 同样可预览（本地即时核对）
+
+## 快速上手（最小可用）
+
+```vue
+<FormUploadImage
+  v-model="cover"
+  :upload-fn="uploadFn"
+  loading-key="cover"
+  placeholder="点击上传封面（单文件 · 限图片）"
+/>
+```
+
+**要点**：
+
+- `uploadFn` 必填（数据职责注入，同 `FormUpload`）；`loadingKey` = 本表单项 `key`（上传期间拦提交）
+- 单文件默认（`maxCount` 1 替换语义）；`maxCount` > 1 = 多文件追加（卡片网格）
+- 必传/非必传 = 表单配置项 `required`（FormMain 校验），与组件无关
+
+## 能力边界 / 按需使用
+
+- **默认即够用：方形卡片 + 点击放大 + 悬停删除**——绝大多数图片上传只传 `uploadFn` / `loadingKey`。
+- `maxCount` / `maxSize` / `drag`：多文件+数量上限 / 大小上限 / 拖拽（透传 FormUpload）。
+- `#file` 插槽（scope 含 `remove`）：完全自定义卡片内容（仍建议保留预览与删除能力）。
+- **完整能力演示**：范式页——单文件必传 / 多文件非必传组合见 FormMain 与 FormSubmitPanel reference。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（继承 FormUpload 全部 + 覆写默认值）
+
+| name | 默认 | 语义 |
+| --- | --- | --- |
+| `uploadFn` | （必填） | 上传接口注入 `(file: File) => Promise<string>`（透传 FormUpload） |
+| `loadingKey` | — | 本表单项 key，上传期间拦提交（透传 FormUpload） |
+| `accept` | `"image/*"` | 文件类型过滤（**覆写默认**，可再覆盖） |
+| `listType` | `"picture-card"` | 列表形态（**覆写默认**为方形卡片网格，透传 ElUpload） |
+| 其余 | 同 FormUpload | `maxCount`（默认 1，>1 多文件）/ `maxSize`（MB 大小上限）/ `drag` / `disabled` / `showProgress` / `placeholder` 等全透传 |
+
+> **ElUpload 属性经 `$attrs` 全量透传**（`autoUpload` / `on-exceed` 等），网络类属性（action/headers/data/http-request）被 FormUpload 忽略（上传行为由 uploadFn 接管）。
+
+### Emits
+
+同 `FormUpload`（`update:modelValue` / `uploadSuccess` / `uploadError` / `triggerChangeLink`）。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 上传触发区（默认「点击/拖拽上传」观感） |
+| `#file` | `{ file, index, remove }` | 列表项自定义；**默认 = 方形缩略图卡片 + 点击放大 + 悬停删除**；`remove` = 删除当前项（基座 slot scope 拓展） |
+| `#tip` | 无 | 列表下方提示（透传 FormUpload） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **别在 `#file` 里塞自绘弹窗**：预览终点 = el-image-viewer（`ImagePreviewTrigger` 点击直达），[MUST NOT] 再包弹窗（两层嵌套已废弃）
+- **`accept` 只是过滤不是校验**：服务端仍须按类型/大小校验（同 FormUpload）
+- **`remove` 走基座值同步**：自定义 `#file` 删除须用 scope 的 `remove`（内部 handleRemove 同步 v-model），[MUST NOT] 直接改 fileList
+- **进度条**：上传中卡片下方有 EP 内置进度（`showProgress` 开关）
+
+## 关联
+
+- 基座：`FormUpload`（上传原语：uploadFn 注入 / validate 拦提交 / #file slot scope）
+- 同族：`FormUploadVideo`（视频，封面占位 + 播放图标 + VideoPreviewTrigger 决策链）、`FormUploadAudio`（音频，内联播放条）
+- 预览：`ImagePreviewTrigger`（点击直达 ElImage 原生放大）
+- 拦截机制：`FORM_ITEM_CHANGE_LOADING`（FormMain validate 闸）
+- 范式页：`apps/reference/src/pages/form/guide/`、`apps/reference/src/pages/form/submit-panel/showcase/`

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

@@ -0,0 +1,82 @@
+# FormUploadVideo（视频上传组件）
+
+> 基于 `FormUpload` 的**视频专属薄封装**：类型限制（`accept="video/*"`）+ **交互对齐图片上传**（picture-card 卡片网格——唯一区别 = 卡片内容为视频预览）。
+> 与 `FormUploadImage` / `FormUploadAudio` 同族（媒体上传三件套）。
+> 范式页：`apps/reference/src/pages/form/guide/`（FormMain 配置化）、`apps/reference/src/pages/form/submit-panel/showcase/`（FormSubmitPanel 配置化）
+
+## 定位
+
+- **何时用**：任意「上传视频」场景——素材库、课程视频；与 `FormUpload` 同契约（先上传拿 URL），只是类型限制 + 列表项按视频形态优化
+- **何时不用**：上传任意文件 → `FormUpload` 本体；图片 / 音频 → 同族 `FormUploadImage` / `FormUploadAudio`
+- 基座关系：**薄封装不改契约**——全部 props / emits / v-model 透传 `FormUpload`；仅三处覆写：ⓐ `accept` 默认 `"video/*"`；ⓑ `listType` 默认 `"picture-card"`（**卡片网格，交互对齐图片上传**）；ⓒ 默认 `#file` 列表项 = 媒体卡片（`VideoPreviewTrigger` 铺满 + 上传中遮罩 + 悬停删除）
+- **卡片内容 = 视频预览**：封面图（有 coverUrl）/ 深色占位 + 播放图标（无封面——业界主流：上传视频大多无封面，YouTube/剪映素材库同此形态）；点击走弹窗决策链（全局遥控 `APP_GLOBAL_VIDEO_PREVIEW_KEY` 命中 → 全局唤起；否则自带弹窗兜底），上传中 blob URL 同样可播放（本地即时核对）
+
+## 快速上手（最小可用）
+
+```vue
+<FormUploadVideo
+  v-model="video"
+  :upload-fn="uploadFn"
+  loading-key="video"
+  placeholder="点击上传视频（单文件 · 限视频）"
+/>
+```
+
+**要点**：
+
+- `uploadFn` 必填（同 `FormUpload`）；`loadingKey` = 本表单项 `key`（上传期间拦提交）
+- 单文件默认（`maxCount` 1 替换语义）；`maxCount` > 1 = 多文件追加（列表行）
+- 必传/非必传 = 表单配置项 `required`，与组件无关
+
+## 能力边界 / 按需使用
+
+- **默认即够用：卡片网格 + 播放图标 + 点击播放**——绝大多数视频上传只传 `uploadFn` / `loadingKey`。
+- `maxCount` / `maxSize` / `drag`：多文件+数量上限 / 大小上限 / 拖拽（透传 FormUpload）；**满上限（`maxCount` 达）触发区隐藏**（单文件上传后消失，替换 = 删旧再传）。
+- `#file` 插槽（scope 含 `remove`）：完全自定义列表项（建议保留预览与删除）。
+- **完整能力演示**：范式页——单文件必传 / 多文件非必传组合见 FormMain 与 FormSubmitPanel reference。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（继承 FormUpload 全部 + 覆写默认值）
+
+| name | 默认 | 语义 |
+| --- | --- | --- |
+| `uploadFn` | （必填） | 上传接口注入 `(file: File) => Promise<string>`（透传 FormUpload） |
+| `loadingKey` | — | 本表单项 key，上传期间拦提交（透传 FormUpload） |
+| `accept` | `"video/*"` | 文件类型过滤（**覆写默认**，可再覆盖） |
+| `listType` | `"picture-card"` | 列表形态（**覆写默认**为卡片网格，交互对齐图片上传；text 等可覆写） |
+| 其余 | 同 FormUpload | `maxCount`（默认 1，>1 多文件）/ `maxSize`（MB 大小上限）/ `drag` / `disabled` / `showProgress` / `placeholder` 等全透传 |
+
+> **ElUpload 属性经 `$attrs` 全量透传**，网络类属性被 FormUpload 忽略（上传行为由 uploadFn 接管）。
+
+### Emits
+
+同 `FormUpload`（`update:modelValue` / `uploadSuccess` / `uploadError` / `triggerChangeLink`）。
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#default` | 无 | 上传触发区（默认「点击/拖拽上传」观感） |
+| `#file` | `{ file, index, remove }` | 列表项自定义；**默认 = 媒体卡片（`VideoPreviewTrigger` 铺满：封面/占位 + 播放图标，点击播放）+ 上传中遮罩 + 悬停删除**；`remove` = 删除当前项 |
+| `#tip` | 无 | 列表下方提示（透传 FormUpload） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **列表项不做 `#t=0.01` 抠首帧**：无封面就深色占位 + 播放图标（业界主流，播放按钮即语义；首帧由服务端生成封面是上传后增强，非前端必须）——首帧兜底只在弹窗端 `ModalVideoPreview`（播放器场景才需要「不黑屏」）
+- **`accept` 只是过滤不是校验**：服务端仍须校验（同 FormUpload）
+- **`remove` 走基座值同步**：自定义 `#file` 删除须用 scope 的 `remove`，[MUST NOT] 直接改 fileList
+- **弹窗端视频属性（autoplay/muted 等）在 `ModalVideoPreview` 上配**，[MUST NOT] 经本组件透传
+
+## 关联
+
+- 基座：`FormUpload`（上传原语：uploadFn 注入 / validate 拦提交 / #file slot scope）
+- 同族：`FormUploadImage`（方形缩略图卡片 + 点击直达放大）、`FormUploadAudio`（内联播放条）
+- 播放端：`VideoPreviewTrigger` → `ModalVideoPreview`（黑底 lightbox，决策链：全局遥控优先 / 自带弹窗兜底）
+- 拦截机制：`FORM_ITEM_CHANGE_LOADING`（FormMain validate 闸）
+- 范式页：`apps/reference/src/pages/form/guide/`、`apps/reference/src/pages/form/submit-panel/showcase/`

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

@@ -9,8 +9,12 @@
 ## 关键类型
 
 - `ListLayoutProps` / `ListLayoutInstance`（= FormSearchInstance + TableMainInstance + update）/ `ListLayoutInnerInjectInfo`（列插槽注入：triggerSearch / triggerReset / update）
-- 内部不导出：`use-sticky`
+- 内部不导出：`use-sticky`、`use-active-filter`（生效条件条投影逻辑：query 投影 + value→label + 表单值同步清除）
+
+## 新能力（2026-08-04）
+
+- **生效筛选条件条**：`formActiveFilter` prop（默认关）开启后，表单卡片顶部一行显示已生效查询条件（query 投影，≠ 表单输入值；枚举字段经 config props.options 显示 label，取不到原值兜底）；单项 × = 移除 query 字段 + 同步清表单值 + 重查；`allowClear`（默认关）额外显示「清除全部」。UI 组件 = form 族 `FormActiveFilter`（纯 UI，数据/事件上抛）
 
 ## 范式页（apps/reference）
 
-- `/list-layout/guide`（最佳实践：搜索 + 弹窗 CRUD + 分离侧栏）/ `/list-layout/sticky`（三件套粘性）/ `/list-layout/module-demo`（keepAlive 模块组合）
+- `/list-layout/guide`（最佳实践：搜索 + 弹窗 CRUD + 分离侧栏）/ `/list-layout/sticky`（三件套粘性）/ `/list-layout/module-demo`（keepAlive 模块组合）/ `/list-layout/active-filter`（生效筛选条件条）

package/src/components/list-layout/docs/README-ListLayout.md

@@ -95,6 +95,7 @@ const { listPageConfig } = useSpaceConfig({
 | `separateSearchConfig` | `Pick<SlotLayoutFlowAsideProps, "type"\|"gap"\|"asideWidth">` | 未设 | 分离侧栏布局 |
 | `searchSticky` / `toolbarSticky` / `pagerSticky` | `boolean` | 均 `false` | 三件套粘性（分离态下 searchSticky 被无视） |
 | `headerObserveResize` / `operationObserveResize` | `boolean` | 均 `false` | header/操作槽量高 ResizeObserver |
+| `initialSearch` | `boolean` | `true` | 挂载后是否立即触发初始化查询（默认查）；关闭后表格空态显示「欢迎触发查询」、KeepAlive 激活不自动刷新（TableMain 经「已发生过查询」自判，见 table docs） |
 
 **v-model**：`isAutoRefresh`、`refreshInterval`、`customView`（配合 `#custom-view-item` 卡片渲染）
 

package/src/components/modal/README.md

@@ -7,15 +7,20 @@
 - [ModalConfirm](./docs/README-ModalConfirm.md) — 确认弹窗/抽屉原语（onXxx props 契约）
 - [ModalForm](./docs/README-ModalForm.md) — 弹窗 + 表单 + 校验提交
 - [ModalDetail](./docs/README-ModalDetail.md) — CRUD 预设薄壳（add / edit / read）
+- [ModalImagePreview](./docs/README-ModalImagePreview.md) — 图片预览弹窗·命令式入口（ElImageViewer 薄适配 + 弹窗配置化契约；点击路径不走它——ElImage 原生直达）
+- [ModalVideoPreview](./docs/README-ModalVideoPreview.md) — 视频预览弹窗·lightbox 形态（ElDialog 直配黑底沉浸，业界 Video Lightbox；url/coverUrl，封面空走 `#t=0.01` 首帧）
+- [ImagePreviewTrigger](./docs/README-ImagePreviewTrigger.md) — 图片触发（ElImage 落地 + 懒加载/占位兜底 + previewSrc 原图，**点击直达 ElImage 原生预览**——零弹窗）
+- [VideoPreviewTrigger](./docs/README-VideoPreviewTrigger.md) — 视频触发（封面吃懒加载 / 无封面占位，**两形态统一播放图标**；视频无 el 原生预览 → 弹窗决策链保留）
 - [ModalShelf](./docs/README-ModalShelf.md) — 弹窗架子（level: app/page/custom + 层级断言）
 - [ModalPorter](./docs/README-ModalPorter.md) — 弹窗搬运（modalList 注册表 + evoke + 卸载自动清理）
 
 ## 关键类型与机制
 
-- 类型：`ModalLevel` / `ModalSameKeyStrategy` / `ModalShelfMap` / `ModalInjectedProps` / `EvokeHandle` / `RegisterEntry` / `ShelfController`（经 `./types` + `./modal-shelf-types` 导出）
+- 类型：`ModalLevel` / `ModalSameKeyStrategy` / `ModalShelfMap` / `ModalInjectedProps` / `EvokeHandle` / `RegisterEntry` / `ShelfController` / `GlobalModalRemote`（含 **`modalKey: string[]`** 已注册 key 清单）/ `GlobalModalControl`（经 `./types` + `./modal-shelf-types` 导出）
+- 全局遥控：`GLOBAL_MODAL_REMOTE_KEY`（core 导出注入 key，触发组件等消费端 inject）+ 预置 key 常量 `APP_GLOBAL_IMAGE_PREVIEW_KEY` / `APP_GLOBAL_VIDEO_PREVIEW_KEY`（AppLayout `enableGlobal*Preview` 开关开启即注册全局预览弹窗）
 - ⚠️ deprecated 兼容别名：`ConfirmModal` / `FormModal` / `DetailModal`（指向新名，后续大版本移除）——**新代码 [MUST NOT] 用旧名**，仅存量迁移期过渡（readme API 表与范式页均用新名）
 - 内置挂载：AppLayout 内置 `level="app"`、AppPage 内置 `level="page"`（业务 [MUST NOT] 自声明）
 
 ## 范式页（apps/reference）
 
-- `/modal/guide`（对接内置 page 架子）/ `/modal/porter/showcase`（三层自定义架子 + 5 场景）/ `/modal/confirm/showcase`（modal/drawer 双形态）/ `/modal/form-modal/showcase`（独立原语用法）
+- `/modal/guide`（对接内置 page 架子）/ `/modal/porter/showcase`（三层自定义架子 + 5 场景）/ `/modal/confirm/showcase`（modal/drawer 双形态）/ `/modal/form-modal/showcase`（独立原语用法）/ `/modal/preview/showcase`（预览族：图片/视频弹窗 + 触发组件 + 全局遥控交叉验证）

package/src/components/modal/docs/README-ImagePreviewTrigger.md

@@ -0,0 +1,78 @@
+# ImagePreviewTrigger（图片预览触发组件）
+
+> 图片触发原语：`ElImage` 落地（img 原生属性对齐）+ 懒加载 + 加载中/失败占位兜底；**点击直接走 ElImage 自带预览（el-image-viewer 放大）**——点图即放大，一层到位，不经弹窗。
+> 与 `VideoPreviewTrigger` 对等成对（视频触发端仍需弹窗；图片预览终点是 el 原生查看器）。
+> 范式页：`apps/reference/src/pages/modal/preview/showcase/`
+
+## 定位
+
+- **何时用**：任意「缩略图可点开看大图」场景——上传文件列表、附件卡片、图片墙
+- **何时不用**：仅展示不点击 → 直接用 `ElImage`；命令式开图（按钮/编排，不经过点击）→ `ModalImagePreview` + 全局遥控器 evoke
+- 关键机制：落地 **`ElImage`**（非裸 `<img>`）——原生 img 属性照常 `$attrs` 透传对齐，同时白拿组件库三件套：**`lazy`（默认开）** + **`#placeholder`（加载中占位）** + **`#error`（加载失败兜底图）** + **`preview-src-list`（点击放大）**
+- **点击直达（零弹窗）**：`preview` 开启时内部给 ElImage 绑定 `preview-src-list`（= `[previewSrc ?? src]`）+ `preview-teleported`——点击图片即打开 **el-image-viewer 全屏放大**（缩放/旋转/切换/ESC/遮罩关闭全原生）——**一层到位**
+- **命令式与点击两入口各司其职**：点击 → ElImage 原生预览（本组件）；命令式 → `ModalImagePreview`（ElImageViewer 薄适配，全局遥控器 evoke）——触发组件 [MUST NOT] 再走弹窗（两层预览嵌套已废弃）
+
+## 快速上手（最小可用）
+
+```vue
+<ImagePreviewTrigger src="https://example.com/thumb.png" />
+```
+
+**要点**：
+
+- `src` 必传（缩略图路径）；零配置即带原生懒加载 + 占位兜底 + **点击放大**
+- 大图与原图分离：`previewSrc` 传原图（点击放大打开的大图），**缺省降级为 `src`**（缩略图即原图时零配置）
+- 点击后：el-image-viewer 全屏放大（ep 原生）——无环境依赖、无决策链、无弹窗
+
+## 能力边界 / 按需使用
+
+- **默认即够用：缩略图 + 懒加载 + 点击放大**——绝大多数场景只传 `src`。
+- `previewSrc`：仅当缩略图/原图分离（如压缩图列表）时传；缺省 = `src`。
+- `#placeholder` / `#error` 插槽：仅当需要自定义加载中/失败兜底图（小图 / base64）时传；缺省 EP 默认观感（灰底加载中 + 失败图标）。
+- `lazy={false}`：仅当图片必须立即加载（首屏无滚动场景）时关。
+- `preview={false}`：关闭点击放大（纯展示缩略图）——仍保留懒加载 + 占位兜底。
+- **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `src` | `string`（必传） | — | 缩略图路径（ElImage.src） |
+| `previewSrc` | `string` | — | 原图路径（点击放大打开的大图）；**缺省降级为 `src`** |
+| `lazy` | `boolean` | `true` | 图片懒加载（ElImage.lazy，原生 loading 优先） |
+| `preview` | `boolean` | `true` | 是否可点击放大（内部绑定 `preview-src-list`；false = 纯展示缩略图） |
+
+> **ElImage / img 原生属性全量透传**：`$attrs` 直达自身 ElImage——`alt` / `fit` / `loading` / `draggable` / `scroll-container` 等原生属性与 EP 图片属性均可用。
+> ⚠ **`width` / `height` 无效**：EP 2.13 的 ElImage 未声明 width/height props，透传会落根 div 的 HTML attribute（对 div 无渲染效果）。尺寸控制请用外层 CSS / `style`（配合 `fit="cover"` 居中裁切）。
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `#placeholder` | 无 | 加载中占位（透传 ElImage；缺省 EP 灰底观感） |
+| `#error` | 无 | 加载失败兜底图（透传 ElImage；缺省 EP 失败图标）——**插槽非属性**，传兜底图走插槽内放 `<img>` |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **[MUST NOT] 点击走弹窗**：图片预览终点 = el-image-viewer（ElImage 原生）——弹窗 → 弹窗内再点放大 = 两层嵌套（脱裤子放屁，已废弃）；命令式开图走 `ModalImagePreview`，与点击路径分离
+- **`previewSrc` 才是预览路径**：`src` 是展示路径——缩略图/原图分离时别把大图塞 `src`（懒加载白拉全尺寸图）
+- **`#error` 是插槽不是属性**：传字符串路径是 EP 常见误区（加载失败显示空白）——兜底图放插槽内 `<img :src>`（或 base64）
+- **`preview=false` 只关放大**：仍渲染缩略图 + 懒加载 + 占位兜底——「图片展示」能力不随「预览」关掉
+
+## 关联
+
+- 命令式弹窗端：`ModalImagePreview`（ElImageViewer 薄适配 + 弹窗配置化契约；全局遥控器 `evoke(APP_GLOBAL_IMAGE_PREVIEW_KEY, { src })`）
+- 对等组件：`VideoPreviewTrigger`（视频触发端；封面/占位 + 播放图标两形态统一，仍需弹窗——视频无 el 原生预览）
+- 命令式弹窗体系：`ModalShelf`（架子 + level 层级）+ `ModalPorter`（modalList 注册表）+ 全局遥控器（`globalModalRemote`）
+- 范式页：`apps/reference/src/pages/modal/preview/showcase/`

package/src/components/modal/docs/README-ModalImagePreview.md

@@ -0,0 +1,78 @@
+# ModalImagePreview（图片预览弹窗·命令式入口）
+
+> 图片预览原语：**ElImageViewer 薄层适配**（el 图片预览组件本体 = 全屏 lightbox）+ **弹窗配置化契约包装**（`v-model:show` / 注册形态注入 / 双输入源）。
+> 注册 key 建议 `modalImagePreview`（ModalShelf/Porter 注册项）；全局预置 key = `APP_GLOBAL_IMAGE_PREVIEW_KEY`。
+> 范式页：`apps/reference/src/pages/modal/preview/showcase/`
+
+## 定位
+
+- **何时用**：**命令式 / 配置化唤起图片预览**——业务按钮、编排逻辑、全局遥控器 `evoke` 开图（el 图片预览无命令式 API，本组件是唯一桥梁）
+- **何时不用**：**点击图片看大图 → 直接用 `ElImage` 的 `preview-src-list`**（el 原生放大查看器，零开发）；触发组件 `ImagePreviewTrigger` 点击即直达 ElImage 预览，**不经本组件**——本组件只服务「不经过点击」的命令式入口
+- **为什么是薄适配**：el 图片预览组件（`ElImageViewer`）本身就是全屏 lightbox 弹层（遮罩 + 缩放旋转 + ESC/遮罩关闭）——**直接以它为底座**，只补一层弹窗配置化契约；[MUST NOT] 再包 `ModalConfirm`（两层嵌套：弹窗内再点才放大——脱裤子放屁，已废弃）
+- 关键机制：`defineModel("show")` → 内部映射 ElImageViewer `v-model:visible`；关闭（ESC / 遮罩 / 关闭按钮）→ `update:visible` → 映射 `update:show` → 架子 `@update:show` 收尾关闭
+- **注册形态（ModalShelf/Porter）**：架子渲染只传 `show`/`payload`/`closeFn`/`removeFn`——业务值走 payload，双输入源：`src` = `props.src ?? payload.src`（原语用法 prop 直传、注册用法 payload 承载）
+- **全局预置**：core 预置 `APP_GLOBAL_IMAGE_PREVIEW_KEY`——AppLayout `enableGlobalImagePreview` 开启后自动注册进全局弹窗（见 README-AppLayout）；命令式 `globalModalRemote.evoke(APP_GLOBAL_IMAGE_PREVIEW_KEY, { src })` 即开图
+
+## 快速上手（最小可用）
+
+```vue
+<ModalImagePreview v-model:show="show" src="https://example.com/a.png" />
+```
+
+**要点**：
+
+- `show` 必传（`v-model:show`）；`src` 必传（图片地址）
+- 打开即全屏 lightbox（el 原生：缩放 / 旋转 / 左右切换 / ESC / 遮罩关闭）
+- 命令式：`globalModalRemote.evoke(APP_GLOBAL_IMAGE_PREVIEW_KEY, { src })`
+
+## 能力边界 / 按需使用
+
+- **默认即够用：`show` + `src` = 全屏图片预览**——绝大多数命令式场景只传这两项。
+- `url-list` / `initial-index`：多图切换（`$attrs` 透传 ElImageViewer）。
+- `hide-on-click-modal` / `close-on-press-escape` / `show-close`：关闭通道控制（透传 ElImageViewer）。
+- 点图放大的「点击路径」不归本组件：`ImagePreviewTrigger` / 任意 `ElImage` 的 `preview-src-list` 直达。
+- **完整能力演示**：`apps/reference/src/pages/modal/preview/showcase/`——能力展示，非推荐默认。
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props（内联 defineProps，无 types.ts）
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必传） | — | 可见性（v-model:show → ElImageViewer visible） |
+| `src` | `string`（必传） | — | 图片地址（双输入源 `props.src ?? payload.src`） |
+| `payload` | `{ src?: string }` | — | 注册形态注入（架子渲染只传 payload；原语用法无需传） |
+| `closeFn` / `removeFn` | `() => void` | — | 注册形态注入的关闭/移除出口（声明避免泄漏进 `$attrs`） |
+| `onClose` | `(status?: boolean) => void` | — | 关闭回调（ElImageViewer @close 触发） |
+
+> **ElImageViewer 属性全量透传**：`$attrs` 直达——`url-list` / `initial-index` / `hide-on-click-modal` / `close-on-press-escape` / `show-close` / `teleported` / `z-index` 等均可用。
+
+### Emits
+
+| 事件 | 载荷 | 语义 |
+| --- | --- | --- |
+| `update:show` | `boolean` | 可见性同步（v-model；ElImageViewer 关闭 → `update:visible` 映射） |
+
+### Slots
+
+无（ElImageViewer 为全屏查看器，无内容插槽语义）
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **[MUST NOT] 包 `ModalConfirm` 底座**：两层预览嵌套已废弃（弹窗内再点放大 = 脱裤子放屁）——本组件 = ElImageViewer + 契约，薄层不叠加
+- **点击路径不走本组件**：点图看大图用 `ElImage` `preview-src-list` / `ImagePreviewTrigger` 直达——本组件只服务命令式入口，两路径各司其职
+- **无标题 / 无按钮语义**：lightbox 沉浸形态不配 title/footer/确认取消——需要「弹窗 + 图片 + 操作按钮」的形态用 `ModalConfirm` + `ElImage` 消费方自拼
+- **关闭映射链**：ElImageViewer 关闭 → `update:visible` → `update:show` → 架子收尾——[MUST NOT] 另接关闭逻辑造成双通道
+
+## 关联
+
+- 弹层族：`ModalConfirm`（确认/表单弹窗体系——图片预览不再用它做底座）、`ModalForm`、`ModalDetail`
+- 预览族：`ModalVideoPreview`（视频预览，同为 lightbox 形态；视频无 el 原生组件，ElDialog 直配黑底）
+- 触发端：`ImagePreviewTrigger`（ElImage + 懒加载 + 占位兜底，**点击直达 ElImage 原生预览**，不经本组件）
+- 命令式弹窗体系：`ModalShelf`（架子 + level 层级）+ `ModalPorter`（modalList 注册表）+ 全局遥控器（`globalModalRemote.evoke(APP_GLOBAL_IMAGE_PREVIEW_KEY, { src })`）
+- 范式页：`apps/reference/src/pages/modal/preview/showcase/`

package/src/components/modal/docs/README-ModalPorter.md

@@ -43,6 +43,7 @@ const modalList: RegisterEntry[] = [
 | name | type | 默认 | 语义 |
 | --- | --- | --- | --- |
 | `modalList` | `RegisterEntry[]`（必传） | — | 弹窗注册表（key → component/懒工厂 → shelf → sameKeyStrategy） |
+| `globalOnly` | `symbol`（core 内部专用） | 无默认 | **专用模式标识**：仅 AppLayout 内部调用时传（`APP_GLOBAL_MODAL_PORTER_SYMBOL`，core 内部不导出）——只接受 `shelf:"app"` 条目推送，非 app 条目 `console.error` + 过滤；外部 [MUST NOT] 使用（Symbol 拿不到即无法误用） |
 
 ### Slots
 
@@ -70,6 +71,14 @@ const modalList: RegisterEntry[] = [
 
 失活/卸载时自动 remove 本 porter 注册的全部 nsKey（useActivated 统一收口）——Porter 销毁即弹窗实例随架清理，**[MUST NOT]** 手动补偿清理。
 
+### 专用模式（`globalOnly`：AppLayout 内部全局弹窗 Porter）
+
+AppLayout 在调用内置 app 级 ModalShelf 的**子元素最前**位置调用一个打 `globalOnly` 标识的专用 Porter，配置数据直接来自 AppLayout 的 `globalModalConfig` prop——**全局弹窗的唯一注册入口**。专用模式下：
+
+- 只接受 `shelf:"app"` 条目；**非 app 条目（page/custom）`console.error` + 过滤**——page 级弹窗注册不得逃逸到全局面（page 级作用域由路由层保证）；
+- 推送的配置落到 app 级架子 → 挂载进 `globalModalRemote`（经 AppLayout `v-model:globalModalRemote` → 内置架子 `v-model:remote`），应用根即可遥控；
+- 专用 Porter 生命周期与 AppLayout 同寿——**规避页面级 Porter 配 app 级弹窗的孤儿弹窗反模式**（页面卸载后弹窗还挂在常驻 app 架子上、句柄丢失）。
+
 ### 注入给弹窗的 props（`ModalInjectedProps<P>`）
 
 架子把 `{show, closeFn, removeFn, payload: P}` 注入弹窗组件（见 ModalShelf 文档）。
@@ -80,6 +89,7 @@ const modalList: RegisterEntry[] = [
 - **shelf 字符串只认 "app"/"page"**：custom 架子必须传 `ShelfInstance`（ref 实例），传字符串进 custom 寻址不通
 - **key 类型必须声明合并**：evoke 的 key 泛型约束 `keyof ModalShelfMap`——业务 [MUST] 在 `.d.ts` 里 declare module 扩展 `ModalShelfMap`（见 ModalShelf 文档），否则 key 不在 map 上 TS 直接拦截
 - **自动清理别补偿**：Porter 失活/卸载已自动 remove 全部 nsKey，手写 `onUnmounted` 清理是重复劳动（也可能提前清掉活跃弹窗）
+- **页面级 Porter [MUST NOT] 配 `shelf:"app"` 条目**：页面卸载后弹窗仍挂在常驻 app 架子上 → 孤儿弹窗（唤起句柄已死、只剩弹窗自身 closeFn）；app 级弹窗唯一正道 = AppLayout `globalModalConfig` + 内部专用 Porter + `globalModalRemote` 遥控
 - **弹窗 UI 不在 Porter 插槽里写**：Porter 只是注册表宿主，弹窗经 evoke 落在架子上渲染——插槽只放页面内容
 
 ## 关联