물류 통합 관리 포털

외부 OMS/WMS(Packiyo) API·Webhook 연동을 중심으로 주문·입고·재고·배송 4대 핵심 플로우를 하나의 고객사 포털에 통합하는 물류 관리 시스템을 React + Express + PostgreSQL 기반으로 설계·구현합니다.

Webhook 이벤트 정규화 파이프라인 구현외부 배송사·Packiyo 상태 코드를 내부 표준 스키마로 매핑하는 정규화 레이어 설계, 큐 기반 비동기 처리 구조 적용

재고 실시간 브로드캐스트 구조 설계Socket.io SKU 단위 구독 모델로 다중 클라이언트 재고 동기화 구현, 가용/예약/안전 재고 분리 집계 뷰 설계

PO 상태 머신 및 불일치 검증 로직 구축PostgreSQL 트랜잭션 기반 PO 단계 전이 검증, 예상-실입고 수량 차이 자동 계산 로직 구현

서비스 타입Web

업종물류 시스템

기술 스택

ReactTypeScriptTailwind CSSNode.jsExpressPostgreSQLPrismaSocket.ioReact Query

주요 기능

주문 관리
PO·입고 관리
실시간 재고 관리
배송·Tracking 관리

Overview

프로젝트 개요

범위: 개발, 디자인, 기획

외부 OMS/WMS(Packiyo) API·Webhook 연동을 중심으로 주문·입고·재고·배송 4대 핵심 플로우를 하나의 고객사 포털에 통합하는 물류 관리 시스템을 React + Express + PostgreSQL 기반으로 설계·구현합니다. 반응형 레이아웃으로 데스크톱과 태블릿 모두 대응하며, 좌측 리스트-우측 상세 패널 구조와 요약 통계 상태바로 운영 담당자가 대량 레코드를 빠르게 훑고 즉시 상세를 확인할 수 있는 대시보드형 흐름을 구현합니다.

요구사항 정의

프로젝트 핵심 과제

프로젝트 진행 시 해결한 핵심 기술 과제입니다.

다수 배송사의 서로 다른 상태 코드 체계를 하나의 표준 스키마로 정규화하는 매핑 테이블 설계

가용/예약/안전 재고를 구분해 실시간으로 집계하면서도 조회 성능을 유지하는 쿼리 설계

Packiyo Webhook 재전송·중복 수신 시 멱등성을 보장하는 이벤트 처리 구조 설계

PO 진행 중 동시 수정 요청이 발생해도 상태 정합성을 유지하는 트랜잭션 격리 수준 설계

구현 내용

핵심 기능 상세

핵심 기능 1

주문 관리

상태·기간·스토어별로 주문을 필터링해 목록을 조회하고, 상세 화면에서 라인아이템·이력을 확인할 수 있습니다

핵심 기능 2

PO·입고 관리

입고 요청(PO)을 등록하고 예정/진행중/완료 단계별 현황과 수량 불일치 여부를 확인할 수 있습니다

핵심 기능 3

실시간 재고 관리

가용/예약/안전 재고를 구분해 조회하고, 재고 변동 이력과 부족 알림을 확인할 수 있습니다. WebSocket으로 재고 변동을 실시간 push하고, 안전 재고 임계값 이하로 떨어지면 알림 배지를 즉시 표시합니다

핵심 기능 4

배송·Tracking 관리

배송 상태와 운송장 번호를 조회하고 배송사 트래킹 페이지로 바로 이동할 수 있으며, 지연 건은 별도 표시됩니다

구현 과정

프로젝트 진행 단계

STEP 1

물류 도메인 분석 및 ERD 설계

주문·PO·재고·배송 4대 엔티티와 Packiyo 연동 스키마 설계, PostgreSQL 테이블 22개 정의

STEP 2

Packiyo Webhook 어댑터 및 API 개발

Express 기반 REST API 구현, Webhook 수신-정규화-큐 적재 파이프라인 구축

STEP 3

재고·배송 실시간 동기화 모듈 개발

Socket.io 네임스페이스 설계, 재고 변동 브로드캐스트 및 배송 지연 감지 스케줄러 구현

STEP 4

마스터-디테일 UI 개발

React 기반 리스트-상세 패널 16개 화면 구현, React Query 캐싱 전략 적용

STEP 5

통합 테스트 및 데이터 정합성 검증

PO 상태 전이·재고 불일치 로직 테스트 케이스 작성, API-프론트엔드 통합 검증

프로젝트 성과

주요 성과