ShiErFeng/docs/superpowers/specs/2026-09-20-pda-business-workflow-design.md

PDA 托盘业务操作功能补全设计

1. 背景与目标

当前仓库已经具备 Web 后台、FastAPI 业务接口、托盘库存状态机、数据库结构、权限模型和六类报表。shierfeng-fastapi-app 目前只有通用登录、首页、工作台和个人中心，没有托盘业务操作页面与对应 API 封装。

本次在不改变既有后端业务契约的前提下，补齐 uni-app PDA 操作端的现场业务功能。PDA 暂不生成 APK，先完成页面、接口对接、扫码交互、权限控制和可验证的开发运行版本。

2. 范围确认

2.1 本次包含

• 复用现有 /login、/getInfo、/logout 认证流程。
• 在 shierfeng-fastapi-app 增加五类现场操作：
  • 仓库入库
  • 工厂装填
  • 发货出库
  • 客户现场使用
  • 退回仓库
• 增加 PDA 端 API 模块、扫码输入组件、业务页面、权限显示和错误/重试处理。
• 复用后端已有状态机、幂等键、数据范围、库存事务和托盘追溯，不在 PDA 前端自行计算最终库存或状态。
• 适配 PDA 扫码头的 HID 键盘输入和回车提交，并保留手工输入作为故障兜底。
• 增加 PDA 端静态契约测试和 H5/开发构建验证；不生成 APK。
• 继续使用 Web 后台维护菌种、客户、现场、产线、仓库、托盘和六类报表。

2.2 本次不包含

• 不打包、签名、安装或发布 APK。
• 不调用摄像头扫码，不新增原生扫码 SDK；当前以 HID 扫码枪输入为主。
• 不把基础资料维护和六类报表复制到 PDA。
• 不修改现有 FastAPI 业务接口的请求/响应契约，除非实现阶段发现有明确且可验证的 PDA 阻塞缺口。
• 不修改 shierfeng-fastapi-frontend 的既有 Web 业务页面，除非共享契约缺陷直接阻塞 PDA。
• 不修改 .env.dev、.env.prod、前端环境文件、用户已有 APP 改动或无关缓存。
• 不执行生产部署、服务器配置、Redis 清理、数据库迁移或培训；这些属于后续运行交付，需要单独的环境授权和验收。
• 不把管理员密码写入源码、设计文档、日志或测试固定文本。

3. 用户角色与权限边界

PDA 页面只展示当前用户拥有的权限，后端接口权限和仓库/现场数据范围仍是最终权威：

角色能力	PDA 操作
仓库操作员	查看可访问仓库、创建/确认入库、扫描装填、创建/确认发货、确认退回
客户现场操作员	扫描托盘、首次选择产线、录入使用包数、发起退回
业务管理员/超级管理员	依据既有权限可执行全部授权操作

不新增固定角色，不自动给普通用户授权。仓库与客户现场的数据范围继续由现有用户-仓库、用户-现场关系决定。

4. 页面与 API 设计

4.1 PDA 页面

新增页面建议采用以下路径，沿用当前 uni-app 页面路由和 Tailwind 样式：

src/pages/business/inbound/index.vue
src/pages/business/filling/index.vue
src/pages/business/shipment/index.vue
src/pages/business/usage/index.vue
src/pages/business/return/index.vue

工作台只增加实际权限允许的业务入口，不保留“建设中”假入口。页面加载失败、权限不足和接口异常必须给出可操作提示。

4.2 PDA API 封装

复用后台已有接口路径，在 src/api/business/ 增加：

inbound.js
filling.js
shipment.js
usage.js
return.js

每个模块覆盖对应的列表、详情、选项、扫码、创建/编辑/删除、确认或提交接口；请求字段使用后端既有 camelCase 契约，不在前端另建同义字段。

4.3 共享扫码组件

新增 PDA 专用扫码输入组件，职责仅限于输入采集和规范化：

• 自动聚焦可用输入框。
• 兼容 HID 扫码枪逐字符输入后回车提交。
• 去除首尾空白，拒绝空值。
• 防止同一托盘在短时间内重复追加。
• 扫码请求期间锁定相关输入，避免并发提交。
• 支持“重新扫描”和手工输入兜底。
• 不在组件内决定托盘状态、库存数量或权限结果。

5. 五类业务流程

5.1 入库

选择后端返回的可用仓库，创建草稿并连续扫描 UNSTOCKED 托盘；允许移除草稿明细，确认时复用业务幂等键。提交成功后以服务端结果刷新页面，不由 PDA 推算库存。

5.2 装填

扫描托盘并展示后端返回的仓库、状态和当前余量；选择菌种，填写批次、规格和正整数包数；提交后清理表单并重新获取托盘状态。非法状态、超容量、无仓库权限由后端拒绝并原样转为用户可读提示。

5.3 发货

选择来源仓库和目标客户现场，连续扫描多个可发货托盘；展示菌种、批次和剩余包数只读信息；确认前复核托盘集合，服务端负责整单锁定、库存扣减和事件追加。

5.4 客户现场使用

扫描托盘后展示菌种、批次、当前余量和允许操作；首次使用要求选择当前现场产线，后续使用沿用后端锁定产线；使用包数必须为正整数且不超过服务端返回余量。成功后只采用服务端返回的新余量和状态。

5.5 退回仓库

