ShiErFeng/docs/superpowers/pda-acceptance-training-runbook.md

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