柏悦物流海外版 PDA

独立的 uni-app Vue 3 App 工程，正式产品形态是安装在海外仓手持 PDA 上的 App。工程不依赖国内 PDA 源码或仓库外共享目录，可独立安装依赖、运行、编译和发布；H5 只用于浏览器调试和编译门禁，不是最终交付形态。

工作台提供柜号级真实入仓、托盘管理、排车拣货、出库任务、一件代发出库、任务完成和发车入口；派送单、派送状态与客户回访由 Admin/Client 承载。登录使用Auth 签发的统一 Access/Refresh Token；业务请求统一经 gateway，不得请求国内 Firstleg/Warehouse 业务接口。

本地运行与检查

Node.js 22 环境：

npm install
npm test
npm run dev:h5

开发环境可在不提交的 .env.local 中配置 VITE_PDA_DEV_USERNAME、VITE_PDA_DEV_PASSWORD，登录页会自动预填；生产 App 构建始终忽略这两个值，账号必须具备 OVERSEAS_WAREHOUSE_PDA_OPERATOR、lastleg:pda:operate 和有效海外仓绑定。

生产编译：

npm run build:h5
npm run build:app

build:h5 生成浏览器调试资源，用于页面和模板编译检查；
build:app 生成正式 App 的离线打包资源；
生成可安装 APK/IPA 需使用 HBuilderX App 开发版执行云打包或配置原生离线打包环境。

正式 App 打包前必填

使用海外版所属的 DCloud 账号为本应用获取独立 AppID，写入 src/manifest.json 的 appid；不得复用国内版 AppID。
确认 Android 包名 com.baiyuelogistics.pda.overseas，如公司已有正式命名规范，在首次正式签名前修改。
配置海外版独立 Android 签名证书；证书、密码和账号信息不得提交仓库。
复制 .env.example 为本机 .env.local，配置统一 Gateway 地址；环境文件不提交仓库。
在目标海外 PDA 上验证扫描广播 Action=android.intent.action.SCANRESULT、Extra=value。

当前实现边界

