이전 목록으로
#Flutter#Android

Flutter 물류 앱 바코드 스캐너 설계: 카메라·하드웨어 입력·중복 방지

현장형 Flutter 앱에서 카메라 바코드 스캔과 블루투스·USB 스캐너 입력을 함께 처리하는 구조를 설명한다. 연속 인식, 중복 API 요청, 포커스와 키보드, 앱 생명주기 문제를 코드로 해결한다.

물류 앱의 스캔 화면은 단순히 문자열을 읽는 카메라 화면이 아니다. 같은 바코드가 여러 프레임에서 반복 인식되고, API 응답 전 다음 코드가 들어오며, 산업용 스캐너는 키보드처럼 값을 입력한다.

입력 방식 비교

방식 장점 주의점
카메라 별도 장비가 필요 없음 조도·초점·중복 감지
Bluetooth/USB HID 빠르고 정확함 포커스·Enter suffix 처리
BLE GATT 장비 상태 제어 가능 권한·연결·재접속 구현 필요
flowchart TD
    A[카메라 또는 외부 스캐너] --> B[입력 정규화]
    B --> C{형식 검증}
    C -- 실패 --> D[오류음과 안내]
    C -- 성공 --> E{중복 또는 처리 중?}
    E -- 예 --> F[입력 무시]
    E -- 아니오 --> G[API 검증]
    G --> H[목록과 수량 갱신]

카메라 스캔 기본 구현

flutter pub add mobile_scanner
import 'package:flutter/material.dart';
import 'package:mobile_scanner/mobile_scanner.dart';

class BarcodeScanPage extends StatefulWidget {
  const BarcodeScanPage({super.key});

  @override
  State<BarcodeScanPage> createState() => _BarcodeScanPageState();
}

class _BarcodeScanPageState extends State<BarcodeScanPage> {
  final _controller = MobileScannerController(
    formats: const [BarcodeFormat.code128, BarcodeFormat.qrCode],
  );

  bool _processing = false;
  String? _lastCode;
  DateTime? _lastScannedAt;

  Future<void> _onDetect(BarcodeCapture capture) async {
    final code = capture.barcodes.isEmpty
        ? null
        : capture.barcodes.first.rawValue?.trim();
    if (code == null || code.isEmpty || _processing) return;

    final now = DateTime.now();
    final duplicated = code == _lastCode &&
        _lastScannedAt != null &&
        now.difference(_lastScannedAt!) < const Duration(seconds: 2);
    if (duplicated) return;

    _processing = true;
    _lastCode = code;
    _lastScannedAt = now;

    try {
      await verifyBarcode(code);
    } finally {
      _processing = false;
    }
  }

  Future<void> verifyBarcode(String code) async {
    // Repository 또는 Cubit으로 전달한다.
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: MobileScanner(
        controller: _controller,
        onDetect: _onDetect,
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _controller.toggleTorch,
        child: const Icon(Icons.flashlight_on),
      ),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }
}

카메라는 같은 코드를 여러 프레임에서 반복 감지할 수 있다. 카메라 입력의 중복 차단 정책과 HID 스캐너의 입력 간격 제한 정책은 구분해서 설계한다.

HID 스캐너 입력 처리

많은 Bluetooth 스캐너는 BLE 데이터가 아니라 키보드 입력 장치로 동작한다. 이 프로젝트에서는 스캐너가 바코드 문자열을 전송한 뒤 Enter 키를 suffix로 보내도록 장비에서 설정하고, BarcodeKeyboardListener는 Enter가 들어오면 하나의 스캔이 완료된 것으로 판단한다.

스캐너 입력이 들어올 때는 입력 필드에 포커스를 요청하지 않는다. TextField를 강제로 포커싱하면 소프트웨어 키보드가 올라와 작업 흐름을 방해할 수 있기 때문이다. 사용자가 입력 필드를 직접 선택한 경우에만 필드가 일반 키보드 입력과 Enter 제출을 담당하고, 포커스가 없을 때는 바깥의 스캐너 리스너가 HID 입력을 처리한다.

