87 lines
14 KiB
Markdown
87 lines
14 KiB
Markdown
# PDA Uni-app Instructions
|
||
|
||
## 项目定位
|
||
|
||
- 本项目面向仓库现场人员，使用 uni-app 适配仓库 PDA 设备。
|
||
- README 记录的登录、箱号选择、扫码、整单或部分拣货、异常原因和完成提交是当前静态原型范围；项目使用 uni-app Vue 3，业务页面采用 Vue 3 兼容的 Options API。
|
||
- 本项目负责现场执行体验，不承担管理后台的订单配置、客户工作台或通用库存管理能力。
|
||
|
||
## 开发与发布边界
|
||
|
||
- H5 在 TEST/灰度均上传静态文件至宿主机 Nginx 站点；禁止重建 PDA H5 容器或将页面入口转发到旧容器。发布步骤见 `README.md`，站点片段见 `deploy/nginx.conf.template`；历史灰度脚本不作现行入口。
|
||
- 当前已有 uni-app Vue 3 页面、`uni_modules/`、`vite.config.js`、`.env.example` 和 H5 同源代理配置。首页当前只展示“入库 → 一件代发”和“出库 → 出库拣货”；“库位查询”等其余能力保留源码与路由但不展示。项目仍没有根级依赖清单、仓库内 npm 构建命令或可核实的 Android 构建命令。H5 已使用 HBuilderX 5.15 自带编译器和 `cli.exe launch web` 验证，具体命令见 `README.md`。现有 Node.js 内置测试仅覆盖页面契约与本地状态规则。
|
||
- PDA 采用 uni-app 开发并支持在线更新；Android 硬件扫描已确认使用广播模式并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。设备型号不构成开发、发布或验收门禁；继续通过设备适配层接入，不绑定单一厂商 SDK。
|
||
- 正式作业已确认为在线模式：断网不能开始正式拣货、提交、完成任务或推进 `LOADED`，不实现离线业务提交队列；恢复网络后提示员工刷新重试。
|
||
- H5 调试使用 HBuilderX 5.15 自带的 uni-app Vue 3 编译器；Android 发布流程仍待明确后补充准确的依赖版本、打包命令，并同步更新 `README.md` 与本文件。
|
||
- 在 `package.json` 与锁文件正式补齐前，`vite.config.js` 只证明目标配置，不证明依赖可安装；维护者可运行仓库当前可执行的 `node --test tests/*.test.mjs`，或使用已安装的 HBuilderX 5.15 CLI 运行 H5，不得从海外 PDA 或全局缓存猜测国内 PDA 的 uni-app/Vite 版本。
|
||
- App API 根只读 `VITE_API_BASE_URL`；H5 固定优先使用 `VITE_H5_API_BASE_URL=/gateway-api` 并由 `vite.config.js` 同源代理、重写为 Gateway `/api`，避免截获项目自身 `api/` 前端模块。环境地址不写入源码，切换构建环境后不得沿用登录缓存中的旧 API 地址。
|
||
- 国内 Android App 启动后仅在 `APP-PLUS` 调用 `utils/app-update.js`，通过独立 `VITE_PDA_UPDATE_URL` 检查更新；更新服务和下载地址必须为 HTTPS。APK 以整数 `versionCode` 判新，WGT 以 `versionName` 判新；强制更新不可跳过，WGT 安装后立即重启。国内 AppID、包名、签名、版本和更新通道不得复用海外 PDA。
|
||
|
||
## 作业流程原则
|
||
|
||
- 扫码是主路径：输入焦点、连续扫描、防抖、重复码、无效码、错箱和扫描反馈必须作为一等场景处理。
|
||
- 普通散箱拣货的扫描身份是后端下发的稳定箱唛箱码 `boxCode`，一次有效且未重复的箱码扫描表示拣出一箱；一件代发已封托的 `SEALED_PALLET` 明细允许扫描系统 `palletNo`、扫描托内任一成员 `boxCode` 或在明细卡片手工确认整托，但三种入口都必须按计划快照中的 `palletNo` 以 `PICK_PALLET` 一次性提交，不能逐箱累计、部分拣货或跳拣；只按权威 `unitType=SEALED_PALLET` 识别整托，不能从资源 ID 或 `indivisible` 猜测。SKU、商品件数、入库单号和页面展示文案只用于辅助识别，不得作为扫码匹配键。
|
||
- 拣货明细卡片按现场找货优先级展示库位、托盘码或入仓码、待拣箱数和处理状态；库位从明细 `inventoryResources.locationCode` 去重汇总，缺失时明确显示“库位 —”。商品名称和 SKU 数据可以保留在响应模型中，但不占用 PDA 拣货卡片主区域。
|
||
- 进入任务时由服务端标记“拣货中”；每次有效箱码或托盘码扫描，以及确认拣出、部分拣货、跳拣操作，都必须立即写入服务端，设备持久化草稿只用于恢复页面状态。底部提交只原子收尾尚未处理的明细并进入装柜取证，不重复提交已落库动作。
|
||
- 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决异常时任务挂起，不能完成或推进 `LOADED`。
|
||
- 作业提交使用对员工不可见的轻量幂等标识和服务端版本；重复提交返回原结果，版本冲突提示刷新后重试，不静默覆盖。
|
||
- 提交成功或明确放弃后清理草稿；退出应用或设备重启后同一作业员、任务和柜次可恢复，其他账号不得继承。
|
||
- PDA 仅允许现场拍照；Admin 可通过独立受权入口人工上传。五类证据各至少 1 张有效照片，同类型允许多张追加；缩略图使用右上角“×”作为员工可见的删除入口，不显示“作废”文案，服务端仍对错误或重复照片保留删除原因、操作人和时间，不硬删除。设备端证据查询、上传、预览和删除统一按当前 `taskId + warehouseId` 走任务专用 API，服务端再绑定真实柜 `containerBookingId`；不得调用旧入仓单/客户作用域证据接口。
|
||
- 与管理后台头程订单、仓库任务和 `baiyue-firstleg` Controller/OpenAPI 对齐稳定标识、状态机、时间和异常码，禁止在前端自行发明另一套业务状态。
|
||
- 一件代发清点组托使用独立 `/first-leg/pda-dropship` 任务链：箱码先经只读识别再确认实收；系统托盘码可先于或晚于箱码扫描。`count` 携托盘码时直接绑定，箱码先扫则进入待绑托区并由 `bind-pending` 批量绑定；换托只使用服务端 `cartonId`，封托后按整托不可拆。只消费 `platform:firstleg:pda:view` 与 `platform:firstleg:pda:work` 权限结果，不在 PDA 自建权限语义。
|
||
- 清点组托使用测量审核预生成的 DP 托盘；扫描托盘通过 `bind-pending` 原子绑定待绑箱。幂等键按操作员、任务、载荷和版本稳定生成，失败重试复用；换托先移回待绑区再扫描目标托盘，封托不可拆分。装柜拣货扫描后等待正式整托 API 成功再更新本地结果。
|
||
|
||
## 设备、安全与可用性
|
||
|
||
- 将扫描器、震动、声音、网络和本地存储封装为设备适配层，业务页面不直接依赖厂商 API。
|
||
- `uni_modules/` 视为第三方依赖代码；除非任务明确要求修补依赖，否则不要直接修改，定制行为应通过业务组件或适配层实现。
|
||
- `manifest.json` 中的设备权限遵循最小化原则；新增或保留权限时说明对应功能，并移除目标平台不需要的权限。
|
||
- 适配手套操作、小屏、强光和高噪声环境：控件触控区域足够大，关键反馈同时使用文字、颜色及声音或震动。
|
||
- 页面应在扫码后迅速恢复到可继续扫描状态；高频路径避免不必要的弹窗和多级导航。
|
||
- 本地只保存完成任务所需的最少数据，退出、换班和设备遗失场景必须能清理敏感缓存。
|
||
- 日志可包含任务和错误关联标识，但不得记录完整令牌、人员隐私或可还原的敏感货物信息。
|
||
|
||
## 质量门禁
|
||
|
||
- 验证按 `../../docs/AI工程执行与协作约束.md` 的“验证范围选择”；文案/纯展示核对差异，局部逻辑指定受影响测试文件，不默认全量、构建或真机全面验收。
|
||
- 扫码、断网恢复、生命周期或设备能力变化才在真实 PDA 核对对应场景；完整设备回归用于明确的发布/验收任务。
|
||
- 状态转换、扫码分类与页面契约按受影响文件执行 `node --test`；`node --test tests/*.test.mjs` 为全量入口，不因新增本地行为自动触发。
|
||
- 修改在线更新协议、版本比较、强制更新、安装或重启行为时运行 `node --test tests/app-update.test.mjs`；新增原生模块、权限或不兼容运行时能力必须发布 APK，不能只发布 WGT。
|
||
- 当前没有依赖清单、仓库内 npm 构建命令或可核实的 Android 构建命令；H5 必须按 `README.md` 使用 HBuilderX 5.15 CLI 实际启动后才可声称通过，不得仅凭 `vite.config.js` 声称 H5、App 打包或真机检查已通过。交付说明应明确实际验证方式、设备、系统版本和仍未覆盖的风险。
|
||
|
||
## 页面与能力快速查询
|
||
|
||
| 目标 | 入口 | 继续查询 |
|
||
|---|---|---|
|
||
| 页面注册与启动 | `pages.json`、`main.js`、`App.vue` | 全局样式和应用生命周期 |
|
||
| API 环境与 H5 开发代理 | `config/runtime.js`、`.env.example`、`vite.config.js` | App `VITE_API_BASE_URL`；H5 同源 `VITE_H5_API_BASE_URL=/gateway-api`，代理上游 `API_PROXY_TARGET` 并重写为 `/api`；会话恢复不得覆盖当前构建地址 |
|
||
| 部分拣货布局与库位展示 | `pages/picking/picking.vue`、`styles/pda.scss` | 库位为空时不渲染空标签或残留分隔符；部分拣货数量必须小于需求且不超过服务端库存/库位可用量，合同 `tests/partial-layout.test.mjs`、`tests/picking-location-display.test.mjs` |
|
||
| Android APK/WGT 在线更新 | `App.vue`、`utils/app-update.js`、`.env.example`、`manifest.json` | `VITE_PDA_UPDATE_URL` 使用国内独立 HTTPS 通道；合同 `tests/app-update.test.mjs`，H5 不执行更新逻辑 |
|
||
| 登录与会话 | `pages/login/`、`stores/session.js` | 远程鉴权适配和会话清理 |
|
||
| 工作台、仓库选择与模块入口 | `pages/home/`、`components/PortalHeader.vue`、`stores/session.js`、`pages/module/`、`pages/operation/` | 左上角只提供启用国内仓选择，选择结果持久化；`data/demo-data.js` 的 `visible` 控制展示、`available` 控制可操作；隐藏能力不得删除源码或路由 |
|
||
| 待处理任务、服务端就绪与领取 | `pages/tasks/tasks.vue` | `api/pda-loading.js` 的 `listLoadingOrders`、`getContainerPickingTask`、`claimContainerPickingTask`；合并任务和缺少柜号/仓库/版本的任务不可进入 |
|
||
| 一件代发 | `pages/dropship-tasks/dropship-tasks.vue`、`pages/dropship-palletization/dropship-palletization.vue` | `api/pda-dropship.js`；作为入库作业，测量审核按预计托数预生成 DP 托盘码，由 Admin 电脑端合并打印后贴到空托盘；PDA 不承载打印，只直接扫码并展示当前操作托盘；PDA 明确执行逐箱清点并支持先扫箱或先扫托、归托、换托/移回待绑托、逐托封托，以及在托盘未进入装柜计划前解除封托；同一国内作业仓的多票可继续装入同一开放托盘，单票全部归托不等于托盘装满，实物装满后才封托；预计托数与已生成托盘数不一致时失败关闭；公网前缀 `/api/platform/v1/first-leg/pda-dropship/**` |
|
||
| 业务编号展示与错误脱敏 | `utils/user-facing.js`、`tests/user-facing-identifiers.test.mjs` | 任务和作业页优先显示真实集装箱号，缺失时显示柜次号，再缺失显示“集装箱号 —”；不得展示 taskId、inboundId、orderId、loadingPlanId、containerBookingId 或长整型内部 ID，错误仍保留 code、requestId、traceId |
|
||
| 拣货任务与箱码扫码 | `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/dropship-palletization/dropship-palletization.vue` | `stores/dropship-palletizing.js`、`utils/dropship-palletizing-state.js`；服务端契约见 `../../baiyue-firstleg/firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml`，合同 `tests/dropship-palletizing-*.test.mjs` |
|
||
| 装柜取证与完成 | `pages/picking/picking.vue` 的 `evidence` 阶段 | 正式边界是 `api/pda-loading.js` 的证据查询、预览、上传、作废和 `completeContainerPickingTask` 全部按当前任务与仓库进入；不得保留按入仓单/客户作用域的旧证据调用。照片由页面直接上传，失败释放操作态，不缓存请求或自动重放；合同 `tests/pda-loading-api.test.mjs`、`tests/picking-evidence-stage.test.mjs`、`tests/seal-save-idempotency.test.mjs` |
|
||
| 扫描诊断 | `pages/scanner-test/` | `utils/scan-broadcast.js` 与广播 Action/Extra |
|
||
| 作业记录与人员 | `pages/history/`、`pages/profile/` | session 与本地敏感数据清理 |
|
||
| 页面与真实 API 合同 | `tests/page-contract.test.mjs`、`tests/pda-loading-api.test.mjs` | 覆盖部分拣货页面、提交门禁、库位不足反馈和国内 PDA 真实接口路径；统一由 `node --test tests/*.test.mjs` 执行 |
|
||
|
||
## 全量验收索引
|
||
|
||
用户明确要求 PDA 全量作业链路验收时使用本表；普通修改不触发全链路。业务域文档用于核对功能来源和验收证据；从 `pages.json` 定位页面，沿页面 → `stores/` → `utils/` → 设备适配层检查。本表只描述 PDA 作业端，不代表后台或 Client 已具备对应能力。
|
||
|
||
| 验收域 | PDA 范围与代码入口 | 验收首读 |
|
||
|---|---|---|---|
|
||
| 作业全链路 | 登录、工作台、一件代发扫码清点/归托/封托、出库扫码拣货、装柜证据、草稿持久化、批量提交、异常和在线更新 | `pages/login/`、`pages/home/`、`pages/dropship-tasks/`、`pages/dropship-palletization/`、`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 页面完成扫码输入、网络阻断/恢复、草稿恢复、批量提交、窄屏和在线更新验收；真机检查属于最后的交互验收。
|