优化

AGENTS.md

@@ -1,42 +1,33 @@
-# Overseas PDA Uni-app Instructions
+# 海外 PDA 指引
 
 ## 快速读取顺序
 
-1. 先用“页面与能力快速索引”定位 `src/pages.json`、工作台或最小页面；页面业务配置从 `src/data/overseas-workbench.js` 进入，不扫描 `src/uni_modules/`。
+1. 按下表定位最小页面；业务配置见 `src/data/overseas-workbench.js`，不扫 `src/uni_modules/`。
-2. 登录、Token 或统一入口请求先读 `src/api/auth.js`、`src/stores/session.js`、`src/config/runtime.js` 和 `../../docs/统一认证与服务通信契约.md`。
+2. 登录/Token/统一请求先读下表登录API/会话、`src/config/runtime.js`、`../../docs/统一认证与服务通信契约.md`。
-3. 沿实际 API 定位：入仓/库存契约读 `../../baiyue-firstleg/lastleg-service/AGENTS.md`；资源契约读 `../../baiyue-firstleg/warehouse-overseas-service/AGENTS.md`；网关路径或鉴权问题才读 `../../baiyue-firstleg/gateway/AGENTS.md`。跨模块流程或入口不明才读 `../../docs/海外仓业务/README.md`；纯页面改动不自动读取后端指引。
+3. 沿实际 API 读直接服务指引：入仓/库存 `../../baiyue-firstleg/lastleg-service/AGENTS.md`，资源 `../../baiyue-firstleg/warehouse-overseas-service/AGENTS.md`；网关路径/鉴权问题才读 `../../baiyue-firstleg/gateway/AGENTS.md`。跨模块或入口不明才读 `../../docs/海外仓业务/README.md`。
 
-最小读取集按任务保持在适用指引和目标页面/API；纯展示任务不增加服务指引，服务端判断才读直接服务指引，跨服务状态或鉴权无法判断时再增加相关方。读取预算遵循根指引的行数与字符数标准，先读适用规则，再检索业务命中段，不全文加载海外仓 README。
+仅读适用指引/目标页面/API；纯页面不读后端，跨服务状态/鉴权不明才扩读。遵根预算，先规则后命中段，不全文读海外仓 README。
 
 ## 项目定位
 
-- 本项目是“柏悦物流海外版”独立 uni-app Vue 3 工程，面向海外仓现场人员。
+- “柏悦物流海外版”面向海外仓现场人员，uni-app Vue 3 独立安装/构建/发布，不依赖 `apps/pda-uniapp/` 或仓库外 `pda-shared`。
-- 工程必须独立安装、构建和发布，不得依赖 `apps/pda-uniapp/` 或仓库外 `pda-shared` 目录。
+- 业务/任务完成见下表；派送/客户回访归 Admin/Client，国内集装箱拣货/装柜归国内 PDA。
-- 当前设备端业务范围包括海外仓入仓、退货签收与合箱、库内、换标、库存/库位/托盘查询，以及排车拣货、普通/一件代发出库任务、任务完成和发车；派送与客户回访由 Admin/Client 承载，国内集装箱拣货/装柜由国内 PDA 承载。
 
 ## 服务与发布边界
 
-- Auth 是唯一账号和 Token 签发方；认证和业务请求共用统一 Gateway，App 根地址只读 VITE_API_BASE_URL，H5 使用 VITE_H5_API_BASE_URL。
+- Auth 唯一签发账号/Token；认证/业务共用 Gateway，App 根地址只读 VITE_API_BASE_URL，H5 用 VITE_H5_API_BASE_URL。
-- 登录、刷新和本地会话必须校验统一 Token 的平台主体、成员、有效期和冻结海外仓；`OVERSEAS_WAREHOUSE_PDA_OPERATOR` 与 `lastleg:pda:operate` 只从 Auth 登录/刷新响应的顶层权限快照读取并持久化，不得解析 JWT 权限。权限快照缺失、无效、过期、跨主体或撤权响应必须 fail-closed 清理会话，不得只依赖页面入口隐藏。
+- 登录/刷新/会话校验Token平台主体、成员、有效期、冻结仓；`OVERSEAS_WAREHOUSE_PDA_OPERATOR`、`lastleg:pda:operate` 仅读存Auth登录/刷新顶层快照，禁解析JWT权限。快照缺失/无效/过期/跨主体或撤权均fail-closed清会话，不能只藏入口。
-- 并发 401 只允许一次 refresh；统一 Token 和权限快照完整校验后原子替换，主体或绑定仓改变时清理会话并重新登录，每个原请求或照片上传最多重放一次。刷新失败清理本地会话，业务错误和网络错误保留 code、requestId、traceId 或 network 诊断。
+- 并发401仅一次refresh，完整校验Token/快照再原子替换；主体/仓变化清会话重登录，原请求/照片上传最多重放一次。刷新失败清会话；业务/网络错留code、requestId、traceId或network诊断。
-- 国内与海外 AppID、Android 包名、签名、版本号、构建产物和在线更新通道必须独立。
+- 国内/海外 AppID、Android 包名、签名、版本号、产物、更新通道独立；`src/manifest.json` AppID须正式打包前由海外所属DCloud账号创建，禁伪造/复用国内AppID。
-- `src/manifest.json` 中的 AppID 在正式打包前由海外版所属 DCloud 账号创建；不得伪造或复用国内 AppID。
+- 环境地址仅配 `.env.local` 等未提交环境文件，不入源码。
-- 环境地址只通过 `.env.local` 等未提交环境文件配置，不写入源码。
+- Android启动仅在 `APP-PLUS` 调 `src/utils/app-update.js`，以独立 `VITE_PDA_UPDATE_URL` 查HTTPS APK/WGT；强更禁跳过，WGT安装即重启。更新服务/标识/签名/版本序列不得与国内 PDA 混用。
-- 海外 Android App 启动后仅在 `APP-PLUS` 调用 `src/utils/app-update.js`，通过海外独立 `VITE_PDA_UPDATE_URL` 检查 HTTPS APK/WGT；强制更新不可跳过，WGT 安装后立即重启。更新服务、AppID、包名、签名和版本序列均不得与国内 PDA 混用。
 
-## 工程入口
+- 源码根 `src/`；扫码广播 Action=`android.intent.action.SCANRESULT`，Extra=`value`。
-
+- 均接真实PDA API；入仓账号锁柜、逐码核平；退货号/SKU候选进入，按本包实收生成退货箱/计费批次。换标含收货/执行/复核；盘点页面/API保留、工作台隐藏。
-- 源码根：`src/`；页面注册：`src/pages.json`；应用配置：`src/manifest.json`。
-- 工作台定义：`src/data/overseas-workbench.js`。
-- 登录与会话：`src/api/auth.js`、`src/stores/session.js`。
-- 扫码设备层：`src/utils/scan-broadcast.js`；广播 Action=`android.intent.action.SCANRESULT`，Extra=`value`。
-- 入仓作业已接柜号级真实海外 API：账号锁柜、三类照片签收、统一箱码定位入仓码、FBA 按箱数收货、OVERSEAS 逐箱收货、一件代发按国内封托来源托盘整托收货并逐入仓码核平；退货入库通过退货单号或 SKU 候选进入并按本包实收生成退货箱与计费批次；移库、托盘管理、换标收货/执行/复核以及库存/库位/托盘查询均已接入专用 PDA API。库存盘点底层页面与接口仍保留，但当前工作台不开放入口。
 
 ## 页面与能力快速索引
 
-本表只保留首个入口；完整 API、字段、状态与恢复规则见 [按需业务索引](docs/business-index.md)。从本应用根执行 `rg -n -F '任务词或文件名' docs/business-index.md` 读取命中条款；涉及业务行为变更时必须核对对应细则，纯定位不全文加载。保留所有适用的最近模块指引。
+路径相对应用根；[业务索引](docs/business-index.md)存API/字段/状态/恢复。应用根 `rg -n -F '任务词或文件名' docs/business-index.md`；涉及业务行为变更时必须核对对应细则及最近指引，定位不全文读。
-
-表中路径均相对本应用根目录。
 
 | 目标 | 首个入口 |
 |---|---|
