chore: initial commit

AGENTS.md

@@ -0,0 +1,37 @@
+# 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 内置测试仅覆盖页面契约与本地状态规则。
+- 目标 PDA 型号、操作系统、扫描头接入方式、离线要求、发布方式及一期同步范围仍需确认。设备与方案确认前，不绑定单一厂商 SDK，也不假设摄像头扫码可替代硬件扫描头。
+- 明确使用的工具链和发布流程后，补充准确的依赖版本、安装、调试、测试和打包命令，并同步更新 `README.md` 与本文件。
+
+## 作业流程原则
+
+- 扫码是主路径：输入焦点、连续扫描、防抖、重复码、无效码、错箱和扫描反馈必须作为一等场景处理。
+- 明确区分整单拣货、部分拣货、异常挂起和完成提交；关键状态转换需服务端确认，不能只依赖本地页面状态。
+- 作业提交应具备幂等标识，防止弱网、重复点击或重放造成重复扣减与重复完成。
+- 离线队列只有在业务批准后才能实现；队列必须可观察、可重试、可取消，并能识别冲突而不是静默覆盖服务端状态。
+- 与管理后台头程订单、仓库任务和 `services/api` 对齐稳定标识、状态机、时间和异常码，禁止在前端自行发明另一套业务状态。
+
+## 设备、安全与可用性
+
+- 将扫描器、震动、声音、网络和本地存储封装为设备适配层，业务页面不直接依赖厂商 API。
+- `uni_modules/` 视为第三方依赖代码；除非任务明确要求修补依赖，否则不要直接修改，定制行为应通过业务组件或适配层实现。
+- `manifest.json` 中的设备权限遵循最小化原则；新增或保留权限时说明对应功能，并移除目标平台不需要的权限。
+- 适配手套操作、小屏、强光和高噪声环境：控件触控区域足够大，关键反馈同时使用文字、颜色及声音或震动。
+- 页面应在扫码后迅速恢复到可继续扫描状态；高频路径避免不必要的弹窗和多级导航。
+- 本地只保存完成任务所需的最少数据，退出、换班和设备遗失场景必须能清理敏感缓存。
+- 日志可包含任务和错误关联标识，但不得记录完整令牌、人员隐私或可还原的敏感货物信息。
+
+## 质量门禁
+
+- 在真实目标 PDA 上验证扫描速度、连续扫描、断网重连、低电量、前后台切换和重复提交。
+- 状态转换、扫码分类与页面契约使用 `node --test tests/*.test.mjs` 验证；新增本地行为时继续补充对应自动化测试。
+- 当前原型没有可核实的 HBuilderX/Android 构建命令，不得声称打包或真机检查已通过；交付说明应明确实际验证方式、设备、系统版本和仍未覆盖的风险。