[Spring Boot] 휴대폰 문자인증(SMS) 구현하기 (feat.CoolSMS API)

CoolSMS, Redis, React(Next.js)
End-to-End

---

현재 진행하는 서비스에서 소셜 회원가입(카카오)과 일반 회원가입을 모두 지원하다보니, 이메일이나 소셜 ID로만으로는 동일 사용자가 여러 번 회원가입 할 수 있는 문제가 발생했다. 실제로 운영하다 보면 중복 가입으로 인한 관리 어려움, 이벤트 남용, 데이터 낭비 등 문제가 발생한다.

이 문제를 해결하기 위해, 팀원들과 논의 끝에 "휴대폰 번호"를 핵심 중복 방지 식별자로 선택했다.
회원가입 시 반드시 휴대폰 인증을 거쳐 이미 사용된 번호로는 가입할 수 없게 막는 방식을 도입했다.

---

일단 SMS 인증 구현 과정 전에 휴대폰 번호 컬럼으로 휴대폰 번호 중복을 체크하는 과정부터 써내려 가겠음 !
 

📱휴대폰 번호 중복체크 구현

1. User Entity(VO)에 Phone 컬럼에 유니크 제약을 추가

 @Column(unique = true, nullable = false)
 private String phone;

 

ALTER TABLE user ADD CONSTRAINT uq_user_phone UNIQUE(phone);

• JPA를 사용하기때문에 VO에다 유니크 제약만 걸어주면 됨.

2. UserRepository(DAO) 

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByPhone(String phone);
}

• Optinal<User> findByPhone 메소드 추가

select * from user where phone=?

• JPA가 만들어주지만 실제 쿼리는 위와 같다.

3. UserService 서비스단 중복 체크 로직

public void validateDuplicatePhone(String phone) {
    if (userRepository.findByPhone(phone).isPresent()) {
        throw new CustomException(ErrorType.ALREADY_EXISTS_PHONE);
    }
 }

• 사용자가 가입을 시도할 때마다 호출

public enum ErrorType implements ErrorCode {
    ALREADY_EXISTS_PHONE(HttpStatus.CONFLICT, "사용중인 휴대폰번호입니다."),
}

• 실패 시 예외 메세지 반환 (Custom Exception)

4. KakoAuthService(kakaoRegister Method) 휴대폰 번호 중복체크 로직

 private final UserService userService;
 
 @Transactional
 public String kakaoRegister(KakaoSocialSignUpdto signUpdto) {
     log.info("[카카오 회원가입] 카카오 회원가입 시도: kakaoId={}, email={}, name={}", signUpdto.getKakaoId(), signUpdto.getEmail(), signUpdto.getName());
     // 휴대폰 번호 중복 체크
     userService.validateDuplicatePhone(signUpdto.getPhone());
     
     // 기타 카카오 회원가입 로직 
     ...
}

• KakaoAuthService에서 UserService를 주입받아 validateDuplicatePhone() 메서드 호출.
• UserRepository를 통해 DB에 같은 휴대폰 번호가 존재하는지 체크하고, 이미 사용 중인 번호일 경우 예외를 발생시켜 중복 가입을 방지한다.

5. AuthController(카카오 회원가입 엔드포인트)

 @PostMapping("/kakao/register")
    public ResponseEntity<?> kakaoRegister(@RequestBody KakaoSocialSignUpdto signUpdto) {
        try {
            String jwt = kakaoAuthService.kakaoRegister(signUpdto);
            return ResponseEntity.ok().body(
                new KakaoRegisterResponseDto(jwt, "회원가입 성공")
            );
        } catch (CustomException e) {
            log.warn("[카카오 회원가입] 커스텀 에러(휴대폰번호 중복): {}", e.getMessage());
            return ResponseEntity.status(e.getErrorType().getStatus()).body(
                new KakaoRegisterResponseDto(null, e.getErrorType().getDesc())
            );
        } catch (IllegalArgumentException e) {
            log.warn("[카카오 회원가입] 중복 가입 시도: {}", e.getMessage());
            return ResponseEntity.badRequest().body(
                new KakaoRegisterResponseDto(null, e.getMessage())
            );
        } catch (Exception e) {
            log.error("[카카오 회원가입] 서버 오류: {}", e.getMessage(), e);
            return ResponseEntity.internalServerError().body(
                new KakaoRegisterResponseDto(null, "서버 오류가 발생했습니다.")
            );
        }
    }

