69 lines
6.6 KiB
Markdown
69 lines
6.6 KiB
Markdown
# PDA Uni-app Instructions
|
|
|
|
## 项目定位
|
|
|
|
- 本项目面向仓库现场人员，使用 uni-app 适配仓库 PDA 设备。
|
|
- README 记录的登录、箱号选择、扫码、整单或部分拣货、异常原因和完成提交是当前静态原型范围；项目使用 uni-app Vue 3，业务页面采用 Vue 3 兼容的 Options API。
|
|
- 本项目负责现场执行体验，不承担管理后台的订单配置、客户工作台或通用库存管理能力。
|
|
|
|
## 开发与发布边界
|
|
|
|
- 当前已有 uni-app Vue 3 静态原型和 `uni_modules/`，没有项目根级依赖清单或可核实的 HBuilderX/Android 构建命令；现有 Node.js 内置测试仅覆盖页面契约与本地状态规则。
|
|
- PDA 采用 uni-app 开发并支持在线更新；Android 硬件扫描已确认使用广播模式并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。设备型号不构成开发、发布或验收门禁；继续通过设备适配层接入，不绑定单一厂商 SDK。
|
|
- 正式作业已确认为在线模式：断网不能开始正式拣货、提交、完成任务或推进 `LOADED`，不实现离线业务提交队列；恢复网络后提示员工刷新重试。
|
|
- 明确使用的工具链和发布流程后，补充准确的依赖版本、安装、调试、测试和打包命令，并同步更新 `README.md` 与本文件。
|
|
|
|
## 作业流程原则
|
|
|
|
- 扫码是主路径：输入焦点、连续扫描、防抖、重复码、无效码、错箱和扫描反馈必须作为一等场景处理。
|
|
- 拣货扫描身份是后端下发的稳定箱唛箱码 `boxCode`；一次有效且未重复的箱码扫描表示拣出一箱。SKU、商品件数、入库单号和页面展示文案只用于辅助识别，不得作为扫码匹配键或拣货计数单位。
|
|
- 进入任务时由服务端标记“拣货中”；扫描结果先写入绑定作业员、任务和柜次的设备持久化草稿，仅在点击提交时批量写后端，禁止逐码提交。
|
|
- 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决异常时任务挂起，不能完成或推进 `LOADED`。
|
|
- 作业提交使用对员工不可见的轻量幂等标识和服务端版本；重复提交返回原结果，版本冲突提示刷新后重试，不静默覆盖。
|
|
- 提交成功或明确放弃后清理草稿；退出应用或设备重启后同一作业员、任务和柜次可恢复，其他账号不得继承。
|
|
- PDA 仅允许现场拍照；Admin 可通过独立受权入口人工上传。五类证据各至少 1 张有效照片，同类型允许多张追加；错误或重复照片标记作废并保留原因、操作人和时间，不硬删除。
|
|
- 与管理后台头程订单、仓库任务和 `baiyue-firstleg` Controller/OpenAPI 对齐稳定标识、状态机、时间和异常码，禁止在前端自行发明另一套业务状态。
|
|
|
|
## 设备、安全与可用性
|
|
|
|
- 将扫描器、震动、声音、网络和本地存储封装为设备适配层，业务页面不直接依赖厂商 API。
|
|
- `uni_modules/` 视为第三方依赖代码；除非任务明确要求修补依赖，否则不要直接修改，定制行为应通过业务组件或适配层实现。
|
|
- `manifest.json` 中的设备权限遵循最小化原则；新增或保留权限时说明对应功能，并移除目标平台不需要的权限。
|
|
- 适配手套操作、小屏、强光和高噪声环境：控件触控区域足够大，关键反馈同时使用文字、颜色及声音或震动。
|
|
- 页面应在扫码后迅速恢复到可继续扫描状态；高频路径避免不必要的弹窗和多级导航。
|
|
- 本地只保存完成任务所需的最少数据，退出、换班和设备遗失场景必须能清理敏感缓存。
|
|
- 日志可包含任务和错误关联标识，但不得记录完整令牌、人员隐私或可还原的敏感货物信息。
|
|
|
|
## 质量门禁
|
|
|
|
- 在真实目标 PDA 上验证扫描速度、连续扫描、断网阻断与恢复刷新、低电量、前后台切换和重复提交。
|
|
- 状态转换、扫码分类与页面契约使用 `node --test tests/*.test.mjs` 验证；新增本地行为时继续补充对应自动化测试。
|
|
- 当前原型没有可核实的 HBuilderX/Android 构建命令，不得声称打包或真机检查已通过；交付说明应明确实际验证方式、设备、系统版本和仍未覆盖的风险。
|
|
|
|
## 页面与能力快速查询
|
|
|
|
| 目标 | 入口 | 继续查询 |
|
|
|---|---|---|
|
|
| 页面注册与启动 | `pages.json`、`main.js`、`App.vue` | 全局样式和应用生命周期 |
|
|
| 登录与会话 | `pages/login/`、`stores/session.js` | 远程鉴权适配和会话清理 |
|
|
| 工作台与模块入口 | `pages/home/`、`pages/module/`、`pages/operation/` | `data/demo-data.js` 与页面禁用规则 |
|
|
| 拣货任务与箱码扫码 | `pages/picking/`、`stores/picking.js` | `api/pda-loading.js`、`utils/scan-broadcast.js`、`components/ScanTargetInput.vue`；服务端契约见 `../../baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.yaml` |
|
|
| 扫描诊断 | `pages/scanner-test/` | `utils/scan-broadcast.js` 与广播 Action/Extra |
|
|
| 作业记录与人员 | `pages/history/`、`pages/profile/` | session 与本地敏感数据清理 |
|
|
|
|
## 全量验收索引
|
|
|
|
当前按 PDA 全量作业链路验收。阶段文档仍用于核对功能来源和验收证据，不再限制本次验收范围；从 `pages.json` 定位页面，沿页面 → `stores/` → `utils/` → 设备适配层检查。本表只描述 PDA 作业端，不代表后台或 Client 已具备对应能力。
|
|
|
|
| 验收域 | PDA 范围与代码入口 | 验收首读 |
|
|
|---|---|---|---|
|
|
| 作业全链路 | 登录、工作台、扫码拣货、装柜证据、草稿持久化、批量提交、异常和在线更新 | `pages/login/`、`pages/home/`、`pages/picking/`、`stores/session.js`、`stores/picking.js`、`utils/scan-broadcast.js`、`pages.json` | 按业务选择 `../../docs/一期/`、`../../docs/二期/`、`../../docs/三期/` 和 `README.md` 的契约与验收规则 |
|
|
|
|
作业边界：PDA 不承担客户工作台或后台配置；服务端状态、权限、幂等和 `LOADED` 门禁是验收事实来源。发布采用既定 uni-app 在线更新安排。
|
|
|
|
## 全量验收脚本
|
|
|
|
- PDA 不单独定义一套“全量 HTTP”入口；PDA 服务链路由 Admin 全量 HTTP 入口中的 `phase3-pda-convergence`、装柜、证据和出仓模块覆盖。
|
|
- 本目录 `node --test tests/*.test.mjs` 仅是 PDA 本地页面/状态质量检查，不代表服务端作业链路已通过。
|
|
- 服务 HTTP 通过后，再按真实 uni-app 页面完成扫码输入、网络阻断/恢复、草稿恢复、批量提交、窄屏和在线更新验收；真机检查属于最后的交互验收。
|