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. 海外入仓、库存或仓储资源联调先读 ../../docs/海外仓业务/README.md、../../baiyue-firstleg/lastleg-service/AGENTS.md、warehouse-overseas-service/AGENTS.md 与 gateway-overseas/AGENTS.md。

项目定位

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

服务与发布边界

• 国内 Auth 是唯一账号和 Token 签发方；海外业务请求统一经 gateway-overseas。
• 登录、刷新和本地会话必须同时校验国内/海外 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。库存盘点底层页面与接口仍保留，但当前工作台不开放入口。

页面与能力快速索引

目标	入口	继续查询
页面注册与启动	src/pages.json、src/main.js、src/App.vue	src/manifest.json、全局样式与应用生命周期
AppID、平台图标与打包资源	src/manifest.json、static/app-icons/	Android/iOS 尺寸映射由 tests/app-icons.test.mjs 锁定；独立 AppID、签名和发布通道不得复用国内 PDA
Android APK/WGT 在线更新	src/App.vue、src/utils/app-update.js、.env.example、src/manifest.json	VITE_PDA_UPDATE_URL 使用海外独立 HTTPS 通道；合同 tests/app-update.test.mjs，H5 不执行更新逻辑
登录、刷新与会话	src/pages/login/login.vue、src/api/auth.js、src/stores/session.js	国内 Auth 签发 Token；API 根见 src/config/runtime.js
海外仓工作台与模块入口	src/pages/home/home.vue、src/pages/module/module.vue	src/data/overseas-workbench.js 是模块与作业可用性入口；首页通过 /api/pda/v1/last-leg/receiving-containers/warehouse-profile 读取 Token 绑定仓的中文主档名称
中英西语言设置	src/i18n/index.js、src/i18n/locales/、src/pages/profile/profile.vue	个人中心可选择并持久化 zh-CN、en、es；当前业务翻译资源仍为空，页面业务文案继续使用中文，不得把语言选择入口误报为全量翻译完成
柜号签收、照片与入仓真实作业	src/pages/operation/operation.vue、src/components/ReceivingSessionSummary.vue、src/api/inbound.js、src/api/receiving-adapter.js、src/api/overseas.js、src/stores/receiving.js	签收前展开显示国内空仓、半仓、满仓、锁仓和带锁码五类整柜只读照片，收货中折叠查看，单图加载失败只允许重试且不阻断拆柜；海外三个固定照片角色各一张，支持现场拍照、鉴权预览及更换失败保留原图；多计划同柜直接展示服务端 assigned/mergeAllowed/urgent/mergeHint，合托明确为现场可选而非完成门禁；扫码实收确认计划生成阶段已预留的真实托盘和库位，不在设备端重新分配。Backend lastleg-service/inboundplan/pda/controller/ReceivingContainerController.java、ReceivingContainerService.java，公网前缀 /api/pda/v1/last-leg/receiving-containers/**
退货入库签收与合箱	src/pages/return-receipt/return-receipt.vue、src/pages/return-packing/return-packing.vue、src/api/return-receipt.js、src/api/return-packing.js、src/stores/warehouse-work.js	签收优先扫描退货单号，也可扫描 SKU 后选择候选退货单，按本包实际 SKU 数量生成退货箱与计费批次；合箱只选择同客户已完成退货单的可用库存并录入新箱箱规；公网前缀 /api/pda/v1/last-leg/return-receipts/**、/api/pda/v1/last-leg/return-inventory/**
托盘管理真实作业	src/pages/pallet/pallet.vue、src/api/pallet.js	扫码查询托盘内容，按服务端返回的托盘/库存版本执行组托、拆托、换托和解绑；公网前缀 /api/pda/v1/last-leg/pallet-operations/**
库存盘点（入口隐藏）	src/pages/stocktake/stocktake.vue、src/api/warehouse-operations.js、src/stores/warehouse-work.js	底层创建、恢复、计数与提交实现仍保留；当前 src/data/overseas-workbench.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	同一页面按操作参数承载换标收货、执行与复核；执行页按当前单明细切换 SKU/箱唛 Tab，组合明细同时显示两类需求。SKU 逐条扫码旧新SKU并携带审批件数，箱唛扫码仓库唛头/新FBA箱唛；组合单按同箱保留两个Tab的核对输入，全部核对后只提交一次箱事实。认领同步处理中；支持拍照、异常/返工和幂等恢复
现场查询真实作业	src/pages/query/query.vue、src/api/warehouse-operations.js	同一页面按操作参数承载库存、库位与托盘查询，只展示稳定业务标识
排车拣货与发车	src/pages/dispatch/dispatch.vue、src/api/fulfillment.js、src/stores/fulfillment.js	任务列表/详情、托盘业务码扫码拣货、幂等完成；发车必须同时完成拣货核平、平台转派送并严格消费服务端 canDepart、departBlockReason，不得按本地数量自行推断；公网前缀 /api/pda/v1/last-leg/dispatches/**
普通/一件代发出库	src/pages/outbound/outbound.vue、src/api/fulfillment.js、src/stores/fulfillment.js	任务列表/详情、逐箱扫码、扫描 DP 托盘码原子拣取整托剩余箱件及幂等完成；公网前缀 /api/pda/v1/last-leg/outbound-tasks/**；派送由 Admin/Client 承载
扫码设备与诊断	src/utils/scan-broadcast.js、src/pages/scanner-test/scanner-test.vue	src/components/ScanTargetInput.vue、声音反馈工具；广播 Action/Extra 见本文件服务边界
作业记录与人员	src/pages/history/history.vue、src/pages/profile/profile.vue	会话隔离、退出清理和后续真实作业历史契约
业务标识与内部 ID 隔离	tests/business-identifiers-ui.test.mjs；页面入口 src/pages/、src/components/，会话映射 src/stores/session.js	页面只展示集装箱号、入仓码、箱码、托盘码、库位码、仓库名称等业务值；不得以 orderId、inboundId、planId、warehouseId、palletId、locationId、user.id 等内部 ID 或截断值回退，错误诊断保留 code、requestId、traceId
本地契约测试	tests/project-contract.test.mjs、navigation.test.mjs、scan-broadcast.test.mjs、audio-feedback.test.mjs	运行 npm test；不代表真实海外 API 或真机验收

海外业务接口边界

• 换标任务标明类型，仅显示实际明细需要的 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 或 /overseas-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-overseas 的显式 PDA 路由，不得直连 Lastleg，也不得改走国内 Gateway。

• 海外业务 Token、PDA 权限和可信身份最终由 Gateway 与服务端校验；前端不得用工作台 available、本地客户 ID 或仓库 ID 代替授权和资源归属校验。

• 排车和出库入口只调用专用 PDA 接口；客户与冻结海外仓范围由 Token、Gateway 和服务端解析，前端不提交 customerId、warehouseId，也不把内部数据库 ID 展示成业务编号。网络失败保留草稿和幂等键，恢复后以服务端任务状态为准；排车详情返回的 canDepart、departBlockReason 是发车按钮唯一门禁，平台未转派送生成 WAIT_OUTBOUND 出库单时不得发车；完成或发车成功后不得重复提交。派送始终由 Admin/Client 承载。

质量门禁

• 安装：npm install；检查：npm test。
• 退货签收、合箱或工作台入口变更先运行 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/、环境文件、签名证书或打包产物。