@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/project-inventory.md

@@ -0,0 +1,326 @@
+# 项目资产清单（Project Inventory）
+
+> **本模块是 AI 代码生成的前置必读文件。**
+> 在生成任何功能代码之前，AI 必须先查阅本清单，确认项目中是否已有对应的库、组件、Hook 或工具函数。
+> **如果项目中已有实现，必须直接使用，禁止引入替代方案。**
+
+---
+
+## 一、三方库清单（按功能分类）
+
+### UI 框架
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `element-plus` | 2.14.x | PC 端 UI 组件库 | 主力框架，自动引入 |
+| `vant` | 4.10.x | 移动端 UI 组件库 | 移动端页面使用 |
+| `@wocwin/t-ui-plus` | 2.0.x | 基于 Element Plus 的企业级增强组件 | |
+| `plus-pro-components` | 0.1.x | Element Plus 企业级扩展组件 | |
+| `vxe-table` | 4.19.x | 高性能大数据表格 | >1000 行数据时使用 |
+| `vxe-pc-ui` | 4.15.x | VXE 配套 PC UI 组件 | |
+| `animate.css` | 4.1.x | CSS 动画库 | |
+
+### 图表与可视化
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `echarts` | 6.1.x | 图表引擎 | 配合 `ReEchart` 组件使用 |
+| `echarts-wordcloud` | 2.1.x | 词云图 | ECharts 扩展 |
+| `relation-graph-vue3` | 2.2.x | 关系/知识图谱 | 力导向/圆形/树形布局 |
+| `@antv/g6` | 5.1.x | 图可视化引擎 | 流程图，配合 `g6-extension-vue` |
+| `g6-extension-vue` | 0.1.x | G6 的 Vue 节点扩展 | 支持 Vue 组件作为图节点 |
+
+### 工作流与流程
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `bpmn-js` | 18.19.x | BPMN 2.0 工作流图渲染 | 使用 Viewer（只读），不用 Modeler |
+| `jsplumb` | 2.15.x | 可视化连线/字段映射 | 拖拽连接场景 |
+
+### 富文本与编辑器
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `@wangeditor/editor` | 5.1.x | 富文本编辑器 | 配合 `ReRichText` 组件使用 |
+
+### 图标
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `@iconify/vue` | 5.0.x | 图标框架 | 支持多图标集 |
+| `@iconify-json/ep` | 1.2.x | Element Plus 图标集 | |
+| `@iconify-json/ri` | 1.2.x | Remix Icon 图标集 | |
+| `vite-plugin-svg-icons` | 2.0.x | SVG 雪碧图 | 配合 `ReSvgIcon` 组件 |
+
+### 状态管理与路由
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `pinia` | 3.0.x | 状态管理 | Composition API 风格 |
+| `pinia-plugin-persistedstate` | 4.7.x | Pinia 持久化插件 | localStorage |
+| `vue-router` | 5.1.x | 路由 | Hash 模式 + 动态路由 |
+
+### HTTP 与加密
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `axios` | 1.18.x | HTTP 请求 | 项目已封装 `src/utils/http.ts` |
+| `crypto-js` | 4.2.x | AES 加解密 | 请求体加密 |
+| `jsencrypt` | 3.5.x | RSA 加解密 | 密钥交换 |
+| `js-md5` | 0.8.x | MD5 哈希 | 请求签名 |
+
+### 工具库
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `@vueuse/core` | 14.3.x | Vue 组合式工具集 | 自动引入 |
+| `@vueuse/math` | 14.3.x | 数学相关组合式函数 | |
+| `@vueuse/motion` | 3.0.x | 运动/入场动画 | `v-motion` 指令 |
+| `@pureadmin/utils` | 2.6.x | 工具函数集 | 下载、存储、设备检测等 |
+| `dayjs` | 1.11.x | 日期处理 | 不用 moment |
+| `qs` | 6.15.x | 查询字符串序列化 | |
+| `js-cookie` | 3.0.x | Cookie 操作 | |
+| `mitt` | 3.0.x | 事件总线 | 全局事件通信 |
+| `chroma-js` | 3.2.x | 颜色处理 | 主题色生成 |
+| `address-parse` | 1.2.x | 中文地址解析 | |
+| `nprogress` | 0.2.x | 路由进度条 | |
+| `responsive-storage` | 2.2.x | 响应式 localStorage | |
+| `sortablejs` | 1.15.x | 拖拽排序 | |
+| `vue-dompurify-html` | 5.3.x | 安全 HTML 渲染 | DOMPurify 过滤 XSS |
+| `browser-image-compression` | 2.0.x | 客户端图片压缩 | 上传前压缩 |
+| `version-rocket` | 1.7.x | 前端版本检测/自动更新 | |
+
+### 文件预览
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `@file-viewer/core` | 2.1.x | 文件预览核心 | |
+| `@file-viewer/vue3` | 2.1.x | 文件预览 Vue3 集成 | 配合 `ReFileViewer` |
+| `@file-viewer/preset-all` | 2.1.x | 文件预览全格式预设 | |
+
+### 二维码与条形码
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `qrcode` | 1.5.x | 二维码生成 | 配合 `ReQrcode` 组件 |
+| `jsbarcode` | 3.12.x | 条形码生成 | 配合 `ReBarcode` 组件 |
+
+### 验证与动画
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `vue3-puzzle-vcode` | 1.1.x | 滑块拼图验证码 | 配合 `ReVerify` 组件 |
+| `typeit` | 8.8.x | 打字机动画 | 配合 `ReTypeit` 组件 |
+| `@tsparticles/slim` | 4.3.x | 粒子动画 | 登录页背景 |
+| `@tsparticles/vue3` | 4.3.x | 粒子动画 Vue3 集成 | |
+| `tippy.js` / `vue-tippy` | 6.x | Tooltip 提示 | |
+
+### 微信集成
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `weixin-js-sdk` | 1.6.x | 微信 JS-SDK | 分享/定位，配合 `useWechat` Hook |
+| `vconsole` | 3.15.x | 移动端调试控制台 | 仅开发/测试环境 |
+
+### 布局
+
+| 库 | 版本 | 用途 | 备注 |
+|---|---|---|---|
+| `grid-layout-plus` | 1.1.x | 拖拽网格布局 | 大屏/仪表盘 widget |
+| `unocss` | 66.x | 原子化 CSS | presetWind3，类 Tailwind 语法 |
+
+---
+
+## 二、Re* 自定义组件清单
+
+> 所有自定义组件以 `Re` 为前缀，目录结构统一为 `ReXxx/src/xxx.vue` + `index.ts` + `type.ts`。
+> **开发新功能时，必须先检查此清单是否已有对应组件，禁止重复造轮子。**
+
+| 组件 | 用途 | 所在目录 |
+|---|---|---|
+| **ReAnchor** | 锚点导航（滚动定位） | `src/components/ReAnchor/` |
+| **ReAttachment** | 附件上传/管理 | `src/components/ReAttachment/` |
+| **ReAuth** | 权限包裹（按 auth code 控制显隐） | `src/components/ReAuth/` |
+| **ReAvatars** | 用户头像展示 | `src/components/ReAvatars/` |
+| **ReBarcode** | 条形码生成 | `src/components/ReBarcode/` |
+| **ReCascader** | 级联选择器 | `src/components/ReCascader/` |
+| **ReCheckCard** | 卡片选择（多选） | `src/components/ReCheckCard/` |
+| **ReCollapsible** | 折叠面板 | `src/components/ReCollapsible/` |
+| **ReDatePicker** | 日期选择器 | `src/components/ReDatePicker/` |
+| **ReDateRangePicker** | 日期范围选择器 | `src/components/ReDateRangePicker/` |
+| **ReDialog** | 弹窗 | `src/components/ReDialog/` |
+| **ReDialogResize** | 可拖拽缩放弹窗 | `src/components/ReDialogResize/` |
+| **ReDragVerify** | 拖拽验证（滑块验证） | `src/components/ReDragVerify/` |
+| **ReEchart** | ECharts 图表容器 | `src/components/ReEchart/` |
+| **ReFileViewer** | 文件预览（Office/PDF） | `src/components/ReFileViewer/` |
+| **ReFlicker** | 闪烁点效果 | `src/components/ReFlicker/` |
+| **ReGrid** | 栅格布局容器 | `src/components/ReGrid/` |
+| **ReGridItem** | 栅格子项 | `src/components/ReGridItem/` |
+| **ReHeaderPage** | 页面头部（标题/面包屑） | `src/components/ReHeaderPage/` |
+| **ReIconPicker** | 图标选择器 | `src/components/ReIconPicker/` |
+| **ReImageVerify** | 图片验证码 | `src/components/ReImageVerify/` |
+| **ReLanguageSwitch** | 语言切换 | `src/components/ReLanguageSwitch/` |
+| **ReNoticeBar** | 通知栏（长文本滚动） | `src/components/ReNoticeBar/` |
+| **RePagination** | 分页器 | `src/components/RePagination/` |
+| **RePopupPicker** | 弹出式选择器（移动端） | `src/components/RePopupPicker/` |
+| **ReQrcode** | 二维码生成 | `src/components/ReQrcode/` |
+| **ReRichText** | 富文本编辑器 | `src/components/ReRichText/` |
+| **ReSeamlessScroll** | 无缝滚动容器 | `src/components/ReSeamlessScroll/` |
+| **ReSegmented** | 分段控制器 | `src/components/ReSegmented/` |
+| **ReSelectQuery** | 远程搜索选择器（带分页） | `src/components/ReSelectQuery/` |
+| **ReSelectVant** | 移动端选择器 | `src/components/ReSelectVant/` |
+| **ReSmsCode** | 短信验证码倒计时按钮 | `src/components/ReSmsCode/` |
+| **ReSvgIcon** | SVG 图标 | `src/components/ReSvgIcon/` |
+| **ReTableBar** | 表格工具栏 | `src/components/ReTableBar/` |
+| **ReTableOperate** | 表格操作按钮（增删改查） | `src/components/ReTableOperate/` |
+| **ReText** | 文本展示（智能省略/tooltip） | `src/components/ReText/` |
+| **ReTimeLine** | 时间轴 | `src/components/ReTimeLine/` |
+| **ReTreeLine** | 树形连线 | `src/components/ReTreeLine/` |
+| **ReTypeit** | 打字机动画 | `src/components/ReTypeit/` |
+| **ReVerify** | 滑块拼图验证 | `src/components/ReVerify/` |
+
+---
+
+## 三、Hooks 清单
+
+> 所有 Hook 位于 `src/hooks/` 目录。开发新功能时必须先检查是否已有可复用的 Hook。
+
+| Hook | 用途 | 关键 API |
+|---|---|---|
+| **useApp** | 全局应用状态（布局、字典、登出等） | `baseCodeGet(codeType)`、`filterValue()`、`headerHeight`、`svgLoading` |
+| **useDetail** | 详情页跳转与参数传递 | `toDetail({ id, mark, text })`、`initToDetail()`、`getParameter()` |
+| **useFormCheck** | 多表单校验聚合 | 追踪各字段校验状态，emit `form-validate` 事件 |
+| **useTableSearch** | 列表页搜索/分页/Loading | `content`、`pagination`、`loading`、`handleSearch()`、`handleReset()` |
+| **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
+| **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
+| **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |
+| **useWechat** | 微信 JS-SDK | `isReady`、`error` |
+
+---
+
+## 四、工具函数清单
+
+> 所有工具位于 `src/utils/` 目录。
+
+| 文件 | 关键导出 | 用途 |
+|---|---|---|
+| `auth.ts` | `getToken()`、`setUserToken()`、`removeToken()` | Token 管理 |
+| `autoUpdate.ts` | `checkUpdate()` | 前端版本检测/自动刷新 |
+| `changeSummaryService.ts` | `ChangeSummaryService.getChangeSummaryData()` | v-compare 变更汇总读取/元素引用修复 |
+| `encryptUtils.ts` | `aesEncrypt()`、`aesDecrypt()`、`rsaEncrypt()`、`md5Sign()` | 加解密工具 |
+| `http.ts` | `http.request()` | Axios 封装（统一 POST + 加密 + 拦截器） |
+| `i18n.ts` | `getLocale()` | 语言检测 |
+| `imageCompression.ts` | `compressImage()` | 图片压缩（上传前） |
+| `message.ts` | `message()` | 消息提示封装（ElMessage 包装） |
+| `mitt.ts` | `mitt()` | 全局事件总线 |
+| `motion.tsx` | `MotionComponent` | 入场动画 TSX 组件 |
+| `particles.ts` | `particlesConfig` | 粒子动画配置 |
+| `progress/` | `NProgress` | 路由进度条配置 |
+| `responsive.ts` | `ResponsiveStorage` | 响应式存储注入 |
+| `router.ts` | `hasAuth()`、路由扁平化、权限过滤 | 路由工具 |
+| `rule.ts` | `passwordRule`、`phoneRule` | 表单校验规则（PC） |
+| `tree.ts` | `handleTree()`、`buildHierarchyTree()` | 树结构转换 |
+| `uploadManager.ts` | `UploadManager` | 批量上传任务管理 |
+| `useActivity.ts` | `useActivity()` | 用户空闲检测/自动登出 |
+| `utils.ts` | `svgLoad()`、`composeOptions()`、`getRowClassByFlag()`、`escapeAttrSelector()`、`formatFileSize()` 等 | 通用工具（含对比辅助） |
+| `vantRules.ts` | `vantRules` | 表单校验规则（移动端 Vant） |
+| `websocket/` | `initWebSocket()`、`closeWebSocket()`、`WebSocketManager` | WebSocket 基础设施 |
+| `wechat/` | `WechatSDK` | 微信 SDK 单例 |
+
+---
+
+## 五、自定义指令清单
+
+> 所有指令位于 `src/directives/` 目录，在 `src/directives/index.ts` 统一注册。
+
+| 指令 | 用途 | 用法示例 |
+|---|---|---|
+| **v-auth** | 按钮级权限控制（无权限移除 DOM） | `v-auth="['btn.add']"` |
+| **v-auto-font** | 根据容器宽度自动缩放字体 | `v-auto-font:0.8` 或 `v-auto-font="{ scale: 0.8, min: 12, max: 24 }"` |
+| **v-compare** | 编辑页变更对比（高亮+汇总） | `v-compare:key="{ oldValue, title, label, enabled }"`；详见 data-compare |
+| **v-copy** | 复制文本到剪贴板 | `v-copy="text"`（双击）、`v-copy:click="text"`（单击） |
+
+---
+
+## 六、Store 模块清单
+
+> 所有 Store 位于 `src/store/modules/`，使用 `pinia-plugin-persistedstate` 持久化。
+
+| Store | 用途 | 关键状态/方法 |
+|---|---|---|
+| **useAppStore** | 应用全局状态 | 侧边栏、布局模式、设备类型 |
+| **useBaseCodeStore** | 字典/码表缓存 | 按 `codeType` 获取+缓存 |
+| **useCompareStore** | 变更对比追踪 | `addOrUpdateRecord` / `clearAllRecords`；按 title 模块分组 |
+| **useLangStore** | 语言设置 | 持久化到 localStorage + cookie |
+| **useMultiTagsStore** | 多标签页 | 标签增删排序 |
+| **useRouterMenuStore** | 路由/菜单 | 静态+动态菜单、keepAlive 缓存 |
+| **useSettingStore** | UI 设置 | 标题、固定头部、侧边栏显隐 |
+| **useThemeStore** | 主题 | 主题色、暗色模式 |
+| **useUserStore** | 用户信息 | userCode、userName、角色、token |
+
+---
+
+## 七、示例页面索引
+
+> 所有示例位于 `src/views/`，是功能开发的参考模板。遇到类似需求时，AI 应优先参考对应示例的代码模式。
+
+| 示例页面 | 路径 | 对应功能 |
+|---|---|---|
+| 附件管理 | `views/attachment/` | 文件上传/下载/管理 |
+| 组件展示 | `views/component/` | 头像、按钮、详情页、Loading、消息提示 |
+| 数据大屏 | `views/dataScreen/` | 可视化大屏 |
+| 表单示例 | `views/form/` | 级联、图标选择、选择器、树选择、多表单 |
+| 数据变更对比 | `views/form/moreForm/`（`/form/moreFormAnchor`） | v-compare、变更汇总、表格行 I/U/D |
+| 功能示例 | `views/function/` | 地址解析、字典、下载、通知栏、二维码、滚动、时间轴、水印 |
+| 知识图谱 | `views/graph/` | 关系图谱（relation-graph） |
+| 首页/仪表盘 | `views/home/` | Widget 侧边栏、词云、分类图 |
+| 登录页 | `views/login/` | 登录 + 二维码登录 |
+| 移动端 | `views/mobile/` | 客户管理、Loading（Vant） |
+| 权限演示 | `views/permission/` | 角色页面、按钮权限、页面权限 |
+| 表格示例 | `views/table/` | 基础表格、树形表格、VXE 高性能表格 |
+| WebSocket | `views/websocket/` | 实时通信 |
+| 微信 | `views/wechat/` | JS-SDK 集成 |
+| 工作流 | `views/workflow/` | BPMN、G6 流程图、JsPlumb 映射 |
+
+---
+
+## 八、功能选型对照表（禁止替换）
+
+> 当用户需求涉及以下场景时，**必须使用项目已有的库/组件**，不得引入替代方案。
+
+| 需求场景 | 项目选型 | 禁止替代 |
+|---|---|---|
+| 图表 | `echarts` + `ReEchart` | 禁止使用 Chart.js / D3 / Plotly 等 |
+| 关系/知识图谱 | `relation-graph-vue3` | 禁止引入 D3 / vis.js / Cytoscape 等 |
+| 流程图 | `@antv/g6` + `g6-extension-vue` | 禁止引入 Mermaid / X6 / LogicFlow 等 |
+| BPMN 工作流 | `bpmn-js` (Viewer) | 禁止引入其他 BPMN 库 |
+| 字段映射/连线 | `jsplumb` | 禁止引入 LeaderLine / Drawflow 等 |
+| 富文本编辑器 | `@wangeditor/editor` + `ReRichText` | 禁止引入 Quill / TinyMCE / CKEditor 等 |
+| 二维码 | `qrcode` + `ReQrcode` | 禁止引入其他二维码库 |
+| 条形码 | `jsbarcode` + `ReBarcode` | 禁止引入其他条形码库 |
+| 文件预览 | `@file-viewer/*` + `ReFileViewer` | 禁止引入 pdf.js / mammoth 等 |
+| 滑块验证 | `vue3-puzzle-vcode` + `ReVerify` | 禁止引入其他验证码库 |
+| 打字机动画 | `typeit` + `ReTypeit` | 禁止引入其他打字机库 |
+| 粒子动画 | `@tsparticles/slim` | 禁止引入 particles.js 等 |
+| 日期处理 | `dayjs` | 禁止引入 moment / date-fns 等 |
+| HTTP 请求 | 项目封装的 `src/utils/http.ts`（基于 axios） | 禁止直接使用 axios / fetch / ky 等 |
+| 状态管理 | `pinia` + `pinia-plugin-persistedstate` | 禁止引入 vuex / zustand 等 |
+| 原子化 CSS | `unocss` | 禁止引入 tailwindcss / windicss 等 |
+| 拖拽排序 | `sortablejs` | 禁止引入 vuedraggable / dnd-kit 等 |
+| 微信集成 | `weixin-js-sdk` + `useWechat` | 禁止引入其他微信 SDK |
+| 高性能表格 | `vxe-table` | 禁止引入 ag-grid / handsontable 等 |
+| 地址解析 | `address-parse` | 禁止引入其他地址解析库 |
+| 图片压缩 | `browser-image-compression` | 禁止引入其他压缩库 |
+| 颜色处理 | `chroma-js` | 禁止引入 color / polished 等 |
+| 事件总线 | `mitt`（项目封装 `src/utils/mitt.ts`） | 禁止引入 eventemitter3 等 |
+| 编辑页数据变更对比 | `v-compare` + `useCompareStore` + `ChangeSummaryService` / `ChangeSummaryDialog` | 禁止自研 Diff 组件树或第三方 diff UI；按 data-compare 模块 |
+
+---
+
+## 九、使用规则
+
+1. **先查后写**：生成任何功能代码前，必须先在本清单中查找是否已有对应的库/组件/Hook/工具
+2. **有则必用**：如果项目已有实现，必须直接使用，不得引入替代方案
+3. **无则上报**：如果确实需要引入新库（清单中没有），必须在输出中明确说明原因，并标注为"待确认"让用户审批
+4. **参考示例**：`src/views/` 下有对应功能的示例页面，应优先参考示例的代码模式
+5. **版本一致**：使用库的版本必须与清单中一致，不得降级或升级

