KOIN POS

한국기술교육대학교(코인) 근처 매장 사장님들을 위한 배달 전용 POS 데스크톱 애플리케이션입니다.

기술 스택

• Electron + electron-vite
• React + TypeScript
• Tailwind CSS v4
• React Router
• TanStack Query — 서버 상태(주문/매장 데이터) 관리, 폴링
• sonner — 토스트 알림
• electron-builder + electron-updater — 패키징, 자동 업데이트

폴더 구조

src/
  main/       # 메인 프로세스
  preload/    # 메인 ↔ 렌더러 브릿지
  renderer/
    src/
      pages/       # 라우트별 화면
      components/  # 도메인 컴포넌트
        ui/        # 범용 원자 컴포넌트
      apis/        # 도메인별 API 레이어
        apiClient.ts        # 공통 fetch 래퍼, 401 갱신, 에러 타입
          entity.ts    # 타입
          client.ts    # raw fetch 함수
          queries.ts   # useQuery 훅
          mutation.ts  # useMutation 훅
      hooks/      #toast 알림 훅
      lib/         # 순수 유틸/도메인 로직
      styles/      # 전역 CSS, 디자인 토큰
      assets/      # 이미지 등 정적 리소스
resources/    # 앱 아이콘 등 런타임 리소스
build/        # 패키징(설치 파일)용 아이콘·설정

환경 변수

루트에 .env.development, .env.production 파일 필요 (git에 포함 안 됨)

시작하기

설치

pnpm install

개발 서버 실행

pnpm dev

로컬 빌드 (설치 파일만 생성, 배포 아님)

pnpm build:win    # Windows
pnpm build:mac    # macOS
pnpm build:linux  # Linux

영수증 프린터 설정

• OS에 프린터와 드라이버를 설치한 뒤 앱의 설정 → 프린터 선택에서 출력 대상을 선택합니다. Linux에서는 CUPS 프린터 큐가 필요합니다.
• 용지 인쇄 가능 폭은 롤 전체 폭이 아닌 실제 인쇄 영역입니다. 80mm 롤의 72mm, 58mm 롤의 48mm는 예시이며 장비 사양에 맞게 직접 입력할 수 있습니다.
• 선택한 프린터와 프린터별 인쇄 가능 폭을 로컬에 저장합니다. 새 프린터는 폭 설정이 필요하며, 이전 프린터의 폭이나 OS 기본 프린터로 자동 대체하지 않습니다.
• 테스트·수동·자동 주문서 출력에 같은 설정을 사용합니다. 페이지 높이는 폰트·이미지 로딩 후 콘텐츠 크기로 계산하고, 여백과 배율을 명시합니다. 앱에서 특정 장비의 DPI를 강제하지 않습니다.
• 드라이버는 사용자 지정 용지 크기를 지원해야 합니다. 절단은 프린터 드라이버에서 작업마다 절단하도록 설정합니다.
• 같은 72mm 인쇄 폭이라도 모델의 기본 해상도는 다를 수 있습니다. OS 드라이버의 DPI와 이미지 변환 해상도를 장비 사양에 맞추세요. 앱의 폭 설정을 줄여 드라이버 해상도 불일치를 보정하지 않습니다.
• 테스트 출력 후 실물 너비·한글·절단을 확인하세요. 인쇄 성공 응답만으로 실물 품질을 보장하지 않습니다. PDF 크기는 맞는데 실물이 회전·확대되면 OS의 PDF/래스터 변환 경로도 확인해야 합니다.

배포 (GitHub Releases)

v* 형태의 태그를 푸시하면 GitHub Actions(.github/workflows/release.yml)가 mac/win/linux를 각각 빌드해서 GitHub Releases에 업로드. 기존에 설치된 앱들은 electron-updater로 자동 업데이트를 감지.

# package.json의 version을 올린 뒤
git add package.json && git commit -m "chore: bump version to 1.0.1"
git tag v1.0.1
git push origin main
git push origin v1.0.1

Actions 빌드가 끝나면 저장소의 Releases 탭에서 Draft 상태인 릴리즈를 Publish로 바꿔야 실제 배포.

권장 개발 환경

VSCode + ESLint + Prettier + Tailwind CSS IntelliSense