pda-overseas-uniapp/AGENTS.md

# 海外 PDA 指引

## 快速读取顺序

1. 按下表定位最小页面；业务配置见 `src/data/overseas-workbench.js`，不扫 `src/uni_modules/`。
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`。

仅读适用指引/目标页面/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-PLUS` 调 `src/utils/app-update.js`，以独立 `VITE_PDA_UPDATE_URL` 查HTTPS APK/WGT；强更禁跳过，WGT安装即重启。更新服务/标识/签名/版本序列不得与国内 PDA 混用。

- 源码根 `src/`；扫码广播 Action=`android.intent.action.SCANRESULT`，Extra=`value`。
- 均接真实PDA API；入仓账号锁柜、逐码核平；退货号/SKU候选进入，按本包实收生成退货箱/计费批次。换标含收货/执行/复核；盘点页面/API保留、工作台隐藏。

## 页面与能力快速索引

路径相对应用根；[业务索引](docs/business-index.md)存API/字段/状态/恢复。应用根 `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/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`；同上库内API |
| 排车理货审核、拣货、整车发车与证照提醒 | `src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`（`completeDispatchLoading`）、`src/stores/fulfillment.js` |
| 普通/一件代发出库 | `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/**` API/DTO，经 `gateway` 显式PDA路由，不直连Lastleg/借平台、客户、内部接口。Gateway/服务端校验Token、`lastleg:pda:operate`、冻结仓、客户/资源归属；工作台 `available`、本地客户/仓ID不代替授权。
- 仅展示服务端业务标识/资格；写操作留稳定幂等键，失败/409重读权威状态，超时不判未执行/成功。
- 收货/退货/移库/托盘/换标/发车/照片/恢复变更须读 `docs/business-index.md` 对应页面行及“海外业务接口边界”，执行专项门禁。
- 仓储转运逐托存箱数、长宽高（cm）、毛重（kg），本托尺寸算体积；逐SKU核对件数差异，不以预报箱数强制核平。沿用客户预报箱唛，不造箱号。测量完成前客户/平台可增整单预报箱数、不选SKU，箱内SKU以PDA实点为准；刷新合并新箱、留本机草稿，清点传forecastPackageCount拦旧快照。生成托盘号锁该卡测量，服务端绑定确认且至少一张现场照片才可完成打托；完成传稳定幂等键、照片文件ID，SKU实收差异在完成弹窗必填原因，不重传测量。重进从详情恢复托盘/鉴权照片；`labelDownloadPath` 下载PDF，打开不等于真机打印。

- 换标目标确认即提交拆合托，无底部二次提交。下述组件按本轮最新 `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可印标签，原生打印未适配，生成托盘号非打印成功；回归见逐箱改绑。

- 换标标类型，仅显明细所需Tab；混合明细做箱唛/SKU两项，服务端分存进度，`cartonProcessedPackages/skuProcessedPackages` 定各Tab待处理数；两项完成整箱计一次，扫箱唛非SKU完成。

- 换标完工后任务 `WAIT_REVIEW`、申请 `CUSTOMER_CONFIRM_PENDING`；客户确认原子复核/释放履约资格。PDA复核池只读；平台经 `/rework` 携任务版本/幂等键/必填备注退回，历史归档重计数；PDA显 `reviewRemark`、清上轮输入/照片草稿。

- 换标完工照片支持缩略图/大图/移除/重拍；重进经 `relabel-tasks/{relabelNo}/photos/files/{fileId}/download` 鉴权读，不存设备临时地址。重拍上传成功才换待提交ID，失败留原图；移除仅解绑待提交引用。

- 退货空态归上表签收API及 `src/api/return-packing.js`：仅 `startReturnReceipt/findReturnSkuCandidates/findPackingOrders` 将 `A0404/404` 转无匹配；签收确认/合箱写/标签读禁套用，权限/网络/服务错留诊断并报错，无记录非写成功；跑下述两项退货API回归。
- 上表入仓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`。合托只提示，不改资格/触发分配；首扫仅确认服务端已有实托/库位/资源锁预留，设备端不重分配。仅传业务箱码/托盘码/收货数量，服务端定资格。
- `overseasUrl`（上述overseas.js）统一拼请求/上传/下载：去 `apiBase` 尾斜杠，基址以 `/api` 结尾则去业务路径重复 `/api`；禁自拼 `session.apiBase`，不靠网关容错双斜杠/重复前缀。
- 待卸柜候选仅读服务端Token绑定仓过滤结果；逐柜验正式 `overseasWarehouseCode/overseasWarehouseName` 与 `warehouse-profile`，缺失/不符fail-closed，禁FBA/目的仓/内部ID推导。保留未齐全柜，严格取 `allPlansReady/operable/blockReason/plannedArrivalAt` 及柜统计；`operable=false` 仅只读摘要、禁prepare。沿用服务端可操作优先、同组计划到仓升序、空值末位；禁按入仓码/计划数组长度推就绪，禁预计到港替代计划到仓。
- 详情/prepare/current均重验接柜仓码；prepare仅建已分配柜会话，非首次认领。仓冲突 `409/A0409` 留中文错误及 `requestId/traceId`；建后仍走current恢复。
- 上表托盘API仅用Lastleg专用PDA Controller，传扫码的 `palletVersion/positionVersion`、随机幂等键，不传客户/仓/库位；409重扫取新版本，禁旧库存快照。
- 请求身份/资源范围仅取Token/current，不传 `customerId/planNo/allocationId/warehouseId/locationId`；409引导账号恢复当前柜，完成前禁切柜。
- 签收照片三角色各一当前文件；上传后以服务端 `downloadPath` 会话内鉴权读。换图失败留原 `fileId`/可提交状态，无原图失败槽不计 `photosReady`；临时路径仅本次预览。
- 柜号签收入仓用Lastleg `/api/pda/v1/last-leg/receiving-containers/**`，退货签收/合箱分别用 `/api/pda/v1/last-leg/return-receipts/**`、`/api/pda/v1/last-leg/return-inventory/**`，入口见上表。
- 理货审核沿既有排车详情；规则/回归见业务索引排车条目。
- 排车/出库网络失败留原命令/幂等键，恢复看服务端任务。排车拣货/装车完成核 `actions.PICK/LOADING_COMPLETE`；装车完成一次提交直接进入 `DELIVERING`，服务端自动生成派送并发车，无独立安排派送/发车入口。完成成功禁重提。

## 质量门禁

- 已发车详情按需挂载 `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/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编译。
- 产品为海外PDA App；`npm run build:h5` 仅浏览器调试/模板门禁，App资源用 `npm run build:app`。APK/IPA须在HBuilderX/正式原生打包环境以独立AppID/签名验证，资源编译非APK真机验收。
- 改 `src/manifest.json` 图标映射或 `static/app-icons/` 跑 `node --test tests/app-icons.test.mjs`；禁缺声明尺寸、同一错尺寸占位、复制国内AppID/签名。
- 改任务/入仓码/柜号/托盘码/库位码等可见标识，以 `node --test` 跑上表标识隔离测试；禁内部ID回退业务号。
- 改更新协议/版本比较/强制更新/安装/重启跑 `node --test tests/app-update.test.mjs`；新增原生模块/权限/不兼容运行时能力须发海外APK，不能只发WGT或下载国内包。
- 不提交 `node_modules/`、`dist/`、`unpackage/`、环境文件、签名证书或打包产物。