주문 도메인의 주요 작업 요약

• 주문에서는 물품을 수령할 업체가 공급업체에게 요청을 보내는 것만 고려한다.
• 주문 도메인에서는 다음의 작업을 수행한다.
  • 본격적으로 배송을 시작하기 전 공급업체, 수령업체, 주문상품 및 재고를 확인한다.
  • 배송 도메인에서 로직을 진행하기 위해 필요한 출발지(공급업체), 도착지(수령업체)에 관한 데이터를 구성하는 전처리 작업을 수행한다.
  • 사용자의 권한이 허브관리자 또는 마스터 관리자일 경우, 주문상태를 기반으로 주문 프로세스의 진행 과정을 제어하고, 취소된 주문 내역에 관한 삭제를 수행한다.

---

주문 엔티티

• 주문 엔티티는 다음의 필수 정보를 포함해야 한다.
  • 공급업체ID, 수령업체ID(요청업체), 상품ID, 수량, 배송ID, 요청사항
• 주문 엔터티 1개당 1가지 품목을 다룬다. → 주문과 상품은 1:1 관계
• 주문 엔터티의 필드는 다음과 같이 구성한다.

  • 주문 엔티티 필드 구성

    • ‘비고’의 내용이 없는 필드일 경우, 해당 필드는 엔티티와 DB 모두 사용

    컬럼명	타입	제약 조건	설명	비고
    order_id	UUID	PK	주문ID
    supplier_id	UUID	NOT NULL	공급업체ID
    supplier_name	VARCHAR(100)	NOT NULL	공급업체명
    supplier_hub_id	UUID	NOT NULL	공급업체 담당 허브ID	배송에서의 출발지 허브에 해당 (모든 업체는 항상 허브ID를 보유)
    supplier_hub_name	VARCHAR(50)	NOT NULL	공급업체 담당 허브명
    supplier_hub_address	VARCHAR(255)	NOT NULL	공급업체 담당 허브 주소	DB에도 저장 (주문은 주문 당시 데이터를 저장)
    receiver_id	UUID	NOT NULL	수령업체ID	주문 요청 업체
    receiver_name	VARCHAR(100)	NOT NULL	수령업체명
    receiver_address	VARCHAR(255)	NOT NULL	수령업체 주소	DB에도 저장 (주문은 주문 당시 데이터를 저장)
    receiver_hub_id	UUID	NOT NULL	수령업체 담당 허브ID	배송에서의 도착지 허브에 해당
    receiver_hub_name	VARCHAR(50)	NOT NULL	수령업체 담당 허브명
    receiver_hub_address	VARCHAR(255)	NOT NULL	수령업체 담당 허브 주소	DB에도 저장
    requirements	VARCHAR(255)	NOT NULL	요구사항	물품을 수령할 업체의 VO
    item_id	UUID	NOT NULL	상품ID
    item_name	VARCHAR(255)	NOT NULL	상품명
    quantity	INT	NOT NULL	주문수량
    item_number	INT	NOT NULL	상품순번	기본값은 1
    status	ENUM	NOT NULL (기본값은 PENDING)	주문상태	PENDING, WAIT_TO_APPROVAL, ACCEPTED, ON_DELIVERY, CANCELLED, COMPLETED 중에서 택1
    hub_manager_id	UUID	NULL	허브관리자ID	주문을 승인한 허브관리자의 ID • 주문 승인 단계에서 허브관리자ID를 저장 • 권한이 HUB인, 로그인한 사용자의 UUID
    hub_manager_name	VARCHAR(50)	NULL	허브관리자명	주문을 승인한 허브관리자의 이름 • 권한이 HUB인, 로그인한 사용자의 이름
    delivery_id	UUID	NULL	배송ID	• 주문 → 배송 이벤트로 배송 엔티티를 생성 • 배송 엔티티 생성 직후 발생한 배송 → 주문 이벤트를 통해 전달받은 배송ID를 저장
    created_at	TIMESTAMP	NOT NULL	생성일시	BaseEntity의 필드 사용
    created_by	UUID	NOT NULL	생성자	BaseUserEntity의 필드 사용
    updated_at	TIMESTAMP	NULL	수정일시	BaseEntity의 필드 사용
    updated_by	UUID	NULL	수정자	BaseUserEntity의 필드 사용
    deleted_at	TIMESTAMP	NULL	삭제일시	BaseEntity의 필드 사용
    deleted_by	UUID	NULL	삭제자	BaseUserEntity의 필드 사용
    version	INT		버전(주문상태 정합성 관리용)

