[FEAT] 회원가입 학생 인증 페이즈 추가

[bebeis]

Issue

Summary

• 회원 가입시 필요한 학생 인증 기능을 추가합니다.

Background

• 다음 마일스톤에서 추가할 학생 매칭 기능 & 신원 투명성 확보

Tasks

• 스키마 변경 고려
• API 스펙 설계
• MailSender 추가
• MailTemplate 구현
• Terraform AWS SES 추가
• 가용성 확보를 위한 폴백 추가

References

• 관련 링크나 문서가 있으면 적어주세요. (선택)

[bebeis]

배경

학생 인증은 로그인 계정 이메일과 별개의 학교 이메일을 사용할 수 있다.
따라서 로그인용 member_auth.email에 인증 대상 학교 이메일을 덮어쓰거나 같이 다루면 안 된다.

초기 API 초안에서는 인증 확인 요청에 email과 code를 함께 받는 형태를 고려했다.

POST /api/v1/members/me/student-verification/email/confirm
{
  "email": "luna@snu.ac.kr",
  "code": "123456"
}

이 방식은 memberId + email + code로 인증 시도를 찾을 수 있어서 단순하지만, 확인 요청이 다시 이메일을 요구한다.
또한 같은 회원이 새 이메일로 재시도했을 때 어떤 인증 요청을 확인하는지 API 계약이 모호해질 수 있다.

Stateless 방식 검토

Stateless 방식은 서버가 인증 시도 상태를 저장하지 않고, 발송 시점에 서명된 토큰을 만들어 클라이언트에 돌려주는 방식이다.

예시 흐름:

1. 사용자가 학교 이메일로 인증 코드 발송을 요청한다.
2. 서버가 memberId, email, universityId, expiresAt, codeHash 등을 포함한 서명 토큰을 만든다.
3. 클라이언트는 확인 요청 때 token + code를 보낸다.
4. 서버는 토큰 서명과 만료를 검증하고, 입력 코드를 비교한다.

장점:

• DB 또는 Redis에 인증 시도 레코드를 만들지 않아도 된다.
• 단순 트래픽에서는 구현량이 작아 보일 수 있다.
• 만료 검증은 토큰 자체로 처리할 수 있다.

단점:

• 재발송 제한, 시도 횟수 제한, 이전 코드 무효화 같은 정책 구현이 어렵다.
• 토큰이 탈취되면 만료 전까지 서버에서 개별 폐기하기 어렵다.
• 운영자가 인증 시도 이력을 추적하기 어렵다.
• 학교 이메일 인증은 보안/어뷰징 정책이 중요해서 완전 stateless는 장기적으로 불리하다.

Stateful 방식 검토

Stateful 방식은 이메일 인증 시도를 서버 저장소에 저장한다.
이번 설계에서는 student_verification_email_challenge 테이블이 이 역할을 한다.

예시 흐름:

1. 사용자가 학교 이메일로 인증 코드 발송을 요청한다.
2. 서버가 student_verification 현재 상태를 만들거나 갱신한다.
3. 서버가 student_verification_email_challenge를 생성하고, challengeId를 응답한다.
4. 메일에는 인증 코드만 발송한다.
5. 클라이언트는 challengeId path와 code body로 확인 요청을 보낸다.

현재 API 형태:

POST /api/v1/members/me/student-verification/email-challenges
{
  "email": "luna@snu.ac.kr"
}

POST /api/v1/members/me/student-verification/email-challenges/{challengeId}/confirmations
{
  "code": "123456"
}

장점:

• 확인 요청에서 이메일을 다시 받지 않아도 된다.
• challengeId가 어떤 인증 시도인지 명확히 식별한다.
• 재발송 제한, 만료, 확인 시도 횟수, 이전 challenge 무효화 정책을 서버에서 제어할 수 있다.
• 운영/CS 관점에서 인증 시도 상태와 이력을 확인하기 쉽다.
• 추후 대체 인증 제출물과 같은 학생 인증 도메인으로 확장하기 쉽다.

단점:

• 테이블 또는 Redis 같은 저장소가 필요하다.
• 만료된 challenge 정리 정책이 필요하다.
• 단순 stateless 토큰 방식보다 구현량이 많다.

최종 판단

학생 인증은 쓰기 권한을 여는 보안 경계에 가깝다.
또한 학교 이메일은 로그인 이메일과 다를 수 있고, 재시도/만료/어뷰징 제한이 필요하다.
따라서 완전 stateless 방식보다 stateful challenge 방식이 더 적절하다.

최종 방향:

• 학생 인증 현재 상태는 student_verification에 저장한다.
• 학교 이메일 인증 시도는 student_verification_email_challenge에 저장한다.
• 확인 요청은 이메일을 다시 받지 않고 challengeId + code로 처리한다.
• 인증 코드는 DB에 원문 저장하지 않고 해시로 저장한다.
• challengeId는 외부 노출용 랜덤 문자열로 만들고, 내부 PK를 직접 노출하지 않는다.
• 회원당 활성 PENDING challenge는 여러 개를 동시에 유효하게 두지 않는다.
• 새 challenge가 생성되면 이전 PENDING challenge는 REPLACED 상태로 바꾸고, 확인은 최신 challenge만 허용한다.
• 만료 challenge는 TTL 기준 주기적 배치로 정리하며, 배치는 1시간마다 실행한다.
• 메일 발송은 Spring MailSender를 사용하고, 실제 발송 인프라는 AWS SES를 사용한다.
• 학생 인증 상세 상태의 기준 데이터는 student_verification으로 둔다.
• 호환성을 위해 member.verification_status와 member.verification_rejected_reason은 유지한다.
• 신규 인증 로직은 student_verification과 member의 인증 상태 컬럼을 이중 갱신한다.
• 기존 코드의 권한 판단과 프로필 응답이 member 컬럼을 읽어도 깨지지 않게 한다.
• member 인증 상태 컬럼 제거는 현재 단계의 목표로 두지 않고, 운영 호환성 확인 후 별도 major migration에서만 검토한다.

확정된 결정 사항

• 인증 코드는 DB에 원문 저장하지 않고 해시로 저장한다.
• challengeId는 외부 노출용 랜덤 문자열로 만들고, 내부 PK를 직접 노출하지 않는다.
• 회원당 이메일 인증 challenge는 최신 PENDING만 유효하게 처리한다.
• 새 PENDING challenge가 생성되면 이전 PENDING challenge는 REPLACED 상태로 바꾼다.
• 만료 challenge는 TTL 기반 주기적 배치로 정리하며, 배치는 1시간마다 실행한다.
• 인증 상세 상태의 기준 데이터는 student_verification이다.
• 호환성을 위해 member.verification_status와 member.verification_rejected_reason은 유지하고 이중 갱신한다.

남은 결정 사항

• student_verification과 member 인증 상태 컬럼 간 불일치가 발생했을 때의 운영 복구 정책을 정해야 한다.
• 장기적으로 member.verification_status를 제거할지, 호환용 projection 컬럼으로 계속 유지할지 별도 major migration에서 다시 판단한다.