# 上架登记模块设计文档

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