Round2

[JVHE]

📌 Summary

"우리가 함께 만들어갈 단 하나의 감성 이커머스"의 간단한 기능 설계를 진행했습니다.
설계 범위는 다음과 같습니다.

- **설계 범위**
    - 상품 목록 / 상품 상세 / 브랜드 조회
    - 상품 좋아요 등록/취소 (멱등 동작)
    - 주문 생성 및 결제 흐름 (재고 차감, 포인트 차감, 외부 시스템 연동)
- **제외 도메인**
    - 회원가입, 포인트 충전 (1주차 구현 완료 기준)
- **요구사항 기반**
    - 루프팩 이커머스 시나리오 문서를 기준으로 기능/제약사항을 설계에 반영합니다.

진행 내용은 reuquirements와 sequence diagram입니다.

💬 Review Points

• 추후 개발되면 좋겠다 싶은 내용들을 간단하게 TBD파트로 추가하여 작성했습니다. 분리할 곳이 따로 없어 한 곳에 묶어두었는데, 기획서 읽는 입장에서 있는게 좋을지 없는게 좋을지 생각이 궁금합니다.
• 멱등 동작을 생각할 때, 고려 요소는 행위와 영향을 주는 상태로 잡아야 할까요? 좋아요를 예로 들어보면 행위(좋아요/해제), 현재상태(Y/N)인 경우 4가지 조합이 나오는데, 4가지 조합으로 멱등성을 나눌지, 행동 기준만 가지고 나눌지가 고민이 되었습니다.

✅ Checklist

📎 References

Summary by CodeRabbit

문서화

• 도메인 모델링 및 시스템 설계 워크플로우에 대한 종합 설명서 추가
• 시퀀스 다이어그램, 클래스 다이어그램, ERD 설계 방법론 및 실제 예시 포함
• 설계 및 기술 작성 과제 가이드라인과 제출 체크리스트 추가
• 상품, 브랜드, 주문 기능을 포함한 e-커머스 플랫폼 요구사항 명세서 추가

[coderabbitai]

Walkthrough

BE L2 Round 2 도메인 설계 및 기술 문서 작성을 위한 종합 문서를 추가합니다. e-commerce 플랫폼의 요구사항, 시퀀스 다이어그램, 클래스 다이어그램, ERD 설계 및 퀘스트 가이드를 포함합니다.

Changes

코호트 / 파일	변경 요약
주간 설계 가이드 docs/week02.md	도메인 모델링, 시스템 설계, 시퀀스/클래스 다이어그램, ERD 설계를 다루는 BE L2 Round 2 종합 교육 자료 추가
퀘스트 및 요구사항 docs/week02_quests.md, docs/week2/01-requirements.md	Round 2 퀘스트 가이드(설계/기술 문서 작성 퀘스트, 제출 형식 및 체크리스트) 및 Looppack e-commerce 플랫폼의 상세 요구사항 문서 추가

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• 순수 문서 추가로 코드 변경이 없음
• 일관된 구조의 마크다운 파일들로 검토 복잡도 최소화
• 요구사항 및 가이드 문서의 내용 정확성과 완성도 확인 필요

Poem

📚 주간 설계, 요구사항의 집합
도메인 모델이 춤을 춘다
시퀀스와 ERD의 하모니
🐰 토끼의 가이드로 함께
완벽한 설계의 길을 달린다! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	제목 'Round2'는 변경사항의 주요 내용을 구체적으로 설명하지 않으며, 실제 변경 내용(docs/week02.md, docs/week02_quests.md, docs/week2/01-requirements.md 추가)과의 연결성이 불명확합니다.	제목을 'Add week 2 documentation and quest guidelines' 같이 더 구체적으로 수정하여 변경사항의 실제 내용을 명확히 전달해주세요.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	PR 설명이 필수 섹션을 대부분 포함하고 있으나, 체크리스트가 비어있고 참고자료 섹션이 누락되어 있습니다.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (12)

docs/week2/01-requirements.md (4)

124-150: 좋아요 기능의 멱등성(Idempotency) 명시 필요.

현재 기본 요구사항(137-139행)에서 "등록하고, 취소면 좋아요를 삭제한다"는 표현만 있어 토글 동작의 멱등성이 명확하지 않습니다.

