# Nexus-App

**Repository Path**: wingxh/nexus-app

## Basic Information

- **Project Name**: Nexus-App
- **Description**: 覆盖ERP、MES传统功能的APP，实现销售、采购、仓库、生产、报工、OCR识别等功能，含有内部聊天通信、审批流、打卡定位等基本功能。加入AI模块，通过AI决策辅助办公。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/NexusERP/nexus-erp
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 14
- **Created**: 2026-10-14
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img alt="NexusERP logo" src="static/logo.png" width="120" />
</p>

# NexusERP 移动端

基于 **uni-app + Vue 3 + Pinia** 的企业移动应用，为 NexusERP 提供 ERP、MES、工作流审批、即时通讯、AI 助手与通知中心入口。项目由 RuoYi-App 深度定制而来，面向 Android、iOS、H5 和微信小程序；各平台的原生能力按实际支持情况适配。

## 功能概览

| 模块           | 当前前端功能                                                                      |
| -------------- | --------------------------------------------------------------------------------- |
| 首页与工作台   | 数据概览、权限控制的业务入口、常用应用、最近使用、扫码和全局搜索                  |
| 基础资料       | 供应商、客户管理及物料查询接口                                                    |
| 采购           | 请购、采购订单、采购合同、采购退货、供应商评价                                    |
| 销售           | 客户订单、报价、销售合同、销售退货                                                |
| 仓储           | 库存、收货入库、出库、调拨、盘点、预警、扫码与 PDA 收货接口                       |
| ERP 生产       | 生产工单、报工、返工与生产统计                                                    |
| 考勤           | 定位打卡、排班、考勤记录、补卡、外出打卡、请假及人脸照片采集                      |
| 财务           | 应收应付、收付款、结算、固定资产、折旧、处置、凭证、科目与期间                    |
| MES 生产执行   | 工单、派工、流转卡、SN、正反向追溯、制造 BOM、安灯                                |
| MES 设备与质量 | 设备、维修、保养、巡检、IQC/IPQC/OQC、数据采集与 SPC                              |
| 工作流审批     | 待办、已办、我发起、流程发起、审批操作及流程图查看                                |
| 即时通讯       | 私聊、群聊、联系人、好友申请、已读、撤回、转发、回复、搜索、收藏、置顶和免打扰    |
| AI 助手        | 会话管理、模型选项、流式回复、提示词、消息反馈、工具/来源展示、交付风险决策与审批 |
| 视觉识别       | 拍照上传、产品标签 OCR 识别与收货信息辅助校验                                     |
| 通知与个人中心 | 通知分页/已读/点击跳转、App 本地通知、公告、资料、协议、设置与账号安全            |

业务功能依赖配套后端的接口、权限、字典及租户配置，接口定义集中在 `api/`。历史规划与接口缺口可从 [文档导航](docs/README.md) 查阅，对接时以当前前后端实现为准。

## 技术与架构

| 领域       | 实现                                                                             |
| ---------- | -------------------------------------------------------------------------------- |
| 应用框架   | uni-app、Vue 3 `createSSRApp`，新页面采用 Composition API 与 `<script setup>`    |
| 状态管理   | Pinia，按 ERP、MES、IM、AI、审批、通知等业务域划分                               |
| UI 与样式  | uni-ui、通用/业务组件、SCSS 设计变量、NxIcon 图标体系                            |
| 请求与认证 | `uni.request` 适配层、共享请求核心、Bearer Token、客户端 ID、角色/权限与协议守卫 |
| 实时通信   | IM WebSocket、消息缓存与离线发送队列；AI 使用 SSE                                |
| 构建       | HBuilderX 官方 uni-app 工具链，Vite 配置解析配套 Vue/Pinia 运行库                |
| 检查与测试 | ESLint 9、Prettier、Vitest、Playwright、Husky、lint-staged 与审计脚本            |

普通 JSON 请求入口为 `utils/request/request.js`，IM 接口通过 `api/im/request.js` 统一处理字符串 ID。`utils/core/` 是 nexus-client-core 的同步副本，本项目通过适配层注入配置、认证和错误处理。

页面采用主包与业务分包组织，四个 tab 为 **首页、工作台、消息、我的**。业务接口包含 `/app/*`、`/erp/*`、`/mes/*`、`/workflow/*`、`/im/*`、`/ai/*`、`/cv/*`、`/system/*` 等前缀，不能把所有接口统一假定为 `/app/*`。

## 项目结构

