pharmacy-pos-qr-system/docs/user-identity-merge.md

사용자 계정 연동(머지) 시나리오

개요

청춘약국 마일리지 시스템은 두 가지 경로로 사용자가 생성됩니다:

1. 전화번호 경로 — 키오스크에서 번호 입력, 회원가입 폼
2. 카카오 경로 — QR 스캔 후 카카오 로그인

한 고객이 두 경로를 모두 사용할 수 있으므로, 전화번호 기반 유저에 카카오 계정을 연동(머지) 하는 로직이 필요합니다.

---

데이터 구조

users 테이블
├── id (PK)
├── nickname    ← 키오스크 신규: "고객" / 카카오 연동 후: 실명
├── phone       ← 전화번호 (유니크 키)
├── mileage_balance
└── ...

customer_identities 테이블
├── user_id (FK → users.id)
├── provider = 'kakao'
└── provider_user_id = 카카오 ID

핵심 원칙: phone이 유저의 기본 식별자. 카카오는 부가 연동.

---

시나리오별 동작

시나리오 1: 키오스크만 사용하는 고객 (가장 흔함)

1회차: 키오스크 → 010-1234-5678 입력
  → get_or_create_user("01012345678", "고객")
  → users: {id: 100, nickname: "고객", phone: "01012345678", balance: 0}
  → 500P 적립 → balance: 500

2회차: 키오스크 → 같은 번호
  → get_or_create_user → 기존 user_id=100 반환
  → 300P 적립 → balance: 800

5회차까지: 전부 user_id=100에 누적

결과: 한 유저에 전부 쌓임. 문제없음.

---

시나리오 2: 키오스크 N회 → 알림톡 → 카카오 연동 (핵심 플로우)

[키오스크 5회 적립] → user_id=100, balance=2,000P, nickname="고객"

[알림톡 수신] → "적립 내역 확인" 버튼 탭
  → https://mile.0bin.in/my-page?phone=01012345678
  → 마이페이지 표시 (잔액 2,000P, 거래 5건)

[카카오 로그인 버튼 클릭]
  → _handle_mypage_kakao_callback() 실행
  → find_user_by_kakao_id(kakao_id) → 없음
  → 카카오에서 전화번호 "01012345678" 수신
  → phone으로 users 조회 → user_id=100 발견
  → link_kakao_identity(100, kakao_id, ...) ← 여기서 머지!
  → nickname "고객" → 카카오 실명 "김철수"로 업데이트
  → /my-page?phone=01012345678 리다이렉트

결과:

• user_id=100에 카카오 계정 연결됨
• 기존 5건의 적립 내역 그대로 유지
• 이름 "고객" → "김철수"로 업데이트
• 다음부터 QR 스캔으로도 같은 계정으로 적립

---

시나리오 3: QR 스캔(카카오) 먼저 → 키오스크 사용

[QR 스캔 + 카카오 로그인]
  → 카카오에서 phone "01012345678" + kakao_id 수신
  → get_or_create_user("01012345678", "김철수")
  → user_id=100 생성 (phone + kakao 동시에 연결)
  → 500P 적립

[이후 키오스크 사용] → 010-1234-5678 입력
  → get_or_create_user → 같은 phone → user_id=100 반환
  → 300P 적립 → balance: 800

결과: 처음부터 phone + kakao가 연결되어 있으므로 머지 불필요.

---

시나리오 4: 이미 카카오 연동된 유저가 다시 카카오 로그인

[카카오 로그인 (마이페이지)]
  → find_user_by_kakao_id(kakao_id) → user_id=100 발견
  → 이미 연결됨 → 마이페이지로 리다이렉트

결과: 중복 연동 방지. link_kakao_identity()도 내부적으로 중복 INSERT 방지.

---

시나리오 5: 카카오에 전화번호가 없는 경우

[카카오 로그인 (마이페이지)]
  → find_user_by_kakao_id → 없음
  → kakao_phone = None (카카오 설정에서 전화번호 미등록)
  → 에러: "카카오 계정에 전화번호 정보가 없습니다"

결과: 연동 불가. 카카오 설정에서 전화번호 등록 안내.

---

시나리오 6: 알림톡에서 바로 my-page 접근 (카카오 로그인 없이)

[알림톡 수신] → "적립 내역 확인" 버튼
  → https://mile.0bin.in/my-page?phone=01012345678
  → 전화번호로 직접 조회 → 마이페이지 표시
  → 카카오 연동 없이 내역만 확인

결과: 열람만 가능. 카카오 연동은 카카오 로그인 버튼을 눌러야 진행.

---

연동 시점 정리

진입 경로	link_kakao_identity 호출	비고
QR 스캔 → 카카오 로그인 → 적립	O	claim 플로우에서 자동 연동
키오스크 → 번호 입력 → 적립	X	전화번호만 있음
마이페이지 → 카카오 로그인	O (신규!)	_handle_mypage_kakao_callback에서 머지
알림톡 → 마이페이지 (번호 직접)	X	카카오 로그인 안 함

---

이름 업데이트 규칙

현재 이름	카카오 이름	결과
"고객"	"김철수"	→ "김철수" (업데이트)
"고객"	"고객" or 없음	→ "고객" (유지)
"김철수" (기존 실명)	"김영희"	→ "김철수" (기존 유지, 덮어쓰지 않음)

원칙: "고객"(키오스크 기본값)인 경우에만 카카오 실명으로 업데이트. 이미 실명이 있으면 유지.

---

관련 코드

함수	파일:라인	역할
get_or_create_user()	app.py:372	전화번호로 유저 조회/생성
link_kakao_identity()	app.py:485	카카오 계정을 유저에 연결
find_user_by_kakao_id()	app.py:519	카카오 ID로 유저 조회
_handle_mypage_kakao_callback()	app.py:793	마이페이지 카카오 콜백 (머지 포함)
api_kiosk_claim()	app.py:1986	키오스크 적립 + 알림톡 발송