[Feat/#99] 회원가입 API 추가 (전화번호·약관 동의)

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/auth/AppAuthApi.java

@@ -21,7 +21,7 @@ public interface AppAuthApi {
     @Operation(summary = "OAuth 로그인",
         description = """
             provider(현재 kconnect)에서 받은 code·codeVerifier·redirectUri로 로그인한다.
-            처음 로그인하면 회원이 만들어진다. termsAgreementRequired가 true면 필수 약관 동의가 필요하다.""")
+            처음 로그인하면 회원이 만들어진다. signUpRequired가 true면 회원가입(전화번호·필수 약관 동의)이 필요하다.""")
     @ApiErrorCode(type = CommonErrorCode.class, codes = {"INVALID_INPUT"})
     @ApiErrorCode(type = OAuthErrorCode.class, codes = {
         "UNSUPPORTED_OAUTH_PROVIDER",

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/auth/response/OAuthLoginResponse.java

@@ -1,9 +1,10 @@
 package kr.ac.kookmin.stream.api.app.core.auth.response;
 
 /**
- * @param termsAgreementRequired 필수 약관에 아직 동의하지 않았으면 true. 앱은 이 값으로 약관 화면을 띄운다
+ * @param signUpRequired 회원가입(전화번호·필수 약관 동의)을 마치지 않았으면 true. 앱은 이 값으로 회원가입 화면을 띄운다
  */
 public record OAuthLoginResponse(
     String accessToken,
-    boolean termsAgreementRequired
+    String name,
+    boolean signUpRequired
 ) {}

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/auth/usecase/OAuthLoginUseCase.java

@@ -7,7 +7,6 @@
 import kr.ac.kookmin.stream.member.domain.member.domain.Member;
 import kr.ac.kookmin.stream.member.domain.member.domain.MemberProfileCommand;
 import kr.ac.kookmin.stream.member.domain.member.service.MemberService;
-import kr.ac.kookmin.stream.member.domain.member.service.MemberTermService;
 import kr.ac.kookmin.stream.security.AuthTokenIssuer;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Component;
@@ -24,17 +23,16 @@ public class OAuthLoginUseCase {
 
     private final OAuthService oauthService;
     private final MemberService memberService;
-    private final MemberTermService memberTermService;
     private final AuthTokenIssuer authTokenIssuer;
 
     public OAuthLoginResponse login(OAuthLoginCommand command) {
         OAuthUserInfo userInfo = oauthService.authenticate(command);
         Member member = findOrRegister(userInfo);
 
         String accessToken = authTokenIssuer.issue(member.getId(), member.getRole(), member.getCouncilDepartment());
-        // 회원을 이번에 만들었는지가 아니라 동의 기록으로 판단한다. 가입 후 동의하지 않고 이탈한 회원도 다시 약관 화면을 본다
-        boolean termsAgreementRequired = !memberTermService.hasAgreedRequiredTerms(member.getId());
-        return new OAuthLoginResponse(accessToken, termsAgreementRequired);
+        // 회원을 이번에 만들었는지가 아니라 저장된 전화번호·동의 기록으로 판단한다. 회원가입 화면에서 이탈한 회원도 다시 가입 화면을 본다
+        boolean signUpRequired = !memberService.isSignedUp(member.getId());
+        return new OAuthLoginResponse(accessToken, member.getName(), signUpRequired);
     }
 
     private Member findOrRegister(OAuthUserInfo userInfo) {

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/AppMemberApi.java

@@ -0,0 +1,31 @@
+package kr.ac.kookmin.stream.api.app.core.member;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import kr.ac.kookmin.stream.api.app.AppApiUser;
+import kr.ac.kookmin.stream.api.app.core.member.request.MemberSignUpRequest;
+import kr.ac.kookmin.stream.api.common.dto.ApiResponse;
+import kr.ac.kookmin.stream.api.common.openapi.ApiErrorCode;
+import kr.ac.kookmin.stream.common.CommonErrorCode;
+import kr.ac.kookmin.stream.member.domain.member.domain.MemberErrorCode;
+
+/**
+ * 학생 앱 회원 API의 문서 명세. 구현은 {@link AppMemberController}가 맡는다.
+ */
+@Tag(name = "회원", description = "학생 앱 회원가입")
+public interface AppMemberApi {
+
+    /** 회원가입. 로그인 응답의 signUpRequired가 true인 회원이 전화번호와 약관 동의 여부를 등록한다. */
+    @Operation(summary = "회원가입",
+        description = """
+            로그인한 회원의 전화번호와 약관 동의 여부를 저장한다.
+            전화번호는 하이픈을 넣어도 되고 빼도 된다. 필수 약관(PRIVACY_POLICY, TERMS_OF_SERVICE)에 모두 동의해야 한다.""")
+    @ApiErrorCode(type = CommonErrorCode.class, codes = {"INVALID_INPUT"})
+    @ApiErrorCode(type = MemberErrorCode.class, codes = {
+        "MEMBER_NOT_FOUND",
+        "REQUIRED_TERMS_NOT_AGREED",
+        "ALREADY_SIGNED_UP",
+        "PHONE_NUMBER_ALREADY_EXISTS"
+    })
+    ApiResponse<Void> signUp(AppApiUser apiUser, MemberSignUpRequest request);
+}

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/AppMemberController.java

@@ -0,0 +1,30 @@
+package kr.ac.kookmin.stream.api.app.core.member;
+
+import jakarta.validation.Valid;
+import kr.ac.kookmin.stream.api.app.AppApiUser;
+import kr.ac.kookmin.stream.api.app.core.member.request.MemberSignUpRequest;
+import kr.ac.kookmin.stream.api.common.dto.ApiResponse;
+import kr.ac.kookmin.stream.member.domain.member.service.MemberService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/v1/app/members")
+@RequiredArgsConstructor
+public class AppMemberController implements AppMemberApi {
+
+    private final MemberService memberService;
+
+    @Override
+    @PostMapping("/sign-up")
+    public ApiResponse<Void> signUp(
+        AppApiUser apiUser,
+        @Valid @RequestBody MemberSignUpRequest request
+    ) {
+        memberService.signUp(apiUser.userId(), request.toCommand());
+        return ApiResponse.success();
+    }
+}

api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/request/MemberSignUpRequest.java

@@ -0,0 +1,51 @@
+package kr.ac.kookmin.stream.api.app.core.member.request;
+
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import kr.ac.kookmin.stream.member.domain.member.domain.MemberSignUpCommand;
+import kr.ac.kookmin.stream.member.domain.member.domain.TermType;
+
+public record MemberSignUpRequest(
+    @NotBlank(message = "전화번호를 입력해 주세요.")
+    @Pattern(regexp = "^010-?\\d{4}-?\\d{4}$", message = "전화번호 형식이 올바르지 않습니다.")
+    String phoneNumber,
+
+    // 필수 약관 여부는 TermType이 정하므로 여기서는 동의 값을 강제하지 않는다
+    @NotEmpty(message = "약관 동의 여부를 입력해 주세요.")
+    @Valid
+    List<@NotNull(message = "약관 동의 항목이 비어 있습니다.") TermAgreementRequest> termAgreements
+) {
+
+    public MemberSignUpCommand toCommand() {
+        validateTermTypesNotDuplicated();
+
+        Map<TermType, Boolean> agreements = new EnumMap<>(TermType.class);
+        termAgreements.forEach(agreement -> agreements.put(agreement.termType(), agreement.agreed()));
+        return new MemberSignUpCommand(phoneNumber, agreements);
+    }
+
+    // 같은 약관이 두 번 오면 IllegalArgumentException → GlobalExceptionHandler가 INVALID_INPUT(400)으로 응답한다
+    private void validateTermTypesNotDuplicated() {
+        long distinctTermTypeCount = termAgreements.stream()
+            .map(TermAgreementRequest::termType)
+            .distinct()
+            .count();
+        if (distinctTermTypeCount != termAgreements.size()) {
+            throw new IllegalArgumentException("같은 약관의 동의 여부가 중복되었습니다.");
+        }
+    }
+
+    public record TermAgreementRequest(
+        @NotNull(message = "약관 종류를 입력해 주세요.")
+        TermType termType,
+
+        @NotNull(message = "약관 동의 여부를 입력해 주세요.")
+        Boolean agreed
+    ) {}
+}

api/common-api/src/main/java/kr/ac/kookmin/stream/api/common/GlobalExceptionHandler.java

@@ -11,6 +11,7 @@
 import org.slf4j.LoggerFactory;
 import org.slf4j.MDC;
 import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
 import org.springframework.validation.FieldError;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
@@ -53,6 +54,15 @@ public ResponseEntity<ApiResponse<Void>> handleIllegalArgument(IllegalArgumentEx
             .body(ApiResponse.error(CommonErrorCode.INVALID_INPUT.name(), e.getMessage()));
     }
 
+    // JSON 문법 오류, enum에 없는 값 등 요청 본문을 읽지 못한 경우. 파서 메시지는 내부 타입 이름을 담고 있어 응답에는 넣지 않는다
+    @ExceptionHandler(HttpMessageNotReadableException.class)
+    public ResponseEntity<ApiResponse<Void>> handleNotReadable(HttpMessageNotReadableException e) {
+        log.warn("[requestId={}, userId={}] (INVALID_INPUT) {}",
+            MDC.get(REQUEST_ID), MDC.get(USER_ID), e.getMessage());
+        return ResponseEntity.status(CommonErrorCode.INVALID_INPUT.status())
+            .body(ApiResponse.error(CommonErrorCode.INVALID_INPUT.name(), "요청 본문 형식이 올바르지 않습니다."));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ApiResponse<Void>> handleInternal(Exception e) {
         log.error("[requestId={}, userId={}] {}",

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/Member.java

@@ -20,13 +20,15 @@ public class Member {
     // 로그인 provider가 주는 학적 상태 원문(재학·휴학·졸업 등). 로그인 전 이관 회원은 null이다
     private String academicStatus;
     private String email;
+    // 회원가입 때 받는 휴대전화 번호(숫자만). 가입 전 회원과 이관 회원은 null이다
+    private String phoneNumber;
     private String fcmToken;
     private Role role;
     private CouncilDepartment councilDepartment;
 
     // 로그인으로 처음 가입하는 회원. 운영진 권한·학생회 부서는 가입 뒤 따로 부여한다
     public static Member create(String studentId, String name, Department department, String academicStatus) {
-        return new Member(null, studentId, name, department, academicStatus, null, null, Role.STUDENT, null);
+        return new Member(null, studentId, name, department, academicStatus, null, null, null, Role.STUDENT, null);
     }
 
     public static Member of(
@@ -36,11 +38,13 @@ public static Member of(
         Department department,
         String academicStatus,
         String email,
+        String phoneNumber,
         String fcmToken,
         Role role,
         CouncilDepartment councilDepartment
     ) {
-        return new Member(id, studentId, name, department, academicStatus, email, fcmToken, role, councilDepartment);
+        return new Member(
+            id, studentId, name, department, academicStatus, email, phoneNumber, fcmToken, role, councilDepartment);
     }
 
     // 로그인할 때마다 provider의 최신 이름·학부·학적 상태로 갱신한다. 바뀐 값이 있으면 true를 돌려준다
@@ -55,4 +59,12 @@ public boolean updateProfile(String name, Department department, String academic
         this.academicStatus = academicStatus;
         return true;
     }
+
+    public void registerPhoneNumber(String phoneNumber) {
+        this.phoneNumber = phoneNumber;
+    }
+
+    public boolean hasPhoneNumber() {
+        return phoneNumber != null;
+    }
 }

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/MemberErrorCode.java

@@ -12,7 +12,10 @@
 public enum MemberErrorCode implements ErrorCode {
 
     MEMBER_NOT_FOUND(ErrorStatus.NOT_FOUND, "회원을 찾을 수 없습니다."),
-    DEPARTMENT_NOT_ALLOWED(ErrorStatus.FORBIDDEN, "소프트웨어융합대학 학생만 이용할 수 있습니다.");
+    DEPARTMENT_NOT_ALLOWED(ErrorStatus.FORBIDDEN, "소프트웨어융합대학 학생만 이용할 수 있습니다."),
+    REQUIRED_TERMS_NOT_AGREED(ErrorStatus.BAD_REQUEST, "필수 약관에 모두 동의해 주세요."),
+    ALREADY_SIGNED_UP(ErrorStatus.CONFLICT, "이미 회원가입을 마쳤습니다."),
+    PHONE_NUMBER_ALREADY_EXISTS(ErrorStatus.CONFLICT, "이미 사용 중인 전화번호입니다.");
 
     private final int status;
     private final String message;

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/MemberSignUpCommand.java

@@ -0,0 +1,16 @@
+package kr.ac.kookmin.stream.member.domain.member.domain;
+
+import java.util.Map;
+
+/**
+ * 회원가입 요청. 전화번호는 하이픈을 지운 숫자만 담는다. 중복 검사와 저장이 같은 형식을 쓰게 하기 위함이다.
+ */
+public record MemberSignUpCommand(
+    String phoneNumber,
+    Map<TermType, Boolean> termAgreements
+) {
+
+    public MemberSignUpCommand {
+        phoneNumber = phoneNumber.replace("-", "");
+    }
+}

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/MemberTermAgreement.java

@@ -28,4 +28,19 @@ public static MemberTermAgreement of(
     ) {
         return new MemberTermAgreement(id, memberId, termType, termVersion, agreed, agreedAt);
     }
+
+    // 현재 약관 버전으로 동의 기록을 만든다. 동의하지 않았으면 동의 시각은 null이다
+    public static MemberTermAgreement create(Long memberId, TermType termType, boolean agreed, LocalDateTime now) {
+        return new MemberTermAgreement(null, memberId, termType, termType.version(), agreed, agreed ? now : null);
+    }
+
+    // 이미 기록이 있는 약관은 새 행을 만들지 않고 현재 버전으로 덮어쓴다. 버전과 동의 여부가 그대로면 최초 동의 시각을 지키도록 건너뛴다
+    public void update(boolean agreed, LocalDateTime now) {
+        if (termType.version().equals(this.termVersion) && this.agreed == agreed) {
+            return;
+        }
+        this.termVersion = termType.version();
+        this.agreed = agreed;
+        this.agreedAt = agreed ? now : null;
+    }
 }

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/TermType.java

@@ -10,9 +10,12 @@
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public enum TermType {
 
-    PRIVACY_POLICY(true),     // 개인정보 이용 동의
-    TERMS_OF_SERVICE(true);   // 서비스 이용 약관 동의
+    PRIVACY_POLICY(true, "v1"),     // 개인정보 이용 동의
+    TERMS_OF_SERVICE(true, "v1");   // 서비스 이용 약관 동의
 
     /** 가입 시 반드시 동의해야 하는 약관인지 여부 */
     private final boolean required;
+
+    /** 현재 약관 버전. 동의 기록에 함께 남긴다 */
+    private final String version;
 }

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/repository/MemberRepository.java

@@ -7,6 +7,7 @@
 public interface MemberRepository {
     Optional<Member> findById(Long id);
     Optional<Member> findByStudentId(String studentId);
+    boolean existsByPhoneNumber(String phoneNumber);
     List<Member> findAllByIds(List<Long> ids);
     List<Long> searchIdsByKeyword(String keyword);
     Member save(Member member);

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/repository/MemberTermAgreementRepository.java

@@ -5,4 +5,5 @@
 
 public interface MemberTermAgreementRepository {
     List<MemberTermAgreement> findAllByMemberId(Long memberId);
+    void saveAll(List<MemberTermAgreement> agreements);
 }

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/service/MemberService.java

@@ -4,6 +4,7 @@
 import java.util.Map;
 import kr.ac.kookmin.stream.member.domain.member.domain.Member;
 import kr.ac.kookmin.stream.member.domain.member.domain.MemberProfileCommand;
+import kr.ac.kookmin.stream.member.domain.member.domain.MemberSignUpCommand;
 
 public interface MemberService {
     Member getById(Long id);
@@ -12,4 +13,6 @@ public interface MemberService {
     List<Long> searchIdsByKeyword(String keyword);
     Member updateProfile(Long id, MemberProfileCommand command);
     Member registerOrUpdateByStudentId(MemberProfileCommand command);
+    Member signUp(Long memberId, MemberSignUpCommand command);
+    boolean isSignedUp(Long memberId);
 }

core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/service/MemberTermService.java

@@ -1,5 +1,9 @@
 package kr.ac.kookmin.stream.member.domain.member.service;
 
+import java.util.Map;
+import kr.ac.kookmin.stream.member.domain.member.domain.TermType;
+
 public interface MemberTermService {
     boolean hasAgreedRequiredTerms(Long memberId);
+    void agree(Long memberId, Map<TermType, Boolean> termAgreements);
 }