---

주문 CRUD 관련

• 주문 엔티티에 관한 CRUD 기능과 검색 기능은 다음의 사항을 고려하여 구현한다.
  • 주문 생성
    • 주문이 생성되면 주문한 상품의 재고가 감소한다.
    • 주문하려는 상품의 재고가 부족하다면 주문에 실패한다.
    • 주문 엔터티가 생성되면 배송, 배송 경로 기록 엔터티도 생성되어야 한다.
  • 주문 삭제
    • 허브관리자가 주문 삭제를 진행할 경우, 본인이 처리 중인 주문만 삭제 가능 (주문 삭제 권한 확인 시, 허브관리자의 권한뿐만 아니라 주문 엔티티에 저장된 허브관리자ID에 관한 대조도 수행한다.)
    • 주문 엔티티 삭제 시 delete_at, deleted_by를 이용하여 논리적 삭제를 진행한다.
    • 주문 삭제는 허브관리자에 의해 주문이 취소되거나, 주문에 관한 롤백을 진행할 때만 수행한다.
    • 주문 삭제는 주문상태가 CANCELLED인 주문 엔티티를 대상으로 수행한다.
  • 주문 조회 및 검색
    • 모든 조회 및 검색 시 deleted_at 필드가 null인 데이터만을 대상으로 처리한다.
    • 검색 기능에는 검색 조건 설정 및 정렬 기능이 추가되어야 한다.
      • 검색 시 10, 30, 50건 기준으로 페이지에 노출되어야 하며, 그 이외의 건수가 입력될 경우 10건을 조회하도록 고정한다.
      • 정렬은 기본적으로 생성일순, 수정일순을 기준으로 삼는다.
  • 주문 CRUD 및 검색에 관한 권한 관리

    • 생성: 모든 로그인한 사용자(주문자 포함) 가능

    • 수정: 마스터 관리자와 해당 주문 처리를 담당하는 허브 관리자만 가능

    • 조회 및 검색: 모든 로그인 사용자가 가능, 단, 주문자 본인은 자신의 주문만 조회 가능

      	생성	수정	삭제	조회 및 검색
      마스터 관리자	O	O	O	O
      허브 관리자	O	O (담당 허브)	O (담당 허브)	O (담당 허브)
      배송 담당자	O	X	X	O (본인 주문)
      업체 담당자	O	X	X	O (본인 주문)

---

주문 프로세스 전반부 - 주문의 유효성 확인

