pharmacy-pos-qr-system/README.md

약국 POS QR 적립 시스템

후향적 고객 매핑 및 마일리지 적립 시스템 (QR 기반)

프로젝트 개요

약국 POS 판매 시 영수증에 QR 코드를 인쇄하고, 고객이 나중에 QR을 스캔하여 카카오 로그인 후 마일리지를 적립받는 시스템입니다.

핵심 문제 해결

• 문제: 약국 POS 판매의 80%는 고객 정보 없이 판매됨
• 솔루션: 영수증 QR → 카카오 로그인 → 후향적 고객 매핑 → 마일리지 적립

프로젝트 구조

pharmacy-pos-qr-system/
├── backend/
│   ├── app.py            # Flask 웹 서버 (QR 마일리지 적립)
│   ├── gui/              # PyQt5 GUI 애플리케이션
│   │   └── pos_sales_gui.py
│   ├── api/              # API 모듈
│   ├── db/               # 데이터베이스 설정
│   │   └── dbsetup.py
│   ├── utils/            # 유틸리티 함수
│   ├── static/           # 정적 파일 (CSS, JS)
│   └── templates/        # Flask HTML 템플릿
│
├── web/                  # 웹 애플리케이션 (Next.js/React)
│
├── docs/                 # 문서
│   └── 후향적적립QR_POS만들기.md
│
└── docker/               # Docker 설정

개발 단계

Phase 1: POS 판매 조회 GUI ✅

• PyQt5 기반 GUI 구현
• MSSQL SALE_MAIN 테이블 조회
• 날짜별 판매 내역 표시
• 상세 품목 조회 (더블클릭)

Phase 2: QR 토큰 생성 ✅

• SQLite mileage.db 스키마 설계
• claim_token 생성 로직
• QR 코드 생성 및 라벨 인쇄
• Flask API 백엔드 구축 (app.py)
• 전화번호 + 이름 기반 간편 적립
• OpenAI 기반 구매 패턴 분석

Phase 3: 카카오 로그인 연동 (계획)

• 카카오 로그인 API 연동
• 웹앱 개발 (QR 스캔 랜딩 페이지)
• 마이페이지 구현

Phase 4: 마일리지 시스템 (계획)

• 마일리지 적립/사용 로직
• POS 고객 연결 기능
• 관리자 대시보드

시스템 구성

1. POS 판매 조회 GUI (pos_sales_gui.py)

• PyQt5 기반 데스크톱 애플리케이션
• MSSQL에서 판매 내역 조회
• QR 생성 및 라벨 인쇄
• SQLite에서 적립 정보 조회 및 표시

2. Flask 웹 서버 (app.py)

• QR 코드 스캔 후 적립 페이지 제공
• 전화번호 + 이름으로 간편 적립
• OpenAI 기반 구매 패턴 분석
• 마일리지 관리 및 조회
• 관리자 대시보드

연계 구조

POS GUI → QR 생성 (SQLite 저장) → 고객 스캔 → Flask 앱 → 적립 완료 → POS GUI에서 확인

기술 스택

Backend

• Python 3.12+
• PyQt5 - GUI 프로그램
• Flask - 웹 서버 및 REST API
• SQLAlchemy - ORM
• pyodbc - MSSQL 연결
• OpenAI API - AI 구매 패턴 분석

Database

• MSSQL - 기존 POS 데이터 (PM_PRES)
• SQLite - 마일리지 데이터 (mileage.db)

Web

• Next.js or React - 웹앱 프레임워크 (계획)
• Tailwind CSS - 스타일링

설치 및 실행

전체 시스템 실행 방법

1단계: Flask 웹 서버 실행 (필수)

cd backend
python app.py

서버가 시작되면 브라우저에서 http://localhost:5000 접속

2단계: POS 판매 GUI 실행

cd backend/gui
python pos_sales_gui.py

• 날짜별 판매 내역 조회
• QR 생성 및 라벨 인쇄
• 적립 정보 실시간 확인

환경 설정

필수 환경 변수 (.env)

# OpenAI API (AI 분석 기능 사용 시)
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4o-mini

의존성 설치

pip install -r requirements.txt

API 엔드포인트

고객용 페이지

• GET / - 메인 페이지
• GET /claim?token={claim_token} - QR 스캔 후 적립 페이지
• POST /api/claim - 마일리지 적립 요청
  • Body: {"claim_token": "...", "phone": "010-1234-5678", "name": "홍길동"}
  • Response: 적립 성공/실패 상태
• GET /my-page?phone={phone} - 마이페이지 (전화번호로 조회)
  • 포인트 잔액 및 구매 이력 조회

관리자용 페이지

• GET /admin - 관리자 대시보드
  • 전체 통계, 최근 거래, 사용자 검색
• GET /admin/transaction/{transaction_id} - 거래 상세 조회
  • 판매 내역, 품목 정보, QR 토큰 상태
• GET /admin/user/{user_id} - 사용자 상세 조회
  • 사용자 정보, 포인트 내역, 구매 이력
• GET /admin/search/user?q={query} - 사용자 검색
  • 전화번호 또는 이름으로 검색
• GET /admin/search/product?q={query} - 제품 검색
  • 제품명으로 검색 및 판매 내역 조회
• POST /admin/ai-analyze-user/{user_id} - AI 구매 패턴 분석
  • OpenAI 기반 구매 패턴 분석 및 추천
  • Response: 구매 패턴, 추천 제품, 마케팅 전략
• POST /admin/use-points - 포인트 사용 처리
  • Body: {"user_id": 1, "points": 5000, "reason": "사용 사유"}
  • 포인트 차감 및 사용 내역 기록

데이터베이스 구조

MSSQL (기존 POS)

• PM_PRES.SALE_MAIN: 판매 헤더
• PM_PRES.SALE_SUB: 판매 상세
  • ⭐ BARCODE 컬럼: 제품 바코드 (95.79% 보유율)
  • 활용: AI 기반 제품 태깅, 온톨로지 구축, 개인화 추천
• PM_BASE.CD_PERSON: 고객 정보
• PM_DRUG.CD_GOODS: 약품 마스터 (제품명)

SQLite (신규 마일리지)

• users: 카카오 로그인 계정
• customer_identities: 외부 로그인 매핑
• claim_tokens: 영수증 QR 토큰
• mileage_ledger: 마일리지 원장
• pos_customer_links: POS 고객 연결

라이선스

MIT License

작성자

thug0bin (양구청춘약국)