@@ -51,12 +42,10 @@
 | 退货箱内清点 | `src/pages/return-counting/return-counting.vue`、`src/api/return-counting.js` |
 | 仓储转运测量、打托与标签 | `src/pages/warehouse-transfer/warehouse-transfer.vue`、`src/api/warehouse-transfers.js` |
 | 托盘管理真实作业 | `src/pages/pallet/pallet.vue`、`src/api/pallet.js` |
-| 库存盘点（入口隐藏） | `src/pages/stocktake/stocktake.vue`、`src/api/warehouse-operations.js`、`src/stores/warehouse-work.js` |
+| 库存盘点（入口隐藏）、商品移库 | `src/pages/stocktake/stocktake.vue`、`src/pages/move/move.vue`；共用 `src/api/warehouse-operations.js`、`src/stores/warehouse-work.js` |
-| 商品移库真实作业 | `src/pages/move/move.vue`、`src/api/warehouse-operations.js`、`src/stores/warehouse-work.js` |
 | 换标真实作业 | `src/pages/relabel/relabel.vue`、`src/api/relabel.js` |
-| 现场查询真实作业 | `src/pages/query/query.vue`、`src/api/warehouse-operations.js` |
+| 现场查询 | `src/pages/query/query.vue`；同上库内API |
-| 排车拣货与发车 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`、`src/stores/fulfillment.js` |
+| 排车拣货、整车发车与证照提醒 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`（`departDispatch`）、`src/stores/fulfillment.js` |
-| 整车发车与证照提醒 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js` 的 `departDispatch` |
 | 普通/一件代发出库 | `src/pages/outbound/outbound.vue`、`src/api/fulfillment.js`、`src/stores/fulfillment.js` |
 | 扫码设备与诊断 | `src/utils/scan-broadcast.js`、`src/pages/scanner-test/scanner-test.vue` |
 | 作业记录与人员 | `src/pages/history/history.vue`、`src/pages/profile/profile.vue` |
@@ -65,48 +54,44 @@
 
 ## 海外业务接口边界
 
-- 库内、换标、收货、排车与出库只调用专用 `/api/pda/**`，客户身份、绑定仓及资源范围由服务端校验；不得借用平台、客户或内部接口绕过授权。
+- 库内/换标/收货/排车/出库/查询仅用 `/api/pda/**` API/DTO，经 `gateway` 显式PDA路由，不直连Lastleg/借平台、客户、内部接口。Gateway/服务端校验Token、`lastleg:pda:operate`、冻结仓、客户/资源归属；工作台 `available`、本地客户/仓ID不代替授权。
-- 前端只展示服务端业务标识与操作资格；写操作保留稳定幂等键，失败/409 后重新读取权威状态，不把网络超时判成操作未执行或已成功。
+- 仅展示服务端业务标识/资格；写操作留稳定幂等键，失败/409重读权威状态，超时不判未执行/成功。
-- 修改收货、退货、移库、托盘、换标、发车、照片或任务恢复前，必须定向读取 `docs/business-index.md` 的对应页面行及“海外业务接口边界”条款；专项检查仍按下文质量门禁执行。
+- 收货/退货/移库/托盘/换标/发车/照片/恢复变更须读 `docs/business-index.md` 对应页面行及“海外业务接口边界”，执行专项门禁。
-- 仓储转运按托盘分别保存箱数、长宽高（cm）和毛重（kg），体积按本托尺寸计算；SKU件数逐种核对差异，不以预报箱数强制核平。箱唛沿用客户预报编号，PDA不得另造新箱号；测量完成前客户与平台可增加整单预报箱数，不选SKU，箱内SKU以PDA实点为准，PDA刷新时合并新箱并保留本机草稿，清点提交携带forecastPackageCount拦截旧快照。生成托盘号后锁定该卡测量数据，必须取得服务端绑定确认且至少有一张现场照片才能完成打托；完成请求提交稳定幂等键、照片文件 ID，SKU实收件数有差异时在完成入口弹窗必填差异原因，不重复提交整份托盘测量。重新进入从详情恢复托盘和鉴权照片；标签使用服务端 `labelDownloadPath` 下载 PDF，打开文档不等于真机打印完成。
+- 仓储转运逐托存箱数、长宽高（cm）、毛重（kg），本托尺寸算体积；逐SKU核对件数差异，不以预报箱数强制核平。沿用客户预报箱唛，不造箱号。测量完成前客户/平台可增整单预报箱数、不选SKU，箱内SKU以PDA实点为准；刷新合并新箱、留本机草稿，清点传forecastPackageCount拦旧快照。生成托盘号锁该卡测量，服务端绑定确认且至少一张现场照片才可完成打托；完成传稳定幂等键、照片文件ID，SKU实收差异在完成弹窗必填原因，不重传测量。重进从详情恢复托盘/鉴权照片；`labelDownloadPath` 下载PDF，打开不等于真机打印。
 
-- 换标目标确认即提交拆托合托，不再二次点击底部提交。`RelabelPalletWork.vue` 按当前轮次 `PALLET_BIND` 最新记录提供逐箱改绑，扫描新目标后弹窗确认，使用既有 `relabel-disassemble` 精确来源路径（不传 `actualSource`）；同目标不发写请求。服务器持有库存、托盘版本与幂等约束，已排车或出库禁止直接改绑。离线回归 `tests/relabel-pallet-work.test.mjs`，不等同真机验收。
+- 换标目标确认即提交拆合托，无底部二次提交。下述组件按本轮最新 `PALLET_BIND` 逐箱改绑，扫新目标弹窗确认，经 `relabel-disassemble` 精确来源路径（不传 `actualSource`）；同目标不写。服务端约束库存/托盘版本及幂等，已排车/出库禁改绑。回归 `tests/relabel-pallet-work.test.mjs`，离线非真机验收。
 
-- SKU 正常作业固定显示一个旧SKU扫描框，通过 `relabel-tasks/{relabelNo}/skus/scan` 提交 itemId、skuIndex 和旧SKU，不要求扫描新标签；多箱同SKU先选择具体明细。服务端每条保存 `SKU_SCAN` 历史，页面按当前返工轮次隐藏已完成子项；全部SKU完成才完成箱的SKU阶段，混合单仍需箱唛阶段。箱唛待处理列表同样隐藏已完成项。回归 `tests/relabel-quick-sku.test.mjs`。
+- SKU仅一个旧SKU扫描框，经 `relabel-tasks/{relabelNo}/skus/scan` 传itemId、skuIndex、旧SKU，不要求新标签；多箱同SKU先选明细。逐条存 `SKU_SCAN`，按本轮返工隐藏完成项；全SKU完成才完成箱SKU阶段，混合单还需箱唛阶段，箱唛列表也隐藏完成项。回归 `tests/relabel-quick-sku.test.mjs`。
 
-- 换标执行页内嵌 `src/components/RelabelPalletWork.vue`：`relabel-sources` 展示原入仓单各托盘箱数；选择来源库存行并扫描实托、输入拆出箱数、核对本批已完成换标箱，再扫描目标托盘合托。每次一个来源库存行，可分批处理多个托盘，无需为拆托额外逐箱扫码。`relabel-disassemble.actualSource` 原子调整本单冻结记账来源并移动库存，目标仍归原入仓单，不新建入库。仅同新目的仓合托；新增托盘不等待客户确认，409后刷新重扫。H5 提供标签打印，原生打印设备适配尚未完成；不能宣称生成托盘号即打印成功。回归 `tests/relabel-pallet-work.test.mjs`。
+- 换标页内嵌 `src/components/RelabelPalletWork.vue`；`relabel-sources` 展示原入仓单逐托箱数。每次选一来源库存行、扫实托、填拆出箱数、核本批已换标箱、扫目标合托；可分批多托，拆托不额外逐箱扫。`relabel-disassemble.actualSource` 原子调整本单冻结记账来源/移库存，目标归原入仓单、不新入库；仅同新目的仓合托，新托不等客户确认，409刷新重扫。H5可印标签，原生打印未适配，生成托盘号非打印成功；回归见逐箱改绑。
 
-- 换标任务标明类型，仅显示实际明细需要的 Tab。混合明细同时进入箱唛/SKU 作业，服务端分开保存两部分进度，`cartonProcessedPackages/skuProcessedPackages` 决定各 Tab 待处理数量；两项均完成后整箱计数一次，不能仅扫箱唛就视为 SKU 完成。
+- 换标标类型，仅显明细所需Tab；混合明细做箱唛/SKU两项，服务端分存进度，`cartonProcessedPackages/skuProcessedPackages` 定各Tab待处理数；两项完成整箱计一次，扫箱唛非SKU完成。
 
-- 换标完工提交使 PDA 任务进入 `WAIT_REVIEW`，申请进入 `CUSTOMER_CONFIRM_PENDING`，客户确认原子完成复核并释放后续履约资格。PDA 复核池只读；平台通过专用 `/rework` 接口携带任务版本、幂等键和必填备注退回，历史事实归档后重新计数，PDA 展示 `reviewRemark` 并清空上一轮输入和照片草稿。
+- 换标完工后任务 `WAIT_REVIEW`、申请 `CUSTOMER_CONFIRM_PENDING`；客户确认原子复核/释放履约资格。PDA复核池只读；平台经 `/rework` 携任务版本/幂等键/必填备注退回，历史归档重计数；PDA显 `reviewRemark`、清上轮输入/照片草稿。
 
-- 换标执行完成照片以缩略图展示并支持大图预览、移除和重拍。重新进入任务通过 `relabel-tasks/{relabelNo}/photos/files/{fileId}/download` 鉴权读取，不持久化设备临时图片地址；重拍先上传成功再替换待提交文件 ID，失败保留原照片，移除只解绑待提交引用。
+- 换标完工照片支持缩略图/大图/移除/重拍；重进经 `relabel-tasks/{relabelNo}/photos/files/{fileId}/download` 鉴权读，不存设备临时地址。重拍上传成功才换待提交ID，失败留原图；移除仅解绑待提交引用。
 
-- 退货查询空态集中在 `src/api/return-receipt.js`、`src/api/return-packing.js`：仅 `startReturnReceipt`、`findReturnSkuCandidates`、`findPackingOrders` 将 `A0404/404` 转为无匹配结果；签收确认、合箱写入和标签读取不得套用此处理，权限、网络与服务错误仍须保留诊断并报错。回归见 `tests/return-receipt-api.test.mjs`、`tests/return-packing-api.test.mjs`，不得将查询无记录误报为写入成功。
+- 退货空态归上表签收API及 `src/api/return-packing.js`：仅 `startReturnReceipt/findReturnSkuCandidates/findPackingOrders` 将 `A0404/404` 转无匹配；签收确认/合箱写/标签读禁套用，权限/网络/服务错留诊断并报错，无记录非写成功；跑下述两项退货API回归。
-- `src/api/inbound.js` 已接入待卸柜候选、柜详情/prepare、current 恢复、三类照片签收、统一箱码定位入仓码、实物托盘解析、普通 FBA bulk/普通 OVERSEAS carton、一件代发 source pallet 整托收货及整柜完成；FBA bulk 不提交 `skuCode`，库存分配由服务端按计划明细完成；一件代发只提交国内冻结的来源托盘号，不允许逐箱或拆托收货。响应与 404/409 判定集中在 `src/api/receiving-adapter.js`，统一 Token 刷新与业务 401 单次重放由 `src/api/overseas.js` 统一处理。
+- 上表入仓API接待卸柜候选、详情/prepare、current、三类照片、箱码定位、实托解析、普通FBA bulk/OVERSEAS carton、一件代发source pallet整托及整柜完成。FBA bulk不传 `skuCode`，服务端按计划分库存；一件代发仅传国内冻结来源托盘号，禁逐箱/拆托收货。响应/404/409归 `src/api/receiving-adapter.js`，Token刷新/业务401单次重放归 `src/api/overseas.js`。
-- 入仓摘要、箱码解析和实收响应的 `assigned/mergeAllowed/urgent/mergeHint` 只消费 Lastleg 返回值，布尔标志只有 `true` 生效，`mergeAllowed` 缺省为 `false`；合托仅作提示，不能改变收货资格或触发分配。首扫实物托盘只确认服务端已有托盘、库位与资源锁预留，不在设备端重新分配托盘、库位或资源锁；只提交业务箱码、托盘码及当前收货数量，最终资格由服务端决定。
+- 入仓摘要/箱码/实收的 `assigned/mergeAllowed/urgent/mergeHint` 仅读Lastleg；布尔仅 `true` 生效，`mergeAllowed` 默认 `false`。合托只提示，不改资格/触发分配；首扫仅确认服务端已有实托/库位/资源锁预留，设备端不重分配。仅传业务箱码/托盘码/收货数量，服务端定资格。
-- `src/api/overseas.js` 的 `overseasUrl` 统一拼接普通请求、上传和下载地址：先移除运行时 `apiBase` 末尾斜杠；当基址已以 `/api` 结尾时，再移除业务路径重复的 `/api` 前缀。各业务 API 不得自行拼接 `session.apiBase`，也不得依赖双斜杠或重复 `/api` 被网关容错。
+- `overseasUrl`（上述overseas.js）统一拼请求/上传/下载：去 `apiBase` 尾斜杠，基址以 `/api` 结尾则去业务路径重复 `/api`；禁自拼 `session.apiBase`，不靠网关容错双斜杠/重复前缀。
-- 待卸柜候选只消费服务端已按 Token 绑定仓过滤的结果，并严格校验每柜正式 `overseasWarehouseCode`、`overseasWarehouseName` 与 `warehouse-profile` 一致；字段缺失或仓不一致一律 fail-closed，不得从 FBA/业务目的仓或内部 ID 推导。候选保留服务端返回的未齐全柜并严格消费 `allPlansReady`、`operable`、`blockReason`、`plannedArrivalAt` 与柜级计划统计；`operable=false` 只能查看只读摘要，不得调用 prepare。候选顺序沿用服务端“可操作优先、同组计划到仓时间升序、时间为空最后”的排序，前端不得用入仓码/计划数组长度自行推导就绪或把预计到港冒充计划到仓。
+- 待卸柜候选仅读服务端Token绑定仓过滤结果；逐柜验正式 `overseasWarehouseCode/overseasWarehouseName` 与 `warehouse-profile`，缺失/不符fail-closed，禁FBA/目的仓/内部ID推导。保留未齐全柜，严格取 `allPlansReady/operable/blockReason/plannedArrivalAt` 及柜统计；`operable=false` 仅只读摘要、禁prepare。沿用服务端可操作优先、同组计划到仓升序、空值末位；禁按入仓码/计划数组长度推就绪，禁预计到港替代计划到仓。
-- 候选详情、prepare 响应和 current 恢复都必须重复校验同一接柜仓编码；prepare 只建立已分配柜的作业会话，不得当作首次认领。服务端仓冲突的 `409/A0409` 中文错误保留 `requestId`/`traceId`；会话建立后仍按既有 current 恢复与完成前禁止切柜逻辑处理。
+- 详情/prepare/current均重验接柜仓码；prepare仅建已分配柜会话，非首次认领。仓冲突 `409/A0409` 留中文错误及 `requestId/traceId`；建后仍走current恢复。
-- `src/api/pallet.js` 只调用 Lastleg 托盘专用 PDA Controller；前端提交服务端扫码返回的 `palletVersion`、`positionVersion` 和随机幂等键，不提交客户、仓库或库位标识。409 后必须重新扫码获取最新版本，禁止用旧库存快照继续作业。
+- 上表托盘API仅用Lastleg专用PDA Controller，传扫码的 `palletVersion/positionVersion`、随机幂等键，不传客户/仓/库位；409重扫取新版本，禁旧库存快照。
-- 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 `customerId`、`planNo`、`allocationId`、`warehouseId` 或 `locationId`。409 必须引导账号恢复当前柜，完成前不得切柜。
+- 请求身份/资源范围仅取Token/current，不传 `customerId/planNo/allocationId/warehouseId/locationId`；409引导账号恢复当前柜，完成前禁切柜。
-- 签收照片固定为三个角色且每个角色只有一个当前文件；上传成功后使用服务端 `downloadPath` 在当前会话内鉴权读取。更换失败时保留原 `fileId` 和可提交状态，无原图的失败槽不得计入 `photosReady`；本地临时路径仅用于本次设备预览，不作为跨会话文件事实。
+- 签收照片三角色各一当前文件；上传后以服务端 `downloadPath` 会话内鉴权读。换图失败留原 `fileId`/可提交状态，无原图失败槽不计 `photosReady`；临时路径仅本次预览。
-- 库内、换标与现场查询只调用 `/api/pda/**` 业务 API/DTO，并统一受 `lastleg:pda:operate`、Token 冻结仓库范围和服务端资源归属约束；写操作必须保留稳定幂等键，409 后重新读取服务端状态，不得把平台、客户或内部接口直接暴露给 PDA。
+- 柜号签收入仓用Lastleg `/api/pda/v1/last-leg/receiving-containers/**`，退货签收/合箱分别用 `/api/pda/v1/last-leg/return-receipts/**`、`/api/pda/v1/last-leg/return-inventory/**`，入口见上表。
-- 柜号签收入仓调用 Lastleg `/api/pda/v1/last-leg/receiving-containers/**`；退货签收与合箱分别调用 `/api/pda/v1/last-leg/return-receipts/**`、`/api/pda/v1/last-leg/return-inventory/**`，具体入口见上表。浏览器或设备请求必须经统一 `gateway` 的显式 PDA 路由，不得直连 Lastleg。
+- 排车/出库网络失败留草稿/幂等键，恢复看服务端任务。发车看 `canDepart/departBlockReason`，拣货/完成同时核 `canPick/pickBlockReason`；平台未转派送生成 `WAIT_OUTBOUND` 出库单禁发车，完成/发车成功禁重提。
-- 海外业务 Token、PDA 权限和可信身份最终由 Gateway 与服务端校验；前端不得用工作台 `available`、本地客户 ID 或仓库 ID 代替授权和资源归属校验。
-- 排车和出库入口只调用专用 PDA 接口；客户与冻结海外仓范围由 Token、Gateway 和服务端解析，前端不提交 `customerId`、`warehouseId`，也不把内部数据库 ID 展示成业务编号。网络失败保留草稿和幂等键，恢复后以服务端任务状态为准；排车详情返回的 `canDepart`、`departBlockReason` 是发车资格依据，拣货及完成按钮同时核对当前单`canPick/pickBlockReason`；平台未转派送生成 `WAIT_OUTBOUND` 出库单时不得发车；完成或发车成功后不得重复提交。派送始终由 Admin/Client 承载。
 
 ## 质量门禁
 
-- 已发车排车详情按需挂载`src/components/DispatchHandoverStatus.vue`，通过`src/api/trip-handover.js`读取当前派送资源和最近交接；每次进入/刷新一次GET，列表不逐行请求。仅只读、不提交客户或仓ID；后台确认交接，已完成派送保留完成时资源。回归`tests/trip-handover.test.mjs`。
+- 已发车详情按需挂载 `src/components/DispatchHandoverStatus.vue`，经 `src/api/trip-handover.js` 读当前派送资源/最近交接；进入/刷新各一次GET，列表不逐行请求。只读；后台确认交接，已完成派送留完成时资源。回归 `tests/trip-handover.test.mjs`。
 
 - 安装：`npm install`；检查：`npm test`。
-- 仓储转运测量、打托、照片或标签入口变更运行 `node --test tests/warehouse-transfer-api.test.mjs tests/project-contract.test.mjs tests/workbench-availability.test.mjs`；静态合同不替代真实扫码、绑定及打印验收。
+- 专项用 `node --test`：转运测量/打托/照片/标签变更跑 `tests/warehouse-transfer-api.test.mjs`；退货签收/合箱/工作台变更先跑 `tests/return-receipt-api.test.mjs tests/return-packing-api.test.mjs`；两类均加 `tests/project-contract.test.mjs tests/workbench-availability.test.mjs`。静态/离线不替代真实API、真机扫码/绑定/打印。
-- 退货签收、合箱或工作台入口变更先运行 `node --test tests/return-receipt-api.test.mjs tests/return-packing-api.test.mjs tests/project-contract.test.mjs tests/workbench-availability.test.mjs`；离线检查不替代真实 API 联调与真机扫码验收。
+- H5编译链 `vue-i18n` 固定 `9.1.9`，禁范围版本/单独升级；依赖变更同步 `package.json`、`package-lock.json`、现有 `pnpm-lock.yaml`，至少跑H5编译。
-- 当前 uni-app H5 编译链要求 `vue-i18n` 精确固定为 `9.1.9`；不得改回范围版本或单独升级。依赖变更必须同步 `package.json`、`package-lock.json` 与现有 `pnpm-lock.yaml`，并至少执行 H5 编译门禁。
+- 产品为海外PDA App；`npm run build:h5` 仅浏览器调试/模板门禁，App资源用 `npm run build:app`。APK/IPA须在HBuilderX/正式原生打包环境以独立AppID/签名验证，资源编译非APK真机验收。
-- 正式产品形态是海外 PDA App；`npm run build:h5` 仅用于浏览器调试和模板编译门禁，App 资源编译使用 `npm run build:app`。
+- 改 `src/manifest.json` 图标映射或 `static/app-icons/` 跑 `node --test tests/app-icons.test.mjs`；禁缺声明尺寸、同一错尺寸占位、复制国内AppID/签名。
-- APK/IPA 必须在 HBuilderX 或正式原生打包环境中使用独立 AppID 与签名验证；仅通过 App 资源编译不得声称 APK 真机验收完成。
+- 改任务/入仓码/柜号/托盘码/库位码等可见标识，以 `node --test` 跑上表标识隔离测试；禁内部ID回退业务号。
-- 修改 `src/manifest.json` 图标映射或 `static/app-icons/` 时运行 `node --test tests/app-icons.test.mjs`，不得缺失已声明尺寸、用同一错误尺寸文件占位或从国内 PDA 复制 AppID/签名。
+- 改更新协议/版本比较/强制更新/安装/重启跑 `node --test tests/app-update.test.mjs`；新增原生模块/权限/不兼容运行时能力须发海外APK，不能只发WGT或下载国内包。
-- 修改任务、入仓码、柜号、托盘码、库位码等用户可见标识时运行 `node --test tests/business-identifiers-ui.test.mjs`；不得以内部数据库 ID 作为业务编号回退。
-- 修改更新协议、版本比较、强制更新、安装或重启行为时运行 `node --test tests/app-update.test.mjs`；新增原生模块、权限或不兼容运行时能力必须发海外 APK，不能仅发布 WGT，也不能下载国内更新包。
 - 不提交 `node_modules/`、`dist/`、`unpackage/`、环境文件、签名证书或打包产物。

src/api/fulfillment.js

@@ -43,7 +43,7 @@ export function normalizeDispatchTask(value) {
 		...value, taskNo: String(value.taskNo || ''), dispatchNo: String(value.dispatchNo),
 		recordVersion: value.recordVersion, pickingReconciled: value.pickingReconciled === true,
 		actions: Object.fromEntries(Object.entries(value.actions || {}).map(([key, gate]) => [key, { ...gate, allowed: gate?.allowed === true }])),
-		items: value.items.map(item => ({ ...item, dispatchItemId: String(item.dispatchItemId || ''), palletNo: String(item.palletNo || ''),
+		items: value.items.map(item => ({ ...item, dispatchItemId: String(item.dispatchItemId || ''), sourceKey: String(item.sourceKey || ''), sourceBusinessType: item.sourceBusinessType == null ? null : String(item.sourceBusinessType), sourceBusinessNo: item.sourceBusinessNo == null ? null : String(item.sourceBusinessNo), palletNo: String(item.palletNo || ''),
 			scheduledPackages: dispatchCount(item.scheduledPackages), pickedPackages: dispatchCount(item.pickedPackages),
 			returnCartons: (item.returnCartons || []).map(carton => ({ ...carton, returnCartonId: String(carton.returnCartonId || ''), cartonMark: String(carton.cartonMark || ''), productQuantity: dispatchCount(carton.productQuantity) })),
 			positions: (item.positions || []).map(position => ({ ...position, positionId: String(position.positionId || ''), balanceId: String(position.balanceId || ''), availablePackages: dispatchCount(position.availablePackages), allocatedPackages: dispatchCount(position.allocatedPackages), pickedPackages: dispatchCount(position.pickedPackages) }))

src/pages/dispatch/dispatch.vue

@@ -11,8 +11,9 @@
 			<template v-if="!current && !loading"><view class="list-toolbar"><text class="list-title">排车任务</text><button :disabled="busy" @tap="loadTasks">刷新</button></view><view v-if="!tasks.length && !error" class="fulfillment-state">暂无排车任务，可扫描排车单号读取。</view><button v-for="task in tasks" :key="task.dispatchNo" class="task-card" @tap="openTask(task.dispatchNo)"><text class="business-code">{{ task.dispatchNo }}</text><text v-if="task.dispatchNo === recentTaskNo" class="recent-badge">上次作业</text><text class="status-badge">{{ stageLabel(task) }}</text><text class="task-meta">任务号 {{ task.taskNo || '—' }}</text></button></template>
 			<template v-if="current"><DispatchHandoverStatus v-if="departed" :dispatch-no="current.dispatchNo" :record-version="current.recordVersion" />
 				<view class="fulfillment-card summary-card"><view class="task-head"><text class="business-code">{{ current.dispatchNo }}</text><text class="status-badge">{{ stageLabel(current) }}</text></view><text class="task-meta">任务号 {{ current.taskNo || '—' }}</text><text v-if="!gate('PICK') && current.stage === 'LOADING'" class="gate-warning">{{ current.actions.PICK?.blockReason || '拣货资格尚未允许，请核对两级审核及当前作业状态' }}</text><view class="metrics"><view><text class="metric-value">{{ plannedPackages }}</text><text>计划箱数</text></view><view><text class="metric-value">{{ pickedPackages }}</text><text>真实已拣</text></view><view><text class="metric-value">{{ remainingPackages }}</text><text>未拣箱数</text></view></view></view>
-				<view v-for="item in current.items" :key="item.dispatchItemId" class="fulfillment-card item-card" :class="{ selected: selectedItem?.dispatchItemId === item.dispatchItemId }" @tap="selectPallet(item)"><view class="task-head"><text class="business-code">{{ item.palletNo || '未关联托盘码' }}</text><text>{{ item.pickedPackages }}/{{ item.scheduledPackages }}箱</text></view><text class="task-meta">{{ item.customerName || '—' }} · {{ routeLabel(item) }}</text><text v-for="carton in item.returnCartons" :key="carton.returnCartonId" class="task-meta">{{ carton.cartonMark }} · {{ carton.status === 'OUTBOUNDED' ? '已拣货' : '待扫描' }}</text><view class="progress"><view :style="{ width: `${itemProgress(item)}%` }"></view></view></view>
+				<view v-for="item in current.items" :key="item.dispatchItemId" class="fulfillment-card item-card" :class="{ selected: selectedItem?.dispatchItemId === item.dispatchItemId }" @tap="selectPallet(item)"><view class="task-head"><text class="business-code">{{ item.palletNo || '未关联托盘码' }}</text><text>{{ item.pickedPackages }}/{{ item.scheduledPackages }}箱</text></view><text class="task-meta">{{ item.sourceBusinessType === 'RELABEL_ORDER' ? '换标单号' : '来源业务号' }} {{ item.sourceBusinessNo || '—' }} · {{ item.customerName || '—' }} · {{ routeLabel(item) }}</text><text v-for="carton in item.returnCartons" :key="carton.returnCartonId" class="task-meta">{{ carton.cartonMark }} · {{ carton.status === 'OUTBOUNDED' ? '已拣货' : '待扫描' }}</text><view class="progress"><view :style="{ width: `${itemProgress(item)}%` }"></view></view></view>
 				<view v-if="!current.items.length" class="fulfillment-state">本车暂无货物，空单不能核平、装车或发车。</view>
+				<view v-if="sourceChoices.length > 1" class="fulfillment-card"><text class="card-title">请选择本次真实拣货来源</text><button v-for="item in sourceChoices" :key="item.dispatchItemId" :disabled="busy || Boolean(pendingCommand)" @tap="chooseSource(item)">{{ item.sourceBusinessNo || '—' }} · {{ item.customerName || '—' }} · 可拣{{ pickablePackages(item) }}箱</button></view>
 				<view v-if="selectedItem && selectedRemaining > 0" class="fulfillment-card"><text class="card-title">本次拣货：{{ selectedItem.palletNo || '来源箱唛' }}</text><text v-if="selectedItem.returnCartons.length">{{ selectedReturnCarton ? `已扫 ${selectedReturnCarton.cartonMark}` : '请扫描来源箱唛，每次一箱' }}</text><view v-else class="count-row"><text>拣货箱数</text><input type="number" :value="packages" :placeholder="`请输入 1-${selectedRemaining} 箱`" :disabled="busy || Boolean(pendingCommand)" @input="updatePackages" /><text>最多{{ selectedRemaining }}箱</text></view><button class="primary-button" :disabled="!canPick || busy || Boolean(pendingCommand)" @tap="submitPick">确认真实拣货</button></view>
 				<view v-if="current.stage === 'LOADING'" class="fulfillment-card gate-card"><text class="card-title">确认装车完成</text><text>{{ current.pickingReconciled ? 'PDA拣货已核平，确认实际装载后进入装车后。' : '先完成全部真实拣货，不能补录数量代替核平。' }}</text><text v-if="!gate('LOADING_COMPLETE')" class="gate-warning">{{ current.actions.LOADING_COMPLETE?.blockReason || '尚未获得装车完成资格' }}</text><button class="primary-button" :disabled="!canComplete || busy || Boolean(pendingCommand)" @tap="prepareLoading">核对实载并确认装车完成</button></view>
 				<view v-if="current.stage === 'AFTER_LOADING' || departed" class="fulfillment-card gate-card"><text class="card-title">实际发车</text><text v-if="departed" class="gate-success">本车已经实际发车，不重复提交。</text><text v-else-if="!gate('DEPART')" class="gate-warning">{{ current.actions.DEPART?.blockReason || '请先由后台完成本车全部客户的派送安排' }}</text><text v-else>装车完成与实际发车是两个动作，请确认现场已经发车。</text><button v-if="!departed" class="depart-button" :disabled="!canDepart || busy || Boolean(pendingCommand)" @tap="depart">确认整车发车</button></view>
@@ -33,11 +34,11 @@ import { toDispatchError } from '@/utils/dispatch-error.js'
 import { startScanBroadcast } from '@/utils/scan-broadcast.js'
 export default {
 	components: { PortalHeader, ScanTargetInput, DispatchHandoverStatus },
-	data() { return { user: session.currentUser, tasks: [], current: null, scanCode: '', loading: false, busy: false, error: null, successMessage: '', bootstrapped: false, resumeOnEntry: false, generation: 0, loadingPreview: null, loadingRows: [] } },
+	data() { return { user: session.currentUser, tasks: [], current: null, scanCode: '', loading: false, busy: false, error: null, successMessage: '', bootstrapped: false, resumeOnEntry: false, generation: 0, loadingPreview: null, loadingRows: [], sourceChoices: [], choiceCartonCode: '' } },
 	computed: {
 		recentTaskNo() { return fulfillment.dispatch.currentNo || '' }, pendingCommand() { return fulfillment.dispatch.pendingCommand }, packages() { return fulfillment.dispatch.packages },
-		selectedItem() { return this.current?.items.find(row => row.dispatchItemId === fulfillment.dispatch.dispatchItemId) || null },
+		selectedItem() { return this.current?.items.find(row => row.dispatchItemId === fulfillment.dispatch.dispatchItemId && row.sourceKey === fulfillment.dispatch.sourceKey) || null },
-		selectedReturnCarton() { return this.selectedItem?.returnCartons.find(row => row.cartonMark === fulfillment.dispatch.cartonCode && row.status === 'OUTBOUND_PENDING') || null },
+		selectedReturnCarton() { const matches = this.selectedItem?.returnCartons.filter(row => row.cartonMark === fulfillment.dispatch.cartonCode && row.status === 'OUTBOUND_PENDING') || []; return matches.length === 1 ? matches[0] : null },
 		selectedPosition() { return this.selectedItem?.positions.find(row => row.availablePackages > 0 && row.allocatedPackages > row.pickedPackages) || null },
 		selectedRemaining() { const remaining = Math.max(0, (this.selectedItem?.scheduledPackages || 0) - (this.selectedItem?.pickedPackages || 0)); return this.selectedItem?.returnCartons.length ? remaining : Math.min(remaining, this.selectedPosition?.availablePackages || 0, Math.max(0, (this.selectedPosition?.allocatedPackages || 0) - (this.selectedPosition?.pickedPackages || 0))) },
 		plannedPackages() { return (this.current?.items || []).reduce((sum, row) => sum + row.scheduledPackages, 0) }, pickedPackages() { return (this.current?.items || []).reduce((sum, row) => sum + row.pickedPackages, 0) }, remainingPackages() { return Math.max(0, this.plannedPackages - this.pickedPackages) },
@@ -54,10 +55,41 @@ export default {
 		startScanner() { this.stopScanner(); this._stopScanner = startScanBroadcast({ onScan: value => this.handleScan(value), onError: error => this.setError(error, '扫码广播注册失败') }) }, stopScanner() { this._stopScanner?.(); this._stopScanner = null },
 		updatePackages(event) { if (this.pendingCommand) return; const value = Number(event.detail.value); updateFulfillmentDraft('dispatch', { packages: Number.isFinite(value) ? value : 0 }) },
 		async loadTasks() { const generation = ++this.generation; await this.run(async () => { const result = await listDispatchTasks(); if (generation === this.generation) { this.tasks = result; this.current = null } }, true) },
-		async openTask(no) { if (this.pendingCommand && this.pendingCommand.dispatchNo !== no) return this.setError(new Error('请先核对原排车请求，不能切到另一张单执行'), '操作未完成'); const generation = ++this.generation; await this.run(async () => { const value = await getDispatchTask(no); if (generation !== this.generation) return; if (value.dispatchNo !== no) throw new Error('返回排车与扫描业务号不一致'); const same = fulfillment.dispatch.currentNo === no; this.current = value; updateFulfillmentDraft('dispatch', { currentNo: no, palletCode: same ? fulfillment.dispatch.palletCode : '', dispatchItemId: same ? fulfillment.dispatch.dispatchItemId : '', cartonCode: same ? fulfillment.dispatch.cartonCode : '', packages: same ? fulfillment.dispatch.packages : 1 }); this.scanCode = '' }, true) },
+		async openTask(no) { if (this.pendingCommand && this.pendingCommand.dispatchNo !== no) return this.setError(new Error('请先核对原排车请求，不能切到另一张单执行'), '操作未完成'); const generation = ++this.generation; await this.run(async () => { const value = await getDispatchTask(no); if (generation !== this.generation) return; if (value.dispatchNo !== no) throw new Error('返回排车与扫描业务号不一致'); const same = fulfillment.dispatch.currentNo === no; this.current = value; this.sourceChoices = []; this.choiceCartonCode = ''; updateFulfillmentDraft('dispatch', { currentNo: no, palletCode: same ? fulfillment.dispatch.palletCode : '', dispatchItemId: same ? fulfillment.dispatch.dispatchItemId : '', sourceKey: same ? fulfillment.dispatch.sourceKey : '', cartonCode: same ? fulfillment.dispatch.cartonCode : '', packages: same ? fulfillment.dispatch.packages : 1 }); this.scanCode = '' }, true) },
-		closeTask() { if (this.busy) return; this.current = null; this.loadingPreview = null; this.scanCode = ''; this.error = null; this.successMessage = ''; updateFulfillmentDraft('dispatch', { currentNo: '', palletCode: '', dispatchItemId: '', cartonCode: '', packages: 1 }); this.loadTasks() },
+		closeTask() { if (this.busy) return; this.current = null; this.loadingPreview = null; this.scanCode = ''; this.error = null; this.successMessage = ''; updateFulfillmentDraft('dispatch', { currentNo: '', palletCode: '', dispatchItemId: '', sourceKey: '', cartonCode: '', packages: 1 }); this.loadTasks() },
-		handleScan(raw) { const code = String(raw?.detail?.value ?? raw ?? this.scanCode).trim(); if (!code || this.busy || this.loading) return; if (this.pendingCommand) return this.setError(new Error('请先核对原排车操作结果'), '原请求未完成'); this.error = null; this.successMessage = ''; updateFulfillmentDraft('dispatch', { palletCode: '', dispatchItemId: '', cartonCode: '', packages: 1 }); if (!this.current || code === this.current.dispatchNo || code === this.current.taskNo) return this.openTask(code === this.current?.taskNo ? this.current.dispatchNo : code); const cartonItem = this.current.items.find(item => item.returnCartons.some(carton => carton.cartonMark === code)); if (cartonItem) { if (!cartonItem.returnCartons.some(carton => carton.cartonMark === code && carton.status === 'OUTBOUND_PENDING')) return this.setError(new Error('该箱已拣或不可出库'), '扫码未匹配'); this.selectPallet(cartonItem); updateFulfillmentDraft('dispatch', { cartonCode: code, packages: 1 }); this.scanCode = ''; playSuccessSound(); return } const matches = this.current.items.filter(item => item.palletNo === code && item.scheduledPackages > item.pickedPackages); if (matches.length > 1) return this.setError(new Error('此托盘包含多条待拣明细，请选择对应客户货物卡片'), '请选择明细'); if (!matches.length) return this.setError(new Error(this.current.items.some(item => item.palletNo === code) ? '该托盘已完成拣货，请勿重复操作' : '扫描未匹配本车实物托盘或来源箱唛'), '扫码未匹配'); this.selectPallet(matches[0]); this.scanCode = ''; playSuccessSound() },
+		handleScan(raw) {
-		selectPallet(item) { if (this.pendingCommand || this.busy || !item?.dispatchItemId || item.scheduledPackages <= item.pickedPackages) return; updateFulfillmentDraft('dispatch', { palletCode: item.palletNo, dispatchItemId: item.dispatchItemId, cartonCode: '', packages: 1 }); this.error = null },
+			const code = String(raw?.detail?.value ?? raw ?? this.scanCode).trim()
+			if (!code || this.busy || this.loading) return
+			if (this.pendingCommand) return this.setError(new Error('请先核对原排车操作结果'), '原请求未完成')
+			this.error = null; this.successMessage = ''; this.sourceChoices = []; this.choiceCartonCode = ''
+			updateFulfillmentDraft('dispatch', { palletCode: '', dispatchItemId: '', sourceKey: '', cartonCode: '', packages: 1 })
+			if (!this.current || code === this.current.dispatchNo || code === this.current.taskNo) return this.openTask(code === this.current?.taskNo ? this.current.dispatchNo : code)
+			const cartonItems = this.current.items.filter(item => item.returnCartons.some(carton => carton.cartonMark === code))
+			if (cartonItems.some(item => item.returnCartons.filter(carton => carton.cartonMark === code && carton.status === 'OUTBOUND_PENDING').length > 1)) return this.setError(new Error('同一来源返回重复待拣箱唛，请重新读取并核对箱记录'), '扫码未匹配')
+			const matches = cartonItems.length ? cartonItems.filter(item => item.scheduledPackages > item.pickedPackages && item.returnCartons.some(carton => carton.cartonMark === code && carton.status === 'OUTBOUND_PENDING')) : this.current.items.filter(item => item.palletNo === code && item.scheduledPackages > item.pickedPackages)
+			if (!matches.length) return this.setError(new Error(cartonItems.length ? '该箱已拣或不可出库' : this.current.items.some(item => item.palletNo === code) ? '该托盘已完成拣货，请勿重复操作' : '扫描未匹配本车实物托盘或来源箱唛'), '扫码未匹配')
+			this.sourceChoices = matches; this.choiceCartonCode = cartonItems.length ? code : ''
+			if (matches.length > 1) return this.setError(new Error('此扫码命中多条待拣明细，请按来源业务号、客户和可拣箱数选择'), '请选择明细')
+			this.chooseSource(matches[0])
+		},
+		chooseSource(item) {
+			if (this.pendingCommand || this.busy || !this.sourceChoices.some(row => row.dispatchItemId === item.dispatchItemId)) return
+			const cartonCode = this.choiceCartonCode
+			this.selectPallet(item)
+			if (fulfillment.dispatch.dispatchItemId !== item.dispatchItemId) return
+			if (cartonCode) updateFulfillmentDraft('dispatch', { cartonCode, packages: 1 })
+			this.scanCode = ''; playSuccessSound()
+		},
+		pickablePackages(item) {
+			const remaining = Math.max(0, item.scheduledPackages - item.pickedPackages)
+			return Math.min(remaining, item.returnCartons.length ? item.returnCartons.filter(row => row.status === 'OUTBOUND_PENDING').length : item.positions.reduce((sum, row) => sum + Math.min(row.availablePackages, Math.max(0, row.allocatedPackages - row.pickedPackages)), 0))
+		},
+		selectPallet(item) {
+			if (this.pendingCommand || this.busy || !item?.dispatchItemId || item.scheduledPackages <= item.pickedPackages) return
+			if (!item.sourceKey || item.sourceBusinessType === 'RELABEL_ORDER' && !item.sourceBusinessNo) return this.setError(new Error('来源业务身份未完整返回，请重新读取任务'), '请选择明细')
+			updateFulfillmentDraft('dispatch', { palletCode: item.palletNo, dispatchItemId: item.dispatchItemId, sourceKey: item.sourceKey, cartonCode: '', packages: 1 })
+			this.sourceChoices = []; this.choiceCartonCode = ''; this.error = null
+		},
 		async submitPick() { if (!this.canPick || this.pendingCommand) return; try { const body = { recordVersion: requireDispatchVersion(this.current.recordVersion), positionId: this.selectedReturnCarton ? null : this.selectedPosition.positionId, packages: this.selectedReturnCarton ? 1 : Number(this.packages), productQuantity: this.selectedReturnCarton?.productQuantity || 0, cartonMark: this.selectedReturnCarton?.cartonMark || null, remark: null }; beginDispatchCommand(this.current.dispatchNo, 'PICK', { ...body, dispatchItemId: this.selectedItem.dispatchItemId }); await this.recoverCommand() } catch (cause) { this.setError(cause, '拣货未提交') } },
 		async prepareLoading() { if (!this.canComplete || this.pendingCommand) return; await this.run(async () => { const data = await getDispatchLoading(this.current.dispatchNo); if (data.dispatchNo !== this.current.dispatchNo || data.pickingReconciled !== true || data.loadingComplete?.allowed !== true) throw new Error(data.loadingComplete?.blockReason || '装车前置未满足'); requireDispatchVersion(data.recordVersion); this.loadingPreview = data; this.loadingRows = data.pallets.map(row => { const confirmed = data.confirmedLoad?.manifestHash === data.manifestHash ? data.confirmedLoad.pallets.find(item => String(item.warehousePalletId) === String(row.warehousePalletId)) : null; return { warehousePalletId: String(row.warehousePalletId), palletNo: row.palletNo, palletSpaces: row.palletSpaces, deliveryIndex: row.deliveryIndex, weightKg: confirmed?.weightKg ?? (row.evidence.some(item => item.field === 'weightKg' && item.actual === true) ? row.weightKg : null), volumeCbm: confirmed?.volumeCbm ?? (row.evidence.some(item => item.field === 'volumeCbm' && item.actual === true) ? row.volumeCbm : null) } }) }) },
 		setMeasurement(row, field, event) { if (this.busy || this.pendingCommand) return; const value = event.detail.value === '' ? null : Number(event.detail.value); row[field] = value != null && Number.isFinite(value) ? value : null },

src/stores/fulfillment.js

@@ -4,7 +4,7 @@ const STORAGE_KEY = 'overseas-pda-fulfillment-draft-v2'
 
 const blankState = () => ({
 	scopeKey: '',
-	dispatch: { currentNo: '', palletCode: '', dispatchItemId: '', cartonCode: '', packages: 1, pendingCommand: null },
+	dispatch: { currentNo: '', palletCode: '', dispatchItemId: '', sourceKey: '', cartonCode: '', packages: 1, pendingCommand: null },
 	outbound: { currentTaskNo: '', scanCode: '', packages: 1, pendingKeys: {} }
 })
 

tests/dispatch-workflow.test.mjs

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises'
 import { fulfillment, beginDispatchCommand, patchDispatchCommand, finishDispatchCommand, discardRejectedDispatchCommand, restoreFulfillmentDraft, updateFulfillmentDraft, resetFulfillmentSession } from '../src/stores/fulfillment.js'
 import { requireDispatchVersion, dispatchVersionAtLeast, normalizeDispatchTask } from '../src/api/fulfillment.js'
 const source = (await readFile(new URL('../src/pages/dispatch/dispatch.vue', import.meta.url), 'utf8')).match(/<script>([\s\S]*?)<\/script>/)[1]
-const item = (overrides = {}) => ({ dispatchItemId: 'item-1', customerId: 'customer-1', customerName: '客户甲', palletNo: 'PALLET-1', scheduledPackages: 2, pickedPackages: 0, positions: [{ positionId: 'position-1', availablePackages: 2, allocatedPackages: 2, pickedPackages: 0 }], returnCartons: [], ...overrides })
+const item = (overrides = {}) => ({ dispatchItemId: 'item-1', sourceKey: 'source-1', sourceBusinessType: 'RELABEL_ORDER', sourceBusinessNo: 'RL-1', customerId: 'customer-1', customerName: '客户甲', palletNo: 'PALLET-1', scheduledPackages: 2, pickedPackages: 0, positions: [{ positionId: 'position-1', availablePackages: 2, allocatedPackages: 2, pickedPackages: 0 }], returnCartons: [], ...overrides })
 test('native string quantities normalize without changing Long identity or version', () => {
   const id = '9007199254740993'
   const value = normalizeDispatchTask(JSON.parse(JSON.stringify({ dispatchNo: 'PC/1', recordVersion: id, items: [item({ dispatchItemId: id, scheduledPackages: '12', pickedPackages: '0', positions: [{ positionId: id, balanceId: id, availablePackages: '12', allocatedPackages: '12', pickedPackages: '0' }], returnCartons: [{ returnCartonId: id, productQuantity: '24' }] })] })))
@@ -101,3 +101,54 @@ test('position picking is bounded by this dispatch allocation and skips already
   state.selectPallet(state.current.items[0]); assert.equal(state.selectedPosition.positionId, 'actual-position'); assert.equal(state.selectedRemaining, 1)
   updateFulfillmentDraft('dispatch', { packages: 2 }); assert.equal(state.canPick, false)
 })
+test('a shared pallet exposes both relabel sources and picking the second preserves its exact position and quantity', async () => {
+  storage(); const rows = [item({ scheduledPackages: 3 }), item({ dispatchItemId: 'item-2', sourceKey: 'source-2', sourceBusinessNo: 'RL-2', customerId: 'customer-2', customerName: '客户乙', scheduledPackages: 5, positions: [{ positionId: 'position-2', availablePackages: 5, allocatedPackages: 5, pickedPackages: 0 }] })]
+  let sent
+  const state = page({ pickDispatchItem: async (...args) => { sent = args; return proof(fulfillment.dispatch.pendingCommand) }, getDispatchTask: async () => task({ recordVersion: 1, items: rows.map((row, index) => index ? { ...row, pickedPackages: 5 } : row) }) })
+  state.current = task({ items: rows }); state.handleScan('PALLET-1')
+  assert.equal(fulfillment.dispatch.dispatchItemId, ''); assert.deepEqual(state.sourceChoices.map(row => [row.sourceBusinessNo, row.customerId, state.pickablePackages(row)]), [['RL-1', 'customer-1', 2], ['RL-2', 'customer-2', 5]])
+  state.chooseSource(state.sourceChoices[1]); state.updatePackages({ detail: { value: '5' } }); await state.submitPick()
+  assert.equal(sent[1], 'item-2'); assert.equal(sent[2].positionId, 'position-2'); assert.equal(sent[2].packages, 5); assert.equal(state.canComplete, false)
+})
+test('an ambiguous source carton requires explicit source selection and never picks the first matching item', async () => {
+  storage(); let sent
+  const rows = [item({ returnCartons: [{ returnCartonId: 'carton-1', cartonMark: 'SHARED-MARK', status: 'OUTBOUND_PENDING', productQuantity: 2 }] }), item({ dispatchItemId: 'item-2', sourceKey: 'source-2', sourceBusinessNo: 'RL-2', customerId: 'customer-2', returnCartons: [{ returnCartonId: 'carton-2', cartonMark: 'SHARED-MARK', status: 'OUTBOUND_PENDING', productQuantity: 7 }] })]
+  const state = page({ pickDispatchItem: async (...args) => { sent = args; return proof(fulfillment.dispatch.pendingCommand) }, getDispatchTask: async () => task({ recordVersion: 1, items: rows }) })
+  state.current = task({ items: rows }); state.handleScan('SHARED-MARK')
+  assert.equal(state.sourceChoices.length, 2); assert.equal(fulfillment.dispatch.dispatchItemId, ''); assert.equal(state.canPick, false)
+  state.chooseSource(state.sourceChoices[1]); await state.submitPick()
+  assert.equal(sent[1], 'item-2'); assert.equal(sent[2].cartonMark, 'SHARED-MARK'); assert.equal(sent[2].productQuantity, 7); assert.equal(sent[2].positionId, null)
+})
+test('selection restoration cannot reuse the same item ID for a different logical source', () => {
+  storage(); const state = page(); state.selectPallet(state.current.items[0]); assert.equal(state.canPick, true)
+  state.current.items[0].sourceKey = 'different-source'; assert.equal(state.selectedItem, null); assert.equal(state.canPick, false)
+})
+for (const sourceType of ['INBOUND_PLAN', 'RETURN_RECEIPT']) test(`ordinary ${sourceType} null business fields survive real wire normalization and exact picking`, async () => {
+  storage(); let sent
+  const raw = JSON.parse(JSON.stringify({ dispatchNo: 'PC/1', taskNo: 'TASK-1', recordVersion: '0', status: 'ACTIVE', stage: 'LOADING', actions: { PICK: { allowed: true } }, pickingReconciled: false, items: [item({ sourceKey: `${sourceType}:source-1`, sourceBusinessType: null, sourceBusinessNo: null, scheduledPackages: '4', pickedPackages: '0', positions: [{ positionId: '9007199254740993', balanceId: '9007199254740994', availablePackages: '4', allocatedPackages: '4', pickedPackages: '0' }] })] }))
+  const normalized = normalizeDispatchTask(raw)
+  assert.equal(normalized.items[0].sourceBusinessType, null); assert.equal(normalized.items[0].sourceBusinessNo, null)
+  const state = page({ pickDispatchItem: async (...args) => { sent = args; return proof(fulfillment.dispatch.pendingCommand) }, getDispatchTask: async () => normalizeDispatchTask({ ...raw, recordVersion: 1 }) })
+  state.current = normalized; state.handleScan('PALLET-1'); assert.equal(state.canPick, true)
+  state.updatePackages({ detail: { value: '4' } }); await state.submitPick()
+  assert.equal(sent[1], 'item-1'); assert.equal(sent[2].positionId, '9007199254740993'); assert.equal(sent[2].packages, 4); assert.equal(sent[2].recordVersion, '0')
+  assert.equal('customerId' in sent[2], false)
+})
+test('RELABEL_ORDER still requires its true business number and all sources require sourceKey', () => {
+  storage(); const state = page()
+  state.selectPallet(item({ sourceBusinessNo: null })); assert.equal(fulfillment.dispatch.dispatchItemId, ''); assert.match(state.error.message, /来源业务身份/)
+  state.selectPallet(item({ sourceKey: '', sourceBusinessType: null, sourceBusinessNo: null })); assert.equal(fulfillment.dispatch.dispatchItemId, '')
+})
+test('duplicate matching carton facts inside one source fail closed rather than taking its first carton', () => {
+  storage(); const state = page()
+  state.current = task({ items: [item({ returnCartons: ['one', 'two'].map(returnCartonId => ({ returnCartonId, cartonMark: 'DUPLICATE', status: 'OUTBOUND_PENDING', productQuantity: 1 })) })] })
+  state.handleScan('DUPLICATE'); assert.match(state.error.message, /重复待拣箱唛/); assert.equal(fulfillment.dispatch.dispatchItemId, ''); assert.equal(state.canPick, false)
+})
+test('two picked logical sources use the single authoritative physical loading row without duplicating measurements', async () => {
+  storage(); const rows = [item({ pickedPackages: 2 }), item({ dispatchItemId: 'item-2', sourceKey: 'source-2', sourceBusinessNo: 'RL-2', pickedPackages: 2 })]
+  const preview = { dispatchNo: 'PC/1', recordVersion: 0, manifestHash: 'one-physical-pallet', pickingReconciled: true, loadingComplete: { allowed: true }, pallets: [{ warehousePalletId: '21', palletNo: 'PALLET-1', palletSpaces: 1, deliveryIndex: 1, weightKg: 100, volumeCbm: 2, evidence: [{ field: 'weightKg', actual: true }, { field: 'volumeCbm', actual: true }] }] }
+  let sent
+  const state = page({ getDispatchLoading: async () => preview, completeDispatchLoading: async (...args) => { sent = args; return proof(fulfillment.dispatch.pendingCommand) }, getDispatchTask: async () => task({ recordVersion: 1, stage: 'AFTER_LOADING', items: rows, pickingReconciled: true }) })
+  state.current = task({ items: rows, pickingReconciled: true }); await state.prepareLoading(); assert.equal(state.loadingRows.length, 1)
+  await state.completeLoading(); assert.deepEqual(sent[1].measurements, [{ warehousePalletId: '21', palletSpaces: 1, weightKg: 100, volumeCbm: 2, deliveryIndex: 1 }])
+})

tests/fulfillment-workflows.test.mjs

@@ -240,10 +240,10 @@ test('native action gates reject strings and retain server block reasons', () =>
 async function dispatchScanHarness(items) {
  const source = (await read('../src/pages/dispatch/dispatch.vue')).match(/<script>([\s\S]*?)<\/script>/)[1]
  const draft={palletCode:'OLD',dispatchItemId:'old',cartonCode:''};let sounds=0
- const deps={PortalHeader:{},ScanTargetInput:{},DispatchHandoverStatus:{},updateFulfillmentDraft:(_,value)=>Object.assign(draft,value),playSuccessSound:()=>{sounds++}}
+ const deps={PortalHeader:{},ScanTargetInput:{},DispatchHandoverStatus:{},fulfillment:{dispatch:draft},updateFulfillmentDraft:(_,value)=>Object.assign(draft,value),playSuccessSound:()=>{sounds++}}
  const definition=new Function(...Object.keys(deps),source.replace(/^\s*import .*$/gm,'').replace('export default','return'))(...Object.values(deps))
- const state={current:{dispatchNo:'DS-TEST',items:items.map(item=>({...item,returnCartons:item.returnCartons||[]}))},error:{message:'previous error'},successMessage:'',setError(error){this.error={message:error.message}}}
+ const state={current:{dispatchNo:'DS-TEST',items:items.map(item=>({sourceKey:`source-${item.dispatchItemId}`,sourceBusinessType:'RELABEL_ORDER',sourceBusinessNo:`RL-${item.dispatchItemId}`,positions:[],...item,returnCartons:item.returnCartons||[]}))},error:{message:'previous error'},successMessage:'',setError(error){this.error={message:error.message}}}
- state.selectPallet=definition.methods.selectPallet.bind(state)
+ state.selectPallet=definition.methods.selectPallet.bind(state);state.chooseSource=definition.methods.chooseSource.bind(state)
  return {state,draft,scan:definition.methods.handleScan.bind(state),sounds:()=>sounds}
 }