Expanded(
  child: BarcodeKeyboardListener(
    // 사용자가 입력 필드를 편집할 때 스캔 리스너의 중복 수신을 막는다.
    ignoreFocusNode: _focusNode,
    onBarcodeScanned: (value) => _handleSubmit(value),
    child: TcTextField(
      controller: _textController,
      focusNode: _focusNode,
      hintText: widget.hintText,
      textInputAction: TextInputAction.done,
      onFieldSubmitted: (value) => _handleSubmit(value),
    ),
  ),
)

ignoreFocusNode는 입력 필드에 포커스가 있을 때 BarcodeKeyboardListener의 처리를 건너뛰게 한다. 따라서 사용자가 직접 입력할 때는 onFieldSubmitted, 필드에 포커스가 없을 때 들어오는 스캐너 입력은 onBarcodeScanned라는 하나의 경로만 실행된다. 스캔을 받기 위해 _focusNode.requestFocus()를 호출하지 않으므로 소프트웨어 키보드도 자동으로 표시되지 않는다.

BarcodeKeyboardListener의 버퍼 동작

bufferDuration은 완성된 바코드 두 건 사이의 디바운스 시간이 아니다. 한 바코드를 구성하는 연속 키 이벤트 사이의 최대 허용 간격이다. 기본값은 100ms이며, 다음 키가 들어왔을 때 직전 키 입력으로부터 100ms보다 오래 지났다면 기존 문자 버퍼를 비운다.

const Duration hundredMs = Duration(milliseconds: 100);
const String lineFeed = '\n';

void onKeyEvent(String? char) {
  checkPendingCharCodesToClear();
  _lastScannedCharCodeTime = DateTime.now();

  if (char == lineFeed) {
    _onBarcodeScannedCallback(_scannedChars.join());
    resetScannedCharCodes();
  } else {
    _scannedChars.add(char!);
  }
}

예를 들어 A, B, C, Enter가 각각 100ms 안에 이어지면 ABC가 전달된다. 도중에 입력 간격이 100ms를 넘으면 앞서 모은 문자는 폐기되고 그다음 문자부터 새 바코드로 수집한다. 별도의 타이머가 100ms 후 자동 실행되는 구조는 아니며, 다음 키 이벤트가 들어오는 시점에 오래된 버퍼를 확인한다.

flowchart TD
    A[물리 키 이벤트] --> B{입력 필드 포커스?}
    B -- 예 --> C[리스너 무시]
    B -- 아니오 --> D{직전 문자와 100ms 이내?}
    D -- 아니오 --> E[기존 버퍼 초기화]
    D -- 예 --> F[버퍼 유지]
    E --> G{Enter 키?}
    F --> G
    G -- 아니오 --> H[문자 추가]
    G -- 예 --> I[문자열 콜백 후 초기화]

이 버퍼는 사람이 천천히 타이핑한 문자열과 스캐너의 빠른 연속 입력을 구분하는 데 도움을 주지만, 다음 기능은 제공하지 않는다.

  • 동일 바코드 중복 차단
  • 완성된 스캔 두 건 사이의 쿨다운
  • API 요청 진행 중 추가 요청 방지
  • 서버의 중복 처리 방지

따라서 같은 바코드를 빠르게 두 번 스캔해도 각 입력이 정상적으로 Enter까지 완성되면 콜백이 두 번 호출된다. 중복 처리가 업무상 문제가 된다면 동일 값 쿨다운, 요청 중 잠금 또는 서버 멱등성 키를 별도 정책으로 추가해야 한다.

빈값과 Enter 처리

Enter가 들어오면 리스너는 현재 버퍼를 합쳐 콜백을 호출한다. 버퍼가 비어 있거나 문자 입력 후 100ms가 지난 상태에서 Enter가 들어오면 빈 문자열이 전달될 수 있으므로, 최종 제출 함수에서 빈값을 방어한다.

