제설자재관리시스템 (Snow Material Management System)
현장 창고 담당자와 사무실 담당자가 함께 사용하는 제설자재 재고/입출고 관리 웹앱(PWA)입니다.
구성
- backend/: Node.js + Express + SQLite(Node.js 내장
node:sqlite 모듈) API 서버 — 별도 컴파일 도구 없이 npm install만으로 설치됩니다
- frontend/: React + Vite 기반 PWA (설치형 웹앱, 오프라인 입력 지원)
Node.js 버전: 22.5 이상 필요 (내장 SQLite 모듈 사용). node -v로 확인하세요. 최신 LTS 버전 설치를 권장합니다.
핵심 설계
- 입출고 원장 방식 재고 계산: 재고 수량을 별도로 저장하지 않고, 모든 입출고 거래(
transactions)의 합계로 현재 재고를 계산합니다. 여러 창고에서 오프라인으로 동시에 기록해도 서버에 반영될 때 값이 충돌하지 않습니다.
- 오프라인 입력: 프론트엔드는 PWA로 설치 가능하며, 네트워크가 끊긴 상태에서 입출고를 등록하면 브라우저 IndexedDB에 임시 저장됩니다. 온라인 상태가 되면 자동으로 서버와 동기화됩니다(
client_id 기반 중복 방지).
- 로그인 없이 전체 공개: 별도 계정·로그인 없이 링크에 접속하면 누구나 모든 화면(대시보드, 입출고 등록, 재고 현황, 이력 조회, 지사·창고·품목·비축기준 관리)을 바로 사용할 수 있습니다. 입출고 등록 시 "담당자" 이름은 자유 텍스트로 직접 입력하며, 브라우저에 마지막 입력값이 저장되어 있어 다음에 다시 입력할 필요는 없습니다.
- 본부 > 지사 > 창고 계층 구조: 창고는 반드시 하나의 지사에 소속되며, 같은 창고명이라도 지사가 다르면 별개로 관리됩니다(예: 충주지사의 "연풍IC"와 상주지사의 "연풍IC"는 서로 다른 창고). 입출고 등록·재고 현황·이력 조회 화면 모두 지사 → 창고 순으로 선택/필터링합니다.
- 품목의 형태(톤백/개포/염수) 구분과 톤 환산: 같은 품목(예: 소금(제설용))도 톤백·개포처럼 형태별로 나누어 입출고를 기록합니다. 각 형태에는 "환산계수"(1단위가 몇 톤인지)가 있어, 재고 합계는 형태별 수량 × 환산계수를 모두 더해 톤 단위로 계산합니다. 예: 소금 톤백 5톤 + 개포 40포대(포대당 0.02톤) = 5.8톤.
- 지사 단위 비축기준: 최소 재고 기준(비축기준)은 창고가 아닌 지사 단위로 설정합니다. 지사 소속 모든 창고의 재고를 톤으로 합산한 값을 비축기준과 비교해 부족 여부를 판단하며, 재고 현황 화면에 지사 합계가 별도로 표시됩니다.
- 전환(형태 변경, 창고/지사 간 이동 포함): 입출고 유형에 "전환"이 있어, 같은 품목의 형태를 바꿔 기록할 수 있습니다(예: 톤백으로 입고된 소금을 현장에서 개포해 소분 보관, 또는 염화칼슘 톤백을 염수로 제조). 전환 전/후 두 건의 거래로 기록되며(감소 + 증가), 톤 환산 총량은 변하지 않아 전체 합계에는 영향이 없습니다. 목적지는 전환 전과 같은 창고가 기본값이지만, "목적지 지사"·"목적지 창고"를 별도로 선택해 다른 창고나 다른 지사로도 옮길 수 있습니다. 창고가 아닌 현장에 설치된 염수 분사 장비로 보내는 경우를 위해 지사별로 "현장염수분사장치"라는 가상 창고도 선택할 수 있습니다.
- 사용(예비살포/본살포) 자동계산: 사용 등록은 살포 유형(예비살포/본살포)과 대수만 입력하면 염화칼슘·소금 사용량을 자동 계산합니다. 염화칼슘은 항상 염수(리터)에서 고정량으로 차감됩니다(예비살포 1대 = 염수 1,500리터, 본살포 1대 = 염수 3,000리터). 소금은 예비살포 1대 = 4톤, 본살포 1대 = 8톤 기준이며, 톤백/개포 중 어느 형태에서 차감할지는 화면에서 선택합니다.
- 지사 표시 순서 고정: 지사 목록은 가나다순이 아니라 진천지사 → 제천지사 → 충주지사 → 보은지사 → 엄정지사 → 상주지사 순으로 고정 표시됩니다(재고 현황·이력 조회·창고 관리·지사 관리 등 전체 화면 공통). "지사 관리"에서 새 지사를 추가하면 항상 마지막 순서로 붙습니다.
실행 방법
방법 A. 사무실 PC 한 대에서 상시 실행 (명령어 없이 링크로 접속)
개발용으로 백엔드(4000번 포트)와 프론트엔드(5173번 포트)를 따로 띄우는 대신, 프론트엔드를 빌드해두면 백엔드 서버 하나가 화면(웹앱)과 API를 모두 제공합니다. 사무실의 PC(또는 서버) 한 대에 설치해서 켜두면, 같은 사내망의 다른 PC·휴대폰은 브라우저에 그 PC의 주소만 입력하면 접속됩니다.
Windows 기준:
- Node.js 22.5 이상 설치 (
node -v로 확인)
- 프로젝트 폴더에서
install.bat 더블클릭 → 처음 한 번만 실행 (패키지 설치, 샘플 데이터 생성, 프론트엔드 빌드)
start.bat 더블클릭 → 서버 실행. 콘솔에 이 PC의 IP 주소(예: 192.168.0.23)가 표시됩니다- 같은 사무실 네트워크의 다른 PC/휴대폰 브라우저에서
http://<표시된 IP>:4000 접속
- 접속이 안 되면 Windows 방화벽에서 4000번 포트(TCP) 인바운드를 허용해야 합니다
start.bat 창을 닫으면 서버가 꺼집니다. 계속 켜두려면 창을 최소화한 채로 그 PC를 켜두세요
- 다음부터 껐다 켤 때는
install.bat 없이 start.bat만 실행하면 됩니다 (품목/코드가 바뀌었을 때만 다시 install.bat으로 재빌드)
이 방식은 별도 비용이 들지 않고 지금 당장 써볼 수 있지만, 그 PC가 꺼지거나 네트워크에서 벗어나면(예: 외부에서 접속) 사용할 수 없습니다. 나중에 클라우드에 배포해 외부에서도 고정 링크로 접속하게 바꿀 수도 있습니다(그때 다시 요청해 주세요).
방법 C. Vercel 배포 (무료, 외부에서 고정 링크로 접속 — 재고 데이터는 임시 저장)
이 저장소를 vercel.com에서 "Import Project"로 연결하면 vercel.json 설정에 따라 프론트엔드는 정적 사이트로, 백엔드(API)는 api/index.js를 통해 서버리스 함수로 자동 배포됩니다. 별도 설정 없이 그대로 배포하면 됩니다.
⚠️ 주의: Vercel의 서버리스 함수는 요청이 뜸해지면(콜드 스타트) 파일시스템이 초기화됩니다. 이 앱은 SQLite 파일을 서버 임시 저장공간(/tmp)에 저장하므로, 콜드 스타트마다 입력했던 재고 데이터가 사라지고 샘플 데이터로 리셋됩니다(첫 요청 시 자동으로 샘플 데이터가 채워집니다). 실제 재고를 계속 누적하려면 방법 A(사무실 PC) 또는 영구 디스크가 있는 클라우드(Render 등)를 사용하세요.
방법 B. 개발 모드 (수정하며 확인할 때)
백엔드:
cd backend
npm install
npm run seed # 최초 1회: 샘플 창고/품목 데이터 생성
npm start # http://localhost:4000
프론트엔드:
cd frontend
npm install
npm run dev # http://localhost:5173 (백엔드로 /api 프록시)
프로덕션 빌드 시:
npm run build
npm run preview
빌드 결과물(dist/)은 서비스워커가 포함된 PWA입니다. 방법 A처럼 백엔드가 직접 서빙하거나, 별도 정적 파일 서버(Nginx 등) 뒤에 배포하고 /api를 백엔드로 프록시해도 됩니다. 모바일 브라우저에서 접속 후 "홈 화면에 추가"로 설치할 수 있습니다.
샘플 데이터 (npm run seed 실행 시 생성)
충북본부 산하 6개 지사, 지사별 3~6개 창고(총 30개, 지사마다 "현장염수분사장치" 포함)가 생성됩니다.
| 지사 | 창고 |
|---|
| 진천지사 | 서청주IC, 지사, 일죽IC, 남이천IC, 마장휴게소, 현장염수분사장치 |
| 제천지사 | 지사, 단양영업소, 치악휴게소, 현장염수분사장치 |
| 충주지사 | 지사, 감곡IC, 괴산IC, 연풍IC, 현장염수분사장치 |
| 보은지사 | 지사, 문의IC, 화서IC, 남상주IC, 내서, 현장염수분사장치 |
| 엄정지사 | 지사, 서충주IC, 북진천IC, 현장염수분사장치 |
| 상주지사 | 연풍IC, 점촌함창IC, 지사, 선산IC, 현장염수분사장치 |
"현장염수분사장치"는 실제 창고가 아니라, 전환(형태 변경) 시 염화칼슘을 염수로 만들어 현장에 설치된 분사 장비로 보낼 때 목적지로 선택하는 가상 창고입니다.
관리 품목과 톤 환산계수:
| 품목 | 형태 | 단위 | 환산계수 | 기준 |
|---|
| 소금(제설용) | 톤백 | 톤 | 1 | |
| 소금(제설용) | 개포 | 톤 | 1 | 톤백을 개포해도 무게는 그대로 |
| 염화칼슘 | 톤백 | 톤 | 1 | |
| 염화칼슘 | 염수 | 리터 | 1/1935 (≈0.00051680) | 염화칼슘 1톤 → 염수 1,935리터 제조 기준 |
지사별 비축기준(톤):
| 지사 | 소금(제설용) | 염화칼슘 |
|---|
| 진천지사 | 3,150 | 294 |
| 제천지사 | 2,745 | 342 |
| 충주지사 | 2,376 | 228 |
| 보은지사 | 2,064 | 360 |
| 엄정지사 | 3,159 | 219 |
| 상주지사 | 1,911 | 132 |
비축기준은 "비축기준 관리" 화면, 환산계수·단위는 "품목 관리" 화면에서 언제든 직접 수정할 수 있습니다.
로그인이 없으므로 링크에 접속하는 모든 사람이 지사·창고 구성을 포함한 전체 화면을 바로 사용할 수 있습니다.
주요 화면
- 대시보드: 지사별 재고량 차트, 부족재고 알림, 최근 입출고 현황
- 입출고 등록: 유형(입고/사용/전환)을 먼저 고르고, 지사 → 창고를 선택하는 큰 버튼 위주의 현장 친화적 화면. 오프라인이어도 저장 가능. "담당자" 이름은 자유 텍스트로 입력하며 브라우저에 마지막 입력값이 저장됩니다
- 입고: 품목(염화칼슘/소금(제설용)) → 형태(톤백/염수, 톤백/개포) 2단계 선택 후 수량 입력
- 사용: 예비살포/본살포 선택 → 대수 입력. 염화칼슘은 염수(리터)로 고정 차감, 소금은 차감할 형태(톤백/개포)만 선택 (수량은 자동 계산)
- 전환: 전환 전/후 형태를 선택하고(기본값은 전환 전과 동일한 형태), 필요하면 목적지 지사·창고(현장염수분사장치 포함)를 소스와 다르게 지정해 형태 변경과 동시에 이동 가능
- 재고 현황: 지사 합계(톤 환산, 비축기준 대비 부족 여부)와 창고별 형태별 상세 재고
- 이력 조회: 지사/창고/유형/기간 필터로 입출고 이력 검색
- 지사/창고/품목/비축기준 관리: 마스터 데이터, 톤 환산계수, 지사별 비축기준
환경 변수 (백엔드)
| 변수 | 기본값 | 설명 |
|---|
PORT | 4000 | API 서버 포트 |
DATA_DIR | backend/data | SQLite 파일 저장 위치 |
향후 확장 아이디어
- 발주 요청 → 사무실 승인 → 입고 처리로 이어지는 승인 워크플로우
- 부족재고 알림 푸시/문자 발송
- 창고별 담당자 다중 배정, 감사 로그
