✨ 메일 인증, 코드 검증, 중복 이메일 검증 API 추가 (#26)

* 🤡 누락된 메일 인증 관련 API mock 추가

* ✨ 메일 인증, 코드 검증, 중복 이메일 검증 API 추가

* ✨ 메일 인증 관련 API 추가

* 🧪 메일 인증에 따른 성공/실패 컴포넌트 테스트 추가

* 🎨 포매팅 적용

Author: Yeonu-Kim

src/feature/auth/application/auth-query.ts

@@ -5,6 +5,58 @@ import { createErrorMessage } from '@/feature/shared/error/create-error-message'
 import { useRouteNavigation } from '@/feature/shared/routes/use-route-navigation';
 import type { UserRole } from '../domain/user-role';
 
+export const useSendVerificationEmail = ({
+  onSuccess,
+  setResponseMessage,
+}: {
+  onSuccess: () => void;
+  setResponseMessage: (message: string) => void;
+}) => {
+  const { authUsecase } = useGuardContext(UsecaseContext);
+  const { mutate: sendVerificationEmail, isPending } = useMutation({
+    mutationFn: async ({ email }: { email: string }) => {
+      return await authUsecase.sendVerificationEmail({ email });
+    },
+    onSuccess: (response) => {
+      if (response.type === 'success') {
+        onSuccess();
+        return;
+      }
+      setResponseMessage(
+        createErrorMessage(response.code, '인증 이메일 발송에 실패했습니다.')
+      );
+    },
+  });
+
+  return { sendVerificationEmail, isPending };
+};
+
+export const useValidateEmailCode = ({
+  onSuccess,
+  setCodeError,
+}: {
+  onSuccess: (verificationToken: string) => void;
+  setCodeError: (message: string) => void;
+}) => {
+  const { authUsecase } = useGuardContext(UsecaseContext);
+  const { mutate: validateEmailCode, isPending } = useMutation({
+    mutationFn: async ({ email, code }: { email: string; code: string }) => {
+      return await authUsecase.validateEmailCode({ email, code });
+    },
+    onSuccess: (response) => {
+      if (response.type === 'success') {
+        onSuccess(response.data.verificationToken);
+        return;
+      }
+      setCodeError(
+        createErrorMessage(response.code, '인증 코드 확인에 실패했습니다.')
+      );
+    },
+  });
+
+  return { validateEmailCode, isPending };
+};
+
 export const useSignIn = ({
   setResponseMessage,
 }: {
@@ -43,8 +95,10 @@ export const useSignIn = ({
 
 export const useSignUp = ({
   setResponseMessage,
+  onDuplicateEmail,
 }: {
   setResponseMessage: (message: string) => void;
+  onDuplicateEmail: () => void;
 }) => {
   const { authUsecase } = useGuardContext(UsecaseContext);
   const { toMain } = useRouteNavigation();
@@ -60,18 +114,21 @@ export const useSignUp = ({
       email: string;
       password: string;
     }) => {
-      return await authUsecase.signUp({
-        role,
-        username,
-        email,
-        password,
-      });
+      const checkResult = await authUsecase.checkEmailDuplicate({ email });
+      if (checkResult.type === 'error') {
+        return checkResult;
+      }
+      return await authUsecase.signUp({ role, username, email, password });
     },
     onSuccess: (response) => {
       if (response.type === 'success') {
         toMain();
         return;
       }
+      if (response.code === 'USER_001') {
+        onDuplicateEmail();
+        return;
+      }
       setResponseMessage(
         createErrorMessage(
           response.code,

src/feature/auth/usecase/auth-usecase.ts

@@ -1,9 +1,23 @@
 import type { UserRole } from '@/feature/auth/domain/user-role';
 import type { UsecaseResponse } from '@/feature/shared/response';
 import type { Apis } from '@/infrastructure/api';
+import type { VerificationTokenResponse } from '@/infrastructure/api/apis/local-server/schemas';
 import type { UserWithAccessTokenResponse } from '@/mocks/auth/schemas';
 
 export type AuthUsecase = {
+  checkEmailDuplicate: ({ email }: { email: string }) => UsecaseResponse<null>;
+  sendVerificationEmail: ({
+    email,
+  }: {
+    email: string;
+  }) => UsecaseResponse<null>;
+  validateEmailCode: ({
+    email,
+    code,
+  }: {
+    email: string;
+    code: string;
+  }) => UsecaseResponse<VerificationTokenResponse>;
   signUp: ({
     role,
     username,
@@ -27,6 +41,36 @@ export type AuthUsecase = {
 };
 
 export const implAuthUsecase = ({ api }: { api: Apis }): AuthUsecase => ({
+  checkEmailDuplicate: async ({ email }) => {
+    const { status, data } = await api['POST /api/auth/email']({
+      body: { email },
+    });
+    if (status === 200) {
+      return { type: 'success', data: null };
+    }
+    return { type: 'error', code: data.code, message: data.message };
+  },
+
+  sendVerificationEmail: async ({ email }) => {
+    const { status, data } = await api['POST /api/auth/email/verify']({
+      body: { email },
+    });
+    if (status === 200) {
+      return { type: 'success', data: null };
+    }
+    return { type: 'error', code: data.code, message: data.message };
+  },
+
+  validateEmailCode: async ({ email, code }) => {
+    const { status, data } = await api['POST /api/auth/email/validate']({
+      body: { email, code },
+    });
+    if (status === 200) {
+      return { type: 'success', data: data as VerificationTokenResponse };
+    }
+    return { type: 'error', code: data.code, message: data.message };
+  },
+
   signUp: async ({ role, username, email, password }) => {
     const { status, data } = await api['POST /api/auth/user']({
       body: { role, username, email, password },

src/feature/shared/error/create-error-message.ts

@@ -31,6 +31,8 @@ const ERROR_MESSAGES: Record<string, string> = {
   DEPOSIT_002: '예치금 정보를 찾을 수 없습니다.',
   // S3
   S3_001: '파일 업로드 URL 생성에 실패했습니다.',
+  // Mail
+  MAIL_001: '이메일 발송에 실패했습니다. 잠시 후 다시 시도해 주세요.',
 };
 
 const FALLBACK_MESSAGE = '오류가 발생했습니다. 다시 시도해 주세요.';

src/infrastructure/api/apis/local-server/apis.ts

@@ -5,9 +5,12 @@ import type {
   SuccessResponse,
 } from '../../domain';
 import type {
+  EmailRequest,
+  EmailValidateRequest,
   SignInRequest,
   SignUpRequest,
   UserWithAccessTokenResponse,
+  VerificationTokenResponse,
 } from './schemas';
 
 type GetApisProps = {
@@ -31,6 +34,28 @@ type Api = (_: {
 
 export const getLocalServerApis = ({ callWithoutToken }: GetApisProps) =>
   ({
+    'POST /api/auth/email': ({ body }: { body: EmailRequest }) =>
+      callWithoutToken<SuccessResponse<null>>({
+        method: 'POST',
+        path: 'api/auth/email',
+        body,
+      }),
+    'POST /api/auth/email/verify': ({ body }: { body: EmailRequest }) =>
+      callWithoutToken<SuccessResponse<null>>({
+        method: 'POST',
+        path: 'api/auth/email/verify',
+        body,
+      }),
+    'POST /api/auth/email/validate': ({
+      body,
+    }: {
+      body: EmailValidateRequest;
+    }) =>
+      callWithoutToken<SuccessResponse<VerificationTokenResponse>>({
+        method: 'POST',
+        path: 'api/auth/email/validate',
+        body,
+      }),
     'POST /api/auth/user': ({ body }: { body: SignUpRequest }) =>
       callWithoutToken<SuccessResponse<UserWithAccessTokenResponse>>({
         method: 'POST',

src/infrastructure/api/apis/local-server/schemas.ts

@@ -20,3 +20,16 @@ export type UserWithAccessTokenResponse = {
   user: UserBriefDTO;
   token: string;
 };
+
+export type EmailRequest = {
+  email: string;
+};
+
+export type EmailValidateRequest = {
+  email: string;
+  code: string;
+};
+
+export type VerificationTokenResponse = {
+  verificationToken: string;
+};

src/mocks/README.md

@@ -10,6 +10,81 @@
 
 ---
 
+# 메일 중복 확인
+
+## POST `/api/auth/email`
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 (중복 없음) | 정상 body |
+| `400` 필드 누락 | `email` 누락 |
+| `409` 중복 이메일 | `email: "duplicate@example.com"` |
+
+---
+
+# 메일 인증 이메일 발송
+
+## POST `/api/auth/email/verify`
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 | 정상 body |
+| `400` 필드 누락 | `email` 누락 |
+| `500` 발송 실패 | `email: "fail-send@example.com"` |
+
+---
+
+# 메일 인증 코드 확인
+
+## POST `/api/auth/email/validate`
+
+성공 시 `{ verificationToken: "mock-verification-token-uuid" }` 반환.
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 | 정상 body |
+| `400` 필드 누락 | `email` 또는 `code` 누락 |
+| `400` 잘못된 코드 | `code: "000000"` |
+
+---
+
+# 로그아웃
+
+## DELETE `/api/auth/user/session`
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 | owner 또는 reviewer 토큰 |
+| `401` 인증 실패 | 토큰 없음 또는 유효하지 않은 토큰 |
+
+---
+
+# 비밀번호 재설정
+
+## POST `/api/auth/password`
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 | 정상 body |
+| `400` 필드 누락 | `email` 누락 |
+| `404` 사용자 없음 | `email: "notfound@example.com"` |
+| `500` 발송 실패 | `email: "fail-send@example.com"` |
+
+---
+
+# 비밀번호 변경
+
+## PATCH `/api/auth/password`
+
+| 케이스 | 조건 |
+|---|---|
+| `200` 성공 | 로그인 토큰 + 정상 body |
+| `400` 필드 누락 | `currentPassword` 또는 `newPassword` 누락 |
+| `401` 인증 실패 | 토큰 없음 또는 유효하지 않은 토큰 |
+| `401` 기존 비밀번호 불일치 | `currentPassword: "wrongpassword"` |
+
+---
+
 # 회원가입
 
 ## POST `/api/auth/user`

src/mocks/auth/data.ts

@@ -1,4 +1,7 @@
-import type { UserWithAccessTokenResponse } from './schemas';
+import type {
+  UserWithAccessTokenResponse,
+  VerificationTokenResponse,
+} from './schemas';
 
 export const mockOwnerUser: UserWithAccessTokenResponse = {
   user: { id: 'owner-001', userRole: 'OWNER' },
@@ -9,3 +12,7 @@ export const mockReviewerUser: UserWithAccessTokenResponse = {
   user: { id: 'reviewer-001', userRole: 'REVIEWER' },
   token: 'mock-reviewer-token',
 };
+
+export const mockVerificationToken: VerificationTokenResponse = {
+  verificationToken: 'mock-verification-token-uuid',
+};

src/mocks/auth/handler.ts

@@ -3,6 +3,12 @@ import { http } from 'msw';
 import { authResolver } from './resolvers';
 
 export const authHandlers = [
+  http.post('*/api/auth/email', authResolver.checkEmailDuplicate),
+  http.post('*/api/auth/email/verify', authResolver.sendVerificationEmail),
+  http.post('*/api/auth/email/validate', authResolver.validateEmailCode),
   http.post('*/api/auth/user', authResolver.signUp),
   http.post('*/api/auth/user/session', authResolver.signIn),
+  http.delete('*/api/auth/user/session', authResolver.signOut),
+  http.post('*/api/auth/password', authResolver.resetPassword),
+  http.patch('*/api/auth/password', authResolver.changePassword),
 ];