# 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. 超出当前版本范围

以下内容在当前版本中不实现：

- 操作日志与操作人员记录（登录功能待定）；
- 重复上架的强制覆盖功能；
- 离线缓存与联网同步；
- 总排号货位变更历史查询。