Skip to content

Commit d9aace3

Browse files
chltmdgh522chltmdgh522
committed
[Docs] Add Swagger annotations and documentation for Point response DTOs
1 parent 3f58568 commit d9aace3

5 files changed

Lines changed: 149 additions & 29 deletions

File tree

‎src/main/java/boombimapi/domain/point/application/PointService.java‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,45 @@
11
package boombimapi.domain.point.application;
22

33
import boombimapi.domain.member.domain.entity.Member;
4-
import boombimapi.domain.point.presentation.dto.res.GetPointHistoryRes;
54
import boombimapi.domain.point.presentation.dto.res.GetPointRes;
65

7-
import java.util.List;
8-
6+
/**
7+
* PointService
8+
* 포인트 관련 핵심 기능 정의 인터페이스.
9+
* <p>
10+
* - 혼잡도 작성 시 포인트 적립<br>
11+
* - 포인트 및 이력 조회<br>
12+
* - 이벤트 응모 시 포인트 차감
13+
*/
914
public interface PointService {
1015

11-
// 혼잡도 작성 추가
16+
/**
17+
* 혼잡도 작성 시 포인트 적립.
18+
* <p>
19+
* 지정된 회원의 포인트 잔액을 증가시키고, 포인트 적립 이력을 기록한다.
20+
*
21+
* @param member 포인트를 적립할 회원 엔티티
22+
* @param balance 적립할 포인트 금액
23+
*/
1224
void earnPointForCongestion(Member member, Long balance);
1325

14-
// 조회
26+
/**
27+
* 회원 포인트 및 이력 조회.
28+
* <p>
29+
* 지정된 회원 ID로 현재 포인트 잔액과 거래 내역을 조회한다.
30+
*
31+
* @param memberId 조회할 회원의 ID
32+
* @return 회원의 포인트 잔액 및 거래 이력 응답 DTO
33+
*/
1534
GetPointRes getPointHistory(String memberId);
1635

17-
// 이벤트 응모할때 20포인트 삭제
36+
/**
37+
* 이벤트 응모 시 포인트 차감.
38+
* <p>
39+
* 회원의 포인트 잔액에서 지정 금액을 차감하고, 응모 이력 및 포인트 사용 이력을 기록한다.
40+
*
41+
* @param memberId 회원 ID
42+
* @param balance 차감할 포인트 금액
43+
*/
1844
void usePointForEvent(String memberId, Long balance);
1945
}

‎src/main/java/boombimapi/domain/point/application/impl/PointServiceImpl.java‎

Lines changed: 42 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@
1515
import boombimapi.domain.point.presentation.dto.res.GetPointHistoryRes;
1616
import boombimapi.domain.point.presentation.dto.res.GetPointRes;
1717
import boombimapi.global.infra.exception.error.BoombimException;
18-
import boombimapi.global.infra.exception.error.ErrorCode;
1918
import jakarta.transaction.Transactional;
2019
import lombok.RequiredArgsConstructor;
2120
import lombok.extern.slf4j.Slf4j;
@@ -26,6 +25,13 @@
2625

2726
import static boombimapi.global.infra.exception.error.ErrorCode.*;
2827

