pda-uniapp/AGENTS.md

PDA Uni-app Instructions

项目定位

• 本项目面向仓库现场人员，使用 uni-app 适配仓库 PDA 设备。
• README 记录的登录、箱号选择、扫码、整单或部分拣货、异常原因和完成提交是当前静态原型范围；项目使用 uni-app Vue 3，业务页面采用 Vue 3 兼容的 Options API。
• 本项目负责现场执行体验，不承担管理后台的订单配置、客户工作台或通用库存管理能力。

开发与发布边界

• 当前已有 uni-app Vue 3 页面、uni_modules/、vite.config.js、.env.example 和 H5 同源代理配置。首页当前只展示“入库 → 一件代发”“出库 → 出库拣货”和“查询 → 库位查询”，其余能力保留源码与路由但不展示；项目仍没有根级依赖清单、仓库内 npm 构建命令或可核实的 Android 构建命令。H5 已使用 HBuilderX 5.15 自带编译器和 cli.exe launch web 验证，具体命令见 README.md。现有 Node.js 内置测试仅覆盖页面契约与本地状态规则。
• PDA 采用 uni-app 开发并支持在线更新；Android 硬件扫描已确认使用广播模式并已接入：Action=android.intent.action.SCANRESULT、字符串 Extra=value。设备型号不构成开发、发布或验收门禁；继续通过设备适配层接入，不绑定单一厂商 SDK。
• 正式作业已确认为在线模式：断网不能开始正式拣货、提交、完成任务或推进 LOADED，不实现离线业务提交队列；恢复网络后提示员工刷新重试。
• H5 调试使用 HBuilderX 5.15 自带的 uni-app Vue 3 编译器；Android 发布流程仍待明确后补充准确的依赖版本、打包命令，并同步更新 README.md 与本文件。
• 在 package.json 与锁文件正式补齐前，vite.config.js 只证明目标配置，不证明依赖可安装；维护者可运行仓库当前可执行的 node --test tests/*.test.mjs，或使用已安装的 HBuilderX 5.15 CLI 运行 H5，不得从海外 PDA 或全局缓存猜测国内 PDA 的 uni-app/Vite 版本。
• App API 根只读 VITE_API_BASE_URL；H5 固定优先使用 VITE_H5_API_BASE_URL=/gateway-api 并由 vite.config.js 同源代理、重写为 Gateway /api，避免截获项目自身 api/ 前端模块。环境地址不写入源码，切换构建环境后不得沿用登录缓存中的旧 API 地址。
• 国内 Android App 启动后仅在 APP-PLUS 调用 utils/app-update.js，通过独立 VITE_PDA_UPDATE_URL 检查更新；更新服务和下载地址必须为 HTTPS。APK 以整数 versionCode 判新，WGT 以 versionName 判新；强制更新不可跳过，WGT 安装后立即重启。国内 AppID、包名、签名、版本和更新通道不得复用海外 PDA。

作业流程原则

• 扫码是主路径：输入焦点、连续扫描、防抖、重复码、无效码、错箱和扫描反馈必须作为一等场景处理。
• 拣货扫描身份是后端下发的稳定箱唛箱码 boxCode；一次有效且未重复的箱码扫描表示拣出一箱。SKU、商品件数、入库单号和页面展示文案只用于辅助识别，不得作为扫码匹配键或拣货计数单位。
• 进入任务时由服务端标记“拣货中”；扫描结果先写入绑定作业员、任务和柜次的设备持久化草稿，仅在点击提交时批量写后端，禁止逐码提交。
• 允许部分拣货和跳拣，但每个未完成项必须填写异常原因；存在未解决异常时任务挂起，不能完成或推进 LOADED。
• 作业提交使用对员工不可见的轻量幂等标识和服务端版本；重复提交返回原结果，版本冲突提示刷新后重试，不静默覆盖。
• 提交成功或明确放弃后清理草稿；退出应用或设备重启后同一作业员、任务和柜次可恢复，其他账号不得继承。
• PDA 仅允许现场拍照；Admin 可通过独立受权入口人工上传。五类证据各至少 1 张有效照片，同类型允许多张追加；错误或重复照片标记作废并保留原因、操作人和时间，不硬删除。设备端证据查询、上传、预览和作废统一按当前 taskId + warehouseId 走任务专用 API，服务端再绑定真实柜 containerBookingId；不得调用旧入仓单/客户作用域证据接口。
• 与管理后台头程订单、仓库任务和 baiyue-firstleg Controller/OpenAPI 对齐稳定标识、状态机、时间和异常码，禁止在前端自行发明另一套业务状态。

设备、安全与可用性

• 将扫描器、震动、声音、网络和本地存储封装为设备适配层，业务页面不直接依赖厂商 API。
• uni_modules/ 视为第三方依赖代码；除非任务明确要求修补依赖，否则不要直接修改，定制行为应通过业务组件或适配层实现。
• manifest.json 中的设备权限遵循最小化原则；新增或保留权限时说明对应功能，并移除目标平台不需要的权限。
• 适配手套操作、小屏、强光和高噪声环境：控件触控区域足够大，关键反馈同时使用文字、颜色及声音或震动。
• 页面应在扫码后迅速恢复到可继续扫描状态；高频路径避免不必要的弹窗和多级导航。
• 本地只保存完成任务所需的最少数据，退出、换班和设备遗失场景必须能清理敏感缓存。
• 日志可包含任务和错误关联标识，但不得记录完整令牌、人员隐私或可还原的敏感货物信息。

质量门禁

• 在真实目标 PDA 上验证扫描速度、连续扫描、断网阻断与恢复刷新、低电量、前后台切换和重复提交。
• 状态转换、扫码分类与页面契约使用 node --test tests/*.test.mjs 验证；新增本地行为时继续补充对应自动化测试。
• 修改在线更新协议、版本比较、强制更新、安装或重启行为时运行 node --test tests/app-update.test.mjs；新增原生模块、权限或不兼容运行时能力必须发布 APK，不能只发布 WGT。
• 当前没有依赖清单、仓库内 npm 构建命令或可核实的 Android 构建命令；H5 必须按 README.md 使用 HBuilderX 5.15 CLI 实际启动后才可声称通过，不得仅凭 vite.config.js 声称 H5、App 打包或真机检查已通过。交付说明应明确实际验证方式、设备、系统版本和仍未覆盖的风险。

页面与能力快速查询

目标	入口	继续查询
页面注册与启动	pages.json、main.js、App.vue	全局样式和应用生命周期
API 环境与 H5 开发代理	config/runtime.js、.env.example、vite.config.js	App VITE_API_BASE_URL；H5 同源 VITE_H5_API_BASE_URL=/gateway-api，代理上游 API_PROXY_TARGET 并重写为 /api；会话恢复不得覆盖当前构建地址
部分拣货布局与库位展示	pages/picking/picking.vue、styles/pda.scss	库位为空时不渲染空标签或残留分隔符；部分拣货数量必须小于需求且不超过服务端库存/库位可用量，合同 tests/partial-layout.test.mjs、tests/picking-location-display.test.mjs
Android APK/WGT 在线更新	App.vue、utils/app-update.js、.env.example、manifest.json	VITE_PDA_UPDATE_URL 使用国内独立 HTTPS 通道；合同 tests/app-update.test.mjs，H5 不执行更新逻辑
登录与会话	pages/login/、stores/session.js	远程鉴权适配和会话清理
工作台、仓库选择与模块入口	pages/home/、components/PortalHeader.vue、stores/session.js、pages/module/、pages/operation/	左上角只提供启用国内仓选择，选择结果持久化；data/demo-data.js 的 visible 控制展示、available 控制可操作；隐藏能力不得删除源码或路由
待处理任务、服务端就绪与领取	pages/tasks/tasks.vue	api/pda-loading.js 的 listLoadingOrders、getContainerPickingTask、claimContainerPickingTask；合并任务和缺少柜号/仓库/版本的任务不可进入
一件代发	pages/dropship-tasks/dropship-tasks.vue、pages/dropship-palletization/dropship-palletization.vue	api/pda-dropship.js；作为入库作业，测量审核按预计托数预生成并可打印 DP 托盘码，PDA 明确执行逐箱清点并支持先扫箱或先扫托、归托和逐托封托；预计托数与已生成托盘数不一致时失败关闭；公网前缀 /api/platform/v1/first-leg/pda-dropship/**
业务编号展示与错误脱敏	utils/user-facing.js、tests/user-facing-identifiers.test.mjs	任务和作业页优先显示真实集装箱号，缺失时显示柜次号，再缺失显示“集装箱号 —”；不得展示 taskId、inboundId、orderId、loadingPlanId、containerBookingId 或长整型内部 ID，错误仍保留 code、requestId、traceId
拣货任务与箱码扫码	pages/picking/、stores/picking.js	api/pda-loading.js、utils/scan-broadcast.js、components/ScanTargetInput.vue；服务端契约见 ../../baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.yaml
装柜取证与完成	pages/picking/picking.vue 的 evidence 阶段	正式边界是 api/pda-loading.js 的证据查询、预览、上传、作废和 completeContainerPickingTask 全部按当前任务与仓库进入；不得保留按入仓单/客户作用域的旧证据调用。上传队列 utils/evidence-upload-queue.js，合同 tests/pda-loading-api.test.mjs、tests/picking-evidence-stage.test.mjs
装柜取证与完成	pages/picking/picking.vue 的 evidence 阶段	正式边界是 api/pda-loading.js 的证据查询、预览、上传、作废和 completeContainerPickingTask 全部按当前任务与仓库进入；不得保留按入仓单/客户作用域的旧证据调用。上传队列 utils/evidence-upload-queue.js，合同 tests/pda-loading-api.test.mjs、tests/picking-evidence-stage.test.mjs、tests/seal-save-idempotency.test.mjs
扫描诊断	pages/scanner-test/	utils/scan-broadcast.js 与广播 Action/Extra
作业记录与人员	pages/history/、pages/profile/	session 与本地敏感数据清理
页面与真实 API 合同	tests/page-contract.test.mjs、tests/pda-loading-api.test.mjs	覆盖部分拣货页面、提交门禁、库位不足反馈和国内 PDA 真实接口路径；统一由 node --test tests/*.test.mjs 执行

全量验收索引

当前按 PDA 全量作业链路验收。业务域文档用于核对功能来源和验收证据，不限制本次验收范围；从 pages.json 定位页面，沿页面 → stores/ → utils/ → 设备适配层检查。本表只描述 PDA 作业端，不代表后台或 Client 已具备对应能力。

验收域	PDA 范围与代码入口	验收首读
作业全链路	登录、工作台、一件代发扫码清点/归托/封托、出库扫码拣货、装柜证据、草稿持久化、批量提交、异常和在线更新	pages/login/、pages/home/、pages/dropship-tasks/、pages/dropship-palletization/、pages/picking/、stores/session.js、stores/picking.js、utils/scan-broadcast.js、pages.json	按业务选择 ../../docs/订单与客户/、../../docs/入库测量与计费/、../../docs/国内货柜履约/ 和 README.md 的契约与验收规则

作业边界：PDA 不承担客户工作台或后台配置；服务端状态、权限、幂等和 LOADED 门禁是验收事实来源。发布采用既定 uni-app 在线更新安排。

全量验收脚本

• PDA 不单独定义一套“全量 HTTP”入口；PDA 服务链路由 Admin 全量 HTTP 入口中的 phase3-pda-convergence、装柜、证据和出仓模块覆盖。
• 本目录 node --test tests/*.test.mjs 仅是 PDA 本地页面/状态质量检查，不代表服务端作业链路已通过。
• 服务 HTTP 通过后，再按真实 uni-app 页面完成扫码输入、网络阻断/恢复、草稿恢复、批量提交、窄屏和在线更新验收；真机检查属于最后的交互验收。