이전 목록으로
#Flutter#Architecture

물류 앱 상태 설계: 주문 상태와 운송장 상태를 분리해야 하는 이유

입고·패킹·간선·배송·설치·회수가 연결된 물류 앱에서 하나의 상태 값만 사용할 때 생기는 문제를 살펴보고, 주문·운송장·작업 Assignment를 분리한 상태 머신과 Flutter 모델링 방법을 제안한다.

물류 시스템에서는 주문이 완료되지 않았어도 일부 운송장은 배송될 수 있고, 기사 배정은 취소됐지만 주문은 살아 있을 수 있다. 모든 상황을 status 하나에 넣으면 조건문이 폭발한다.

상태의 주체를 분리한다

erDiagram
    ORDER ||--|{ WAYBILL : contains
    ORDER ||--o{ ASSIGNMENT : schedules
    WAYBILL ||--o{ SCAN_EVENT : records
    ASSIGNMENT ||--o{ WORK_EVENT : records

    ORDER {
      int id
      string order_status
      string service_type
    }
    WAYBILL {
      int id
      string waybill_number
      string logistics_status
    }
    ASSIGNMENT {
      int id
      date work_date
      string assignment_status
    }
  • Order: 고객 계약과 전체 주문의 완료·취소 상태
  • Waybill: 실제 상품의 입고·출고·배송 상태
  • Assignment: 기사, 작업일, 일정 확정 상태
  • Work Event: 스캔·사진·서명·완료 같은 이력

배송 상태 머신 예시

stateDiagram-v2
    [*] --> ReceiptConfirmed
    ReceiptConfirmed --> DriverAssigned
    DriverAssigned --> ScheduleConfirmed
    ScheduleConfirmed --> Loaded
    Loaded --> Working
    Working --> Completed
    Loaded --> Returning: 취소 또는 재약속
    Working --> Returning: 설치 불가
    Returning --> Returned

상태 전이는 서버가 최종 권한을 가져야 한다. 앱은 “현재 상태에서 가능한 액션”을 표시하되 서버 응답으로 다시 확정한다.

Dart 모델링

enum WaybillStatus {
  receiptConfirmed,
  driverAssigned,
  scheduleConfirmed,
  loaded,
  working,
  completed,
  returning,
  returned,
}

enum WorkAction {
  confirmSchedule,
  scanOutbound,
  startWork,
  completeWork,
  requestReschedule,
  requestCancel,
}

extension WaybillStatusPolicy on WaybillStatus {
  Set<WorkAction> get allowedActions => switch (this) {
        WaybillStatus.driverAssigned => {
            WorkAction.confirmSchedule,
            WorkAction.requestCancel,
          },
        WaybillStatus.scheduleConfirmed => {
            WorkAction.scanOutbound,
            WorkAction.requestReschedule,
          },
        WaybillStatus.loaded => {
            WorkAction.startWork,
            WorkAction.requestReschedule,
          },
        WaybillStatus.working => {
            WorkAction.completeWork,
            WorkAction.requestCancel,
          },
        _ => const {},
      };
}

UI가 상태 문자열을 직접 비교하지 않고 정책 객체나 Extension을 사용하면 여러 화면의 조건을 한곳에서 관리할 수 있다.

final canComplete = status.allowedActions.contains(WorkAction.completeWork);

FilledButton(
  onPressed: canComplete ? onComplete : null,
  child: const Text('작업 완료'),
)

표시 상태와 업무 상태를 분리한다

서버 상태를 그대로 화면 문구로 쓰면 여러 서비스 유형에서 어색해진다. 같은 completed라도 설치는 “설치 완료”, 픽업은 “픽업 완료”, 회수는 “회수 완료”로 표시해야 한다.

String displayLabel({
  required WaybillStatus status,
  required ServiceType serviceType,
}) {
  return switch ((status, serviceType)) {
    (WaybillStatus.completed, ServiceType.installation) => '설치 완료',
    (WaybillStatus.completed, ServiceType.pickup) => '픽업 완료',
    (WaybillStatus.completed, ServiceType.collection) => '회수 완료',
    (WaybillStatus.working, _) => '작업 중',
    _ => '처리 중',
  };
}

부분 완료

주문과 운송장이 1:N이면 전체 완료를 Boolean으로 저장하지 않는다.

완료 수량 = completed waybill count
전체 수량 = active waybill count

0개 완료       → 진행 전
일부 완료      → 부분 완료
전체 완료      → 완료

서버가 계산한 집계 값을 내려주되, 원본 운송장 상태가 진실의 원천이어야 한다.

상태 설계 체크리스트

  • 상태 이름에 화면 문구가 섞이지 않았는가?
  • 주문·운송장·배정 상태의 주체가 분리됐는가?
  • 가능한 전이와 금지된 전이가 문서화됐는가?
  • 부분 완료와 재작업을 표현할 수 있는가?
  • 취소와 재약속 이후 새 Assignment 관계가 남는가?
  • 이벤트 이력으로 누가 언제 변경했는지 추적 가능한가?
  • 앱과 웹이 같은 전이 규칙을 사용하는가?

관련 문서

목록으로 돌아가기

다른 게시글

#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 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.