客户现场扫描待退回托盘，选择目标仓库并发起退回；仓库用户扫描并确认收货。申请和确认分别持有独立幂等键，页面分别保存两阶段状态，确认后以服务端返回的库存状态刷新。

6. 认证、密码与安全

• PDA 继续使用当前 JWT、传输加密和 /getInfo 权限信息。
• 前端不硬编码管理员密码；给定账号只用于经授权的本地联调验证。
• 当前登录页中的旧默认密码预填值需要改为不暴露密码的空表单或开发环境专用行为，不能把真实密码写入仓库。
• 管理员密码变更属于账号凭据写操作，须先只读核对当前认证存储，再单独确认、备份并执行，日志不得输出密码、Token 或 Cookie。
• PDA 页面隐藏不能替代后端权限校验；所有业务请求继续经过后端接口权限和数据范围检查。

7. 状态、幂等与错误处理

• PDA 只提交业务输入和幂等键，不提交目标库存、目标状态或版本号。
• 网络超时、响应丢失或用户重试时复用同一个业务幂等键；同键不同请求内容显示冲突，不自动生成新业务操作。
• 扫码重复、按钮重复点击和页面切换期间的旧响应由前端请求序列号/锁控制。
• 401 继续走现有会话过期处理；403、业务状态冲突、库存不足和数据范围错误必须显示后端消息并允许安全重试。
• 页面恢复或重新进入时，以详情/列表接口作为唯一权威，不能相信本地缓存的库存和状态。

8. 验证与交付

8.1 代码验证

• 为 PDA API 路径、字段映射、权限入口、扫码规范化、幂等键复用和五类页面交互增加 Node 20 契约测试。
• 使用现有后端业务测试和 Ruff 验证共享接口没有回归。
• 运行 uni-app 的 H5/开发构建或等价编译检查；不执行 build:app，不生成 APK。
• 对当前工作区做精确 diff 检查，保留用户已有 APP、环境、日志和缓存改动。

8.2 人工验收清单

1. 使用管理员和受限普通用户分别登录。
2. 验证未授权菜单不显示、直接接口请求返回 403。
3. 使用 HID 扫码枪验证五类业务的扫码、回车、重复扫码和错误重试。
4. 验证库存、剩余包数、产线绑定、退回冻结和事件追溯均以后端结果为准。
5. 验证页面刷新/断网重试不重复扣减库存。

真实服务器部署、APK 安装、客户培训和跨设备实测在本次代码补全后仍需单独安排，不能用本地构建结果替代。

9. 当前基线与风险

• Web/FastAPI 核心业务已存在并有业务测试；本次重点是 uni-app PDA 缺失能力。
• 当前 PDA 工程已包含通用登录、首页、工作台、个人中心，以及入库、装填、发货、现场使用、退回五类业务页面和对应 API 模块。
• 后端接口、Web 管理页面和数据库 SQL 已存在；PDA 的实际设备联调、服务器访问地址、数据库迁移和真实角色授权仍需运行环境配合。
• APK 暂不打包，因此本次交付物是源码、接口封装、页面和可验证开发版本，不包含安装包。

10. 需求覆盖矩阵（代码审计结果）

下表区分“代码已实现”和“真实环境已交付”，避免把静态测试或本地构建误认为部署、安装或培训完成。

序号	需求	当前结论	主要证据
1	业务流程、功能边界、角色、交付内容和不包含事项	已确认	本设计第 1～3、8～9 节
2	托盘、菌种、产线、仓库、装填、发货、使用、退回字段	已梳理	module_business/entity、SQL 脚本
3	后台、接口、数据库结构和基础运行环境	代码已完成；实际环境未部署	module_business、sql/、前后端工程
4	菌种、产线、仓库、用户等基础资料维护	已实现	Web views/master、系统用户/角色模块
5	托盘唯一标识、固定二维码、状态和档案	已实现	biz_pallet 唯一约束、状态机、托盘管理页
6	入库登记、入库单、库存更新	已实现	inbound_controller.py、inbound_service.py
7	扫码装填菌种、批次、规格、包数并更新状态	已实现	filling_service.py、Web/PDA 装填页
8	发货单、托盘扫码/选择、明细和库存扣减	已实现	shipment_service.py、Web/PDA 发货页
9	PDA 登录、扫码识别和读取菌种/余量	已实现；未打包 APK	shierfeng-fastapi-app/src/pages/business、PDA API
10	客户扫码、产线绑定、使用包数、操作人和时间	已实现	usage_service.py、使用记录模型和页面
11	全部/部分使用、剩余包数、退回和状态流转	已实现	pallet_state_machine.py、使用/退回服务
12	六类库存、装填、发货、消耗、退回、追溯报表	已实现	report_controller.py、Web 六类报表页
13	权限、操作记录、流转追溯和异常留痕	已实现	权限依赖、Log、biz_pallet_event、追溯报表
14	Android 页面、接口、PDA 适配和 APK	页面/API/HID 已实现；APK 按要求暂缓	PDA H5 构建与扫码组件
15	后台、接口、PDA、库存、退回整体联调	代码级验证完成；真实设备联调未完成	契约测试通过；缺少真实设备/服务地址
16	服务器、数据库、后台/接口服务和访问地址部署	未完成	缺少目标服务器和部署授权
17	App 安装、扫码验收和客户培训	未完成	缺少 PDA 设备及培训安排

登录页默认只填充用户名 admin；密码保持空白并由操作员手工输入，不将真实密码写入源码、测试或日志。