Files

Misaka_Company d136dbf947 chore: remove obsolete tests, add design docs and PRD

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-05-09 14:32:24 +08:00

11 KiB

Raw Permalink Blame History

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 操作流程

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 锁定模式操作流程

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

请求体：

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

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

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

11 KiB Raw Permalink Blame History Unescape Escape