제설자재관리시스템 (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 기준:

1. Node.js 22.5 이상 설치 (node -v로 확인)
2. 프로젝트 폴더에서 install.bat 더블클릭 → 처음 한 번만 실행 (패키지 설치, 샘플 데이터 생성, 프론트엔드 빌드)
3. start.bat 더블클릭 → 서버 실행. 콘솔에 이 PC의 IP 주소(예: 192.168.0.23)가 표시됩니다
4. 같은 사무실 네트워크의 다른 PC/휴대폰 브라우저에서 http://<표시된 IP>:4000 접속
   • 접속이 안 되면 Windows 방화벽에서 4000번 포트(TCP) 인바운드를 허용해야 합니다
   • start.bat 창을 닫으면 서버가 꺼집니다. 계속 켜두려면 창을 최소화한 채로 그 PC를 켜두세요
5. 다음부터 껐다 켤 때는 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 파일 저장 위치

향후 확장 아이디어

• 발주 요청 → 사무실 승인 → 입고 처리로 이어지는 승인 워크플로우
• 부족재고 알림 푸시/문자 발송
• 창고별 담당자 다중 배정, 감사 로그