Skip to content

Commit d3edbe6

Browse files
toongritoongri
committed
feat: add documentation for week 2 requirements, diagrams, and ERD
1 parent 9aef292 commit d3edbe6

File tree

4 files changed

+569
-0
lines changed

4 files changed

+569
-0
lines changed

‎docs/week2/01-requirements.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# 요구사항 명세서 (Requirements Specification)
2+
3+
## 1. 개요
4+
5+
### 1.1 태스크 목표 정의
6+
7+
#### 해결하고자 하는 문제
8+
- 기존 대형 이커머스는 상품 위주의 탐색 경험으로, 사용자가 좋아하는 상품을 발견하고 모으는 즐거움이 부족
9+
- 구매 시 매번 결제 정보를 입력해야 하는 번거로움으로 인한 구매 전환 장벽 존재
10+
- 사용자의 취향과 관심사를 반영한 개인화된 쇼핑 경험 부재
11+
12+
#### 태스크 목표
13+
- 좋아요 기능을 통해 사용자가 관심 있는 상품을 손쉽게 큐레이션할 수 있는 환경 제공
14+
- 포인트 선충전 모델로 구매 전환 장벽을 낮추고 빠른 결제 경험 제공
15+
- 사용자 행동 데이터(좋아요, 구매 패턴)를 수집하여 향후 추천/랭킹 시스템 구축 기반 마련
16+
17+
#### 2주차 구현 범위
18+
본 명세서는 다음 기능의 설계 및 구현을 다룹니다:
19+
- **상품 탐색**: 상품 목록 조회, 상품 상세 조회, 브랜드 조회
20+
- **좋아요 관리**: 좋아요 등록/취소, 좋아요한 상품 목록 조회 (멱등성 보장)
21+
- **주문 처리**: 주문 생성 및 결제 (재고 차감, 포인트 차감, 외부 시스템 연동)
22+
23+
#### 제외 범위
24+
다음 기능은 1주차에서 구현 완료되었으며, 본 명세서에서는 다루지 않습니다:
25+
- 회원가입 및 내 정보 조회
26+
- 포인트 충전 및 보유 포인트 조회
27+
- 인증/인가 (X-USER-ID 헤더 기반 식별)
28+
29+
### 1.2 기대 효과
30+
31+
- **사용자 재방문율 증가**: 좋아요 기능을 통한 관심 상품 큐레이션으로 재방문 유도
32+
- **전환율 향상**: 포인트 선충전 모델로 구매 시 결제 단계를 최소화하여 전환 장벽 감소
33+
- **데이터 기반 확장 가능성**: 사용자 행동 데이터를 수집하여 향후 추천/랭킹 시스템 구축 기반 마련
34+
35+
---
36+
37+
## 2. 도메인 용어집
38+
39+
### Products 도메인
40+
41+
**핵심 개념:**
42+
- **브랜드 (Brand)**: 상품을 생산하고 제공하는 패션 브랜드 또는 제조사
43+
- **상품 (Product)**: 구매 가능한 개별 패션 아이템. 가격, 소속 브랜드, 재고 수량 정보를 포함
44+
45+
**상태:**
46+
- **판매중 (AVAILABLE)**: 재고가 있어 구매 가능한 상태
47+
- **품절 (OUT_OF_STOCK)**: 재고가 소진되어 구매 불가능한 상태
48+
- **단종 (DISCONTINUED)**: 더 이상 판매하지 않는 상태
49+
50+
### Likes 도메인
51+
52+
**핵심 개념:**
53+
- **좋아요 (ProductLike)**: 사용자가 특정 상품에 대해 표시하는 관심 표현. 사용자는 각 상품에 최대 1개의 좋아요만 등록 가능
54+
55+
### Orders 도메인
56+
57+
**핵심 개념:**
58+
- **주문 (Order)**: 사용자가 특정 상품의 구매를 요청하고 결제를 완료한 거래 단위
59+
- **결제 (Payment)**: 주문에 대한 포인트 차감 및 결제 처리 정보
60+
61+
**주문 상태:**
62+
- **접수됨 (PLACED)**: 주문이 시스템에 접수된 상태
63+
- **결제 완료됨 (PAID)**: 결제가 완료되어 처리 대기 중인 상태
64+
65+
**결제 상태:**
66+
- **준비 (READY)**: 결제가 준비된 상태
67+
- **완료 (PAID)**: 결제가 완료된 상태
68+
69+
**행위:**
70+
- **주문하다 (place)**: 사용자가 상품을 주문하는 행위
71+
- **결제하다 (pay)**: 주문에 대한 결제를 완료하는 행위
72+
73+
### 공통
74+
75+
**핵심 개념:**
76+
- **사용자 (User)**: 감성 이커머스 플랫폼에 가입하여 상품을 탐색하고 구매하는 개인. "구매자"와 동일한 의미로 사용
77+
- **포인트 (Point)**: 사용자가 사전에 충전하여 보유한 가상 화폐 잔액. 상품 구매 시 결제 수단으로 사용됨
78+
79+
---
80+
81+
## 3. 유스케이스 명세
82+
83+
### 3.1 주요 사용자
84+
- **구매자**: 패션 상품을 탐색하고 구매하는 일반 사용자
85+
86+
### 3.2 구매자의 목표
87+
88+
1. **관심 있는 상품 탐색 및 좋아요로 관리하기**
89+
- 다양한 상품 둘러보기
90+
- 마음에 드는 상품 좋아요로 저장
91+
- 좋아요 한 상품 다시 보기
92+
93+
2. **상품 주문 및 결제하기**
94+
- 원하는 상품 주문 요청
95+
- 포인트 차감 및 재고 확보
96+
- 주문 완료 처리
97+
98+
### 3.3 유스케이스 시나리오
99+
100+
#### 유스케이스 1: 관심 있는 상품 탐색 및 좋아요로 관리하기
101+
102+
**주요 시나리오:**
103+
1. 사용자가 상품 목록 화면에 진입한다
104+
2. 시스템은 최신 등록된 상품 목록을 조회한다 (각 상품의 좋아요 수 포함)
105+
3. 사용자가 관심 있는 상품의 상세 정보를 조회한다 (좋아요 수 포함)
106+
4. 사용자가 해당 상품에 좋아요를 등록한다
107+
5. 시스템은 좋아요를 저장하고 해당 상품의 좋아요 수를 1 증가시킨다
108+
6. 사용자가 "내가 좋아요 한 상품 목록"을 조회하여 저장한 상품들을 확인한다
109+
110+
**대체 시나리오 1 (브랜드별 상품 필터링):**
111+
1. 사용자가 브랜드 정보를 조회한다
112+
2. 사용자가 특정 브랜드를 선택하여 해당 브랜드의 상품만 필터링한다
113+
3. 시스템은 선택된 브랜드의 상품 목록을 조회하여 반환한다
114+
4. 해당 브랜드에 상품이 없으면 빈 목록을 표시한다
115+
116+
**대체 시나리오 2 (정렬 기준 변경):**
117+
1. 사용자가 정렬 기준을 선택한다 (최신순/가격낮은순/인기순)
118+
2. 시스템은 선택된 기준으로 상품을 정렬하여 반환한다
119+
120+
**대체 시나리오 3 (좋아요 중복 등록 - 멱등성):**
121+
1. 사용자가 이미 좋아요를 등록한 상품에 다시 좋아요를 등록한다
122+
2. 시스템은 오류 없이 성공 응답을 반환하며, 좋아요 상태는 변경되지 않는다
123+
3. 상품의 좋아요 수는 증가하지 않는다
124+
125+
**대체 시나리오 4 (좋아요 취소):**
126+
1. 사용자가 좋아요를 등록한 상품의 좋아요를 취소한다
127+
2. 시스템은 좋아요를 제거하고 해당 상품의 좋아요 수를 1 감소시킨다
128+
3. 사용자가 "내가 좋아요 한 상품 목록"에서 해당 상품이 제거된 것을 확인한다
129+
130+
**대체 시나리오 5 (좋아요 취소 중복 요청 - 멱등성):**
131+
1. 사용자가 좋아요를 등록하지 않은 상품에 좋아요 취소를 요청한다
132+
2. 시스템은 오류 없이 성공 응답을 반환하며, 좋아요 상태는 변경되지 않는다
133+
3. 상품의 좋아요 수는 감소하지 않는다
134+
135+
**예외 시나리오 1 (존재하지 않는 상품):**
136+
1. 사용자가 존재하지 않는 상품에 좋아요를 등록하거나 상세 조회를 시도한다
137+
2. 시스템은 "상품을 찾을 수 없음" 오류를 반환한다
138+
139+
**예외 시나리오 2 (잘못된 정렬 기준):**
140+
1. 사용자가 지원하지 않는 정렬 기준을 입력한다
141+
2. 시스템은 "지원하지 않는 정렬 기준" 오류를 반환한다
142+
143+
---
144+
145+
#### 유스케이스 2: 상품 주문 및 결제하기
146+
147+
**주요 시나리오:**
148+
1. 사용자가 원하는 상품을 선택하고 주문을 요청한다
149+
2. 시스템은 상품 재고를 차감한다
150+
3. 시스템은 주문을 접수 상태로 생성한다
151+
4. 시스템은 결제를 준비 상태로 생성한다
152+
5. 시스템은 사용자의 포인트를 차감한다
153+
6. 시스템은 외부 PG 시스템에 결제 요청을 전송한다
154+
7. 사용자에게 주문 생성 완료 응답을 반환한다 (결제 준비 상태)
155+
156+
**대체 시나리오 1 (전액 포인트 결제):**
157+
1. 사용자가 상품 주문을 요청한다
158+
2. 시스템은 재고를 차감한다
159+
3. 시스템은 주문을 접수 상태로 생성한다
160+
4. 시스템은 결제를 준비 상태로 생성한다
161+
5. 시스템은 포인트를 차감한다 (전액 결제 가능)
162+
6. 외부 PG 호출을 스킵하고 결제를 완료 처리한다
163+
7. 사용자에게 주문 완료 응답을 반환한다
164+
165+
**예외 시나리오 1 (재고 부족):**
166+
1. 사용자가 상품 주문을 요청한다
167+
2. 시스템이 재고 차감을 시도하지만 재고가 부족하여 실패한다
168+
3. 시스템은 "재고 부족" 오류를 반환한다
169+
4. 주문이 생성되지 않으며, 포인트도 차감되지 않는다
170+
171+
**예외 시나리오 2 (포인트 부족):**
172+
1. 사용자가 상품 주문을 요청한다
173+
2. 시스템이 재고를 차감한다
174+
3. 시스템이 포인트 차감을 시도하지만 잔액이 부족하여 실패한다
175+
4. 시스템은 트랜잭션을 롤백한다
176+
5. 시스템은 "포인트 부족" 오류를 반환한다
177+
6. 주문 및 결제가 생성되지 않는다
178+
179+
**예외 시나리오 3 (외부 PG 시스템 실패):**
180+
1. 사용자가 상품 주문을 요청한다
181+
2. 시스템이 재고, 포인트 차감 및 주문/결제 생성을 시도한다
182+
3. 외부 PG 시스템에 결제 요청 전송 시 오류가 발생한다
183+
4. 시스템은 트랜잭션을 롤백한다
184+
5. 시스템은 "결제 요청 실패" 오류를 반환한다
185+
6. 주문 및 결제가 생성되지 않으며, 재고와 포인트도 차감되지 않는다
186+
187+
---
188+
189+
## 4. 기술 요구사항
190+
191+
### 4.1 데이터 정합성
192+
193+
**주문 처리 (재고/포인트 차감)**
194+
- 강한 일관성 (Strong Consistency) 필요
195+
- 재고 차감, 포인트 차감, 주문 생성, 결제 생성이 모두 성공하거나 모두 실패해야 함
196+
- 트랜잭션 롤백을 통한 원자성 보장
197+
198+
**좋아요 카운트**
199+
- 최종 일관성 (Eventual Consistency) 허용
200+
- 좋아요 수는 대략적인 인기도 지표로, 실시간 정확성 불필요
201+
- 사용자의 좋아요 등록/취소 상태는 즉시 반영되어야 함
202+
203+
### 4.2 에러 처리
204+
205+
**주문 생성 실패**
206+
- 재고 부족: 재고 부족 정보 제공
207+
- 포인트 부족: 포인트 잔액 부족 정보 제공
208+
- 외부 PG 시스템 실패: 결제 요청 실패 정보 전달 (전체 롤백)
209+
210+
**좋아요 처리**
211+
- 존재하지 않는 상품: "상품을 찾을 수 없음" 명확히 구분
212+
- 멱등성 보장: 중복 요청에도 사용자에게 성공 응답 전달