• KakaoAuthService를 주입받아 HTTP 요청/응답 관리에 집중하도록 설계
• 회원가입이 정상적으로 이루어진 경우 JWT토큰과 함께 회원가입 성공 메세지 반환
• 실패 시, 각각의 예외를 던짐
  • CustomException: 휴대폰 중복
  • IllegalArgumentException: 소셜 계정 중복
  • 기타 예외: 500 Internal Server Error

---

📝 CoolSMS 휴대폰 인증 도입기

🤔 도입 계기

서론에서 언급했지만 기존 소셜/일반 회원가입을 모두 지원하다 보니 이메일이나 소셜 ID만으로는 중복 회원가입 문제가 발생한다.

🔁 전체 인증 Flow

1. 사용자가 회원가입 폼에서 휴대폰 번호 입력
2. "인증번호 받기" 클릭 시, 서버(백엔드)에서 CoolSMS API를 통해 인증번호 전송
3. 인증번호를 Redis에 3분간 임시 저장
4. 사용자는 인증번호 입력 후, "인증번호 확인" 버튼으로 검증
5. 인증 성공 시, 인증 완료 플래그/코드로 회원가입 진행

---

1. Cool SMS 회원가입 및 API Key / Secret 발급

• CoolSMS에서 회원가입 후 API Key와 Secret Key를 발급받는다.

2. 환경 설정(yml, env, gradle)

2-1. build.gradle (dependencies 의존성 추가)

// CoolSMS 의존성 추가 (문자인증)
implementation 'net.nurigo:sdk:4.3.2'

 
2-2. application.yml (local)

coolsms:
  api-key: ${COOLSMS_API_KEY}
  api-secret: ${COOLSMS_API_SECRET}
  sender: "발신 번호"

• 위와 같이 yml파일을 수정해준다.
• sender에는 CoolSMS에 등록한 발신번호 (ex:"010-1234-5678")를 입력하면됨.

2-3. .env

• CoolSMS에서 발급받은 API Key와 SECRET Key 입력

3. SmsConfig 및 SmsUitl 클래스

3-1. SmsConfig(외부 라이브러리, API Key, 기타 설정 관련 Bean 등록)

import net.nurigo.sdk.message.service.DefaultMessageService;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SmsConfig {

    @Value("${coolsms.api-key}")
    private String apiKey;
    @Value("${coolsms.api-secret}")
    private String apiSecret;

    // CoolSMS Message Bean 등록
    @Bean
    public DefaultMessageService messageService() {
        return new DefaultMessageService(apiKey, apiSecret, "https://api.coolsms.co.kr");
    }
}

• 외부 SMS 서비스 연동의 종속성을 한 곳에서 관리하여 유지보수와 보안성 UP
• 실제 운영환경/개발환경에 따라 Key를 다르게 관리할 수 있음. 별도의 Mock 서비스로도 대체 가능
• Bean 등록 방식이므로, 추후 서비스 단에서 직접 객체를 생성하지 않고 DI로 관리.

3-2. SmsUtil

import java.util.Random;
import org.springframework.stereotype.Component;

@Component
public class SmsUtil {
    public static String generateAuthCode() {
        Random random = new Random();
        int code = 100000 + random.nextInt(900000); // 6자리 숫자
        return String.valueOf(code);
    }

    public String makeAuthMessage(String authCode) {
        return "[IssueMate 인증번호] " + authCode + "\n본인 확인을 위해 인증번호를 입력해주세요.";
    }
}

• 인증번호(OTP) 생성 및 메세지 포맷을 한 곳에서 관리.
• 인증번호 생성(`generateAuthCode`)은 6자리 랜덤 숫자를 리턴하며, 메세지 생성 (`makeAuthMessage`)은 사용자에게 전송될 안내문과 함께 인증번호를 조합한다.

4. SmsService (문자메세지 인증 관련 비즈니스 로직)

