# backend-uniapp

**Repository Path**: meng_lingyun_admin/backend-uniapp

## Basic Information

- **Project Name**: backend-uniapp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时光列车（backend-uniapp）

> 基于 uni-app 的跨端移动应用，一套代码编译到 **App（Android / iOS）、H5、微信小程序** 等平台，内置管理端（用户 / 角色 / 组织 / 字典）与实时消息（MQTT）能力。

## 项目介绍

时光列车是一套使用 **uni-app（Vue2 语法，兼容 Vue3）** 开发的跨端前端项目，后端接口基于 HTTP + Bearer Token 认证对接，同时通过 **MQTT 协议** 实现实时消息推送（如公告、通知等），支持 H5 与 App 双端运行。

项目亮点：

- 跨端复用：同一套代码同时支持 App、H5、小程序，通过条件编译自动适配各端环境。
- 实时通信：内置基于 `mqtt@4.1.0` 的 MQTT 客户端封装（参考 [uniapp 在 app 下使用 mqtt 协议，支持 vue3](https://blog.csdn.net/u011096919/article/details/145837439)），支持订阅 / 取消订阅、断线自动重连、消息分发。
- 管理后台：内置用户、角色、组织、字典四大管理模块，支持列表分页与编辑。
- 工程化：HTTP 请求统一封装（GET / POST JSON / POST Form，动态 token），业务 API 按模块拆分，加密工具、路由、存储等工具齐备。

## 技术栈

| 类别 | 技术 |
| --- | --- |
| 框架 | uni-app（Vue 2 语法，兼容 Vue 3） |
| UI 组件库 | uView UI（uni_modules 版） |
| 样式 | Sass、Tailwind CSS（精简版 tailwind.min.scss） |
| 实时通信 | mqtt@4.1.0 |
| 工具库 | crypto-js（加解密）、gm-crypto（国密）、jsbn（大数运算 / RSA）、dayjs（时间处理） |

## 软件架构

```
backend-uniapp
├── App.vue                  # 应用入口（生命周期 + 全局样式）
├── main.js                  # 全局挂载（uView、Promise 适配）
├── manifest.json            # 应用配置（App / 小程序 / H5）
├── pages.json               # 页面路由与全局样式配置
├── pages/                   # 页面
│   ├── index/               # 首页
│   ├── login/               # 登录
│   ├── webview/             # 内嵌网页
│   ├── mine/                # 我的
│   ├── message/             # 消息（MQTT 实时消息展示）
│   └── manager/             # 管理端
│       ├── user/            # 用户管理（列表 + 编辑）
│       ├── role/            # 角色管理（列表 + 编辑）
│       ├── org/             # 组织管理（列表 + 编辑）
│       └── dict/            # 字典管理（列表 + 编辑）
├── components/              # 自定义组件（NavBar、TabBar、UserCard、XToast 等）
├── http/                    # 业务 API 模块（auth / user / role / org / dict / notice）
├── utils/                   # 工具库
│   ├── request.js           # HTTP 请求封装（动态 token、GET / POST JSON / POST Form）
│   ├── mqtt.js              # MQTT 客户端封装（订阅、重连、消息分发）
│   ├── crypto.js            # 加解密工具
│   ├── storage.js           # 本地存储封装
│   ├── router.js            # 路由跳转封装
│   └── system.js            # 系统信息工具
└── uni_modules/             # uni-app 插件市场组件（uview-ui）
```

## 安装教程

1. 使用 HBuilderX 导入项目（或 `git clone` 后使用命令行方式运行）。

2. 安装 npm 依赖（项目根目录执行）：

   ```bash
   npm install
   ```

3. 单独安装 MQTT 依赖（**建议锁定 4.1.0 版本**，避免打包空白问题）：

   ```bash
   npm install mqtt@4.1.0
   ```

4. 运行项目：

   - H5 端：HBuilderX 运行到浏览器，或 `npm run dev:h5`
   - App 端：HBuilderX 运行到手机 / 模拟器（或自定义基座）
   - 小程序端：HBuilderX 运行到微信开发者工具

## 使用说明

### 1. 接口地址配置

接口地址通过条件编译按端区分，位于 `utils/request.js`：

- **H5 端**：`/api`（走开发代理）
- **App 端**：`https://mengly.com.cn/backend-java`（生产接口）

请求头会动态读取本地存储的 `token` / `expireTime` 并携带 `Authorization: Bearer <token>` 认证。

### 2. 登录认证

进入登录页完成认证后，token 写入本地存储；所有业务请求（用户、角色、组织、字典、公告等）均通过 `http/` 下的模块调用，统一走 `utils/request.js` 封装。

### 3. MQTT 实时消息（核心能力）

项目参考 [《uniapp 在 app 下使用 mqtt 协议（支持 vue3）》](https://blog.csdn.net/u011096919/article/details/145837439) 实现 App 端 MQTT 通信，步骤如下：

#### 3.1 依赖版本

务必使用 `mqtt@4.1.0`：

```bash
npm install mqtt@4.1.0
```

#### 3.2 客户端封装

`utils/mqtt.js` 中封装了 `MQTTClient` 类，提供 `connect / subscribe / unsubscribe / destroy` 方法，并内置：

- 连接成功自动重订阅（`resubscribe`）
- 断线自动重连（5 秒重试，`scheduleReconnect`）
- 同一主题多回调的消息分发（`Map<topic, Set<callback>>`）

```js
import { mqttClient } from '@/utils/mqtt'

mqttClient.init()
mqttClient.subscribe('app_xxdg/topic', (msg) => {
  console.log('收到消息：', msg)
})
```

#### 3.3 全局挂载（可选）

在 `main.js` 中全局挂载 mqtt 模块，页面内直接使用：

```js
import mqtt from 'mqtt/dist/mqtt.js'
app.config.globalProperties.$mqtt = mqtt
```

#### 3.4 ⚠️ App 端打包空白修复（重要）

直接使用 mqtt 打包 App 会出现**白屏**问题。解决方法是修改依赖库源码：

1. 打开 `node_modules/mqtt/dist/mqtt.js`（注意是依赖库文件，不是自己创建的 `utils/mqtt.js`）；
2. 将源码中的 `wx.connectSocket` 修改为 `uni.connectSocket`；
3. 并在调用处补上 `complete: () => {}` 回调（避免部分平台缺少 complete 报错）。

#### 3.5 按端配置连接地址（条件编译）

```js
let ip = ''
// #ifdef H5
ip = 'ws://你的IP:8083/mqtt'
// #endif
// #ifdef APP-PLUS
ip = 'wx://你的IP:8083/mqtt'
// #endif

const client = this.$mqtt.connect(ip, {
  clientId: 'uni-app-' + Date.now(),
  keepalive: 60,
  clean: true,
  reconnectPeriod: 5000
})

client.subscribe('app_xxdg/topic', (err) => {
  if (!err) console.log('成功已订阅主题')
})

client.on('message', (topic, message) => {
  console.log('收到消息：', message.toString())
})
```

## 目录说明

| 模块 | 说明 |
| --- | --- |
| `pages/manager` | 管理端：用户、角色、组织、字典的列表与编辑 |
| `pages/message` | 消息页：展示 MQTT 实时推送内容 |
| `http/` | 按业务拆分的接口模块，统一走 request 封装 |
| `utils/mqtt.js` | MQTT 客户端封装（订阅 / 重连 / 消息分发） |
| `utils/crypto.js` | 加解密（crypto-js / gm-crypto / jsbn） |
| `components/` | 通用自定义组件 |

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 相关参考

- [uniapp 在 app 下使用 mqtt 协议（支持 vue3）—— CSDN](https://blog.csdn.net/u011096919/article/details/145837439)
- [uni-app 官方文档](https://uniapp.dcloud.net.cn/)
- [uView UI 文档](https://uviewui.com/)