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

🧑‍💻 Admin 관리자 관리 기능(Read/Write) 구현 회고 (검색/정렬/필터/페이징 + 수정/역할/상태/삭제)

이번 팀 프로젝트에서 내가 맡은 파트는 관리자(Admin) 도메인이었다.
초반에는 인증(세션) 기능을 먼저 구현했고, 그 다음 단계로 “관리자 관리 기능” 체크리스트(READ/WRITE)를 끝까지 완성하는 게 목표였다.

---

✅ 내가 해야 했던 관리자 체크리스트

관리자 체크리스트에서 “Read/Write”는 아래 6개였다.

📌 READ

• 관리자 목록 조회(검색/정렬/필터/페이징)
• 관리자 상세 조회

📌 WRITE

• 관리자 정보 수정(이름/이메일/전화)
• 관리자 역할 변경
• 관리자 상태 변경
• 관리자 삭제(Soft Delete로 전환)

그리고 이 기능들은 승인/거부(approve/reject), 내 정보 조회/수정, 비밀번호 변경 같은 기존 기능과도 자연스럽게 연결된다.

---

🧩 내가 만든 구조(패키지/역할)

팀 컨벤션을 최대한 안 깨기 위해, admin 도메인은 아래처럼 정리했다.

admin
 ┣ controller
 ┣ dto
 ┃  ┣ request
 ┃  ┣ response
 ┃  ┗ session
 ┣ entity
 ┣ repository
 ┗ service
    ┣ AdminQueryService   (조회 전용)
    ┗ AdminCommandService (변경 전용)

왜 Query / Command를 나눴을까?

이건 “CQRS 맛보기” 방식이다.

• 조회(Read)는 검색 조건/정렬/페이징** 같은 “쿼리 최적화” 중심
• 변경(Write)는 비즈니스 규칙/상태 변경/검증** 중심

같은 서비스에 넣으면 코드가 섞여서 커지고, 팀 프로젝트에서는 충돌도 늘어난다.
그래서 아예 조회/수정 흐름을 분리했다.

---

READ 구현: 관리자 목록 조회 + 상세 조회

READ는 “관리자 목록 화면”을 만들기 위한 핵심 기능이다.
특히 백오피스는 데이터가 많아질수록 검색/필터/정렬/페이징이 중요하다.

---

1) 관리자 목록 조회에서 지원한 기능

지원 파라미터

• keyword: 이름/이메일 검색
• role: 역할 필터
• status: 상태 필터
• Pageable: 페이징 + 정렬

즉, 이런 요청이 가능하다:

• “운영 관리자만 보고 싶다”
• “승인대기 상태만 보고 싶다”
• “keyword=kim 으로 이름/이메일 검색”
• “페이지 2번, 10개씩”
• “createdAt desc 정렬”

---

2) Specification을 선택한 이유

관리자 목록 조회는 조건이 계속 변한다.

• keyword가 있을 수도 없을 수도
• role도 있을 수도 없을 수도
• status도 있을 수도 없을 수도

이걸 if문으로 QueryDSL 없이 처리하면:

• 메서드가 과도하게 늘어나거나
• 조건 조합마다 쿼리를 따로 만들게 된다.

그래서 JpaSpecificationExecutor + Specification으로
“조건 조합을 유연하게 붙이는 방식”을 택했다.

---

3) AdminSpecifications 예시

keyword 검색

• keyword가 없으면 null 반환 → 해당 조건은 적용 안 됨
• keyword가 있으면 name/email like 검색

public static Specification<Admin> keyword(String keyword) {
    if (keyword == null || keyword.isBlank()) return null;

    return (root, query, cb) -> cb.or(
            cb.like(cb.lower(root.get("adminName")), "%" + keyword.toLowerCase() + "%"),
            cb.like(cb.lower(root.get("email")), "%" + keyword.toLowerCase() + "%")
    );
}

---

4) AdminQueryService: 조회 전용 서비스

@Transactional(readOnly = true)
public Page<AdminListResponse> search(AdminSearchCondition condition, Pageable pageable) {
    Specification<Admin> spec = Specification.where(AdminSpecifications.keyword(condition.keyword()))
            .and(AdminSpecifications.role(condition.role()))
            .and(AdminSpecifications.status(condition.status()));

    return adminRepository.findAll(spec, pageable).map(AdminListResponse::from);
}

여기서 중요한 포인트

✅ @Transactional(readOnly = true)

• 조회는 readOnly로 실행 → 성능/안정성 측면에서 유리
• 팀원 리뷰로 “클래스 레벨 readOnly” 적용도 반영했음

✅ DTO 변환은 map(AdminListResponse::from)

• Entity를 그대로 반환하지 않고 응답 DTO로 변환
• 비밀번호 같은 민감 정보 노출 방지

---

5) Controller: searchAdmins

@GetMapping
public ApiResponse<Page<AdminListResponse>> searchAdmins(
        @ModelAttribute AdminSearchCondition condition,
        Pageable pageable,
        HttpSession session
) {
    requireSuperAdmin(session);
    return ApiResponse.success(HttpStatus.OK, adminQueryService.search(condition, pageable));
}

리뷰 반영 포인트 1) @ModelAttribute

