[Feat/#107] 회원 전화번호 변경 API 추가

[tnals0924]

#️⃣연관된 이슈

• Closes 회원 전화번호 변경 API 추가 #107
• 선행: 회원가입 API 추가 (전화번호·약관 동의) #99 (회원가입 API)

🎯 해결하려는 문제가 무엇인가요?

로그인한 학생이 자기 전화번호를 바꾸는 PATCH /v1/app/members/me/phone-number를 추가합니다.

// 요청 (Authorization: Bearer {accessToken})
{ "phoneNumber": "010-1234-5678" }
// 응답 data: null

❓ 왜 해결해야 하나요?

#99에서 회원가입 때 전화번호를 받아 members.phone_number에 저장하지만, 가입한 뒤에는 번호를 바꿀 방법이 없었습니다. 번호를 바꾼 학생은 학생회 연락을 받지 못합니다.

⭐ 어떻게 해결했나요?

• 흐름: 컨트롤러가 MemberService.updatePhoneNumber를 바로 부릅니다. member 도메인 하나만 쓰므로 UseCase는 두지 않았습니다.
• 하이픈 제거는 Command에서: MemberPhoneNumberUpdateCommand의 compact constructor에서 하이픈을 지웁니다. 가입(MemberSignUpCommand)과 같은 위치·방식이라, 중복 검사와 저장이 항상 숫자만 쓰는 형식을 씁니다. 값이 하나뿐이지만 정규화를 둘 곳이 필요해서 FCM 토큰 등록과 달리 Command를 만들었습니다.
• 입력 검증: MemberSignUpRequest와 같은 @NotBlank + @Pattern("^010-?\\d{4}-?\\d{4}$")입니다. 가입 때 받은 번호와 변경한 번호의 형식이 달라지지 않게 맞췄습니다.
• 중복 검사: 가입에서 쓰던 validatePhoneNumberNotDuplicated를 재사용합니다. 자기 번호면 통과하고, 다른 활성 회원이 쓰면 409입니다. 코드는 그대로 두고, 변경에서도 쓰인다는 내용만 주석에 더했습니다.
• 변경 없으면 저장 생략: Member.updatePhoneNumber가 바뀌었는지 돌려주고, 같은 번호면 저장하지 않습니다(updateFcmToken과 같은 방식). 같은 번호로 다시 호출해도 200입니다.
• 가입 완료 여부는 검사하지 않음: #99에서 가입 전 회원의 API 호출을 서버가 막지 않기로 했습니다. 가입 전 회원이 이 API로 번호를 넣어도 약관 동의가 없으니 signUpRequired는 그대로 true이고, 이후 같은 번호로 가입하면 자기 번호라 중복 검사를 통과합니다.
• DB 마이그레이션과 infrastructure:db 변경은 없습니다. 기존 phone_number 컬럼과 uk_members_active_phone_number, MemberRepositoryImpl.save의 유니크 위반 변환, @DynamicUpdate를 그대로 씁니다.

🧩 이 PR의 한계 & 트레이드오프

• 본인 인증 없음: SMS 인증 없이 형식·중복 검사만 합니다. 가입 때만이 아니라 언제든 남의 번호로 바꿔 선점할 수 있습니다(회원가입 API 추가 (전화번호·약관 동의) #99 리스크 1). 진짜 주인은 409를 받고, 운영진용 수정 API가 없어 지금은 DB를 직접 고쳐야 합니다.
• 번호 사용 여부 노출: 409 응답으로 "이 번호를 쓰는 회원이 있다"는 것을 알 수 있습니다. 가입 API는 가입을 마치면 ALREADY_SIGNED_UP으로 먼저 막히지만, 이 API는 가입한 회원이 횟수 제한 없이 반복 호출할 수 있습니다. 호출자가 소융대 인증 회원으로 한정되고 요청 횟수 제한 장치가 없어 이번에는 그대로 두었습니다.
• 변경 이력 없음: 이전 번호를 남기지 않습니다. access log에 요청 시각과 회원 ID만 남습니다.
• 정규화·정규식 중복: 하이픈 제거와 전화번호 정규식이 가입·변경 두 곳에 있습니다. 전화번호 값 객체로 묶는 리팩토링은 범위 밖이라 하지 않았습니다.
• 로컬 검증 범위: 로컬에 DB가 없어 컴파일과 ModularityTests·DomainImplAccessTests까지만 확인했습니다. 실제 저장과 409 응답은 dev에서 확인이 필요합니다.

⛓️ 기존 기능에 미치는 영향

• 새 엔드포인트와 메서드만 추가했습니다. 기존 API 응답과 DB 스키마는 바뀌지 않습니다.
• Swagger 회원 태그 설명을 "학생 앱 회원가입·FCM 토큰 등록·전화번호 변경"으로 바꿨습니다.

🔀 Edge Case & 실패 시나리오

상황	응답
번호 누락·공백, 010이 아닌 번호, 자릿수 오류, 문자 포함	400 INVALID_INPUT
탈퇴 등으로 회원 없음	404 MEMBER_NOT_FOUND
다른 활성 회원이 쓰는 번호	409 PHONE_NUMBER_ALREADY_EXISTS
지금 번호와 같은 번호 (하이픈 유무 무관)	200 (저장 생략)
탈퇴 회원이 쓰던 번호	200 (활성 회원만 중복으로 봄)

• 두 회원이 같은 번호로 동시에 변경: 둘 다 존재 검사를 통과해도 uk_members_active_phone_number 위반을 MemberRepositoryImpl.save가 PHONE_NUMBER_ALREADY_EXISTS로 바꿔 409가 됩니다.
• 같은 회원의 FCM 토큰 등록과 동시에 처리: @DynamicUpdate로 바뀐 컬럼만 UPDATE하므로 서로 덮어쓰지 않습니다.

📋 검토한 대안과 선택 이유

• Command 없이 서비스에서 하이픈 제거: 파일은 하나 줄지만 정규화 위치가 가입(Command)과 변경(Service)으로 갈립니다. #99의 "Request·Service가 아닌 Command에서 정규화" 기준을 따랐습니다.
• 같은 번호 요청을 400으로 응답: 앱이 화면에서 안내할 수 있지만 에러 코드가 늘고 재시도가 실패로 보입니다. FCM 토큰 등록과 같이 멱등으로 두었습니다.
• 전화번호가 없는 회원은 거절: "변경" API의 의미는 분명해지지만 에러 코드가 새로 필요하고 #99의 결정과 어긋납니다.
• SMS 본인 인증: 선점을 막을 수 있지만 SMS 업체 연동과 인증 API가 필요해 범위가 크게 늘어 별도 작업으로 미뤘습니다.

💬 리뷰 포인트

• MemberServiceImpl.updatePhoneNumber: 중복 검사 → 변경 여부 확인 → 저장 순서와 validatePhoneNumberNotDuplicated 재사용
• 가입 전 회원의 호출을 허용한 판단

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: billilge/stream-server/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0e002d95-5a79-4027-85de-2001dca6ec39

📥 Commits

Reviewing files that changed from the base of the PR and between bccbe97 and 9ce9f14.

📒 Files selected for processing (7)

• api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/AppMemberApi.java
• api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/AppMemberController.java
• api/app-api/src/main/java/kr/ac/kookmin/stream/api/app/core/member/request/PhoneNumberUpdateRequest.java
• core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/Member.java
• core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/domain/MemberPhoneNumberUpdateCommand.java
• core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/service/MemberService.java
• core/domain/member/src/main/java/kr/ac/kookmin/stream/member/domain/member/service/impl/MemberServiceImpl.java

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

로그인 회원의 전화번호를 변경하는 API와 도메인 처리를 추가합니다. 요청 전화번호를 검증하고 하이픈을 제거합니다. 서비스는 중복 여부를 확인하고, 번호가 바뀐 경우에만 저장합니다.

Changes: 전화번호 변경

Layer / File(s)	Summary
전화번호 변경 도메인 처리 core/domain/member/.../MemberPhoneNumberUpdateCommand.java, core/domain/member/.../Member.java, core/domain/member/.../MemberService.java, core/domain/member/.../MemberServiceImpl.java	명령 생성 시 하이픈을 제거합니다. 서비스는 회원을 조회하고 전화번호 중복을 확인합니다. 회원 번호가 실제로 변경된 경우에만 저장합니다.
전화번호 변경 API 연결 api/app-api/.../PhoneNumberUpdateRequest.java, api/app-api/.../AppMemberApi.java, api/app-api/.../AppMemberController.java	요청 전화번호는 비어 있지 않은 010 형식인지 검증합니다. PATCH /v1/app/members/me/phone-number가 요청을 명령으로 변환해 서비스에 전달합니다. API 명세에는 같은 번호 요청과 중복 번호 오류 조건을 기술합니다.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant AppMemberController
  participant PhoneNumberUpdateRequest
  participant MemberServiceImpl
  participant Member
  Client->>AppMemberController: PATCH 전화번호 변경 요청
  AppMemberController->>PhoneNumberUpdateRequest: 요청 검증 및 명령 변환
  AppMemberController->>MemberServiceImpl: updatePhoneNumber(memberId, command)
  MemberServiceImpl->>Member: updatePhoneNumber(phoneNumber)
  Member-->>MemberServiceImpl: 변경 여부 반환
  MemberServiceImpl-->>AppMemberController: 처리 결과 반환
  AppMemberController-->>Client: 성공 응답

Loading

Merge Risk: ⚪ Minimal · up to 9ce9f

The phone-number update meets the stated API behavior, with no identified issue blocking merge. Persistence and response behavior still need the planned dev-environment verification.

Pre-merge checks · 6 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 41.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (6 passed)

Check name	Status	Explanation
Description check		PR 설명은 템플릿의 모든 주요 섹션을 포함합니다. 구현 방식, 영향 범위, 예외 시나리오, 트레이드오프, 대안, 검증 범위를 구체적으로 설명합니다.
Linked Issues check		PR은 #107을 명시적으로 종료하며, 전화번호 변경 API 추가라는 이슈 목표와 구현 범위가 일치합니다.
Out of Scope Changes check		변경 사항은 전화번호 변경 API, 요청 검증, 정규화, 중복 검사, 도메인 서비스 처리에 집중합니다. 데이터베이스 마이그레이션, SMS 인증, 관리자 API 등 제외된 범위는 추가하지 않았습니다.
Title check		제목은 회원 전화번호 변경 API 추가라는 주요 변경 사항을 정확하고 간결하게 설명합니다.
Linked Issues check		직접 연결된 활성 이슈 #107의 코딩 요구사항을 충족합니다. AppMemberController가 PATCH /v1/app/members/me/phone-number를 제공하고 @Valid 요청을 서비스로 전달합니다. PhoneNumberUpdateRequest는 @NotBlank와 ^010-?\\d{4}-?\\d{4}$로 가입과 같은 …
Out of Scope Changes check		변경 범위는 #107 구현에 직접 연결됩니다. 컨트롤러·API 명세·요청 검증·정규화 Command·도메인 갱신·서비스 중복 검사는 새 전화번호 변경 API에 필요합니다. Swagger 설명과 주석 변경도 해당 기능을 설명하는 범위입니다. 제공된 변경 요약에서 관련 없는 기능 변경은 확인되지 않습니다.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}