void _handleSubmit(String rawValue) {
  final value = rawValue.trim();
  if (value.isEmpty) return;

  _textController.clear();
  widget.onSubmitted(value);
}

플랫폼별 키 이벤트

리스너는 RawKeyboard.instance에 직접 등록되기 때문에 다른 컨트롤이 포커스를 가지고 있어도 물리 키보드 이벤트를 받을 수 있다. 다만 ignoreFocusNode에 포커스가 있으면 즉시 반환해 TextField와 리스너가 같은 입력을 동시에 처리하지 않도록 한다.

물리 키 입력 판단 순서

이 구현에는 “이 장치가 바코드 스캐너인가?”를 식별하는 별도의 장치 판별 로직은 없다. RawKeyboard로 들어온 키 이벤트를 대상으로 문자 범위, 특수 키, Down/Up 이벤트와 입력 속도를 조합해 스캐너 입력처럼 해석한다.

void _keyBoardCallback(RawKeyEvent keyEvent) {
  // 1. 입력 필드를 사용 중이면 TextField가 처리한다.
  if (widget.ignoreFocusNode?.hasFocus == true) return;

  // 2. keyId가 문자 범위를 벗어난 키는 Enter와 왼쪽 Shift만 허용한다.
  if (keyEvent.logicalKey.keyId > 255 &&
      keyEvent.logicalKey != LogicalKeyboardKey.enter &&
      keyEvent.logicalKey != LogicalKeyboardKey.shiftLeft) {
    return;
  }

  // 3. 설정에 따라 KeyUp 또는 KeyDown 한쪽만 처리한다.
  final acceptedEvent =
      (!useKeyDownEvent && keyEvent is RawKeyUpEvent) ||
      (useKeyDownEvent && keyEvent is RawKeyDownEvent);

  if (!acceptedEvent) return;

  // 4. 플랫폼 키 데이터에서 문자 또는 Enter를 추출해 버퍼로 보낸다.
  // 실제 구현은 Android, Windows, Web 등 플랫폼별 분기를 사용한다.
}

판단 과정은 다음과 같다.

  1. ignoreFocusNode.hasFocus가 true이면 전체 이벤트를 무시한다.
  2. logicalKey.keyId <= 255인 키는 문자 후보로 통과시킨다.
  3. keyId > 255인 키 중에서는 Enter와 왼쪽 Shift만 예외적으로 허용하고 방향키, 기능키 등의 나머지 특수 키는 버린다.
  4. 기본 설정에서는 RawKeyUpEvent, useKeyDownEvent: true에서는 RawKeyDownEvent만 처리해 Down과 Up의 이중 수집을 방지한다.
  5. 통과한 이벤트를 플랫폼별 데이터에서 문자열로 변환한 후, 문자 간격이 bufferDuration 안에 이어지고 Enter로 끝나면 바코드로 확정한다.

여기서 “물리 키”라는 표현은 RawKeyboard 이벤트 경로로 들어오는 하드웨어 키 입력이라는 의미다. 코드가 keyEvent.physicalKey나 USB/Bluetooth 장치 ID를 검사하는 것은 아니며, 실제 필터 기준은 대부분 logicalKey다. 따라서 일반 USB·Bluetooth 키보드로 빠르게 문자열을 입력하고 Enter를 눌러도 스캐너 입력으로 인식될 수 있다. 반대로 소프트웨어 키보드 입력은 일반적으로 TextField의 텍스트 입력 경로로 처리되며 이 리스너의 스캔 버퍼 대상이 아니다.

기본적으로 RawKeyUpEvent를 처리하며, Windows에서 빈 바코드 문제가 발생하면 useKeyDownEvent: true로 RawKeyDownEvent를 사용한다. Android에서는 caseSensitive: true일 때 왼쪽 Shift 입력을 감지해 다음 문자를 대문자로 변환한다. Web, Linux, Windows, macOS, iOS, Fuchsia는 각 플랫폼의 키 데이터에서 문자를 추출한다.

