회원가입 개발 명세 (FRD)¶
요지¶
이메일 3단계 가입의 구현 방식을 정리한다. 설계의 핵심은 등록을 마지막에 한 번만 한다는 것이다. 1·2단계는 입력을 모으기만 하고(중복 검사와 인증코드 발송만 서버를 부른다), 3단계의 [가입 완료]를 누르는 순간 모든 데이터를 한 번에 묶어 단일 등록 API로 보낸다. 그러면 서버가 그 시점에 전 항목을 다시 검증한다 — 클라이언트 검증을 우회한 요청이나 그 사이 바뀐 상태(이메일 재중복 등)를 막기 위해서다. 로그인과 회원가입이 공유하는 입력 검증 규칙(V-01~31)은 아래 §예외·검증 표가 단일 기준이며, 로그인 FRD도 이 표를 참조한다.
상위 PRD (링크 · 변경 시 알림)¶
기획은 prd(바뀌면 이 문서도 갱신), 회원 도메인 상세는 member가 단일 기준이다.
기술 접근 · 아키텍처¶
Step1 이메일 → /check-duplicate (200/409)
Step2 인증코드 발송(180s 타이머/60s 쿨다운/일5회) + 코드 입력 + 비번·약관 로컬 수집(서버 미호출)
Step3 이름·역할 수집 → /api/auth/sign-up (전 데이터 일괄)
BE 재검증: 이메일 재중복 · 코드 유효/만료 · 비번 정책 · 약관 필수 · 이름/역할
→ 201 가입 완료 → 자동 로그인 or /login
- 상태: 가입 직후
INACTIVE, 이메일 인증 완료 시ACTIVE. - 레이트 리밋: 가입·인증코드 재발송·중복체크에 각각 적용.
- 경쟁 조건: Step1 통과 이메일도 최종 제출 시 409 가능. 400 응답은
step·fields단위 오류 반환(예:{step:2, fields:{emailCode:"CODE.INVALID", password:"PWD.POLICY"}}).
API · 데이터 모델¶
가입 흐름은 세 종류의 호출로 이뤄진다 — 이메일이 쓸 수 있는지 미리 확인하고, 인증코드를 보내고 검증하고, 마지막에 전체를 묶어 등록한다.
| 동작 | 엔드포인트 | 비고 |
|---|---|---|
| 이메일 중복 확인 | GET /api/public/email-verifications/check-duplicate |
200 사용가능 / 409 중복 |
| 인증코드 발송·검증 | POST /api/public/email-verifications{,/check} |
쿨다운·일일 한도, 코드 만료 |
| 회원가입 완료 | POST /api/auth/sign-up |
이메일·비번·이름·역할·약관 일괄 등록 |
상태 코드는 201(생성), 200(토큰까지 동시 발급), 400(형식·정합성), 409(최종 이메일 중복), 410(코드 만료), 422(금칙어·정책 위반), 429(레이트 리밋), 500을 쓴다.
회원은 member 본 테이블 + 역할별 teacher/student 조인 테이블(@OneToOne+@MapsId)로 저장하며, 공통 필드와 Role(STUDENT/PARENT/TEACHER)·Status(INACTIVE→ACTIVE)는 member §2가 기준이다.
예외·검증 — 로그인·회원가입 공용 규칙 (V-01~31)¶
아래 표는 로그인과 회원가입이 함께 쓰는 입력 검증 규칙 전체이며, 두 기능의 단일 기준이다. "공용" 열은 어디에 적용되는지를 뜻한다 — ALL은 두 폼 공통, 회원가입/로그인은 해당 폼 전용, (선택)·(정책)·(보안)은 정책으로 켜고 끄는 옵션이다.
| ID | 대상 | 조건 | 에러 메시지 | 공용 |
|---|---|---|---|---|
| V-01 | 이메일 | 비어있음 | 이메일을 입력해주세요. | ALL |
| V-02 | 이메일 | 형식 오류(RFC 5322) | 올바른 이메일 형식이 아니에요. | ALL |
| V-03 | 이메일 | 255자 초과 | 이메일은 255자 이내로 입력해주세요. | ALL |
| V-04 | 이메일 | 차단 도메인(temp-mail 등) | 사용할 수 없는 이메일 도메인입니다. | ALL |
| V-05 | 비밀번호 | 비어있음 | 비밀번호를 입력해주세요. | ALL |
| V-06 | 비밀번호 | 8자 미만 | 비밀번호는 8자 이상으로 입력해주세요. | ALL |
| V-07 | 비밀번호 | 64자 초과 | 비밀번호는 64자 이내로 입력해주세요. | ALL |
| V-08 | 비밀번호 | 영문 대/소·숫자·특수문자 조합 불충족 | 비밀번호는 영문 대/소문자, 숫자, 특수문자를 모두 포함해야 해요. | ALL |
| V-09 | 비밀번호 | 이메일과 동일/일부 포함 | 이메일과 동일한 비밀번호는 사용할 수 없어요. | ALL |
| V-10 | 비밀번호 | 동일 문자 반복(aaaaaa) | 반복된 문자로만 구성된 비밀번호는 사용할 수 없어요. | ALL |
| V-11 | 비밀번호 | 공백 포함 | 비밀번호에는 공백을 포함할 수 없어요. | ALL |
| V-12 | 입력 전체 | 앞뒤 공백(trim 미처리) | 입력값 앞뒤 공백을 제거해주세요. | ALL |
| V-13 | 비번 확인 | 비밀번호와 불일치 | 비밀번호와 일치하는지 확인해주세요. | 회원가입 |
| V-14 | 약관 | 필수 항목 미체크 | 필수 약관에 동의해주세요. | 회원가입 |
| V-15 | 이메일 | 중복 계정 존재(409) | 이미 가입된 이메일입니다. 로그인을 시도하거나 비밀번호를 재설정해주세요. | 회원가입 |
| V-16 | 이메일 | 인증 미완료 | 이메일 인증이 완료되지 않았습니다. | 회원가입 |
| V-17 | 비밀번호 | 이전 비밀번호 재사용 | 이전에 사용한 비밀번호는 다시 사용할 수 없습니다. | ALL(선택) |
| V-18 | 비밀번호 | 키보드 순서(abcd·1234·qwerty) | 연속된 문자/숫자는 비밀번호에 사용할 수 없습니다. | ALL(선택) |
| V-19 | 비밀번호 | 5회 실패 잠금 계정에서 사용 | 계정이 잠겨있습니다. 비밀번호를 재설정해주세요. | 로그인 |
| V-20 | 이름 | 비어있음/2자 미만 | 이름(표시명)을 2자 이상 입력해주세요. | 회원가입 |
| V-21 | 이름 | 비속어/금칙어(Filter DB) | 사용할 수 없는 단어가 포함되어 있습니다. | 회원가입 |
| V-22 | 역할 | 미선택 | 역할을 선택해주세요. | 회원가입 |
| V-23 | 이메일 | i18n 미지원(한글 도메인 등) | 지원하지 않는 이메일 형식이에요. | ALL(정책) |
| V-24 | 인증코드 | 형식 오류(숫자 외/자리수) | 인증 코드는 6자리 숫자로 입력해주세요. | 회원가입 |
| V-25 | 인증코드 | 만료/잘못된 코드 | 인증 코드가 만료되었거나 올바르지 않습니다. | 회원가입 |
| V-26 | 약관 | 전체동의 해제 후 필수 누락 | 필수 약관은 반드시 동의해야 합니다. | 회원가입 |
| V-27 | 입력 전체 | 금지 특수문자(< > SQL 등) |
허용되지 않은 문자가 포함되어 있습니다. | ALL(보안) |
| V-28 | 이메일 | MX Record 검증 실패 | 실제 존재하지 않는 이메일 주소입니다. | ALL(선택) |
| V-29 | 리치텍스트 | 화이트리스트 위반 서식 | 지원하지 않는 서식은 사용할 수 없습니다. | ALL |
| V-30 | ENUM | 허용되지 않은 Enum 멤버 | 잘못된 선택 값입니다. | ALL |
| V-31 | 이름(실명) | 한글 외(특수문자·영문·숫자) | 이름은 한글로만 입력 가능합니다. | 회원가입 |
단계별 적용: Step1=V-01~04·15 / Step2=V-24·25(코드)·V-05~13·16(비번·인증)·V-14·26(약관) / Step3=V-20·21·22·27·31(프로필·역할).
의존성 · 영향 범위¶
- member 도메인(Member/Status/Role), 이메일 인증 인프라(코드 발송·쿨다운·레이트 리밋), 비속어 Filter DB.
- 본 §5 V-table은 로그인 개발 명세 (FRD) §5가 참조하는 공용 SSOT.
테스트 계획¶
공통 케이스·E2E 전략은 qa-playbook을 따른다. 이 기능에서 꼭 확인할 것은 3단계를 앞뒤로 오가는 흐름, 중복 이메일, 코드 만료·불일치, 비밀번호 정책, 약관 필수, 그리고 최종 제출 순간의 재중복(409)·코드 만료(410) 경쟁 상황이다. 이름 한글 검증(V-31)과 역할 미선택(V-22)도 빠뜨리지 않는다.
작업 분해 (이슈 링크)¶
진행·완료 상태는 status와 GitHub 이슈에서 확인한다. 관련 이슈: Jira BTS-245.