@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/references/http-api.md

@@ -1,110 +1,130 @@
 ---
 skill: http-api
-description: 规范 HTTP 请求封装、API 接口文件组织、RSA+AES 加解密调用、文件下载等网络层开发模式。在编写或修改 API 接口调用时调用。
+description: 规范 HTTP 请求封装、API 接口文件组织、加解密与文件下载。编写或修改 API 时加载。
 scope: project
 tags: [axios, http, api, encryption, rsa, aes, download, request]
 ---
 
 # HTTP 请求与 API 接口规范
 
+> 实现落点：`src/utils/http.ts`、`src/api/**`、全局 `Result<T>`。
+
 ## Http 封装架构
 
-项目使用自定义 `Http` 类封装 Axios，位于 `src/utils/http/`。核心特性：
+项目使用自定义 `Http` 类封装 Axios，位于 `src/utils/http.ts`。核心特性：
+
+- 请求/响应拦截器统一处理 Token（`token` / `userCode` 请求头）、错误弹窗、NProgress
+- RSA + AES 混合加解密（由 `VITE_ENCODE_SWITCH` 全局控制，非单请求开关）
+- 请求去重（相同请求默认取消前一个，可用 `repeatRequest: true` 放行）
+- 统一响应类型 `Result<T>`（定义在 `types/global.d.ts`）
 
-- 请求/响应拦截器统一处理 Token、错误码、Loading 状态
-- RSA + AES 混合加密（通过 `@CryptoAPI` 注解配合后端）
-- 请求去重（相同请求自动取消前一个）
-- 统一响应类型 `Result<T>`
+```typescript
+import { http } from "@/utils/http";
+```
 
 ## 统一响应类型
 
 ```typescript
-interface Result<T = any> {
-  success: boolean;
-  data: T;
-  message: string;
-  code: number;
+/** types/global.d.ts — 权威定义 */
+interface Result<T = unknown> {
+  att?: unknown[];
+  data?: T | null;
+  exceptionName?: null;
+  status?: number;
+  statusText?: string;
+  name?: string;
 }
 ```
 
-所有 API 返回值必须包裹在 `Result<T>` 中，通过 `data` 字段获取业务数据。
+- 成功判断：`res.status === 200`
+- 业务数据：`res.data`
+- 错误文案：`res.statusText`
+- **不要**使用 `success` / `code` / `message` 这类非本项目字段
+
+分页数据结构：
+
+```typescript
+interface Data {
+  pageNo?: number;
+  pageSize?: number;
+  pageCount?: number;
+  totalCount?: number;
+  content?: Content[];
+}
+
+interface QueryData {
+  pageNo: number;
+  pageSize: number;
+}
+```
 
 ## API 调用标准模式
 
 ### 接口文件组织
 
-API 文件按业务模块拆分，放在 `src/api/` 目录下：
+API 按业务模块放在 `src/api/`（多为 `模块/index.ts`）：
 
 ```
 src/api/
-├── system.ts       # 系统管理接口
-├── order.ts        # 订单模块接口
-├── report.ts       # 报表模块接口
-└── modules/
-    └── auth.ts     # 认证相关接口
+├── login/index.ts
+├── common/index.ts
+├── table/index.ts
+├── home/index.ts
+├── graph/index.ts
+└── ...
 ```
 
 ### 接口定义格式
 
 ```typescript
-import http from "@/utils/http";
-import type { Result } from "@/utils/http/types";
-import type { UserListParams, UserListResult, UserInfo } from "./types/system";
-
-/** 获取用户列表 */
-export function getUserListApi(data: UserListParams) {
-  return http.request<Result<UserListResult>>(
-    "post",
-    "/api/system/user/list",
-    { data }
-  );
-}
+import { http } from "@/utils/http";
 
-/** 获取用户详情 */
-export function getUserDetailApi(id: string) {
-  return http.request<Result<UserInfo>>(
+/** 真实业务接口：环境变量 + 后端 path */
+export function getUserListApi(data: CombinedQueryData) {
+  return http.request<Result<Data>>(
     "post",
-    "/api/system/user/detail",
-    { data: { id } }
+    `${import.meta.env.VITE_API_BASE_URL}/console/user/list`,
+    { data },
   );
 }
 
-/** 删除用户 */
-export function deleteUserApi(id: string) {
-  return http.request<Result<null>>(
-    "post",
-    "/api/system/user/delete",
-    { data: { id } }
-  );
-}
+/** 本地 Mock：仅开发 Fake Server 使用，不是前后端 URL 规范 */
+export const getLogin = (data: LoginParams) => {
+  return http.request<Result<UserData>>("post", "/mock/login", { data });
+};
 ```
 
 ### 接口约定
 