package/references/qrcode-barcode.md

@@ -0,0 +1,92 @@
+# 二维码与条形码
+
+规范二维码/条形码生成组件的使用。在需要展示扫码、商品条码、票据二维码等场景时参照。
+
+## 组件选型
+
+| 场景                | 组件        | 底层库      |
+| ------------------- | ----------- | ----------- |
+| 二维码（支持 logo） | `ReQrcode`  | `qrcode`    |
+| 条形码              | `ReBarcode` | `jsbarcode` |
+
+## ReQrcode
+
+```vue
+<script setup lang="ts">
+import ReQrcode from "@/components/ReQrcode";
+import logoImg from "@/assets/logo.png";
+
+const text = ref("https://example.com");
+const logoUrl = ref(logoImg);
+
+function onDone(url: string) {
+  console.log("生成完成:", url);
+}
+</script>
+
+<template>
+  <ReQrcode :text="text" :width="200" @done="onDone" />
+
+  <!-- 带 logo / 颜色配置 -->
+  <ReQrcode
+    :text="text"
+    :logo="logoUrl"
+    :width="200"
+    :options="{
+      color: { dark: '#55D187', light: '#2d8cf0' },
+    }"
+    @click="text = ''"
+  />
+</template>
+```
+
+### Props
+
+| Prop       | 类型                     | 默认值     | 说明                        |
+| ---------- | ------------------------ | ---------- | --------------------------- |
+| `text`     | `string \| array`        | -          | 二维码内容                  |
+| `tag`      | `'canvas' \| 'img'`      | `'canvas'` | 渲染标签；`img` 不支持 logo |
+| `width`    | `number`                 | `200`      | 宽度（正方形）              |
+| `logo`     | `string \| object`       | -          | logo 地址或配置对象         |
+| `options`  | `QRCodeRenderersOptions` | `{}`       | qrcode.js 配置              |
+| `disabled` | `boolean`                | `false`    | 是否显示过期遮罩            |
+
+### Events
+
+- `done(url)`：生成完成返回 base64 URL。
+- `click`：点击二维码触发。
+- `disabled-click`：点击过期遮罩触发。
+
+## ReBarcode
+
+```vue
+<script setup lang="ts">
+import ReBarcode from "@/components/ReBarcode";
+
+const barcodeText = ref("HP12399300-12");
+const options = reactive({
+  lineColor: "#990000",
+  background: "#eee",
+});
+</script>
+
+<template>
+  <ReBarcode :text="barcodeText" />
+  <ReBarcode :text="barcodeText" type="EAN13" :options="options" />
+</template>
+```
+
+### Props
+
+| Prop      | 类型                         | 默认值      | 说明                                                         |
+| --------- | ---------------------------- | ----------- | ------------------------------------------------------------ |
+| `text`    | `string`                     | -           | 条形码内容                                                   |
+| `tag`     | `'canvas' \| 'img' \| 'svg'` | `'canvas'`  | 渲染标签                                                     |
+| `type`    | `string`                     | `'CODE128'` | 编码格式：`CODE128` / `CODE39` / `EAN13` / `EAN8` / `UPC` 等 |
+| `options` | `object`                     | `{}`        | JsBarcode 完整配置                                           |
+
+## 关键约定
+
+1. 二维码内容为空时不渲染，需配合 `v-if` 或默认值处理。
+2. logo 图片需考虑跨域；本地图片建议通过 `import` 引入。
+3. 条形码 `type` 与 `options.format` 同时存在时，`type` 优先级更高。

