본문으로 건너뛰기
REPL WorksREPL Works
Menu

SHOWCASE SPECIFICATION

REPL WMS

REPL WMS는 플레이오토 주문을 피킹, 바코드 검수, CJ 송장 출력까지 잇고 상품과 박스 재고를 이력으로 맞추는 창고 관리 시스템입니다.

1. 개요 (Overview)

REPL WMS 랜딩페이지

REPL WMS는 온라인 쇼핑몰과 오프라인 매장에서 함께 판매하는 회사의 창고 관리 시스템(WMS)입니다. 자기 창고에서 직접 주문을 출고하는 한 회사를 위해 만들었고, 한 번 설치하면 한 회사가 사용합니다.

PlayAuto에서 내려받은 주문서 파일과 CJ 송장 PDF를 함께 올리면 주문 줄이 우리 회사 상품과 연결됩니다. 주문서를 출력해 피킹하고, 바코드 스캐너로 검수·포장한 뒤 CJ 송장 라벨을 출력합니다. 검수가 끝나면 상품과 박스 재고가 줄고, 모든 변동이 이력으로 남습니다.

"주문은 파일로 들어오고, 재고는 이력으로 남습니다. 출고가 끝난 뒤에도 왜 수량이 바뀌었는지 추적할 수 있어야 합니다."

REPL WMS는 아직 판매하지 않습니다. wms.repl.net에서 공용 데모 계정(demo@repl.net / 1234)으로 모든 화면을 관리자로 사용해 볼 수 있습니다. 데모 데이터는 인스턴스가 시작할 때마다 샘플 데이터로 초기화됩니다.

2. 사용된 표준 문서 (Documents Used)

REPL WMS 저장소는 비공개이며, REPL Works 표준 문서와 공통 규칙으로 제품 정의, 구현 제약, 아키텍처, 작업 순서를 관리합니다.

  • PRODUCT_SPEC.md: 주문 가져오기, 검수, 재고, 발주, 오프라인 판매의 요구사항과 오류 조건
  • TECH_STACK.md: Laravel, Nova, Livewire, 데이터베이스, 테스트와 배포 제약
  • ARCHITECTURE.md: 구성 요소의 책임 경계, 재고 원장, 상태 기계와 불변식
  • TASKS.md: 37개 구현 작업과 수락 기준
  • AGENTS.md: AI 에이전트가 따르는 문서 순서와 작업 규칙

사람이 읽는 .replworks/docs/IDEAS.md에는 이 제품을 다시 만들게 된 배경과 서비스화 판단이 남아 있습니다. 코딩형 AI는 이 문서를 요구사항으로 읽지 않습니다.

3. 적용 워크플로 (Workflow Usage)

대화형 AI (주문·검수·재고 규칙 정의)
표준 문서 (제품·기술·아키텍처·작업)
코딩형 AI (TASK 단위 구현)
Human Review (데모 인스턴스와 브라우저 검증)
Release (v1.0.7)

대화형 AI와 주문·검수·재고 규칙을 정리해 PRODUCT_SPEC.md에 남기고, TECH_STACK.md와 ARCHITECTURE.md에서 구현 제약과 구성 요소의 책임을 확정했습니다. 코딩형 AI는 TASKS.md의 작업을 하나씩 구현하고, 사람은 데모 인스턴스와 실제 브라우저에서 동작을 확인한 뒤 릴리즈했습니다. 2026-11-04 기준 37개 작업을 모두 마쳤고 v1.0.7을 배포했습니다.

  • 외부 형식은 경계로 다룹니다. PlayAuto 주문서 파일과 CJ 송장 PDF는 우리가 제어하지 않는 입력입니다. 파일을 읽는 코드는 실제 형식을 기준으로 검증하고, 상품 코드를 찾지 못한 주문 줄은 따로 모아 고칠 수 있게 합니다.
  • 바코드 스캐너는 키보드 입력입니다. 스캐너가 값을 입력하고 Enter를 누르는 방식이므로, Laravel Dusk의 실제 브라우저 E2E 테스트로 검수 화면의 스캔과 저장을 검증했습니다.
  • 실패하면 아무것도 바뀌지 않습니다. 주문 가져오기, 검수 저장, 임시 저장 취소, 반품, 상태 변경은 각각 하나의 원자적 작업입니다. 중간에 실패하면 주문과 재고는 이전 상태로 남습니다.

