시골약사
5339204fca
- 프로젝트 구조에 app.py 명시 - Phase 2 완료 상태로 업데이트 (QR 토큰 생성, Flask API) - 시스템 구성 및 연계 구조 설명 추가 - Flask API 엔드포인트 11개 문서화 (고객용 4개, 관리자용 7개) - 전체 시스템 실행 방법 상세 가이드 추가 - backend/gui/README.md에 app.py 연동 관계 추가 - OpenAI 기반 AI 분석 기능 안내 추가 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
202 lines
5.7 KiB
Markdown
202 lines
5.7 KiB
Markdown
# 약국 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 ✅
|
|
|
|
- [x] PyQt5 기반 GUI 구현
|
|
- [x] MSSQL SALE_MAIN 테이블 조회
|
|
- [x] 날짜별 판매 내역 표시
|
|
- [x] 상세 품목 조회 (더블클릭)
|
|
|
|
### Phase 2: QR 토큰 생성 ✅
|
|
|
|
- [x] SQLite mileage.db 스키마 설계
|
|
- [x] claim_token 생성 로직
|
|
- [x] QR 코드 생성 및 라벨 인쇄
|
|
- [x] Flask API 백엔드 구축 (app.py)
|
|
- [x] 전화번호 + 이름 기반 간편 적립
|
|
- [x] 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 웹 서버 실행 (필수)
|
|
|
|
```bash
|
|
cd backend
|
|
python app.py
|
|
```
|
|
|
|
서버가 시작되면 브라우저에서 http://localhost:5000 접속
|
|
|
|
#### 2단계: POS 판매 GUI 실행
|
|
|
|
```bash
|
|
cd backend/gui
|
|
python pos_sales_gui.py
|
|
```
|
|
|
|
- 날짜별 판매 내역 조회
|
|
- QR 생성 및 라벨 인쇄
|
|
- 적립 정보 실시간 확인
|
|
|
|
### 환경 설정
|
|
|
|
#### 필수 환경 변수 (.env)
|
|
|
|
```bash
|
|
# OpenAI API (AI 분석 기능 사용 시)
|
|
OPENAI_API_KEY=your-api-key-here
|
|
OPENAI_MODEL=gpt-4o-mini
|
|
```
|
|
|
|
#### 의존성 설치
|
|
|
|
```bash
|
|
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 (양구청춘약국)
|