[내일배움캠프 Spring 3기] 고객 및 상품 관리 시스템 프로젝트 (이커머스 백오피스) - API, 세션

[Spring] 백오피스 관리자 인증(세션) 구현 회고 & 트러블슈팅 (회원가입/로그인/로그아웃/세션 설정)

팀 프로젝트에서 “백오피스 관리자” 파트를 맡게 되면서, 필수 기능 중 세션 기반 인증(쿠키/세션)을 먼저 구현했다.

구현한 기능 목록 (필수 4개)

• 관리자 회원가입 API (기본 상태: 승인대기 PENDING, 비밀번호 암호화 저장)
• 관리자 로그인 API (세션 생성 및 저장, ACTIVE만 로그인 가능)
• 관리자 로그아웃 API (세션 invalidate)
• 세션 만료 시간/쿠키 옵션(HttpOnly) 설정

---

1. 팀 컨벤션에 맞춘 패키지 구조

팀 프로젝트라서 내 마음대로 구조를 만들면 나중에 충돌이 나거나 유지보수가 어려워질 수 있다.
프로젝트 내부를 보니 도메인별로 묶는 방식이 사용되고 있었고, 공통 응답/예외 포맷도 이미 존재했다.

그래서 관리자 인증은 아래처럼 admin 도메인 패키지를 만들고 그 안에서 3-layer를 유지했다.

com.example.commercepilot
 ┣ admin
 ┃ ┣ controller
 ┃ ┣ dto
 ┃ ┃ ┣ request
 ┃ ┃ ┣ response
 ┃ ┃ ┗ session
 ┃ ┣ entity
 ┃ ┣ repository
 ┃ ┣ service
 ┣ config
 ┣ exception

팀 공통 포맷 재사용

• ApiResponse (성공/실패 응답 공통)
• ErrorCode, ErrorResponse
• GlobalExceptionHandler (CustomException + Validation 처리)

팀 컨벤션을 최대한 따라가면서, 내가 구현하는 기능만 자연스럽게 추가되도록 했다.

---

2. 관리자 회원가입 API 구현

2-1. 요구사항 핵심 정리

회원가입에서 놓치면 안 되는 포인트는 아래였다.

• 입력값 유효성 검증 (이메일 형식, 비밀번호 최소 8자, 전화번호 010-XXXX-XXXX, role 필수 등)
• 이메일 중복 체크
• 비밀번호 암호화 저장 (BCrypt 기반 PasswordEncoder)
• 가입 시 기본 상태: 승인대기(PENDING)

2-2. DTO(Validation) 설계 이유

회원가입 요청 DTO는 record로 만들고 Bean Validation을 붙였다.
Controller에서 @Valid를 붙이면 Validation 실패 시 MethodArgumentNotValidException이 발생하고, 팀 공통 GlobalExceptionHandler에서 ApiResponse.fail(INVALID_INPUT_VALUE, fieldErrors) 형태로 내려줄 수 있다.

public record AdminSignupRequest(
    @NotBlank String name,
    @Email @NotBlank String email,
    @Size(min = 8) @NotBlank String password,
    @Pattern(regexp = "^010-\\d{4}-\\d{4}$") @NotBlank String callNumber,
    @NotNull AdminRole role
) {}

응답 DTO는 민감정보(비밀번호)는 절대 포함하지 않도록 최소 필드만 정의했다.

public record AdminSignupResponse(
    Long id,
    String name,
    String email,
    String callNumber,
    AdminRole role,
    AdminStatus status,
    LocalDateTime createdAt
) { ... }

🔎 왜 password를 응답에 안 넣는가?

리뷰에서도 실제로 나온 포인트인데, 해시된 비밀번호라도 응답으로 내려주는 건 보안상 적절하지 않다.
그래서 응답 DTO에 password는 아예 포함시키지 않았다.

---

2-3. Service 로직 설계 이유 (CommandService)

회원가입은 “데이터를 생성하는(쓰기)” 로직이다.
그래서 팀에서 추천하던 CQRS 맛보기 구조처럼, 쓰기 로직은 CommandService에 두고 확장 가능하도록 구성했다.

@Transactional
public AdminSignupResponse signup(AdminSignupRequest request) {
    if (adminRepository.existsByEmail(request.email())) {
        throw new CustomException(ErrorCode.ADMIN_EMAIL_DUPLICATED);
    }

    String encoded = passwordEncoder.encode(request.password());

    Admin admin = Admin.pending(
        request.name(),
        request.email(),
        encoded,
        request.callNumber(),
        request.role()
    );

    Admin saved = adminRepository.save(admin);
    return AdminSignupResponse.from(saved);
}

여기서 내가 신경쓴 부분

• 중복 이메일은 existsByEmail로 빠르게 체크
• 비밀번호는 PasswordEncoder.encode()로 저장 직전에 암호화
• 상태는 무조건 PENDING으로 고정 (승인 전에는 로그인 불가)

---

3. 로그인 API 구현 (세션 기반 인증)

3-1. 요구사항 핵심

로그인은 단순히 이메일/비밀번호만 맞으면 끝이 아니라, 계정 상태에 따라 로그인 가능 여부가 갈린다.

• ACTIVE만 로그인 가능
• PENDING/REJECTED/SUSPENDED/INACTIVE는 로그인 불가 + 명확한 메시지

