SunAdmin 开发文档

主题

🖥️ Admin 总览 ​

Admin 位于 frontend/admin，是 Vue3 + TypeScript + Vite 管理后台。

🧫 技术栈 ​

类型依赖
UIElement Plus、@element-plus/icons-vue
状态Pinia
路由Vue Router 4
请求Axios
国际化vue-i18n
图表ECharts
富文本Tiptap
表格vxe-table
样式Sass、Tailwind CSS

🪛 目录结构 ​

text
src
├─ assets/                     图标、图片等静态资源
├─ components/                 通用组件
├─ config/                     项目配置
├─ enums/                      枚举
├─ error/                      错误页
├─ hooks/                      组合式函数
├─ install/                    插件安装入口
├─ lang/                       国际化
├─ layout/                     后台布局
├─ router/                     路由
├─ stores/                     Pinia
├─ styles/                     全局样式
├─ utils/                      请求、缓存、反馈、主题、工具函数
├─ views/System/               System 基础模块页面
└─ views/{Module}/             已安装模块发布的后台页面

🧬 System 页面模块 ​

src/views/System 包含：

目录说明
account登录页
apiSystem 模块 API 封装
article文章分类与文章管理
dashboard数据概览页
finance财务管理、退款中心
decoration页面装修设计器
integration支付、存储、微信、AI
language语言代码与翻译
media媒体库
message公告、短信
org部门、岗位
permission管理员、角色、菜单
setting系统配置、字典、协议、维护
user用户列表、详情、资料设置

已安装的模块会把模块自身的后台页面发布到 src/views/{Module}。

🕵️ 配置入口 ​

frontend/admin/src/config/index.ts：

字段当前值说明
terminal1终端类型
titleSunAdmin应用标题
version1.0.0请求头版本
baseUrlVITE_APP_BASE_URL接口域名
urlPrefixadminapi后台接口前缀
timeout10000请求超时

🧭 常用页面位置 ​

新增或排查 Admin 功能时，可按下表快速定位：

场景推荐位置
后台登录页src/views/System/account
控制台 / 仪表盘src/views/System/dashboard
全局布局、侧边栏、Tabssrc/layout
错误页（404、403、500）src/error
全局请求封装src/utils/request/index.ts
用户与权限 Storesrc/stores/modules/user.ts
路由表与动态路由生成src/router/index.ts
全局枚举 / 常量src/enums
通用复用组件src/components
国际化文案src/lang
模块运行包共享组件src/modules/runtime-shared.ts
已安装模块运行包入口注册src/modules/runtime-components.ts（由安装器生成）
模块装修链接选择器src/modules/app-links.ts（由安装器生成）

模块发布到 src/views/{Module} 的页面遵循同样约定：每个模块下通常会有 api/、component/、业务子目录和入口 index.vue / index.ts。具体业务字段、路由、组件挂载请优先参考已安装的 System 页面。

🧩 布局扩展点 ​

顶部 Toolbar ​

顶部导航栏支持模块动态注入自定义 Toolbar 组件。Header 在初始化时通过 import.meta.glob 自动扫描：

text
src/views/*/layout/toolbar.vue

只要模块将 toolbar.vue 发布到 src/views/{Module}/layout/，该组件就会被自动加载并渲染到顶部导航栏右侧（默认功能区左侧）。

示例结构：

text
frontend/admin/src/views/{Module}/
├─ layout/
│  └─ toolbar.vue      # 顶部工具栏（可选）
├─ api/
├─ component/
└─ index.vue

Toolbar 组件使用 defineAsyncComponent 异步加载，超时时间为 3 秒。组件内部可自由使用 Element Plus、Pinia 等全局能力。

在 publish-manifest.json 中，将 Admin 页面目录整体发布即可包含 layout/toolbar.vue：

json
{
  "files": [
    {
      "from": "admin/src/views/{Module}",
      "to": "frontend/admin/src/views/{Module}"
    }
  ]
}

数据源注册 ​

装修 DataPicker 组件支持模块动态注册自定义数据源。系统在初始化时通过 import.meta.glob 自动扫描：

text
src/views/**/component/data-source/index.ts