4-1. sendAuthCode(String phoneNumber)

    public void sendAuthCode(String phoneNumber) {
        String authCode = SmsUtil.generateAuthCode(); // 인증번호 생성
        String messageText = smsUtil.makeAuthMessage(authCode); // 메세지 포맷팅

        Message message = new Message();
        message.setFrom("010-9205-9228");
        message.setTo(phoneNumber);
        message.setText(messageText);

        // 요청 래핑
        SingleMessageSendingRequest request = new SingleMessageSendingRequest(message);

        // CoolSMS 발송 및 로그
        try {
            SingleMessageSentResponse response = messageService.sendOne(request);
            log.info("[SMS] 인증번호 발송 - to: {}, code: {}, response: {}", phoneNumber, authCode, response);
        } catch (Exception e) {
            log.error("[SMS] 인증번호 발송 실패 - to: {}, 에러: {}", phoneNumber, e.getMessage(), e);
            throw new RuntimeException("SMS 발송에 실패했습니다.");
        }

        // Redis에 인증번호 저장 (3분 유효)
        String redisKey = "SMS:AUTH:" + phoneNumber;
        redisTemplate.opsForValue().set(redisKey, authCode, 3, TimeUnit.MINUTES);
        log.info("[SMS] 인증번호 Redis 저장 - key: {}, code: {}", redisKey, authCode);
    }

• 전달받은 휴대폰 번호로 6자리 인증번호를 생성해서 문자로 발송.
• 인증번호를 Redis에 3분(180초) 동안 저장함.

동작 흐름

1. SmsUtil.generateAuthCode() 호출 → 6자리 인증번호 생성
2. SmsUtil.makeAuthMessage(authCode) 호출 → 사용자에게 보낼 안내 메세지 포맷팅
3. CoolSMS(Message, SingleMessageSendingRequest)로 실제 SMS 전송
4. 발송 성공 시, `SMS:AUTH: <phoneNumber>` 라는 키로 인증번호를 Redis에 저장 (3분 타임아웃)

 
4-2. verifyAuthCode(String phoneNumber, String inputCode)

public boolean verifyAuthCode(String phoneNumber, String inputCode) {
        String redisKey = "SMS:AUTH:" + phoneNumber;
        String storedCode = redisTemplate.opsForValue().get(redisKey);
        log.info("[SMS] 인증번호 검증 요청 - key: {}, 입력값: {}, 저장값: {}", redisKey, inputCode, storedCode);

        if (storedCode != null && storedCode.equals(inputCode)) {
            redisTemplate.delete(redisKey); // 1회 검증 후 삭제
            log.info("[SMS] 인증번호 검증 성공 - key: {}", redisKey);
            return true;
        }
        log.warn("[SMS] 인증번호 검증 실패 - key: {}, 입력값: {}", redisKey, inputCode);
        return false;
    }

• 전달받은 휴대폰 번호와 입력받은 인증번호를 Redis에 저장된 값과 비교하여 일치 여부 검증
• 1회 검증 시 Redis에서 인증번호 즉시 삭제 (재사용 불가)

동작 흐름

1. `SMS:AUTH:<phoneNumber>` 키로 Redis에서 인증번호 조회
2. 저장된 값이 있고, 입력값과 일치하면 인증번호 Redis에서 삭제, 성공 로그 출력 및 true 반환
3. 값이 없거나, 입력값 불일치 시 실패 로그 출력 및 false 반환

5. SmsController (API EndPoint)

5-1. 인증번호 발송 엔드포인트 @PostMapping("/sms/send")

    private final SmsService smsService;

    // 인증번호 발송
    @PostMapping("/send")
    public ResponseEntity<?> sendAuthCode(@RequestParam String phone) {
        try {
            smsService.sendAuthCode(phone);
            log.info("[SMS] 인증번호 발송 요청 완료 - to: {}", phone);
            return ResponseEntity.ok().body(Map.of("message", "인증번호가 전송되었습니다."));
        } catch (Exception e) {
            log.error("[SMS] 인증번호 발송 요청 실패 - to: {}, 에러: {}", phone, e.getMessage(), e);
            return ResponseEntity.internalServerError().body("SMS 발송에 실패했습니다: " + e.getMessage());
        }
    }

