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、字段、状态与恢复规则见 按需业务索引。从本应用根执行 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 的对应页面行及“海外业务接口边界”条款；专项检查仍按下文质量门禁执行。

质量门禁

• 已发车排车详情按需挂载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/、环境文件、签名证书或打包产物。