# RuoYi-App-Plus

**Repository Path**: pgz-tmp26/RuoYi-App-Plus

## Basic Information

- **Project Name**: RuoYi-App-Plus
- **Description**: RuoYi-App-Plus 是基于 uni-app + Vue3 的多端移动端项目，支持 H5、App、小程序，配套 RuoYi-Vue-Plus 后端，提供统一接口、加密通信与企业级业务能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: release
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 16
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<img src="./docs/images/project-logo-horizontal.png" width="340" alt="RuoYi App Plus"><br>

<strong>面向多端业务场景的 RuoYi 移动端解决方案</strong>

基于 uni-app、Vue 3、Vite 和 TypeScript 构建，配套 RuoYi-Vue-Plus 6.x 后端，统一支持 H5、App、微信小程序及其他小程序平台。

`多端统一`　 `接口加密`　 `登录鉴权`　 `约定式路由`　 `分包优化`

</div>

---

## 项目简介

RuoYi App Plus 是 RuoYi-Vue-Plus 的移动端前端项目。项目基于 **unibest** 工程模板重构，在保留 uni-app 多端能力的基础上，整合了登录鉴权、用户中心、工作台、接口加密、状态持久化、约定式路由和分包加载等常用能力。

同一套业务代码可以运行在 H5、App 和小程序环境中。项目已提供标准化请求层、环境配置、页面布局及常见业务页面，适合作为移动端管理系统和企业应用的开发基础。

> [!IMPORTANT]
> 本项目需要配合 RuoYi-Vue-Plus 后端使用。开始联调前，请确认接口地址、`clientId`、接口加密开关和 RSA 密钥与后端配置一致；生产环境请替换示例地址、AppID 和相关密钥，避免提交真实敏感信息。

## 核心能力

| 能力 | 说明 |
| --- | --- |
| 多端运行 | 一套代码支持 H5、App、微信小程序及其他小程序平台 |
| 登录鉴权 | 统一维护 token 和用户状态，启动时验证会话，失效后重新登录 |
| 接口通信 | 封装 `uni.request`，统一处理请求头、错误提示、超时和响应数据 |
| 安全加密 | 支持 RSA + AES 接口加解密，并与 RuoYi-Vue-Plus 后端协议配套 |
| 工程能力 | 提供约定式路由、布局系统、自动导入、类型声明和环境变量管理 |
| 性能优化 | 支持主包、业务分包、异步跨包调用及组件按需加载 |
| UI 与样式 | 集成 uview-plus、uni_modules、UnoCSS 和 Sass |

## 技术栈

| 分类 | 技术 |
| --- | --- |
| 工程模板 | unibest（`v4.4.0`） |
| 多端框架 | uni-app |
| 前端框架 | Vue 3 |
| 开发语言 | TypeScript、JavaScript |
| 构建工具 | Vite 5 |
| 状态管理 | Pinia、pinia-plugin-persistedstate |
| UI 组件 | uview-plus、uni_modules |
| 样式方案 | UnoCSS、Sass |
| 请求封装 | uni.request |
| 加密能力 | crypto-js、jsencrypt |
| 包管理器 | pnpm |

## 关于 unibest

