[feat] 일반 구성원 추가 기능 구현 (#578)

* [refactor] MemberActivity 일반 구성원 aggregate 구성

* [feat] 기수 단건 조회 기능 추가

* [feat] 일반 구성원 활동 추가 기능 구현

* [test] Member 생성 팩토리 사용으로 테스트 수정

* [test] Member 도메인계층 테스트 생성, 일부 코드 가독성 개선

* [test] 구성원 추가 기능 테스트 보강

* [fix] 일반 구성원 추가 시 teamId 검증 및 저장 누락 수정

* [feat] 일반 구성원 추가 dto 검증 조건 추가

* [feat] 삭제된 구성원 존재시 복구하는 로직 추가

Author: kangkings

src/main/java/org/ject/support/admin/member/controller/AdminMemberSemesterApiSpec.java

@@ -0,0 +1,17 @@
+package org.ject.support.admin.member.controller;
+
+import org.ject.support.admin.member.dto.request.CreateMemberSemesterRequest;
+import org.springframework.web.bind.annotation.RequestBody;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+
+@Tag(name = "AdminMemberSemester", description = "일반 구성원 API")
+public interface AdminMemberSemesterApiSpec {
+	@Operation(
+		summary = "일반 구성원 추가",
+		description = "일반 구성원을 추가합니다."
+	)
+	void createAdminMemberSemester(@RequestBody @Valid CreateMemberSemesterRequest request);
+}

src/main/java/org/ject/support/admin/member/controller/AdminMemberSemesterController.java

@@ -0,0 +1,24 @@
+package org.ject.support.admin.member.controller;
+
+import org.ject.support.admin.member.dto.request.CreateMemberSemesterRequest;
+import org.ject.support.admin.member.service.AdminMemberUseCase;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/admin/members/semester")
+@RequiredArgsConstructor
+public class AdminMemberSemesterController implements AdminMemberSemesterApiSpec {
+
+	private final AdminMemberUseCase adminMemberUsecase;
+
+	//일반 구성원 추가
+	@Override
+	@PostMapping
+	public void createAdminMemberSemester(CreateMemberSemesterRequest request) {
+		adminMemberUsecase.createMemberSemester(request);
+	}
+}

src/main/java/org/ject/support/admin/member/dto/request/CreateMemberSemesterRequest.java

@@ -0,0 +1,62 @@
+package org.ject.support.admin.member.dto.request;
+
+import java.util.List;
+
+import org.ject.support.domain.member.CareerDetails;
+import org.ject.support.domain.member.ExperiencePeriod;
+import org.ject.support.domain.member.JobFamily;
+import org.ject.support.domain.member.Region;
+import org.ject.support.domain.recruit.domain.RecruitTypeDetail;
+
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+
+public record CreateMemberSemesterRequest(
+
+	/*
+	필수 항목: 이름, 전화번호, 이메일, 직군(포지션), 지원자 신분, 모집단위, 기수id
+	선택 항목: 팀id, 비고, 관심도메인, 거주지역, 직무 관련 경험
+	 */
+	@NotBlank(message = "이름을 입력해주세요")
+	@Size(max = 20, message = "이름은 20자 이하로 입력해주세요.")
+	@Pattern(regexp = "^[^\\s]+$", message = "이름은 공백없이 입력해주세요")
+	String name,
+
+	@NotBlank(message = "이메일을 입력해주세요.")
+	@Email(message = "올바른 이메일 형식이 아닙니다.")
+	@Size(max = 30, message = "이메일은 30자 이하로 입력해주세요.")
+	String email,
+
+	@NotBlank(message = "전화번호를 입력해주세요")
+	@Pattern(regexp = "^010\\d{8}$", message = "010으로 시작하는 11자리 숫자를 입력해주세요.")
+	String phoneNumber,
+
+	@NotNull(message = "포지션을 선택해주세요")
+	JobFamily jobFamily,
+
+	@NotNull(message = "모집 단위를 선택해주세요")
+	RecruitTypeDetail recruitTypeDetail,
+
+	@NotNull(message = "지원자 신분을 선택해주세요")
+	CareerDetails careerDetails,
+
+	@NotNull(message = "기수를 선택해주세요")
+	Long semesterId,
+
+	Long teamId,
+
+	ExperiencePeriod experiencePeriod,
+
+	@Size(max = 100, message = "비고는 100자 이하로 입력해주세요.")
+	String memo,
+
+	@Size(min = 1, max = 3, message = "관심 도메인은 최소 1개부터 최대 3개까지 선택 가능합니다.")
+	List<String> interestedDomains,
+
+	Region region
+
+) {
+}

src/main/java/org/ject/support/admin/member/service/AdminMemberActivityService.java

@@ -0,0 +1,46 @@
+package org.ject.support.admin.member.service;
+
+import org.ject.support.admin.member.dto.request.CreateMemberSemesterRequest;
+import org.ject.support.domain.member.MemberType;
+import org.ject.support.domain.member.entity.MemberActivity;
+import org.ject.support.domain.member.exception.MemberException;
+import org.ject.support.domain.member.repository.MemberActivityRepository;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+
+import static org.ject.support.domain.member.exception.MemberErrorCode.ALREADY_EXIST_MEMBER_SEMESTER_ACTIVITY;
+
+@Service
+@RequiredArgsConstructor
+public class AdminMemberActivityService {
+
+	private final MemberActivityRepository memberActivityRepository;
+
+
+	public void createMemberSemesterActivity(CreateMemberSemesterRequest request, Long memberId) {
+		// 추가하려는 대상이 같은 기수에 이미 등록되어있는지 중복 검증
+		validateDuplicateSemesterActivity(memberId, request.semesterId());
+
+		// MemberActivity생성, 내부에서 MemberSemester 생성
+		MemberActivity memberActivity = MemberActivity.createSemesterActivity(
+			memberId,
+			request.jobFamily(),
+			request.recruitTypeDetail(),
+			request.careerDetails(),
+			request.experiencePeriod(),
+			request.memo(),
+			request.semesterId(),
+			request.teamId()
+		);
+
+		memberActivityRepository.save(memberActivity);
+	}
+
+	// 동일 기수 일반 구성원 활동 중복 검증
+	private void validateDuplicateSemesterActivity(Long memberId, Long semesterId) {
+		if (memberActivityRepository.existsSemesterActivity(memberId, MemberType.SEMESTER, semesterId)) {
+			throw new MemberException(ALREADY_EXIST_MEMBER_SEMESTER_ACTIVITY);
+		}
+	}
+}

src/main/java/org/ject/support/admin/member/service/AdminMemberService.java

@@ -0,0 +1,65 @@
+package org.ject.support.admin.member.service;
+
+import org.ject.support.admin.member.dto.request.CreateMemberSemesterRequest;
+import org.ject.support.domain.member.entity.Member;
+import org.ject.support.domain.member.repository.MemberRepository;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+
+@Service
+@RequiredArgsConstructor
+public class AdminMemberService {
+
+	private final MemberRepository memberRepository;
+
+	/*
+	(2026.06.23)
+	1. email로 삭제 포함 구성원 신상 전부 조회
+	2. 삭제된 구성원 존재시: isDeleted를 복구하고 새로 입력받은 값으로 덮어쓰기
+	3. 활성 구성원 존재시: 기존 값 재사용
+	4. 미 존재시: 새로 생성
+	 */
+
+	// email 기준 구성원 조회 또는 신상정보 생성
+	public Long findOrCreateMember(CreateMemberSemesterRequest request) {
+		return memberRepository.findByEmailIncludingDeleted(request.email())
+			.map(member -> useExistingMember(member, request))
+			.orElseGet(() -> createMember(request));
+	}
+
+	// 기존 구성원 상태에 따라 재사용 또는 복구
+	private Long useExistingMember(Member member, CreateMemberSemesterRequest request) {
+		if (member.getIsDeleted()) {
+			return restoreMember(member, request);
+		}
+
+		return member.getId();
+	}
+
+	// 삭제된 구성원 신상정보 갱신 후 복구
+	private Long restoreMember(Member member, CreateMemberSemesterRequest request) {
+		member.restore(
+			request.name(),
+			request.phoneNumber(),
+			request.interestedDomains(),
+			request.region()
+		);
+		return member.getId();
+	}
+
+	// 구성원 신상정보 생성
+	private Long createMember(CreateMemberSemesterRequest request) {
+		Member member = Member.create(
+			request.name(),
+			request.email(),
+			request.phoneNumber(),
+			request.interestedDomains(),
+			request.region()
+		);
+
+		Member savedMember = memberRepository.save(member);
+		return savedMember.getId();
+	}
+
+}

src/main/java/org/ject/support/admin/member/service/AdminMemberTeamService.java

@@ -0,0 +1,20 @@
+package org.ject.support.admin.member.service;
+
+import java.util.List;
+
+import org.ject.support.domain.member.repository.TeamRepository;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+
+@Service
+@RequiredArgsConstructor
+public class AdminMemberTeamService {
+
+	private final TeamRepository teamRepository;
+
+	// 기수에 속한 팀 ID 목록 조회
+	public List<Long> getTeamIdsBySemesterId(Long semesterId) {
+		return teamRepository.findIdsBySemesterId(semesterId);
+	}
+}

src/main/java/org/ject/support/admin/member/service/AdminMemberUseCase.java

@@ -0,0 +1,46 @@
+package org.ject.support.admin.member.service;
+
+import static org.ject.support.domain.member.exception.MemberErrorCode.NOT_FOUND_TEAM_OF_SEMESTER;
+
+import org.ject.support.admin.member.dto.request.CreateMemberSemesterRequest;
+import org.ject.support.domain.member.exception.MemberException;
+import org.ject.support.domain.recruit.service.SemesterInquiryUsecase;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import lombok.RequiredArgsConstructor;
+
+@Service
+@RequiredArgsConstructor
+public class AdminMemberUseCase {
+
+	private final AdminMemberService adminMemberService;
+	private final AdminMemberActivityService adminMemberActivityService;
+	private final AdminMemberTeamService adminMemberTeamService;
+	private final SemesterInquiryUsecase semesterInquiryUsecase;
+
+	// 일반 구성원 생성 흐름 처리
+	@Transactional
+	public void createMemberSemester(CreateMemberSemesterRequest request) {
+		// 기수 유효성 검증
+		semesterInquiryUsecase.getSemester(request.semesterId());
+		validateTeam(request.semesterId(), request.teamId());
+
+		// email 기준 기존 Member 조회 또는 신규 생성
+		Long memberId = adminMemberService.findOrCreateMember(request);
+
+		// memberId 기준 MemberActivity와 MemberSemester 생성 및 저장
+		adminMemberActivityService.createMemberSemesterActivity(request, memberId);
+	}
+
+	// 선택한 팀의 기수 소속 검증
+	private void validateTeam(Long semesterId, Long teamId) {
+		if (teamId == null) {
+			return;
+		}
+
+		if (!adminMemberTeamService.getTeamIdsBySemesterId(semesterId).contains(teamId)) {
+			throw new MemberException(NOT_FOUND_TEAM_OF_SEMESTER);
+		}
+	}
+}

src/main/java/org/ject/support/domain/member/entity/Member.java

@@ -28,7 +28,7 @@
 @SQLRestriction("is_deleted = false")
 @Entity
 @Getter
-@Builder
+@Builder(access = AccessLevel.PRIVATE)
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 @NoArgsConstructor(access = AccessLevel.PROTECTED)
 public class Member extends BaseTimeEntity {
@@ -61,4 +61,34 @@ public class Member extends BaseTimeEntity {
     @Builder.Default
     private Boolean isDeleted = false;
 
+
+    public static Member create(
+        String name,
+        String email,
+        String phoneNumber,
+        List<String> interestedDomains,
+        Region region
+    ){
+        return Member.builder()
+            .name(name)
+            .email(email)
+            .phoneNumber(phoneNumber)
+            .region(region)
+            .interestedDomains(interestedDomains)
+            .build();
+    }
+
+    // 삭제된 구성원 정보가 있는 경우 복구한 뒤 새로 입력한 값으로 덮어쓰기
+    public void restore(
+        String name,
+        String phoneNumber,
+        List<String> interestedDomains,
+        Region region
+    ) {
+        this.isDeleted = false;
+        this.name = name;
+        this.phoneNumber = phoneNumber;
+        this.interestedDomains = interestedDomains;
+        this.region = region;
+    }
 }

src/main/java/org/ject/support/domain/member/entity/MemberActivity.java

@@ -1,12 +1,15 @@
 package org.ject.support.domain.member.entity;
 
+import jakarta.persistence.CascadeType;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
 import jakarta.persistence.EnumType;
 import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
+import jakarta.persistence.OneToOne;
 import jakarta.persistence.Table;
 import java.time.LocalDate;
 
@@ -19,11 +22,13 @@
 import org.ject.support.domain.member.ExperiencePeriod;
 import org.ject.support.domain.member.JobFamily;
 import org.ject.support.domain.member.MemberType;
+import org.ject.support.domain.member.exception.MemberErrorCode;
+import org.ject.support.domain.member.exception.MemberException;
 import org.ject.support.domain.recruit.domain.RecruitTypeDetail;
 
 @Entity
 @Getter
-@Builder
+@Builder(access = AccessLevel.PRIVATE)
 @Table(name = "member_activity")
 @SQLDelete(sql = "UPDATE member_activity SET is_deleted = true WHERE id = ?")
 @SQLRestriction("is_deleted = false")
@@ -73,4 +78,37 @@ public class MemberActivity extends BaseTimeEntity {
     @Column(name = "recruit_type_detail", length = 45, nullable = false)
     @Enumerated(EnumType.STRING)
     private RecruitTypeDetail recruitTypeDetail;
+
+    @OneToOne(mappedBy = "memberActivity", fetch = FetchType.LAZY, orphanRemoval = true, cascade = CascadeType.ALL)
+    private MemberSemester memberSemester;
+
+    // 일반 구성원 활동과 관리 항목 생성
+    public static MemberActivity createSemesterActivity(
+        Long memberId,
+        JobFamily jobFamily,
+        RecruitTypeDetail recruitTypeDetail,
+        CareerDetails careerDetails,
+        ExperiencePeriod experiencePeriod,
+        String memo,
+        Long semesterId,
+        Long teamId
+    ){
+        MemberActivity memberActivity = MemberActivity.builder()
+            .memberId(memberId)
+            .memberType(MemberType.SEMESTER)
+            .jobFamily(jobFamily)
+            .recruitTypeDetail(recruitTypeDetail)
+            .careerDetails(careerDetails)
+            .experiencePeriod(experiencePeriod)
+            .memo(memo)
+            .build();
+        //애그리거트 루트인 MemberActivity쪽에서 식별 관계인 엔티티 생성 책임
+        //MemberSemester는 MemberActivity없이 단독으로 사용되지 않음
+        memberActivity.memberSemester = MemberSemester.create(memberActivity, semesterId, teamId);
+        return memberActivity;
+    }
+
+    //Todo: 메이커스 구성원 활동과 관리 항목 생성
+
+    //Todo: 운영 서포터즈 구성원 활동과 관리 항목 생성
 }