Loopers-dev-lab
diff --git a/‎.docs/design/01-requirements.md‎
Lines changed: 17 additions & 17 deletions b/‎.docs/design/01-requirements.md‎
Lines changed: 17 additions & 17 deletions
diff --git a/‎.docs/design/02-sequence-diagrams.md‎
Lines changed: 119 additions & 108 deletions b/‎.docs/design/02-sequence-diagrams.md‎
Lines changed: 119 additions & 108 deletions
@@ -56,7 +56,7 @@
 | **액터** | User |
 | **사전조건** | • 요청 시 상품 ID가 파라미터로 전달된다.<br> • (선택) 사용자가 로그인된 상태이다.|
 | **기본 시나리오** | 1) 사용자는 상품 목록이나 링크를 통해 상세 페이지에 접근할 수 있다.<br> 2) 시스템은 상품명, 가격, 재고, 좋아요 수, 브랜드 정보를 반환한다. |
-| **예외 시나리오** | • 상품 ID가 존재하지 않거나 삭제된 상품 혹은 인 경우 404 반환한다. <br> • 상품이 비공개 상태일 경우 403 반환한다.<br> • 상품 ID 형식이 잘못된 경우 400 반환한다. |
+| **예외 시나리오** | • 상품 ID가 존재하지 않거나 삭제된 상품인 경우 "상품을 찾을 수 없습니다" 메시지 반환<br> • 상품이 비공개 상태일 경우 "접근할 수 없는 상품입니다" 메시지 반환<br> • 상품 ID 형식이 잘못된 경우 "잘못된 요청입니다" 메시지 반환 |
 | **후조건** | 상품 상세 정보가 표시된다. |
 
 ---
@@ -66,10 +66,10 @@
 |------|------|
 | **액터** | User |
 | **사전조건** | • 사용자는 로그인 상태이다. |
-| **기본 시나리오** | 1) 사용자가 상세/목록 페이지에서 좋아요 버튼을 클릭한다.<br> 2) 시스템은 해당 사용자의 좋아요 등록/취소를 처리한다.<br> 4) 현재 상태(liked=true/false)와 총 좋아요 수를 반환한다. |
-| **예외 시나리오** | • 중복 요청 시 동일 결과 반환(멱등 보장)<br> • 데이터 충돌 시 요청 재시도 처리 |
+| **기본 시나리오** | 1) 사용자가 상세/목록 페이지에서 좋아요 버튼을 클릭한다.<br> 2) 시스템은 해당 사용자의 좋아요 등록/취소를 처리한다.<br> 3) 현재 좋아요 상태(좋아요 함/안 함)와 총 좋아요 수를 반환한다. |
+| **예외 시나리오** | • 이미 좋아요한 상품에 다시 좋아요 요청 시 현재 상태 유지 (중복 방지)<br> • 좋아요하지 않은 상품에 취소 요청 시 현재 상태 유지 (중복 방지)<br> • 시스템 오류 시 요청 재시도 가능 |
 | **후조건** | 좋아요 상태가 변경되고, 상품 목록/상세 정보에 반영된다. |
-| **비고** | (user_id, product_id) UNIQUE 제약으로 중복 방지 |
+| **비고** | 동일 사용자는 동일 상품에 대해 하나의 좋아요만 등록 가능 (중복 방지) |
 
 ---
 
@@ -78,17 +78,17 @@
 |------|------|
 | **액터** | User |
 | **사전조건** | 상품이 존재하고 재고 및 포인트가 충분해야 함 |
