chore: ignore android/build directory

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

.gitignore

@@ -32,6 +32,7 @@ migrate_working_dir/
 .pub-cache/
 .pub/
 /build/
+android/build/
 
 # Symbolication related
 app.*.symbols
@@ -43,6 +44,7 @@ app.*.map.json
 /android/app/debug
 /android/app/profile
 /android/app/release
+/android/build/
 
 # AI Agents
 .claude/

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

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

docs/plans/2026-05-09-registration-plan.md

@@ -0,0 +1,941 @@
+# 上架登记模块 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the generic ScanPage with a shelf-registration (上架登记) module that validates scanned barcodes, binds execution card numbers to warehouse locations, and provides API configuration.
+
+**Architecture:** Lightweight Flutter app using setState for state management, EventChannel for native barcode scanner, SharedPreferences for config persistence, and http package for API calls. CodeParser provides pure regex-based barcode classification.
+
+**Tech Stack:** Flutter 3.x, Dart, http, shared_preferences, Android native EventChannel (SEUIC scanner)
+
+---
+
+### Task 1: CodeParser — barcode classification service
+
+**Files:**
+- Create: `lib/services/code_parser.dart`
+- Test: `test/services/code_parser_test.dart`
+
+**Step 1: Write the tests**
+
+```dart
+// test/services/code_parser_test.dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pad_scanner/services/code_parser.dart';
+
+void main() {
+  group('CodeParser.parse', () {
+    test('identifies zongpaiNo type B', () {
+      final result = CodeParser.parse('26B1');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26B1');
+    });
+
+    test('identifies zongpaiNo type C', () {
+      final result = CodeParser.parse('26C12');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26C12');
+    });
+
+    test('identifies zongpaiNo type T', () {
+      final result = CodeParser.parse('26T3');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26T3');
+    });
+
+    test('identifies zongpaiNo type BW (thermometer, 4 digits)', () {
+      final result = CodeParser.parse('26BW0001');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26BW0001');
+    });
+
+    test('identifies zongpaiNo type CW (thermometer, 4 digits)', () {
+      final result = CodeParser.parse('26CW0015');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26CW0015');
+    });
+
+    test('rejects BW with non-4-digit serial', () {
+      final result = CodeParser.parse('26BW01');
+      expect(result.type, CodeType.invalid);
+    });
+
+    test('rejects CW with non-4-digit serial', () {
+      final result = CodeParser.parse('26CW15');
+      expect(result.type, CodeType.invalid);
+    });
+
+    test('identifies normal location code', () {
+      final result = CodeParser.parse('A01-02-03');
+      expect(result.type, CodeType.locationNormal);
+      expect(result.value, 'A01-02-03');
+    });
+
+    test('identifies transit location code', () {
+      final result = CodeParser.parse('TRANS-01');
+      expect(result.type, CodeType.locationTransit);
+      expect(result.value, 'TRANS-01');
+    });
+
+    test('rejects lowercase location code', () {
+      final result = CodeParser.parse('a01-02-03');
+      expect(result.type, CodeType.invalid);
+    });
+
+    test('rejects completely invalid code', () {
+      final result = CodeParser.parse('HELLO123');
+      expect(result.type, CodeType.invalid);
+    });
+
+    test('rejects empty string', () {
+      final result = CodeParser.parse('');
+      expect(result.type, CodeType.invalid);
+    });
+
+    test('isLocation helper returns true for normal location', () {
+      expect(CodeParser.isLocation(CodeType.locationNormal), true);
+      expect(CodeParser.isLocation(CodeType.locationTransit), true);
+      expect(CodeParser.isLocation(CodeType.zongpaiNo), false);
+      expect(CodeParser.isLocation(CodeType.invalid), false);
+    });
+
+    test('identifies production number format (reserved, still invalid)', () {
+      final result = CodeParser.parse('R00001');
+      expect(result.type, CodeType.invalid);
+    });
+  });
+}
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `flutter test test/services/code_parser_test.dart`
+Expected: FAIL — `code_parser.dart` does not exist
+
+**Step 3: Write the implementation**
+
+```dart
+// lib/services/code_parser.dart
+/// Regex-based barcode classifier per PRD §4.
+class CodeParser {
+  // 总排号: YY + B/C/T + digits, or YY + BW/CW + exactly 4 digits
+  static final _zongpaiRegex = RegExp(
+    r'^\d{2}(B|C|T)\d+$|^\d{2}(BW|CW)\d{4}$',
+  );
+
+  // 普通货位: AREA-LEVEL-SLOT, all uppercase letters/digits separated by dashes
+  static final _locationRegex = RegExp(
+    r'^[A-Z0-9]+-[A-Z0-9]+-[A-Z0-9]+$',
+  );
+
+  // 转运货位: TRANS-xxx
+  static final _transitRegex = RegExp(
+    r'^TRANS-',
+  );
+
+  /// Parse a scanned code string and return its classification.
+  static ParseResult parse(String code) {
+    if (code.isEmpty) {
+      return ParseResult(type: CodeType.invalid, value: code);
+    }
+
+    // Check transit first (TRANS- prefix)
+    if (_transitRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.locationTransit, value: code);
+    }
+
+    // Check zongpai number
+    if (_zongpaiRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.zongpaiNo, value: code);
+    }
+
+    // Check normal location
+    if (_locationRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.locationNormal, value: code);
+    }
+
+    return ParseResult(type: CodeType.invalid, value: code);
+  }
+
+  /// Returns true if the code type represents any location.
+  static bool isLocation(CodeType type) =>
+      type == CodeType.locationNormal || type == CodeType.locationTransit;
+}
+
+enum CodeType { zongpaiNo, locationNormal, locationTransit, invalid }
+
+class ParseResult {
+  final CodeType type;
+  final String value;
+  ParseResult({required this.type, required this.value});
+}
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `flutter test test/services/code_parser_test.dart`
+Expected: All PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/services/code_parser.dart test/services/code_parser_test.dart
+git commit -m "feat: add CodeParser for barcode classification per PRD §4"
+```
+
+---
+
+### Task 2: ApiService — rewrite for registration API
+
+**Files:**
+- Modify: `lib/services/api_service.dart` (full rewrite)
+- Delete: `lib/models/scan_record.dart` (no longer needed)
+
+**Step 1: Write the new ApiService**
+
+```dart
+// lib/services/api_service.dart
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+
+/// Result of a registration API call.
+class RegistrationResult {
+  final bool success;
+  final bool isDuplicate;
+  final String? errorMessage;
+  final Map<String, dynamic>? duplicateInfo;
+
+  RegistrationResult({
+    required this.success,
+    this.isDuplicate = false,
+    this.errorMessage,
+    this.duplicateInfo,
+  });
+
+  factory RegistrationResult.ok() =>
+      RegistrationResult(success: true);
+
+  factory RegistrationResult.duplicate(Map<String, dynamic> info) =>
+      RegistrationResult(success: false, isDuplicate: true, duplicateInfo: info);
+
+  factory RegistrationResult.error(String message) =>
+      RegistrationResult(success: false, errorMessage: message);
+}
+
+class ApiService {
+  final http.Client _client;
+  final Duration timeout;
+
+  ApiService({http.Client? client, this.timeout = const Duration(seconds: 5)})
+      : _client = client ?? http.Client();
+
+  /// Submit a shelf registration (上架登记).
+  Future<RegistrationResult> registerLocation({
+    required String baseUrl,
+    required String zongpaiNo,
+    required String locationCode,
+  }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/location');
+    try {
+      final response = await _client
+          .post(
+            uri,
+            headers: {'Content-Type': 'application/json'},
+            body: jsonEncode({
+              'zongpai_no': zongpaiNo,
+              'location_code': locationCode,
+            }),
+          )
+          .timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          return RegistrationResult.ok();
+        case 409:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return RegistrationResult.duplicate(body);
+        default:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final msg = body['error'] ?? body['message'] ?? 'Unknown error (${response.statusCode})';
+          return RegistrationResult.error(msg.toString());
+      }
+    } catch (e) {
+      return RegistrationResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  /// Test connectivity by making a HEAD request to the base URL.
+  Future<bool> testConnection(String baseUrl) async {
+    try {
+      final uri = Uri.parse(baseUrl);
+      final response = await _client.head(uri).timeout(timeout);
+      return response.statusCode < 500;
+    } catch (_) {
+      return false;
+    }
+  }
+}
+```
+
+**Step 2: Verify compilation**
+
+Run: `flutter analyze lib/services/api_service.dart`
+Expected: No issues
+
+**Step 3: Commit**
+
+```bash
+git add lib/services/api_service.dart
+git rm lib/models/scan_record.dart
+git commit -m "feat: rewrite ApiService for registration API, remove ScanRecord model"
+```
+
+---
+
+### Task 3: SettingsPage — rewrite with save + test connection
+
+**Files:**
+- Modify: `lib/pages/settings_page.dart` (full rewrite)
+
+**Step 1: Write the new SettingsPage**
+
+```dart
+// lib/pages/settings_page.dart
+import 'package:flutter/material.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:pad_scanner/services/api_service.dart';
+
+class SettingsPage extends StatefulWidget {
+  const SettingsPage({super.key});
+
+  @override
+  State<SettingsPage> createState() => _SettingsPageState();
+}
+
+class _SettingsPageState extends State<SettingsPage> {
+  final _controller = TextEditingController();
+  final _apiService = ApiService();
+  bool _saving = false;
+  bool _testing = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _loadUrl();
+  }
+
+  Future<void> _loadUrl() async {
+    final prefs = await SharedPreferences.getInstance();
+    final url = prefs.getString('api_url') ?? '';
+    _controller.text = url;
+  }
+
+  Future<void> _saveUrl() async {
+    final url = _controller.text.trim();
+    if (url.isEmpty) {
+      _showSnackBar('请输入 API 地址', isError: true);
+      return;
+    }
+    setState(() => _saving = true);
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString('api_url', url);
+    setState(() => _saving = false);
+    if (mounted) {
+      _showSnackBar('设置已保存');
+    }
+  }
+
+  Future<void> _testConnection() async {
+    final url = _controller.text.trim();
+    if (url.isEmpty) {
+      _showSnackBar('请先输入 API 地址', isError: true);
+      return;
+    }
+    setState(() => _testing = true);
+    final ok = await _apiService.testConnection(url);
+    setState(() => _testing = false);
+    if (mounted) {
+      _showSnackBar(
+        ok ? '连接成功' : '连接失败，请检查地址和网络',
+        isError: !ok,
+      );
+    }
+  }
+
+  void _showSnackBar(String message, {bool isError = false}) {
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(
+        content: Text(message),
+        backgroundColor: isError ? Colors.red.shade700 : Colors.green.shade700,
+        duration: const Duration(seconds: 2),
+      ),
+    );
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('设置')),
+      body: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            const Text('API 服务器地址', style: TextStyle(fontSize: 14)),
+            const SizedBox(height: 8),
+            TextField(
+              controller: _controller,
+              decoration: const InputDecoration(
+                hintText: 'http://192.168.1.100:8000',
+                border: OutlineInputBorder(),
+              ),
+              keyboardType: TextInputType.url,
+            ),
+            const SizedBox(height: 20),
+            ElevatedButton.icon(
+              onPressed: _saving ? null : _saveUrl,
+              icon: _saving
+                  ? const SizedBox(
+                      width: 18,
+                      height: 18,
+                      child: CircularProgressIndicator(strokeWidth: 2),
+                    )
+                  : const Icon(Icons.save),
+              label: const Text('保存设置'),
+            ),
+            const SizedBox(height: 8),
+            OutlinedButton.icon(
+              onPressed: _testing ? null : _testConnection,
+              icon: _testing
+                  ? const SizedBox(
+                      width: 18,
+                      height: 18,
+                      child: CircularProgressIndicator(strokeWidth: 2),
+                    )
+                  : const Icon(Icons.wifi),
+              label: const Text('测试连接'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+**Step 2: Verify compilation**
+
+Run: `flutter analyze lib/pages/settings_page.dart`
+Expected: No issues
+
+**Step 3: Commit**
+
+```bash
+git add lib/pages/settings_page.dart
+git commit -m "feat: rewrite SettingsPage with save and test-connection"
+```
+
+---
+
+### Task 4: RegistrationPage — main shelf registration UI
+
+**Files:**
+- Create: `lib/pages/registration_page.dart`
+
+**Step 1: Write the RegistrationPage**
+
+This is the main page. It handles:
+- Scanner event stream subscription
+- Barcode classification via CodeParser
+- State management for zongpaiNo, locationCode, lock mode
+- Submit flow with error handling
+- PRD §8 layout
+
+```dart
+// lib/pages/registration_page.dart
+import 'package:flutter/material.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:pad_scanner/services/scanner_service.dart';
+import 'package:pad_scanner/services/code_parser.dart';
+import 'package:pad_scanner/services/api_service.dart';
+import 'package:pad_scanner/pages/settings_page.dart';
+
+class RegistrationPage extends StatefulWidget {
+  const RegistrationPage({super.key});
+
+  @override
+  State<RegistrationPage> createState() => _RegistrationPageState();
+}
+
+class _RegistrationPageState extends State<RegistrationPage> {
+  final _scannerService = ScannerService();
+  final _apiService = ApiService();
+
+  String? _zongpaiNo;
+  String? _locationCode;
+  CodeType? _locationType;
+  bool _isLocked = false;
+  bool _isSubmitting = false;
+
+  // Feedback state
+  String? _successMessage;
+  String? _snackbarMessage;
+  Color? _snackbarColor;
+
+  @override
+  void initState() {
+    super.initState();
+    _scannerService.scanResults.listen(_onScan);
+  }
+
+  void _onScan(ScanResult result) {
+    final parsed = CodeParser.parse(result.barcode);
+    switch (parsed.type) {
+      case CodeType.zongpaiNo:
+        setState(() {
+          _zongpaiNo = parsed.value;
+          _snackbarMessage = null;
+          _successMessage = null;
+        });
+      case CodeType.locationNormal:
+      case CodeType.locationTransit:
+        if (!_isLocked) {
+          setState(() {
+            _locationCode = parsed.value;
+            _locationType = parsed.type;
+            _snackbarMessage = null;
+            _successMessage = null;
+          });
+        }
+      case CodeType.invalid:
+        _showFeedback('无效码，请重新扫描', isError: true);
+    }
+  }
+
+  void _showFeedback(String message, {bool isError = false}) {
+    setState(() {
+      _snackbarMessage = message;
+      _snackbarColor = isError ? Colors.red.shade700 : Colors.green.shade700;
+    });
+    Future.delayed(const Duration(seconds: 2), () {
+      if (mounted) setState(() => _snackbarMessage = null);
+    });
+  }
+
+  String get _statusText {
+    if (_isSubmitting) return '正在提交…';
+    if (_successMessage != null) return _successMessage!;
+    if (_isLocked && _locationCode != null && _zongpaiNo == null) {
+      return '货位已锁定，请扫描下一张执行卡';
+    }
+    final hasZ = _zongpaiNo != null;
+    final hasL = _locationCode != null;
+    if (hasZ && hasL) return '请确认信息并提交';
+    if (hasZ && !hasL) return '请扫描目标货位号';
+    if (!hasZ && hasL) return '请扫描执行卡';
+    return '等待扫描总排号或货位号…';
+  }
+
+  bool get _canSubmit =>
+      _zongpaiNo != null &&
+      _locationCode != null &&
+      !_isSubmitting;
+
+  Future<void> _submit() async {
+    if (!_canSubmit) return;
+
+    final prefs = await SharedPreferences.getInstance();
+    final baseUrl = prefs.getString('api_url') ?? '';
+    if (baseUrl.isEmpty) {
+      _showFeedback('未配置 API 地址，请前往设置', isError: true);
+      return;
+    }
+
+    setState(() => _isSubmitting = true);
+
+    final result = await _apiService.registerLocation(
+      baseUrl: baseUrl,
+      zongpaiNo: _zongpaiNo!,
+      locationCode: _locationCode!,
+    );
+
+    if (!mounted) return;
+
+    setState(() => _isSubmitting = false);
+
+    if (result.success) {
+      setState(() {
+        _zongpaiNo = null;
+        if (!_isLocked) {
+          _locationCode = null;
+          _locationType = null;
+        }
+        _successMessage = _isLocked
+            ? '货位已锁定，请扫描下一张执行卡'
+            : '上架成功';
+      });
+      _showFeedback(
+        _isLocked ? '上架成功' : '上架成功',
+        isError: false,
+      );
+      // Auto-clear success message
+      Future.delayed(const Duration(milliseconds: 1500), () {
+        if (mounted) setState(() => _successMessage = null);
+      });
+    } else if (result.isDuplicate) {
+      _showDuplicateDialog(result.duplicateInfo);
+    } else {
+      _showFeedback(result.errorMessage ?? '提交失败', isError: true);
+    }
+  }
+
+  void _showDuplicateDialog(Map<String, dynamic>? info) {
+    showDialog(
+      context: context,
+      barrierDismissible: false,
+      builder: (ctx) => AlertDialog(
+        backgroundColor: Colors.red.shade50,
+        title: const Row(
+          children: [
+            Icon(Icons.warning, color: Colors.red),
+            SizedBox(width: 8),
+            Text('重复上架', style: TextStyle(color: Colors.red)),
+          ],
+        ),
+        content: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text('总排号：${_zongpaiNo ?? ""}'),
+            const SizedBox(height: 4),
+            Text('已登记货位：${info?["location_code"] ?? "未知"}'),
+            const SizedBox(height: 4),
+            Text('登记时间：${info?["registered_at"] ?? "未知"}'),
+            const SizedBox(height: 12),
+            const Text('请核查实物，确认是否操作错误。', style: TextStyle(fontWeight: FontWeight.bold)),
+          ],
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(ctx),
+            child: const Text('关闭'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  void _toggleLock(bool value) {
+    if (value && _locationCode == null) {
+      _showFeedback('请先扫描货位号', isError: true);
+      return;
+    }
+    setState(() => _isLocked = value);
+  }
+
+  String _locationLabel(CodeType? type) {
+    if (type == CodeType.locationTransit) return '转运区域';
+    return '普通货架';
+  }
+
+  Color _locationLabelColor(CodeType? type) {
+    if (type == CodeType.locationTransit) return Colors.orange;
+    return Colors.blue;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('上架登记'),
+        actions: [
+          // Lock toggle in app bar
+          Padding(
+            padding: const EdgeInsets.only(right: 4),
+            child: Row(
+              children: [
+                const Text('锁定货位', style: TextStyle(fontSize: 13)),
+                Switch(
+                  value: _isLocked,
+                  onChanged: _toggleLock,
+                ),
+                IconButton(
+                  icon: const Icon(Icons.settings),
+                  onPressed: () => Navigator.push(
+                    context,
+                    MaterialPageRoute(builder: (_) => const SettingsPage()),
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+      body: Column(
+        children: [
+          // Feedback snackbar area
+          if (_snackbarMessage != null)
+            Container(
+              width: double.infinity,
+              padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+              color: _snackbarColor,
+              child: Text(
+                _snackbarMessage!,
+                style: const TextStyle(color: Colors.white, fontSize: 14),
+                textAlign: TextAlign.center,
+              ),
+            ),
+
+          // Main form area
+          Expanded(
+            child: Padding(
+              padding: const EdgeInsets.all(16),
+              child: Column(
+                children: [
+                  // Zongpai number field
+                  const Align(
+                    alignment: Alignment.centerLeft,
+                    child: Text('总排号', style: TextStyle(fontSize: 14, fontWeight: FontWeight.w500)),
+                  ),
+                  const SizedBox(height: 6),
+                  Container(
+                    width: double.infinity,
+                    padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 14),
+                    decoration: BoxDecoration(
+                      border: Border.all(
+                        color: _zongpaiNo != null ? Colors.green : Colors.grey.shade400,
+                        width: _zongpaiNo != null ? 2 : 1,
+                      ),
+                      borderRadius: BorderRadius.circular(8),
+                    ),
+                    child: Text(
+                      _zongpaiNo ?? '',
+                      style: TextStyle(
+                        fontSize: 20,
+                        fontWeight: FontWeight.bold,
+                        color: _zongpaiNo != null ? Colors.black87 : Colors.grey,
+                      ),
+                    ),
+                  ),
+
+                  const SizedBox(height: 20),
+
+                  // Location field
+                  Row(
+                    children: [
+                      const Text('目标货位', style: TextStyle(fontSize: 14, fontWeight: FontWeight.w500)),
+                      if (_locationCode != null) ...[
+                        const SizedBox(width: 8),
+                        Container(
+                          padding: const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
+                          decoration: BoxDecoration(
+                            color: _locationLabelColor(_locationType).withValues(alpha: 0.15),
+                            borderRadius: BorderRadius.circular(4),
+                          ),
+                          child: Text(
+                            _locationLabel(_locationType),
+                            style: TextStyle(
+                              fontSize: 11,
+                              color: _locationLabelColor(_locationType),
+                              fontWeight: FontWeight.bold,
+                            ),
+                          ),
+                        ),
+                      ],
+                    ],
+                  ),
+                  const SizedBox(height: 6),
+                  Container(
+                    width: double.infinity,
+                    padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 14),
+                    decoration: BoxDecoration(
+                      border: Border.all(
+                        color: _locationCode != null ? Colors.green : Colors.grey.shade400,
+                        width: _locationCode != null ? 2 : 1,
+                      ),
+                      borderRadius: BorderRadius.circular(8),
+                    ),
+                    child: Row(
+                      children: [
+                        Expanded(
+                          child: Text(
+                            _locationCode ?? '',
+                            style: TextStyle(
+                              fontSize: 20,
+                              fontWeight: FontWeight.bold,
+                              color: _locationCode != null ? Colors.black87 : Colors.grey,
+                            ),
+                          ),
+                        ),
+                        if (_isLocked)
+                          const Icon(Icons.lock, color: Colors.orange, size: 20),
+                      ],
+                    ),
+                  ),
+
+                  const SizedBox(height: 28),
+
+                  // Submit button
+                  SizedBox(
+                    width: double.infinity,
+                    height: 48,
+                    child: ElevatedButton(
+                      onPressed: _canSubmit ? _submit : null,
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor: _canSubmit
+                            ? colorScheme.primary
+                            : Colors.grey.shade300,
+                        foregroundColor: _canSubmit
+                            ? Colors.white
+                            : Colors.grey.shade600,
+                        shape: RoundedRectangleBorder(
+                          borderRadius: BorderRadius.circular(8),
+                        ),
+                      ),
+                      child: _isSubmitting
+                          ? const SizedBox(
+                              width: 22,
+                              height: 22,
+                              child: CircularProgressIndicator(
+                                strokeWidth: 2,
+                                color: Colors.white,
+                              ),
+                            )
+                          : const Text('确 认 上 架', style: TextStyle(fontSize: 18)),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ),
+
+          // Status bar at bottom
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
+            color: colorScheme.surfaceContainerHighest,
+            child: Row(
+              children: [
+                Container(
+                  width: 8,
+                  height: 8,
+                  decoration: BoxDecoration(
+                    color: _isSubmitting
+                        ? Colors.orange
+                        : _successMessage != null
+                            ? Colors.green
+                            : Colors.blue,
+                    shape: BoxShape.circle,
+                  ),
+                ),
+                const SizedBox(width: 8),
+                Expanded(
+                  child: Text(
+                    _statusText,
+                    style: const TextStyle(fontSize: 14),
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+**Step 2: Verify compilation**
+
+Run: `flutter analyze lib/pages/registration_page.dart`
+Expected: No issues
+
+**Step 3: Commit**
+
+```bash
+git add lib/pages/registration_page.dart
+git commit -m "feat: add RegistrationPage with single and lock-mode shelf registration"
+```
+
+---
+
+### Task 5: main.dart — wire up RegistrationPage as home
+
+**Files:**
+- Modify: `lib/main.dart`
+- Delete: `lib/pages/scan_page.dart`
+
+**Step 1: Update main.dart**
+
+```dart
+// lib/main.dart
+import 'package:flutter/material.dart';
+import 'package:pad_scanner/pages/registration_page.dart';
+
+void main() {
+  runApp(const PadScannerApp());
+}
+
+class PadScannerApp extends StatelessWidget {
+  const PadScannerApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: '上架登记',
+      theme: ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
+        useMaterial3: true,
+      ),
+      home: const RegistrationPage(),
+    );
+  }
+}
+```
+
+**Step 2: Delete old ScanPage**
+
+```bash
+git rm lib/pages/scan_page.dart
+```
+
+**Step 3: Verify full project compiles**
+
+Run: `flutter analyze`
+Expected: No issues
+
+**Step 4: Commit**
+
+```bash
+git add lib/main.dart
+git commit -m "feat: wire RegistrationPage as app home, remove ScanPage"
+```
+
+---
+
+### Task 6: Final verification
+
+**Step 1: Run all tests**
+
+Run: `flutter test`
+Expected: All tests pass
+
+**Step 2: Run full analysis**
+
+Run: `flutter analyze`
+Expected: No issues found
+
+**Step 3: Verify no dangling imports**
+
+Search for any remaining references to `scan_page.dart` or `scan_record.dart`:
+Run: `grep -r "scan_page\|scan_record" lib/`
+Expected: No matches

docs/plans/2026-05-09-sound-settings-design.md

@@ -0,0 +1,38 @@
+# 铃声配置功能设计
+
+## 概述
+在设置页新增铃声配置入口，用户可以为"上架成功"和"上架失败"分别指定本地音频文件作为提示铃声。
+
+## 依赖
+- `file_picker` — 从设备选择音频文件（支持 mp3/wav/ogg/aac/m4a/flac）
+- `audioplayers` — 播放本地音频文件
+
+## 数据存储
+使用 `SharedPreferences`：
+- `sound_success` — 上架成功铃声文件路径
+- `sound_failure` — 上架失败铃声文件路径
+
+## UI 设计
+设置页新增"铃声设置"分区，API 地址下方：
+
+```
+铃声设置
+─────────────────────────────
+上架成功铃声
+[当前文件名或"未设置"]  [选择] [试听] [清除]
+
+上架失败铃声
+[当前文件名或"未设置"]  [选择] [试听] [清除]
+```
+
+## 音频播放逻辑
+- 封装为 `SoundService`，统一管理播放
+- 通过 `DeviceFileSource` 播放本地文件
+- 上架成功/失败时检查是否配置了铃声，有则播放
+- 保留现有震动反馈，铃声与震动并行
+
+## 涉及文件
+1. `pubspec.yaml` — 添加依赖
+2. `lib/services/sound_service.dart` — 新建，封装音频播放
+3. `lib/pages/settings_page.dart` — 新增铃声配置 UI
+4. `lib/pages/registration_page.dart` — 集成铃声播放

docs/plans/2026-05-11-boxing-module.md

@@ -0,0 +1,519 @@
+# 装箱编号模块 Implementation Plan — Flutter
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 实现 PRD v1.3 中定义的装箱编号模块 Flutter 页面，支持三种装箱模式（一码一箱、一码多箱、多码一箱），包含扫码识别、信息查询、自动填充、重复校验和提交功能。
+
+**Architecture:** 在现有 Flutter 应用基础上扩展，使用 setState 管理 UI 状态，EventChannel 接收扫码数据，http 包调用后端 API。新增 BoxingPage 和 BoxingDetailPage 两个页面。
+
+**Tech Stack:** Flutter 3.x, Dart, http, shared_preferences, Android native EventChannel (SEUIC scanner)
+
+---
+
+## 页面结构
+
+```
+HomePage
+  ├── 上架登记 (RegistrationPage)  ← 已完成
+  ├── 装箱编号 (BoxingPage)        ← 本次实现
+  │   └── 装箱详情 (BoxingDetailPage) ← 子页面
+  └── 货架查询                      ← 规划中
+```
+
+## 状态机设计
+
+三种装箱模式对应不同的状态流转：
+
+```
+一码一箱: 等待扫码 → 扫码后自动填充箱号+数量 → 确认 → 成功(1.5s) → 重置等待扫码
+一码多箱: 等待扫码 → 扫码后自动填充箱号 → 手动填数量 → 确认 → 成功
+          → "继续添加": 预填箱号+1、预填上次数量 → 确认 → ...
+          → "返回": 重置等待扫码
+多码一箱: 等待扫码 → 扫码后填充+锁定箱号+数量 → 确认 → 成功
+          → 自动等待下一个扫码 → 箱号锁定 → 自动填充新数量 → 确认 → ...
+          → "返回": 重置等待扫码
+```
+
+---
+
+### Task 1: ApiService 扩展 — 装箱 API 方法
+
+**Files:**
+- Modify: `lib/services/api_service.dart`
+
+**Step 1: 添加装箱相关的数据类和 API 方法**
+
+在文件末尾（`ApiService` 类内部）新增以下方法，在文件顶部新增数据类：
+
+```dart
+// === 装箱模块数据类 ===
+
+/// 装箱信息查询结果
+class BoxInfoResult {
+  final bool success;
+  final String? errorMessage;
+  final String? errorCode;
+  final String? zongpaiNo;
+  final String? paichanNo;
+  final int? quantity;
+  final List<BoxDetailData> existingBoxes;
+  final int maxBoxNo;
+  final int suggestedBoxNo;
+
+  BoxInfoResult({
+    required this.success,
+    this.errorMessage,
+    this.errorCode,
+    this.zongpaiNo,
+    this.paichanNo,
+    this.quantity,
+    this.existingBoxes = const [],
+    this.maxBoxNo = 0,
+    this.suggestedBoxNo = 1,
+  });
+
+  factory BoxInfoResult.ok(Map<String, dynamic> json) {
+    final boxes = (json['existing_boxes'] as List<dynamic>?)
+            ?.map((b) => BoxDetailData.fromJson(b as Map<String, dynamic>))
+            .toList() ??
+        [];
+    return BoxInfoResult(
+      success: true,
+      zongpaiNo: json['zongpai_no'] as String?,
+      paichanNo: json['paichan_no'] as String?,
+      quantity: json['quantity'] as int?,
+      existingBoxes: boxes,
+      maxBoxNo: json['max_box_no'] as int? ?? 0,
+      suggestedBoxNo: json['suggested_box_no'] as int? ?? 1,
+    );
+  }
+
+  factory BoxInfoResult.error(String message, {String? errorCode}) {
+    return BoxInfoResult(success: false, errorMessage: message, errorCode: errorCode);
+  }
+}
+
+/// 箱号明细
+class BoxDetailData {
+  final int boxNo;
+  final List<BoxItemData> items;
+
+  BoxDetailData({required this.boxNo, required this.items});
+
+  factory BoxDetailData.fromJson(Map<String, dynamic> json) {
+    final items = (json['items'] as List<dynamic>?)
+            ?.map((i) => BoxItemData.fromJson(i as Map<String, dynamic>))
+            .toList() ??
+        [];
+    return BoxDetailData(boxNo: json['box_no'] as int, items: items);
+  }
+}
+
+/// 箱号内单个总排号明细
+class BoxItemData {
+  final String zongpaiNo;
+  final int quantity;
+
+  BoxItemData({required this.zongpaiNo, required this.quantity});
+
+  factory BoxItemData.fromJson(Map<String, dynamic> json) {
+    return BoxItemData(
+      zongpaiNo: json['zongpai_no'] as String,
+      quantity: json['quantity'] as int,
+    );
+  }
+}
+
+/// 装箱保存结果
+class BoxSaveResult {
+  final bool success;
+  final bool isDuplicate;
+  final String? errorMessage;
+  final String? paichanNo;
+  final int? boxNo;
+
+  BoxSaveResult({
+    required this.success,
+    this.isDuplicate = false,
+    this.errorMessage,
+    this.paichanNo,
+    this.boxNo,
+  });
+
+  factory BoxSaveResult.ok(Map<String, dynamic> json) {
+    return BoxSaveResult(
+      success: true,
+      paichanNo: json['paichan_no'] as String?,
+      boxNo: json['box_no'] as int?,
+    );
+  }
+
+  factory BoxSaveResult.duplicate(Map<String, dynamic> json) {
+    return BoxSaveResult(
+      success: false,
+      isDuplicate: true,
+      paichanNo: json['paichan_no'] as String?,
+      boxNo: json['box_no'] as int?,
+    );
+  }
+
+  factory BoxSaveResult.error(String message) {
+    return BoxSaveResult(success: false, errorMessage: message);
+  }
+}
+```
+
+在 `ApiService` 类内新增两个方法：
+
+```dart
+  /// 查询装箱信息 — GET /CargoTrace/box/info
+  Future<BoxInfoResult> fetchBoxInfo({
+    required String baseUrl,
+    required String zongpaiNo,
+  }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/box/info').replace(
+      queryParameters: {'zongpai_no': zongpaiNo},
+    );
+    try {
+      final response = await _client.get(uri, headers: {
+        'Content-Type': 'application/json',
+      }).timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxInfoResult.ok(body);
+        case 400:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final errorCode = body['error_code']?.toString() ?? '';
+          return BoxInfoResult.error(
+            _errorMessage(errorCode),
+            errorCode: errorCode,
+          );
+        case 404:
+          return BoxInfoResult.error('未找到该总排号对应的排产号信息');
+        default:
+          return BoxInfoResult.error('查询失败 (${response.statusCode})');
+      }
+    } catch (e) {
+      return BoxInfoResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  /// 保存装箱记录 — POST /CargoTrace/box
+  Future<BoxSaveResult> saveBoxRecord({
+    required String baseUrl,
+    required String zongpaiNo,
+    required int boxNo,
+    required int quantity,
+  }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/box');
+    try {
+      final response = await _client
+          .post(
+            uri,
+            headers: {'Content-Type': 'application/json'},
+            body: jsonEncode({
+              'zongpai_no': zongpaiNo,
+              'box_no': boxNo,
+              'quantity': quantity,
+            }),
+          )
+          .timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxSaveResult.ok(body);
+        case 400:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final msg = body['message']?.toString() ?? '请求参数错误';
+          return BoxSaveResult.error(msg);
+        case 409:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxSaveResult.duplicate(body);
+        case 404:
+          return BoxSaveResult.error('未找到该总排号对应的排产号信息');
+        default:
+          return BoxSaveResult.error('提交失败 (${response.statusCode})');
+      }
+    } catch (e) {
+      return BoxSaveResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  String _errorMessage(String errorCode) {
+    switch (errorCode) {
+      case 'INVALID_ZONGPAI':
+        return '无效的总排号格式';
+      default:
+        return '请求参数错误';
+    }
+  }
+```
+
+**Step 2: 验证编译**
+
+Run: `flutter analyze lib/services/api_service.dart`
+
+**Step 3: Commit**
+
+```bash
+git add lib/services/api_service.dart
+git commit -m "feat: add box info query and save methods to ApiService"
+```
+
+---
+
+### Task 2: BoxingDetailPage — 装箱详情页
+
+**Files:**
+- Create: `lib/pages/boxing_detail_page.dart`
+
+**Step 1: 实现详情页**
+
+只读页面，展示排产号下的完整装箱明细（PRD §7.3）。
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:pad_scanner/services/api_service.dart';
+
+class BoxingDetailPage extends StatelessWidget {
+  final String paichanNo;
+  final List<BoxDetailData> existingBoxes;
+
+  const BoxingDetailPage({
+    super.key,
+    required this.paichanNo,
+    required this.existingBoxes,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: Row(
+          children: [
+            const Text('装箱详情'),
+            const SizedBox(width: 12),
+            Text(
+              paichanNo,
+              style: const TextStyle(fontSize: 14, fontWeight: FontWeight.normal),
+            ),
+          ],
+        ),
+      ),
+      body: Column(
+        children: [
+          Expanded(
+            child: ListView.builder(
+              padding: const EdgeInsets.all(12),
+              itemCount: existingBoxes.length,
+              itemBuilder: (context, index) {
+                final box = existingBoxes[index];
+                return _buildBoxGroup(context, box);
+              },
+            ),
+          ),
+          // 底部汇总
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
+            color: Theme.of(context).colorScheme.surfaceContainerHighest,
+            child: Text(
+              '共 ${existingBoxes.length} 箱',
+              style: const TextStyle(fontSize: 14),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Widget _buildBoxGroup(BuildContext context, BoxDetailData box) {
+    return Padding(
+      padding: const EdgeInsets.only(bottom: 12),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          Text(
+            '箱号 ${box.boxNo}',
+            style: const TextStyle(fontSize: 14, fontWeight: FontWeight.bold),
+          ),
+          const SizedBox(height: 4),
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.all(8),
+            decoration: BoxDecoration(
+              border: Border.all(color: Colors.grey.shade300),
+              borderRadius: BorderRadius.circular(6),
+            ),
+            child: Column(
+              children: box.items.map((item) {
+                return Padding(
+                  padding: const EdgeInsets.symmetric(vertical: 2),
+                  child: Row(
+                    mainAxisAlignment: MainAxisAlignment.spaceBetween,
+                    children: [
+                      Text(item.zongpaiNo, style: const TextStyle(fontSize: 14)),
+                      Text('数量：${item.quantity}', style: const TextStyle(fontSize: 14)),
+                    ],
+                  ),
+                );
+              }).toList(),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+**Step 2: 验证编译**
+
+Run: `flutter analyze lib/pages/boxing_detail_page.dart`
+
+**Step 3: Commit**
+
+```bash
+git add lib/pages/boxing_detail_page.dart
+git commit -m "feat: add BoxingDetailPage for boxing record details"
+```
+
+---
+
+### Task 3: BoxingPage — 装箱编号主页面
+
+**Files:**
+- Create: `lib/pages/boxing_page.dart`
+
+这是核心页面，实现 PRD §7 中的所有交互逻辑。
+
+**Step 1: 实现装箱模式枚举和页面**
+
+核心状态变量：
+- `BoxingMode _mode` — 当前装箱模式
+- `_BoxingPhase _phase` — 当前阶段（waiting / scanned / submitted）
+- `String? _zongpaiNo` — 当前总排号
+- `String? _paichanNo` — 排产号
+- `int? _erpQuantity` — ERP 中的数量
+- `List<BoxDetailData> _existingBoxes` — 已有箱号明细
+- `int _maxBoxNo` — 最大箱号
+- `TextEditingController _boxNoController` — 箱号输入
+- `TextEditingController _quantityController` — 数量输入
+- `bool _boxNoLocked` — 箱号是否锁定（多码一箱）
+- `int? _lastBoxNo` / `int? _lastQuantity` — 上次提交的值（一码多箱用）
+
+页面结构：
+
+```
+┌──────────────────────────────────┐
+│ 装箱编号            [一码一箱 ○]  │ ← AppBar + 模式切换
+├──────────────────────────────────┤
+│ 提示条区域 (错误/警告)            │ ← 红色/amber/yellow 提示条
+├──────────────────────────────────┤
+│ ✓ 26BW0011              已识别   │ ← 扫码区
+│                                  │
+│ 排产号：    W00009                │ ← 信息区
+│ 已有箱数：3箱  最大箱号：3        │
+│                     [详情 →]     │
+│ ─────────────────────────────── │
+│ 箱号[ 4 ]   数量[ 80 ]  [确认]   │ ← 输入区
+│                                  │
+├──────────────────────────────────┤
+│ [返回]              [继续添加]    │ ← 操作栏（一码多箱/多码一箱）
+├──────────────────────────────────┤
+│ ● 等待扫码                       │ ← 状态栏
+└──────────────────────────────────┘
+```
+
+**扫码处理逻辑（_onScan）：**
+1. 解析码值 → 只接受 `CodeType.zongpaiNo`
+2. 调用 `fetchBoxInfo` 查询后端
+3. 成功后根据模式填充：
+   - 一码一箱：箱号 = suggested_box_no，数量 = erp_quantity
+   - 一码多箱：箱号 = suggested_box_no，数量为空
+   - 多码一箱（首次）：箱号 = suggested_box_no，数量 = erp_quantity，箱号锁定
+   - 多码一箱（后续）：箱号保持锁定，数量 = 新总排号的 erp_quantity
+
+**重复箱号检测（本地）：**
+- 当箱号值变化时，比对 `_existingBoxes` 中是否已存在该箱号
+- 重复时：amber 边框 + 警告条 + 禁用确认按钮
+
+**提交逻辑（_submit）：**
+1. 调用 `saveBoxRecord` 保存
+2. 成功后根据模式处理后续：
+   - 一码一箱：显示成功 1.5s → 重置
+   - 一码多箱：记录 lastBoxNo/lastQuantity → 等待"继续添加"
+   - 多码一箱：保留箱号锁定 → 等待下一个扫码
+
+**Step 2: 验证编译**
+
+Run: `flutter analyze lib/pages/boxing_page.dart`
+
+**Step 3: Commit**
+
+```bash
+git add lib/pages/boxing_page.dart
+git commit -m "feat: add BoxingPage with three boxing modes"
+```
+
+---
+
+### Task 4: HomePage 更新 — 接入装箱模块
+
+**Files:**
+- Modify: `lib/pages/home_page.dart`
+
+**Step 1: 更新装箱模块状态**
+
+将 `boxing` FeatureCard 的 `status` 从 `ModuleStatus.developing` 改为 `ModuleStatus.online`，设置 `version: 'v1.0'`。
+
+**Step 2: 更新导航逻辑**
+
+在 `_navigateToModule` 的 `ModuleType.boxing` case 中：
+- 添加 `import 'package:pad_scanner/pages/boxing_page.dart';`
+- 替换 placeholder 为 `targetPage = const BoxingPage();`
+
+**Step 3: 验证编译**
+
+Run: `flutter analyze`
+
+**Step 4: Commit**
+
+```bash
+git add lib/pages/home_page.dart
+git commit -m "feat: activate boxing module in HomePage"
+```
+
+---
+
+### Task 5: 最终验证
+
+**Step 1: 全量分析**
+
+Run: `flutter analyze`
+
+Expected: No issues found
+
+**Step 2: 运行测试**
+
+Run: `flutter test`
+
+Expected: All tests pass
+
+**Step 3: 检查无遗漏引用**
+
+确认 `BoxingPage` 已正确从 `HomePage` 导航访问。
+
+---
+
+## 文件变更汇总
+
+| 操作 | 文件 | 说明 |
+|------|------|------|
+| Modify | `lib/services/api_service.dart` | 新增装箱 API 方法和数据类 |
+| Create | `lib/pages/boxing_detail_page.dart` | 装箱详情只读页 |
+| Create | `lib/pages/boxing_page.dart` | 装箱编号主页面（三种模式） |
+| Modify | `lib/pages/home_page.dart` | 激活装箱模块导航 |

docs/上架登记模块PRD_v1.0.md

@@ -0,0 +1,310 @@
+# 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. 超出当前版本范围
+
+以下内容在当前版本中不实现：
+
+- 操作日志与操作人员记录（登录功能待定）；
+- 重复上架的强制覆盖功能；
+- 离线缓存与联网同步；
+- 总排号货位变更历史查询。

lib/main.dart

@@ -1,5 +1,5 @@
 import 'package:flutter/material.dart';
-import 'package:pad_scanner/pages/scan_page.dart';
+import 'package:pad_scanner/pages/home_page.dart';
 
 void main() {
   runApp(const PadScannerApp());
@@ -11,12 +11,12 @@ class PadScannerApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
-      title: 'PAD Scanner',
+      title: 'CargoTrace',
       theme: ThemeData(
         colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
         useMaterial3: true,
       ),
-      home: const ScanPage(),
+      home: const HomePage(),
     );
   }
 }

lib/models/scan_record.dart

@@ -1,21 +0,0 @@
-enum SendStatus { pending, success, failed }
-
-class ScanRecord {
-  final String barcode;
-  final String codeType;
-  final DateTime timestamp;
-  SendStatus status;
-
-  ScanRecord({
-    required this.barcode,
-    required this.codeType,
-    required this.timestamp,
-    this.status = SendStatus.pending,
-  });
-
-  Map<String, dynamic> toJson() => {
-        'barcode': barcode,
-        'code_type': codeType,
-        'timestamp': timestamp.toUtc().toIso8601String(),
-      };
-}

lib/pages/boxing_detail_page.dart

@@ -0,0 +1,95 @@
+import 'package:flutter/material.dart';
+import 'package:pad_scanner/services/api_service.dart';
+
+class BoxingDetailPage extends StatelessWidget {
+  final String paichanNo;
+  final List<BoxDetailData> existingBoxes;
+
+  const BoxingDetailPage({
+    super.key,
+    required this.paichanNo,
+    required this.existingBoxes,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: Row(
+          children: [
+            const Text('装箱详情'),
+            const SizedBox(width: 12),
+            Text(
+              paichanNo,
+              style:
+                  const TextStyle(fontSize: 14, fontWeight: FontWeight.normal),
+            ),
+          ],
+        ),
+      ),
+      body: Column(
+        children: [
+          Expanded(
+            child: existingBoxes.isEmpty
+                ? const Center(child: Text('暂无装箱记录'))
+                : ListView.builder(
+                    padding: const EdgeInsets.all(12),
+                    itemCount: existingBoxes.length,
+                    itemBuilder: (context, index) {
+                      return _buildBoxGroup(context, existingBoxes[index]);
+                    },
+                  ),
+          ),
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
+            color: Theme.of(context).colorScheme.surfaceContainerHighest,
+            child: Text(
+              '共 ${existingBoxes.length} 箱',
+              style: const TextStyle(fontSize: 14),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Widget _buildBoxGroup(BuildContext context, BoxDetailData box) {
+    return Padding(
+      padding: const EdgeInsets.only(bottom: 12),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          Text(
+            '箱号 ${box.boxNo}',
+            style: const TextStyle(fontSize: 14, fontWeight: FontWeight.bold),
+          ),
+          const SizedBox(height: 4),
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.all(8),
+            decoration: BoxDecoration(
+              border: Border.all(color: Colors.grey.shade300),
+              borderRadius: BorderRadius.circular(6),
+            ),
+            child: Column(
+              children: box.items.map((item) {
+                return Padding(
+                  padding: const EdgeInsets.symmetric(vertical: 2),
+                  child: Row(
+                    mainAxisAlignment: MainAxisAlignment.spaceBetween,
+                    children: [
+                      Text(item.zongpaiNo, style: const TextStyle(fontSize: 14)),
+                      Text('数量：${item.quantity}',
+                          style: const TextStyle(fontSize: 14)),
+                    ],
+                  ),
+                );
+              }).toList(),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}

lib/pages/boxing_page.dart

@@ -0,0 +1,846 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:pad_scanner/services/app_config_service.dart';
+import 'package:pad_scanner/services/scanner_service.dart';
+import 'package:pad_scanner/services/code_parser.dart';
+import 'package:pad_scanner/services/api_service.dart';
+import 'package:pad_scanner/pages/boxing_detail_page.dart';
+
+// === 装箱模式 ===
+
+enum BoxingMode {
+  one2one, // 一码一箱
+  one2many, // 一码多箱
+  many2one, // 多码一箱
+}
+
+// === 页面阶段 ===
+
+enum _Phase {
+  waiting, // 等待扫码
+  scanned, // 已扫码，显示信息
+  submitted, // 已提交成功
+}
+
+// === 主页面 ===
+
+class BoxingPage extends StatefulWidget {
+  const BoxingPage({super.key});
+
+  @override
+  State<BoxingPage> createState() => _BoxingPageState();
+}
+
+class _BoxingPageState extends State<BoxingPage> {
+  final _scannerService = ScannerService();
+  final _apiService = ApiService();
+
+  // 模式
+  BoxingMode _mode = BoxingMode.one2one;
+
+  // 阶段
+  _Phase _phase = _Phase.waiting;
+
+  // 当前总排号
+  String? _zongpaiNo;
+
+  // 排产号信息（来自后端查询）
+  String? _paichanNo;
+  int? _erpQuantity;
+  List<BoxDetailData> _existingBoxes = [];
+  int _maxBoxNo = 0;
+
+  // 输入
+  final _boxNoController = TextEditingController();
+  final _quantityController = TextEditingController();
+  final _boxNoFocusNode = FocusNode();
+  final _quantityFocusNode = FocusNode();
+
+  // 多码一箱：已扫描过的总排号列表（用于显示）
+  final _scannedZongpais = <String>[];
+
+  // 箱号锁定（多码一箱模式）
+  bool _boxNoLocked = false;
+
+  // 提交中
+  bool _isSubmitting = false;
+
+  // 一码多箱：上次提交的值（用于继续添加预填）
+  int? _lastBoxNo;
+  int? _lastQuantity;
+
+  // 重复箱号
+  bool _isDuplicateBoxNo = false;
+
+  // 反馈
+  String? _feedbackMessage;
+  Color? _feedbackColor;
+
+  @override
+  void initState() {
+    super.initState();
+    _scannerService.scanResults.listen(_onScan);
+  }
+
+  @override
+  void dispose() {
+    _boxNoController.dispose();
+    _quantityController.dispose();
+    _boxNoFocusNode.dispose();
+    _quantityFocusNode.dispose();
+    super.dispose();
+  }
+
+  // === 模式切换 ===
+
+  String get _modeLabel {
+    switch (_mode) {
+      case BoxingMode.one2one:
+        return '一码一箱';
+      case BoxingMode.one2many:
+        return '一码多箱';
+      case BoxingMode.many2one:
+        return '多码一箱';
+    }
+  }
+
+  void _cycleMode() {
+    setState(() {
+      switch (_mode) {
+        case BoxingMode.one2one:
+          _mode = BoxingMode.one2many;
+        case BoxingMode.one2many:
+          _mode = BoxingMode.many2one;
+        case BoxingMode.many2one:
+          _mode = BoxingMode.one2one;
+      }
+      _resetState();
+    });
+  }
+
+  void _resetState() {
+    _phase = _Phase.waiting;
+    _zongpaiNo = null;
+    _paichanNo = null;
+    _erpQuantity = null;
+    _existingBoxes = [];
+    _maxBoxNo = 0;
+    _boxNoController.clear();
+    _quantityController.clear();
+    _scannedZongpais.clear();
+    _boxNoLocked = false;
+    _isSubmitting = false;
+    _lastBoxNo = null;
+    _lastQuantity = null;
+    _isDuplicateBoxNo = false;
+    _feedbackMessage = null;
+    _feedbackColor = null;
+  }
+
+  // === 扫码处理 ===
+
+  void _onScan(ScanResult result) {
+    final parsed = CodeParser.parse(result.barcode);
+
+    if (parsed.type != CodeType.zongpaiNo) {
+      _showFeedback('无效码，请重新扫描', isError: true);
+      return;
+    }
+
+    final zongpai = parsed.value;
+
+    // 多码一箱已提交后：等待下一个扫码
+    if (_mode == BoxingMode.many2one && _phase == _Phase.submitted) {
+      _handleNextScanMany2One(zongpai);
+      return;
+    }
+
+    // 其他模式：等待扫码阶段才处理
+    if (_phase != _Phase.waiting) return;
+
+    _queryBoxInfo(zongpai);
+  }
+
+  void _handleNextScanMany2One(String zongpai) {
+    setState(() {
+      _phase = _Phase.waiting;
+      _zongpaiNo = null;
+      _feedbackMessage = null;
+    });
+    _queryBoxInfo(zongpai);
+  }
+
+  Future<void> _queryBoxInfo(String zongpai) async {
+    final configService = AppConfigService();
+    final baseUrl = await configService.getString('api_url') ?? '';
+    if (baseUrl.isEmpty) {
+      _showFeedback('未配置 API 地址，请前往设置', isError: true);
+      return;
+    }
+
+    final result = await _apiService.fetchBoxInfo(
+      baseUrl: baseUrl,
+      zongpaiNo: zongpai,
+    );
+
+    if (!mounted) return;
+
+    if (!result.success) {
+      _showFeedback(result.errorMessage ?? '查询失败', isError: true);
+      return;
+    }
+
+    setState(() {
+      _zongpaiNo = zongpai;
+      _paichanNo = result.paichanNo;
+      _erpQuantity = result.quantity;
+      _existingBoxes = result.existingBoxes;
+      _maxBoxNo = result.maxBoxNo;
+      _phase = _Phase.scanned;
+      _isDuplicateBoxNo = false;
+      _feedbackMessage = null;
+
+      // 多码一箱：记录已扫描列表
+      if (_mode == BoxingMode.many2one && !_scannedZongpais.contains(zongpai)) {
+        _scannedZongpais.add(zongpai);
+      }
+
+      // 根据模式自动填充
+      _applyAutoFill();
+    });
+  }
+
+  void _applyAutoFill() {
+    switch (_mode) {
+      case BoxingMode.one2one:
+        // 箱号 = max+1, 数量 = ERP 数量
+        _boxNoController.text = (_maxBoxNo + 1).toString();
+        _quantityController.text = (_erpQuantity ?? 0).toString();
+      case BoxingMode.one2many:
+        if (_lastBoxNo != null) {
+          // 继续添加：箱号 = 上次+1, 数量 = 上次值
+          _boxNoController.text = (_lastBoxNo! + 1).toString();
+          _quantityController.text = _lastQuantity?.toString() ?? '';
+        } else {
+          // 首次：箱号 = max+1, 数量不填
+          _boxNoController.text = (_maxBoxNo + 1).toString();
+          _quantityController.clear();
+        }
+      case BoxingMode.many2one:
+        // 箱号 = max+1 (首次) 或锁定, 数量 = ERP 数量
+        if (!_boxNoLocked) {
+          _boxNoController.text = (_maxBoxNo + 1).toString();
+          _boxNoLocked = true;
+        }
+        _quantityController.text = (_erpQuantity ?? 0).toString();
+    }
+    _checkDuplicateBoxNo();
+  }
+
+  // === 重复箱号检测 ===
+
+  void _checkDuplicateBoxNo() {
+    final boxNo = int.tryParse(_boxNoController.text);
+    if (boxNo == null) {
+      setState(() => _isDuplicateBoxNo = false);
+      return;
+    }
+    final exists = _existingBoxes.any((b) => b.boxNo == boxNo);
+    setState(() => _isDuplicateBoxNo = exists);
+  }
+
+  // === 提交 ===
+
+  bool get _canSubmit {
+    if (_isSubmitting || _phase != _Phase.scanned) return false;
+    if (_zongpaiNo == null) return false;
+    final boxNo = int.tryParse(_boxNoController.text);
+    final qty = int.tryParse(_quantityController.text);
+    if (boxNo == null || qty == null || qty <= 0) return false;
+    if (_isDuplicateBoxNo) return false;
+    return true;
+  }
+
+  Future<void> _submit() async {
+    if (!_canSubmit) return;
+
+    final configService = AppConfigService();
+    final baseUrl = await configService.getString('api_url') ?? '';
+    if (baseUrl.isEmpty) {
+      _showFeedback('未配置 API 地址，请前往设置', isError: true);
+      return;
+    }
+
+    final boxNo = int.parse(_boxNoController.text);
+    final quantity = int.parse(_quantityController.text);
+
+    setState(() => _isSubmitting = true);
+
+    final result = await _apiService.saveBoxRecord(
+      baseUrl: baseUrl,
+      zongpaiNo: _zongpaiNo!,
+      boxNo: boxNo,
+      quantity: quantity,
+    );
+
+    if (!mounted) return;
+
+    setState(() => _isSubmitting = false);
+
+    if (result.success) {
+      _onSubmitSuccess(boxNo, quantity);
+    } else if (result.isDuplicate) {
+      _showFeedback(
+        '排产号 ${result.paichanNo ?? ""} 下箱号 ${result.boxNo ?? ""} 已存在',
+        isError: true,
+      );
+    } else {
+      _showFeedback(result.errorMessage ?? '提交失败', isError: true);
+    }
+  }
+
+  void _onSubmitSuccess(int boxNo, int quantity) {
+    setState(() {
+      _lastBoxNo = boxNo;
+      _lastQuantity = quantity;
+      // 刷新已有箱号列表（将新记录加入本地列表）
+      _existingBoxes = List.from(_existingBoxes)
+        ..add(BoxDetailData(
+          boxNo: boxNo,
+          items: [BoxItemData(zongpaiNo: _zongpaiNo!, quantity: quantity)],
+        ));
+      _maxBoxNo = _maxBoxNo > boxNo ? _maxBoxNo : boxNo;
+    });
+
+    switch (_mode) {
+      case BoxingMode.one2one:
+        // 显示成功 1.5s → 重置
+        _showFeedback('装箱成功', isError: false);
+        Future.delayed(const Duration(milliseconds: 1500), () {
+          if (mounted) setState(() => _resetState());
+        });
+
+      case BoxingMode.one2many:
+        // 进入已提交状态，等待"继续添加"或"返回"
+        setState(() {
+          _phase = _Phase.submitted;
+          _zongpaiNo = null;
+        });
+        _showFeedback('装箱成功', isError: false);
+
+      case BoxingMode.many2one:
+        // 进入已提交状态，自动等待下一个扫码
+        setState(() {
+          _phase = _Phase.submitted;
+          _zongpaiNo = null;
+        });
+        _showFeedback('装箱成功，请扫描下一个总排号', isError: false);
+    }
+  }
+
+  // === 操作按钮 ===
+
+  void _onContinueAdding() {
+    // 一码多箱的继续添加
+    setState(() {
+      _phase = _Phase.waiting;
+      _feedbackMessage = null;
+    });
+    // 预填值会在下次扫码后的 _applyAutoFill 中处理
+    // 但这里需要手动触发，因为不重新扫码
+    // 用户需要扫描同一个总排号（或其他总排号）
+  }
+
+  void _onGoBack() {
+    setState(() => _resetState());
+  }
+
+  // === 反馈 ===
+
+  void _showFeedback(String message, {bool isError = false}) {
+    setState(() {
+      _feedbackMessage = message;
+      _feedbackColor = isError ? Colors.red.shade700 : Colors.green.shade700;
+    });
+    Future.delayed(const Duration(seconds: 2), () {
+      if (mounted) setState(() => _feedbackMessage = null);
+    });
+  }
+
+  // === 导航到详情页 ===
+
+  void _openDetail() {
+    Navigator.push(
+      context,
+      MaterialPageRoute(
+        builder: (_) => BoxingDetailPage(
+          paichanNo: _paichanNo ?? '',
+          existingBoxes: _existingBoxes,
+        ),
+      ),
+    );
+  }
+
+  // === 状态文字 ===
+
+  String get _statusText {
+    if (_isSubmitting) return '正在提交…';
+    if (_feedbackMessage != null) return _feedbackMessage!;
+    switch (_phase) {
+      case _Phase.waiting:
+        if (_mode == BoxingMode.many2one && _boxNoLocked) {
+          return '请扫描下一个总排号';
+        }
+        return '等待扫码';
+      case _Phase.scanned:
+        return '请确认信息并提交';
+      case _Phase.submitted:
+        switch (_mode) {
+          case BoxingMode.one2many:
+            return '装箱成功，可继续添加或返回';
+          case BoxingMode.many2one:
+            return '请扫描下一个总排号';
+          case BoxingMode.one2one:
+            return '';
+        }
+    }
+  }
+
+  Color get _statusDotColor {
+    if (_isSubmitting) return Colors.orange;
+    if (_feedbackMessage != null) {
+      return _feedbackColor == Colors.red.shade700 ? Colors.red : Colors.green;
+    }
+    switch (_phase) {
+      case _Phase.waiting:
+        return Colors.blue;
+      case _Phase.scanned:
+        return Colors.green;
+      case _Phase.submitted:
+        return Colors.green;
+    }
+  }
+
+  // === Build ===
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final isWaiting = _phase == _Phase.waiting && _zongpaiNo == null;
+    final showActionButtons =
+        _phase == _Phase.submitted && _mode != BoxingMode.one2one;
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('装箱编号'),
+        actions: [
+          // 模式切换按钮
+          Padding(
+            padding: const EdgeInsets.only(right: 4),
+            child: TextButton.icon(
+              onPressed: _cycleMode,
+              icon: const Icon(Icons.swap_horiz, size: 18),
+              label: Text(
+                _modeLabel,
+                style: const TextStyle(fontSize: 13),
+              ),
+              style: TextButton.styleFrom(
+                foregroundColor: _mode == BoxingMode.many2one
+                    ? Colors.orange
+                    : colorScheme.primary,
+              ),
+            ),
+          ),
+        ],
+      ),
+      body: Column(
+        children: [
+          // 反馈提示条
+          if (_feedbackMessage != null)
+            Container(
+              width: double.infinity,
+              padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+              color: _feedbackColor,
+              child: Text(
+                _feedbackMessage!,
+                style: const TextStyle(color: Colors.white, fontSize: 14),
+                textAlign: TextAlign.center,
+              ),
+            ),
+
+          // 重复箱号警告条
+          if (_isDuplicateBoxNo && _phase == _Phase.scanned)
+            Container(
+              width: double.infinity,
+              padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
+              color: Colors.amber.shade100,
+              child: Text(
+                '箱号 ${_boxNoController.text} 已存在，请重新输入',
+                style: TextStyle(color: Colors.amber.shade900, fontSize: 13),
+              ),
+            ),
+
+          // 主内容区
+          Expanded(
+            child: SingleChildScrollView(
+              padding: const EdgeInsets.all(12),
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  // === 扫码区 ===
+                  _buildScanArea(isWaiting),
+
+                  const SizedBox(height: 12),
+
+                  // === 信息区 ===
+                  _buildInfoArea(isWaiting, colorScheme),
+
+                  const Divider(height: 24),
+
+                  // === 输入区 ===
+                  _buildInputArea(isWaiting),
+                ],
+              ),
+            ),
+          ),
+
+          // 操作按钮（一码多箱 / 多码一箱）
+          if (showActionButtons)
+            Padding(
+              padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 4),
+              child: Row(
+                children: [
+                  Expanded(
+                    child: OutlinedButton(
+                      onPressed: _onGoBack,
+                      style: OutlinedButton.styleFrom(
+                        minimumSize: const Size.fromHeight(40),
+                      ),
+                      child: const Text('返回'),
+                    ),
+                  ),
+                  if (_mode == BoxingMode.one2many) ...[
+                    const SizedBox(width: 12),
+                    Expanded(
+                      child: ElevatedButton(
+                        onPressed: _onContinueAdding,
+                        style: ElevatedButton.styleFrom(
+                          minimumSize: const Size.fromHeight(40),
+                        ),
+                        child: const Text('继续添加'),
+                      ),
+                    ),
+                  ],
+                ],
+              ),
+            ),
+
+          // 底部状态栏
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
+            color: colorScheme.surfaceContainerHighest,
+            child: Row(
+              children: [
+                Container(
+                  width: 8,
+                  height: 8,
+                  decoration: BoxDecoration(
+                    color: _statusDotColor,
+                    shape: BoxShape.circle,
+                  ),
+                ),
+                const SizedBox(width: 8),
+                Expanded(
+                  child: Text(
+                    _statusText,
+                    style: const TextStyle(fontSize: 14),
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  // === 扫码区 Widget ===
+
+  Widget _buildScanArea(bool isWaiting) {
+    if (isWaiting) {
+      // 等待扫码：置灰提示
+      return Container(
+        width: double.infinity,
+        padding: const EdgeInsets.all(16),
+        decoration: BoxDecoration(
+          color: Colors.grey.shade100,
+          borderRadius: BorderRadius.circular(8),
+        ),
+        child: const Row(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            Icon(Icons.qr_code_scanner, color: Colors.grey, size: 20),
+            SizedBox(width: 8),
+            Text(
+              '请扫描执行卡二维码',
+              style: TextStyle(color: Colors.grey, fontSize: 14),
+            ),
+          ],
+        ),
+      );
+    }
+
+    // 已扫码：显示总排号
+    if (_mode == BoxingMode.many2one && _scannedZongpais.isNotEmpty) {
+      // 多码一箱：显示已扫描列表
+      return Wrap(
+        spacing: 6,
+        runSpacing: 4,
+        children: _scannedZongpais.map((zp) {
+          final isCurrent = zp == _zongpaiNo;
+          return Chip(
+            avatar: Icon(
+              Icons.check_circle,
+              size: 16,
+              color: isCurrent ? Colors.green : Colors.grey,
+            ),
+            label: Text(zp, style: const TextStyle(fontSize: 13)),
+            visualDensity: VisualDensity.compact,
+          );
+        }).toList(),
+      );
+    }
+
+    // 单个总排号
+    return Container(
+      width: double.infinity,
+      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 12),
+      decoration: BoxDecoration(
+        border: Border.all(color: Colors.green, width: 2),
+        borderRadius: BorderRadius.circular(8),
+      ),
+      child: Row(
+        children: [
+          const Icon(Icons.check_circle, color: Colors.green, size: 18),
+          const SizedBox(width: 8),
+          Text(
+            _zongpaiNo ?? '',
+            style: const TextStyle(
+              fontSize: 18,
+              fontWeight: FontWeight.bold,
+              color: Colors.black87,
+            ),
+          ),
+          const Spacer(),
+          const Text(
+            '已识别',
+            style: TextStyle(fontSize: 12, color: Colors.green),
+          ),
+        ],
+      ),
+    );
+  }
+
+  // === 信息区 Widget ===
+
+  Widget _buildInfoArea(bool isWaiting, ColorScheme colorScheme) {
+    final grey = isWaiting;
+
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        // 排产号
+        Text(
+          '排产号：',
+          style: TextStyle(
+            fontSize: 13,
+            color: grey ? Colors.grey : Colors.black54,
+          ),
+        ),
+        const SizedBox(height: 2),
+        Text(
+          _paichanNo ?? '--',
+          style: TextStyle(
+            fontSize: 16,
+            fontWeight: FontWeight.w600,
+            color: grey ? Colors.grey : Colors.black87,
+          ),
+        ),
+        const SizedBox(height: 8),
+
+        // 已有箱数 + 最大箱号 + 详情按钮
+        Row(
+          children: [
+            Expanded(
+              child: Row(
+                children: [
+                  Text(
+                    '已有箱数：',
+                    style: TextStyle(
+                      fontSize: 13,
+                      color: grey ? Colors.grey : Colors.black54,
+                    ),
+                  ),
+                  Text(
+                    grey ? '--' : '${_existingBoxes.length}箱',
+                    style: TextStyle(
+                      fontSize: 13,
+                      fontWeight: FontWeight.w600,
+                      color: grey ? Colors.grey : Colors.black87,
+                    ),
+                  ),
+                  const SizedBox(width: 16),
+                  Text(
+                    '最大箱号：',
+                    style: TextStyle(
+                      fontSize: 13,
+                      color: grey ? Colors.grey : Colors.black54,
+                    ),
+                  ),
+                  Text(
+                    grey ? '--' : '$_maxBoxNo',
+                    style: TextStyle(
+                      fontSize: 13,
+                      fontWeight: FontWeight.w600,
+                      color: _maxBoxNo > 0 ? Colors.amber.shade800 : Colors.grey,
+                    ),
+                  ),
+                ],
+              ),
+            ),
+            TextButton(
+              onPressed: grey || _existingBoxes.isEmpty ? null : _openDetail,
+              style: TextButton.styleFrom(
+                padding: const EdgeInsets.symmetric(horizontal: 8),
+                minimumSize: Size.zero,
+                tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+              ),
+              child: Text(
+                '详情 →',
+                style: TextStyle(
+                  fontSize: 13,
+                  color: grey || _existingBoxes.isEmpty
+                      ? Colors.grey.shade400
+                      : colorScheme.primary,
+                ),
+              ),
+            ),
+          ],
+        ),
+      ],
+    );
+  }
+
+  // === 输入区 Widget ===
+
+  Widget _buildInputArea(bool isWaiting) {
+    final enabled = !isWaiting && _phase == _Phase.scanned;
+
+    return Row(
+      crossAxisAlignment: CrossAxisAlignment.end,
+      children: [
+        // 箱号输入
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Text(
+                '箱号',
+                style: TextStyle(
+                  fontSize: 13,
+                  color: enabled ? Colors.black54 : Colors.grey,
+                ),
+              ),
+              const SizedBox(height: 4),
+              SizedBox(
+                height: 40,
+                child: TextField(
+                  controller: _boxNoController,
+                  focusNode: _boxNoFocusNode,
+                  enabled: enabled && !_boxNoLocked,
+                  keyboardType: TextInputType.number,
+                  inputFormatters: [FilteringTextInputFormatter.digitsOnly],
+                  onChanged: (_) => _checkDuplicateBoxNo(),
+                  decoration: InputDecoration(
+                    contentPadding: const EdgeInsets.symmetric(horizontal: 10),
+                    border: const OutlineInputBorder(),
+                    enabledBorder: OutlineInputBorder(
+                      borderSide: BorderSide(
+                        color: _isDuplicateBoxNo
+                            ? Colors.amber
+                            : Colors.grey.shade400,
+                      ),
+                    ),
+                    suffixIcon: _boxNoLocked
+                        ? const Icon(Icons.lock, size: 18, color: Colors.orange)
+                        : null,
+                  ),
+                  style: const TextStyle(fontSize: 16),
+                ),
+              ),
+            ],
+          ),
+        ),
+        const SizedBox(width: 8),
+
+        // 数量输入
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Text(
+                '数量',
+                style: TextStyle(
+                  fontSize: 13,
+                  color: enabled ? Colors.black54 : Colors.grey,
+                ),
+              ),
+              const SizedBox(height: 4),
+              SizedBox(
+                height: 40,
+                child: TextField(
+                  controller: _quantityController,
+                  focusNode: _quantityFocusNode,
+                  enabled: enabled,
+                  keyboardType: TextInputType.number,
+                  inputFormatters: [FilteringTextInputFormatter.digitsOnly],
+                  decoration: const InputDecoration(
+                    contentPadding: EdgeInsets.symmetric(horizontal: 10),
+                    border: OutlineInputBorder(),
+                  ),
+                  style: const TextStyle(fontSize: 16),
+                ),
+              ),
+            ],
+          ),
+        ),
+        const SizedBox(width: 8),
+
+        // 确认按钮
+        SizedBox(
+          height: 40,
+          child: ElevatedButton(
+            onPressed: _canSubmit ? _submit : null,
+            style: ElevatedButton.styleFrom(
+              backgroundColor:
+                  _canSubmit ? Theme.of(context).colorScheme.primary : Colors.grey.shade300,
+              foregroundColor: _canSubmit ? Colors.white : Colors.grey.shade600,
+            ),
+            child: _isSubmitting
+                ? const SizedBox(
+                    width: 18,
+                    height: 18,
+                    child: CircularProgressIndicator(
+                      strokeWidth: 2,
+                      color: Colors.white,
+                    ),
+                  )
+                : const Text('确认', style: TextStyle(fontSize: 15)),
+          ),
+        ),
+      ],
+    );
+  }
+}

lib/pages/home_page.dart

@@ -0,0 +1,341 @@
+import 'package:flutter/material.dart';
+import 'package:pad_scanner/services/app_config_service.dart';
+import 'package:pad_scanner/pages/settings_page.dart';
+import 'package:pad_scanner/pages/registration_page.dart';
+import 'package:pad_scanner/pages/boxing_page.dart';
+import 'package:pad_scanner/services/api_service.dart';
+
+/// Module type enum for each available feature card
+enum ModuleType { registration, boxing, shelfQuery }
+
+/// Module status for PRD state tracking
+enum ModuleStatus { online, developing, planning }
+
+/// Function card data model per PRD §3.3
+class FeatureCard {
+  final ModuleType type;
+  final IconData icon;
+  final String title;
+  final String description;
+  final ModuleStatus status;
+  final String? version;
+  final String route;
+
+  const FeatureCard({
+    required this.type,
+    required this.icon,
+    required this.title,
+    required this.description,
+    required this.status,
+    this.version,
+    required this.route,
+  });
+}
+
+class HomePage extends StatefulWidget {
+  const HomePage({super.key});
+
+  @override
+  State<HomePage> createState() => _HomePageState();
+}
+
+class _HomePageState extends State<HomePage> {
+  final _apiService = ApiService();
+  bool _isCheckingConnection = false;
+  bool _isConnected = false;
+  String _apiAddress = '';
+
+  /// Module registry from PRD §3.4
+  static const _modules = [
+    FeatureCard(
+      type: ModuleType.registration,
+      icon: Icons.local_shipping_outlined,
+      title: '上架登记',
+      description: '扫码绑定总排号与货位',
+      status: ModuleStatus.online,
+      version: 'v1.0',
+      route: '/registration',
+    ),
+    FeatureCard(
+      type: ModuleType.boxing,
+      icon: Icons.view_list_outlined,
+      title: '装箱编号',
+      description: '查询箱号、录入装箱明细',
+      status: ModuleStatus.online,
+      version: 'v1.0',
+      route: '/boxing',
+    ),
+    FeatureCard(
+      type: ModuleType.shelfQuery,
+      icon: Icons.search_outlined,
+      title: '货架查询',
+      description: '按合同查询货架库存',
+      status: ModuleStatus.planning,
+      version: null,
+      route: '',
+    ),
+  ];
+
+  @override
+  void initState() {
+    super.initState();
+    _checkConnection();
+  }
+
+  Future<void> _checkConnection() async {
+    final configService = AppConfigService();
+    final url = await configService.getString('api_url') ?? '';
+    if (url.isEmpty) {
+      setState(() {
+        _isConnected = false;
+        _apiAddress = '';
+        _isCheckingConnection = false;
+      });
+      return;
+    }
+
+    setState(() => _isCheckingConnection = true);
+    final ok = await _apiService.testConnection(url);
+    if (!mounted) return;
+    setState(() {
+      _isConnected = ok;
+      _apiAddress = url;
+      _isCheckingConnection = false;
+    });
+  }
+
+  void _onCardTap(FeatureCard card) {
+    switch (card.status) {
+      case ModuleStatus.online:
+        _navigateToModule(card.type);
+      case ModuleStatus.developing:
+        _showToast('该功能正在开发中');
+      case ModuleStatus.planning:
+        _showToast('该功能规划中');
+    }
+  }
+
+  void _showToast(String message) {
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(content: Text(message), duration: const Duration(seconds: 2)),
+    );
+  }
+
+  void _navigateToModule(ModuleType type) {
+    late Widget targetPage;
+    switch (type) {
+      case ModuleType.registration:
+        targetPage = const RegistrationPage();
+        break;
+      case ModuleType.boxing:
+        targetPage = const BoxingPage();
+        break;
+      case ModuleType.shelfQuery:
+        return; // 规划中，不导航
+    }
+    Navigator.push(
+      context,
+      MaterialPageRoute(builder: (_) => targetPage),
+    ).then((_) => _checkConnection());
+  }
+
+  void _navigateToSettings() {
+    Navigator.push(
+      context,
+      MaterialPageRoute(builder: (_) => const SettingsPage()),
+    ).then((_) => _checkConnection());
+  }
+
+  Color _getConnectionStatusColor() {
+    if (_isCheckingConnection) return Colors.orange;
+    return _isConnected ? Colors.green : Colors.red;
+  }
+
+  String _getConnectionStatusText() {
+    if (_isCheckingConnection) return '● 正在检测连接...';
+    if (!_isConnected || _apiAddress.isEmpty) return '● 未连接，请检查设置';
+    return '● 已连接 $_apiAddress';
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('CargoTrace'),
+        actions: [
+          Padding(
+            padding: const EdgeInsets.only(right: 8),
+            child: IconButton(
+              icon: const Icon(Icons.settings),
+              onPressed: _navigateToSettings,
+            ),
+          ),
+        ],
+      ),
+      body: Column(
+        children: [
+          // Function cards area
+          Expanded(
+            child: ListView.builder(
+              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
+              itemCount: _modules.length,
+              itemBuilder: (context, index) {
+                final card = _modules[index];
+                return _buildFeatureCard(context, card);
+              },
+            ),
+          ),
+
+          // Bottom connection status bar
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+            color: colorScheme.surfaceContainerHighest,
+            child: Row(
+              children: [
+                Container(
+                  width: 8,
+                  height: 8,
+                  decoration: BoxDecoration(
+                    color: _getConnectionStatusColor(),
+                    shape: BoxShape.circle,
+                  ),
+                ),
+                const SizedBox(width: 8),
+                Expanded(
+                  child: Text(
+                    _getConnectionStatusText(),
+                    style: const TextStyle(fontSize: 13),
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Widget _buildFeatureCard(BuildContext context, FeatureCard card) {
+    final Color statusBgColor;
+    final TextStyle statusTextStyle;
+    final String statusText;
+
+    switch (card.status) {
+      case ModuleStatus.online:
+        statusBgColor = Colors.green.shade700;
+        statusTextStyle = const TextStyle(color: Colors.white, fontSize: 12);
+        statusText = card.version ?? '已上线';
+        break;
+      case ModuleStatus.developing:
+        statusBgColor = Colors.blue.shade700;
+        statusTextStyle = const TextStyle(color: Colors.white, fontSize: 12);
+        statusText = '开发中';
+        break;
+      case ModuleStatus.planning:
+        statusBgColor = Colors.grey.shade500;
+        statusTextStyle = const TextStyle(color: Colors.white, fontSize: 12);
+        statusText = '规划中';
+        break;
+    }
+
+    final canNavigate = card.status == ModuleStatus.online;
+
+    return Padding(
+      padding: const EdgeInsets.only(bottom: 16),
+      child: InkWell(
+        onTap: () => _onCardTap(card),
+        borderRadius: BorderRadius.circular(8),
+        child: Container(
+          padding: const EdgeInsets.all(16),
+          decoration: BoxDecoration(
+            color: canNavigate ? Colors.white : Colors.grey.shade200,
+            borderRadius: BorderRadius.circular(8),
+            boxShadow: [
+              BoxShadow(
+                color: Colors.black.withValues(alpha: 0.05),
+                blurRadius: 4,
+                offset: const Offset(0, 2),
+              ),
+            ],
+          ),
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              // First row: icon + module name
+              Row(
+                children: [
+                  Icon(
+                    card.icon,
+                    size: 22,
+                    color: canNavigate ? Colors.blue : Colors.grey,
+                  ),
+                  const SizedBox(width: 8),
+                  Text(
+                    card.title,
+                    style: TextStyle(
+                      fontSize: 16,
+                      fontWeight: FontWeight.bold,
+                      color: canNavigate ? Colors.black87 : Colors.grey,
+                    ),
+                  ),
+                ],
+              ),
+              const SizedBox(height: 6),
+              // Second row: description
+              Text(
+                card.description,
+                style: TextStyle(fontSize: 13, color: Colors.grey.shade600),
+              ),
+              const SizedBox(height: 10),
+              // Third row: status badge (right aligned)
+              Align(
+                alignment: Alignment.centerRight,
+                child: Container(
+                  padding: const EdgeInsets.symmetric(
+                    horizontal: 8,
+                    vertical: 3,
+                  ),
+                  decoration: BoxDecoration(
+                    color: statusBgColor,
+                    borderRadius: BorderRadius.circular(4),
+                  ),
+                  child: Row(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Text(statusText, style: statusTextStyle),
+                      if (card.status == ModuleStatus.online) ...[
+                        const SizedBox(width: 6),
+                        Container(
+                          width: 6,
+                          height: 6,
+                          decoration: const BoxDecoration(
+                            color: Colors.white,
+                            shape: BoxShape.circle,
+                          ),
+                        ),
+                      ] else ...[
+                        const SizedBox(width: 6),
+                        Container(
+                          width: 6,
+                          height: 6,
+                          decoration: BoxDecoration(
+                            color: Colors.white.withValues(alpha: 0.5),
+                            shape: BoxShape.circle,
+                          ),
+                        ),
+                      ],
+                    ],
+                  ),
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

lib/pages/registration_page.dart

@@ -0,0 +1,644 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:vibration/vibration.dart';
+import 'package:pad_scanner/services/app_config_service.dart';
+import 'package:pad_scanner/services/scanner_service.dart';
+import 'package:pad_scanner/services/code_parser.dart';
+import 'package:pad_scanner/services/api_service.dart';
+import 'package:pad_scanner/services/sound_service.dart';
+
+class RegistrationPage extends StatefulWidget {
+  const RegistrationPage({super.key});
+
+  @override
+  State<RegistrationPage> createState() => _RegistrationPageState();
+}
+
+class _RegistrationPageState extends State<RegistrationPage> {
+  final _scannerService = ScannerService();
+  final _apiService = ApiService();
+  final _soundService = SoundService();
+  final _focusNode = FocusNode();
+
+  final _zongpaiNos = <String>[];
+  String? _locationCode;
+  CodeType? _locationType;
+  bool _isLocked = false;
+  bool _isSubmitting = false;
+
+  String? _successMessage;
+  String? _snackbarMessage;
+  Color? _snackbarColor;
+
+  @override
+  void initState() {
+    super.initState();
+    _scannerService.scanResults.listen(_onScan);
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      _focusNode.requestFocus();
+    });
+  }
+
+  @override
+  void dispose() {
+    _focusNode.dispose();
+    _soundService.dispose();
+    super.dispose();
+  }
+
+  void _onKeyEvent(KeyEvent event) {
+    if (event is KeyDownEvent &&
+        event.logicalKey == LogicalKeyboardKey.enter) {
+      _submit();
+    }
+  }
+
+  void _onScan(ScanResult result) {
+    final parsed = CodeParser.parse(result.barcode);
+    switch (parsed.type) {
+      case CodeType.zongpaiNo:
+        setState(() {
+          if (_isLocked) {
+            // 锁定模式：追加到列表（重复则覆盖）
+            final idx = _zongpaiNos.indexOf(parsed.value);
+            if (idx >= 0) {
+              _zongpaiNos[idx] = parsed.value;
+            } else {
+              _zongpaiNos.add(parsed.value);
+            }
+          } else {
+            // 单次模式：只有一条，覆盖
+            if (_zongpaiNos.isNotEmpty) {
+              _zongpaiNos[0] = parsed.value;
+            } else {
+              _zongpaiNos.add(parsed.value);
+            }
+          }
+          _snackbarMessage = null;
+          _successMessage = null;
+        });
+      case CodeType.locationNormal:
+      case CodeType.locationTransit:
+        if (!_isLocked) {
+          setState(() {
+            _locationCode = parsed.value;
+            _locationType = parsed.type;
+            _snackbarMessage = null;
+            _successMessage = null;
+          });
+        }
+      case CodeType.invalid:
+        _showFeedback('无效码：${result.barcode}', isError: true);
+    }
+  }
+
+  void _removeZongpai(int index) {
+    setState(() {
+      _zongpaiNos.removeAt(index);
+    });
+  }
+
+  void _showFeedback(String message, {bool isError = false}) {
+    setState(() {
+      _snackbarMessage = message;
+      _snackbarColor = isError ? Colors.red.shade700 : Colors.green.shade700;
+    });
+    Future.delayed(const Duration(seconds: 2), () {
+      if (mounted) setState(() => _snackbarMessage = null);
+    });
+  }
+
+  String get _statusText {
+    if (_isSubmitting) return '正在提交…';
+    if (_successMessage != null) return _successMessage!;
+    if (_isLocked && _locationCode != null && _zongpaiNos.isEmpty) {
+      return '货位已锁定，请扫描下一张执行卡';
+    }
+    final hasZ = _zongpaiNos.isNotEmpty;
+    final hasL = _locationCode != null;
+    if (hasZ && hasL) return '请确认信息并提交';
+    if (hasZ && !hasL) return '请扫描目标货位号';
+    if (!hasZ && hasL) return '请扫描执行卡';
+    return '等待扫描总排号或货位号…';
+  }
+
+  bool get _canSubmit =>
+      _zongpaiNos.isNotEmpty && _locationCode != null && !_isSubmitting;
+
+  Future<void> _submit() async {
+    if (!_canSubmit) return;
+
+    final configService = AppConfigService();
+    final baseUrl = await configService.getString('api_url') ?? '';
+    if (baseUrl.isEmpty) {
+      _showFeedback('未配置 API 地址，请前往设置', isError: true);
+      return;
+    }
+
+    setState(() => _isSubmitting = true);
+
+    if (_isLocked && _zongpaiNos.length > 1) {
+      // 批量提交：逐个提交列表中的总排号
+      await _submitBatch(baseUrl);
+    } else {
+      // 单条提交
+      await _submitOne(baseUrl, _zongpaiNos.first);
+    }
+  }
+
+  Future<void> _submitOne(String baseUrl, String zongpaiNo) async {
+    final result = await _apiService.registerLocation(
+      baseUrl: baseUrl,
+      zongpaiNo: zongpaiNo,
+      locationCode: _locationCode!,
+    );
+
+    if (!mounted) return;
+
+    setState(() => _isSubmitting = false);
+
+    if (result.success) {
+      _vibrateSuccess();
+      setState(() {
+        _zongpaiNos.remove(zongpaiNo);
+        if (!_isLocked) {
+          _locationCode = null;
+          _locationType = null;
+        }
+        _successMessage = _isLocked ? '货位已锁定，请扫描下一张执行卡' : '上架成功';
+      });
+      _showFeedback('上架成功', isError: false);
+      Future.delayed(const Duration(milliseconds: 1500), () {
+        if (mounted) setState(() => _successMessage = null);
+      });
+    } else if (result.isDuplicate) {
+      _vibrateError();
+      _showDuplicateDialog(zongpaiNo, result.duplicateInfo);
+    } else {
+      _vibrateError();
+      _showFeedback(result.errorMessage ?? '提交失败', isError: true);
+    }
+  }
+
+  Future<void> _submitBatch(String baseUrl) async {
+    int successCount = 0;
+    final failed = <String>[];
+    final toRemove = <String>[];
+
+    for (final zp in List.of(_zongpaiNos)) {
+      final result = await _apiService.registerLocation(
+        baseUrl: baseUrl,
+        zongpaiNo: zp,
+        locationCode: _locationCode!,
+      );
+      if (result.success) {
+        successCount++;
+        toRemove.add(zp);
+      } else {
+        failed.add(zp);
+        if (result.isDuplicate) {
+          // 重复上架弹窗中断批量流程
+          setState(() {
+            _zongpaiNos.removeWhere((e) => toRemove.contains(e));
+            _isSubmitting = false;
+          });
+          _showDuplicateDialog(zp, result.duplicateInfo);
+          return;
+        }
+      }
+    }
+
+    if (!mounted) return;
+
+    setState(() {
+      _zongpaiNos.removeWhere((e) => toRemove.contains(e));
+      _isSubmitting = false;
+    });
+
+    if (failed.isEmpty) {
+      _vibrateSuccess();
+      _showFeedback('批量上架成功（$successCount 条）', isError: false);
+    } else {
+      _vibrateError();
+      _showFeedback('成功 $successCount 条，失败 ${failed.length} 条', isError: true);
+    }
+  }
+
+  void _vibrateSuccess() {
+    Vibration.vibrate(duration: 200);
+    _soundService.playSuccess();
+  }
+
+  void _vibrateError() {
+    Vibration.vibrate(duration: 1000);
+    _soundService.playFailure();
+  }
+
+  void _showDuplicateDialog(String zongpaiNo, Map<String, dynamic>? info) {
+    showDialog(
+      context: context,
+      barrierDismissible: false,
+      builder: (ctx) => AlertDialog(
+        backgroundColor: Colors.red.shade50,
+        title: const Row(
+          children: [
+            Icon(Icons.warning, color: Colors.red),
+            SizedBox(width: 8),
+            Text('重复上架', style: TextStyle(color: Colors.red)),
+          ],
+        ),
+        content: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text('总排号：$zongpaiNo'),
+            const SizedBox(height: 4),
+            Text('已登记货位：${info?["location_code"] ?? "未知"}'),
+            const SizedBox(height: 4),
+            Text('登记时间：${info?["registered_at"] ?? "未知"}'),
+            const SizedBox(height: 12),
+            const Text(
+              '请核查实物，确认是否操作错误。',
+              style: TextStyle(fontWeight: FontWeight.bold),
+            ),
+          ],
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(ctx),
+            child: const Text('关闭'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  void _toggleLock(bool value) {
+    if (value && _locationCode == null) {
+      _showFeedback('请先扫描货位号', isError: true);
+      return;
+    }
+    setState(() {
+      _isLocked = value;
+      if (!value) {
+        // 退出锁定模式，只保留最后一条总排号
+        if (_zongpaiNos.length > 1) {
+          _zongpaiNos.removeRange(0, _zongpaiNos.length - 1);
+        }
+      }
+    });
+  }
+
+  String _locationLabel(CodeType? type) {
+    if (type == CodeType.locationTransit) return '转运区域';
+    return '普通货架';
+  }
+
+  Color _locationLabelColor(CodeType? type) {
+    if (type == CodeType.locationTransit) return Colors.orange;
+    return Colors.blue;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return KeyboardListener(
+      focusNode: _focusNode,
+      onKeyEvent: _onKeyEvent,
+      child: Scaffold(
+        appBar: AppBar(
+        title: const Text('上架登记'),
+        actions: [
+          Padding(
+            padding: const EdgeInsets.only(right: 4),
+            child: Row(
+              children: [
+                const Text('锁定货位', style: TextStyle(fontSize: 13)),
+                Switch(value: _isLocked, onChanged: _toggleLock),
+              ],
+            ),
+          ),
+        ],
+      ),
+      body: Column(
+        children: [
+          // Feedback banner
+          if (_snackbarMessage != null)
+            Container(
+              width: double.infinity,
+              padding: const EdgeInsets.symmetric(vertical: 10, horizontal: 16),
+              color: _snackbarColor,
+              child: Text(
+                _snackbarMessage!,
+                style: const TextStyle(color: Colors.white, fontSize: 14),
+                textAlign: TextAlign.center,
+              ),
+            ),
+
+          // Main form area
+          Expanded(
+            child: Padding(
+              padding: const EdgeInsets.all(16),
+              child: Column(
+                children: [
+                  // ---- 目标货位 (上方) ----
+                  Row(
+                    children: [
+                      const Text(
+                        '目标货位',
+                        style: TextStyle(
+                          fontSize: 14,
+                          fontWeight: FontWeight.w500,
+                        ),
+                      ),
+                      if (_locationCode != null) ...[
+                        const SizedBox(width: 8),
+                        Container(
+                          padding: const EdgeInsets.symmetric(
+                            horizontal: 6,
+                            vertical: 2,
+                          ),
+                          decoration: BoxDecoration(
+                            color: _locationLabelColor(
+                              _locationType,
+                            ).withValues(alpha: 0.15),
+                            borderRadius: BorderRadius.circular(4),
+                          ),
+                          child: Text(
+                            _locationLabel(_locationType),
+                            style: TextStyle(
+                              fontSize: 11,
+                              color: _locationLabelColor(_locationType),
+                              fontWeight: FontWeight.bold,
+                            ),
+                          ),
+                        ),
+                      ],
+                    ],
+                  ),
+                  const SizedBox(height: 6),
+                  Container(
+                    width: double.infinity,
+                    padding: const EdgeInsets.symmetric(
+                      horizontal: 12,
+                      vertical: 14,
+                    ),
+                    decoration: BoxDecoration(
+                      border: Border.all(
+                        color: _locationCode != null
+                            ? Colors.green
+                            : Colors.grey.shade400,
+                        width: _locationCode != null ? 2 : 1,
+                      ),
+                      borderRadius: BorderRadius.circular(8),
+                    ),
+                    child: Row(
+                      children: [
+                        Expanded(
+                          child: Text(
+                            _locationCode ?? '',
+                            style: TextStyle(
+                              fontSize: 20,
+                              fontWeight: FontWeight.bold,
+                              color: _locationCode != null
+                                  ? Colors.black87
+                                  : Colors.grey,
+                            ),
+                          ),
+                        ),
+                        if (_isLocked)
+                          const Icon(
+                            Icons.lock,
+                            color: Colors.orange,
+                            size: 20,
+                          ),
+                      ],
+                    ),
+                  ),
+
+                  const SizedBox(height: 16),
+
+                  // ---- 总排号 (下方) ----
+                  Row(
+                    children: [
+                      const Text(
+                        '总排号',
+                        style: TextStyle(
+                          fontSize: 14,
+                          fontWeight: FontWeight.w500,
+                        ),
+                      ),
+                      if (_isLocked && _zongpaiNos.isNotEmpty) ...[
+                        const SizedBox(width: 8),
+                        Container(
+                          padding: const EdgeInsets.symmetric(
+                            horizontal: 6,
+                            vertical: 2,
+                          ),
+                          decoration: BoxDecoration(
+                            color: Colors.blue.withValues(alpha: 0.15),
+                            borderRadius: BorderRadius.circular(4),
+                          ),
+                          child: Text(
+                            '${_zongpaiNos.length} 条',
+                            style: const TextStyle(
+                              fontSize: 11,
+                              color: Colors.blue,
+                              fontWeight: FontWeight.bold,
+                            ),
+                          ),
+                        ),
+                      ],
+                    ],
+                  ),
+                  const SizedBox(height: 6),
+
+                  if (_isLocked) ...[
+                    // 锁定模式：列表显示多条总排号
+                    Expanded(
+                      child: _zongpaiNos.isEmpty
+                          ? Container(
+                              width: double.infinity,
+                              padding: const EdgeInsets.all(14),
+                              decoration: BoxDecoration(
+                                border: Border.all(color: Colors.grey.shade400),
+                                borderRadius: BorderRadius.circular(8),
+                              ),
+                              child: const Text(
+                                '',
+                                style: TextStyle(
+                                  fontSize: 20,
+                                  color: Colors.grey,
+                                ),
+                              ),
+                            )
+                          : ListView.separated(
+                              itemCount: _zongpaiNos.length,
+                              separatorBuilder: (_, __) =>
+                                  const SizedBox(height: 6),
+                              itemBuilder: (context, index) {
+                                return Dismissible(
+                                  key: ValueKey('${_zongpaiNos[index]}-$index'),
+                                  direction: DismissDirection.endToStart,
+                                  onDismissed: (_) => _removeZongpai(index),
+                                  background: Container(
+                                    alignment: Alignment.centerRight,
+                                    padding: const EdgeInsets.only(right: 16),
+                                    decoration: BoxDecoration(
+                                      color: Colors.red.shade100,
+                                      borderRadius: BorderRadius.circular(8),
+                                    ),
+                                    child: const Icon(
+                                      Icons.delete,
+                                      color: Colors.red,
+                                    ),
+                                  ),
+                                  child: Container(
+                                    padding: const EdgeInsets.symmetric(
+                                      horizontal: 12,
+                                      vertical: 12,
+                                    ),
+                                    decoration: BoxDecoration(
+                                      border: Border.all(
+                                        color: Colors.green,
+                                        width: 2,
+                                      ),
+                                      borderRadius: BorderRadius.circular(8),
+                                    ),
+                                    child: Row(
+                                      children: [
+                                        Expanded(
+                                          child: Text(
+                                            _zongpaiNos[index],
+                                            style: const TextStyle(
+                                              fontSize: 20,
+                                              fontWeight: FontWeight.bold,
+                                              color: Colors.black87,
+                                            ),
+                                          ),
+                                        ),
+                                        IconButton(
+                                          icon: const Icon(
+                                            Icons.close,
+                                            size: 20,
+                                          ),
+                                          onPressed: () =>
+                                              _removeZongpai(index),
+                                          padding: EdgeInsets.zero,
+                                          constraints: const BoxConstraints(),
+                                        ),
+                                      ],
+                                    ),
+                                  ),
+                                );
+                              },
+                            ),
+                    ),
+                  ] else ...[
+                    // 单次模式：单个显示
+                    Container(
+                      width: double.infinity,
+                      padding: const EdgeInsets.symmetric(
+                        horizontal: 12,
+                        vertical: 14,
+                      ),
+                      decoration: BoxDecoration(
+                        border: Border.all(
+                          color: _zongpaiNos.isNotEmpty
+                              ? Colors.green
+                              : Colors.grey.shade400,
+                          width: _zongpaiNos.isNotEmpty ? 2 : 1,
+                        ),
+                        borderRadius: BorderRadius.circular(8),
+                      ),
+                      child: Text(
+                        _zongpaiNos.isNotEmpty ? _zongpaiNos.first : '',
+                        style: TextStyle(
+                          fontSize: 20,
+                          fontWeight: FontWeight.bold,
+                          color: _zongpaiNos.isNotEmpty
+                              ? Colors.black87
+                              : Colors.grey,
+                        ),
+                      ),
+                    ),
+                  ],
+
+                  const SizedBox(height: 16),
+
+                  // Submit button
+                  SizedBox(
+                    width: double.infinity,
+                    height: 48,
+                    child: ElevatedButton(
+                      onPressed: _canSubmit ? _submit : null,
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor: _canSubmit
+                            ? colorScheme.primary
+                            : Colors.grey.shade300,
+                        foregroundColor: _canSubmit
+                            ? Colors.white
+                            : Colors.grey.shade600,
+                        shape: RoundedRectangleBorder(
+                          borderRadius: BorderRadius.circular(8),
+                        ),
+                      ),
+                      child: _isSubmitting
+                          ? const SizedBox(
+                              width: 22,
+                              height: 22,
+                              child: CircularProgressIndicator(
+                                strokeWidth: 2,
+                                color: Colors.white,
+                              ),
+                            )
+                          : Text(
+                              _isLocked && _zongpaiNos.length > 1
+                                  ? '批量上架（${_zongpaiNos.length} 条）'
+                                  : '确认上架(P1)',
+                              style: const TextStyle(fontSize: 18),
+                            ),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ),
+
+          // Status bar at bottom
+          Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(vertical: 12, horizontal: 16),
+            color: colorScheme.surfaceContainerHighest,
+            child: Row(
+              children: [
+                Container(
+                  width: 8,
+                  height: 8,
+                  decoration: BoxDecoration(
+                    color: _isSubmitting
+                        ? Colors.orange
+                        : _successMessage != null
+                        ? Colors.green
+                        : Colors.blue,
+                    shape: BoxShape.circle,
+                  ),
+                ),
+                const SizedBox(width: 8),
+                Expanded(
+                  child: Text(
+                    _statusText,
+                    style: const TextStyle(fontSize: 14),
+                    overflow: TextOverflow.ellipsis,
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    ),
+    );
+  }
+}

lib/pages/scan_page.dart

@@ -1,127 +0,0 @@
-import 'package:flutter/material.dart';
-import 'package:shared_preferences/shared_preferences.dart';
-import 'package:pad_scanner/models/scan_record.dart';
-import 'package:pad_scanner/services/scanner_service.dart';
-import 'package:pad_scanner/services/api_service.dart';
-import 'package:pad_scanner/pages/settings_page.dart';
-
-class ScanPage extends StatefulWidget {
-  const ScanPage({super.key});
-
-  @override
-  State<ScanPage> createState() => _ScanPageState();
-}
-
-class _ScanPageState extends State<ScanPage> {
-  final _scannerService = ScannerService();
-  final _apiService = ApiService();
-  final _records = <ScanRecord>[];
-  String _status = 'Waiting for scan...';
-
-  @override
-  void initState() {
-    super.initState();
-    _startListening();
-  }
-
-  void _startListening() {
-    _scannerService.scanResults.listen((result) async {
-      final record = ScanRecord(
-        barcode: result.barcode,
-        codeType: result.codeType,
-        timestamp: DateTime.now(),
-      );
-
-      setState(() {
-        _records.insert(0, record);
-        _status = 'Sending...';
-      });
-
-      final prefs = await SharedPreferences.getInstance();
-      final url = prefs.getString('api_url') ?? '';
-
-      if (url.isEmpty) {
-        setState(() {
-          record.status = SendStatus.failed;
-          _status = 'No URL configured. Go to Settings.';
-        });
-        return;
-      }
-
-      final ok = await _apiService.sendScanData(
-        url,
-        barcode: record.barcode,
-        codeType: record.codeType,
-      );
-
-      if (mounted) {
-        setState(() {
-          record.status = ok ? SendStatus.success : SendStatus.failed;
-          _status = ok ? 'Sent successfully' : 'Send failed';
-        });
-      }
-    });
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      appBar: AppBar(
-        title: const Text('PAD Scanner'),
-        actions: [
-          IconButton(
-            icon: const Icon(Icons.settings),
-            onPressed: () => Navigator.push(
-              context,
-              MaterialPageRoute(builder: (_) => const SettingsPage()),
-            ),
-          ),
-        ],
-      ),
-      body: Column(
-        children: [
-          Container(
-            width: double.infinity,
-            padding: const EdgeInsets.all(16),
-            color: Theme.of(context).colorScheme.surfaceContainerHighest,
-            child: Text(
-              _status,
-              style: Theme.of(context).textTheme.titleMedium,
-              textAlign: TextAlign.center,
-            ),
-          ),
-          Expanded(
-            child: _records.isEmpty
-                ? const Center(
-                    child: Text(
-                        'No scans yet.\nPress the scan button on the device.',
-                        textAlign: TextAlign.center))
-                : ListView.builder(
-                    itemCount: _records.length,
-                    itemBuilder: (context, index) {
-                      final r = _records[index];
-                      return ListTile(
-                        title: Text(r.barcode),
-                        subtitle: Text(
-                            '${r.codeType}  ${r.timestamp.toLocal().toIso8601String().substring(0, 19)}'),
-                        trailing: Icon(
-                          r.status == SendStatus.success
-                              ? Icons.check_circle
-                              : r.status == SendStatus.failed
-                                  ? Icons.error
-                                  : Icons.hourglass_empty,
-                          color: r.status == SendStatus.success
-                              ? Colors.green
-                              : r.status == SendStatus.failed
-                                  ? Colors.red
-                                  : Colors.orange,
-                        ),
-                      );
-                    },
-                  ),
-          ),
-        ],
-      ),
-    );
-  }
-}

lib/pages/settings_page.dart

@@ -1,6 +1,8 @@
 import 'package:flutter/material.dart';
-import 'package:shared_preferences/shared_preferences.dart';
+import 'package:pad_scanner/services/app_config_service.dart';
+import 'package:file_picker/file_picker.dart';
 import 'package:pad_scanner/services/api_service.dart';
+import 'package:pad_scanner/services/sound_service.dart';
 
 class SettingsPage extends StatefulWidget {
   const SettingsPage({super.key});
@@ -12,93 +14,266 @@ class SettingsPage extends StatefulWidget {
 class _SettingsPageState extends State<SettingsPage> {
   final _controller = TextEditingController();
   final _apiService = ApiService();
+  final _soundService = SoundService();
   bool _saving = false;
+  bool _testing = false;
+
+  String? _successPath;
+  String? _failurePath;
 
   @override
   void initState() {
     super.initState();
     _loadUrl();
+    _loadSoundPaths();
   }
 
   Future<void> _loadUrl() async {
-    final prefs = await SharedPreferences.getInstance();
-    _controller.text = prefs.getString('api_url') ?? '';
+    final configService = AppConfigService();
+    final url = await configService.getString('api_url') ?? '';
+    _controller.text = url;
+  }
+
+  Future<void> _loadSoundPaths() async {
+    final s = await _soundService.getSuccessPath();
+    final f = await _soundService.getFailurePath();
+    if (mounted) {
+      setState(() {
+        _successPath = s;
+        _failurePath = f;
+      });
+    }
   }
 
   Future<void> _saveUrl() async {
+    final url = _controller.text.trim();
+    if (url.isEmpty) {
+      _showSnackBar('请输入 API 地址', isError: true);
+      return;
+    }
     setState(() => _saving = true);
-    final prefs = await SharedPreferences.getInstance();
-    await prefs.setString('api_url', _controller.text.trim());
+    final configService = AppConfigService();
+    await configService.setString('api_url', url);
     setState(() => _saving = false);
     if (mounted) {
-      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(content: Text('URL saved')),
-      );
+      _showSnackBar('设置已保存');
     }
   }
 
   Future<void> _testConnection() async {
     final url = _controller.text.trim();
     if (url.isEmpty) {
-      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(content: Text('Please enter a URL first')),
-      );
+      _showSnackBar('请先输入 API 地址', isError: true);
       return;
     }
-    final ok = await _apiService.sendScanData(
-      url,
-      barcode: 'TEST_BARCODE',
-      codeType: 'TEST',
-    );
+    setState(() => _testing = true);
+    final ok = await _apiService.testConnection(url);
+    setState(() => _testing = false);
     if (mounted) {
-      ScaffoldMessenger.of(context).showSnackBar(
-        SnackBar(content: Text(ok ? 'Connection OK' : 'Connection failed')),
-      );
+      _showSnackBar(ok ? '连接成功' : '连接失败，请检查地址和网络', isError: !ok);
     }
   }
 
+  Future<void> _pickSound(bool isSuccess) async {
+    final result = await FilePicker.pickFiles(
+      type: FileType.audio,
+    );
+    if (result != null && result.files.single.path != null) {
+      final path = result.files.single.path!;
+      if (isSuccess) {
+        await _soundService.setSuccessPath(path);
+      } else {
+        await _soundService.setFailurePath(path);
+      }
+      setState(() {
+        if (isSuccess) {
+          _successPath = path;
+        } else {
+          _failurePath = path;
+        }
+      });
+    }
+  }
+
+  Future<void> _clearSound(bool isSuccess) async {
+    if (isSuccess) {
+      await _soundService.setSuccessPath(null);
+    } else {
+      await _soundService.setFailurePath(null);
+    }
+    setState(() {
+      if (isSuccess) {
+        _successPath = null;
+      } else {
+        _failurePath = null;
+      }
+    });
+  }
+
+  Future<void> _previewSound(String path) async {
+    await _soundService.play(path);
+  }
+
+  String _fileName(String? path) {
+    if (path == null) return '未设置';
+    return path.split('/').last;
+  }
+
+  void _showSnackBar(String message, {bool isError = false}) {
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(
+        content: Text(message),
+        backgroundColor:
+            isError ? Colors.red.shade700 : Colors.green.shade700,
+        duration: const Duration(seconds: 2),
+      ),
+    );
+  }
+
   @override
   void dispose() {
     _controller.dispose();
+    _soundService.dispose();
     super.dispose();
   }
 
   @override
   Widget build(BuildContext context) {
     return Scaffold(
-      appBar: AppBar(title: const Text('Settings')),
-      body: Padding(
+      appBar: AppBar(title: const Text('设置')),
+      body: SingleChildScrollView(
         padding: const EdgeInsets.all(16),
         child: Column(
           crossAxisAlignment: CrossAxisAlignment.stretch,
           children: [
+            // ---- API 地址 ----
+            const Text('API 服务器地址', style: TextStyle(fontSize: 14)),
+            const SizedBox(height: 8),
             TextField(
               controller: _controller,
               decoration: const InputDecoration(
-                labelText: 'API URL',
-                hintText: 'http://192.168.1.100:8000/scan',
+                hintText: 'http://192.168.1.100:8000',
                 border: OutlineInputBorder(),
               ),
               keyboardType: TextInputType.url,
             ),
-            const SizedBox(height: 16),
-            ElevatedButton(
+            const SizedBox(height: 20),
+            ElevatedButton.icon(
               onPressed: _saving ? null : _saveUrl,
-              child: _saving
+              icon: _saving
                   ? const SizedBox(
-                      width: 20,
-                      height: 20,
-                      child: CircularProgressIndicator(strokeWidth: 2))
-                  : const Text('Save'),
+                      width: 18,
+                      height: 18,
+                      child: CircularProgressIndicator(strokeWidth: 2),
+                    )
+                  : const Icon(Icons.save),
+              label: const Text('保存设置'),
             ),
             const SizedBox(height: 8),
-            OutlinedButton(
-              onPressed: _testConnection,
-              child: const Text('Test Connection'),
+            OutlinedButton.icon(
+              onPressed: _testing ? null : _testConnection,
+              icon: _testing
+                  ? const SizedBox(
+                      width: 18,
+                      height: 18,
+                      child: CircularProgressIndicator(strokeWidth: 2),
+                    )
+                  : const Icon(Icons.wifi),
+              label: const Text('测试连接'),
+            ),
+
+            const SizedBox(height: 24),
+
+            // ---- 铃声设置 ----
+            const Divider(),
+            const SizedBox(height: 8),
+            const Text('铃声设置',
+                style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold)),
+            const SizedBox(height: 16),
+
+            // 上架成功铃声
+            _buildSoundRow(
+              label: '上架成功铃声',
+              path: _successPath,
+              onPick: () => _pickSound(true),
+              onPreview: _successPath != null
+                  ? () => _previewSound(_successPath!)
+                  : null,
+              onClear: _successPath != null ? () => _clearSound(true) : null,
+            ),
+
+            const SizedBox(height: 12),
+
+            // 上架失败铃声
+            _buildSoundRow(
+              label: '上架失败铃声',
+              path: _failurePath,
+              onPick: () => _pickSound(false),
+              onPreview: _failurePath != null
+                  ? () => _previewSound(_failurePath!)
+                  : null,
+              onClear:
+                  _failurePath != null ? () => _clearSound(false) : null,
             ),
           ],
         ),
       ),
     );
   }
+
+  Widget _buildSoundRow({
+    required String label,
+    required String? path,
+    required VoidCallback onPick,
+    required VoidCallback? onPreview,
+    required VoidCallback? onClear,
+  }) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Text(label, style: const TextStyle(fontSize: 14)),
+        const SizedBox(height: 6),
+        Row(
+          children: [
+            Expanded(
+              child: Container(
+                padding:
+                    const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+                decoration: BoxDecoration(
+                  border: Border.all(color: Colors.grey.shade400),
+                  borderRadius: BorderRadius.circular(8),
+                ),
+                child: Text(
+                  _fileName(path),
+                  style: TextStyle(
+                    fontSize: 13,
+                    color: path != null ? Colors.black87 : Colors.grey,
+                  ),
+                  overflow: TextOverflow.ellipsis,
+                ),
+              ),
+            ),
+            const SizedBox(width: 8),
+            IconButton(
+              icon: const Icon(Icons.folder_open),
+              tooltip: '选择文件',
+              onPressed: onPick,
+            ),
+            if (onPreview != null)
+              IconButton(
+                icon: const Icon(Icons.play_arrow),
+                tooltip: '试听',
+                onPressed: onPreview,
+              ),
+            if (onClear != null)
+              IconButton(
+                icon: const Icon(Icons.clear, size: 20),
+                tooltip: '清除',
+                onPressed: onClear,
+              ),
+          ],
+        ),
+      ],
+    );
+  }
 }

lib/services/api_service.dart

@@ -1,29 +1,267 @@
 import 'dart:convert';
 import 'package:http/http.dart' as http;
 
+/// Result of a registration API call.
+class RegistrationResult {
+  final bool success;
+  final bool isDuplicate;
+  final String? errorMessage;
+  final Map<String, dynamic>? duplicateInfo;
+
+  RegistrationResult({
+    required this.success,
+    this.isDuplicate = false,
+    this.errorMessage,
+    this.duplicateInfo,
+  });
+
+  factory RegistrationResult.ok() =>
+      RegistrationResult(success: true);
+
+  factory RegistrationResult.duplicate(Map<String, dynamic> info) =>
+      RegistrationResult(success: false, isDuplicate: true, duplicateInfo: info);
+
+  factory RegistrationResult.error(String message) =>
+      RegistrationResult(success: false, errorMessage: message);
+}
+
+// === 装箱模块数据类 ===
+
+/// 箱号内单个总排号明细
+class BoxItemData {
+  final String zongpaiNo;
+  final int quantity;
+
+  BoxItemData({required this.zongpaiNo, required this.quantity});
+
+  factory BoxItemData.fromJson(Map<String, dynamic> json) {
+    return BoxItemData(
+      zongpaiNo: json['zongpai_no'] as String,
+      quantity: json['quantity'] as int,
+    );
+  }
+}
+
+/// 箱号明细
+class BoxDetailData {
+  final int boxNo;
+  final List<BoxItemData> items;
+
+  BoxDetailData({required this.boxNo, required this.items});
+
+  factory BoxDetailData.fromJson(Map<String, dynamic> json) {
+    final items = (json['items'] as List<dynamic>?)
+            ?.map((i) => BoxItemData.fromJson(i as Map<String, dynamic>))
+            .toList() ??
+        [];
+    return BoxDetailData(boxNo: json['box_no'] as int, items: items);
+  }
+}
+
+/// 装箱信息查询结果
+class BoxInfoResult {
+  final bool success;
+  final String? errorMessage;
+  final String? zongpaiNo;
+  final String? paichanNo;
+  final int? quantity;
+  final List<BoxDetailData> existingBoxes;
+  final int maxBoxNo;
+  final int suggestedBoxNo;
+
+  BoxInfoResult({
+    required this.success,
+    this.errorMessage,
+    this.zongpaiNo,
+    this.paichanNo,
+    this.quantity,
+    this.existingBoxes = const [],
+    this.maxBoxNo = 0,
+    this.suggestedBoxNo = 1,
+  });
+
+  factory BoxInfoResult.ok(Map<String, dynamic> json) {
+    final boxes = (json['existing_boxes'] as List<dynamic>?)
+            ?.map((b) => BoxDetailData.fromJson(b as Map<String, dynamic>))
+            .toList() ??
+        [];
+    return BoxInfoResult(
+      success: true,
+      zongpaiNo: json['zongpai_no'] as String?,
+      paichanNo: json['paichan_no'] as String?,
+      quantity: json['quantity'] as int?,
+      existingBoxes: boxes,
+      maxBoxNo: json['max_box_no'] as int? ?? 0,
+      suggestedBoxNo: json['suggested_box_no'] as int? ?? 1,
+    );
+  }
+
+  factory BoxInfoResult.error(String message) {
+    return BoxInfoResult(success: false, errorMessage: message);
+  }
+}
+
+/// 装箱保存结果
+class BoxSaveResult {
+  final bool success;
+  final bool isDuplicate;
+  final String? errorMessage;
+  final String? paichanNo;
+  final int? boxNo;
+
+  BoxSaveResult({
+    required this.success,
+    this.isDuplicate = false,
+    this.errorMessage,
+    this.paichanNo,
+    this.boxNo,
+  });
+
+  factory BoxSaveResult.ok(Map<String, dynamic> json) {
+    return BoxSaveResult(
+      success: true,
+      paichanNo: json['paichan_no'] as String?,
+      boxNo: json['box_no'] as int?,
+    );
+  }
+
+  factory BoxSaveResult.duplicate(Map<String, dynamic> json) {
+    return BoxSaveResult(
+      success: false,
+      isDuplicate: true,
+      paichanNo: json['paichan_no'] as String?,
+      boxNo: json['box_no'] as int?,
+    );
+  }
+
+  factory BoxSaveResult.error(String message) {
+    return BoxSaveResult(success: false, errorMessage: message);
+  }
+}
+
 class ApiService {
   final http.Client _client;
+  final Duration timeout;
 
-  ApiService({http.Client? client}) : _client = client ?? http.Client();
+  ApiService({http.Client? client, this.timeout = const Duration(seconds: 5)})
+      : _client = client ?? http.Client();
 
-  Future<bool> sendScanData(
-    String url, {
-    required String barcode,
-    required String codeType,
+  /// Submit a shelf registration (上架登记).
+  Future<RegistrationResult> registerLocation({
+    required String baseUrl,
+    required String zongpaiNo,
+    required String locationCode,
   }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/location');
     try {
       final response = await _client
           .post(
-            Uri.parse(url),
+            uri,
             headers: {'Content-Type': 'application/json'},
             body: jsonEncode({
-              'barcode': barcode,
-              'code_type': codeType,
-              'timestamp': DateTime.now().toUtc().toIso8601String(),
+              'zongpai_no': zongpaiNo,
+              'location_code': locationCode,
             }),
           )
-          .timeout(const Duration(seconds: 5));
-      return response.statusCode >= 200 && response.statusCode < 300;
+          .timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          return RegistrationResult.ok();
+        case 400:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final msg = body['message']?.toString() ?? '请求参数错误';
+          return RegistrationResult.error(msg);
+        case 409:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return RegistrationResult.duplicate(body);
+        default:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final msg = body['message'] ?? body['error'] ?? 'Unknown error (${response.statusCode})';
+          return RegistrationResult.error(msg.toString());
+      }
+    } catch (e) {
+      return RegistrationResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  /// 查询装箱信息 — GET /CargoTrace/box/info
+  Future<BoxInfoResult> fetchBoxInfo({
+    required String baseUrl,
+    required String zongpaiNo,
+  }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/box/info').replace(
+      queryParameters: {'zongpai_no': zongpaiNo},
+    );
+    try {
+      final response = await _client
+          .get(uri, headers: {'Content-Type': 'application/json'})
+          .timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxInfoResult.ok(body);
+        case 400:
+          return BoxInfoResult.error('无效的总排号格式');
+        case 404:
+          return BoxInfoResult.error('未找到该总排号对应的排产号信息');
+        default:
+          return BoxInfoResult.error('查询失败 (${response.statusCode})');
+      }
+    } catch (e) {
+      return BoxInfoResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  /// 保存装箱记录 — POST /CargoTrace/box
+  Future<BoxSaveResult> saveBoxRecord({
+    required String baseUrl,
+    required String zongpaiNo,
+    required int boxNo,
+    required int quantity,
+  }) async {
+    final uri = Uri.parse('$baseUrl/CargoTrace/box');
+    try {
+      final response = await _client
+          .post(
+            uri,
+            headers: {'Content-Type': 'application/json'},
+            body: jsonEncode({
+              'zongpai_no': zongpaiNo,
+              'box_no': boxNo,
+              'quantity': quantity,
+            }),
+          )
+          .timeout(timeout);
+
+      switch (response.statusCode) {
+        case 200:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxSaveResult.ok(body);
+        case 400:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          final msg = body['message']?.toString() ?? '请求参数错误';
+          return BoxSaveResult.error(msg);
+        case 409:
+          final body = jsonDecode(response.body) as Map<String, dynamic>;
+          return BoxSaveResult.duplicate(body);
+        case 404:
+          return BoxSaveResult.error('未找到该总排号对应的排产号信息');
+        default:
+          return BoxSaveResult.error('提交失败 (${response.statusCode})');
+      }
+    } catch (e) {
+      return BoxSaveResult.error('网络异常，请检查网络连接');
+    }
+  }
+
+  /// Test connectivity by making a HEAD request to the base URL.
+  Future<bool> testConnection(String baseUrl) async {
+    try {
+      final uri = Uri.parse(baseUrl);
+      final response = await _client.head(uri).timeout(timeout);
+      return response.statusCode < 500;
     } catch (_) {
       return false;
     }

lib/services/app_config_service.dart

@@ -0,0 +1,53 @@
+import 'dart:io';
+import 'package:flutter/foundation.dart';
+import 'package:path_provider/path_provider.dart';
+import 'dart:convert';
+
+/// 应用全局配置服务 (替代 SharedPreferences)
+/// 配置数据持久化为本地 JSON 文件，覆盖安装应用时数据不丢失。
+class AppConfigService {
+  static const String _kConfigFileName = 'app_config.json';
+  static final Map<String, dynamic> _defaults = {'api_url': ''};
+
+  Future<String> get _filePath async {
+    final directory = await getApplicationDocumentsDirectory();
+    return '${directory.path}/$_kConfigFileName';
+  }
+
+  /// 读取完整配置字典
+  Future<Map<String, dynamic>> loadConfig() async {
+    try {
+      final file = File(await _filePath);
+      if (await file.exists()) {
+        final jsonString = await file.readAsString();
+        return jsonDecode(jsonString) as Map<String, dynamic>;
+      }
+    } catch (e) {
+      debugPrint('[AppConfig] 读取配置失败: $e');
+    }
+    return Map<String, dynamic>.from(_defaults);
+  }
+
+  /// 读取字符串配置项
+  Future<String?> getString(String key) async {
+    final config = await loadConfig();
+    return config[key] as String?;
+  }
+
+  /// 保存字符串配置项
+  Future<void> setString(String key, String value) async {
+    final config = await loadConfig();
+    config[key.toString()] = value.toString();
+    await _saveConfig(config);
+  }
+
+  /// 完整写入 JSON 文件
+  Future<void> _saveConfig(Map<String, dynamic> config) async {
+    try {
+      final file = File(await _filePath);
+      await file.writeAsString(jsonEncode(config));
+    } catch (e) {
+      debugPrint('[AppConfig] 保存配置失败: $e');
+    }
+  }
+}

lib/services/code_parser.dart

@@ -0,0 +1,41 @@
+// lib/services/code_parser.dart
+class CodeParser {
+  static final _zongpaiRegex = RegExp(
+    r'^\d{2}(B|C|T)\d+$|^\d{2}(BW|CW)\d{4}$',
+  );
+  static final _locationRegex = RegExp(
+    r'^[A-Z0-9]+-[A-Z0-9]+-[A-Z0-9]+$',
+  );
+  static final _transitRegex = RegExp(
+    r'^TRANS-',
+  );
+
+  static ParseResult parse(String code) {
+    final trimmed = code.trim();
+    if (trimmed.isEmpty) {
+      return ParseResult(type: CodeType.invalid, value: code);
+    }
+    final normalized = trimmed.toUpperCase();
+    if (_transitRegex.hasMatch(normalized)) {
+      return ParseResult(type: CodeType.locationTransit, value: normalized);
+    }
+    if (_zongpaiRegex.hasMatch(normalized)) {
+      return ParseResult(type: CodeType.zongpaiNo, value: normalized);
+    }
+    if (_locationRegex.hasMatch(normalized)) {
+      return ParseResult(type: CodeType.locationNormal, value: normalized);
+    }
+    return ParseResult(type: CodeType.invalid, value: code);
+  }
+
+  static bool isLocation(CodeType type) =>
+      type == CodeType.locationNormal || type == CodeType.locationTransit;
+}
+
+enum CodeType { zongpaiNo, locationNormal, locationTransit, invalid }
+
+class ParseResult {
+  final CodeType type;
+  final String value;
+  ParseResult({required this.type, required this.value});
+}

lib/services/sound_service.dart

@@ -0,0 +1,58 @@
+import 'package:audioplayers/audioplayers.dart';
+import 'package:pad_scanner/services/app_config_service.dart';
+
+class SoundService {
+  static const _keySuccess = 'sound_success';
+  static const _keyFailure = 'sound_failure';
+
+  final _player = AudioPlayer();
+  final _configService = AppConfigService();
+
+  Future<String?> getSuccessPath() async {
+    return _configService.getString(_keySuccess);
+  }
+
+  Future<String?> getFailurePath() async {
+    return _configService.getString(_keyFailure);
+  }
+
+  Future<void> setSuccessPath(String? path) async {
+    if (path != null) {
+      await _configService.setString(_keySuccess, path);
+    } else {
+      final config = await _configService.loadConfig();
+      config.remove(_keySuccess);
+    }
+  }
+
+  Future<void> setFailurePath(String? path) async {
+    if (path != null) {
+      await _configService.setString(_keyFailure, path);
+    } else {
+      final config = await _configService.loadConfig();
+      config.remove(_keyFailure);
+    }
+  }
+
+  Future<void> playSuccess() async {
+    final path = await getSuccessPath();
+    if (path != null) {
+      await _player.play(DeviceFileSource(path));
+    }
+  }
+
+  Future<void> playFailure() async {
+    final path = await getFailurePath();
+    if (path != null) {
+      await _player.play(DeviceFileSource(path));
+    }
+  }
+
+  Future<void> play(String path) async {
+    await _player.play(DeviceFileSource(path));
+  }
+
+  Future<void> dispose() async {
+    await _player.dispose();
+  }
+}

linux/flutter/generated_plugin_registrant.cc

@@ -6,6 +6,10 @@
 
 #include "generated_plugin_registrant.h"
 
+#include <audioplayers_linux/audioplayers_linux_plugin.h>
 
 void fl_register_plugins(FlPluginRegistry* registry) {
+  g_autoptr(FlPluginRegistrar) audioplayers_linux_registrar =
+      fl_plugin_registry_get_registrar_for_plugin(registry, "AudioplayersLinuxPlugin");
+  audioplayers_linux_plugin_register_with_registrar(audioplayers_linux_registrar);
 }

linux/flutter/generated_plugins.cmake

@@ -3,9 +3,11 @@
 #
 
 list(APPEND FLUTTER_PLUGIN_LIST
+  audioplayers_linux
 )
 
 list(APPEND FLUTTER_FFI_PLUGIN_LIST
+  jni
 )
 
 set(PLUGIN_BUNDLED_LIBRARIES)

macos/Flutter/GeneratedPluginRegistrant.swift

@@ -5,8 +5,12 @@
 import FlutterMacOS
 import Foundation
 
-import shared_preferences_foundation
+import audioplayers_darwin
+import device_info_plus
+import file_picker
 
 func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
-  SharedPreferencesPlugin.register(with: registry.registrar(forPlugin: "SharedPreferencesPlugin"))
+  AudioplayersDarwinPlugin.register(with: registry.registrar(forPlugin: "AudioplayersDarwinPlugin"))
+  DeviceInfoPlusMacosPlugin.register(with: registry.registrar(forPlugin: "DeviceInfoPlusMacosPlugin"))
+  FilePickerPlugin.register(with: registry.registrar(forPlugin: "FilePickerPlugin"))
 }

pubspec.lock

@@ -1,14 +1,78 @@
 # Generated by pub
 # See https://dart.dev/tools/pub/glossary#lockfile
 packages:
+  args:
+    dependency: transitive
+    description:
+      name: args
+      sha256: d0481093c50b1da8910eb0bb301626d4d8eb7284aa739614d2b394ee09e3ea04
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.7.0"
   async:
     dependency: transitive
     description:
       name: async
-      sha256: "758e6d74e971c3e5aceb4110bfd6698efc7f501675bcfe0c775459a8140750eb"
+      sha256: e2eb0491ba5ddb6177742d2da23904574082139b07c1e33b8503b9f46f3e1a37
       url: "https://pub.dev"
     source: hosted
-    version: "2.13.0"
+    version: "2.13.1"
+  audioplayers:
+    dependency: "direct main"
+    description:
+      name: audioplayers
+      sha256: a72dd459d1a48f61a6fb9c0134dba26597c9236af40639ff0eb70eb4e0baab70
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.6.0"
+  audioplayers_android:
+    dependency: transitive
+    description:
+      name: audioplayers_android
+      sha256: "60a6728277228413a85755bd3ffd6fab98f6555608923813ce383b190a360605"
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.2.1"
+  audioplayers_darwin:
+    dependency: transitive
+    description:
+      name: audioplayers_darwin
+      sha256: c994b3bb3a921e4904ac40e013fbc94488e824fd7c1de6326f549943b0b44a91
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.4.0"
+  audioplayers_linux:
+    dependency: transitive
+    description:
+      name: audioplayers_linux
+      sha256: f75bce1ce864170ef5e6a2c6a61cd3339e1a17ce11e99a25bae4474ea491d001
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.2.1"
+  audioplayers_platform_interface:
+    dependency: transitive
+    description:
+      name: audioplayers_platform_interface
+      sha256: "0e2f6a919ab56d0fec272e801abc07b26ae7f31980f912f24af4748763e5a656"
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.1.1"
+  audioplayers_web:
+    dependency: transitive
+    description:
+      name: audioplayers_web
+      sha256: faa8fa6587f996a6f604433b53af44c57a1407d4fe8dff5766cf63d6875e8de9
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.2.0"
+  audioplayers_windows:
+    dependency: transitive
+    description:
+      name: audioplayers_windows
+      sha256: bafff2b38b6f6d331887558ba6e0a01c9c208d9dbb3ad0005234db065122a734
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.3.0"
   boolean_selector:
     dependency: transitive
     description:
@@ -33,6 +97,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.1.2"
+  code_assets:
+    dependency: transitive
+    description:
+      name: code_assets
+      sha256: "83ccdaa064c980b5596c35dd64a8d3ecc68620174ab9b90b6343b753aa721687"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.0"
   collection:
     dependency: transitive
     description:
@@ -41,14 +113,54 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.19.1"
+  cross_file:
+    dependency: transitive
+    description:
+      name: cross_file
+      sha256: "28bb3ae56f117b5aec029d702a90f57d285cd975c3c5c281eaca38dbc47c5937"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.5+2"
+  crypto:
+    dependency: transitive
+    description:
+      name: crypto
+      sha256: c8ea0233063ba03258fbcf2ca4d6dadfefe14f02fab57702265467a19f27fadf
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.7"
   cupertino_icons:
     dependency: "direct main"
     description:
       name: cupertino_icons
-      sha256: ba631d1c7f7bef6b729a622b7b752645a2d076dba9976925b8f25725a30e1ee6
+      sha256: "41e005c33bd814be4d3096aff55b1908d419fde52ca656c8c47719ec745873cd"
       url: "https://pub.dev"
     source: hosted
-    version: "1.0.8"
+    version: "1.0.9"
+  dbus:
+    dependency: transitive
+    description:
+      name: dbus
+      sha256: d0c98dcd4f5169878b6cf8f6e0a52403a9dff371a3e2f019697accbf6f44a270
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.7.12"
+  device_info_plus:
+    dependency: transitive
+    description:
+      name: device_info_plus
+      sha256: b4fed1b2835da9d670d7bed7db79ae2a94b0f5ad6312268158a9b5479abbacdd
+      url: "https://pub.dev"
+    source: hosted
+    version: "12.4.0"
+  device_info_plus_platform_interface:
+    dependency: transitive
+    description:
+      name: device_info_plus_platform_interface
+      sha256: e1ea89119e34903dca74b883d0dd78eb762814f97fb6c76f35e9ff74d261a18f
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.0.3"
   fake_async:
     dependency: transitive
     description:
@@ -73,6 +185,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "7.0.1"
+  file_picker:
+    dependency: "direct main"
+    description:
+      name: file_picker
+      sha256: "27c58ff4ec17d8e05b8b27fa66175bf5786b9ff9bd94ca418a571c7f6771b27b"
+      url: "https://pub.dev"
+    source: hosted
+    version: "11.0.0"
+  fixnum:
+    dependency: transitive
+    description:
+      name: fixnum
+      sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
   flutter:
     dependency: "direct main"
     description: flutter
@@ -86,6 +214,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "5.0.0"
+  flutter_plugin_android_lifecycle:
+    dependency: transitive
+    description:
+      name: flutter_plugin_android_lifecycle
+      sha256: "38d1c268de9097ff59cf0e844ac38759fc78f76836d37edad06fa21e182055a0"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.0.34"
   flutter_test:
     dependency: "direct dev"
     description: flutter
@@ -96,6 +232,22 @@ packages:
     description: flutter
     source: sdk
     version: "0.0.0"
+  glob:
+    dependency: transitive
+    description:
+      name: glob
+      sha256: c3f1ee72c96f8f78935e18aa8cecced9ab132419e8625dc187e1c2408efc20de
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.3"
+  hooks:
+    dependency: transitive
+    description:
+      name: hooks
+      sha256: "025f060e86d2d4c3c47b56e33caf7f93bf9283340f26d23424ebcfccf34f621e"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.3"
   http:
     dependency: "direct main"
     description:
@@ -112,6 +264,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "4.1.2"
+  jni:
+    dependency: transitive
+    description:
+      name: jni
+      sha256: c2230682d5bc2362c1c9e8d3c7f406d9cbba23ab3f2e203a025dd47e0fb2e68f
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.0"
+  jni_flutter:
+    dependency: transitive
+    description:
+      name: jni_flutter
+      sha256: "8b59e590786050b1cd866677dddaf76b1ade5e7bc751abe04b86e84d379d3ba6"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.1"
   leak_tracker:
     dependency: transitive
     description:
@@ -144,6 +312,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "5.1.1"
+  logging:
+    dependency: transitive
+    description:
+      name: logging
+      sha256: c8245ada5f1717ed44271ed1c26b8ce85ca3228fd2ffdb75468ab01979309d61
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.0"
   matcher:
     dependency: transitive
     description:
@@ -168,6 +344,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.17.0"
+  native_toolchain_c:
+    dependency: transitive
+    description:
+      name: native_toolchain_c
+      sha256: "6ba77bb18063eebe9de401f5e6437e95e1438af0a87a3a39084fbd37c90df572"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.17.6"
+  objective_c:
+    dependency: transitive
+    description:
+      name: objective_c
+      sha256: "100a1c87616ab6ed41ec263b083c0ef3261ee6cd1dc3b0f35f8ddfa4f996fe52"
+      url: "https://pub.dev"
+    source: hosted
+    version: "9.3.0"
+  package_config:
+    dependency: transitive
+    description:
+      name: package_config
+      sha256: f096c55ebb7deb7e384101542bfba8c52696c1b56fca2eb62827989ef2353bbc
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.2.0"
   path:
     dependency: transitive
     description:
@@ -176,6 +376,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.9.1"
+  path_provider:
+    dependency: "direct main"
+    description:
+      name: path_provider
+      sha256: "50c5dd5b6e1aaf6fb3a78b33f6aa3afca52bf903a8a5298f53101fdaee55bbcd"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.5"
+  path_provider_android:
+    dependency: transitive
+    description:
+      name: path_provider_android
+      sha256: "69cbd515a62b94d32a7944f086b2f82b4ac40a1d45bebfc00813a430ab2dabcd"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.3.1"
+  path_provider_foundation:
+    dependency: transitive
+    description:
+      name: path_provider_foundation
+      sha256: "2a376b7d6392d80cd3705782d2caa734ca4727776db0b6ec36ef3f1855197699"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.6.0"
   path_provider_linux:
     dependency: transitive
     description:
@@ -200,6 +424,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.3.0"
+  petitparser:
+    dependency: transitive
+    description:
+      name: petitparser
+      sha256: "91bd59303e9f769f108f8df05e371341b15d59e995e6806aefab827b58336675"
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.0.2"
   platform:
     dependency: transitive
     description:
@@ -216,62 +448,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.8"
-  shared_preferences:
-    dependency: "direct main"
-    description:
-      name: shared_preferences
-      sha256: "6e8bf70b7fef813df4e9a36f658ac46d107db4b4cfe1048b477d4e453a8159f5"
-      url: "https://pub.dev"
-    source: hosted
-    version: "2.5.3"
-  shared_preferences_android:
+  pub_semver:
     dependency: transitive
     description:
-      name: shared_preferences_android
-      sha256: bd14436108211b0d4ee5038689a56d4ae3620fd72fd6036e113bf1345bc74d9e
+      name: pub_semver
+      sha256: "5bfcf68ca79ef689f8990d1160781b4bad40a3bd5e5218ad4076ddb7f4081585"
       url: "https://pub.dev"
     source: hosted
-    version: "2.4.13"
-  shared_preferences_foundation:
+    version: "2.2.0"
+  record_use:
     dependency: transitive
     description:
-      name: shared_preferences_foundation
-      sha256: "6a52cfcdaeac77cad8c97b539ff688ccfc458c007b4db12be584fbe5c0e49e03"
+      name: record_use
+      sha256: "2551bd8eecfe95d14ae75f6021ad0248be5c27f138c2ec12fcb52b500b3ba1ed"
       url: "https://pub.dev"
     source: hosted
-    version: "2.5.4"
-  shared_preferences_linux:
-    dependency: transitive
-    description:
-      name: shared_preferences_linux
-      sha256: "580abfd40f415611503cae30adf626e6656dfb2f0cee8f465ece7b6defb40f2f"
-      url: "https://pub.dev"
-    source: hosted
-    version: "2.4.1"
-  shared_preferences_platform_interface:
-    dependency: transitive
-    description:
-      name: shared_preferences_platform_interface
-      sha256: "57cbf196c486bc2cf1f02b85784932c6094376284b3ad5779d1b1c6c6a816b80"
-      url: "https://pub.dev"
-    source: hosted
-    version: "2.4.1"
-  shared_preferences_web:
-    dependency: transitive
-    description:
-      name: shared_preferences_web
-      sha256: c49bd060261c9a3f0ff445892695d6212ff603ef3115edbb448509d407600019
-      url: "https://pub.dev"
-    source: hosted
-    version: "2.4.3"
-  shared_preferences_windows:
-    dependency: transitive
-    description:
-      name: shared_preferences_windows
-      sha256: "94ef0f72b2d71bc3e700e025db3710911bd51a71cefb65cc609dd0d9a982e3c1"
-      url: "https://pub.dev"
-    source: hosted
-    version: "2.4.1"
+    version: "0.6.0"
   sky_engine:
     dependency: transitive
     description: flutter
@@ -281,10 +473,10 @@ packages:
     dependency: transitive
     description:
       name: source_span
-      sha256: "254ee5351d6cb365c859e20ee823c3bb479bf4a293c22d17a9f1bf144ce86f7c"
+      sha256: "56a02f1f4cd1a2d96303c0144c93bd6d909eea6bee6bf5a0e0b685edbd4c47ab"
       url: "https://pub.dev"
     source: hosted
-    version: "1.10.1"
+    version: "1.10.2"
   stack_trace:
     dependency: transitive
     description:
@@ -309,6 +501,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.4.1"
+  synchronized:
+    dependency: transitive
+    description:
+      name: synchronized
+      sha256: "63896c27e81b28f8cb4e69ead0d3e8f03f1d1e5fc531a3e579cabed6a2c7c9e5"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.4.0+1"
   term_glyph:
     dependency: transitive
     description:
@@ -333,6 +533,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.4.0"
+  uuid:
+    dependency: transitive
+    description:
+      name: uuid
+      sha256: "1fef9e8e11e2991bb773070d4656b7bd5d850967a2456cfc83cf47925ba79489"
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.5.3"
   vector_math:
     dependency: transitive
     description:
@@ -341,14 +549,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.2.0"
+  vibration:
+    dependency: "direct main"
+    description:
+      name: vibration
+      sha256: "9bb06614c69260f8bd11c80fe01ed7988905cf00e3417d656c2647e41f261d87"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.8"
+  vibration_platform_interface:
+    dependency: transitive
+    description:
+      name: vibration_platform_interface
+      sha256: "258c273268f8aa40c88d29741137c536874a738779b92ddb8aa32ed093721ec5"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.1.2"
   vm_service:
     dependency: transitive
     description:
       name: vm_service
-      sha256: ddfa8d30d89985b96407efce8acbdd124701f96741f2d981ca860662f1c0dc02
+      sha256: "0016aef94fc66495ac78af5859181e3f3bf2026bd8eecc72b9565601e19ab360"
       url: "https://pub.dev"
     source: hosted
-    version: "15.0.0"
+    version: "15.2.0"
   web:
     dependency: transitive
     description:
@@ -357,6 +581,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.1.1"
+  win32:
+    dependency: transitive
+    description:
+      name: win32
+      sha256: d7cb55e04cd34096cd3a79b3330245f54cb96a370a1c27adb3c84b917de8b08e
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.15.0"
+  win32_registry:
+    dependency: transitive
+    description:
+      name: win32_registry
+      sha256: "6f1b564492d0147b330dd794fee8f512cec4977957f310f9951b5f9d83618dae"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.0"
   xdg_directories:
     dependency: transitive
     description:
@@ -365,6 +605,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.1.0"
+  xml:
+    dependency: transitive
+    description:
+      name: xml
+      sha256: "971043b3a0d3da28727e40ed3e0b5d18b742fa5a68665cca88e74b7876d5e025"
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.6.1"
+  yaml:
+    dependency: transitive
+    description:
+      name: yaml
+      sha256: b9da305ac7c39faa3f030eccd175340f968459dae4af175130b3fc47e40d76ce
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.3"
 sdks:
-  dart: ">=3.9.0-0 <4.0.0"
-  flutter: ">=3.29.0"
+  dart: ">=3.11.0 <4.0.0"
+  flutter: ">=3.38.4"

pubspec.yaml

@@ -35,7 +35,10 @@ dependencies:
   # Use with the CupertinoIcons class for iOS style icons.
   cupertino_icons: ^1.0.8
   http: ^1.2.0
-  shared_preferences: ^2.2.0
+  path_provider: ^2.1.1
+  vibration: ^3.1.8
+  file_picker: 11.0.0
+  audioplayers: ^6.6.0
 
 dev_dependencies:
   flutter_test:

test/models/scan_record_test.dart

@@ -1,29 +0,0 @@
-import 'package:flutter_test/flutter_test.dart';
-import 'package:pad_scanner/models/scan_record.dart';
-
-void main() {
-  group('ScanRecord', () {
-    test('creates with correct defaults', () {
-      final record = ScanRecord(
-        barcode: '1234567890',
-        codeType: 'CODE128',
-        timestamp: DateTime.parse('2026-05-07T10:30:00Z'),
-      );
-      expect(record.barcode, '1234567890');
-      expect(record.codeType, 'CODE128');
-      expect(record.status, SendStatus.pending);
-    });
-
-    test('toJson produces correct map', () {
-      final record = ScanRecord(
-        barcode: 'ABC123',
-        codeType: 'QR',
-        timestamp: DateTime.parse('2026-05-07T10:30:00Z'),
-      );
-      final json = record.toJson();
-      expect(json['barcode'], 'ABC123');
-      expect(json['code_type'], 'QR');
-      expect(json['timestamp'], '2026-05-07T10:30:00.000Z');
-    });
-  });
-}

test/services/api_service_test.dart

@@ -1,34 +1,100 @@
+import 'dart:convert';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:http/http.dart' as http;
-import 'package:http/testing.dart';
 import 'package:pad_scanner/services/api_service.dart';
 
 void main() {
-  group('ApiService', () {
-    test('sendScanData returns true on 200', () async {
-      final client = MockClient((request) async {
-        return http.Response('{"status":"ok"}', 200);
-      });
-      final service = ApiService(client: client);
-      final result = await service.sendScanData(
-        'http://localhost:8000/scan',
-        barcode: '123456',
-        codeType: 'CODE128',
+  group('ApiService.registerLocation', () {
+    test('returns ok on 200', () async {
+      final mockClient = _MockClient((request) async {
+        return http.Response(
+          jsonEncode({'zongpai_no': '26B1', 'location_code': 'A01-02-03', 'created_at': '2026-05-11T10:00:00'}),
+          200,
+          headers: {'content-type': 'application/json; charset=utf-8'},
         );
-      expect(result, isTrue);
+      });
+      final svc = ApiService(client: mockClient);
+      final result = await svc.registerLocation(
+        baseUrl: 'http://localhost',
+        zongpaiNo: '26B1',
+        locationCode: 'A01-02-03',
+      );
+      expect(result.success, isTrue);
+      expect(result.isDuplicate, isFalse);
     });
 
-    test('sendScanData returns false on error', () async {
-      final client = MockClient((request) async {
-        return http.Response('error', 500);
-      });
-      final service = ApiService(client: client);
-      final result = await service.sendScanData(
-        'http://localhost:8000/scan',
-        barcode: '123456',
-        codeType: 'CODE128',
+    test('returns duplicate on 409 with location_code and registered_at', () async {
+      final mockClient = _MockClient((request) async {
+        return http.Response(
+          jsonEncode({
+            'error_code': 'DUPLICATE_LOCATION',
+            'message': '该总排号已存在货位记录',
+            'location_code': 'A01-02-03',
+            'registered_at': '2026-05-11T10:00:00',
+          }),
+          409,
+          headers: {'content-type': 'application/json; charset=utf-8'},
         );
-      expect(result, isFalse);
+      });
+      final svc = ApiService(client: mockClient);
+      final result = await svc.registerLocation(
+        baseUrl: 'http://localhost',
+        zongpaiNo: '26B1',
+        locationCode: 'A02-01-01',
+      );
+      expect(result.success, isFalse);
+      expect(result.isDuplicate, isTrue);
+      expect(result.duplicateInfo?['location_code'], 'A01-02-03');
+      expect(result.duplicateInfo?['registered_at'], '2026-05-11T10:00:00');
+    });
+
+    test('returns error on 400 with message', () async {
+      final mockClient = _MockClient((request) async {
+        return http.Response(
+          jsonEncode({'error_code': 'INVALID_ZONGPAI', 'message': 'INVALID_ZONGPAI'}),
+          400,
+          headers: {'content-type': 'application/json; charset=utf-8'},
+        );
+      });
+      final svc = ApiService(client: mockClient);
+      final result = await svc.registerLocation(
+        baseUrl: 'http://localhost',
+        zongpaiNo: 'INVALID',
+        locationCode: 'A01-02-03',
+      );
+      expect(result.success, isFalse);
+      expect(result.isDuplicate, isFalse);
+      expect(result.errorMessage, 'INVALID_ZONGPAI');
+    });
+
+    test('returns error on network failure', () async {
+      final mockClient = _MockClient((request) async {
+        throw Exception('Connection refused');
+      });
+      final svc = ApiService(client: mockClient, timeout: Duration(seconds: 1));
+      final result = await svc.registerLocation(
+        baseUrl: 'http://localhost',
+        zongpaiNo: '26B1',
+        locationCode: 'A01-02-03',
+      );
+      expect(result.success, isFalse);
+      expect(result.errorMessage, '网络异常，请检查网络连接');
     });
   });
 }
+
+class _MockClient extends http.BaseClient {
+  final Future<http.Response> Function(http.BaseRequest) _handler;
+  _MockClient(this._handler);
+
+  @override
+  Future<http.StreamedResponse> send(http.BaseRequest request) async {
+    final response = await _handler(request);
+    return http.StreamedResponse(
+      http.ByteStream.fromBytes(response.bodyBytes),
+      response.statusCode,
+      headers: response.headers,
+      reasonPhrase: response.reasonPhrase,
+    );
+  }
+}

test/services/code_parser_test.dart

@@ -0,0 +1,65 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pad_scanner/services/code_parser.dart';
+
+void main() {
+  group('CodeParser.parse', () {
+    test('identifies zongpaiNo type B', () {
+      final result = CodeParser.parse('26B1');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26B1');
+    });
+    test('identifies zongpaiNo type C', () {
+      final result = CodeParser.parse('26C12');
+      expect(result.type, CodeType.zongpaiNo);
+    });
+    test('identifies zongpaiNo type T', () {
+      final result = CodeParser.parse('26T3');
+      expect(result.type, CodeType.zongpaiNo);
+    });
+    test('identifies zongpaiNo type BW (4 digits)', () {
+      final result = CodeParser.parse('26BW0001');
+      expect(result.type, CodeType.zongpaiNo);
+    });
+    test('identifies zongpaiNo type CW (4 digits)', () {
+      final result = CodeParser.parse('26CW0015');
+      expect(result.type, CodeType.zongpaiNo);
+    });
+    test('rejects BW with non-4-digit serial', () {
+      expect(CodeParser.parse('26BW01').type, CodeType.invalid);
+    });
+    test('rejects CW with non-4-digit serial', () {
+      expect(CodeParser.parse('26CW15').type, CodeType.invalid);
+    });
+    test('identifies normal location code', () {
+      final result = CodeParser.parse('A01-02-03');
+      expect(result.type, CodeType.locationNormal);
+      expect(result.value, 'A01-02-03');
+    });
+    test('identifies transit location code', () {
+      final result = CodeParser.parse('TRANS-01');
+      expect(result.type, CodeType.locationTransit);
+    });
+    test('normalizes lowercase zongpaiNo to uppercase', () {
+      final result = CodeParser.parse('26b1');
+      expect(result.type, CodeType.zongpaiNo);
+      expect(result.value, '26B1');
+    });
+    test('normalizes lowercase location code to uppercase', () {
+      final result = CodeParser.parse('a01-02-03');
+      expect(result.type, CodeType.locationNormal);
+      expect(result.value, 'A01-02-03');
+    });
+    test('rejects invalid code', () {
+      expect(CodeParser.parse('HELLO123').type, CodeType.invalid);
+    });
+    test('rejects empty string', () {
+      expect(CodeParser.parse('').type, CodeType.invalid);
+    });
+    test('isLocation helper', () {
+      expect(CodeParser.isLocation(CodeType.locationNormal), true);
+      expect(CodeParser.isLocation(CodeType.locationTransit), true);
+      expect(CodeParser.isLocation(CodeType.zongpaiNo), false);
+      expect(CodeParser.isLocation(CodeType.invalid), false);
+    });
+  });
+}

windows/flutter/generated_plugin_registrant.cc

@@ -6,6 +6,9 @@
 
 #include "generated_plugin_registrant.h"
 
+#include <audioplayers_windows/audioplayers_windows_plugin.h>
 
 void RegisterPlugins(flutter::PluginRegistry* registry) {
+  AudioplayersWindowsPluginRegisterWithRegistrar(
+      registry->GetRegistrarForPlugin("AudioplayersWindowsPlugin"));
 }

windows/flutter/generated_plugins.cmake

@@ -3,9 +3,11 @@
 #
 
 list(APPEND FLUTTER_PLUGIN_LIST
+  audioplayers_windows
 )
 
 list(APPEND FLUTTER_FFI_PLUGIN_LIST
+  jni
 )
 
 set(PLUGIN_BUNDLED_LIBRARIES)