"멱등성 동작 지원"이라는 표현은 있지만, 실제 설계 시 중요한 제약 사항이 있습니다. 학습자들이 다음을 이해하도록 명시하면 좋겠습니다:

• 같은 사용자가 동일 상품에 대해 동일한 좋아요 요청을 여러 번 보내도 최종 상태는 동일해야 함
• 이를 위해 좋아요 존재 여부를 먼저 확인한 후 create/delete 로직이 필요함
• 이는 단순 toggle이 아니라 상태 기반 멱등 연산임

다음과 같이 제약사항 섹션을 강화하면 학습자의 설계 방향이 더 명확해질 것 같습니다:

#### 제약사항

좋아요는 상품별로만, 브랜드 좋아요는 제외.
최대 좋아요 수 제한 없음.

**멱등성 요구사항 (중요)**:
- 같은 사용자가 동일 상품에 대해 여러 번 좋아요 요청을 보내도 최종 상태는 동일해야 함
- 요청 1: `POST /products/{id}/like` → 좋아요 등록 (상태 변경)
- 요청 1 재전송: `POST /products/{id}/like` → 이미 좋아요됨, 상태 변경 없음 (동일 결과)

이렇게 하면 RabbitMQ, 네트워크 재시도 등 실무에서의 멱등성 필요성과도 자연스럽게 연결됩니다.

[/suggest_recommended_refactor]

---

151-176: 주문 생성 시 동시성 문제(Race Condition) 설계 가이드 부재.

현재 기본 요구사항(167-169행)에서 "재고 차감", "포인트 차감"만 명시되어 있지만, 실무 e-commerce의 핵심 문제인 동시성 제어가 충분히 다루어지지 않습니다.

두 사용자가 마지막 재고 상품을 동시에 구매하려 할 때, 재고 확인과 차감 사이의 race condition으로 인해 최종 재고가 음수가 될 수 있으며, 분산 잠금을 통해 재고 업데이트가 원자적이고 일관성 있게 보장되어야 합니다.

다음 내용을 TBD 또는 제약사항 섹션에 추가하면 좋겠습니다:

#### TBD: 현재 고려 중인 추가 요구사항

- **동시성 제어 (Concurrency Control)**
  - 두 사용자가 동시에 마지막 재고를 구매 시도할 때 처리 방식
  - 재고 확인(`SELECT`)과 차감(`UPDATE`)이 원자적으로 수행되어야 함
  - 예: `UPDATE products SET stock = stock - 1 WHERE id = ? AND stock > 0`
  - 실패 시 명확한 "품절" 에러 반환

#### 제약사항

- 재고가 0 이하로 떨어지지 않아야 함 (음수 재고 방지)
- 재고 확인과 차감 사이의 race condition 방지

이를 통해 학습자들이 설계 시 동시성을 고려하고, 후속 구현 단계에서 Lock 전략(pessimistic locking, optimistic locking)이나 트랜잭션 격리 수준을 선택하도록 유도할 수 있습니다.

[/suggest_recommended_refactor]

---

48-49: 정렬 기능의 인기순 정의 부족.

48행의 "인기순: 좋아요 수 기준"은 좋지만, 다음이 불명확합니다:

• 시간 범위: 전체 기간? 최근 30일?
• 동점 처리: 좋아요 수가 같은 경우 어떻게 정렬?

- 정렬 기능을 제공해야 한다.
    - 기본, 인기순: 좋아요 수 기준 (동점 시 등록 시간 역순)
    - 최신순: 등록시간 기준, 가격순(오름,내림)

이렇게 명시하면 구현 시 정렬 쿼리가 더 명확해집니다.
[/suggest_optional_refactor]

---

77-82: 할인 가격 계산 요구사항의 구체성 부족.

77-82행에서 "조회 시 할인 적용 가격을 계산하여 표시"라고 명시되어 있지만:

• 할인 데이터의 출처: DB에 저장? 외부 시스템?
• 할인 우선순위: 여러 할인이 있을 때 중복 적용 여부?
• 표시 방식: 원가/할인가 모두? 할인율?

- 조회 시 할인 적용 가격을 계산하여 표시.
  - 할인은 상품별 또는 카테고리별로 관리됨을 가정
  - API 응답에 포함 항목: 원가(price), 할인가(discountedPrice), 할인율(discountRate)
  - 각 상품 최대 1개 할인만 적용 (우선순위: 상품 > 카테고리)

