[volume-1] 회원가입, 내 정보 조회, 포인트 조회, 포인트 충전 기능 구현 (#22)

* Feature/user (#1)

* test: User 단위테스트 추가

* feat: User 도메인 구현

* test: 회원 가입 통합테스트 추가

* feat: 회원가입 서비스 로직 구현

* test: 회원가입 E2E 테스트 추가

* feat: 회원가입 API 구현

* test: gender필드를 저장할 수 있도록 테스트 코드 수정

* refactor: User도메인에 성별 필드 추가

* test: 회원 정보 조회 통합 테스트 작성

* feat: 회원 정보 조회 서비스 로직 구현

* test: 회원 정보 조회 E2E 테스트 작성

* feat: 회원 정보 조회 API 추가

* Feature/point (#2)

* test: 회원가입 관련 테스트 코드가 SignUpFacade를 참조하도록 수정

* refactor: 회원가입을 처리하는 SignUpFacade 구현

* test: 포인트 조회 통합테스트 추가

* feat: 포인트 조회 서비스 로직 구현

* test: 포인트 조회 E2E 테스트 코드 추가

* feat: 포인트 조회 API 로직 추가

* test: 포인트 충전 단위 테스트 추가

* feat: 포인트 충전 도메인 로직 추가

* test: 포인트 충전 테스트 코드 추가

* feat: 포인트 충전 서비스 로직 추가

* test: 포인트 충전 E2E 테스트 코드 추가

* feat: 포인트 충전 API 추가

* docs: 회원가입, 내 정보 조회, 포인트 조회, 포인트 충전 기능 관련 docstring 추가 (#3)

Author: minor7295

apps/commerce-api/src/main/java/com/loopers/application/signup/SignUpFacade.java

@@ -0,0 +1,49 @@
+package com.loopers.application.signup;
+
+import com.loopers.domain.point.PointService;
+import com.loopers.domain.user.Gender;
+import com.loopers.domain.user.User;
+import com.loopers.domain.user.UserService;
+import jakarta.transaction.Transactional;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+/**
+ * 회원가입 파사드.
+ * <p>
+ * 회원가입 시 사용자 생성과 포인트 초기화를 조율하는 
+ * 애플리케이션 서비스입니다.
+ * 트랜잭션 경계를 관리하여 데이터 일관성을 보장합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@RequiredArgsConstructor
+@Component
+public class SignUpFacade {
+    private final UserService userService;
+
+    private final PointService pointService;
+
+    /**
+     * 회원가입을 처리합니다.
+     * <p>
+     * 사용자를 생성하고 초기 포인트(0)를 부여합니다.
+     * 전체 과정이 하나의 트랜잭션으로 처리됩니다.
+     * </p>
+     *
+     * @param userId 사용자 ID
+     * @param email 이메일 주소
+     * @param birthDateStr 생년월일 (yyyy-MM-dd)
+     * @param gender 성별
+     * @return 생성된 사용자 정보
+     * @throws com.loopers.support.error.CoreException 유효성 검증 실패 또는 중복 ID 존재 시
+     */
+    @Transactional
+    public SignUpInfo signUp(String userId, String email, String birthDateStr, Gender gender) {
+        User user = userService.create(userId, email, birthDateStr, gender);
+        pointService.create(user, 0L);
+        return SignUpInfo.from(user);
+    }
+}

apps/commerce-api/src/main/java/com/loopers/application/signup/SignUpInfo.java

@@ -0,0 +1,38 @@
+package com.loopers.application.signup;
+
+import com.loopers.domain.user.Gender;
+import com.loopers.domain.user.User;
+
+import java.time.LocalDate;
+
+/**
+ * 회원가입 결과 정보를 담는 레코드.
+ * <p>
+ * User 도메인 엔티티로부터 생성된 불변 데이터 전송 객체입니다.
+ * </p>
+ *
+ * @param id 사용자 엔티티 ID
+ * @param userId 사용자 ID
+ * @param email 이메일 주소
+ * @param birthDate 생년월일
+ * @param gender 성별
+ * @author Loopers
+ * @version 1.0
+ */
+public record SignUpInfo(Long id, String userId, String email, LocalDate birthDate, Gender gender) {
+    /**
+     * User 엔티티로부터 SignUpInfo를 생성합니다.
+     *
+     * @param user 변환할 사용자 엔티티
+     * @return 생성된 SignUpInfo
+     */
+    public static SignUpInfo from(User user) {
+        return new SignUpInfo(
+                user.getId(),
+                user.getUserId(),
+                user.getEmail(),
+                user.getBirthDate(),
+                user.getGender()
+        );
+    }
+}

apps/commerce-api/src/main/java/com/loopers/domain/point/Point.java

@@ -0,0 +1,84 @@
+package com.loopers.domain.point;
+
+import com.loopers.domain.BaseEntity;
+import com.loopers.domain.user.User;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import jakarta.persistence.*;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * 포인트 도메인 엔티티.
+ * <p>
+ * 사용자의 포인트 잔액을 관리하며, 포인트 충전 기능을 제공합니다.
+ * User와 일대일 관계를 맺고 있습니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@Entity
+@Table(name = "point")
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Getter
+public class Point extends BaseEntity {
+    @OneToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(
+        name = "user_id",
+        referencedColumnName = "id",
+        foreignKey = @ForeignKey(value = ConstraintMode.NO_CONSTRAINT)
+    )
+    private User user;
+
+    @Column(name = "balance", nullable = false)
+    private Long balance;
+
+    /**
+     * Point 인스턴스를 생성합니다.
+     *
+     * @param user 포인트 소유자
+     * @param balance 초기 잔액 (null인 경우 0으로 초기화)
+     */
+    public Point(User user, Long balance) {
+        this.user = user;
+        this.balance = balance != null ? balance : 0L;
+    }
+
+    /**
+     * Point 인스턴스를 생성하는 정적 팩토리 메서드.
+     *
+     * @param user 포인트 소유자
+     * @param balance 초기 잔액
+     * @return 생성된 Point 인스턴스
+     */
+    public static Point of(User user, Long balance) {
+        return new Point(user, balance);
+    }
+
+    /**
+     * 포인트를 충전합니다.
+     *
+     * @param amount 충전할 포인트 금액 (0보다 커야 함)
+     * @throws CoreException amount가 null이거나 0 이하일 경우
+     */
+    public void charge(Long amount) {
+        validateChargeAmount(amount);
+        this.balance += amount;
+    }
+
+    /**
+     * 충전 금액의 유효성을 검증합니다.
+     *
+     * @param amount 검증할 충전 금액
+     * @throws CoreException amount가 null이거나 0 이하일 경우
+     */
+    private void validateChargeAmount(Long amount) {
+        if (amount == null || amount <= 0) {
+            throw new CoreException(ErrorType.BAD_REQUEST, "포인트는 0보다 큰 값이어야 합니다.");
+        }
+    }
+}
+
+

apps/commerce-api/src/main/java/com/loopers/domain/point/PointRepository.java

@@ -0,0 +1,30 @@
+package com.loopers.domain.point;
+
+/**
+ * Point 엔티티에 대한 저장소 인터페이스.
+ * <p>
+ * 포인트 정보의 영속성 계층과의 상호작용을 정의합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+public interface PointRepository {
+    /**
+     * 포인트를 저장합니다.
+     *
+     * @param point 저장할 포인트
+     * @return 저장된 포인트
+     */
+    Point save(Point point);
+    
+    /**
+     * 사용자 ID로 포인트를 조회합니다.
+     *
+     * @param userId 조회할 사용자 ID
+     * @return 조회된 포인트, 없으면 null
+     */
+    Point findByUserId(String userId);
+}
+
+

apps/commerce-api/src/main/java/com/loopers/domain/point/PointService.java

@@ -0,0 +1,68 @@
+package com.loopers.domain.point;
+
+import com.loopers.domain.user.User;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 포인트 도메인 서비스.
+ * <p>
+ * 포인트 생성, 조회, 충전 등의 도메인 로직을 처리합니다.
+ * </p>
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+@RequiredArgsConstructor
+@Component
+public class PointService {
+    private final PointRepository pointRepository;
+
+    /**
+     * 새로운 포인트를 생성합니다.
+     *
+     * @param user 포인트 소유자
+     * @param balance 초기 잔액
+     * @return 생성된 포인트
+     */
+    public Point create(User user, Long balance) {
+        Point point = Point.of(user, balance);
+        return pointRepository.save(point);
+    }
+
+    /**
+     * 사용자 ID로 포인트를 조회합니다.
+     *
+     * @param userId 조회할 사용자 ID
+     * @return 조회된 포인트, 없으면 null
+     */
+    public Point findByUserId(String userId) {
+        return pointRepository.findByUserId(userId);
+    }
+
+    /**
+     * 사용자의 포인트를 충전합니다.
+     * <p>
+     * 트랜잭션 내에서 실행되어 데이터 일관성을 보장합니다.
+     * </p>
+     *
+     * @param userId 사용자 ID
+     * @param amount 충전할 금액 (0보다 커야 함)
+     * @return 충전된 포인트
+     * @throws CoreException 포인트를 찾을 수 없거나 충전 금액이 유효하지 않을 경우
+     */
+    @Transactional
+    public Point charge(String userId, Long amount) {
+        Point point = pointRepository.findByUserId(userId);
+        if (point == null) {
+            throw new CoreException(ErrorType.NOT_FOUND, "포인트를 찾을 수 없습니다.");
+        }
+        point.charge(amount);
+        return pointRepository.save(point);
+    }
+}
+
+

apps/commerce-api/src/main/java/com/loopers/domain/user/Gender.java

@@ -0,0 +1,14 @@
+package com.loopers.domain.user;
+
+/**
+ * 사용자의 성별을 나타내는 열거형.
+ *
+ * @author Loopers
+ * @version 1.0
+ */
+public enum Gender {
+    MALE,
+    FEMALE
+}
+
+