• PENDING: 주문 대기

  • 주문-업체 & 주문-상품: FeignClient 사용 → 주문 서비스에서 업체 조회, 상품 단건 조회 API 호출

    • 공급업체, 수령업체, 상품이 삭제되지 않고 존재하는지 확인
    • 조회한 공급업체, 수령업체, 상품 중 하나라도 유효하지 않으면 예외 발생 후 종료
      • 업체, 상품 조회 API를 사용 → 업체, 상품이 존재하는 경우 해당 업체 엔티티를 반환 (조회한 업체 엔터티를 주문 도메인에서 재구성)
    • 조회한 공급업체, 수령업체, 주문상품에 관해서는 다음의 유효성 검사를 추가적으로 진행
      • 공급업체ID와 수령업체ID가 같으면 잘못 선택된 것으로 간주하여 예외 발생 후 종료
      • 공급업체ID의 업체타입이 SUPPLIER가 아니거나, 수령업체의 업체타입이 RECEIVER가 아닐 경우 예외 발생 후 종료
      • 주문상품의 업체ID가 공급업체ID와 다르면 예외 발생 후 종료
    • 위 작업은 업체의 도메인 로직을 기반으로 주문 서비스 로직에서 수행
    • 공급업체, 수령업체, 상품이 모두 확인되면 다음 정보를 바탕으로 주문 엔터티를 생성
      • 공급업체VO: 공급업체ID, 공급업체명, 공급업체허브ID, 공급업체 허브명, 공급업체 허브 주소
      • 수령업체VO: 수령업체ID, 수령업체명, 수령업체주소, 수령업체허브ID, 수령업체 허브명, 수령업체 허브 주소, 주문요청사항
      • 주문상품VO: (주문)상품ID, 상품명, 주문수량, 상품순번
      • 주문상태(PENDING)
    • 업체는 반드시 특정 허브에 소속되므로, 공급업체와 수령업체, 상품이 모두 존재하면 주문 엔티티를 생성
    • 허브주소는 DB 테이블에 저장

  • 주문 → 허브 방향 이벤트 발송

    • 주문 → 허브 방향 이벤트 메시지 구성
      • 주문ID, (공급업체)허브ID, (공급)업체ID, 상품ID(아이템ID), 주문수량, 주문상태
        • 허브ID, 공급업체ID, 상품ID
          • 허브재고 엔티티를 식별하기 위해 모두 필요
        • 주문상태
          • 허브재고 엔티티 내부에서 재고 차감 로직을 진행할 때, 수신한 이벤트의 주문상태가 PENDING 인지를 확인할 때 사용
        • 주문수량
          • 주문수량에 따라 허브재고 엔티티의 재고를 차감
        • 허브 도메인에서 이벤트를 수신하면, 전달한 이벤트의 주문수량과 허브 재고를 비교
          • 허브의 재고가 충분할 경우, 허브 재고 차감 로직 수행 후 허브 → 주문 방향 이벤트 발송
          • 허브의 재고가 충분하지 않을 경우, 허브 → 주문 방향 이벤트 발송 (즉, 허브 재고가 주문한 상품의 수량을 충족하는지에 관계없이 허브 → 주문 이벤트 발송은 무조건 수행하게 됨)

  • 허브 → 주문 방향 이벤트 발송

    • 허브 → 주문 방향으로 발송할 이벤트 메시지는 다음의 필드를 포함
      • 주문ID(주문 → 허브 이벤트에서 허브 도메인이 수신했던 주문ID를 그대로 반환)
      • 허브ID
      • 허브재고ID
      • 주문수량(주문 → 허브 이벤트에서 허브 도메인이 수신했던 수량 그대로 반환)
      • 허브의 재고에서 주문수량만큼 뺀 정수값
        • 주문 도메인에서 이벤트 수신 시, 이 값이 음수인지 아닌지로 주문 가능 여부를 판정
    • 허브에서 발송한 이벤트를 주문 도메인에서 수신하여 주문 상태를 전환해야 하기 때문에 이 과정이 필수
      • 허브의 재고를 차감했다면, 주문 도메인의 주문상태는 PENDING → WAIT_TO_APPROVAL 로 전환
      • 허브의 재고가 부족하다면 주문 도메인의 주문상태는 PENDING → CANCELLED로 전환

  • PENDING 상태에서는 허브관리자가 주문 취소 API를 통해 수동으로 주문을 취소할 수 있으므로, 특정 주문 엔터티를 대상으로 주문상태를 변경할 때의 데이터 정합성을 보장하기 위해 주문 엔티티에 version을 추가

• WAIT_TO_APPROVAL
  • 공급업체, 수령업체 확인 및 주문상품 수량만큼의 허브 재고 차감 완료
  • 허브관리자의 승인만 기다리는 상태(주문 프로세스 종료)

---

주문 프로세스 후반부 - 주문 승인 및 배송

• 허브관리자가 직접 주문 승인 API를 요청하면서 주문 프로세스의 후반부 작업이 시작됨
• ACCEPTED: 아래 작업을 모두 완수해야 주문 승인 완료
  • 허브관리자의 주문 승인 API 호출 시, 승인된 주문 엔티티의 주문상태 전환
    • 주문상태는 WAIT_TO_APPROVAL → ACCEPTED 로 전환
  • 주문상태 변경 직후 주문 → 배송 방향으로 이벤트를 발송
    • 주문 → 배송 방향 이벤트 메시지에 포함할 항목은 아래와 같음
      • 주문ID
      • 공급업체허브ID, 공급업체허브주소
      • 수령업체허브ID, 수령업체허브주소, 수령업체ID, 수령업체명, 수령업체주소, 수령업체 슬랙ID
      • 허브관리자ID
    • 배송 엔티티에서는 수신한 이벤트 메시지의 데이터를 배송 엔티티 생성에 활용
  • 배송 엔티티 생성 직후 배송 → 주문 방향 이벤트 발생
    • 배송 → 주문 방향으로 전송할 이벤트는 다음의 필드들로 구성
      • 주문ID, 출발지ID, 목적지ID, 배송ID, 배송상태
    • 수신한 배송ID를 주문 엔티티의 배송ID 필드에 저장
    • 수신한 출발지ID가 공급업체허브ID와 같고, 배송상태가 ‘허브대기중’이라면 주문 엔티티의 주문상태를 전환
      • 주문상태는 ACCEPTED → ON_DELIVERY 로 전환
