docs: 프로젝트 README 업데이트 - Flask app.py 및 API 문서 추가

- 프로젝트 구조에 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>

README.md

@@ -16,12 +16,15 @@
 ```
 pharmacy-pos-qr-system/
 ├── backend/
+│   ├── app.py            # Flask 웹 서버 (QR 마일리지 적립)
 │   ├── gui/              # PyQt5 GUI 애플리케이션
 │   │   └── pos_sales_gui.py
-│   ├── api/              # Flask API 서버
+│   ├── api/              # API 모듈
 │   ├── db/               # 데이터베이스 설정
 │   │   └── dbsetup.py
-│   └── utils/            # 유틸리티 함수
+│   ├── utils/            # 유틸리티 함수
+│   ├── static/           # 정적 파일 (CSS, JS)
+│   └── templates/        # Flask HTML 템플릿
 │
 ├── web/                  # 웹 애플리케이션 (Next.js/React)
 │
@@ -40,12 +43,14 @@ pharmacy-pos-qr-system/
 - [x] 날짜별 판매 내역 표시
 - [x] 상세 품목 조회 (더블클릭)
 
-### Phase 2: QR 토큰 생성 (진행 예정)
+### Phase 2: QR 토큰 생성 ✅
 
-- [ ] SQLite mileage.db 스키마 설계
+- [x] SQLite mileage.db 스키마 설계
-- [ ] claim_token 생성 로직
+- [x] claim_token 생성 로직
-- [ ] QR 코드 생성 및 라벨 인쇄
+- [x] QR 코드 생성 및 라벨 인쇄
-- [ ] Flask API 백엔드 구축
+- [x] Flask API 백엔드 구축 (app.py)
+- [x] 전화번호 + 이름 기반 간편 적립
+- [x] OpenAI 기반 구매 패턴 분석
 
 ### Phase 3: 카카오 로그인 연동 (계획)
 
@@ -59,47 +64,114 @@ pharmacy-pos-qr-system/
 - [ ] 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 서버
+- **Flask** - 웹 서버 및 REST API
 - **SQLAlchemy** - ORM
 - **pyodbc** - MSSQL 연결
+- **OpenAI API** - AI 구매 패턴 분석
 
 ### Database
 - **MSSQL** - 기존 POS 데이터 (PM_PRES)
 - **SQLite** - 마일리지 데이터 (mileage.db)
 
 ### Web
-- **Next.js** or **React** - 웹앱 프레임워크
+- **Next.js** or **React** - 웹앱 프레임워크 (계획)
 - **Tailwind CSS** - 스타일링
 
 ## 설치 및 실행
 
-### 1. Backend GUI (POS 판매 조회)
+### 전체 시스템 실행 방법
+
+#### 1단계: Flask 웹 서버 실행 (필수)
+
+```bash
+cd backend
+python app.py
+```
+
+서버가 시작되면 브라우저에서 http://localhost:5000 접속
+
+#### 2단계: POS 판매 GUI 실행
 
 ```bash
 cd backend/gui
 python pos_sales_gui.py
 ```
 
-### 2. Flask API 서버 (Phase 2)
+- 날짜별 판매 내역 조회
+- QR 생성 및 라벨 인쇄
+- 적립 정보 실시간 확인
+
+### 환경 설정
+
+#### 필수 환경 변수 (.env)
+
+```bash
+# OpenAI API (AI 분석 기능 사용 시)
+OPENAI_API_KEY=your-api-key-here
+OPENAI_MODEL=gpt-4o-mini
+```
+
+#### 의존성 설치
 
 ```bash
-cd backend/api
 pip install -r requirements.txt
-python flask_app.py
 ```
 
-### 3. 웹 애플리케이션 (Phase 3)
+## API 엔드포인트
 
-```bash
+### 고객용 페이지
-cd web
+
-npm install
+- `GET /` - 메인 페이지
-npm run dev
+- `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": "사용 사유"}`
+  - 포인트 차감 및 사용 내역 기록
 
 ## 데이터베이스 구조
 

backend/gui/README.md

@@ -7,7 +7,8 @@ PyQt5 기반 POS 판매 내역 조회 프로그램
 - 날짜별 판매 내역 조회
 - 실시간 총 매출 집계
 - 판매 상세 품목 조회 (더블클릭)
-- QR 생성 버튼 (Phase 2 준비)
+- QR 생성 및 라벨 인쇄
+- 적립 정보 실시간 표시 (Flask app.py 연동)
 
 ## 실행 방법
 
@@ -21,12 +22,62 @@ python pos_sales_gui.py
 
 ## 데이터베이스 연결
 
-MSSQL PM_PRES 데이터베이스에 연결합니다.
+### MSSQL
+PM_PRES 데이터베이스에 연결합니다.
 - SALE_MAIN: 판매 헤더
 - SALE_SUB: 판매 상세
 
+### SQLite
+mileage.db 데이터베이스에 연결합니다.
+- claim_tokens: QR 토큰 정보
+- users: 적립 사용자 정보
+
 연결 설정은 `../db/dbsetup.py`에서 관리됩니다.
 
+## Flask 웹 서버 연동
+
+### 필수 사전 실행
+이 GUI를 사용하기 전에 **Flask 웹 서버(app.py)를 먼저 실행**해야 합니다.
+
+```bash
+# 1단계: Flask 서버 실행 (필수)
+cd backend
+python app.py
+
+# 2단계: POS GUI 실행
+cd backend/gui
+python pos_sales_gui.py
+```
+
+### 연계 흐름
+
+```
+1. POS GUI에서 판매 내역 조회
+   ↓
+2. QR 생성 버튼 클릭
+   ↓
+3. SQLite에 claim_token 저장
+   ↓
+4. QR 라벨 인쇄
+   ↓
+5. 고객이 QR 스캔 → Flask 웹 페이지 접속
+   ↓
+6. 전화번호 + 이름 입력 → 적립 완료
+   ↓
+7. POS GUI에서 적립 정보 실시간 확인 (적립자명, 포인트)
+```
+
+### 주요 기능
+
+#### QR 생성
+- 선택한 판매 내역에 대해 QR 코드 생성
+- claim_token을 SQLite에 저장
+- Zebra 프린터로 라벨 인쇄
+
+#### 적립 정보 표시
+- 판매 내역 테이블에 적립 상태 표시
+- 적립 완료 시 사용자 정보 표시 (이름, 전화번호, 포인트)
+
 ## 스크린샷
 
 ```