-| **기본 시나리오** | 1) 사용자가 여러 상품을 선택해 주문을 요청한다.<br> 2) OrderService는 ProductService에 재고 확인을 요청한다.<br> 3) OrderService는 PointService에 결제 금액만큼 포인트 차감을 요청한다.<br> 4) 모든 검증이 통과되면 주문 정보를 생성한다.<br> 5) 주문 정보를 외부 시스템으로 전송한다.<br> 6) 주문 생성 결과(주문번호, 결제금액, 잔여 포인트)를 반환한다. |
-| **예외 시나리오** | • 포인트 부족 → “결제 실패” 응답 및 충전 안내<br> • 재고 부족 → “주문 불가 상품” 메시지 반환<br> • 외부 전송 실패 → 주문은 저장되지만 상태를 “보류(PENDING)”로 표시 |
+| **기본 시나리오** | 1) 사용자가 여러 상품을 선택해 주문을 요청한다.<br> 2) 시스템은 주문할 상품의 재고가 충분한지 확인한다.<br> 3) 시스템은 사용자의 포인트 잔액이 주문 금액보다 충분한지 확인한다.<br> 4) 모든 검증이 통과되면 주문 정보를 생성하고 재고를 차감한다.<br> 5) 주문 금액만큼 포인트를 차감하고 주문 상태를 "완료"로 변경한다.<br> 6) 주문 생성 결과(주문번호, 결제금액, 잔여 포인트)를 사용자에게 반환한다. |
+| **예외 시나리오** | • 포인트 부족 → "결제 실패" 응답 및 포인트 충전 안내 메시지 표시<br> • 재고 부족 → "주문 불가 상품" 메시지 반환 및 재고 부족 안내<br> • 시스템 오류 → 주문은 저장되지만 상태를 "처리 중"으로 표시하여 나중에 재처리 가능 |
 | **후조건** | 포인트와 재고가 차감되고, 주문 내역이 생성된다. |
-| **비고** | UC-04-1~3을 포함하며, 트랜잭션으로 처리해야 함. |
+| **비고** | UC-04-1~3을 포함하며, 모든 단계가 성공해야 주문이 완료되고, 중간에 실패하면 모든 변경사항이 취소됨. |
 
 #### UC-04-1 포인트 결제 처리
 | 항목 | 내용 |
 |------|------|
 | **액터** | System |
 | **기능 요약** | 사용자의 포인트 잔액을 검증 후 주문 금액만큼 차감한다. |
-| **예외 시나리오** | 잔액 부족 시 “Insufficient Points” 오류 반환 |
+| **예외 시나리오** | 포인트 잔액이 주문 금액보다 부족한 경우 "포인트 부족" 오류 메시지 반환 |
 | **후조건** | 사용자의 포인트 잔액이 감소한다. |
 
 #### UC-04-2 재고 차감 처리
@@ -104,8 +104,8 @@
 |------|------|
 | **액터** | System / External Service |
 | **기능 요약** | 생성된 주문을 외부 시스템으로 전송한다. |
-| **예외 시나리오** | 외부 API 응답 지연 시 재시도 또는 비동기 큐에 저장 |
-| **후조건** | 주문 상태가 “전송 완료”로 변경된다. |
+| **예외 시나리오** | 외부 시스템 응답 지연 또는 오류 시 자동 재시도 또는 나중에 처리할 수 있도록 대기 목록에 저장 |
+| **후조건** | 주문 정보가 외부 시스템에 전송되고 주문 상태가 "전송 완료"로 변경된다. |
 
 ---
 
@@ -126,17 +126,17 @@
 | **액터** | User |
 | **사전조건** | 주문이 존재하고 해당 사용자의 주문이어야 함 |
 | **기본 시나리오** | 1) 사용자는 목록이나 링크를 통해 상세 페이지에 접근할 수 있다.<br> 2) 시스템은 해당 주문의 상세 정보(주문번호, 상품 목록, 총액, 상태 등)를 반환한다. |
