调整部分前端布局和后端增删改逻辑

2026-09-26 23:11:05 +08:00
parent 977e7f996e
commit 17d991a74a
117 changed files with 311994 additions and 3192 deletions
@@ -0,0 +1,106 @@
+# 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`
@@ -294,7 +294,7 @@ git commit --only -m '新增：PDA HID 扫码输入组件' -- \

 - [ ] **Step 1: 写路由、权限和凭据安全测试并确认 RED**

-测试必须断言五个页面路径和标题存在，工作台包含五类业务权限字符串，且 `src/pages/login.vue` 不再包含 `admin123` 或其他密码字面量。测试也要断言入口跳转路径与页面路径一致。
+测试必须断言五个页面路径和标题存在，工作台包含五类业务权限字符串，且 `src/pages/login.vue` 不再包含旧默认密码或其他密码字面量。测试也要断言入口跳转路径与页面路径一致。

 - [ ] **Step 2: 注册五个页面并实现入口过滤**

@@ -702,7 +702,7 @@ ruff check module_business tests/module_business

 ```bash
 git diff --check HEAD~9..HEAD
-rg -n --fixed-strings 'admin123' shierfeng-fastapi-app/src shierfeng-fastapi-app/tests
+rg -n --fixed-strings '旧默认密码' shierfeng-fastapi-app/src shierfeng-fastapi-app/tests
 rg -n 'Bearer[[:space:]]+[A-Za-z0-9._-]+' shierfeng-fastapi-app/src shierfeng-fastapi-app/tests
 git status --short
 ```
@@ -148,6 +148,32 @@ return.js
 ## 9. 当前基线与风险

 - Web/FastAPI 核心业务已存在并有业务测试；本次重点是 uni-app PDA 缺失能力。
- 当前 PDA 工程只有通用登录、首页、工作台和个人中心，尚无业务页面与业务 API 模块。
- 后端接口已存在，但 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`；密码保持空白并由操作员手工输入，不将真实密码写入源码、测试或日志。
@@ -12,7 +12,7 @@
 ## 上线前准备

 1. 先备份数据库，并确认当前没有正在进行的入库、装填、发货、使用或退回操作。
-2. MySQL 只执行 `shierfeng-fastapi-backend/sql/patches/20260922_test_data_batch_mysql.sql`；PostgreSQL 只执行对应的 `_pg.sql` 文件，不能同时执行两份。
+2. MySQL 执行 `shierfeng-fastapi-backend/sql/patches/20260922_test_data_batch_mysql.sql`。
 3. 迁移完成后检查 `biz_test_batch`、`biz_test_batch_user` 和各业务表的 `test_batch_id` 字段及外键。
 4. 配置在线清理上限。默认 `TEST_BATCH_ONLINE_PURGE_MAX_ROWS=0`，表示禁止在线清理；只有明确配置为正整数且批次影响总数不超过上限时，管理页才允许执行清理。预览令牌默认有效期为 `TEST_BATCH_PREVIEW_TTL_SECONDS=600` 秒。