94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# 上架登记模块设计文档
|
||
|
||
日期：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
|
||
- 总排号输入显示区（扫入时绿色边框）
|
||
- 货位号显示区 + 货位类型标签（蓝/橙）
|
||
- 确认上架按钮（两字段均填入时高亮）
|
||
- 底部状态提示栏
|