-| **예외 시나리오** | • 주문이 존재하지 않을 경우 404 반환<br> • 다른 사용자의 주문을 조회하려는 경우 403 반환<br> • 주문 ID 형식이 잘못된 경우 400 반환 |
+| **예외 시나리오** | • 주문이 존재하지 않을 경우 "주문을 찾을 수 없습니다" 메시지 반환<br> • 다른 사용자의 주문을 조회하려는 경우 "접근할 수 없는 주문입니다" 메시지 반환<br> • 주문 ID 형식이 잘못된 경우 "잘못된 요청입니다" 메시지 반환 |
 | **후조건** | 주문 상세 정보가 화면에 표시된다. |
 
 ---
 
 ## ⚙️ 5. 비기능 요구사항
 | 항목 | 내용 |
 |------|------|
-| **식별 방식** | 모든 API는 `X-USER-ID` 헤더로 사용자 식별 |
-| **동시성 제어** | 포인트 차감 및 재고 차감은 트랜잭션 단위로 동작 |
-| **멱등성 보장** | 좋아요, 주문 요청은 멱등하게 처리되어야 함 |
-| **성능 요구사항** | 상품 목록 조회는 페이지네이션(page/size) 적용 |
-| **확장성 고려** | 좋아요 데이터를 추천/랭킹 기능으로 확장 가능 |
-| **일관성 보장** | 외부 시스템 연동 실패 시 재시도 로직 또는 보류 상태 유지 |
+| **식별 방식** | 모든 요청은 사용자 ID를 통해 사용자를 식별 |
+| **데이터 일관성** | 주문 처리 시 포인트 차감과 재고 차감은 함께 성공하거나 함께 취소됨 (부분 성공 방지) |
+| **중복 방지** | 좋아요, 주문 요청은 동일한 요청을 여러 번 보내도 같은 결과가 나오도록 처리 |
+| **성능 요구사항** | 상품 목록 조회 시 한 번에 보여줄 수 있는 상품 수를 제한하여 빠른 응답 제공 |
+| **확장성 고려** | 좋아요 데이터를 활용하여 상품 추천이나 인기 랭킹 기능으로 확장 가능 |
+| **오류 처리** | 외부 시스템 연동 실패 시 자동 재시도 또는 나중에 처리할 수 있도록 보류 상태로 관리 |
@@ -5,159 +5,170 @@
 ---
 
 ## 🎯 개요
-이 문서는 **UC-03 (좋아요)** 와 **UC-04 (주문)** 의 핵심 시나리오를 시퀀스 다이어그램으로 시각화한다.  
-핵심 비즈니스 로직 흐름만 표현하여 가독성을 높였다.
+이 문서는 **UC-03 (좋아요)** 와 **UC-04 (주문)** 의 핵심 시나리오를 비즈니스 관점에서 시각화한다.  
+기술적인 세부사항보다는 **사용자와 시스템 간의 상호작용 흐름**을 중심으로 설명하여, 비개발자도 쉽게 이해할 수 있도록 작성되었다.
 
 ---
 
 ## ❤️ UC-03 상품 좋아요 등록/취소
 
-> **멱등성 보장**: 이미 좋아요한 상태에서 다시 좋아요 요청 시, 추가 작업 없이 현재 상태(`liked: true`)를 반환하여 멱등성을 보장합니다.
-
 ### 1️⃣ 좋아요 등록
 