-1. **所有接口统一使用 POST 方法**，参数通过 `data` 传递。
-2. 接口函数命名：`[动作] + [模块] + Api`，如 `getUserListApi`、`deleteOrderApi`。
-3. 接口函数必须声明完整的参数类型和返回类型。
-4. 接口类型定义放在对应的 `types/` 文件或同目录 `type.ts` 中。
-5. 不要在组件中直接写 `http.request`，必须抽取到 `api/` 目录。
+1. **请求方法以后端文档为准，允许 GET / POST**。常见列表/提交多用 POST + `data`；下载模板、签名、部分查询等后端要求 GET 时用 GET + `params`（见 `getDownLoadTemplate`、微信签名等）。
+2. **参数位置与方法匹配**：POST → `data`；GET → `params`。不要为了“统一 POST”强行改写后端已定义的 GET。
+3. **真实地址**用 `import.meta.env.VITE_API_BASE_URL` 拼接后端 path；**禁止硬编码域名**。
+4. **`/mock/...` 等路径仅用于本地 Fake Server**（`mock/` + `vite-plugin-fake-server`），联调真实后端时必须换成真实 path。
+5. **不要**虚构统一前缀 `/api/...` 当作项目标准。
+6. 字段命名前后端统一 **驼峰 camelCase**（如 `userName`、`userCode`）。
+7. Java `Long` / `BigDecimal` → 前端 `string`。
+8. 接口函数命名语义化，如 `getLogin`、`getTableList`、`deleteAttachmentById`。
+9. 不要在组件中直接写 `http.request`，必须抽到 `src/api/`。
+10. `Result<T>` 为全局类型，一般无需从 http 目录再 import。
 
 ## 在组件中使用 API
 
 ```vue
 <script setup lang="ts">
-import { ref } from "vue";
-import { getUserListApi } from "@/api/system";
-import type { UserListResult } from "@/api/types/system";
+import { getUserListApi } from "@/api/xxx";
 
 const loading = ref(false);
-const tableData = ref<UserListResult["list"]>([]);
+const tableData = ref<Content[]>([]);
 const total = ref(0);
 
-async function fetchData(params: UserListParams) {
+async function fetchData(params: CombinedQueryData) {
   loading.value = true;
   try {
-    const { data } = await getUserListApi(params);
-    tableData.value = data.list;
-    total.value = data.total;
+    const res = await getUserListApi(params);
+    if (res.status === 200) {
+      tableData.value = res.data?.content ?? [];
+      total.value = res.data?.totalCount ?? 0;
+    }
   } finally {
     loading.value = false;
   }
@@ -112,77 +132,92 @@ async function fetchData(params: UserListParams) {
 </script>
 ```
 
+列表页优先使用 `useTableSearch`（已按 `pageNo` / `pageSize` / `content` / `totalCount` / `status === 200` 对接）。
+
 ## 加密请求
 
-项目支持 RSA + AES 混合加密，用于敏感数据传输（密码、身份证号等）。
+加解密由环境变量控制，实现见 `src/utils/http.ts`、`src/utils/encryptUtils.ts`：
 