• ON_DELIVERY: 배송중(주문 프로세스의 일부로서의 상태에 해당
  • 배송 중 오류로 인해 배송 로직에 관한 롤백을 수행할 때도, 배송 → 주문 방향으로 롤백 이벤트 발생
• COMPLETED: 주문 처리 완료
  • 배송 로직을 정상적으로 완료하면 배송 → 주문 방향 이벤트 발생
    • 배송 → 주문 방향으로 전송할 이벤트는 다음의 필드들로 구성
      • 주문ID, 출발지ID, 목적지ID, 배송ID, 배송상태
    • 수신한 목적지ID가 수령업체ID와 같고, 배송상태가 ‘배송완료’일 때 주문상태를 전환
      • 주문상태는 ON_DELIVERY → COMPLETED로 전환

---

주문 취소/주문 진행 중 롤백

• CANCELLED: 주문 취소

  • 주문 취소 enum을 세분해야 할 필요가 있을 경우, enum 추가 예정 (현재는 일단 CANCELLED로 통일)
  • 주문상태가 CANCELLED 인 주문은 해당 주문을 담당했던 허브관리자가 삭제

• 다음과 같은 상황이 발생하면 주문에 관한 롤백을 수행하며, 주문상태를 CANCELLED로 전환

  • 허브 재고 부족
  • 배송 로직 진행 중 오류 발생
  • 허브관리자의 주문 취소

• 허브 재고 부족

  • 허브 → 주문 방향으로 이벤트 발송
  • 이벤트 메시지는 아래와 같이 구성
    • 주문ID
    • 공급업체허브ID
    • 허브재고ID
    • 상품ID
    • 주문수량
    • 허브의 재고에 주문수량만큼 더한 정수값

• 배송 로직 진행 중 오류 발생(아래 순서대로 진행)

  1. 배송 내부의 롤백 로직을 수행한 직후, 배송 → 주문 방향 이벤트 메시지 발송

     • 이벤트 메시지 구성
       • 주문ID, 출발지ID, 목적지ID, 배송ID, 배송상태
       • 이때의 출발지ID, 목적지ID는 배송 엔터티의 출발지ID, 목적지ID에 해당
     • 주문 도메인에서는 이벤트 수신 직후 주문상태를 ON_DELIVERY → CANCELLED로 전환

  2. 주문 → 허브 방향 이벤트 발송

     • 이벤트 메시지 구성: 주문ID, (공급업체)허브ID, (공급)업체ID, 상품ID(아이템ID), 주문수량, 주문상태
       • 허브ID, 업체ID, 상품ID
         • 허브재고 엔티티를 식별하기 위해 모두 필요
       • 주문상태
         • 허브재고 엔티티에서 재고 복원 로직을 진행할 때, 수신한 이벤트의 주문상태가 CANCELLED일 때만 재고를 복원하도록 제한하기 위해 사용
       • 주문수량
         • 주문상태가 CANCELLED 일 때 주문수량만큼 허브의 재고를 복원

• 허브 관리자의 주문 취소

  • 주문상태가 PENDING, WAIT_TO_APPROVAL일 때만 허브관리자가 주문 취소 API를 통해 수동으로 주문 취소 가능
  • 주문상태 변경 직후 주문 → 허브 방향 이벤트 발송
    • 이벤트 메시지 구성: 주문ID, 허브ID, 공급업체ID, 상품ID, 주문수량, 주문상태
      • 허브ID, 공급업체ID, 상품ID
        • 허브재고 엔티티를 식별하기 위해 모두 필요
      • 주문상태
        • 허브재고 엔티티에서 재고 복원 로직을 진행할 때, 허브 도메인이 수신한 이벤트의 주문상태가 CANCELLED인지를 확인할 때 사용
      • 주문수량
        • 주문상태가 CANCELLED 일 때 주문수량만큼 허브의 재고를 복원