+**시나리오**: 사용자가 상품에 좋아요를 누르는 과정
+
 ```mermaid
 sequenceDiagram
     autonumber
-    actor User
-    participant Controller
-    participant Facade
-    participant ProductDisplay
-
-    User->>Controller: POST /api/v1/like/products/{productId}
-    Controller->>Facade: likeProduct(userId, productId)
-    Facade->>ProductDisplay: findById(productId)
-    ProductDisplay-->>Facade: ProductDisplay
-    
-    alt 이미 좋아요 함
-        ProductDisplay-->>Facade: likeCount
-        Facade-->>Controller: {liked: true, likeCount}
-    else 좋아요 없음
-        Facade->>Facade: create Like(userId, productId)
-        Facade->>ProductDisplay: like(Like)
-        ProductDisplay->>ProductDisplay: likes.add(Like)
-        ProductDisplay-->>Facade: likeCount
-        Facade-->>Controller: {liked: true, likeCount}
+    actor 사용자
+    participant 웹사이트
+    participant 좋아요시스템
+    participant 상품정보
+
+    사용자->>웹사이트: 좋아요 버튼 클릭
+    웹사이트->>좋아요시스템: 좋아요 요청 전송
+    
+    alt 이미 좋아요한 상품인 경우
+        좋아요시스템->>좋아요시스템: 이미 좋아요 상태 확인
+        좋아요시스템-->>웹사이트: 좋아요 상태 유지 (변경 없음)
+    else 처음 좋아요하는 경우
+        좋아요시스템->>상품정보: 상품 존재 여부 확인
+        상품정보-->>좋아요시스템: 상품 정보 반환
+        좋아요시스템->>좋아요시스템: 좋아요 기록 저장
+        좋아요시스템->>상품정보: 좋아요 수 업데이트
+        상품정보-->>좋아요시스템: 업데이트 완료
+        좋아요시스템-->>웹사이트: 좋아요 등록 완료
     end
-    Controller-->>User: 응답
+    
+    웹사이트-->>사용자: 좋아요 상태 표시 업데이트
 ```
 
+**설명**:
+- 사용자가 좋아요 버튼을 클릭하면, 시스템은 먼저 해당 사용자가 이미 좋아요를 눌렀는지 확인합니다.
+- 이미 좋아요한 경우: 추가 작업 없이 현재 상태를 유지합니다 (중복 방지).
+- 처음 좋아요하는 경우: 좋아요 기록을 저장하고 상품의 좋아요 수를 증가시킵니다.
+
 ### 2️⃣ 좋아요 취소
 
-> **멱등성 보장**: 좋아요하지 않은 상태에서 취소 요청 시, 추가 작업 없이 현재 상태(`liked: false`)를 반환하여 멱등성을 보장합니다.
+**시나리오**: 사용자가 좋아요를 취소하는 과정
 
 ```mermaid
 sequenceDiagram
     autonumber
-    actor User
-    participant Controller
-    participant Facade
-    participant ProductDisplay
-
-    User->>Controller: DELETE /api/v1/like/products/{productId}
-    Controller->>Facade: unlikeProduct(userId, productId)
-    Facade->>ProductDisplay: findById(productId)
-    ProductDisplay-->>Facade: ProductDisplay
-    
-    alt 좋아요 없음
-        ProductDisplay-->>Facade: likeCount
-        Facade-->>Controller: {liked: false, likeCount}
-    else 이미 좋아요 함
-        Facade->>Facade: find Like(userId, productId)
-        Facade->>ProductDisplay: unlike(Like)
-        ProductDisplay->>ProductDisplay: likes.remove(Like)
-        ProductDisplay-->>Facade: likeCount
-        Facade-->>Controller: {liked: false, likeCount}
+    actor 사용자
+    participant 웹사이트
+    participant 좋아요시스템
+    participant 상품정보
+
+    사용자->>웹사이트: 좋아요 취소 버튼 클릭
+    웹사이트->>좋아요시스템: 좋아요 취소 요청 전송
+    
+    alt 좋아요하지 않은 상품인 경우
+        좋아요시스템->>좋아요시스템: 좋아요 기록 없음 확인
+        좋아요시스템-->>웹사이트: 좋아요 없음 상태 유지 (변경 없음)
+    else 이미 좋아요한 경우
+        좋아요시스템->>상품정보: 상품 존재 여부 확인
+        상품정보-->>좋아요시스템: 상품 정보 반환
+        좋아요시스템->>좋아요시스템: 좋아요 기록 삭제
+        좋아요시스템->>상품정보: 좋아요 수 감소
+        상품정보-->>좋아요시스템: 업데이트 완료
+        좋아요시스템-->>웹사이트: 좋아요 취소 완료
     end
-    Controller-->>User: 응답
+    
+    웹사이트-->>사용자: 좋아요 상태 표시 업데이트
 ```
 