```text
├── api/                         # 认证、协议、通知及按域划分的接口/枚举
│   ├── bd/ pu/ so/ wm/ prd/     # 主数据、采购、销售、仓储、ERP 生产
│   ├── sch/ fin/                # 考勤、财务
│   ├── mes/                    # pro、eq、qc、dc、spc
│   └── wf/ im/ ai/ cv/ system/  # 审批、IM、AI、视觉识别、系统
├── pages/
│   ├── index.vue / work/       # 首页与工作台
│   ├── im/ mine/ login/        # 消息、我的与登录/注册
│   ├── erp/                    # bd、pu、so、wm、prd、sch、fin 业务页面
│   ├── mes/ wf/ ai/            # MES、审批与 AI 页面
│   └── notification/ system/ common/
├── components/                 # common、business、third-party 与平台相关组件
├── composables/                # usePaginatedList.js 通用分页管理
├── store/modules/              # Pinia 仓库；IM 拆分于 im/，im.js 保留兼容导出
├── utils/
│   ├── request/ core/          # 请求/下载适配与共享核心
│   ├── im/ notification/       # IM 缓存/提醒与 App 通知生命周期
│   ├── ai/ wf/ format/         # SSE、Markdown、BPMN 与格式化
│   └── websocket.js / location.js
├── static/                     # 图片、字体、图标与全局 SCSS
├── scripts/                    # 图标生成、审计、HBuilderX 工具链与编译验证
├── tests/ / e2e/               # 单元测试与 Playwright 用例
├── docs/                       # 分类文档与历史记录
├── App.vue / main.js           # 应用生命周期与入口
├── config.js / permission.js   # 环境配置、认证及协议路由守卫
├── pages.json / manifest.json  # 页面分包、tabBar、权限与版本
├── vite.config.js / uni.scss   # 构建配置与设计变量
└── AGENTS.md                   # 仓库开发指导
```

## 开发环境

- **HBuilderX**：安装官方 uni-app 编译插件，用于开发运行、发行和编译验证。
- **Node.js**：建议使用 Node.js 24；完整开发工具链按当前依赖要求使用 `>=22.22.1`。`package.json` 声明的 `>=18` 低于当前 lint-staged 17.3 的实际要求。
- **配套 NexusERP 后端**：准备对应业务接口、租户、客户端、测试用户及权限；AI、视觉识别和工作流还需要后端相应服务配置。
- **目标平台工具**：按需准备 Android/iOS 设备或模拟器、微信开发者工具。

### 1. 获取项目与安装开发依赖

```bash
git clone https://gitee.com/helloworld_wh18/nexus-app.git
cd nexus-app
npm install
```

npm 依赖用于检查、测试和资源生成；应用运行库由 HBuilderX 工具链提供。仓库当前没有 `dev:h5`、`build:h5` npm 脚本，H5 开发通过 HBuilderX 启动。

### 2. 配置后端

在 [config.js](config.js) 的 `envConfig` 中分别配置开发与生产地址。例如：

```js
const envConfig = {
  development: { baseUrl: 'http://localhost:8080' },
  production: { baseUrl: 'https://your-domain.example/prod-api' }
}
```

HBuilderX「运行」注入 `NODE_ENV=development`，「发行」和编译验证使用生产模式。环境选择依据构建模式，不依赖 H5 页面 hostname；编译验证默认使用生产配置。

- 浏览器与后端位于同一台机器时可以使用 `localhost`；真机和模拟器应使用设备可访问的后端地址。
- 核对 `appClientId` 与后端客户端配置，保持 `appInfo.version`、`package.json` 和 `manifest.json` 版本一致。
- 反向代理需按现有接口保留路径，同时支持 WebSocket 和 AI 事件流 `/resource/sse`。

### 3. 使用 HBuilderX 运行

1. 在 HBuilderX 中导入项目目录。
2. 通过「运行」选择浏览器、App 真机/模拟器或微信小程序。
3. 发行时选择相应平台，并检查 `manifest.json` 的应用标识、权限、原生模块和平台配置。

H5 端口在 `manifest.json` 的 `h5.devServer.port` 中配置，当前为 **9090**，访问地址通常为 `http://localhost:9090`。

### 4. 使用官方工具链编译验证

仓库提供 [scripts/verify-build.mjs](scripts/verify-build.mjs)，支持 H5 与 App 的生产模式编译验证。PowerShell 示例：

```powershell
# 替换为本机 HBuilderX 安装目录
$env:HBUILDERX_PATH = 'C:\Tools\HBuilderX'
node scripts/verify-build.mjs --platform h5
node scripts/verify-build.mjs --platform app
```

也可以使用 `--hbuilderx <安装目录>`；默认产物位于 `unpackage/verify/h5` 和 `unpackage/verify/app`，使用 `--output <目录>` 可指定输出位置。

`vite.config.js` 通过 `scripts/runtime-toolchain.mjs` 解析官方工具链。HBuilderX 运行环境使用 `UNI_HBUILDERX_PLUGINS` 或 `HX_APP_ROOT` 定位插件目录，验证脚本会自动设置。App 编译验证产生编译资源，安装包生成与设备运行继续通过 HBuilderX 完成。

## 常用命令与测试

