distribution_erp/docs/KAKAO_LOGIN_CHECKLIST.md

카카오 로그인 — 운영 전환 체크리스트

테스트 환경에서 카카오 로그인/가입 기능 동작 확인 완료. 운영 배포 전후로 처리할 작업을 단계별로 정리.

---

1. 운영 DB 마이그레이션

운영 DB 에 user_info.kakao_id 컬럼 + 부분 unique 인덱스 추가.

# A. 자동 배포 스크립트 사용 (권장 — 멱등)
#    deploy.sh 가 매 배포마다 migrate:momo 자동 실행
docker compose -f docker-compose.prod.yml exec -T momo-erp npm run migrate:momo

# B. 010 만 수동 실행 (009 가 admin 비번 초기화하는 게 부담스러우면)
psql "<운영 DATABASE_URL>" -f db/migrations/010_kakao_login.sql

검증

-- 컬럼 존재 확인
SELECT column_name FROM information_schema.columns
 WHERE table_name = 'user_info' AND column_name = 'kakao_id';

-- 부분 unique 인덱스 확인
SELECT indexdef FROM pg_indexes
 WHERE indexname = 'idx_user_info_kakao_id';

---

2. 카카오 앱 명의 이전 (모모유통)

현재 상태: 개발자(혜진) 개인 카카오 계정 명의로 등록된 테스트 앱. 목표 상태: (주)모모유통 명의 카카오 계정으로 등록된 운영 앱 + 비즈 앱 인증.

모모유통 측에서 진행

• 회사 대표 이메일로 카카오 계정 생성 (예: momo8443@daum.net)
• https://developers.kakao.com 가입
• 애플리케이션 추가
  • 앱 이름: MOMO 유통 ERP (또는 적절한 이름)
  • 사업자명: (주)모모유통
• 비즈니스 → 비즈 앱 전환 → 사업자등록증 업로드 → 검수 신청 (1~3 영업일 소요)
• 검수 통과 후:
  • 카카오 로그인 → 동의항목에서 카카오계정(이메일) 을 필수 동의 로 활성화
• 앱 → 멤버 메뉴에서 개발자(혜진) 카카오 계정을 팀원으로 초대

신규 앱에서 등록할 것

• 카카오 로그인 → 활성화 ON
• 앱 → 플랫폼 키 → 카카오 로그인 리다이렉트 URI 등록
  • http://localhost:3000/api/auth/kakao/callback (개발용)
  • https://momotogether.com/api/auth/kakao/callback (운영용)
• 클라이언트 시크릿 활성화 + 코드 발급 (보안 권장)
• 동의항목: 닉네임 필수 동의 + 이메일 필수 동의 (비즈 검수 통과 후)

---

3. 운영 환경변수 설정

운영 서버의 .env.production 에 카카오 환경변수 3개 추가.

# 운영 서버 SSH 접속
cd /deploy/source   # 또는 ~/momo-erp/source

# .env.production 끝에 추가
cat >> .env.production <<'EOF'

KAKAO_REST_API_KEY=<신규 앱의 REST API 키>
KAKAO_CLIENT_SECRET=<신규 앱의 Client Secret>
KAKAO_REDIRECT_URI=https://momotogether.com/api/auth/kakao/callback
EOF

# 컨테이너 재시작 (env_file 다시 로드)
docker compose -f docker-compose.prod.yml up -d --force-recreate momo-erp

---

4. 노출된 키 폐기 (보안)

테스트 단계에서 채팅·로그에 노출된 키들. 운영 시작 전 카카오 콘솔에서 재발급 후 새 값으로 운영 적용.

대상:

• 테스트용 REST API 키: 1e7825...
• 테스트용 Client Secret: jva60F8UfxZtDFI...

운영 앱은 신규 발급 키만 쓰므로, 테스트 앱은 삭제하거나 그대로 두어도 무방 (사용 안 하면 그만).

⚠ 운영 앱 키는 이번에는 채팅/이슈/PR 본문에 절대 붙여넣지 말 것. .env.production 에 직접 SSH 붙여 넣기.

.env 추적 정책 재검토 (선택)

현재 .env.development 는 git 트래킹된 상태(dev 시크릿이 히스토리에 있음). 운영 전환 시점에 다음을 함께 고려:

• .env.development.example (마스킹 템플릿)을 추가하고 실제 .env.development 는 git rm --cached 로 untrack
• 팀에 .env 공유 채널(1Password / Bitwarden / 슬랙 비공개) 합의
• 과거 히스토리의 시크릿은 git filter-repo 로 청소 또는 어차피 모두 재발급

---

5. 배포 후 동작 확인

신규 가입 (kakao_id 미보유)

1. https://momotogether.com/login → "카카오로 시작하기"
2. 카카오 동의 화면 (이메일·닉네임)
3. → /signup/kakao 추가정보 입력
   • 비즈 인증 후라면 이메일 자동 채워짐 (read-only)
   • 비즈 인증 전이면 이메일도 직접 입력
4. 업체명·연락처·주소 입력 → 가입 완료 → /m/dashboard

재방문 로그인 (kakao_id 매칭)

1. 같은 카카오 계정으로 "카카오로 시작하기"
2. 동의 화면 건너뜀 (카카오 SSO + 이전 동의 기록)
3. → 즉시 /m/dashboard 진입

DB 검증

SELECT user_id, user_name, email, kakao_id, regdate
  FROM user_info
 WHERE kakao_id IS NOT NULL
 ORDER BY regdate DESC
 LIMIT 10;

---

6. 자동 동작 (코드 변경 불필요)

• 비즈 앱 인증 통과 → 카카오에서 이메일 자동 수신 → /signup/kakao 페이지가 이메일 read-only 모드로 자동 전환 (src/app/(auth)/signup/kakao/page.tsx 의 needEmailInput 분기)
• 동일 이메일 일반 가입자가 카카오 로그인 시도 → 자동으로 kakao_id 연결 후 로그인 (src/app/api/auth/kakao/callback/route.ts)

---

코드 변경 요약 (참고)

파일	역할
db/migrations/010_kakao_login.sql	user_info.kakao_id 컬럼 + unique 인덱스
src/lib/kakao-auth.ts	카카오 OAuth 헬퍼 (인가 URL · 토큰 교환 · 프로필 · DB 조회/INSERT)
src/app/api/auth/kakao/start/route.ts	인가 URL 리다이렉트 + state CSRF 쿠키
src/app/api/auth/kakao/callback/route.ts	콜백 — kakao_id 매칭 / 동일 이메일 자동 연결 / 신규 분기
src/app/api/auth/kakao/pending/route.ts	가입 페이지용 pending JWT 검증
src/app/api/auth/kakao/complete/route.ts	가입 완료 — INSERT + 세션
src/app/(auth)/signup/kakao/page.tsx	추가정보 입력 페이지
src/app/(auth)/login/page.tsx	카카오 버튼 + ?kakao_error=... 토스트
src/app/(auth)/signup/page.tsx	카카오 버튼
src/middleware.ts	/api/auth/kakao public path 추가

보안 설계

• CSRF: 인가 요청 state 파라미터에 16바이트 nonce, httpOnly 쿠키와 대조
• 임시 가입 정보: jose JWT (NEXTAUTH_SECRET 서명, 10분 만료) — 클라이언트 위조 불가
• 자동 계정 연결: 카카오 OAuth 가 이메일 소유 검증을 보장하는 경우에만
• 일반 로그인 차단: 카카오 가입자는 user_password='' → verifyMomoCredentials 가 거부