feat: wire RegistrationPage as app home, remove ScanPage

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

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/registration_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: '上架登记',
       theme: ThemeData(
         colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
         useMaterial3: true,
       ),
-      home: const ScanPage(),
+      home: const RegistrationPage(),
     );
   }
 }

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/registration_page.dart

@@ -0,0 +1,404 @@
+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;
+
+  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('上架成功', isError: false);
+      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: [
+          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 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: [
+                  // 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 with type label
+                  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,
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}

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

@@ -13,6 +13,7 @@ class _SettingsPageState extends State<SettingsPage> {
   final _controller = TextEditingController();
   final _apiService = ApiService();
   bool _saving = false;
+  bool _testing = false;
 
   @override
   void initState() {
@@ -22,41 +23,52 @@ class _SettingsPageState extends State<SettingsPage> {
 
   Future<void> _loadUrl() async {
     final prefs = await SharedPreferences.getInstance();
-    _controller.text = prefs.getString('api_url') ?? '';
+    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', _controller.text.trim());
+    await prefs.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,
       );
     }
   }
 
+  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();
@@ -66,35 +78,45 @@ class _SettingsPageState extends State<SettingsPage> {
   @override
   Widget build(BuildContext context) {
     return Scaffold(
-      appBar: AppBar(title: const Text('Settings')),
+      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(
-                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('测试连接'),
             ),
           ],
         ),

lib/services/api_service.dart

@@ -1,29 +1,78 @@
 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}) : _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 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;
     }

lib/services/code_parser.dart

@@ -0,0 +1,39 @@
+// 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) {
+    if (code.isEmpty) {
+      return ParseResult(type: CodeType.invalid, value: code);
+    }
+    if (_transitRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.locationTransit, value: code);
+    }
+    if (_zongpaiRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.zongpaiNo, value: code);
+    }
+    if (_locationRegex.hasMatch(code)) {
+      return ParseResult(type: CodeType.locationNormal, value: code);
+    }
+    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});
+}

test/services/code_parser_test.dart

@@ -0,0 +1,58 @@
+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('rejects lowercase location code', () {
+      expect(CodeParser.parse('a01-02-03').type, CodeType.invalid);
+    });
+    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);
+    });
+  });
+}