-### 使用方式
+| 变量 | 作用 |
+|------|------|
+| `VITE_ENCODE_SWITCH` | 是否开启加解密 |
+| `VITE_ENCODE_PUBKEY` | 前端加密用公钥 |
+| `VITE_ENCODE_PRIKEY` | 前端解密用私钥 |
 
 ```typescript
-// 普通请求（不加密）
+// ✅ 正确：开关开着时拦截器自动处理，业务侧照常传 data
 http.request<Result<T>>("post", url, { data: params });
 
-// 加密请求（通过配置项开启）
-http.request<Result<T>>("post", url, {
-  data: params,
-  crypto: true,  // 开启 RSA+AES 加密
-});
+// ❌ 错误：项目中不存在单请求 crypto: true 配置
+http.request<Result<T>>("post", url, { data: params, crypto: true });
 ```
 
-### 加密流程
+### 加密流程（开关开启时）
 
-1. 前端生成随机 AES 密钥
-2. 用 AES 密钥加密请求体
-3. 用后端公钥（RSA）加密 AES 密钥
-4. 将加密后的 AES 密钥 + 密文一起发送
-5. 后端用私钥解密 AES 密钥，再解密请求体
-6. 响应数据同样使用 AES 加密返回
+1. 前端生成会话 AES 密钥，RSA 公钥封装后放入 `accessToken` 字段
+2. 请求体 AES 加密；请求头带 `sign`
+3. 后端解密后处理业务
+4. 响应若带 `accessToken`，前端 RSA 解开密钥再 AES 解密得到业务 `Result`
 
-## 文件下载
+注意：GET、FormData、白名单路径不走加解密。
 
-### 标准下载模式
+## 文件上传 / 下载
 
-```typescript
-import { blobDown } from "@/utils/download";
+### 上传
 
-/** 导出 Excel */
-export function exportUserExcelApi(data: ExportParams) {
-  return http.request<Blob>(
+```typescript
+export function getUploadUrl(path: string, data: FormData) {
+  const url = path || "/documentInfo/uploadFile";
+  return http.request<Result<UploadFileResult>>(
     "post",
-    "/api/system/user/export",
-    { data, responseType: "blob" }
+    `${import.meta.env.VITE_API_BASE_URL}${url}`,
+    {
+      data,
+      headers: { "Content-Type": "multipart/form-data" },
+    },
+    { repeatRequest: true },
   );
 }