+**설명**:
+- 사용자가 좋아요 취소 버튼을 클릭하면, 시스템은 해당 사용자가 좋아요를 눌렀는지 확인합니다.
+- 좋아요하지 않은 경우: 추가 작업 없이 현재 상태를 유지합니다 (중복 방지).
+- 좋아요한 경우: 좋아요 기록을 삭제하고 상품의 좋아요 수를 감소시킵니다.
+
 ---
 
 ## 🛒 UC-04 주문 생성
 
-### 1️⃣ 주문 생성 기본 흐름
+### 1️⃣ 주문 생성 기본 흐름 (성공 케이스)
+
+**시나리오**: 사용자가 여러 상품을 선택하여 주문을 생성하는 과정
 
 ```mermaid
 sequenceDiagram
     autonumber
-    actor User
-    participant Controller
-    participant Facade
-    participant ProductOrder
-    participant Point
-    participant Order
-
-    User->>Controller: POST /api/v1/orders
-    Controller->>Facade: createOrder(userId, items, totalAmount)
+    actor 사용자
+    participant 쇼핑몰
+    participant 주문시스템
+    participant 상품재고
+    participant 포인트계정
+    participant 주문내역
+
+    사용자->>쇼핑몰: 주문하기 버튼 클릭
+    쇼핑몰->>주문시스템: 주문 요청 전송 (상품 목록, 수량)
     
-    Note over Facade: 트랜잭션 시작
+    Note over 주문시스템: 주문 처리 시작 (모든 작업이 성공하거나 모두 취소됨)
     
-    Facade->>ProductOrder: checkStock(quantity)
-    ProductOrder-->>Facade: stock available
+    주문시스템->>상품재고: 주문할 상품의 재고 확인
+    상품재고-->>주문시스템: 재고 충분함
     
-    Facade->>Point: checkBalance(totalAmount)
-    Point-->>Facade: balance sufficient
+    주문시스템->>주문시스템: 주문 총액 계산
     
-    Facade->>ProductOrder: decreaseStock(quantity)
-    ProductOrder-->>Facade: success
+    주문시스템->>포인트계정: 포인트 잔액 확인
+    포인트계정-->>주문시스템: 포인트 충분함
     
-    Facade->>Point: deduct(totalAmount)
-    Point-->>Facade: success
+    주문시스템->>상품재고: 주문 수량만큼 재고 차감
+    상품재고-->>주문시스템: 재고 차감 완료
     
-    Facade->>Order: create(List~ProductOrder~, Point)
-    Order-->>Facade: Order (status: PENDING)
+    주문시스템->>포인트계정: 주문 금액만큼 포인트 차감
+    포인트계정-->>주문시스템: 포인트 차감 완료
     
-    Note over Facade: 트랜잭션 커밋
-    Facade-->>Controller: Order
-    Controller-->>User: 주문 접수 완료
+    주문시스템->>주문내역: 주문 정보 저장 (상태: 완료)
+    주문내역-->>주문시스템: 주문 저장 완료
+    
+    Note over 주문시스템: 모든 작업 성공적으로 완료
+    
+    주문시스템-->>쇼핑몰: 주문 완료 (주문번호, 결제금액, 잔여 포인트)
+    쇼핑몰-->>사용자: 주문 완료 화면 표시
 ```
 