| 命令                                       | 用途                                     |
| ------------------------------------------ | ---------------------------------------- |
| `npm run lint` / `npm run lint:fix`        | ESLint 检查 / 自动修复                   |
| `npm run format:check` / `npm run format`  | Vue、JS、TS、样式和 JSON 格式检查 / 写入 |
| `npx prettier --check AGENTS.md README.md` | 检查仓库入口 Markdown 文档格式           |
| `npm test` / `npm run test:watch`          | Vitest 单元测试 / 监听模式               |
| `npm run e2e:install`                      | 安装 Playwright Chromium                 |
| `npm run e2e` / `npm run e2e:ui`           | 端到端测试 / UI 调试                     |
| `npm run audit:pages`                      | 页面质量报告                             |
| `npm run audit:enums`                      | 对照后端语料检查枚举漂移                 |
| `npm run iconfont` / `npm run icons:nexus` | 生成图标字体 / Nexus 图标资源            |
| `npm run icons:audit`                      | 图标审计                                 |

单元测试集中在 `tests/unit/`，通过 `tests/setup.js` 提供 uni API mock；组件测试使用 happy-dom。可执行 `npm test -- tests/unit/runtime-toolchain.spec.js` 运行特定用例。

页面审计与枚举审计输出报告，退出码为 0 不表示没有问题。枚举审计默认查找同级 `../nexus-erp`，也可显式指定：

```bash
npm run audit:enums -- --backend=../nexus-erp
```

Playwright 配置位于 [playwright.config.js](playwright.config.js)，不会自动启动 H5 或后端服务。运行前准备测试账号和群组；其默认 H5 地址为 5173，与当前 manifest 的 9090 不同，需要覆盖：

```powershell
$env:E2E_BASE_URL = 'http://localhost:9090'
$env:E2E_APP_BASE = $env:E2E_BASE_URL
$env:E2E_USER_A = 'your-test-user-a'
$env:E2E_USER_A_PWD = 'your-test-password-a'
$env:E2E_USER_B = 'your-test-user-b'
$env:E2E_USER_B_PWD = 'your-test-password-b'
$env:E2E_GROUP_ID = 'your-test-group-id'
npm run e2e
```

IM 用例的后端与 WebSocket 地址可通过 `E2E_API_BASE`、`E2E_WS_BASE` 覆盖。流程图用例独立使用 `E2E_APP_BASE`（默认 9091），并需要配置 `E2E_WF_PHONE`、`E2E_WF_PROC_INS_ID`、`E2E_WF_TASK_ID` 对应的测试数据；前置条件缺失会跳过测试，运行时需核对实际执行与跳过数量。

## 平台能力与验证范围

- **定位与相机**：考勤定位、人脸照片和标签识别依赖目标平台权限及后端校验；H5、App、小程序的授权入口存在差异。
- **AI 流式回复**：当前 SSE 工具在 H5 使用 EventSource，在 App 使用 HTML5+ `XMLHttpRequest` 进度流；其他平台需确认可用的传输能力。
- **App 通知**：WebSocket 收到 `USER_NOTIFICATION` 后创建本地系统通知，依赖安装包中的 Push 模块与系统通知权限。H5 使用 Toast 提醒。
- **后台与冷启动**：进程结束或 JS/WebSocket 被系统挂起时无法继续接收新事件；已创建的本地通知点击可进入启动后的路由队列。当前实现没有接入设备 token 注册或远程云推送服务。
- **设备验收**：通知栏、权限弹窗、锁屏、定位、相机和真实冷启动需真机验证；单元测试及编译验证只覆盖各自范围。

详细通知设计与验收记录见 [App 本地通知与点击路由](docs/04-变更记录/2026-10-12-App本地通知与点击路由.md)。

## 开发文档

全部索引见 [docs/README.md](docs/README.md)，文档按架构规范、接口、开发规划、变更记录、测试用例和历史归档分类。

| 文档                                                                       | 用途                               |
| -------------------------------------------------------------------------- | ---------------------------------- |
| [仓库开发指导](AGENTS.md)                                                  | 目录、请求/状态/路由约定和验证要求 |
| [UI 设计规范](docs/01-架构与规范/UI设计规范.md)                            | 设计变量、组件与页面规范           |
| [架构分析报告](docs/01-架构与规范/架构分析报告.md)                         | 架构背景与演进建议                 |
| [接口状态与后端缺口清单](docs/02-接口文档/接口状态与后端缺口清单.md)       | 接口对接背景与缺口记录             |
| [MES 接口契约核实](docs/02-接口文档/MES生产执行接口契约核实-2026-09-12.md) | MES 参数、状态与响应契约核查       |
| [开发路线图](docs/03-开发规划/开发路线图.md)                               | 阶段目标与历史规划                 |
| [IM 模块升级总结](docs/04-变更记录/IM模块P0-P6升级总结.md)                 | IM 变更与回归记录                  |
| [核心流程测试用例](docs/05-测试用例/核心流程测试用例.md)                   | 业务流程测试参考                   |

部分文档是历史计划或阶段总结，功能现状以仓库代码为准。

## 贡献与许可证

提交修改前参考 [AGENTS.md](AGENTS.md)，执行与修改范围相符的检查，并说明平台、验证结果和未验证范围。接口、路由或运行方式发生变化时同步更新文档。

本项目使用 [MIT License](LICENSE)。

- 原始版权：Copyright (c) 2022 若依。
- NexusERP 二次开发：Copyright (c) 2026 NexusERP。