• 프론트엔드에서 휴대폰 번호를 전달받아, 해당 번호로 인증번호(SMS)를 발송 요청하는 엔드포인트

동작 흐름

1. smsService.sendAuthCode(phone) 호출로 인증번호 생성 및 전송
2. 발송 성공 시, {"message": "인증번호가 전송되었습니다."} 형식의 JSON 응답 반환 (200 OK)
3. 예외 발생 시, 서버 에러 메시지와 함께 500 응답

5-2. 인증번호 검증 엔드포인트 @PostMapping("/sms/verify")

// 인증번호 검증
    @PostMapping("/verify")
    public ResponseEntity<?> verifyAuthCode(
        @RequestParam String phone,
        @RequestParam String code
    ) {
        boolean result = false;
        try {
            result = smsService.verifyAuthCode(phone, code);
        } catch (Exception e) {
            log.error("[SMS] 인증번호 검증 중 예외 - to: {}, 에러: {}", phone, e.getMessage());
            return ResponseEntity.internalServerError().body("인증 중 서버 오류: " + e.getMessage());
        }

        if (result) {
            log.info("[SMS] 인증번호 검증 성공 - to: {}", phone);
            return ResponseEntity.ok().body(Map.of("message","인증되었습니다."));
        } else {
            log.warn("[SMS] 인증번호 검증 실패 - to: {}", phone);
            return ResponseEntity.badRequest().body(Map.of("message", "인증번호가 일치하지 않습니다"));
        }
    }

• 프론트엔드에서 사용자가 입력한 인증번호와 서버(Redis)에 저장된 인증번호를 비교하여 일치 여부를 확인하는 엔드포인트.

동작 흐름

1. sms.Service.verifyAuthCode(phone, code) 호출로 실제 검증 수행
2. 성공 시, {"message": "인증되었습니다."} 형식의 JSON 응답 반환 (200 OK)
3. 실패 시, {"message": "인증번호가 일치하지 않습니다."} 형식의 JSON 반환(400 BadRequest)
4. 서버 예외 시, 500 응답 및 에러 메세지 반환

5. BE: 문자메세지 인증 테스트 화면 (with Swagger)

1. 입력한 번호로 인증코드 발송

 
2. 메세지 전송화면

 
3. Redis 저장

 
4. 인증 코드 검증

• 실패 시

• 성공 시

• 인증 성공 시 Redis에서 해당 키 값 삭제(일회성)

---

🎨 FE: SMS 문자메세지 인증 API 연동 및 화면 UI/UX (Next.js)

프론트엔드 파일/코드 별 정리

1. feature/phone-auth/api/sms.ts

import {
  SmsSendRequest,
  SmsVerifyRequest,
} from "@/feature/phone-auth/types/sms.types";

export async function sendSmsAuthCode({ phone }: SmsSendRequest) {
  const res = await fetch(
    `http://localhost:8080/sms/send?phone=${encodeURIComponent(phone)}`,
    {
      method: "POST",
    }
  );

  const data = await res.json();

  if (!res.ok) throw new Error(data.message || "인증번호 전송 실패");
  return data;
}

export async function verifySmsAuthCode({ phone, code }: SmsVerifyRequest) {
  const res = await fetch(
    `http://localhost:8080/sms/verify?phone=${encodeURIComponent(phone)}&code=${encodeURIComponent(code)}`,
    {
      method: "POST",
    }
  );

  const data = await res.json();

  if (!res.ok) throw new Error(data.message || "인증번호 검증 실패");
  return data;
}

• 역할: 백엔드 인증 API(/sms/send, /sms,verify) 호출 함수 정의

주요 내용

• 인증번호 전송: sendSmsAuthCode({ phone })
• 인증번호 검증: verifySmsAuthCode({ phone, code })
• fetch/에러 처리 포함, 재사용 가능

2. feature/phone-auth/api/sms.ts

"use client";

