# u.POS

> u.POS는 iPad·iPhone·Stripe 결제 단말기(S700/S710)·macOS/Windows PC에서 같은 상품, 같은 재고, 같은 매출로 판매하는 매장용 POS 시스템이다. 결제는 서버가 Stripe 웹훅으로 확정하고, 운영은 관리자 웹 하나로 한다. 일본어·한국어를 지원하며 통화는 엔(JPY)이다.

## 판매 플랫폼

- Stripe S710 POS: Stripe Reader S700/S710 단말기 위에서 직접 실행. 상품 선택 → 카드 결제 → Bluetooth 영수증 출력, 현금 결제와 레지, 금액 직접 입력, 정식 영수증(領収証) 발행, 영수증 QR 환불, 배터리 잔량 표시.
- iPad POS: 카운터용 가로 화면. 카탈로그와 장바구니, 카드·현금, 미완료 주문 자동 복구, 주문 이력·인도 확인·재출력.
- iPhone POS: 팝업·이동 판매용 세로 화면. iPad와 같은 기능.
- 데스크톱 POS(macOS·Windows): USB 바코드 스캐너, 키보드 현금 입력, LAN·OS 프린터, 환불, 레지.
- 관리자 웹: 상품·SKU·장소별 가격·이미지, 재고(입고·실사·이동·원장), 주문·환불·반품, 직원 권한, POS 기기·리더·프린터, 출력 이력, 매출 보고서·CSV·공유 링크, 감사 로그.

## 결제 흐름

1. POS가 장소별 카탈로그·가격·판매 가능 수량을 서버에서 받는다.
2. 서버가 서버 가격으로 주문을 계산하고 모든 SKU 재고를 한 번에 예약한다.
3. Stripe 리더로 카드 결제하거나 현금(받은 금액·거스름돈)으로 결제한다.
4. 서버가 Stripe 웹훅 서명을 검증해 주문을 paid로 확정하고 예약 재고를 판매로 전환한다.
5. 확정된 영수증을 매장 프린터(Bluetooth·LAN·OS 드라이버, ESC/POS)로 출력한다. 비트맵 출력이라 일본어·한국어·QR이 기종과 무관하게 인쇄된다.
6. 인도 확인 후 매출·대조·보고서는 관리자 웹에서 본다.

모든 쓰기 요청은 멱등키로 한 번만 반영되며, 웹훅은 먼저 저장된 뒤 큐와 정기 작업이 재처리·Stripe 상태 대조를 맡는다. 카드 결제는 온라인 상태에서만 가능하다.

## 권한·보안

관리자·매니저·스태프 역할. 환불은 매니저 이상. 관리자 웹에 등록된 기기만 POS 로그인 가능. 관리자 2단계 인증(TOTP), 감사 로그.

## 기술

Swift/SwiftUI, Kotlin/Jetpack Compose, Electron+React, React+Vite, TypeScript Cloudflare Workers, PostgreSQL(Hyperdrive), Cloudflare R2·Queues, Stripe Terminal, ESC/POS, OpenAPI.

## 링크

- 소개 페이지: https://pos-www.pages.dev/
- 자주 묻는 질문: https://pos-www.pages.dev/#faq