또한 로그인 성공 시에는 서버 세션에 아래 정보를 저장해야 한다.

• adminId
• email
• role

3-2. 세션 저장 DTO + 세션 키 상수

세션에 저장하는 데이터는 최소한으로, 그리고 명확하게 하려고 별도 record로 뺐다.

public record LoginAdmin(Long adminId, String email, AdminRole role) {}

세션 key는 오타 방지 위해 상수로 관리했다.

public final class SessionConst {
    public static final String LOGIN_ADMIN = "LOGIN_ADMIN";
}

---

3-3. 로그인 Service 로직 (상태별 분기)

@Transactional(readOnly = true)
public void login(AdminLoginRequest request, HttpSession session) {
    Admin admin = adminRepository.findByEmail(request.email())
        .orElseThrow(() -> new CustomException(ErrorCode.LOGIN_FAILED));

    if (!passwordEncoder.matches(request.password(), admin.getPassword())) {
        throw new CustomException(ErrorCode.LOGIN_FAILED);
    }

    validateLoginStatus(admin.getStatus());

    LoginAdmin loginAdmin = new LoginAdmin(admin.getId(), admin.getEmail(), admin.getRole());
    session.setAttribute(SessionConst.LOGIN_ADMIN, loginAdmin);
}

🔎 왜 이메일 없음 / 비번 틀림은 같은 에러(LOGIN_FAILED)로 처리했나?

보안상 “이메일이 존재하는지”를 노출하면 안 되기 때문에 보통 로그인 실패는 동일하게 처리한다.
그래서 계정 존재 여부는 숨기고, 상태(승인대기/정지 등)는 요구사항에 맞게 명확히 분기했다.

---

4. 로그아웃 API 구현

로그아웃은 간단히 세션 무효화만 하면 된다.

public void logout(HttpSession session) {
    session.invalidate();
}

컨트롤러에서는 아래처럼 응답 data 없이 성공만 내려주도록 했다.

@PostMapping("/logout")
public ApiResponse<Void> logout(HttpSession session) {
    adminAuthService.logout(session);
    return ApiResponse.success(HttpStatus.OK);
}

---

5. 세션 만료시간/쿠키(HttpOnly) 설정

서버에서 세션을 오래 유지할지 결정해야 한다.
필수 요구사항 예시가 24시간이었고, 세션 쿠키는 XSS 위험을 줄이기 위해 HttpOnly 옵션을 사용했다.

application.properties

server.servlet.session.timeout=24h
server.servlet.session.cookie.http-only=true

---

6. 트러블슈팅

6-1. DTO 패키지 구조 때문에 “import 오류”가 났다

처음에는 DTO를 admin/dto 아래에 바로 두고 import를 작성했는데, 팀 구조를 따라가다 보니 dto/request, dto/response로 폴더를 나눴다.

그 상태에서 서비스 코드가 아래처럼 작성되어 있으면:

import com.example.commercepilot.admin.dto.AdminSignupRequest;

실제 DTO 경로는:

com.example.commercepilot.admin.dto.request.AdminSignupRequest

이라서 IntelliJ에서 Cannot resolve symbol 에러가 계속 났다.

해결:

• DTO 파일의 package 선언을 폴더 구조에 맞추고,
• Service/Controller import도 정확히 맞춰줬다.

---

6-2. “암호화된 비밀번호를 응답에 담는 게 적절한가요?” 리뷰 대응

서비스 로직에 encoded 변수가 보이다 보니, 리뷰어가 “응답에 password가 포함되는지”를 걱정해주셨다.

실제로는 AdminSignupResponse에 password 필드가 없고, from()에서도 매핑하지 않아 응답으로 나가지 않는다.

✅ 대응:

• AdminSignupResponse에 password가 없음을 코드로 설명
• “해시라도 응답에 포함하지 않는 것이 원칙”이라는 점을 확인

(추가로 안전하게 하려면 엔티티 password에 @JsonIgnore를 붙여 실수로 엔티티를 반환해도 노출되지 않게 막을 수도 있다.)

---

7. 회고

이번 인증 파트를 하면서 느낀 건, 기능 자체보다 팀 컨벤션에 맞춰 구조를 자연스럽게 끼워 넣는 것이 더 중요했다는 점이다.

• “내가 익숙한 구조”대로 만들면 빨리 만들 수 있지만,
• 팀 프로젝트는 결국 다 같이 유지보수할 수 있는 구조가 더 가치가 크다.

또한 로그인/회원가입은 실무에서도 민감한 영역이라

• 응답에 민감정보 포함 여부
• 실패 응답 메시지 정책
• 세션 보안 옵션(HttpOnly)
  같은 세부 포인트가 중요하다는 걸 체감했다.

---

8. 다음 할 일

인증(세션) 4개를 끝낸 뒤에는 관리자 기능이 본격적으로 남아있다.

• 관리자 승인/거부(슈퍼관리자 세션 기반)
• 내 프로필 조회/수정
• 비밀번호 변경
• 관리자 목록/검색/정렬/필터/페이징
• 관리자 상세/수정/삭제/역할 변경/상태 변경

다음 글에서는 “슈퍼관리자 승인 프로세스(승인대기 -> 활성)”을 구현하면서 생긴 이슈들을 정리할 예정이다.