[unibest](https://unibest.tech/) 是 uniapp + Vue3 + Vite5 + TypeScript + UnoCSS + Pinia 组合的最佳实践工程模板，提供约定式路由、布局系统、自动导入、代码片段等开箱能力。仓库地址：`https://github.com/feige996/unibest`（原 `codercup/unibest` 已迁移）。

本项目由 unibest `v4.4.0` 模板重构而来，保留了模板的核心工程能力：

| unibest 能力 | 本项目的落地 |
| --- | --- |
| 约定式路由 | `pages.config.ts` + 页面 SFC 内 `definePage`，自动生成 `pages.json`，无需手写 |
| 清单配置 | `manifest.config.ts` 自动生成 `manifest.json` |
| 布局系统 | `src/layouts` + `vite-plugin-uni-layouts`，页面通过 `definePage` 指定布局 |
| 样式方案 | UnoCSS（`uno.config.ts`）、Sass，图标使用 `@iconify-json/carbon` |
| 自动导入 | `unplugin-auto-import` 自动导入 Vue / uni-app API 与 `src/hooks`；`vite-plugin-uni-components` 自动注册组件 |
| 分包优化 | `@uni-ku/bundle-optimizer` 分包优化与异步跨包调用 |

其余为 RuoYi 业务定制：uview-plus UI、z-paging 列表加载、`src/http` 请求封装（接口加密、token / clientid 拦截、openapi-ts-request 适配）、`src/api` 接口层、`src/pages-mine` / `src/pages-common` 分包等。

uni-app 编译链当前锁定 `3.0.0-5020420260813003`（2026-08 alpha 线），可通过 `pnpm uvm` 升级 uni-app 版本。

### unibest 工程约定

- 页面路由：页面放入 `src/pages`（主包）、`src/pages-mine` / `src/pages-common`（分包），在 SFC 中用 `definePage` 声明标题、导航栏、布局等，路由配置自动生成。
- 新增页面后需重启开发服务，使页面配置重新生成。
- VS Code 中可按 unibest 文档安装配套插件，`.vue` 文件输入 `v3` 可生成常用代码片段。

## 环境要求

| 工具 | 要求 |
| --- | --- |
| Node.js | `>=20`，项目 `.nvmrc` 为 `v22` |
| pnpm | `>=9` |

版本配置位于 `package.json`。

## 目录结构

```text
.
├── env                     # 环境变量
├── scripts                 # 辅助脚本、微信上传脚本
├── src
│   ├── api                 # 后端接口
│   ├── components          # 公共组件
│   ├── hooks               # hooks
│   ├── http                # 请求封装与拦截
│   ├── layouts             # 布局
│   ├── pages               # 主包页面
│   ├── pages-common        # 通用分包
│   ├── pages-mine          # 我的分包
│   ├── plugins             # 全局插件
│   ├── static              # 静态资源
│   ├── store               # Pinia 状态
│   ├── style               # 全局样式
│   ├── types               # 类型声明
│   ├── uni_modules         # uni_modules 组件
│   └── utils               # 工具函数
├── manifest.config.ts
├── pages.config.ts
├── vite.config.ts
└── README.md
```

## 页面结构

主包页面：

| 页面 | 说明 |
| --- | --- |
| `src/pages/index/index.vue` | 首页 |
| `src/pages/login/index.vue` | 登录 |
| `src/pages/register/index.vue` | 注册 |
| `src/pages/work/index.vue` | 工作台 |
| `src/pages/mine/index.vue` | 我的 |

我的分包：

| 页面 | 说明 |
| --- | --- |
| `src/pages-mine/info/index.vue` | 个人信息 |
| `src/pages-mine/info/edit.vue` | 编辑资料 |
| `src/pages-mine/avatar/index.vue` | 修改头像 |
| `src/pages-mine/pwd/index.vue` | 修改密码 |
| `src/pages-mine/setting/index.vue` | 设置 |
| `src/pages-mine/help/index.vue` | 帮助 |
| `src/pages-mine/about/index.vue` | 关于 |

通用分包位于：

```text
src/pages-common
```

页面通过 SFC 内的 `definePage` 自动生成路由配置，不再手写维护根目录 `pages.json`。

## 环境变量

环境变量目录：

```text
env
```

| 文件 | 说明 |
| --- | --- |
| `env/.env` | 通用环境变量 |
| `env/.env.development` | 开发环境 |
| `env/.env.test` | 测试环境 |
| `env/.env.production` | 生产环境 |

常用变量：

| 变量 | 说明 |
| --- | --- |
| `VITE_SERVER_BASEURL` | 后端主接口地址 |
| `VITE_SERVER_BASEURL_SECONDARY` | 后端备用接口地址 |
| `VITE_APP_PROXY_ENABLE` | H5 是否启用本地代理 |
| `VITE_APP_PROXY_PREFIX` | H5 代理前缀 |
| `VITE_APP_PORT` | H5 开发服务端口 |
| `VITE_DELETE_CONSOLE` | 构建时是否移除 console/debugger |
| `VITE_SHOW_SOURCEMAP` | 是否输出 sourcemap |
| `VITE_SERVER_BASEURL_WEIXIN_DEVELOP` | 微信开发版接口地址 |
| `VITE_SERVER_BASEURL_WEIXIN_TRIAL` | 微信体验版接口地址 |
| `VITE_SERVER_BASEURL_WEIXIN_RELEASE` | 微信正式版接口地址 |
| `VITE_APP_SITE_URL` | 应用官网地址 |
| `VITE_APP_PRIVACY_URL` | 隐私政策地址 |
| `VITE_APP_AGREEMENT_URL` | 用户协议地址 |

开发环境默认后端地址：

```text
http://127.0.0.1:8080
```

生产环境默认使用占位地址：

```text
https://api.example.com/prod-api
```

实际部署时需要替换为自己的后端地址。

## 应用配置

应用级配置位于：

```text
src/config.js
```

| 配置 | 说明 |
| --- | --- |
| `baseUrl` | 读取 `VITE_SERVER_BASEURL` |
| `clientID` | 后端客户端标识 |
| `appEncrypt` | 是否启用接口加密 |
| `rsaPublicKey` | 请求加密公钥 |
| `rsaPrivateKey` | 响应解密私钥 |

后端默认开启接口加密，前端客户端标识和 RSA 密钥需要与后端配置保持一致。

接口地址、小程序 AppID、协议链接等发布环境信息请在环境变量中填写。

## 请求封装

| 文件 | 说明 |
| --- | --- |
| `src/http/http.ts` | uni.request 封装、接口加密、响应解密、错误处理 |
| `src/http/interceptor.ts` | 请求拦截器，处理 token、clientid 等请求头 |
| `src/http/types.ts` | 请求类型 |
| `src/http/vue-query.ts` | openapi-ts-request 适配 |
| `src/utils/request.js` | 兼容 RuoYi 风格接口调用 |
| `src/utils/jsencrypt.ts` | RSA 加解密 |
| `src/utils/crypto.ts` | AES / Base64 工具 |

## 本地运行

```bash
# 安装依赖
pnpm install

# H5
pnpm dev:h5

# App
pnpm dev:app

# 微信小程序
pnpm dev:mp-weixin
```

## 常用脚本

| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 默认开发 |
| `pnpm dev:h5` | H5 开发 |
| `pnpm dev:app` | App 开发 |
| `pnpm dev:mp-weixin` | 微信小程序开发 |
| `pnpm build:h5` | H5 构建 |
| `pnpm build:app` | App 构建 |
| `pnpm build:mp-weixin` | 微信小程序构建 |
| `pnpm upload:mp` | 微信小程序上传 |
| `pnpm type-check` | 类型检查 |
| `pnpm lint` | 代码检查 |
| `pnpm lint:fix` | 自动修复部分 lint 问题 |

## 与后端联调

1. 启动后端 `RuoYi-Vue-Plus`，默认端口 `8080`。
2. 确认 `env/.env.development` 中 `VITE_SERVER_BASEURL=http://127.0.0.1:8080`。
3. 确认 `src/config.js` 中 `clientID`、`appEncrypt`、RSA 密钥与后端一致。
4. 根据目标平台启动 H5、App 或小程序开发命令。

### H5 代理

H5 是否启用代理由环境变量控制：

```text
VITE_APP_PROXY_ENABLE
```

启用代理时，代理规则位于：

```text
vite.config.ts
```

App 和小程序端通常不走 Vite devServer 代理，而是直接使用环境变量中的后端地址。

## 开发前检查清单

首次接手或换机器开发时，建议先确认：

1. Node.js 是否满足项目要求，建议按 `.nvmrc` 使用 Node 22。
2. pnpm 是否满足 `>=9`。
3. 是否在仓库根目录执行命令。
4. 后端是否启动，默认端口是否为 `8080`。
5. 当前运行平台是 H5、App 还是小程序。
6. 对应环境变量中的后端地址是否能被当前平台访问。
7. `src/config.js` 中 `clientID`、`appEncrypt`、RSA 密钥是否与后端一致。
8. 小程序端是否配置了合法请求域名。

## 新增页面流程

本项目使用 `definePage` 约定式页面配置。新增页面时推荐：

1. 确认页面属于主包还是分包。
2. 主包页面放入 `src/pages`。
3. 我的模块相关页面放入 `src/pages-mine`。
4. 通用可复用页面放入 `src/pages-common`。
5. 在 Vue SFC 中使用 `definePage` 配置页面标题、样式、导航栏等。
6. 如页面需要出现在底部 Tab 或入口宫格中，同步修改对应组件或页面入口。
7. 页面请求接口统一放入 `src/api`，不要直接在页面中散落请求路径。

主包适合放启动后高频访问的核心页面；分包适合放个人中心、设置、详情、低频工具页，以控制首包体积。

## 接口开发流程

新增接口建议放在：

```text
src/api/<module>
```

旧版 RuoYi 风格接口通常通过：

```text
src/utils/request.js
```

新版请求能力集中在：

```text
src/http
```

开发接口时需要确认：

| 项 | 说明 |
| --- | --- |
| 请求路径 | 与后端 Controller 保持一致 |
| 请求方式 | GET / POST / PUT / DELETE 要匹配 |
| token | 登录后由拦截器自动携带 |
| clientid | 由拦截器自动携带 |
| 加密 | POST/PUT 且配置开启时会走加密 |
| 错误提示 | 统一由请求封装处理，页面只处理业务态 |
| 文件上传 | 使用项目现有上传工具 |

页面中尽量只调用语义化 API 方法，例如 `getUserInfo()`、`updatePassword()`，不要直接写 `http.post('/xxx')`。

## 登录态与权限

移动端登录相关能力涉及：

| 文件 / 目录 | 说明 |
| --- | --- |
| `src/pages/login/index.vue` | 登录页面 |
| `src/api/login.js` | 登录、注册、验证码等接口 |
| `src/store/token.ts` | token、clientId 等登录态 |
| `src/http/interceptor.ts` | 请求头注入、登录态处理 |
| `src/pages/mine` | 我的页面，通常展示用户信息和入口 |

常见登录流程：

1. 用户进入登录页。
2. 获取验证码或其他登录前置数据。
3. 调用登录接口，携带 `clientId`。
4. 保存 token、用户信息或客户端信息。
5. 后续请求由拦截器自动携带 `Authorization` 和 `clientid`。
6. token 失效时跳转登录页或提示重新登录。

## 多端差异说明

| 平台 | 重点 |
| --- | --- |
| H5 | 可使用 Vite 本地代理，适合快速联调 |
| App | 后端地址需要手机或模拟器可访问，注意文件、权限、原生插件 |
| 微信小程序 | 需要合法域名，部分 Web API 不可用，包体积限制更明显 |
| 其他小程序 | 关注平台 API 差异、登录能力和上传发布流程 |

不要假设 H5 能跑通就代表 App 和小程序都无问题。涉及上传、下载、扫码、定位、权限、文件系统、分享等能力时，需要按目标平台单独验证。

## 开发指引

| 需求 | 推荐位置 |
| --- | --- |
| 新增接口 | `src/api` |
| 新增主包页面 | `src/pages` |
| 新增我的分包页面 | `src/pages-mine` |
| 新增通用分包页面 | `src/pages-common` |
| 修改登录 | `src/pages/login/index.vue` |
| 修改个人中心 | `src/pages/mine`、`src/pages-mine` |
| 修改请求逻辑 | `src/http/http.ts`、`src/http/interceptor.ts` |
| 修改接口地址 | `env/.env.*` |
| 修改客户端标识 / 加密配置 | `src/config.js` |
| 修改页面配置 | `pages.config.ts` |
| 修改应用配置 | `manifest.config.ts` |
| 修改构建配置 | `vite.config.ts` |
| 修改样式 | `src/style`、`uno.config.ts` |

## 常见问题排查

### H5 能访问，App 或小程序访问失败

通常是地址可达性问题。检查：

1. `127.0.0.1` 在手机或小程序环境中指向的不是电脑。
2. 后端是否绑定到局域网可访问地址。
3. 手机和电脑是否在同一网络。
4. 防火墙是否放行后端端口。
5. 小程序是否配置合法请求域名。

### 登录失败或提示加密异常

检查：

1. `src/config.js` 中 `clientID` 是否与后端一致。
2. `appEncrypt` 是否与后端 `api-decrypt.enabled` 匹配。
3. RSA 公私钥是否与后端配置配套。
4. 请求头中是否带有 `clientid`。
5. 后端验证码是否开启，前端参数是否完整。

### 页面新增后没有路由

检查：

1. 页面是否放在 `src/pages`、`src/pages-mine` 或 `src/pages-common` 下。
2. SFC 中是否正确使用 `definePage`。
3. `vite.config.ts` 中 UniPages 插件的分包配置是否覆盖该目录。
4. 是否需要重启开发服务使页面配置重新生成。

### 小程序包体积过大

优化方向：

1. 将低频页面放入分包。
2. 避免在主包引入大型依赖。
3. 组件按需引入。
4. 图片资源压缩后再放入项目。
5. 对平台专属代码使用条件编译。

## 多端注意事项

1. H5 开发可使用本地代理，也可直连后端。
2. App、小程序端通常需要后端地址为局域网或公网可访问地址。
3. 微信小程序需要配置合法请求域名。
4. App 端原生插件资源复制逻辑位于 `vite-plugins` 和 `vite.config.ts`。
5. 小程序开发工具自动打开逻辑受脚本与环境变量控制。

## 部署说明

构建前需要确认：

1. 生产环境后端地址已经替换。
2. 客户端标识与后端生产配置一致。
3. RSA 密钥与后端生产配置一致。
4. 小程序合法域名、App 权限、manifest 配置已按目标平台调整。

构建参考：

```bash
pnpm build:h5
pnpm build:app
pnpm build:mp-weixin
```

## 注意事项

1. 本项目依赖 uni-app 多端编译链，不同平台的运行和构建行为不同。
2. 开发环境默认后端地址为 `http://127.0.0.1:8080`。
3. 生产环境不要使用示例接口地址或示例 AppID。
4. 不要提交小程序上传私钥、证书、生产密钥、真实后端地址等敏感信息。
5. 提交前注意检查 `node_modules`、本地 IDE 配置、构建产物和生成文件。

## 界面预览

| 登录 | 首页 | 工作台 |
| --- | --- | --- |
| <img src="docs/images/screenshot-login.png" width="220" alt="登录"> | <img src="docs/images/screenshot-home.png" width="220" alt="首页"> | <img src="docs/images/screenshot-workbench.png" width="220" alt="工作台"> |

| 我的 | 个人信息 | 编辑资料 |
| --- | --- | --- |
| <img src="docs/images/screenshot-mine.png" width="220" alt="我的"> | <img src="docs/images/screenshot-profile.png" width="220" alt="个人信息"> | <img src="docs/images/screenshot-profile-edit.png" width="220" alt="编辑资料"> |