# Nexus-PDA
**Repository Path**: NexusERP/nexus-pda
## Basic Information
- **Project Name**: Nexus-PDA
- **Description**: Nexus 产品系列 · PDA 手持智能终端 — 面向仓储/产线/质检/设备的扫码优先作业终端（uni-app + Vue 3），安装包见发行版
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 6
- **Created**: 2026-08-20
- **Last Updated**: 2026-11-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: pda, nexus
## README
# Nexus PDA · 手持作业终端
面向仓储、产线、质检和设备人员的**扫码优先作业终端**。基于 uni-app + Vue 3 开发，使用 HBuilderX 构建，由 Nexus ERP 提供业务接口，连接现场扫码操作与后台业务单据。
**主仓库：[Nexus ERP](https://gitee.com/NexusERP/nexus-erp)** · [PDA 仓库](https://gitee.com/NexusERP/nexus-pda) · [发行版与安装包](https://gitee.com/NexusERP/nexus-pda/releases) · [开发文档](doc/README.md)
## 目录
- [项目定位](#项目定位)
- [项目架构](#项目架构)
- [主要功能](#主要功能)
- [功能截图与使用说明](#功能截图与使用说明)
- [开发与运行](#开发与运行)
- [发行与现场验证](#发行与现场验证)
- [相关文档](#相关文档)
- [许可证](#许可证)
## 项目定位
Nexus PDA 承接现场高频、短流程的扫码作业：扫单定位、逐行核对、录入结果、提交反馈。作业台按业务分组提供入口，并展示后端按权限返回的待办摘要。
| 项目 / 场景 | 职责 |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Nexus ERP 主仓库](https://gitee.com/NexusERP/nexus-erp) | 提供 ERP / MES 业务服务、单据管理、审批配置和 PDA 接口，负责状态流转、权限及库存校验。 |
| Nexus PDA（本仓库） | 面向手持终端执行仓储、产线、质量、设备作业及追溯查询。 |
| 移动 App / station | 与移动 App 保持独立的业务页面；固定工位联机设备由 station 承载，具体边界见[功能设计](doc/design/功能设计.md)。 |
Android PDA 是现场使用场景，H5 可用于开发预览和手输流程检查。扫码广播、键盘楔、摄像头以及打印能力需按目标设备分别验证。
## 项目架构
### 技术与分层
| 层次 | 技术 / 入口 | 主要职责 |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| 应用与页面 | uni-app、Vue 3 Composition API、`App.vue`、`pages.json` | 应用初始化、页面路由及各业务作业界面。 |
| 状态与配置 | Pinia、`store/`、`config.js` | 登录用户、账号与租户上下文、环境地址、扫码和打印配置。 |
| 公共交互 | `components/` | 扫码输入、身份解析状态、离线提示、任务核对及追溯结果展示。 |
| 作业编排 | `composables/` | `useScan` 处理扫码输入；`useDocFlow` 管理单据查询、明细和提交状态；`useMaterialIdentity` 管理服务端身份解析。 |
| 业务接口 | `api/`、`utils/request/` | 按业务域封装接口，统一处理登录态、重复提交和错误反馈。 |
| 终端基础能力 | `utils/`、`static/` | GS1 解析、主数据缓存、离线队列、幂等命令、上传、音效振动和打印适配。 |
| 工程检查 | Vitest、ESLint、Prettier、`tests/`、`scripts/` | 单元测试、代码规范、共享 core 一致性检查与集成冒烟。 |
```text
Android PDA / 手机 H5 开发预览
└─────────────────────┬─────────────────────┘
uni-app + Vue 3
│
pages/ 页面 + components/ 公共交互
│
composables/ 扫码、单据与身份解析
│
api/ + utils/request/ 请求层
│
Nexus ERP 后端（主仓库提供业务服务）
/app/auth/* 登录与用户信息
/app/pda/* 仓储、产线、质量、设备、追溯
横向能力：Pinia 状态 · 主数据缓存 · 离线队列 · 幂等命令 · 终端适配
```
扫码或手输编码后，页面通过服务端解析确认物料、批次、SN 或单据身份，再结合当前单据与明细进行核对。写操作携带命令标识，后端负责最终业务校验和幂等处理；本地 GS1 解析与主数据缓存用于展示和预校验。
### 目录结构
```text
nexus-pda/
├── api/ # 登录、PDA 业务和物料追溯接口
├── components/
│ ├── common/ # 扫码、身份状态、离线任务等公共组件
│ └── trace/ # 制造履历展示组件
├── composables/ # 扫码接入、单据流程、物料身份会话
├── pages/
│ ├── login/ # 登录
│ ├── work/ # 作业台与待办入口
│ ├── wm/ # 收货、发料、移库、盘点、退料、交接
│ ├── mes/ # 报工、SN、质量三检、设备点检与维保
│ ├── trace/ # 综合查询、身份 / 批次追溯
│ └── mine/ # 账号、主数据同步、离线任务核对
├── store/ # Pinia 用户与配置状态
├── utils/
│ ├── core/ # nexus-client-core 的共享基础能力副本
│ └── print/ # 标签模板、TSPL 指令与打印适配
├── static/ # 公共样式和扫码反馈音效
├── tests/ # 单元与页面回归测试
├── scripts/ # 共享 core 同步、音效生成、集成冒烟
├── doc/ # 设计、实施、验证文档与功能截图
├── config.js # 环境地址、扫码和打印配置
├── manifest.json # 应用信息、权限和打包配置
└── pages.json # 页面路由与导航配置
```
`utils/core/` 由同级 `nexus-client-core/src` 单向同步维护，修改共享逻辑时应先修改源工程，再运行同步脚本。
## 主要功能
| 业务领域 | 功能 | 典型使用流程 |
| -------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 作业台 | 当前操作员、快捷作业、待办摘要、业务分组 | 登录 → 查看待办 → 进入对应作业。 |
| 仓储收发 | 收货上架、备料发料、退料核销 | 扫单 → 核对物料 / 批次 / SN 与数量 → 按单据状态提交。收货包含逐行核销、库位上架确认和收货过账。 |
| 库存作业 | 移库、明盘 / 盲盘、临时盘点 | 移库分别确认源库位与目标库位；盘点录入实盘数量后按后端规则处理差异。 |
| 产线作业 | 上料交接、SN 绑定 / 解绑、工序报工 | 按单据交接物料，关联 SN 与批次；扫描派工单开工，录入合格、不良及报废数量后完工报工。 |
| 质量管理 | 来料检验 IQC、制程巡检 IPQC、出货检验 OQC、AQL 抽样试算 | 扫码定位待检单 → 填写检验数量和判定 → 提交结果；IPQC 支持拍照上传留证。 |
| 设备管理 | 设备点检、保养维保 | 扫设备码 → 按点检模板逐项录入；按保养计划执行维保。 |
| 统一追溯 | 物料 / 批次 / SN 查询、来源与去向、MES 批次链和制造履历、身份与批次追溯 | 扫码或输入编码 → 服务端解析 → 查看有权限的追溯记录。 |
| 终端辅助 | 主数据同步、离线任务、扫码反馈、标签打印适配 | 提前同步物料和库位；核对待同步或隔离任务；按机型启用扫码广播和打印。 |
### 扫码与离线原则
- **多种输入方式**：键盘楔扫码枪、Android 广播、摄像头和手动输入。键盘楔以回车提交，广播 action 与字段名按机型配置。
- **身份以服务端解析为准**：识别物料、批次、SN 与单据，遇到歧义、身份不符或明细版本问题时提示操作员处理。
- **保留原始命令**：写操作发送前持久化命令快照，网络异常后可进入待同步状态；重放沿用原命令和幂等标识，业务校验失败需人工核对。
- **按账号与租户隔离**：登出或切换账号时隔离原任务，保留操作归属；原账号和原租户核对后可恢复符合条件的隔离任务。
- **区分待同步与已完成**：本地入队不代表服务端已过账。缓存和离线队列用于辅助现场作业，需联网解析、上传或强校验的流程仍依赖后端。
## 功能截图与使用说明
> 以下截图由当前前端源码构建的 H5 页面配合本地演示数据生成，人员、单号和数量均为示例。截图展示界面与操作入口，不代表真实业务数据或 PDA 真机验收结果。图片保存在 [`doc/images/`](doc/images/)。
### 1. 作业台与收货上架
| 作业台 | 收货上架 |
| :-----------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------: |
| 
| 
|
- **作业台**：登录后查看当前操作员和待办数量，通过「扫码收货」「综合查询」或业务分组进入作业；下拉刷新待办。
- **收货上架**：从「仓储作业 → 收货上架」扫描单号进入明细，逐行扫描物料并确认本次数量；完成核销后扫描库位确认上架，再执行收货过账。
### 2. 库存盘点与工序报工
| 库存盘点 | 工序报工 |
| :---------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------: |
| 
| 
|
- **库存盘点**：扫描盘点单号后，扫描物料录入实盘数量。明盘可核对账面数与差异，盲盘按计划隐藏账面数；无预建单时可发起临时盘点。
- **工序报工**：扫描工单 / 派工单，或刷新列表选择派工。待开工单先开工，进行中单录入合格、不良和报废数量后提交完工报工。
### 3. 质量检验与设备点检
| 质量检验与 AQL 试算 | 设备点检 |
| :-----------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: |
| 
| 
|
- **质量检验**：进入来料、制程或出货检验，扫码定位单据，填写检验结果。展开「AQL 抽样试算」可按批量、AQL 与检验水平计算样本量及 Ac / Re，并填入检验数量；试算建议供检验员参考。
- **设备点检**：扫描设备编码载入点检模板，逐项对照标准填写实测值，选择合格 / 不合格并记录异常说明，检查完毕后提交。
### 4. 统一追溯与离线任务
| 统一追溯 | 我的与离线任务 |
| :----------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------: |
| 
| 
|
- **统一追溯**：从「综合查询」或「质量管理 → 追溯查询」输入物料、批次或 SN 编码。系统按解析对象展示来源、去向和制造记录，或进入身份 / 批次追溯详情；可见内容由服务端权限控制。
- **主数据与离线任务**：从作业台「账户」进入「我的」，点击「同步主数据」更新缓存。有待同步、失败或隔离任务时展示核对面板；先确认服务端记录，再按任务状态同步或恢复。
## 开发与运行
### 环境准备
- Node.js：版本要求见 `package.json`（当前声明为 `>=18.0.0`）。
- HBuilderX：安装 uni-app / Vue 3 编译能力，用于 H5 预览及 Android 构建。
- Nexus ERP：准备可访问的后端环境，以及具有相应租户和业务权限的测试账号。后端部署请参阅[主仓库](https://gitee.com/NexusERP/nexus-erp)。
```bash
git clone https://gitee.com/NexusERP/nexus-pda.git
cd nexus-pda
npm install
```
通过 HBuilderX 导入本目录，选择运行到浏览器进行页面预览，或运行到 Android 设备进行调试。业务编译由 HBuilderX 执行，仓库中的 npm 脚本用于测试和工程检查。
### 配置说明
| 配置位置 | 配置项 | 说明 |
| --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `config.js` | `envConfig.development.baseUrl` | 开发接口默认 `http://localhost:8080`；真机调试时改为设备可访问的后端地址。 |
| `config.js` | `envConfig.production.baseUrl` | 发行构建使用的接口地址，打包前核对目标环境。当前通过构建注入的 `NODE_ENV` 区分环境。 |
| `config.js` | `appClientId` | 与后端注册的客户端保持一致。 |
| `config.js` | `scan.useBroadcast`、`scan.broadcast` | 默认关闭广播扫码；适配机型后配置广播 action、数据字段名并启用。 |
| `config.js` | `print.enabled`、`print.adapter` | 默认关闭打印，适配器为 `mock`；接入实际 BLE 打印机后再启用并验收。 |
| `manifest.json` | `appid`、版本、权限、发行配置 | 按目标应用配置 appid、签名证书和权限，具体见[打包前检查清单](doc/checklists/打包前检查清单.md)。 |
### 本地检查
```bash
npm test # Vitest 单元与回归测试
npm run lint # ESLint 检查
npm run format:check # 代码格式检查
```
共享 core 检查需要同级 `nexus-client-core` 源工程和脚本配置的目标工程目录：
```bash
npm run sync:core:check # 比对共享副本，检查过程不覆盖文件
npm run sync:core # 从源工程同步到脚本配置的各目标工程
```
同步脚本会维护本仓库和同级 `Nexus_App` 的 `utils/core/`，运行同步前应确认目标目录。需要与后端联调时，按[集成测试记录](doc/集成测试记录.md)准备本地环境，再运行 `node scripts/integration/pda-smoke.mjs`；脚本包含写操作，应使用专用测试数据。
## 发行与现场验证
- [v0.1.0 试点发行版](https://gitee.com/NexusERP/nexus-pda/releases/tag/v0.1.0)（2026-10-08）。安装包和历史版本见[发行版页面](https://gitee.com/NexusERP/nexus-pda/releases)。
- 当前为试点工程，扫码广播、键盘楔、摄像头、反馈音效和打印驱动需在选定 Android PDA 上逐项验证。
- 打包前核对 appid、证书、生产接口和设备权限。当前生产接口配置为 HTTP，网络与凭证存储注意事项见[待办与风险](doc/plans/待办与风险.md)。
- 本地测试、H5 截图与历史冒烟记录分别提供对应范围的证据；设备适配和业务试点按[打包前检查清单](doc/checklists/打包前检查清单.md)验收。
## 相关文档
| 文档 | 内容 |
| ----------------------------------------------------- | -------------------------------------------- |
| [PDA 开发文档索引](doc/README.md) | 产品设计、实施计划和验证记录入口。 |
| [功能设计](doc/design/功能设计.md) | 业务边界、领域规则、扫码与离线原则。 |
| [PDA 性能与界面优化](doc/design/PDA性能与界面优化.md) | 作业台请求、扫码乱序保护和工业终端视觉规则。 |
| [工位 Pad 模式设计](doc/design/工位Pad模式设计.md) | 尚未立项的横屏固定工位方案与前置条件。 |
| [待办与风险](doc/plans/待办与风险.md) | 仍需人工或目标环境确认的发布事项。 |
| [集成测试记录](doc/集成测试记录.md) | 历史本机冒烟证据与联调说明。 |
| [打包前检查清单](doc/checklists/打包前检查清单.md) | 构建、真机和试点验收门禁。 |
## 许可证
本项目使用 [MIT License](LICENSE)。