pad_scanner/docs/plans/2026-05-09-registration-design.md

上架登记模块设计文档

日期：2026-05-09 状态：已批准

---

1. 概述

基于 PRD v1.0 实现上架登记模块，完全替换现有 ScanPage。支持单次上架和连续上架（锁定货位）两种模式。新增配置页面管理 API 地址。

2. 架构

延续现有轻量架构，不引入额外状态管理框架。使用 setState + 简单状态类。

文件结构

lib/
├── main.dart                      # MaterialApp + 路由
├── models/
│   ├── registration_state.dart    # 上架登记页面状态
│   └── api_config.dart            # API 配置模型
├── pages/
│   ├── registration_page.dart     # 上架登记主页（替换 ScanPage）
│   └── settings_page.dart         # 重构：API地址 + 保存 + 测试连接
├── services/
│   ├── api_service.dart           # 重写：适配 /CargoTrace/location
│   ├── code_parser.dart           # 新增：码值识别
│   └── scanner_service.dart       # 保持不变

3. 核心组件

3.1 CodeParser（码值识别）

静态工具类，实现 PRD §4 规则：

• 总排号：^\d{2}(B|C|T)\d+$ 或 ^\d{2}(BW|CW)\d{4}$
• 普通货位：[区域货架]-[层]-[格] 全大写横杠分隔
• 转运货位：TRANS- 开头
• 无效码：不匹配以上规则

返回枚举类型：zongpaiNo / locationNormal / locationTransit / invalid

3.2 RegistrationPage（上架登记主页）

状态字段：

• zongpaiNo / locationCode / isLocked / isSubmitting / statusText / errorType

扫码处理流程：

1. ScannerService 收到扫码事件
2. CodeParser 识别码值类型
3. 根据类型填入对应字段（重复同类型覆盖）
4. 锁定模式下货位号不接受新扫码值
5. 两字段均非空时确认按钮高亮
6. 提交 → 调用 ApiService → 处理结果

3.3 SettingsPage（配置页）

• API 地址输入框
• 保存设置按钮 → SharedPreferences 持久化
• 测试连接按钮 → HEAD/GET 请求验证可达性
• 返回按钮

3.4 ApiService（API 服务）

• POST {baseUrl}/CargoTrace/location
• 请求体：{ "zongpai_no": "...", "location_code": "..." }
• 处理 200/409/400/500 响应
• 超时 5 秒

4. 错误处理

错误类型	UI 表现
无效码	红色 SnackBar，已有字段不受影响
重复上架 (409)	Dialog 弹窗，显示已有货位和登记时间，需手动关闭
网络异常	黄色提示条，数据保留，可重试
其他业务错误	显示后端错误描述，数据保留

5. 反馈机制（当前版本）

仅实现屏幕反馈：颜色变化、状态提示文案、弹窗。声音/振动/LED 留后续版本。

6. 页面布局

参照 PRD §8.1 的 ASCII 布局：

• 顶部标题栏 + 锁定货位 Toggle
• 总排号输入显示区（扫入时绿色边框）
• 货位号显示区 + 货位类型标签（蓝/橙）
• 确认上架按钮（两字段均填入时高亮）
• 底部状态提示栏