310 lines
11 KiB
Markdown
310 lines
11 KiB
Markdown
# PRD · 模块一：上架登记
|
||
|
||
版本：v1.0
|
||
状态：待评审
|
||
适用端：安卓扫码枪 Flutter 应用
|
||
|
||
---
|
||
|
||
## 1. 功能概述
|
||
|
||
上架登记模块是成品库房作业流程的第二步。工人完成分堆后，需要将每张执行卡对应的产品登记到具体的货位上。系统记录总排号与货位号的绑定关系，为后续的货架查询、清点和装箱编号提供数据基础。
|
||
|
||
本模块支持两种操作场景：
|
||
|
||
- **单次上架**：每次绑定一个总排号到一个货位；
|
||
- **连续上架（锁定模式）**：锁定一个货位后，连续扫描多个总排号，批量完成绑定。
|
||
|
||
---
|
||
|
||
## 2. 用户与使用场景
|
||
|
||
**使用人员**：成品库房工人
|
||
|
||
**典型场景**：
|
||
|
||
|场景|描述|
|
||
|---|---|
|
||
|普通上架|工人将某个执行卡对应的产品放到货架上，扫码登记货架货位。|
|
||
|转运上架|工人判断某个产品可以直接进入转运流程，扫码登记转运特殊货位。|
|
||
|批量上架|同一批次多个执行卡产品放到同一货架位，锁定货位后连续扫执行卡。|
|
||
|
||
---
|
||
|
||
## 3. 设备能力约定
|
||
|
||
|项目|说明|
|
||
|---|---|
|
||
|扫码输出方式|广播输出（Android Intent）|
|
||
|屏幕尺寸|3.5 英寸|
|
||
|键盘|31 键实体键盘|
|
||
|网络|WiFi / 蓝牙 / 蜂窝，三种模式|
|
||
|反馈方式|声音、振动、LED 灯、屏幕显示|
|
||
|
||
Flutter 层通过 `EventChannel` 接收原生广播，不依赖输入框焦点捕获。
|
||
|
||
---
|
||
|
||
## 4. 码值识别规则
|
||
|
||
系统根据扫入码值的格式自动判断类型，不强制要求扫码顺序。
|
||
|
||
|码值类型|识别规则|示例|
|
||
|---|---|---|
|
||
|总排号|正则 `^\d{2}(B\|C\|T)\d+$\|^\d{2}(BW\|CW)\d{4}$`，温度计(BW/CW)流水号必须固定4位数字，其余类型不补零|`26B1`、`26C12`、`26BW0001`、`26CW0015`、`26T3`|
|
||
|排产号|正则 `^[A-Z]{1,2}\d{5}(-J)?$`（当前模块暂不使用，预留）|`R00001`、`CY00012`、`R06936-J`|
|
||
|普通货位号|格式为 `[区域货架]-[层]-[格]`，全大写，横杠分隔|`A01-02-03`|
|
||
|转运特殊货位号|以 `TRANS-` 开头|`TRANS-01`|
|
||
|无效码|不符合以上任何规则|—|
|
||
|
||
**重复扫码规则**：在同一次提交动作完成前，如果同一类型的码被多次扫入，取最后一次扫入的值作为有效值，前一次自动覆盖。
|
||
|
||
---
|
||
|
||
## 5. 功能详细说明
|
||
|
||
### 5.1 单次上架模式
|
||
|
||
#### 5.1.1 进入方式
|
||
|
||
应用启动后默认进入单次上架模式。
|
||
|
||
#### 5.1.2 操作流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A([进入上架登记页]) --> B[等待扫码\n总排号或货位号，顺序不限]
|
||
B --> C{识别码值类型}
|
||
C -->|总排号格式| D[填入总排号字段]
|
||
C -->|货位号格式| E[填入货位号字段]
|
||
C -->|无效码| F[提示无效码\n不影响已有字段]
|
||
F --> B
|
||
D -->|重复扫入同类型码| D
|
||
E -->|重复扫入同类型码| E
|
||
D --> G{两个字段\n是否均已填入}
|
||
E --> G
|
||
G -->|否| B
|
||
G -->|是| H[确认按钮高亮\n工人核查信息]
|
||
H --> I[按确认键提交]
|
||
I --> J[调用后端接口]
|
||
J --> K{结果}
|
||
K -->|成功| L[清空页面\n成功反馈 1.5s\n等待下一次扫码]
|
||
K -->|重复上架| M[错误弹窗\n显示已有货位与时间\n需手动关闭]
|
||
K -->|网络异常| N[保留数据\n提示检查网络\n可直接重试]
|
||
K -->|其他错误| O[保留数据\n显示错误描述]
|
||
L --> B
|
||
M --> B
|
||
N --> I
|
||
```
|
||
|
||
#### 5.1.3 提交前校验
|
||
|
||
|校验项|规则|处理方式|
|
||
|---|---|---|
|
||
|总排号格式|必须符合 `两位年份+类型字母(B/C/BW/CW/T)+流水号` 格式；温度计类型流水号必须为4位|扫入时即提示"无效码"|
|
||
|货位号格式|必须符合普通货位或转运特殊货位规则|扫入时即提示"无效码"|
|
||
|两个字段均已填入|确认按钮才可点击|按钮置灰，无法提交|
|
||
|总排号已存在货位记录|后端返回冲突错误|显示错误提示，见 §6.2|
|
||
|
||
#### 5.1.4 提交成功后的状态
|
||
|
||
- 清空总排号字段和货位号字段；
|
||
- 页面回到初始等待扫码状态；
|
||
- 成功反馈持续约 1.5 秒后自动消失；
|
||
- 货位锁定模式未开启时，货位号字段也一并清空。
|
||
|
||
---
|
||
|
||
### 5.2 连续上架模式（锁定货位）
|
||
|
||
#### 5.2.1 进入方式
|
||
|
||
页面上提供"锁定货位"切换控件（Toggle）。工人在货位号字段已填入有效值时，可以开启锁定模式。
|
||
|
||
#### 5.2.2 锁定模式行为
|
||
|
||
|行为|说明|
|
||
|---|---|
|
||
|货位号字段锁定|货位号字段显示为锁定状态，新扫入的货位号码值不会覆盖当前货位号|
|
||
|总排号字段正常工作|每次扫入总排号后，填入总排号字段，等待工人确认|
|
||
|确认提交|提交成功后，仅清空总排号字段，货位号保持不变，页面立即进入等待下一个总排号状态|
|
||
|解除锁定|工人再次点击控件解除锁定，货位号字段恢复可覆盖状态|
|
||
|
||
#### 5.2.3 锁定模式操作流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A([进入上架登记页]) --> B[扫入有效货位号]
|
||
B --> C[开启锁定货位 Toggle]
|
||
C --> D[货位号字段锁定\n新扫入货位码不覆盖]
|
||
D --> E[扫入总排号]
|
||
E --> F{总排号\n是否有效}
|
||
F -->|无效| G[提示无效码] --> E
|
||
F -->|有效| H[填入总排号字段]
|
||
H --> I[工人核查信息\n按确认键提交]
|
||
I --> J[调用后端接口]
|
||
J --> K{结果}
|
||
K -->|成功| L[仅清空总排号字段\n货位号保持锁定]
|
||
K -->|重复上架| M[错误弹窗\n需手动关闭]
|
||
K -->|失败| N[保留数据\n显示错误]
|
||
L --> O{继续\n锁定模式?}
|
||
M --> O
|
||
N --> O
|
||
O -->|是| E
|
||
O -->|解除锁定| P[关闭 Toggle\n货位号字段恢复可覆盖]
|
||
P --> Q([返回单次上架模式])
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 异常与错误处理
|
||
|
||
### 6.1 无效码
|
||
|
||
扫入码值无法识别为总排号或货位号时：
|
||
|
||
- 屏幕顶部短暂显示红色提示条："无效码，请重新扫描"；
|
||
- 当前已填入的有效字段不受影响；
|
||
- 触发错误音效。
|
||
|
||
### 6.2 总排号重复上架（核心错误）
|
||
|
||
后端返回该总排号已存在货位记录：
|
||
|
||
- 页面显示明显的错误提示弹窗，内容包含：
|
||
- 当前总排号；
|
||
- 该总排号已登记的货位号；
|
||
- 登记时间；
|
||
- 提示工人核查实物，确认是否发生了错误操作；
|
||
- 弹窗需要工人主动关闭，不自动消失；
|
||
- 当前页面数据保留，等待工人决定下一步操作；
|
||
- 触发与普通失败不同的错误音效（更明显）。
|
||
|
||
> 设计说明：重复上架在正常业务中不应发生。一旦出现，说明现场可能有问题（如同一产品被两人同时操作、扫错执行卡等），需要工人停下来核查，不应允许静默通过。
|
||
|
||
### 6.3 网络异常
|
||
|
||
接口请求超时或网络不可达：
|
||
|
||
- 屏幕显示"网络异常，请检查网络连接"；
|
||
- 当前已填入的数据保留；
|
||
- 工人可在网络恢复后直接重试，无需重新扫码；
|
||
- 触发失败音效。
|
||
|
||
### 6.4 后端其他错误
|
||
|
||
后端返回其他业务错误：
|
||
|
||
- 显示后端返回的错误描述（需后端统一错误格式）；
|
||
- 当前数据保留，等待工人处理。
|
||
|
||
---
|
||
|
||
## 7. 反馈机制
|
||
|
||
|事件|屏幕|声音|振动|LED|
|
||
|---|---|---|---|---|
|
||
|扫入有效总排号|总排号字段填入，绿色高亮|短促提示音|短震|—|
|
||
|扫入有效货位号|货位号字段填入，绿色高亮|短促提示音|短震|—|
|
||
|扫入无效码|红色提示条|错误音|短震|红色闪烁|
|
||
|提交成功|全屏绿色提示 1.5 秒|成功音|长震|绿色常亮 1.5 秒|
|
||
|重复上架错误|红色错误弹窗（需手动关闭）|连续错误音|连续震|红色闪烁|
|
||
|网络异常|黄色提示条|失败音|短震|—|
|
||
|
||
---
|
||
|
||
## 8. 页面结构
|
||
|
||
### 8.1 主页面布局
|
||
|
||
```
|
||
┌──────────────────────────────┐
|
||
│ 上架登记 [锁定货位 ○] │ ← 顶部标题栏 + 锁定控件
|
||
├──────────────────────────────┤
|
||
│ │
|
||
│ 总排号 │
|
||
│ ┌────────────────────────┐ │
|
||
│ │ 26B1 │ │ ← 已扫入时绿色边框
|
||
│ └────────────────────────┘ │
|
||
│ │
|
||
│ 目标货位 │
|
||
│ ┌────────────────────────┐ │
|
||
│ │ A01-02-03 [普通货架] │ │ ← 货位类型标签
|
||
│ └────────────────────────┘ │ ← 锁定时显示锁图标
|
||
│ │
|
||
│ ┌────────────────────────┐ │
|
||
│ │ 确 认 上 架 │ │ ← 两个字段均已填入时高亮
|
||
│ └────────────────────────┘ │
|
||
│ │
|
||
├──────────────────────────────┤
|
||
│ ● 等待扫描总排号... │ ← 当前状态提示
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
### 8.2 状态提示栏文案
|
||
|
||
|当前状态|提示文案|
|
||
|---|---|
|
||
|两个字段均为空|等待扫描总排号或货位号…|
|
||
|仅总排号已填入|请扫描目标货位号|
|
||
|仅货位号已填入|请扫描执行卡|
|
||
|两个字段均已填入|请确认信息并提交|
|
||
|提交中|正在提交…|
|
||
|锁定模式下提交成功|货位已锁定，请扫描下一张执行卡|
|
||
|
||
### 8.3 货位类型标签
|
||
|
||
|货位类型|标签文字|标签颜色|
|
||
|---|---|---|
|
||
|普通货架货位|普通货架|蓝色|
|
||
|转运特殊货位|转运区域|橙色|
|
||
|
||
---
|
||
|
||
## 9. 接口依赖
|
||
|
||
### 9.1 上架登记接口
|
||
|
||
**POST** `/CargoTrace/location`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"zongpai_no": "26B1",
|
||
"location_code": "A01-02-03"
|
||
}
|
||
```
|
||
|
||
成功响应：`200 OK`
|
||
|
||
失败响应：
|
||
|
||
|HTTP 状态码|错误码|含义|
|
||
|---|---|---|
|
||
|409 Conflict|`DUPLICATE_LOCATION`|该总排号已存在货位记录|
|
||
|400 Bad Request|`INVALID_ZONGPAI`|总排号不存在|
|
||
|400 Bad Request|`INVALID_LOCATION`|货位号不合法|
|
||
|500|`SERVER_ERROR`|服务器内部错误|
|
||
|
||
---
|
||
|
||
## 10. 非功能要求
|
||
|
||
|项目|要求|
|
||
|---|---|
|
||
|接口响应时间|正常网络下 ≤ 500ms|
|
||
|扫码到字段填入延迟|≤ 100ms（本地处理，无网络请求）|
|
||
|离线处理策略|断网时不允许提交，提示工人检查网络，数据保留在页面上|
|
||
|货位类型本地判断|货位类型（普通/转运）由客户端根据编码规则本地判断，不依赖接口|
|
||
|
||
---
|
||
|
||
## 11. 超出当前版本范围
|
||
|
||
以下内容在当前版本中不实现：
|
||
|
||
- 操作日志与操作人员记录（登录功能待定）；
|
||
- 重复上架的强制覆盖功能；
|
||
- 离线缓存与联网同步；
|
||
- 总排号货位变更历史查询。 |