이렇게 구체화하면 ERD/API 설계 시 할인 엔티티 구조가 더 명확해집니다.
[/suggest_optional_refactor]

docs/week02.md (3)

113-160: 시퀀스 다이어그램 예제에서 트랜잭션/동시성 처리 누락.

현재 제공된 예제(131-153행)는 좋아요 토글의 "행복한 경로(happy path)"만 보여줍니다. 학습자가 실무적 고민을 하도록 다음을 추가하면 좋겠습니다:

예제 다음에 다음과 같은 주석을 추가하는 것을 권장합니다:

### 💬 Mermaid 예제 (계속)

**주의: 위 예제는 단순 흐름만 보여줍니다**

실제 구현 시 고려사항:
- **멱등성**: 네트워크 재시도로 인해 toggleLike()가 여러 번 호출될 수 있음 → exists() 체크 필수
- **트랜잭션**: 좋아요 수 업데이트와 좋아요 레코드 생성/삭제가 원자적이어야 함
- **동시성**: 같은 사용자가 rapid-fire로 요청 시 경합 조건(race condition) 가능성

이렇게 하면 학습자들이 설계 → 구현으로 넘어갈 때 "왜 트랜잭션이 필요한가?", "왜 select for update가 필요한가?"라는 질문이 자연스럽게 생깁니다.

[/suggest_recommended_refactor]

---

163-213: 클래스 다이어그램 예제의 도메인 책임 분석이 피상적.

현재 예제(183-206행)는 구조만 보여주고, 각 도메인 객체의 책임이 명확하지 않습니다.

예제 다음에 설명을 추가하면 좋겠습니다:

### 💬 예제 분석

**각 클래스의 책임 (도메인 주도 설계)**:
- `Product`: 상품의 기본 정보, 가격 계산 (원가 vs 할인가)
- `Brand`: 브랜드 정보 관리
- `Like`: 사용자-상품 관계의 구체화 (aggregate 또는 value object?)
- `Member`: 사용자 정보 (좋아요 관리는 여기? Like 엔티티?에 위임?)

**설계 고민거리**:
1. Like는 엔티티인가 VO인가? 
   - 엔티티: ID 필드 필요, 생명주기 독립적 → CompositeKey(memberId, productId)
   - VO: Member와 Product의 순수한 관계만 표현
   
2. 좋아요 수는 Product에 비정규화할 것인가? Like 테이블에서 COUNT할 것인가?
   - 장점/단점 트레이드오프 설명 필요

이렇게 하면 "왜 이렇게 설계했는가?"라는 질문이 자연스럽습니다.

[/suggest_recommended_refactor]

---

216-267: ERD 예제에서 동시성 제어를 위한 컬럼 누락.

주문/재고 관련 ERD이 없는데, 학습자들이 race condition을 고려한 설계를 하도록 돕기 위해 다음을 제안합니다.

"### ⚠ 자주 겪는 실수" 섹션(262-267행)에 다음을 추가하면 좋겠습니다:

### ⚠ 자주 겪는 실수

- 비즈니스 흐름이 반영되지 않은 정규화만 추구
- 중복 데이터 제거만 집중해 조회 JOIN이 과도해짐
- 상태 컬럼 없음 → 코드에서 하드코딩으로 해결함

**+추가: 동시성을 고려하지 않은 ERD**
- ❌ Stock 테이블만 있고 pessimistic lock이나 version 컬럼 고려 안 함
- ❌ Order 상태 전이(PENDING → CONFIRMED)의 원자성 보장 방법 없음
- ✅ 트랜잭션 격리와 pessimistic lock (FOR UPDATE) 또는 버전 관리 필요