package/references/rich-text.md

@@ -0,0 +1,73 @@
+# 富文本编辑器
+
+规范 wangEditor 富文本编辑器 ReRichText 的使用，含图片/视频上传与 v-model 同步。在需要富文本录入时参照。
+
+## 组件
+
+使用 `ReRichText` 封装 `@wangeditor/editor`。
+
+```vue
+<script setup lang="ts">
+import ReRichText from "@/components/ReRichText";
+
+const content = ref("");
+const attachmentIds = ref<string[]>([]);
+</script>
+
+<template>
+  <ReRichText
+    v-model="content"
+    v-model:attachment-ids="attachmentIds"
+    :height="300"
+    placeholder="请输入内容"
+    :toolbar-config="{ excludeKeys: ['insertImage', 'insertVideo'] }"
+    :upload-params="{ bizKey: 'news_001', projectStage: 'draft' }"
+  />
+</template>
+```
+
+## Props
+
+| Prop              | 类型               | 默认值                                            | 说明             |
+| ----------------- | ------------------ | ------------------------------------------------- | ---------------- |
+| `modelValue`      | `string`           | `''`                                              | HTML 内容        |
+| `height`          | `string \| number` | `300`                                             | 编辑器高度       |
+| `placeholder`     | `string`           | `'请输入内容'`                                    | 占位文案         |
+| `disabled`        | `boolean`          | `false`                                           | 只读模式         |
+| `uploadImagePath` | `string`           | `'/documentInfo/uploadFile'`                      | 图片上传接口路径 |
+| `uploadVideoPath` | `string`           | `'/documentInfo/uploadFile'`                      | 视频上传接口路径 |
+| `bizKey`          | `string`           | `''`                                              | 业务主键         |
+| `projectStage`    | `string`           | `''`                                              | 附件阶段         |
+| `uploadParams`    | `object`           | `{}`                                              | 上传额外参数     |
+| `toolbarConfig`   | `object`           | `{ excludeKeys: ['insertImage', 'insertVideo'] }` | 工具栏配置       |
+
+## Events
+
+- `update:modelValue(html)`：内容同步。
+- `change(html)`：内容变化回调。
+
+## 上传模式
+
+当前启用 **自定义上传**（`customUpload`），通过项目统一 `getUploadUrl` 接口上传：
+
+```typescript
+// 关键参数
+{
+  multipartFile: file,
+  ...uploadParams,
+  bizKey,
+  projectStage,
+  attachmentType: 'news_image',
+  fileType: getFileType(file.name),
+  operatorCode: userStore.userCode || ''
+}
+```
+
+如需切换为 wangEditor 默认 server 模式，注释 `customUpload` 并开放 `server`、`customInsert` 等配置。
+
+## 关键约定
+
+1. 编辑器实例在 `onBeforeUnmount` 中销毁，避免内存泄漏。
+2. 空内容使用 `editor.isEmpty()` 判断，图片/视频等非文本场景也能正确处理。
+3. 上传成功后会将附件 ID 追加到 `attachmentIds`，用于业务关联。
+4. 全屏编辑时自动启用编辑器，退出后恢复 `disabled` 状态。

