# 🚀 [기능개선][모듈구조] 멀티모듈 패키지 구조 리팩터링 (Controller 이동, DTO 통합)

[Cassiiopeia]

📝 현재 문제점

• SS-Auth, SS-Member 모듈에 Controller, DTO, Domain이 분산되어 있어 레이어 경계가 모호함
• controller/dto/, service/dto/, domain/ 등 DTO가 여러 폴더에 산재
• Controller가 각 도메인 모듈에 위치하여 HTTP 관심사와 비즈니스 로직의 책임 분리가 불명확
• LoginCommand, LoginResult 등 불필요한 중간 변환 DTO가 존재하여 코드 복잡도 증가

🛠️ 해결 방안

• Controller를 SS-Web 모듈로 이동하여 HTTP 관심사를 한 곳에서 관리
• 각 모듈의 DTO를 모듈 루트 dto/ 폴더 하나로 통합
• Command/Result 변환 패턴을 제거하고 Controller-Service 간 DTO 직접 공유
• DTO 네이밍 규칙 통일 ({메소드명}Request, {메소드명}Response, {의미단위}Dto)
• DTO는 Record, Entity는 @builder 클래스로 구현 방식 통일

⚙️ 작업 내용

• SS-Auth dto/ 폴더 통합 (controller/dto + service/dto + domain → dto/)
• LoginCommand, LoginResult 제거 → LoginRequest, LoginResponse 직접 사용
• Controller 클래스를 SS-Web 모듈로 이동 (controller/auth/, controller/member/)
• SS-Web WebConfig 및 관련 import 경로 수정
• 전체 import 경로 수정 및 빌드 확인

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[EM-H20]

Guide by SUH-LAB

브랜치

20260309_#3_멀티모듈_패키지_구조_리팩터링_Controller_이동_DTO_통합

커밋 메시지

#   멀티모듈 패키지 구조 리팩터링 (Controller 이동, DTO 통합) : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-BE/issues/3

[Cassiiopeia]

멀티모듈 패키지 구조 리팩터링 (Controller 이동, DTO 통합)

이슈: #3

---

📌 작업 개요

SS-Auth, SS-Member 모듈에 분산되어 있던 Controller, DTO, Domain을 정리하여 레이어 경계를 명확히 분리함.
Controller를 SS-Web 모듈로 이동하고, DTO를 각 모듈 루트의 dto/ 폴더 하나로 통합.
불필요한 Command/Result 변환 레이어를 제거하고 Controller-Service 간 DTO 직접 공유 방식으로 단순화.

---

🎯 구현 목표

• Controller(HTTP 관심사)와 비즈니스 로직(Service)의 명확한 레이어 분리
• DTO 폴더 산재 문제 해소 (controller/dto/, service/dto/, domain/ → dto/ 통합)
• LoginCommand, LoginResult 등 중간 변환 DTO 제거
• DTO 네이밍 규칙 통일 및 Record 방식 표준화

---

✅ 구현 내용

1. Controller → SS-Web 모듈로 이동

• 변경 전: SS-Auth/controller/AuthController.java
• 변경 후: SS-Web/controller/auth/AuthController.java
• Controller는 HTTP 관심사만 담당하므로 SS-Web 모듈에서 일괄 관리
• 향후 Member, Study 등 도메인 Controller도 SS-Web/controller/{도메인}/ 하위에 위치

2. SS-Auth DTO 단일 폴더 통합

• 삭제: controller/dto/, service/dto/, domain/ 폴더
• 생성: dto/ 폴더 하나로 통합

파일	내용
LoginRequest.java	소셜 로그인 요청 (SocialType, idToken)
LoginResponse.java	로그인 응답 (memberId, nickname, tokens, isNewMember)
LogoutRequest.java	로그아웃 요청 (refreshToken)
ReissueRequest.java	토큰 재발급 요청 (refreshToken)
ReissueResponse.java	토큰 재발급 응답 (tokens)
Tokens.java	Access/Refresh Token 쌍 (기존 domain/ 이동)

모든 DTO는 Java Record로 구현. @NotNull, @NotBlank 검증 어노테이션 적용.

3. LoginCommand / LoginResult 제거

• LoginCommand, LoginResult 삭제
• AuthService.login() 시그니처 변경: LoginCommand → LoginRequest, 반환 LoginResult → LoginResponse
• Controller → Service 직접 전달, 중간 변환 코드(toCommand(), from()) 완전 제거

4. BaseTimeEntity 패키지 이동

• 변경 전: SS-Common/common/BaseTimeEntity.java
• 변경 후: SS-Common/common/entity/BaseTimeEntity.java
• Entity 관련 공통 클래스를 entity/ 하위로 분리하여 패키지 구조 명확화
• Member.java import 경로 수정 반영

---

🔧 보안 및 품질 개선

Refresh Token 탈취 감지 로직 추가 (AuthService.java)

기존에는 Redis 저장값과 단순 비교만 수행. 탈취된 구 토큰으로 재발급 시도 시 감지 불가 문제 존재.

변경 후 흐름:

1. Redis에 해당 memberId 토큰이 없음 → 이미 사용된 토큰으로 재시도 → 탈취 감지 경고 로그 + 예외
2. Redis 값과 불일치 → 강제 로그아웃(Redis 삭제) + 경고 로그 + 예외
3. 정상 경로 → 기존 토큰 즉시 삭제 후 신규 토큰 발급 (Token Rotation)

reissue() 패턴 통일 (AuthService.java, AuthController.java)

• reissueTokens(String) → reissue(ReissueRequest) 로 변경
• 반환 타입 Tokens → ReissueResponse (login과 동일한 패턴)
• Controller에서 new ReissueResponse(tokens) 직접 조립하던 코드 제거

기타 수정

항목	내용
@Transactional(readOnly=true) 수정	reissue() 내부 Redis 쓰기 작업 존재 → @Transactional로 변경
LoginMemberArgumentResolver fallback 제거	Interceptor 미적용 경로에서 @AuthMember 사용 시 조용히 처리되던 문제 수정. null이면 즉시 UNAUTHENTICATED_REQUEST 예외
GlobalExceptionHandler 로그 패턴 통일	모든 log 호출에 [Action] 태그 추가
RefreshTokenRepository.findByMemberId	반환 타입 String → Optional<String>
JwtTokenProvider 생성자 키 길이 검증	secret 32바이트 미만 시 기동 시점에 IllegalArgumentException 발생
WebConfig 주석 추가	excludePathPatterns와 AuthController 연관 명시

---

📐 확정된 코드 컨벤션 (CLAUDE.md 등록)

항목	규칙
DTO 구현	Java Record
Entity 구현	@builder 클래스
DTO 네이밍	{메소드명}Request / {메소드명}Response / 공유 시 {의미단위}Dto
Controller 위치	반드시 SS-Web 모듈
DTO 위치	각 모듈 루트 dto/ 폴더
Controller ↔ Service	같은 DTO 직접 공유 (Command/Result 변환 없음)

---

📌 참고사항

• 소셜 로그인 전략 실제 구현(Kakao, Google, Apple)은 의도적으로 미포함. 별도 이슈로 진행 예정.
• 로컬 빌드 환경(Spring Boot 4.0.2-SNAPSHOT) 특성상 정적 검증으로 확인 완료.

[Cassiiopeia]

@EM-H20 Stable 적용 완료