import { useState, useEffect } from "react";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";
import { Alert, AlertDescription } from "@/components/ui/alert";
import { CheckCircle, Clock, RotateCcw, Send } from "lucide-react";
import { sendSmsAuthCode, verifySmsAuthCode } from "../api/sms";

type Props = {
  phone: string;
  disabled: boolean;
  onVerified: (code: string) => void;
};

export default function PhoneAuthSection({
  phone,
  disabled,
  onVerified,
}: Props) {
  const [code, setCode] = useState("");
  const [codeSent, setCodeSent] = useState(false);
  const [sendLoading, setSendLoading] = useState(false);
  const [verifyLoading, setVerifyLoading] = useState(false);
  const [verified, setVerified] = useState(false);
  const [error, setError] = useState("");
  const [success, setSuccess] = useState("");
  const [timeLeft, setTimeLeft] = useState(0);

  // 카운트다운 타이머
  useEffect(() => {
    let interval: NodeJS.Timeout | null = null;

    if (timeLeft > 0 && !verified) {
      interval = setInterval(() => {
        setTimeLeft((prev) => {
          if (prev <= 1) {
            return 0;
          }
          return prev - 1;
        });
      }, 1000);
    }

    return () => {
      if (interval) {
        clearInterval(interval);
      }
    };
  }, [timeLeft, verified]);

  // 시간을 MM:SS 형태로 포맷팅
  const formatTime = (seconds: number) => {
    const minutes = Math.floor(seconds / 60);
    const remainingSeconds = seconds % 60;
    return `${minutes.toString().padStart(2, "0")}:${remainingSeconds.toString().padStart(2, "0")}`;
  };

  const handleSend = async () => {
    setError("");
    setSuccess("");
    setSendLoading(true);

    try {
      await sendSmsAuthCode({ phone });
      setCodeSent(true);
      setTimeLeft(180); // 3분 = 180초
      setCode(""); // 인증번호 입력 필드 초기화
      setSuccess("인증번호가 전송되었습니다.");
    } catch (err) {
      setError((err as Error).message || "인증번호 전송 실패");
    } finally {
      setSendLoading(false);
    }
  };

  const handleVerify = async () => {
    setError("");
    setSuccess("");
    setVerifyLoading(true);

    try {
      await verifySmsAuthCode({ phone, code });
      setVerified(true);
      setTimeLeft(0); // 타이머 정지
      setSuccess("인증 성공!");
      onVerified(code);
    } catch (err) {
      setError((err as Error).message || "인증 실패");
    } finally {
      setVerifyLoading(false);
    }
  };

  // 버튼 텍스트와 아이콘을 결정하는 함수
  const getButtonContent = () => {
    if (sendLoading) {
      return (
        <>
          <Clock className="w-4 h-4 mr-2 animate-spin" />
          전송 중...
        </>
      );
    }

    if (codeSent && timeLeft > 0) {
      return (
        <>
          <Clock className="w-4 h-4 mr-2" />
          재전송 ({formatTime(timeLeft)})
        </>
      );
    }

    if (codeSent && timeLeft === 0) {
      return (
        <>
          <RotateCcw className="w-4 h-4 mr-2" />
          인증번호 재전송
        </>
      );
    }

    return (
      <>
        <Send className="w-4 h-4 mr-2" />
        인증번호 받기
      </>
    );
  };

  if (verified) {
    return (
      <div className="flex items-center gap-2 p-3 bg-green-900/20 border border-green-800 rounded-lg">
        <CheckCircle className="w-5 h-5 text-green-400" />
        <span className="text-green-400 font-medium">인증 완료</span>
      </div>
    );
  }

  return (
    <div className="space-y-3">
      {/* 인증번호 전송 버튼 */}
      <Button
        onClick={handleSend}
        disabled={disabled || sendLoading || (codeSent && timeLeft > 0)}
        type="button"
        className="w-full bg-gray-700 hover:bg-gray-600 text-white border border-gray-600 disabled:opacity-50"
        variant="outline"
      >
        {getButtonContent()}
      </Button>

      {/* 인증번호 입력 및 확인 */}
      {codeSent && (
        <div className="space-y-3">
          <div className="flex gap-2">
            <div className="flex-1 relative">
              <Input
                placeholder="인증번호 6자리 입력"
                value={code}
                onChange={(e) =>
                  setCode(e.target.value.replace(/[^\d]/g, "").slice(0, 6))
                }
                maxLength={6}
                className="bg-gray-800 border-gray-700 text-white placeholder:text-gray-500 focus:border-gray-600 focus:ring-gray-600 pr-16"
              />
              {/* 타이머 표시 */}
              {timeLeft > 0 && (
                <div className="absolute right-3 top-1/2 transform -translate-y-1/2">
                  <span
                    className={`text-sm font-mono ${timeLeft <= 30 ? "text-red-400" : "text-gray-400"}`}
                  >
                    {formatTime(timeLeft)}
                  </span>
                </div>
              )}
              {timeLeft === 0 && codeSent && (
                <div className="absolute right-3 top-1/2 transform -translate-y-1/2">
                  <span className="text-sm text-red-400 font-medium">
                    만료됨
                  </span>
                </div>
              )}
            </div>
            <Button
              onClick={handleVerify}
              disabled={
                verifyLoading || !code || code.length !== 6 || timeLeft === 0
              }
              type="button"
              className="bg-white hover:bg-gray-100 text-black font-medium px-6"
            >
              {verifyLoading ? "확인 중..." : "확인"}
            </Button>
          </div>

          {/* 타이머 안내 메시지 */}
          {timeLeft > 0 && (
            <p className="text-xs text-gray-500 text-center">
              인증번호는 {formatTime(timeLeft)} 후 만료됩니다.
            </p>
          )}

          {timeLeft === 0 && (
            <p className="text-xs text-red-400 text-center">
              인증번호가 만료되었습니다. 새로운 인증번호를 요청해주세요.
            </p>
          )}
        </div>
      )}

      {/* 에러 메시지 */}
      {error && (
        <Alert
          variant="destructive"
          className="bg-red-900/20 border-red-800 text-red-200"
        >
          <AlertDescription>{error}</AlertDescription>
        </Alert>
      )}

      {/* 성공 메시지 */}
      {success && !verified && (
        <Alert className="bg-green-900/20 border-green-800 text-green-200">
          <AlertDescription>{success}</AlertDescription>
        </Alert>
      )}
    </div>
  );
}

