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/，没有项目根级依赖清单或可核实的 HBuilderX/Android 构建命令；现有 Node.js 内置测试仅覆盖页面契约与本地状态规则。
• Android 硬件扫描已确认使用广播模式并已接入：Action=android.intent.action.SCANRESULT、字符串 Extra=value。目标 PDA 型号、Android 版本、打包发布方式和真实设备验收仍待确认；继续通过设备适配层接入，不绑定单一厂商 SDK。
• 正式作业已确认为在线模式：断网不能开始正式拣货、提交、完成任务或推进 LOADED，不实现离线业务提交队列；恢复网络后提示员工刷新重试。
• 明确使用的工具链和发布流程后，补充准确的依赖版本、安装、调试、测试和打包命令，并同步更新 README.md 与本文件。

作业流程原则

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

设备、安全与可用性

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

质量门禁

• 在真实目标 PDA 上验证扫描速度、连续扫描、断网阻断与恢复刷新、低电量、前后台切换和重复提交。
• 状态转换、扫码分类与页面契约使用 node --test tests/*.test.mjs 验证；新增本地行为时继续补充对应自动化测试。
• 当前原型没有可核实的 HBuilderX/Android 构建命令，不得声称打包或真机检查已通过；交付说明应明确实际验证方式、设备、系统版本和仍未覆盖的风险。

一期/二期/三期快速索引

按阶段处理 PDA 任务时，先核对阶段文档，再从 pages.json 定位页面，沿页面 → stores/ → utils/ → 设备适配层检查；本表只描述 PDA 作业端，不代表后台或 Client 已具备对应能力。

阶段	当前状态与边界	PDA 入口	开始前核对
一期：头程订单基础闭环	PDA 仅保留静态登录、工作台和出库拣货原型；是否与一期头程订单/仓库任务同步上线尚未确认，不得将本地状态当作服务端闭环。	pages/login/、pages/home/、pages/picking/、stores/session.js、stores/picking.js；页面注册见 pages.json。	../../docs/一期/README.md、../../docs/一期/一期头程订单闭环设计.md、README.md；确认设备、同步范围、鉴权和服务端任务契约后再接 API。
二期：到仓与计费	不在二期实现 PDA 到仓测量、称重、托盘/库位或费用确认；这些能力由 Admin/Client/Backend 完成，PDA 继续维持静态原型。	现有 pages/picking/ 不扩展二期业务；扫码适配保持在 utils/scan-broadcast.js 与 components/ScanTargetInput.vue。	../../docs/二期/README.md、../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md；确认二期终点 WAIT_SPLIT + APPROVED + CONFIRMED，不得提前接入分柜。
三期：国内出仓	PDA 承接分柜后拣货和装柜证据。在线作业、进入即开始、持久化草稿、批量提交、异常阻断、轻量幂等/版本和五类多图规则已确认；一柜多人、换班释放、最终 LOADED 触发和设备发布仍待确认。	复用 pages/picking/、stores/picking.js、utils/scan-broadcast.js 和远程 API 适配；当前内存草稿、单类型照片替换等实现不得作为最终契约。	../../docs/三期/README.md、../../docs/三期/三期开发规划.md、../../docs/三期/三期需求确认表.md、README.md；按已确认子规则继续开发，待定项保持可扩展，不自行固定。

阶段边界：PDA 不承担客户工作台或后台配置；一期仅验证原型与同步范围，二期不提前引入 PDA/分柜/装柜。三期已确认的 PDA 子规则可进入开发和契约测试，仍待确认的多人协作、完成触发和真机发布不得自行定稿。