-### 2️⃣ 외부 전송 성공
+**설명**:
+1. 사용자가 주문하기 버튼을 클릭하면, 주문 시스템이 주문 처리를 시작합니다.
+2. **재고 확인**: 주문할 상품의 재고가 충분한지 확인합니다.
+3. **포인트 확인**: 사용자의 포인트 잔액이 주문 금액보다 충분한지 확인합니다.
+4. **재고 차감**: 재고가 충분하면 주문 수량만큼 재고를 차감합니다.
+5. **포인트 차감**: 포인트가 충분하면 주문 금액만큼 포인트를 차감합니다.
+6. **주문 저장**: 주문 정보를 저장하고 상태를 "완료"로 설정합니다.
+7. **결과 반환**: 주문 번호, 결제 금액, 잔여 포인트를 사용자에게 반환합니다.
 
-```mermaid
-sequenceDiagram
-    autonumber
-    participant Facade
-    participant ExternalService
-    participant Order
+**중요**: 모든 단계가 성공해야 주문이 완료됩니다. 중간에 실패하면 모든 변경사항이 취소됩니다 (예: 재고 차감 후 포인트 부족 시 재고도 원복).
 
-    Note over Facade: 주문 생성 완료
-    
-    Facade->>ExternalService: sendOrder(order)
-    ExternalService-->>Facade: success
-    
-    Facade->>Order: complete()
-    Order->>Order: status = COMPLETED
-    
-    Facade-->>User: 주문 완료
-```
+### 2️⃣ 주문 실패 시나리오
 
-### 3️⃣ 외부 전송 실패 (PENDING 상태 유지)
+**시나리오**: 재고 부족 또는 포인트 부족으로 주문이 실패하는 경우
 
 ```mermaid
 sequenceDiagram
     autonumber
-    participant Facade
-    participant ExternalService
-    participant Order
-
-    Note over Facade: 주문 생성 완료
-    
-    Facade->>ExternalService: sendOrder(order)
-    ExternalService-->>Facade: error
-    
-    Note over Facade: 주문은 저장되지만 PENDING 상태 유지
-    
-    Facade->>Order: 상태 유지
-    Order->>Order: status = PENDING
-    
-    Note over Facade: 재시도 로직 또는 비동기 큐에 저장
-    
-    Facade-->>User: 주문 접수 완료 (외부 전송 보류)
+    actor 사용자
+    participant 쇼핑몰
+    participant 주문시스템
+    participant 상품재고
+    participant 포인트계정
+
+    사용자->>쇼핑몰: 주문하기 버튼 클릭
+    쇼핑몰->>주문시스템: 주문 요청 전송
+    
+    alt 재고 부족인 경우
+        주문시스템->>상품재고: 주문할 상품의 재고 확인
+        상품재고-->>주문시스템: 재고 부족 (요청 수량 > 현재 재고)
+        주문시스템-->>쇼핑몰: 주문 실패 (재고 부족)
+        쇼핑몰-->>사용자: 재고 부족 안내 메시지 표시
+    else 포인트 부족인 경우
+        주문시스템->>상품재고: 재고 확인 (성공)
+        주문시스템->>포인트계정: 포인트 잔액 확인
+        포인트계정-->>주문시스템: 포인트 부족 (주문 금액 > 잔액)
+        주문시스템-->>쇼핑몰: 주문 실패 (포인트 부족)
+        쇼핑몰-->>사용자: 포인트 부족 안내 및 충전 안내 메시지 표시
+    end
 ```
 
-### 💬 예외 시나리오
-- **포인트 부족**: Point.deduct()에서 예외 발생 → 트랜잭션 롤백
-- **재고 부족**: ProductOrder.decreaseStock()에서 예외 발생 → 트랜잭션 롤백
-- **외부 전송 실패**: 주문은 저장되지만 상태를 PENDING으로 유지하여 재시도 가능
+**설명**:
+- **재고 부족**: 주문하려는 상품의 재고가 부족하면 주문이 실패합니다. 이 경우 아무것도 차감되지 않습니다.
+- **포인트 부족**: 포인트 잔액이 주문 금액보다 부족하면 주문이 실패합니다. 재고는 이미 확인했지만, 포인트 부족으로 인해 주문이 취소되므로 재고도 차감되지 않습니다.