• 역할
  • 휴대폰 번호 인증 UI 및 상태 관리(입력, 전송, 검증, 타이버, 에러/성공 안내 등)
  • 타이머/재전송/만료 기능 까지 포함. 인터랙션 개선
• 주요 내용
  • 휴대폰 번호 인증 (문자 발송 → 인증번호 입력 → 검증 → 성공/실패 알림) UI + 로직
  • 인증 성공 시 onVerified(code) 콜백으로 상위에서 인증 상태 관리
  • 일반 회원가입, 소셜회원가입 모두에서 재사용 가능하게 설꼐
  • 인증번호 유효시간 타이머(카운트다운) 추가 (timeLeft 상태, MM:SS 표시)
  • 만료 시 인증번호 입력 / 확인 버튼 비활성화 및 "만료됨" 메세지 강조
  • 재전송 / 재인증 UX 개선
    • 인증번호 만료 시 "인증번호 재전송 버튼"
    • 인증번호 재전송 시, 타이머, 입력란 모두 리셋

3. feature/phone-auth/types/sms.types.ts

export interface SmsSendRequest {
  phone: string;
}

export interface SmsVerifyRequest {
  phone: string;
  code: string;
}

• 역할: 휴대폰 인증 API 파라미터/응답 타입 정의(TypeScript)
• 주요 타입: SmsSendRequest, SmsVerifyRequest

4. feature/social-signup/compnents/SocialSignupForm.tsx 수정

"use client";