**예시: 안전한 재고 차감 쿼리**
```sql
-- Race condition 방지: select for update + atomic decrement
SELECT * FROM products WHERE id = 1 FOR UPDATE;
UPDATE products SET stock = stock - 1 WHERE id = 1 AND stock > 0;
-- 결과: 0 rows affected면 품절 처리

이를 통해 ERD 설계 후 구현 시 `@Lock(LockModeType.PESSIMISTIC_WRITE)` 같은 JPA 어노테이션이 왜 필요한지 자연스럽게 이해하게 됩니다.

[/suggest_recommended_refactor]

</blockquote></details>
<details>
<summary>docs/week02_quests.md (5)</summary><blockquote>

`19-32`: **설계 범위에서 멱등 동작과 외부 시스템 연동의 구체성 부족.**

19-26행에서 "멱등 동작 지원"과 "외부 시스템 연동"이 명시되어 있지만, 학습자가 "이게 뭘 의미하는 거지?"라고 물을 가능성이 높습니다.



```markdown
### 📋 과제 정보

- **설계 범위**
    - 상품 목록 / 상품 상세 / 브랜드 조회
    - 상품 좋아요 등록/취소 (멱등 동작):
      * 같은 사용자가 동일한 좋아요 요청을 여러 번 보내도 최종 상태는 동일
      * 예: 첫 요청 → 좋아요 등록, 재전송 → 상태 변화 없음
    - 주문 생성 및 결제 흐름:
      * 재고 차감 (동시 요청 시 초과 판매 방지)
      * 포인트 차감
      * 외부 시스템 연동 (예: 결제 게이트웨이, 재고 관리 시스템)
      * 트랜잭션 롤백 (재고/포인트 복구)

[/suggest_recommended_refactor]

이렇게 하면 학습자들이 설계 시 멱등성과 분산 트랜잭션을 자연스럽게 고려하게 됩니다.

---

96-101: Feature Suggestions에 동시성(Race Condition) 항목 추가 제안.

현재 제안(96-101행)에서 멱등성, 도메인 분리, ERD 고민은 있지만, 실무 e-commerce의 가장 흔한 버그인 동시성 제어 고민이 빠져 있습니다.

### 🎯 Feature Suggestions

- 좋아요 기능의 멱등성을 보장하기 위해 어떻게 설계할 수 있을까?
- 주문 생성 시 재고/포인트 차감을 어떻게 연결했는가?
  * **추가: 두 사용자가 동시에 마지막 재고 상품을 구매 시도할 때 어떻게 처리할까?**
    - 재고 확인과 차감이 원자적으로 처리되어야 하는 이유는?
    - Pessimistic vs Optimistic locking의 장단점?
- 도메인 객체를 어떻게 나누고 책임을 위임했는가?
- ERD 설계 시 어떤 부분에서 고민이 있었는가?
  * **추가: 트랜잭션 격리 수준(Isolation Level)과 ERD의 관계는?**

[/suggest_recommended_refactor]

이렇게 하면 학습자들이 단순 "요구사항 구현"을 넘어 "왜 이런 문제가 발생하는가?", "어떻게 해결하는가?"를 깊이 있게 고민하게 됩니다.

---

42-48: 체크리스트 항목 46번의 시퀀스 다이어그램 지표가 모호.

"책임 객체가 드러나는가?"라는 표현이 구체적이지 않아, 학습자가 어떤 수준의 책임 분배를 기대하는지 불명확합니다.

## ✅ Checklist

- [ ]  상품/브랜드/좋아요/주문 도메인이 모두 포함되어 있는가?
- [ ]  기능 요구사항이 유저 중심으로 정리되어 있는가?
- [ ]  시퀀스 다이어그램에서 책임 객체가 드러나는가?
    * (지표) Controller → Service → Repository / Domain이 명확한 역할 분담을 하고 있는가?
    * (지표) 각 객체 간 메시지 흐름이 단방향인가, 아니면 복잡하게 얽혀 있는가?
- [ ]  클래스 구조가 도메인 설계를 잘 표현하고 있는가?
- [ ]  ERD 설계 시 데이터 정합성을 고려하여 구성하였는가?
    * (지표) Foreign key, 제약(constraints), 트랜잭션 격리 수준이 명시되어 있는가?

[/suggest_recommended_refactor]

---

63-95: 기술 라이팅 가이드의 성공 사례 부재.

"좋은 톤" 섹션(77-87행)은 예시만 있고, 실제 과제 범위에서 어떤 내용을 써야 하는지 구체적인 예가 없습니다.

다음 예시를 추가하면 학습자가 더 구체적으로 따라할 수 있습니다:

### ✨ 좋은 톤은 이런 느낌이에요 (Round 2 예시)

