# PDA 托盘业务验收与培训手册

## 1. 文档目的

本手册用于服务器、数据库和 PDA 设备准备完成后的现场验收与客户培训。它不替代部署、数据库迁移或 APK 打包，也不把本地构建结果视为真机验收结果。

当前代码交付物是 uni-app PDA 页面、接口封装、HID 扫码组件和可验证 H5 构建；APK 按当前范围暂不生成。

## 2. 验收前置条件

- 后端服务已部署并可从 PDA 访问，已确定 `VITE_APP_BASE_API` 对应地址。
- 数据库已执行与目标数据库类型匹配的初始化 SQL/业务补丁，并完成备份。
- Redis、JWT、传输加密和验证码配置已按目标环境确认。
- 已准备管理员、仓库操作员、客户现场操作员三类账号，并分别配置仓库/现场数据范围。
- 已准备至少两个空托盘、一个已装填托盘、一个可部分使用托盘和一个可退回托盘；每个托盘二维码唯一且可扫描。
- PDA 与扫码头处于 HID 键盘输入模式，扫码结束符配置为回车；网络稳定性和离线恢复策略已确认。
- 验收记录表包含：用例编号、账号、托盘码、时间、预期结果、实际结果、截图/日志、问题编号和签字人。

## 3. 角色验收

| 角色 | 应能操作 | 不应能操作 |
| --- | --- | --- |
| 管理员 | 在授权范围内查看基础资料、业务单、报表和追溯 | 不应绕过后端权限与数据范围 |
| 仓库操作员 | 入库、装填、发货、退回收货 | 不应操作未授权仓库或客户现场 |
| 客户现场操作员 | 扫码查看托盘、绑定产线、录入使用、发起退回 | 不应确认仓库收货或访问未授权现场 |

登录页默认填充用户名 `admin`；密码必须由操作员现场手工输入，不记录在测试单、日志或源码中。

## 4. 核心业务验收用例

### 4.1 基础资料与二维码

1. Web 后台新增菌种、客户、现场、产线、仓库和托盘。
2. 为托盘设置容量，生成并查看固定二维码。
3. 重复托盘编号或二维码应被拒绝；停用托盘不能进入业务流程。
4. 为仓库和现场分配用户，使用受限账号确认数据范围。

### 4.2 入库

1. 仓库用户选择授权仓库，扫描 `UNSTOCKED` 托盘。
2. 重复扫描同一托盘应被前端提示并不会重复加入。
3. 创建入库草稿，移除一条明细后保存并重新进入详情。
4. 确认入库，检查库存状态变为仓库空托盘，并检查托盘事件。
5. 在响应丢失后使用同一操作重试，确认不会重复入库。

### 4.3 装填

1. 扫描仓库空托盘，确认页面显示仓库、容量和当前余量。
2. 选择菌种，录入批次、规格和正整数包数。
3. 使用 0、负数、超容量和未授权仓库数据验证后端拒绝。
4. 提交成功后检查状态、菌种、批次、初始包数和装填事件。

### 4.4 发货

1. 选择授权来源仓库和目标客户现场，连续扫描可发货托盘。
2. 检查页面展示的菌种、批次和剩余包数为服务端数据。
3. 创建草稿并确认，检查来源库存扣减、现场位置和发货事件。
4. 用同一幂等键重试确认，确认不会重复扣减库存。

### 4.5 客户现场使用

1. 现场用户扫描已发货托盘，确认菌种、批次和剩余包数可读。
2. 首次使用选择当前现场产线，录入正整数使用包数。
3. 使用小于余量的包数，确认状态为部分使用且剩余包数正确。
4. 使用剩余全部包数，确认状态为现场空托盘且剩余包数为 0。
5. 尝试切换已绑定的其他产线、超出余量或使用 0 包，确认请求被拒绝。

### 4.6 退回

1. 现场用户选择目标仓库并扫描可退回托盘，提交退回申请。
2. 检查托盘状态进入退回中，不能再次发货或重复申请。
3. 仓库用户查看退回详情，扫描整集合托盘并确认收货。
4. 漏扫、错扫、重复扫和余量快照变化均应阻止确认。
5. 确认成功后检查仓库库存、托盘状态和退回事件。

## 5. 报表、权限与异常验收

- 查看托盘库存、装填、发货、产线消耗、退回和托盘追溯六类报表。
- 用受限账号验证未授权菜单不显示，直接调用接口返回 403。
- 检查关键写操作包含操作人、时间、业务单和托盘事件。
- 在扫码请求期间连续回车，确认输入锁生效且不会并发提交。
- 断网后重试，确认使用原幂等键；网络恢复后不会重复扣减库存。
- 使用非法状态、库存不足、错误仓库/现场和旧详情快照，确认错误可见且状态不被部分写入。

## 6. 培训顺序

1. 讲解托盘二维码、状态和“服务端结果为准”原则。
2. 仓库操作员练习入库、装填、发货和退回收货。
3. 客户现场操作员练习扫码、产线选择、部分/全部使用和退回申请。
4. 管理员练习基础资料、用户数据范围、报表和托盘追溯。
5. 演练重复扫码、断网重试、无权限和库存不足，不使用真实业务数据做首次演示。
6. 培训结束后由各角色完成一条完整闭环：入库 → 装填 → 发货 → 使用 → 退回。

## 7. 当前不包含事项

- 本阶段不打包、签名、安装或发布 APK。
- 本阶段不调用摄像头扫码，不新增原生扫码 SDK；扫码方式为 HID 扫码头加手工输入兜底。
- 本手册不执行生产部署、数据库迁移、密码重置或客户培训；这些动作需在目标环境中按前置条件执行并留存记录。

## 8. 代码证据

- 设计与需求覆盖矩阵：`docs/superpowers/specs/2026-09-20-pda-business-workflow-design.md`
- PDA 页面与接口：`shierfeng-fastapi-app/src/pages/business`、`shierfeng-fastapi-app/src/api/business`
- Web 基础资料、业务和报表：`shierfeng-fastapi-frontend/src/views`
- 后端业务与状态机：`shierfeng-fastapi-backend/module_business`
- 数据库结构：`shierfeng-fastapi-backend/sql`