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保留、工作台隐藏。

页面与能力快速索引

路径相对应用根；业务索引存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/**，入口见上表。

• 理货审核沿既有排车详情；规则/回归见业务索引排车条目。

• 排车/出库网络失败留原命令和键；资格、阶段、恢复及装车资料API见业务索引排车条目。src/components/DispatchLoadingDocuments.vue 支持装车中同步上传，装车与资料均完成后自动派送，无独立发车入口。

质量门禁

• 已发车详情按需挂载 src/components/DispatchHandoverStatus.vue，经 src/api/trip-handover.js 读当前派送资源/最近交接；进入/刷新各一次GET，列表不逐行请求。只读；后台确认交接，已完成派送留完成时资源。回归 tests/trip-handover.test.mjs。

• 验证按 ../../docs/AI工程执行与协作约束.md；文案看差异，小逻辑定向测试，不默认全量/构建/真机验收。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/、环境文件、签名证书或打包产物。