+```
 
-// 在组件中调用
-async function handleExport() {
-  const res = await exportUserExcelApi(queryParams);
-  blobDown(res, "用户列表.xlsx");
+### 下载
+
+```typescript
+import { blobDown } from "@/utils/utils";
+
+export function downloadFile(data: Recordable) {
+  return http.request<Result<Blob>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/documentInfo/downloadFile`,
+    { data },
+    { responseType: "blob" },
+  );
 }
-```
 
-### 下载工具函数
+// 组件中：拦截器对 Blob 可能返回 { data, name }
+const res = await downloadFile(params);
+blobDown(res.data, res.name || "文件.xlsx", res);
+```
 
-- `blobDown(data, filename)` — 将 Blob 数据下载为文件
-- `download(url, filename)` — 通过 URL 下载文件
-- `downloadAttachment(id)` — 根据附件 ID 下载附件
+相关工具：
 
-## 请求取消
+- `blobDown(data, name, response)` — Blob 下载（`src/utils/utils.ts`）
+- `getDownLoadTemplate(name)` — 模板下载（GET + `params`，属现有特例）
 
-使用 `AbortController` 实现请求取消，页面切换时自动取消未完成的请求：
+## 请求取消 / 重复请求
 
-```typescript
-// http 封装内部自动处理，组件中无需手动取消
-// 但如果需要手动取消：
-const controller = new AbortController();
-http.request("post", url, { data, signal: controller.signal });
-controller.abort(); // 取消请求
-```
+- 默认 `repeatRequest: false`：相同请求会取消前一个。
+- 需要允许并发时传 `{ repeatRequest: true }`（如上传）。
+- 也可传 `signal: AbortController.signal` 手动取消。
 
 ## 常见反例
 
-- 在组件中直接写 `axios.post()` 而不通过 http 封装。
-- 接口函数不声明返回类型，使用 `any`。
-- 使用 GET 方法传 query 参数（本项目统一用 POST + data）。
-- 下载文件时忘记设置 `responseType: "blob"`。
-- 把接口 URL 硬编码在组件中而不抽取到 `api/` 目录。
+- 在组件中直接 `axios.post()` / `fetch()`，绕过 `@/utils/http`。
+- 使用虚构的 `/api/...` 前缀，或把 `/mock/...` 当成生产约定。
+- 硬编码域名，不用 `VITE_API_BASE_URL`。
+- 后端文档是 GET，却强行改成 POST（或反过来）；POST 用 `params`、GET 用 `data` 等位置错配。
+- 按 `success` / `message` / `code` 或 `list` / `total` 解析响应。
+- 字段写成 `username` 等非驼峰，或与文档不一致。
+- 使用不存在的 `crypto: true`；或忘记配置 `VITE_ENCODE_*`。
+- 下载忘记 `responseType: "blob"`。
+- `Long` / 金额用 `number` 导致精度丢失。

package/references/icons.md

@@ -0,0 +1,326 @@
+---
+skill: icons
+description: 规范项目图标体系（本地 SVG 雪碧图、Iconify ep/ri、全局 svg-icon、ReIconPicker、菜单 meta.icon、UnoCSS presetIcons、svg?component）。在新增/选用图标、改菜单图标、图标选择器或内网离线图标时调用。
+scope: project
+tags: [vue3, icon, svg-icon, ReSvgIcon, ReIconPicker, iconify, ep, ri, unocss, menu-icon]
+---
+
+# 图标体系规范
+
+> 页面/菜单/按钮里要用图标时加载本模块。  
+> **真相源**：`src/components/ReSvgIcon`、`src/components/ReIconPicker`、`src/icons/svg`、`main.ts`、`uno.config.ts`、`build/plugins/SvgSpriteLoader.ts` / `SvgLoader.ts`。  
+> 选型表见 `project-inventory`「图标」节；勿另起 IconFont / 未约定的图标库。
+
+---
+
+## 依赖（core，模板已装）
+
+| 包 | 版本 | 用途 |
+|---|---|---|
+| `@iconify/vue` | `5.0.1` | Iconify 运行时渲染 |
+| `@iconify-json/ep` | `1.2.4` | Element Plus 图标集（dev） |
+| `@iconify-json/ri` | `1.2.10` | Remix Icon 集（dev） |
+| `vite-plugin-svg-icons` | `2.0.1` | 本地 SVG → Symbol 雪碧图 |
+| `vite-svg-loader` | `5.1.1` | `*.svg?component` 组件化 |
+
+缺包时按精确版本安装（征得确认）：
+
+```bash
+pnpm add @iconify/vue@5.0.1
+pnpm add -D @iconify-json/ep@1.2.4 @iconify-json/ri@1.2.10 vite-plugin-svg-icons@2.0.1 vite-svg-loader@5.1.1
+```
+
+构建接线（模板已有，**勿重复改 Vite**，除非用户明确要求）：
+
+- `build/plugins/SvgSpriteLoader.ts` → 扫描 `src/icons/svg`
+- `build/plugins/SvgLoader.ts` → `vite-svg-loader`
+- `main.ts`：`import 'virtual:svg-icons-register'` + `app.component('svg-icon', SvgIcon)`
+
+---
+
+## 一、选型决策（先选通道）
+
+| 场景 | 用法 | 说明 |
+|------|------|------|
+| 菜单 / 标签 / 业务页通用展示 | **`<svg-icon name="..." />`** | 全局组件，统一入口 |
+| 表单里选图标并回写字符串 | **`ReIconPicker`** | 选中值再交给 `svg-icon` |
+| 模板里一次性装饰图标（搜索框前缀等） | **UnoCSS** `i-ep-*` / `i-ri:*` | 不经 `svg-icon` |
+| 需当 Vue 组件传给 EP（如 `el-icon`、`:icon`） | **`import X from '...svg?component'`** | `vite-svg-loader` |
+| 大插画 / 错误页整图 | `assets/svg/*.svg?component` | 非菜单雪碧图 |
+
+**默认优先 `svg-icon`**。禁止：页面散落 `@iconify/vue` 的 `<Icon>`、引入未约定的 `@iconify-json/*` 全集、硬编码外链 Icon CDN（内网见第七节）。
+
+---
+
+## 二、命名与解析规则（`ReSvgIcon`）
+
+全局标签：`<svg-icon>`（实现：`src/components/ReSvgIcon/src/svgIcon.vue`）。
+
+| `name` 形态 | 判定 | 渲染 |
+|-------------|------|------|
+| 含 `:`（如 `ep:user`、`ri:download-line`） | Iconify | `@iconify/vue` 的 `<Icon>` |
+| 以 `i-` 开头且含 `:`（如 `i-ep:home`） | Iconify | 自动剥掉 `i-` 再渲染（兼容 Picker） |
+| 无冒号（如 `home`、`hot`） | 本地雪碧图 | `<use xlink:href="#icon-{name}" />` |
+
+Props：
+
+| Prop | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `name` | `string` | 必填 | 见上表 |
+| `size` | `number \| string` | `18` | 宽高与 fontSize |
+| `color` | `string` | `''` | 颜色；本地 SVG 宜 `fill="currentColor"` |
+
+```vue
+<template>
+  <!-- Iconify -->
+  <svg-icon name="ri:file-list-3-line" :size="18" color="var(--el-color-primary)" />
+  <svg-icon name="ep:user" :size="18" />
+
+  <!-- 本地：对应 src/icons/svg/home.svg -->
+  <svg-icon name="home" :size="18" />
+
+  <!-- Picker 回写值也可直接用 -->
+  <svg-icon name="i-ep:home" :size="18" />
+</template>
+```
+
+---
+
+## 三、本地 SVG 雪碧图
+
+### 目录与注册
+
+- 文件放在 **`src/icons/svg/*.svg`**（仅此目录进雪碧图）。
+- 插件：`vite-plugin-svg-icons`，`symbolId: 'icon-[dir]-[name]'`。
+- 运行时：`virtual:svg-icons-register`；`<svg-icon name="xxx">` → `#icon-xxx`（文件名无扩展名）。
+
+### 新增本地图标步骤
+
+1. 将 SVG 放入 `src/icons/svg/`，文件名用 **kebab-case 或已有风格**（如 `arrow-right-double.svg`、`circleClose.svg`），**不要空格**。
+2. path 使用 **`fill="currentColor"`**（或可继承 currentColor），便于跟主题色 / 菜单色。
+3. 业务里：`<svg-icon name="文件名不含扩展名" />`。
+4. 菜单：`meta: { icon: '文件名不含扩展名' }`。
+5. 无需改 `main.ts` / Vite；热更新后即可。
+
+### 现有本地名（摘要）
+
+`home`、`hot`、`iframe`、`graph`、`lollipop`、`logo`、`notice`、`arrowRight`、`collapse`、`expand`、`unexpand`、`refresh`、`select`、`close`、`fullscreen-fill`、`fullscreen-exit-fill`、`dataScreen`、`form`、`function`、`tools`、`component`、`grid`、`multiple`、`new`、`drag`、`menuoverflow`、`day`、`dark`、`check-line`、`semi-select`、`circleClose`、`bottom-left`、`bottom-right`、`arrow-right-double` 等。以仓库 `src/icons/svg` 为准。
+
+### 约定
+
+- **菜单高频、品牌、项目定制图形** → 本地 SVG。
+- **通用线性图标** → `ep:` / `ri:`，不必每个都落本地文件。
+- 勿把营销大图塞进 `icons/svg`；插画放 `src/assets/svg`。
+
+---
+
+## 四、菜单与路由图标
+
+侧栏 / 顶栏 / TagsView 均通过 **`meta.icon`（string）** → `<svg-icon :name="..." />`。
+
+```typescript
+// src/router/modules/xxx.ts
+export default {
+  path: "/customer",
+  redirect: "/customer/list",
+  meta: {
+    title: "客户管理",
+    icon: "ep:user", // 或本地 "home"
+    rank: 10,
+  },
+  children: [
+    {
+      path: "/customer/list",
+      name: "CustomerList",
+      component: () => import("@/views/customer/list/index.vue"),
+      meta: {
+        title: "客户列表",
+        icon: "ep:user",
+        // 可选：菜单右侧角标类小图标
+        extraIcon: "hot",
+      },
+    },
+  ],
+} satisfies RouteConfigsTable;
+```
+
+规则：
+
+1. `meta.icon` / `meta.extraIcon` **必须是 string**（本地名或 `ep:` / `ri:` / `i-ep:`…），不要塞组件对象。
+2. `extraIcon` 用于「热门」等角标（如本地 `hot`），侧栏在非折叠时展示。
+3. 业务路由模块**禁止**再挂 `Layout`（见 `core-kernel`）。
+
+---
+
+## 五、ReIconPicker 图标选择器
+
+路径：`src/components/ReIconPicker`。演示页：`src/views/form/iconPicker`（`/form/icon-picker`）。
+
+### 默认图标源
+
+| key | label | 说明 |
+|-----|-------|------|
+| `local` | 本地图标 | `import.meta.glob('/src/icons/svg/*.svg')`，值为**无冒号**文件名 |
+| `ep` | Element Plus | `@iconify-json/ep/icons.json`，选中值形如 **`i-ep:xxx`** |
+| `ri` | Remix Icon | `@iconify-json/ri/icons.json`，选中值形如 **`i-ri:xxx`** |
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import { ReIconPicker } from "@/components/ReIconPicker";
+
+const icon = ref("");
+</script>
+
+<template>
+  <ReIconPicker v-model="icon" clearable placeholder="请选择图标" />
+  <!-- 展示：与 Picker 值同一套 name 规则 -->
+  <svg-icon v-if="icon" :name="icon" :size="18" />
+</template>
+```
+
+### 限制来源 / 仅本地
+
+```vue
+<script setup lang="ts">
+import type { IconSourceConfig } from "@/components/ReIconPicker/src/type";
+import epIcons from "@iconify-json/ep/icons.json";
+import { ReIconPicker } from "@/components/ReIconPicker";
+
+const onlyEp: IconSourceConfig[] = [
+  { key: "ep", label: "Element Plus", iconData: epIcons },
+];
+const onlyLocal: IconSourceConfig[] = [
+  { key: "local", label: "本地图标", isLocal: true },
+];
+
+const iconEp = ref("i-ep:home");
+const iconLocal = ref("home");
+</script>
+
+<template>
+  <ReIconPicker v-model="iconEp" :sources="onlyEp" />
+  <ReIconPicker v-model="iconLocal" :sources="onlyLocal" />
+</template>
+```
+
+### 表单校验
+
+```vue
+<script setup lang="ts">
+import type { FormInstance, FormRules } from "element-plus";
+import { ReIconPicker } from "@/components/ReIconPicker";
+
+const formRef = ref<FormInstance>();
+const form = reactive({ icon: "" });
+const rules: FormRules = {
+  icon: [{ required: true, message: "请选择图标", trigger: "change" }],
+};
+</script>
+
+<template>
+  <el-form ref="formRef" :model="form" :rules="rules">
+    <el-form-item label="图标" prop="icon">
+      <ReIconPicker v-model="form.icon" required />
+    </el-form-item>
+  </el-form>
+</template>
+```
+
+Props 摘要：`modelValue`、`placeholder`、`disabled`、`clearable`、`size`、`sources`、`required`。  
+Emits：`update:modelValue`、`change`、`blur`、`focus`。
+
+---
+
+## 六、UnoCSS 图标类
+
+`uno.config.ts` 已启用 `presetIcons({ scale: 1.2 })`，并支持 `i-` 标签变体。
+
+```vue
+<template>
+  <!-- class 写法 -->
+  <i class="i-ep-search" />
+  <i class="i-ep:chat-dot-round" />
+
+  <!-- 属性化 / 组件标签（Uno 变体） -->
+  <i-ep-edit />
+</template>
+```
+
+约定：
+
+1. **动态绑定的图标 class** 若构建后丢失，加入 `uno.config.ts` 的 `safelist`（已有示例 `'i-ep:chat-dot-round'`）。
+2. 菜单、可配置图标、要随主题变色的业务图标 → 仍用 **`svg-icon`**，不要只用 Uno 类。
+3. 颜色用 `color-[var(--el-text-color-placeholder)]` 等变量，避免硬编码。
+
+---
+
+## 七、内网 / 离线 Iconify
+
+默认 `@iconify/vue` 会在首次渲染时请求 `https://api.iconify.design`。  
+内网或离线需在 `main.ts` **开启集合打入**（约 +3MB，注释已预留）：
+
+```typescript
+import { addCollection } from "@iconify/vue";
+import epIcons from "@iconify-json/ep/icons.json";
+import riIcons from "@iconify-json/ri/icons.json";
+
+addCollection(epIcons as any);
+addCollection(riIcons as any);
+```
+
+仅外网可访问时可保持注释关闭，按需拉取。
+
+---
+
+## 八、`svg?component` 组件化
+
+用于必须传入 **Vue 组件** 的场景（非字符串 name）：
+
+```vue
+<script setup lang="ts">
+import ExpandIcon from "@/icons/svg/expand.svg?component";
+import BackTopIcon from "@/assets/svg/back_top.svg?component";
+</script>
+
+<template>
+  <el-button :icon="ExpandIcon" />
+  <BackTopIcon />
+</template>
+```
+
+- 菜单雪碧图仍走 `src/icons/svg` + `svg-icon`。
+- `assets/svg`、`assets/login` 等静态图用 `?component` 或 `<img>`，不要混进菜单 `meta.icon`。
+
+---
+
+## 九、移动端
+
+Vant Tabbar 等使用 **Vant 自带图标名**（如 `home-o`），见 `mobile-h5`，**不要**把 `ep:` / `ri:` 字符串塞进 `van-tabbar-item` 的 `icon`。PC 与 H5 图标通道分离。
+
+---
+
+## 十、常见反例
+
+| 错误 | 正确 |
+|------|------|
+| 业务页直接 `<Icon icon="ep:xxx" />` | `<svg-icon name="ep:xxx" />` |
+| 菜单 `icon: () => import('...')` 组件 | `icon: "ep:user"` 或 `"home"` |
+| 硬编码 `#409EFF` 上色 | `color="var(--el-color-primary)"` 或 CSS `currentColor` |
+| 新图标丢进 `assets` 却当菜单名用 | 放入 `src/icons/svg` 或改用 `ep:`/`ri:` |
+| 未确认就 `pnpm add @iconify-json/mdi` | 优先 ep/ri/本地；新前缀须「待确认」 |
+| 内网环境不 `addCollection` 却大量用 Iconify | 开启第七节或改本地 SVG |
+| 通知栏等已支持本地名却写死外链 | `left-icon="notice"`（本地名） |
+
+---
+
+## 十一、生成后自检
+
+- [ ] 菜单 / 展示统一 `svg-icon` 或路由 `meta.icon` 字符串
+- [ ] `name` 符合「本地无冒号 / Iconify 含冒号」规则；Picker 的 `i-ep:` 可直接展示
+- [ ] 新增本地文件在 `src/icons/svg`，且 `currentColor`
+- [ ] 未擅自引入新图标集；未改 Vite 插件接线（除非用户要求）
+- [ ] 内网场景已说明是否需要 `addCollection`
+- [ ] 动态 Uno 图标类已考虑 `safelist`
+- [ ] 颜色走 CSS 变量 / `currentColor`，暗黑与侧栏主题下可读

package/references/layout-theme.md

@@ -297,7 +297,7 @@ src/layout/
 presetRemToPx({ baseFontSize: 4 })  // 所有 rem 值 × 4 = px（mt-1 → 1px）
 presetWind3()                        // Tailwind Wind 兼容
 presetAttributify()                  // 属性化模式
-presetIcons({ scale: 1.2 })         // 图标自动引入
+presetIcons({ scale: 1.2 })         // 图标自动引入（`i-ep-*` / `i-ri:*`；完整约定见 `icons`）
 ```
 
 ### 主题色桥接