pda-overseas-uniapp/AGENTS.md

# Overseas PDA Uni-app Instructions

## 快速读取顺序

1. 先用“页面与能力快速索引”定位 `src/pages.json`、工作台或最小页面；页面业务配置从 `src/data/overseas-workbench.js` 进入，不扫描 `src/uni_modules/`。
2. 登录、Token 或统一入口请求先读 `src/api/auth.js`、`src/stores/session.js`、`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`；纯页面改动不自动读取后端指引。

最小读取集按任务保持在适用指引和目标页面/API；纯展示任务不增加服务指引，服务端判断才读直接服务指引，跨服务状态或鉴权无法判断时再增加相关方。读取预算遵循根指引的行数与字符数标准，先读适用规则，再检索业务命中段，不全文加载海外仓 README。

## 项目定位

- 本项目是“柏悦物流海外版”独立 uni-app Vue 3 工程，面向海外仓现场人员。
- 工程必须独立安装、构建和发布，不得依赖 `apps/pda-uniapp/` 或仓库外 `pda-shared` 目录。
- 当前设备端业务范围包括海外仓入仓、退货签收与合箱、库内、换标、库存/库位/托盘查询，以及排车拣货、普通/一件代发出库任务、任务完成和发车；派送与客户回访由 Admin/Client 承载，国内集装箱拣货/装柜由国内 PDA 承载。

## 服务与发布边界

- 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 清理会话，不得只依赖页面入口隐藏。
- 并发 401 只允许一次 refresh；统一 Token 和权限快照完整校验后原子替换，主体或绑定仓改变时清理会话并重新登录，每个原请求或照片上传最多重放一次。刷新失败清理本地会话，业务错误和网络错误保留 code、requestId、traceId 或 network 诊断。
- 国内与海外 AppID、Android 包名、签名、版本号、构建产物和在线更新通道必须独立。
- `src/manifest.json` 中的 AppID 在正式打包前由海外版所属 DCloud 账号创建；不得伪造或复用国内 AppID。
- 环境地址只通过 `.env.local` 等未提交环境文件配置，不写入源码。
- 海外 Android App 启动后仅在 `APP-PLUS` 调用 `src/utils/app-update.js`，通过海外独立 `VITE_PDA_UPDATE_URL` 检查 HTTPS APK/WGT；强制更新不可跳过，WGT 安装后立即重启。更新服务、AppID、包名、签名和版本序列均不得与国内 PDA 混用。

## 工程入口

- 源码根：`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` 读取命中条款；涉及业务行为变更时必须核对对应细则，纯定位不全文加载。保留所有适用的最近模块指引。

表中路径均相对本应用根目录。

| 目标 | 首个入口 |
|---|---|
| 页面注册与启动 | `src/pages.json`、`src/main.js`、`src/App.vue` |
| AppID、平台图标与打包资源 | `src/manifest.json`、`static/app-icons/` |
| Android APK/WGT 在线更新 | `src/App.vue`、`src/utils/app-update.js`、`.env.example` |
| 登录、刷新与会话 | `src/pages/login/login.vue`、`src/api/auth.js`、`src/stores/session.js` |
| 海外仓工作台与模块入口 | `src/pages/home/home.vue`、`src/pages/module/module.vue` |
| 中英西语言设置 | `src/i18n/index.js`、`src/i18n/locales/`、`src/pages/profile/profile.vue` |
| 柜号签收、照片与入仓真实作业 | `src/pages/operation/operation.vue`、`src/components/ReceivingSessionSummary.vue`、`src/api/inbound.js` |
| 退货入库签收与合箱 | `src/pages/return-receipt/return-receipt.vue`、`src/pages/return-packing/return-packing.vue`、`src/api/return-receipt.js` |
| 退货箱内清点 | `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/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/dispatch/dispatch.vue`、`src/api/fulfillment.js`、`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` |
| 业务标识与内部 ID 隔离 | `tests/business-identifiers-ui.test.mjs`、`src/pages/`、`src/components/` |
| 本地契约测试 | `tests/project-contract.test.mjs`、`tests/navigation.test.mjs`、`tests/scan-broadcast.test.mjs` |

## 海外业务接口边界

- 库内、换标、收货、排车与出库只调用专用 `/api/pda/**`，客户身份、绑定仓及资源范围由服务端校验；不得借用平台、客户或内部接口绕过授权。
- 前端只展示服务端业务标识与操作资格；写操作保留稳定幂等键，失败/409 后重新读取权威状态，不把网络超时判成操作未执行或已成功。
- 修改收货、退货、移库、托盘、换标、发车、照片或任务恢复前，必须定向读取 `docs/business-index.md` 的对应页面行及“海外业务接口边界”条款；专项检查仍按下文质量门禁执行。
- 仓储转运按托盘分别保存箱数、长宽高（cm）和毛重（kg），体积按本托尺寸计算；SKU件数逐种核对差异，不以预报箱数强制核平。箱唛沿用客户预报编号，PDA不得另造新箱号；测量完成前客户与平台可增加整单预报箱数，不选SKU，箱内SKU以PDA实点为准，PDA刷新时合并新箱并保留本机草稿，清点提交携带forecastPackageCount拦截旧快照。生成托盘号后锁定该卡测量数据，必须取得服务端绑定确认且至少有一张现场照片才能完成打托；完成请求提交稳定幂等键、照片文件 ID，SKU实收件数有差异时在完成入口弹窗必填差异原因，不重复提交整份托盘测量。重新进入从详情恢复托盘和鉴权照片；标签使用服务端 `labelDownloadPath` 下载 PDF，打开文档不等于真机打印完成。