‎docs/week2/02-sequence-diagrams.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# 시퀀스 다이어그램 (Sequence Diagrams)
2+
3+
본 문서는 감성 이커머스의 핵심 유스케이스에 대한 객체 간 상호작용을 시각화합니다.
4+
5+
---
6+
7+
## 1. 상품 목록 조회
8+
9+
사용자가 상품 목록을 조회하는 시나리오입니다. 각 상품의 좋아요 수를 함께 조회하여 인기도를 표시합니다.
10+
11+
![img](https://github.com/user-attachments/assets/753a69c5-574c-43c8-a10b-9ca79f40ca43)
12+
13+
**주요 흐름:**
14+
15+
1. 사용자가 페이징, 정렬 기준과 함께 상품 목록 조회를 요청
16+
2. Facade가 정렬 기준에 따라 상품 목록을 조회 (Slice 반환)
17+
3. 조회된 상품 ID 목록으로 좋아요 수를 일괄 조회
18+
4. Facade에서 상품 정보와 좋아요 수를 조합하여 ProductInfo 리스트 생성
19+
20+
**고려사항:**
21+
22+
- ProductLikeCount를 일괄 조회하여 N+1 문제 방지
23+
- 정렬 기준: latest(최신순), price_asc(가격낮은순), likes_desc(인기순)
24+
25+
---
26+
27+
## 2. 상품 좋아요 등록
28+
29+
사용자가 상품에 좋아요를 등록하는 시나리오입니다. 멱등성을 보장하여 중복 등록 시에도 오류 없이 처리됩니다.
30+
31+
![img_1.png](https://github.com/user-attachments/assets/9aafe5bc-3edb-401d-adb8-27e3359ab681)
32+
33+
**주요 흐름:**
34+
35+
1. 사용자가 특정 상품에 좋아요 등록 요청
36+
2. Facade가 기존 좋아요 존재 여부 확인
37+
3. 이미 존재하면 아무 작업 없이 성공 응답 (멱등성 보장)
38+
4. 존재하지 않으면 ProductLike 생성 및 저장
39+
5. ProductLikeCountRepository의 increment()로 좋아요 수 증가
40+
6. 성공 응답
41+
42+
**고려사항:**
43+
44+
- 멱등성 보장: 중복 등록 시도에도 오류 없이 성공 응답
45+
- 좋아요 수 증가는 Repository 레벨에서 원자적으로 처리
46+
47+
---
48+
49+
## 3. 주문 생성 및 결제
50+
51+
사용자가 상품을 주문하고 결제하는 시나리오입니다. 전액 포인트 결제 여부에 따라 외부 PG 호출 여부가 결정됩니다.
52+
53+
![img_2.png](https://github.com/user-attachments/assets/bd4f2c97-399c-4af9-8cd1-8759cb8ee232)
54+
55+
**주요 흐름:**
56+
57+
1. 재고를 비관적 락으로 조회하여 차감 (StockManager)
58+
2. 주문을 접수 상태(PLACED)로 생성 (Order.place)
59+
3. 포인트를 차감하고 이력 기록 (PointAccountManager)
60+
4. **결제 처리 (PaymentManager.pay)**
61+
- Payment 생성 (READY 상태)
62+
- 결제 처리 필요 여부 판단 (Payment.needsExternalPayment())
63+
- 외부 결제 필요: PG 시스템에 결제 요청 전송
64+
- 전액 포인트: 즉시 결제 완료 처리 (PAID 상태)
65+
5. 성공 시 트랜잭션 커밋, 실패 시 자동 롤백
66+
67+
**고려사항:**
68+
69+
- 재고 차감은 비관적 락을 통한 동시성 제어
70+
- 전액 포인트 결제 여부는 Payment 도메인 객체가 판단 (actualPaymentAmount == 0)
71+
- 재고 부족, 포인트 부족, PG 실패 시 트랜잭션 롤백으로 일관성 보장

‎docs/week2/03-class-diagram.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# 클래스 다이어그램 (Class Diagram)
2+
3+
본 문서는 감성 이커머스의 도메인 모델 구조를 시각화합니다.
4+
5+
---
6+
7+
## 1. Products 도메인
8+
9+
![img_3.png](https://github.com/user-attachments/assets/7aaa6268-7eeb-42e5-a30f-b324ba849468)
10+
11+
**주요 구조:**
12+
13+
- **Brand**: 브랜드 정보 엔티티
14+
- **Product**: 상품 엔티티. 상태 관리 행위(품절/재판매/단종) 포함
15+
- **Stock**: 재고 엔티티. 차감/증가/소진 확인 행위 포함
16+
- **StockManager**: 재고 차감 시 Stock과 Product를 함께 조율하는 도메인 서비스
17+
- **Money**: 금액 값 객체. 금액 계산 로직 캡슐화
18+
- **ProductStatus**: 상품 상태 열거형
19+
20+
**설계 의도:**
21+
22+
- Product와 Stock은 각각 독립적인 애그리게이트 루트
23+
- StockManager가 두 애그리게이트를 조율하여 비즈니스 로직 수행
24+
25+
---
26+
27+
## 2. Likes 도메인
28+
29+
![img_6.png](https://github.com/user-attachments/assets/ed4682ae-1f41-4d4b-8819-f412a08d5fb8)
30+
31+
**주요 구조:**
32+
33+
- **ProductLike**: 사용자의 상품 좋아요 기록 엔티티
34+
35+
**설계 의도:**
36+
37+
- 단순한 관계 엔티티로 별도의 비즈니스 로직 없음
38+
39+
---
40+
41+
## 3. Orders 도메인
42+
43+
![img_5.png](https://github.com/user-attachments/assets/d8074471-d055-4d55-8b21-2c8daf2e1ae0)
44+
45+
**주요 구조:**
46+
47+
- **Order**: 주문 엔티티. 주문 생성(place) 및 결제 완료(pay) 행위 포함
48+
- **OrderItem**: 주문 항목 엔티티. 주문 시점의 상품 정보 스냅샷
49+
- **Payment**: 결제 엔티티. 결제 생성, 외부 결제 필요 여부 판단, 완료 처리 행위 포함
50+
- **PaymentManager**: 결제 생성 및 PG 호출 조율을 담당하는 도메인 서비스
51+
- **OrderStatus**: 주문 상태 열거형
52+
- **PaymentStatus**: 결제 상태 열거형
53+
54+
**설계 의도:**
55+
56+
- Order와 OrderItem은 하나의 애그리게이트 (강한 일관성)
57+
- Payment는 독립적인 애그리게이트
58+
- PaymentManager가 결제 프로세스 전체를 조율

0 commit comments

Comments
 (0)