계정 복구 개발 명세 (FRD)¶
요지¶
이메일 기반 계정 복구(아이디 찾기·비밀번호 재설정)를 어떻게 구현하는지 정리한다. 로그인하지 못한 사람만 들어오는 비로그인 전용 흐름이고, 본인 인증을 통과한 뒤 비밀번호를 재설정하면 그 자리에서 잠금까지 함께 푼다.
상위 PRD (링크 · 변경 시 알림)¶
기획은 prd(바뀌면 이 문서도 갱신), 회원 도메인은 member다. 잠금 해제는 로그인 개발 명세 (FRD)와 맞물린다.
기술 접근 · 아키텍처¶
권한·접근 조건¶
- 비로그인 사용자만 접근 가능. 로그인 상태 진입 시
/로 리다이렉트. - 인증 수단(이메일/전화번호)이 회원 DB에 등록되어 있어야 함.
화면 구성·흐름¶
상단 헤더(로고·홈 버튼) / 본문(단계별 복구 폼) / 푸터(약관·개인정보). 폼 단계: 복구 유형 선택 → 본인 인증 → 결과/비밀번호 재설정.
로그인 페이지 ─[계정 복구]→ 복구 페이지 ─ 복구 유형 선택
├ 이메일 찾기 → 이메일 입력 → /auth/verify → 성공: 아이디 노출 → 로그인 페이지
└ 비밀번호 재설정 → 인증 정보 입력 → /auth/verify → 성공: 재설정 폼
→ /auth/reset-password → 성공: "비밀번호 변경 완료" 토스트 → 로그인 페이지
상태: 로딩(인증·변경 요청 중 스피너), 입력값 없을 시 버튼 비활성, 에러(인증 실패/계정 불일치/서버 오류).
Postcondition¶
본인 인증 성공 시 verified=true 복구 완료 상태. 비밀번호 재설정 성공 시 DB user.password 갱신 + 잠금 해제(ACTIVE) 후 로그인 페이지 이동.
API · 데이터 모델¶
복구는 본인 인증과 비밀번호 재설정 두 단계의 호출로 끝난다 — 먼저 본인을 확인해 verified 상태로 올리고, 그 위에서 비밀번호를 바꾼다.
| 동작 | 엔드포인트 | 비고 |
|---|---|---|
| 본인 인증 | /auth/verify |
이메일/휴대폰 입력, verified=true 상태 전환 |
| 비밀번호 재설정 | /auth/reset-password |
성공 시 user.password 갱신 |
예외 시나리오·메시지 키¶
복구 흐름은 막히는 지점이 많아 오류마다 무슨 메시지를 어디에(인라인 vs 토스트) 띄우고 다음에 뭘 하게 할지를 미리 정해 뒀다. 프런트는 아래 메시지 키를 그대로 쓴다.
| 발생 조건 | 메시지 | 메시지 키 | 노출 위치 | 후속 |
|---|---|---|---|---|
| 인증 코드 불일치 | 입력 정보를 다시 확인해주세요. | auth.error.invalid_code |
폼 하단 | 입력 초기화·재입력 |
| 등록 계정 없음 | 일치하는 계정이 없습니다. | auth.error.account_not_found |
폼 하단 | 재입력, 인증 불가 |
| 비밀번호 불일치 | 비밀번호가 일치하지 않습니다. | auth.error.password_mismatch |
비번 칸 하단 | 확인 필드 포커스 |
| 입력값 누락 | 필수 입력 항목을 모두 작성해주세요. | auth.error.missing_field |
폼 하단 | 버튼 비활성 유지 |
| 토큰 만료 | 인증이 만료되었습니다. 다시 시도해주세요. | auth.error.expired_token |
토스트 | 인증 초기화·첫 단계 복귀 |
| 서버 오류 | 잠시 후 다시 시도해주세요. | common.error.server |
토스트 | 프로세스 중단·재시도 |
의존성 · 영향 범위¶
- member 도메인(
user.password·status), 이메일/휴대폰 인증 채널. - 로그인 개발 명세 (FRD) 5회 실패 잠금 해제 경로(재설정 성공 → ACTIVE +
login_fail_count=0).
테스트 계획¶
공통 케이스·E2E 전략은 qa-playbook을 따른다. 이 기능에서 꼭 볼 것은 비로그인 전용 접근(로그인 상태로 들어오면 /로 보냄), 유형 선택, 본인 인증의 성공·불일치, 등록 계정 없음, 비밀번호 재설정과 확인 불일치, 토큰 만료, 그리고 재설정 성공 뒤 잠금이 풀려 다시 로그인되는지다. 오류 메시지는 위 표의 키를 기준으로 한다.
복구는 단계마다 떨어져 나가기 쉬워서 GA 퍼널을 단계별로 촘촘히 심고, 각 구간이 무엇을 알려 주는지까지 정해 뒀다 — 어디서 유입되고 어느 인증 경로를 선호하며 어디서 막히는지를 보기 위해서다.
| 구간 | 측정 | 의도 |
|---|---|---|
| 진입(A) | 로그인 실패 후 '계정 복구' 클릭 수 | 유입률·CTA 위치/문구 개선 근거 |
| 방식 선택(B) | 이메일 찾기 vs 비밀번호 재설정 비중 | 선호 인증 경로 데이터 |
| 인증 요청(C·E) | /auth/verify 시도·성공률, 실패 케이스 |
실패율·UX 혼선·에러 메시지 개선 |
| 재설정(D·F·G) | 인증→재설정 이탈, 성공/실패 사유 | 전환율·프로세스 안정성 |
| 이탈(H) | 중간 단계 이탈 step·time_spent | 단계 축소·폼 구조 개선 |
이벤트와 파라미터 전체 목록은 원본(Notion)에 있다.
작업 분해 (이슈 링크)¶
진행·완료 상태는 status와 GitHub 이슈에서 확인한다. 관련 이슈: Jira BTS-264.