4. 사용 기술 (Tools Used)

  • PHP 8.4, Laravel 12: 애플리케이션과 관리 화면
  • Laravel Nova 5.7.7: 관리 화면의 목록, 검색, 상세, 생성, 수정
  • Livewire, Volt, Alpine.js: 로그인 화면과 바코드 검수 화면
  • MySQL, SQLite: 배포 인스턴스와 로컬 개발·테스트 데이터베이스
  • maatwebsite/excel: PlayAuto 주문서 파일(xlsx, xls, csv) 읽기
  • mPDF, picqer/php-barcode-generator: 주문서·송장·영수증·바코드 시트 PDF와 바코드 이미지
  • Scramble: 검수 화면이 사용하는 웹 API 문서
  • Sentry, Laravel Telescope: 오류 추적과 개발 환경 관찰
  • PHPUnit, Laravel Dusk, Laravel Pint: 단위·기능 테스트, 실제 브라우저 E2E 테스트, 코드 스타일
  • Docker, GHCR, Coolify, GitHub Actions: 이미지 빌드, 배포와 롤백

5. 재고 정확성 설계 (Inventory Correctness)

재고는 이 제품의 핵심입니다. 상품 재고와 박스 재고는 입고, 출고, 반품, 오프라인 판매, 수동 조정으로 계속 바뀌므로, 현재 수량만 저장하면 왜 그 수량이 되었는지 설명할 수 없습니다.

  • 원장이 재고를 소유합니다. 모든 재고 변경은 상품 이력 또는 박스 이력 한 건을 만들고, 현재 재고는 그 이력의 합과 같아야 합니다. 이 불변식을 어기는 코드는 재고를 바꿀 수 없습니다.
  • 정정은 삭제가 아니라 취소입니다. 잘못된 이력은 수정하거나 지우지 않고, 반대 수량의 취소 이력을 새로 만듭니다. 같은 이력을 두 번 취소할 수 없습니다.
  • 음수 재고를 허용합니다. 실제 창고 수량과 시스템 수량이 다를 때 출고를 거부하면 주문은 막히고 차이는 숨겨집니다. 음수를 허용하고 이력으로 차이를 드러냅니다.
  • 겹치는 저장을 막습니다. 같은 주문의 검수 저장과 임시 저장 취소는 한 번에 하나씩 처리합니다. 두 저장이 동시에 들어와도 재고를 두 번 빼지 않습니다.
  • 주문 단위로 계산합니다. 검수 저장은 주문 줄별로 이미 뺀 수량과 새로 확정한 수량의 차이만 재고에 반영합니다. 부분 완료 후 완료해도 총 차감은 한 번입니다.

6. 배포와 운영 (Release & Operations)

GitHub Release → linux/arm64 이미지 빌드 → GHCR → Coolify 배포
문제가 생기면 → rollback workflow

배포 인스턴스는 MySQL을 쓰고, 웹 서버, 큐 워커, 스케줄러를 한 컨테이너에서 실행합니다. GitHub Actions가 릴리즈 태그로 이미지를 빌드해 GHCR에 올리고 Coolify에 배포합니다. 롤백이 필요하면 이전 릴리즈 태그로 되돌립니다.

데모 인스턴스는 시작할 때마다 샘플 데이터로 초기화하고 데모 계정을 다시 만듭니다. 운영 인스턴스에는 데모 계정과 샘플 데이터가 생기지 않습니다. 화면은 한국어와 영어를 제공하고 기본 언어는 한국어입니다.

7. 학습된 레슨 (Lessons Learned)

재고의 진실은 현재 숫자가 아니라 이력의 합입니다. 현재 수량만 저장하면 검수, 반품, 취소가 겹칠 때 왜 그 수량이 되었는지 설명할 수 없습니다. 모든 변경을 이력으로 남기고 그 합이 현재 재고가 되게 하면, 재고가 어긋나도 원인을 찾을 수 있습니다.

실패했을 때 아무것도 바뀌지 않아야 합니다. 주문 가져오기와 검수 저장을 원자적 작업으로 만들고, 실패하면 이전 상태로 남게 했습니다. 실패 경로를 먼저 정하면 정상 경로도 단순해집니다.

외부 파일 형식은 제품의 경계입니다. PlayAuto 주문서와 CJ 송장 PDF는 우리가 바꿀 수 없으므로, 파일을 읽는 코드와 그 결과를 검증하는 테스트를 경계로 분리했습니다.

데모 인스턴스도 제품의 일부입니다. 판매하지 않는 제품도 공용 데모로 전체 화면을 보여 줄 수 있어야 하고, 데모 데이터는 매번 같은 상태에서 시작해야 합니다.