package/references/seamless-scroll.md

@@ -0,0 +1,38 @@
+# 无缝滚动
+
+规范无缝滚动、无限滚动列表与轮播滚动效果。在需要公告栏、排行榜、滚动列表时参照。
+
+## 组件
+
+使用 `ReSeamlessScroll` 实现无缝滚动：
+
+```vue
+<ReSeamlessScroll :data="list" :class-option="classOption">
+  <ul>
+    <li v-for="item in list" :key="item.id">
+      {{ item.title }}
+    </li>
+  </ul>
+</ReSeamlessScroll>
+```
+
+## 常用配置
+
+```typescript
+const classOption = {
+  step: 1, // 步长
+  limitMoveNum: 5, // 启动滚动的最小数据量
+  hoverStop: true, // 鼠标悬停停止
+  direction: "top", // top | bottom | left | right
+  singleHeight: 0, // 单步停顿高度
+  singleWidth: 0,
+  waitTime: 1000, // 单步停顿时间
+  autoPlay: true,
+};
+```
+
+## 关键约定
+
+1. 数据量小于 `limitMoveNum` 时不滚动。
+2. 水平滚动时内容需要足够宽；垂直滚动时容器需要固定高度。
+3. 组件内部会复制一份内容实现无缝效果，DOM 操作-heavy 场景避免数据频繁更新。