이 구현은 위젯이 화면에 보이는지와 관계없이 State가 트리에 남아 있는 동안 전역 키 이벤트를 수신한다. 사용하지 않는 화면의 리스너가 함께 살아 있으면 동일 입력을 여러 리스너가 받을 수 있으므로 라우트 생명주기와 위젯 제거 여부를 확인해야 한다. dispose()에서는 스트림 구독과 컨트롤러를 닫고 RawKeyboard 리스너를 반드시 제거한다.

Flutter 버전 주의: RawKeyboard, RawKeyEvent, RawKeyDownEvent, RawKeyUpEvent는 Flutter 3.18 이후 deprecated API다. 현재 구현을 유지할 수는 있지만 새 코드나 향후 마이그레이션에서는 HardwareKeyboard와 KeyEvent 기반 구현을 검토해야 한다. 기존 API는 향후 제거될 예정이다.

구현상 확인할 점

  • RawKeyboard.instance.addListener()는 전역 등록이므로 화면마다 리스너 인스턴스가 중복 생성되지 않게 한다.
  • 리스너 등록은 State 생성자보다 initState()에서, 해제는 dispose()에서 대칭적으로 관리하는 편이 명확하다.
  • bufferDuration 검사에는 별도 타이머가 없다. 마지막 문자 뒤에 다음 이벤트가 오지 않으면 버퍼는 그대로 남아 있다가 다음 이벤트에서 초기화된다.
  • Enter만 수신해도 빈 문자열 콜백이 발생할 수 있으므로 _handleSubmit()의 빈값 검사를 제거하면 안 된다.
  • caseSensitive 처리는 현재 Android의 왼쪽 Shift 조합만 별도로 보정한다. 모든 플랫폼에서 동일한 대소문자 동작을 보장하는 옵션으로 간주하면 안 된다.
  • useKeyDownEvent를 잘못 설정하면 한 번의 스캔이 Down/Up 이벤트 중 의도하지 않은 쪽에서 처리되거나 문자가 누락될 수 있으므로 실제 HID 스캐너와 대상 OS에서 검증한다.
  • Android 분기는 공통 Enter 검사보다 먼저 실행되어 RawKeyEventDataAndroid.codePoint를 문자열로 변환한다. 대상 스캐너의 Enter가 실제로 \n으로 변환되어 완료 처리되는지 Android 실기기에서 확인한다.

실제 장비마다 suffix가 없거나 Enter 대신 Tab을 보내도록 설정되어 있을 수 있다. 앱의 완료 키 판단과 스캐너의 suffix 설정이 일치하는지 먼저 확인한다.

실무 체크리스트

  • 스캔할 포맷만 지정해 탐색 범위를 줄인다.
  • 저조도 환경을 위해 Torch 버튼을 제공한다.
  • BarcodeKeyboardListener의 완료 조건과 장비의 Enter suffix 설정을 일치시킨다.
  • 스캐너 수신을 위해 입력 필드를 강제로 포커싱하지 않는다.
  • 빈 문자열을 제출하지 않는다.
  • bufferDuration은 문자 간 최대 간격이며 스캔 간 디바운스나 중복 요청 방어가 아님을 구분한다.
  • Enter만 들어온 경우를 포함해 최종 제출 단계에서 빈 문자열을 차단한다.
  • 화면에서 사용하지 않는 리스너가 위젯 트리에 남아 중복 수신하지 않는지 확인한다.
  • API 처리 중 다음 스캔을 허용할지, 큐에 넣을지 또는 무시할지는 별도 정책으로 결정한다.
  • 성공·중복·오류에 서로 다른 소리와 진동을 사용한다.
  • 앱 비활성화 시 카메라를 중지하고 복귀 시 재시작한다.
  • 화면을 벗어난 뒤 콜백이 UI를 갱신하지 않도록 한다.

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.