模块在该路径下导出数据源配置，DataPicker 即可在"数据源"下拉中列出该模块提供的选项。数据源模块通过 loadModules() 懒加载，仅在 DataPicker 打开时触发。

示例结构：

text
frontend/admin/src/views/{Module}/
├─ component/
│  └─ data-source/
│     └─ index.ts      # 数据源注册
├─ api/
└─ index.vue

移动端链接选择器 ​

装修链接选择器支持模块动态注册自定义链接类型。系统在初始化时通过 import.meta.glob 同步扫描：

text
src/views/**/component/mobile-link/index.ts

模块在该路径下导出链接类型配置（含 component 属性），链接选择器即可展示该模块提供的链接选项。

示例结构：

text
frontend/admin/src/views/{Module}/
├─ component/
│  └─ mobile-link/
│     └─ index.ts      # 链接类型注册
├─ api/
└─ index.vue

装修组件 ​

后台装修设计器的左侧组件面板会自动列出所有可用组件。组件来源有三种：

核心组件随 Admin 内置，位于 src/views/System/decoration/component/widgets/，按分类目录组织（basic 基础组件、commerce 营销组件）。每个组件是一个独立目录，包含 index.ts 入口。框架在启动时自动扫描该目录，无需手动注册。

模块组件在模块安装时由安装器写入 src/modules/decoration-widgets.ts。模块只需在自己的源码中提供组件，安装器会自动完成注册。注册内容包括模块分组信息（标题、排序）和组件列表。模块卸载时，对应条目会被清理。

运行包组件用于在生产环境安装模块后，无需重新build源码即可使用。模块通过 module:build-runtime 命令将装修组件构建成独立的 JS 包，装修系统在打开组件面板时按需加载，不需要把模块组件打进主 Admin 构建产物。

无论哪种来源，每个装修组件都需要提供：

导出用途
options()返回组件名称、标题和图标，决定在面板中如何展示
attr属性面板组件，负责右侧配置表单
content渲染面板组件，负责设计器中的可视化预览

组件面板按分组展示：核心组件按分类分组，模块组件按模块名分组并按配置的 order 排序。

扩展点汇总 ​

扩展点说明
顶部 Toolbar模块在 views/{Module}/layout/toolbar.vue 提供组件，自动渲染到导航栏
数据源模块在 views/{Module}/component/data-source/index.ts 注册，供装修 DataPicker 使用
移动端链接模块在 views/{Module}/component/mobile-link/index.ts 注册，供装修链接选择器使用
装修组件模块提供组件，安装器写入 decoration-widgets.ts；生产环境支持运行包按需加载

📦 运行包共享机制 ​

运行包（Runtime）是模块在生产环境下的远程页面包，通过 module:build-runtime 命令构建。运行包页面在浏览器中通过动态 import() 加载，不能使用主 Admin 的本地模块。为了让运行包也能访问 Vue、Element Plus 和项目共享组件，框架通过全局对象暴露这些能力。

共享入口 ​

text
src/modules/runtime-shared.ts

该文件在 Admin 启动时执行 registerAdminRuntimeShared()，将共享内容挂载到：

ts
window.__SUNADMIN_ADMIN_RUNTIME__

运行包可访问的内容 ​

分类内容
框架vue、vue-router、pinia
UIelement-plus、element-plus locale
请求request（Axios 封装）
反馈feedback（消息提示）
组合式函数usePaging、useFormData、useDictOptions、useDictData、useAppStore
组件AdminListShell、AdminSurfaceCard、DelWrap、Drawer、FooterBar、Icon、ImageView、MediaPicker、Pagination、Popup、UserPicker

运行包页面应通过 window.__SUNADMIN_ADMIN_RUNTIME__ 获取这些依赖，不要自行打包 Vue 或 Element Plus。