처음엔 keyword, role, status를 각각 받아서 직접 condition을 new로 만들었다.
근데 팀원 리뷰로:

Spring MVC 바인딩을 활용하면 new로 생성하지 않아도 된다.

그래서 @ModelAttribute로 자동 바인딩을 적용했다.

---

리뷰 반영 포인트 2) import 누락 문제

내가 한 번 실수로 AdminStatus를 import 안 하고
풀패키지명을 그대로 적어버렸다.

@RequestParam com.example...AdminStatus status

리뷰에서 바로 지적 받았고, import로 정리했다.

---

WRITE 구현: 수정/역할/상태/삭제

WRITE는 “관리자 관리 화면에서 버튼 누르면 실행되는 기능”이다.

• 관리자 정보 수정 (이름/이메일/전화)
• 역할 변경
• 상태 변경
• 삭제

---

1) 관리자 정보 수정(updateAdmin)

핵심 검증: 이메일 중복 처리

수정은 가입과 달라서 기존 이메일이 그대로일 때는 중복 체크를 하면 안 됨

그래서 조건을 이렇게 넣었다:

if (!admin.getEmail().equals(request.email()) && adminRepository.existsByEmail(request.email())) {
    throw new CustomException(ErrorCode.ADMIN_EMAIL_DUPLICATED);
}

✅ 이메일이 변경될 때만 중복 체크

---

2) 역할 변경(changeRole)

@Transactional
public void changeRole(Long adminId, AdminRole role) {
    Admin admin = findAdmin(adminId);
    admin.changeRole(role);
}

• 실제 권한 체크는 Controller에서
• Entity는 상태 변경만 담당

---

3) 상태 변경(changeStatus)

@Transactional
public void changeStatus(Long adminId, AdminStatus status) {
    Admin admin = findAdmin(adminId);
    admin.changeStatus(status);
}

---

4) 삭제(deleteAdmin) - Soft Delete 전환

처음엔 물리 삭제를 했다.

adminRepository.delete(admin);

그런데 리뷰에서:

관리자 계정은 기록 추적이 중요한데 Hard Delete는 위험하다
status를 DELETED로 바꾸는 Soft Delete가 낫지 않나요?

그래서 Soft Delete로 변경했다.

public void delete() {
    this.status = AdminStatus.DELETED;
}

서비스는:

@Transactional
public void deleteAdmin(Long adminId) {
    Admin admin = findAdmin(adminId);
    admin.delete();
}

✅ DB row 삭제 X
✅ 상태로만 비활성 처리
✅ 운영/감사 로그 관점에서 안전

---

트러블슈팅/리뷰 반영 정리

이번 단계에서 기능 구현보다
리뷰 반영으로 코드 품질을 올린 경험이 컸다.

---

1) 세션 키 하드코딩 제거

처음에는 문자열로 작성했는데

session.getAttribute("LOGIN_SUPER_ADMIN")

리뷰로 “상수화” 권장 -> SessionConst로 통일했다.

---

2) Service의 트랜잭션 전략 개선

팀원 리뷰:

클래스 레벨에 readOnly=true를 걸고
수정 메서드에만 @Transactional 붙이면 누락 방지된다.

그래서:

• QueryService -> 클래스 레벨 readOnly
• CommandService -> 기본 readOnly + 쓰기만 @Transactional

---

3) 비밀번호 변경 검증 로직 위치 개선

서비스가 검증을 다 하면
Service가 도메인 규칙을 너무 많이 알게 된다.

그래서 Admin 엔티티로 책임을 넘겼다.

public void changePasswordWithValidation(...) {
   // current mismatch
   // new confirm mismatch
   // already used password
   // encode + 저장
}

도메인 규칙은 도메인에
서비스는 흐름만 제어

---

오늘 작업 요약

• 관리자 READ 기능 구현
  • 검색(keyword)
  • 필터(role, status)
  • 정렬/페이징(Pageable)
  • 목록/상세 조회 API
• 관리자 WRITE 기능 구현
  • 관리자 정보 수정
  • 역할 변경
  • 상태 변경
  • 삭제(Soft Delete 전환)
• 리뷰 반영
  • import 정리, 하드코딩 제거
  • @ModelAttribute 활용
  • 트랜잭션 readOnly 전략 개선
  • 비밀번호 변경 로직 도메인 위임

---

회고 (Keep / Problem / Try)

✅ Keep (만족)

• admin 패키지 구조를 팀 컨벤션에 맞춰 일관되게 유지
• Query/Command 분리로 충돌 가능성 감소
• 응답 포맷(ApiResponse)과 예외 포맷(ErrorCode) 유지

⚠️ Problem (불편)

• Soft Delete 적용 후 조회 제외 정책을 더 명확하게 해야 함
• URI prefix(/admins vs /api/admins) 통일 필요

🚀 Try (다음 개선)

• Soft Delete 된 계정은 기본 조회에서 제외되도록 정책 강화
• 관리 기능 인터셉터/ArgumentResolver로 권한 체크 공통화
• SuperAdmin 도메인 분리 구현 (ERD 기반)

https://documenter.getpostman.com/view/51133118/2sBXcGDzTV#086ea58f-0aa3-48f1-846e-e32e98d671df