package/references/tree-table.md

@@ -0,0 +1,111 @@
+# 树形表格与树结构
+
+## 树结构工具函数
+
+### handleTree — 扁平转树
+
+```typescript
+import { handleTree } from '@/utils/tree'
+
+const treeData = handleTree(flatList, 'id', 'parentId', 'children')
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `data` | 扁平数组 | — |
+| `id` | ID 字段名 | `'id'` |
+| `parentId` | 父节点字段名 | `'parentId'` |
+| `children` | 子节点字段名 | `'children'` |
+
+### buildHierarchyTree — 补充层级信息
+
+```typescript
+import { buildHierarchyTree } from '@/utils/tree'
+
+const hierarchyTree = buildHierarchyTree(treeData, [])
+// 为每个节点补充 id、parentId、pathList 层级信息
+```
+
+## el-table 树形表格
+
+```vue
+<el-table
+  :data="tableData"
+  row-key="id"
+  default-expand-all
+  :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
+>
+  <el-table-column prop="name" label="名称" />
+  <el-table-column prop="code" label="编码" />
+</el-table>
+```
+
+## 树 + 表格联动
+
+左侧树形菜单 + 右侧查询表格的经典布局：
+
+```vue
+<script setup lang="ts">
+import TreeMenu from './tree.vue'
+
+const formQuery = reactive({ deptId: '', form1: '', form2: '' })
+const { onSearch } = useTableSearch(formQuery, getTableList)
+
+function onTreeSelect(value) {
+  formQuery.deptId = value.selected ? value.id : ''
+  onSearch()
+}
+</script>
+
+<template>
+  <el-row :gutter="20">
+    <el-col :span="5">
+      <TreeMenu @select="onTreeSelect" />
+    </el-col>
+    <el-col :span="19">
+      <!-- 查询表格 -->
+    </el-col>
+  </el-row>
+</template>
+```
+
+## ReTreeLine 树形连接线
+
+用于 `el-tree` 自定义节点，展示层级连线效果。
+
+```vue
+<script setup lang="ts">
+import { ReTreeLine } from '@/components/ReTreeLine'
+</script>
+
+<template>
+  <el-tree :data="treeData" :props="{ label: 'name' }">
+    <template #default="{ node, data }">
+      <ReTreeLine :node="node" :data="data" :tree-data="treeData">
+        <template #default>
+          <span>{{ node.label }}</span>
+        </template>
+      </ReTreeLine>
+    </template>
+  </el-tree>
+</template>
+```
+
+### 兼容性
+
+- 兼容 `el-tree` 与 `el-tree-v2`（虚拟树）。
+- 使用虚拟树时**必须**传入 `:tree-data` 属性。
+
+## 关键约定
+
+1. 后端返回扁平数据时，前端使用 `handleTree` 转换为树结构。
+2. 懒加载树通过 `:load` 属性实现，回写数据使用 `:cache-data`。
+3. 树节点选择事件需同时处理选中和取消选中两种状态，清空对应查询条件。
+4. 树表格的 `row-key` 必须指定唯一标识字段。
+5. `ReTreeLine` 的插槽用于自定义节点内容，外层由组件自动绘制连线。
+
+## 关联文件
+
+- [src/utils/tree.ts](file:///e:/work/vue3-web-temp/src/utils/tree.ts)
+- [src/components/ReTreeLine/index.ts](file:///e:/work/vue3-web-temp/src/components/ReTreeLine/index.ts)
+- [src/views/table/treeTable/index.vue](file:///e:/work/vue3-web-temp/src/views/table/treeTable/index.vue)