| 특징 | Round 2 설계 예시 |
| --- | --- |
| 🤔 내 언어로 설명한 개념 | "Like 기능을 처음엔 간단한 toggle로 구현했는데, 멱등성이 보장되지 않아 재설계했다" |
| 💭 판단 흐름이 드러나는 글 | "주문 시 재고 확인과 차감을 분리했다가, 동시 구매 시 음수 재고가 나타나는 문제를 발견해 트랜잭션으로 감싸게 되었다" |
| 📐 정보 나열보다 인사이트 중심 | "처음엔 Like와 Product를 1:N으로 연결했는데, 좋아요 수를 빠르게 조회해야 해서 Product에 비정규화하는 trade-off를 고민했다" |

이렇게 하면 학습자들이 "아, 내 설계 고민도 이렇게 써야 하는구나"라고 이해합니다.

[/suggest_optional_refactor]

---

1-10: PR 본문의 빈 템플릿 정보 제공.

현재 PR 본문이 빈 마크다운 템플릿이라는 PR 목표 설명이 있는데, 학습자 가이드에서 PR 제출 시 어떤 정보를 포함할 것을 권장하는지 명시되지 않았습니다.

다음 가이드를 추가하면 좋겠습니다:

## 📝 Round 2 Quests

---

### 📋 PR 작성 가이드

> PR 제목: `[2주차] 설계 문서 제출 - 홍길동`

> **PR 본문에 포함할 사항**:
> 1. **설계 의사결정** (각 1-2줄)
>    - Like 기능의 멱등성을 위해 상태 기반 토글 선택한 이유
>    - 주문 시 재고 보호를 위해 선택한 락 전략 (Pessimistic/Optimistic)
> 2. **고민한 지점**
>    - "이 부분이 어려웠습니다" 또는 "여러 선택지가 있었습니다"
> 3. **피드백 포인트**
>    - 리뷰어에게 특히 봐달라고 하는 부분

이렇게 하면 리뷰어(강사)가 학습자의 사고 과정을 이해하고 피드백하기 쉬워집니다.
[/suggest_optional_refactor]

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used**: CodeRabbit UI

**Review profile**: CHILL

**Plan**: Pro

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between d5ec39748d141edbb4c1b43001d1f4ce2f6b0b4c and 52f798bfffd56cc5547efedbe95282e911023df1.

</details>

<details>
<summary>📒 Files selected for processing (3)</summary>

* `docs/week02.md` (1 hunks)
* `docs/week02_quests.md` (1 hunks)
* `docs/week2/01-requirements.md` (1 hunks)

</details>

<details>
<summary>🧰 Additional context used</summary>

<details>
<summary>🧠 Learnings (1)</summary>

<details>
<summary>📓 Common learnings</summary>

Learnt from: minor7295
Repo: Loopers-dev-lab/loopers-spring-java-template PR: 22
File: apps/commerce-api/src/main/java/com/loopers/interfaces/api/point/PointsV1Controller.java:24-34
Timestamp: 2025-10-31T14:57:09.157Z
Learning: In the loopers-spring-java-template repository, the X-USER-ID header-based user identification is temporarily used for learning purposes and will be replaced with proper authentication (Spring Security) in a future PR. Do not flag this as a security issue until proper authentication is implemented.

</details>

</details>

</details>

<details>
<summary>🔇 Additional comments (1)</summary><blockquote>

<details>
<summary>docs/week02.md (1)</summary><blockquote>

`268-287`: **참고 자료 링크가 모두 최신인지 확인 필요.**

참고 자료 섹션(275-280행)의 링크들이 여전히 유효한지 확인하고, 특히 도메인 주도 설계(DDD) 관련 한국어 자료가 충분한지 검토를 제안합니다.



다음 링크들의 유효성을 확인해 주세요:
- https://www.msaschool.io/operation/design/design-two/ (도메인 주도 설계)
- https://mermaid.js.org/ (Mermaid 공식 문서)

또한 다음을 추가하면 학습자에게 도움이 될 것 같습니다:
- 한국어 DDD 서적/아티클 추천 (번역본 또는 원문)
- Mermaid 한국어 튜토리얼

[/request_verification]

</blockquote></details>

</blockquote></details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->