28+
/**
29+
* PointServiceImpl
30+
* 포인트 적립, 조회, 사용(이벤트 응모) 관련 비즈니스 로직을 담당한다.
31+
* - 혼잡도 작성 시 포인트 적립
32+
* - 포인트 및 이력 조회
33+
* - 이벤트 응모 시 포인트 차감 및 응모 이력 생성
34+
*/
2935
@Service
3036
@RequiredArgsConstructor
3137
@Transactional
@@ -37,14 +43,23 @@ public class PointServiceImpl implements PointService {
3743
private final MemberRepository memberRepository;
3844
private final EventCampaignRepository eventCampaignRepository;
3945

46+
/**
47+
* [혼잡도 작성 시 포인트 적립]
48+
* - 특정 회원의 포인트 잔액을 증가시키고, 적립 이력을 저장한다.
49+
* - 포인트가 존재하지 않으면 예외 발생.
50+
*
51+
* @param member 포인트를 적립할 회원
52+
* @param balance 적립할 포인트 금액
53+
*/
4054
@Override
4155
public void earnPointForCongestion(Member member, Long balance) {
4256
Point point = pointRepository.findByMember(member)
4357
.orElseThrow(() -> new BoombimException(POINT_NOT_EXIST));
4458

45-
59+
// 포인트 적립
4660
point.addBalance(balance);
4761

62+
// 포인트 이력 생성
4863
PointHistory pointHistory = PointHistory.builder()
4964
.member(member)
5065
.amount(balance)
@@ -56,6 +71,14 @@ public void earnPointForCongestion(Member member, Long balance) {
5671
pointHistoryRepository.save(pointHistory);
5772
}
5873

74+
/**
75+
* [회원 포인트 및 이력 조회]
76+
* - 회원의 현재 포인트 잔액과 포인트 거래 이력을 조회한다.
77+
* - 회원 또는 포인트 정보가 존재하지 않으면 예외 발생.
78+
*
79+
* @param memberId 조회할 회원 ID
80+
* @return 포인트 잔액 및 거래 이력 응답 DTO
81+
*/
5982
@Override
6083
public GetPointRes getPointHistory(String memberId) {
6184
Member member = memberRepository.findById(memberId)
@@ -65,17 +88,24 @@ public GetPointRes getPointHistory(String memberId) {
6588
.orElseThrow(() -> new BoombimException(POINT_NOT_EXIST));
6689

6790
List<PointHistory> pointHistories = pointHistoryRepository.findAllByMemberOrderByCreatedAtDesc(member);
68-
6991
List<GetPointHistoryRes> result = new ArrayList<>();
7092

7193
for (PointHistory pointHistory : pointHistories) {
7294
result.add(GetPointHistoryRes.of(pointHistory));
7395
}
7496

75-
7697
return GetPointRes.of(point.getBalance(), result);
7798
}
7899

100+
/**
101+
* [이벤트 응모 시 포인트 차감]
102+
* - 회원 포인트 잔액에서 지정 금액을 차감하고, 응모 이력을 저장한다.
103+
* - 응모 횟수가 5회를 초과하면 예외 발생.
104+
* - 포인트가 부족한 경우 예외 발생.
105+
*
106+
* @param memberId 회원 ID
107+
* @param balance 차감할 포인트 금액
108+
*/
79109
@Override
80110
public void usePointForEvent(String memberId, Long balance) {
81111
Member member = memberRepository.findById(memberId)
@@ -84,25 +114,29 @@ public void usePointForEvent(String memberId, Long balance) {
84114
Point point = pointRepository.findByMember(member)
85115
.orElseThrow(() -> new BoombimException(POINT_NOT_EXIST));
86116

117+
// 포인트 잔액 부족 예외
87118
if (point.getBalance() - balance < 0) {
88119
throw new BoombimException(INSUFFICIENT_POINT_FOR_EVENT);
89120
}
90121

122+
// 이벤트 응모 제한 초과 예외
91123
if (point.getApplyEventCount() == 5) {
92124
throw new BoombimException(EVENT_PARTICIPATION_LIMIT_EXCEEDED);
93125
}
94126

95-
point.subtractBalance(balance); // 포인트 감소
96-
point.addApplyEventCnt(); // 이벤트 횟수 추가
127+
// 포인트 차감 및 응모 횟수 증가
128+
point.subtractBalance(balance);
129+
point.addApplyEventCnt();
97130

98-
EventCampaign eventCampaign = EventCampaign
99-
.builder()
131+
// 이벤트 응모 이력 저장
132+
EventCampaign eventCampaign = EventCampaign.builder()
100133
.member(member)
101134
.eventCategory(EventCategory.EVENT_PARTICIPATION_TICKET)
102135
.build();
103136

104137
eventCampaignRepository.save(eventCampaign);
105138

139+
// 포인트 거래 이력 저장
106140
PointHistory pointHistory = PointHistory.builder()
107141
.member(member)
108142
.amount(balance)

‎src/main/java/boombimapi/domain/point/presentation/controller/PointController.java‎

Lines changed: 33 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package boombimapi.domain.point.presentation.controller;
22

33
import boombimapi.domain.point.application.PointService;
4-
import boombimapi.domain.point.presentation.dto.res.GetPointHistoryRes;
54
import boombimapi.domain.point.presentation.dto.res.GetPointRes;
65
import io.swagger.v3.oas.annotations.Operation;
76
import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -13,34 +12,58 @@
1312
import org.springframework.security.core.annotation.AuthenticationPrincipal;
1413
import org.springframework.web.bind.annotation.*;
1514

16-
import java.util.List;
17-
15+
/**
16+
* PointController
17+
* 포인트 관련 API 엔드포인트를 제공한다.
18+
* <p>
19+
* - 포인트 내역 조회<br>
20+
* - 이벤트 응모(포인트 차감)
21+
*/
1822
@RestController
1923
@RequestMapping("/api/point")
2024
@RequiredArgsConstructor
2125
@Slf4j
22-
@Tag(name = "Point", description = "point 전용 API")
26+
@Tag(name = "Point", description = "포인트 관련 API")
2327
public class PointController {
2428

2529
private final PointService pointService;
2630

27-
@Operation(summary = "포인트 내역 조회 API", description = "포인트 내역을 조회합니다.")
31+
/**
32+
* [GET] 포인트 내역 조회 API
33+
* <p>
34+
* - 회원의 포인트 잔액 및 거래 이력을 조회한다.<br>
35+
* - 인증된 사용자(@AuthenticationPrincipal)의 memberId를 기반으로 조회 수행.
36+
*
37+
* @param memberId 인증된 회원 ID
38+
* @return 포인트 잔액 및 거래 이력 응답 DTO
39+
*/
40+
@Operation(summary = "포인트 내역 조회 API", description = "회원의 포인트 잔액과 거래 이력을 조회합니다.")
2841
@ApiResponses(value = {
2942
@ApiResponse(responseCode = "200", description = "포인트 내역 조회 성공"),
43+
@ApiResponse(responseCode = "404", description = "포인트 정보가 존재하지 않음")
3044
})
3145
@GetMapping
3246
public ResponseEntity<GetPointRes> getPointHistory(@AuthenticationPrincipal String memberId) {
3347
return ResponseEntity.ok(pointService.getPointHistory(memberId));
3448
}
3549

36-
37-
@Operation(summary = "이벤트 응모 API", description = "이벤트 응모를 해서 포인트를 차감합니다.")
50+
/**
51+
* [PATCH] 이벤트 응모 API
52+
* <p>
53+
* - 회원이 이벤트에 응모하며, 포인트 20점을 차감한다.<br>
54+
* - 포인트 잔액 부족 또는 응모 횟수 초과 시 예외 발생.
55+
*
56+
* @param memberId 인증된 회원 ID
57+
* @return HTTP 200 OK (성공 시 바디 없음)
58+
*/
59+
@Operation(summary = "이벤트 응모 API", description = "이벤트에 응모하여 포인트를 차감합니다. (1회당 20포인트 차감)")
3860
@ApiResponses(value = {
39-
@ApiResponse(responseCode = "200", description = "포인트 차감 성공"),
40-
@ApiResponse(responseCode = "404", description = "포인트가 존재하지 않음"),
61+
@ApiResponse(responseCode = "200", description = "포인트 차감 및 이벤트 응모 성공"),
62+
@ApiResponse(responseCode = "400", description = "응모 횟수 초과 또는 포인트 부족"),
63+
@ApiResponse(responseCode = "404", description = "포인트 정보가 존재하지 않음")
4164
})
4265
@PatchMapping
43-
public ResponseEntity<Void> postPointEvnet(@AuthenticationPrincipal String memberId) {
66+
public ResponseEntity<Void> applyEvent(@AuthenticationPrincipal String memberId) {
4467
pointService.usePointForEvent(memberId, 20L);
4568
return ResponseEntity.ok().build();
4669
}

‎src/main/java/boombimapi/domain/point/presentation/dto/res/GetPointHistoryRes.java‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,52 @@
11
package boombimapi.domain.point.presentation.dto.res;
22

3-
import boombimapi.domain.point.domain.entity.Point;
43
import boombimapi.domain.point.domain.entity.PointHistory;
54
import boombimapi.domain.point.domain.entity.type.PointAction;
6-
import boombimapi.domain.point.domain.entity.type.PointCategory;
5+
import io.swagger.v3.oas.annotations.media.Schema;
76

87
import java.time.LocalDateTime;
98

9+
/**
10+
* GetPointHistoryRes
11+
* <p>
12+
* 포인트 거래 이력 응답 DTO.
13+
* <br>포인트 적립 또는 차감 내역을 반환한다.
14+
*/
15+
@Schema(description = "포인트 거래 이력 응답 DTO")
1016
public record GetPointHistoryRes(
17+
18+
@Schema(description = "포인트 거래 이력 ID", example = "101")
1119
Long pointHistoryId,
1220

21+
@Schema(description = "거래 후 잔액", example = "180")
1322
Long balance,
1423

24+
@Schema(description = "거래 금액 (적립/차감된 포인트)", example = "20")
1525
Long amount,
1626

27+
@Schema(description = "거래 발생 일시", example = "2025-10-16T12:45:00")
1728
LocalDateTime createdAt,
1829

30+
@Schema(description = "포인트 동작 유형 (EARN: 적립, USE: 사용)", example = "USE")
1931
PointAction pointAction,
2032

33+
@Schema(description = "포인트 카테고리 (예: EVENT, CONGESTION 등)", example = "EVENT")
2134
String pointCategory
2235
) {
23-
public static GetPointHistoryRes of(PointHistory pointHistory){
36+
/**
37+
* PointHistory 엔티티 → GetPointHistoryRes DTO 변환 메서드
38+
*
39+
* @param pointHistory 포인트 이력 엔티티
40+
* @return 변환된 응답 DTO
41+
*/
42+
public static GetPointHistoryRes of(PointHistory pointHistory) {
2443
return new GetPointHistoryRes(
2544
pointHistory.getId(),
2645
pointHistory.getBalance(),
2746
pointHistory.getAmount(),
2847
pointHistory.getCreatedAt(),
2948
pointHistory.getPointAction(),
30-
pointHistory.getPointCategory().getKey());
49+
pointHistory.getPointCategory().getKey()
50+
);
3151
}
3252
}

‎src/main/java/boombimapi/domain/point/presentation/dto/res/GetPointRes.java‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,31 @@
11
package boombimapi.domain.point.presentation.dto.res;
22

3+
import io.swagger.v3.oas.annotations.media.Schema;
4+
35
import java.util.List;
46

7+
/**
8+
* GetPointRes
9+
* <p>
10+
* 회원의 포인트 잔액과 거래 이력을 함께 반환하는 응답 DTO.
11+
*/
12+
@Schema(description = "회원 포인트 잔액 및 거래 이력 응답 DTO")
513
public record GetPointRes(
14+
15+
@Schema(description = "현재 포인트 잔액", example = "120")
616
Long point,
717

18+
@Schema(description = "포인트 거래 이력 리스트")
819
List<GetPointHistoryRes> getPointHistoryRes
920
) {
21+
/**
22+
* 포인트 및 거래 이력 DTO 생성 메서드
23+
*
24+
* @param point 포인트 잔액
25+
* @param getPointHistoryRes 포인트 거래 이력 리스트
26+
* @return GetPointRes 객체
27+
*/
1028
public static GetPointRes of(Long point, List<GetPointHistoryRes> getPointHistoryRes) {
1129
return new GetPointRes(point, getPointHistoryRes);
1230
}
13-
1431
}

0 commit comments

Comments
 (0)