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 目录。
• 当前业务范围按四期收敛为入仓、库内、换标、库存/库位/托盘查询；不包含海外仓出库、派送和国内集装箱拣货/装柜。

服务与发布边界

• 国内 Auth 是唯一账号和 Token 签发方；海外业务请求统一经 gateway-overseas。
• 登录、刷新和本地会话必须同时校验国内/海外 Token 的平台主体、成员、冻结海外仓一致；海外 Token 还必须精确包含 WAREHOUSE_PICKER 与 lastleg:pda:operate。无效、过期、跨主体或撤权响应必须 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 专用 Controller、权限和 Token 冻结仓库范围契约齐备前必须禁用，不得调用平台/客户/内部接口或模拟成功。

页面与能力快速索引

目标	入口	继续查询
页面注册与启动	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/	当前只保留 zh-CN、en、es 初始化、空资源目录和本地语言状态能力；业务文案仍统一使用中文，需求稳定前不迁移页面、不开放语言切换入口
柜号签收、照片与入仓真实作业	src/pages/operation/operation.vue、src/api/inbound.js、src/api/receiving-adapter.js、src/api/overseas.js、src/stores/receiving.js	三个固定照片角色各一张，支持拍照/相册、鉴权预览及更换失败保留原图；Backend lastleg-service/inboundplan/pda/controller/ReceivingContainerController.java、ReceivingContainerService.java，公网前缀 /api/pda/v1/last-leg/receiving-containers/**
库内、托盘、换标与现场查询待接前端	src/data/overseas-workbench.js 中对应 available: false 入口	Backend 已有 pda/stocktake/、pda/move/、pda/warehouse/、palletops/、relabel/pda/ 与 overseas-pda-operations-v1.yaml；本应用新增专用 API/状态恢复和测试前不得启用
扫码设备与诊断	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	会话隔离、退出清理和后续真实作业历史契约
本地契约测试	tests/project-contract.test.mjs、navigation.test.mjs、scan-broadcast.test.mjs、audio-feedback.test.mjs	运行 npm test；不代表真实海外 API 或真机验收

海外业务接口边界

• src/api/inbound.js 已接入待卸柜候选、柜详情/prepare、current 恢复、三类照片签收、统一箱码定位入仓码、实物托盘解析、FBA bulk/OVERSEAS carton 收货及整柜完成；FBA bulk 不提交 skuCode，库存分配由服务端按计划明细完成；响应与 404/409 判定集中在 src/api/receiving-adapter.js，双 Token 刷新与海外 401 单次重放由 src/api/overseas.js 统一处理。
• 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 customerId、planNo、allocationId、warehouseId 或 locationId。409 必须引导账号恢复当前柜，完成前不得切柜。
• 签收照片固定为三个角色且每个角色只有一个当前文件；上传成功后使用服务端 downloadPath 在当前会话内鉴权读取。更换失败时保留原 fileId 和可提交状态，无原图的失败槽不得计入 photosReady；本地临时路径仅用于本次设备预览，不作为跨会话文件事实。
• 库内、换标与现场查询只有视觉原型依据，当前工作台入口保持禁用；新增真实作业必须建立 /api/pda/** 业务 API/DTO、lastleg:pda:operate 权限、Token 冻结仓库范围、错误态和契约测试，不得把平台、客户或内部接口直接暴露给 PDA。
• 已有海外入仓 PDA Controller 统一位于 Lastleg /api/pda/v1/last-leg/inbound-plans/{planNo}/**；浏览器或设备请求仍必须经 gateway-overseas 的显式 PDA 路由，不得直连 Lastleg，也不得改走国内 Gateway。
• 海外业务 Token、PDA 权限和可信身份最终由 Gateway 与服务端校验；前端不得用工作台 available、本地客户 ID 或仓库 ID 代替授权和资源归属校验。
• 四期仍止于入仓、库存与库内操作。后端历史 dispatch/、出库和派送代码不构成海外 PDA 页面入口，也不得加入工作台。

质量门禁

• 安装：npm install；检查：npm test。
• 正式产品形态是海外 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/app-update.test.mjs；新增原生模块、权限或不兼容运行时能力必须发海外 APK，不能仅发布 WGT，也不能下载国内更新包。
• 不提交 node_modules/、dist/、unpackage/、环境文件、签名证书或打包产物。