import type React from "react";
import { useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import type { KakaoSocialSignUpRequest } from "@/feature/social-signup/types/signup.types";
import registerKakaoUser from "@/feature/social-signup/api/register";
import PhoneAuthSection from "@/feature/phone-auth/components/PhoneAuthSection";
import { Alert, AlertDescription } from "@/components/ui/alert";
import { Input } from "@/components/ui/input";
import { Checkbox } from "@/components/ui/checkbox";
import { Button } from "@/components/ui/button";
import { Label } from "@/components/ui/label";
import { User, Phone, Shield, CheckCircle } from "lucide-react";
import type { CheckedState } from "@radix-ui/react-checkbox";

export default function SocialSignupForm() {
  const router = useRouter();
  const searchParams = useSearchParams();

  // 쿼리에서 provider/kakaoId/email 등 가져옴
  const provider = searchParams.get("provider");
  const kakaoId = searchParams.get("kakaoId");
  const email = searchParams.get("email");

  const [name, setName] = useState("");
  const [phone, setPhone] = useState("");
  const [termsAgreed, setTermsAgreed] = useState(false);
  const [phoneVerified, setPhoneVerified] = useState(false);
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);

  // 휴대폰 번호 포맷팅 함수
  const formatPhoneNumber = (value: string) => {
    // 숫자만 추출
    const numbers = value.replace(/[^\d]/g, "");

    // 최대 11자리까지만 허용
    const truncated = numbers.slice(0, 11);

    // 길이에 따라 포맷팅
    if (truncated.length <= 3) {
      return truncated;
    }
    if (truncated.length <= 7) {
      return `${truncated.slice(0, 3)}-${truncated.slice(3)}`;
    }
    return `${truncated.slice(0, 3)}-${truncated.slice(3, 7)}-${truncated.slice(7)}`;
  };

  const handlePhoneChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const formatted = formatPhoneNumber(e.target.value);
    setPhone(formatted);
    if (phoneVerified) {
      setPhoneVerified(false);
    }
  };

  const handlePhoneVerified = () => {
    setPhoneVerified(true);
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError("");

    if (!name || !phone || !termsAgreed) {
      setError("실명, 휴대폰번호, 약관동의 모두 필수입니다.");
      return;
    }
    if (!phoneVerified) {
      setError("휴대폰 인증을 완료해주세요.");
      return;
    }
    // 휴대폰 번호 유효성 검사
    const phoneNumbers = phone.replace(/[^\d]/g, "");
    if (phoneNumbers.length !== 11) {
      setError("올바른 휴대폰 번호를 입력해주세요.");
      return;
    }

    setLoading(true);

    try {
      const payload: KakaoSocialSignUpRequest = {
        provider: provider ?? "kakao",
        kakaoId: kakaoId ?? undefined,
        email: email ?? undefined,
        name,
        phone,
        termsAgreed,
      };

      const res = await registerKakaoUser(payload);
      localStorage.setItem("jwt_token", res.token);
      router.replace("/dashboard");
    } catch (err) {
      setError((err as Error).message || "회원가입에 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };

  // 휴대폰 인증 비활성화 조건
  const isPhoneAuthDisabled = phone.replace(/[^\d]/g, "").length !== 11;

  return (
    <div className="min-h-screen flex items-center justify-center bg-black p-4">
      <div className="w-full max-w-md">
        <div className="text-center mb-8">
          <h1 className="text-2xl font-bold text-white mb-2">회원가입</h1>
          <p className="text-gray-400">추가 정보를 입력해주세요</p>
        </div>

        <form
          className="space-y-6 p-8 bg-gray-900 rounded-xl shadow-2xl border border-gray-800"
          onSubmit={handleSubmit}
        >
          {error && (
            <Alert
              variant="destructive"
              className="bg-red-900/20 border-red-800 text-red-200"
            >
              <AlertDescription>{error}</AlertDescription>
            </Alert>
          )}
          {/* 실명 입력 */}
          <div className="space-y-2">
            <Label
              htmlFor="name"
              className="text-gray-200 font-medium flex items-center gap-2"
            >
              <User className="w-4 h-4" />
              실명
            </Label>
            <Input
              id="name"
              value={name}
              onChange={(e) => setName(e.target.value)}
              placeholder="홍길동"
              className="bg-gray-800 border-gray-700 text-white placeholder:text-gray-500 focus:border-gray-600 focus:ring-gray-600"
              autoComplete="name"
            />
          </div>

          {/* 휴대폰 번호 입력 및 인증 */}
          <div className="space-y-3">
            <Label
              htmlFor="phone"
              className="text-gray-200 font-medium flex items-center gap-2"
            >
              <Phone className="w-4 h-4" />
              휴대폰번호
              {phoneVerified && (
                <CheckCircle className="w-4 h-4 text-green-400 ml-auto" />
              )}
            </Label>

            <Input
              id="phone"
              value={phone}
              onChange={handlePhoneChange}
              placeholder="010-1234-5678"
              className="bg-gray-800 border-gray-700 text-white placeholder:text-gray-500 focus:border-gray-600 focus:ring-gray-600"
              autoComplete="tel"
              maxLength={13}
              disabled={phoneVerified}
            />

            <PhoneAuthSection
              phone={phone}
              disabled={isPhoneAuthDisabled}
              onVerified={handlePhoneVerified}
            />
          </div>

          {/* 약관 동의 */}
          <div className="space-y-4">
            <div className="flex items-start gap-3 p-4 bg-gray-800/50 rounded-lg border border-gray-700">
              <Checkbox
                id="terms"
                checked={termsAgreed}
                onCheckedChange={(checked: CheckedState) =>
                  setTermsAgreed(checked === true)
                }
                className="mt-0.5 border-2 border-gray-500 bg-gray-700 data-[state=checked]:bg-white data-[state=checked]:text-black data-[state=checked]:border-white"
              />
              <div className="flex-1">
                <Label
                  htmlFor="terms"
                  className="text-gray-300 cursor-pointer flex items-start gap-2 leading-relaxed"
                >
                  <Shield className="w-4 h-4 mt-0.5 text-gray-400" />
                  <span>
                    <span className="text-red-400 font-medium">(필수)</span>{" "}
                    서비스 이용약관에 동의합니다.
                  </span>
                </Label>
              </div>
            </div>
          </div>

          <Button
            type="submit"
            className="w-full bg-white hover:bg-gray-100 text-black font-semibold py-3 transition-colors"
            disabled={loading}
          >
            {loading ? "가입 중..." : "가입하기"}
          </Button>
        </form>
      </div>
    </div>
  );
}

• 역할
  • 소셜 회원가입 폼
  • 휴대폰 인증 컴포넌트 통합
  • 회원가입 전 필수 입력/인증/약관 체크 등
• 변경 사항
  • PhoneAuthSection 컴포넌트 추가
  • 인증 플래그/코드 관리
  • 인증 성공 시만 회원가입 가능
  • 입력값, 에러, 상태 등 개선

화면 이미지

1. 휴대폰 번호 유효성 검증
 
[검증 완료 시, 인증번호 받기 버튼 활성화 ]

 
[검증 미완료 시, 인증번호 받기 비활성화]

 
2. 인증번호 받기 버튼 클릭 시
 
[인증번호 6자리가 모두 입력 안되있으면, 확인 버튼 비활성화]

 
[6자리 모두 입력되면, 확인버튼 활성화]

 
3. 인증번호 비교 화면
 
[인증번호 일치]

 
[인증번호 불일치]

 
5. 인증을하지 않고 가입하기 버튼 클릭 시

 
6. 인증번호 시간 만료

---

이번 포스팅은 회원가입에 휴대폰 인증을 붙이는 전체 플로우 및 과정에 대해 정리해보았다.

직접 붙여보고 나니 진짜 서비스에 한걸음 더 다가간 느낌이 체감된다.

실서비스에서 실제 인증/중복체크의 중요성을 체감했다. 단순히 "소셜 로그인만 붙이면 끝!" 이 아닌, 실제 운영 환경에서는 동일인이 여러 번 가입하는 문제를 반드시 체크해야 한다는 점, 핵심 식별자(이메일, 소셜ID, 휴대폰 번호 등)의 의미와 한계에 대해 고민하게 되었고, 그 중에서도 휴대폰 인증이 가장 현실적임을 직접 경험해보았다.

유저 경험(UX)에서 단순 인증만이 아니라 실시간 타이머, 재전송, 만료 안내, 반응형 즉각 피드백 등 사용자 경험을 세심하게 고려해야한다는 점을 다시 한번 느끼게 되었다.

 
ℹ️ 참고
[ - ]