设计：补全 PDA 业务操作功能

2026-09-20 16:24:07 +08:00
parent 3edba99d2d
commit f2629ccf14
1 changed files with 153 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 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 样式：
+
+```text
+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/` 增加：
+
+```text
+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 模块。
+- 后端接口已存在，但 PDA 的实际设备联调、服务器访问地址和真实角色授权仍需运行环境配合。
+- APK 暂不打包，因此本次交付物是源码、接口封装、页面和可验证开发版本，不包含安装包。