- 换标目标确认即提交拆托合托，不再二次点击底部提交。`RelabelPalletWork.vue` 按当前轮次 `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`。

- 换标执行页内嵌 `src/components/RelabelPalletWork.vue`：`relabel-sources` 展示原入仓单各托盘箱数；选择来源库存行并扫描实托、输入拆出箱数、核对本批已完成换标箱，再扫描目标托盘合托。每次一个来源库存行，可分批处理多个托盘，无需为拆托额外逐箱扫码。`relabel-disassemble.actualSource` 原子调整本单冻结记账来源并移动库存，目标仍归原入仓单，不新建入库。仅同新目的仓合托；新增托盘不等待客户确认，409后刷新重扫。H5 提供标签打印，原生打印设备适配尚未完成；不能宣称生成托盘号即打印成功。回归 `tests/relabel-pallet-work.test.mjs`。

- 换标任务标明类型，仅显示实际明细需要的 Tab。混合明细同时进入箱唛/SKU 作业，服务端分开保存两部分进度，`cartonProcessedPackages/skuProcessedPackages` 决定各 Tab 待处理数量；两项均完成后整箱计数一次，不能仅扫箱唛就视为 SKU 完成。

- 换标完工提交使 PDA 任务进入 `WAIT_REVIEW`，申请进入 `CUSTOMER_CONFIRM_PENDING`，客户确认原子完成复核并释放后续履约资格。PDA 复核池只读；平台通过专用 `/rework` 接口携带任务版本、幂等键和必填备注退回，历史事实归档后重新计数，PDA 展示 `reviewRemark` 并清空上一轮输入和照片草稿。

- 换标执行完成照片以缩略图展示并支持大图预览、移除和重拍。重新进入任务通过 `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`，不得将查询无记录误报为写入成功。
- `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` 统一处理。
- 入仓摘要、箱码解析和实收响应的 `assigned/mergeAllowed/urgent/mergeHint` 只消费 Lastleg 返回值，布尔标志只有 `true` 生效，`mergeAllowed` 缺省为 `false`；合托仅作提示，不能改变收货资格或触发分配。首扫实物托盘只确认服务端已有托盘、库位与资源锁预留，不在设备端重新分配托盘、库位或资源锁；只提交业务箱码、托盘码及当前收货数量，最终资格由服务端决定。
- `src/api/overseas.js` 的 `overseasUrl` 统一拼接普通请求、上传和下载地址：先移除运行时 `apiBase` 末尾斜杠；当基址已以 `/api` 结尾时，再移除业务路径重复的 `/api` 前缀。各业务 API 不得自行拼接 `session.apiBase`，也不得依赖双斜杠或重复 `/api` 被网关容错。
- 待卸柜候选只消费服务端已按 Token 绑定仓过滤的结果，并严格校验每柜正式 `overseasWarehouseCode`、`overseasWarehouseName` 与 `warehouse-profile` 一致；字段缺失或仓不一致一律 fail-closed，不得从 FBA/业务目的仓或内部 ID 推导。候选保留服务端返回的未齐全柜并严格消费 `allPlansReady`、`operable`、`blockReason`、`plannedArrivalAt` 与柜级计划统计；`operable=false` 只能查看只读摘要，不得调用 prepare。候选顺序沿用服务端“可操作优先、同组计划到仓时间升序、时间为空最后”的排序，前端不得用入仓码/计划数组长度自行推导就绪或把预计到港冒充计划到仓。
- 候选详情、prepare 响应和 current 恢复都必须重复校验同一接柜仓编码；prepare 只建立已分配柜的作业会话，不得当作首次认领。服务端仓冲突的 `409/A0409` 中文错误保留 `requestId`/`traceId`；会话建立后仍按既有 current 恢复与完成前禁止切柜逻辑处理。
- `src/api/pallet.js` 只调用 Lastleg 托盘专用 PDA Controller；前端提交服务端扫码返回的 `palletVersion`、`positionVersion` 和随机幂等键，不提交客户、仓库或库位标识。409 后必须重新扫码获取最新版本，禁止用旧库存快照继续作业。
- 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 `customerId`、`planNo`、`allocationId`、`warehouseId` 或 `locationId`。409 必须引导账号恢复当前柜，完成前不得切柜。
- 签收照片固定为三个角色且每个角色只有一个当前文件；上传成功后使用服务端 `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/**`，具体入口见上表。浏览器或设备请求必须经统一 `gateway` 的显式 PDA 路由，不得直连 Lastleg。
- 海外业务 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`。

- 安装：`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/return-receipt-api.test.mjs tests/return-packing-api.test.mjs tests/project-contract.test.mjs tests/workbench-availability.test.mjs`；离线检查不替代真实 API 联调与真机扫码验收。
- 当前 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 与签名验证；仅通过 App 资源编译不得声称 APK 真机验收完成。
- 修改 `src/manifest.json` 图标映射或 `static/app-icons/` 时运行 `node --test tests/app-icons.test.mjs`，不得缺失已声明尺寸、用同一错误尺寸文件占位或从国内 PDA 复制 AppID/签名。
- 修改任务、入仓码、柜号、托盘码、库位码等用户可见标识时运行 `node --test tests/business-identifiers-ui.test.mjs`；不得以内部数据库 ID 作为业务编号回退。
- 修改更新协议、版本比较、强制更新、安装或重启行为时运行 `node --test tests/app-update.test.mjs`；新增原生模块、权限或不兼容运行时能力必须发海外 APK，不能仅发布 WGT，也不能下载国内更新包。
- 不提交 `node_modules/`、`dist/`、`unpackage/`、环境文件、签名证书或打包产物。