已复用并内置：登录壳、PDA 样式、扫码广播、声音反馈、导航、网络检测、图标及 uni_modules。
已隔离：国内集装箱拣货、装柜证据、国内 Firstleg API、国内任务状态和国内本地草稿。
入仓页面已接待卸柜候选、柜详情与账号锁柜、三类角色照片签收、current 恢复、统一箱码与既有物理托盘解析、FBA 按箱数和 OVERSEAS 逐箱收货、逐入仓码核平及整柜完成的真实 API；收货页不预列柜内入仓码，箱码解析成功后只显示本次命中的入仓码；409 会引导返回当前柜，错误会保留业务码、requestId 与 traceId。
候选列表明确显示当前 PDA 绑定仓及每柜已分配的海外接柜仓编码/名称，仅接受与绑定仓一致的服务端候选、详情、prepare 与 current 会话；字段缺失或仓不匹配时直接阻断，不从 FBA/业务目的仓或内部 ID 推导。列表同时显示已齐全与未齐全柜，展示计划到仓时间、总订单、入仓码、已生成计划、未操作和缺入仓码数量；未齐全柜置灰但可查看服务端阻断原因，只有服务端 allPlansReady=true && operable=true 才能建立已分配柜的作业会话。
托盘管理已接 /api/pda/v1/last-leg/pallet-operations/**：支持扫描查询当前仓实物托盘及库存内容，并按服务端版本执行组托、拆托、换托和解绑；不同目的仓不能合托，冻结或处理中的库存由服务端拒绝。
排车拣货已接 /api/pda/v1/last-leg/dispatches/**：支持任务列表、业务单号恢复、托盘码扫码拣货、任务完成及全部箱数核平后的发车；服务端仍会校验关联出库单和托盘门禁。
出库作业已接 /api/pda/v1/last-leg/outbound-tasks/**：支持普通出库和一件代发任务列表/详情、托盘码/箱码/SKU/入仓码扫码拣货与核平完成；不会展示或进入派送流程。
排车与出库写操作使用可恢复的稳定幂等键。网络失败保留当前任务、扫码草稿和幂等键；成功后释放键并按服务端状态恢复，避免重复完成或发车。
入仓请求不手填客户、计划、分配、仓库或库位标识；身份与当前柜范围由 Token、Gateway 和服务端会话确定。页面同时支持 PDA 广播扫码与 H5 人工输入。
登录、恢复和刷新会 fail-closed 校验统一 Token 的平台操作主体和冻结海外仓，并从 Auth 登录/刷新响应的顶层权限快照校验 OVERSEAS_WAREHOUSE_PDA_OPERATOR、lastleg:pda:operate，不从 JWT 解析权限；并发 401 共享一次 refresh，主体与绑定仓保持一致后原子替换统一 Token 和权限快照，并将原请求或照片上传重放一次。刷新失败或重放后仍未授权时清空会话和作业草稿，并返回登录页；退出或重新登录后，旧请求不能重放到新会话，迟到的刷新响应也不能恢复旧会话或清除新会话。
库存盘点、商品移库、换标收货/执行/复核以及库存/库位/托盘查询均已接入 /api/pda/** 专用接口；支持 PDA 广播扫码与 H5 人工输入，并按服务端版本、幂等键和冲突状态恢复，不调用平台、客户或内部接口。
本地契约测试与 H5/App 资源编译不等于真实测试环境 HTTP 或 PDA 真机验收。

App 在线更新

Android App 启动后会读取 VITE_PDA_UPDATE_URL 并检查海外 PDA 的独立更新通道，员工也可在“个人中心 → 检查更新”手动触发；H5 仅展示 App 操作提示，不执行更新。更新服务接收 appid、platform、appVersion、appVersionCode、wgtVersion 查询参数，无更新返回 { "update": false }，有更新返回：

{
  "update": true,
  "appid": "<海外PDA AppID>",
  "packageType": "wgt",
  "versionName": "0.0.2",
  "versionCode": 2,
  "minAppVersionCode": 1,
  "downloadUrl": "https://updates.example.com/pda/overseas/0.0.2.wgt",
  "mandatory": true,
  "releaseNotes": "本次更新内容"
}

packageType 只允许 apk 或 wgt，appid 必须与当前安装包一致。WGT 清单还须提供 minAppVersionCode（最低兼容 APK 整数版本），不满足时客户端拒绝安装并提示升级 APK。mandatory=true 时员工不能跳过，并在下载或安装失败后提供重试；wgt 安装完成会立即重启，APK 交由 Android 安装器完成覆盖安装。正式发布要求：

海外 PDA 每次整包发布同时递增 src/manifest.json 的 versionName 与整数 versionCode，使用海外独立 AppID、包名和签名打包 APK。
wgt 发布至少递增 versionName，并使用与已安装原生包兼容的 uni-app 编译器生成；新增原生模块、权限或不兼容运行时能力时必须发布 APK，不能只发 wgt。
更新清单与下载地址使用 HTTPS，先在测试设备验证可选更新、强制更新、断网重试、APK 覆盖安装、wgt 重启及扫码作业回归，再切换正式清单。
海外和国内更新记录、文件目录及发布权限保持隔离，服务端必须按请求中的 appid 拒绝跨应用更新包。

H5 静态托管（TEST 与灰度）

国内、海外 PDA H5 统一由宿主机已有 Nginx/宝塔站点直接提供静态文件，不再构建或发布 PDA H5 Docker 镜像、Compose 服务或容器。正式部署约束见测试环境单机部署与配置契约的“PDA H5 发布方式”；历史灰度报告不再作为发布入口。

发布构建使用 / 资源 base 与 hash 路由，部署到本应用独立域名根目录，浏览器入口为 /#/。不能放到子目录后继续共用根路径资源，也不能将 Vite 开发代理当作线上配置。

执行 npm run build:h5 导出 Web 静态文件；npm run build:app 不属于 H5 发布。

发布步骤：

构建后执行 node scripts/verify-h5.mjs，核对 HTML/JS/CSS 资源路径及同源 API。构建、测试仍按根规则经 local-check.ps1 执行。
将 dist/build/h5/ 目录内的文件上传到该 PDA 站点现有 root。先上传 assets/、static/ 等资源，最后替换 index.html，保留站点证书验证目录和站点配置；不要把外层构建目录一起嵌套上传。
页面 location / 使用 try_files $uri $uri/ =404 直接读取静态文件，设置 Cache-Control: no-store；不得再转发到旧 PDA 容器。接口 /gateway-api/ 独立转发到当前环境统一 Gateway /api/，保留 Authorization 和上传能力。
首次切换前备份实际生效站点配置，合并下述片段并执行 nginx -t，成功后才重载。已有独立 API 规则先核对并复用，不能直接追加重复 location。后续仅更新静态文件时无需新建容器或重载 Nginx。
检查域名首页及实际引用的 JS/CSS 均返回 200，并将响应内容的 SHA-256 与本次产物逐项比较；确认响应不是旧容器内容。再检查登录和受影响页面。首页 200 不等于接口或业务验收通过。

站点配置片段

deploy/nginx.conf.template 是合并到已有 server 的参考片段，不是完整站点配置。保留现有域名、HTTPS、证书与宝塔 include；替换原有 root/index 及同名 location。环境地址、端口及网站目录只在部署侧配置，不提交到源码。

在部署机器上将 PDA_SITE_ROOT 设置为该站点真实根目录，PDA_GATEWAY_ORIGIN 设置为宿主机可达的当前环境 Gateway 源地址（协议、主机、端口，不含末尾 / 或 /api）。不要使用仅 Docker 网络可解析的服务名。显式只渲染这两个变量，保留 $uri、$host 和代理请求头变量：

envsubst '${PDA_SITE_ROOT} ${PDA_GATEWAY_ORIGIN}' < deploy/nginx.conf.template

输出仅供核对和合并，不直接覆盖完整站点。若机器没有 envsubst，手工替换这两个占位符；未替换的模板不能直接加载。

两端统一 API 配置

App 的 VITE_API_BASE_URL 为统一 Gateway 绝对地址（含 /api）；H5 使用 VITE_H5_API_BASE_URL=/gateway-api。API_PROXY_TARGET 仅供本地 Vite 开发代理使用，不随静态包发布。实际地址放在未提交环境文件；变更编译变量后须重新构建。

站点 API 规则须使用 location ^~ /gateway-api/，防止驾驶证等包含 LICENSE 的业务路径被站点敏感文件正则截获。仅更新静态包不能修复代理配置；域名入口和每层代理均须核对。

部署定向检查：node --test tests/h5-deployment.test.mjs，经 local-check.ps1 执行。该检查覆盖静态发布约束、资源 base 和开发代理重写，不替代目标主机 Nginx 校验、真实 HTTP、人工页面及 Android 真机验收。

11 KiB Raw Permalink Blame History Unescape Escape