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`。
- 国内与海外 AppID、Android 包名、签名、版本号、构建产物和在线更新通道必须独立。
- `src/manifest.json` 中的 AppID 在正式打包前由海外版所属 DCloud 账号创建；不得伪造或复用国内 AppID。
- 环境地址只通过 `.env.local` 等未提交环境文件配置，不写入源码。

## 工程入口

- 源码根：`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 按 SKU 与箱数收货、OVERSEAS 逐箱收货并逐入仓码核平；其他库内、换标与查询模块仍是静态原型，不得将原型提示改成模拟远程成功。

## 页面与能力快速索引

| 目标 | 入口 | 继续查询 |
|---|---|---|
| 页面注册与启动 | `src/pages.json`、`src/main.js`、`src/App.vue` | `src/manifest.json`、全局样式与应用生命周期 |
| 登录、刷新与会话 | `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` 是模块、作业可用性和原型数据入口 |
| 入仓真实作业、库内/换标/现场查询原型 | `src/pages/operation/operation.vue`、`src/api/inbound.js`、`src/api/overseas.js` | 入仓/卸柜/上架后端入口 `lastleg-service/inboundplan/pda/`；库存事实 `lastleg-service/inventory/`；库位/托盘资源 `warehouse-overseas-service/` |
| 扫码设备与诊断 | `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 恢复、三类照片签收、入仓码下 SKU/箱唛解析、实物托盘解析、FBA bulk/OVERSEAS carton 收货及整柜完成；响应与 404/409 判定集中在 `src/api/receiving-adapter.js`，双 Token 刷新与海外 401 单次重放由 `src/api/overseas.js` 统一处理。
- 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 `customerId`、`planNo`、`allocationId`、`warehouseId` 或 `locationId`。409 必须引导账号恢复当前柜，完成前不得切柜。
- 库内、换标与现场查询仍是静态原型；新增真实作业必须建立明确的业务 API/DTO、错误态和契约测试，不得把原型任务改成模拟成功。
- 已有海外入仓 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`。
- H5 生产编译：`npm run build:h5`；App 资源编译：`npm run build:app`。
- APK/IPA 必须在 HBuilderX 或正式原生打包环境中使用独立 AppID 与签名验证；仅通过 App 资源编译不得声称 APK 真机验收完成。
- 不提交 `node_modules/`、`dist/`、`unpackage/`、环境文件、签名证书或打包产物。