[2주차] 설계 문서 제출 - 김준형 #22
Conversation
Walkthrough주간 2 문서 추가: 요구사항 명세, 세 가지 시퀀스 다이어그램(제품 목록, 좋아요 등록, 주문·결제), 클래스 다이어그램, ERD로 제품 탐색·좋아요·주문/결제 흐름과 데이터 모델을 문서화합니다. (50단어 이내) Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client
participant API as API
participant DB as DB
rect rgb(235,245,255)
Note over Client,API: 1) 제품 목록 조회 (집계 포함)
Client->>API: GET /products?sort=...
API->>DB: 쿼리(제품 + 좋아요 집계)
DB-->>API: 제품 리스트(좋아요 수 포함)
API-->>Client: 200 OK (정렬된 제품 목록)
end
sequenceDiagram
autonumber
participant Client as Client
participant API as API
participant DB as DB
rect rgb(245,255,235)
Note over Client,API: 2) 좋아요 등록 (멱등성, 원자적 증가)
Client->>API: POST /products/{id}/like (userId)
API->>DB: 조회(Product 존재 여부, 기존 ProductLike)
alt 이미 좋아요 있음
DB-->>API: exists=true
API-->>Client: 200 OK (멱등성 처리)
else 없음
API->>DB: 트랜잭션 시작
DB->>DB: ProductLike INSERT
DB->>DB: LikeCount INCREMENT (원자적)
DB-->>API: 트랜잭션 커밋
API-->>Client: 201 Created
end
end
sequenceDiagram
autonumber
participant Client as Client
participant API as API
participant DB as DB
participant PG as PaymentGateway
rect rgb(255,245,235)
Note over Client,API: 3) 주문 생성 및 결제 흐름 (재고 잠금, 포인트, 외부 결제)
Client->>API: POST /orders (cart, usePoints)
API->>DB: 비관적 잠금(Stock 확인/감소)
alt 재고부족
DB-->>API: 재고부족 오류
API-->>Client: 400 OutOfStock
else 재고확보
API->>DB: Order 생성 (OrderItem 스냅샷)
API->>DB: 포인트 차감 시도
alt 포인트 충분 & 결제 불필요
DB-->>API: 커밋, 주문 완료
API-->>Client: 201 주문완료
else 외부결제 필요
API->>PG: 결제요청
alt PG 성공
PG-->>API: 결제확인
API->>DB: Payment 완료 업데이트, 커밋
API-->>Client: 201 주문완료
else PG 실패
PG-->>API: 결제실패
API->>DB: 롤백(재고 복구, 포인트 복구), 주문 취소 상태
API-->>Client: 402 Payment Failed
end
end
end
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/week2/01-requirements.md(1 hunks)docs/week2/02-sequence-diagrams.md(1 hunks)docs/week2/03-class-diagram.md(1 hunks)docs/week2/04-erd.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/week2/01-requirements.md
193-193: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
198-198: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
205-205: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
210-210: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (4)
docs/week2/02-sequence-diagrams.md (1)
1-71: 시퀀스 다이어그램 문서가 잘 구성됨요구사항 명세서의 주요 사용 사례를 시각화하고 있으며, 각 흐름에서 중요한 설계 고려사항(멱등성, N+1 방지, 트랜잭션 롤백 등)을 명확히 기술했습니다. 도메인 서비스(Facade, StockManager, PointAccountManager, PaymentManager) 활용이 적절하게 표현되어 있습니다.
docs/week2/03-class-diagram.md (1)
1-58: 클래스 다이어그램이 도메인 모델 설계를 명확하게 표현애그리게이트 구조(Product/Stock 분리, Order/OrderItem 통합, Payment 독립)가 요구사항의 일관성 요구에 적절히 대응하고 있습니다. 도메인 서비스의 역할(StockManager, PaymentManager)이 명확하게 정의되어 있어 시퀀스 다이어그램의 흐름과 잘 맞아떨어집니다.
docs/week2/04-erd.md (2)
104-127: 좋아요 취소 처리 전략 명확히 하기
product_like_counts테이블에서 "좋아요 취소에 대해 하드 딜리트로 처리"라고 명시하고 있는데, 다른 모든 테이블에서는 소프트 딜리트를 사용합니다. 이 차이를 의도한 설계인지 명확히 해야 합니다.만약
product_likes테이블에서는 소프트 딜리트를 사용하고product_like_counts에서만 하드 딜리트를 사용한다면, 이 이중 전략의 이유를 문서에 추가로 설명하는 것이 좋습니다. (예: "count 테이블은 비즈니스 로직에 직접 영향을 미치지 않는 캐시로 취급")
1-227: ERD가 도메인 모델 및 요구사항을 포괄적으로 반영전체적으로 테이블 구조가 클래스 다이어그램의 애그리게이트 설계, 시퀀스 다이어그램의 흐름, 그리고 요구사항의 기술 요구사항을 일관되게 지원하고 있습니다.
긍정적인 측면:
product_like_counts테이블로 집계 쿼리 성능 최적화 (N+1 방지)stocks테이블의 비관적 락 지원 설계order_items의 상품 정보 스냅샷으로 데이터 일관성 보장- 주요 조회 패턴에 대한 인덱스 정의
- 제약 조건으로 데이터 무결성 강화 (quantity >= 0, count >= 0)
- Order-OrderItem에만 FK 유지, 나머지는 앱 레벨 참조 무결성 관리
toongri
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/week2/03-class-diagram.md (1)
1-58: 문서 구조 및 내용 품질 우수도메인 주도 설계 원칙을 명확하게 반영한 아키텍처 설명입니다. Products, Likes, Orders 도메인의 애그리게이트, 값 객체, 도메인 서비스가 잘 정의되었고, 각 섹션의 설계 의도 설명이 명확합니다. 한국어 표현도 전문적이고 이해하기 쉽습니다.
제안 사항:
PR 제목에서 "ERD"와 "diagrams"를 언급했으므로, 이 문서의 상단에 간단한 소개 문장을 추가하여 (1) 시퀀스 다이어그램과의 관계, (2) ERD와의 차이점을 설명하면 전체 문서 체계가 더욱 명확해질 것 같습니다.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/week2/02-sequence-diagrams.md(1 hunks)docs/week2/03-class-diagram.md(1 hunks)docs/week2/04-erd.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/week2/04-erd.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/week2/02-sequence-diagrams.md
djawnstj
left a comment
djawnstj
left a comment
There was a problem hiding this comment.
준형님, 이번 주차 고생하셨습니다!
꼼꼼하게 작성해주셨네요ㅎㅎ 이 설계를 기반으로 어떻게 구현이 될지 기대가 됩니다.
|
|
||
| **좋아요 처리** | ||
| - 존재하지 않는 상품: "상품을 찾을 수 없음" 명확히 구분 | ||
| - 멱등성 보장: 중복 요청에도 사용자에게 성공 응답 전달 |
There was a problem hiding this comment.
@djawnstj 아 저는 멱등성을 보장하는 API는 같은 요청에 대해 동일한 결과를 낳아야한다고 생각했습니다. 그래서 좋아요 요청을 함에 있어서 언제 어디서 요청을 하든 항상 성공 응답과 좋아요가 db에 기록되는 결과를 낳아야한다고 생각했던 것 같습니다.
| - ProductLikeCount를 일괄 조회하여 N+1 문제 방지 | ||
| - 정렬 기준: latest(최신순), price_asc(가격낮은순), likes_desc(인기순) |
There was a problem hiding this comment.
지금 다이어그램에서는 ProductRepository 조회 후 ProductLikeRepository 를 조회하는데, 인기순 상품 목록을 조회하고자 할때도 문제 없을까요?
There was a problem hiding this comment.
@djawnstj 아 인기순 흐름에 대해선 다른 flow을 작성해둬야할 것 같습니다. 그리고 인덱스도 추가해놔야겠네요 감사합니다. 놓쳤습니다
|
|
||
| 사용자가 상품을 주문하고 결제하는 시나리오입니다. 전액 포인트 결제 여부에 따라 외부 PG 호출 여부가 결정됩니다. | ||
|
|
||
|  |
There was a problem hiding this comment.
다이어그램에서 주요 흐름의 순차에 따라 lifeline 을 위치해주신 것 같은데, 저는 개인적으로 비슷한 계층끼리 모여있는게 보기 좋은 것 같더라고요.
그리고 너무 많은 정보를 한번에 담으려고 하지 않았나 생각도 들어요. 시퀀스 다이어그램에는 모든 구현이 다 담길 필요는 없다고 생각합니다.
There was a problem hiding this comment.
@djawnstj 아 이 부분 조금 주의하겠습니다. 과제 내용에 controller, service 등등의 layer 흐름을 표현하라는 문구에 매몰되어서 모든 상세 스펙을 적어야 리뷰가 쉽다고 판단했던 것 같습니다. 같은 백엔드 개발자들과 구현 리뷰를 한다고 했을 때 어떤 수준으로 문서화해주는게 좋았을까요?ㅠ
docs/week2/04-erd.md
Outdated
| #### product_like_counts (상품 좋아요 수) | ||
|
|
||
| | 컬럼명 | 타입 | 제약 | 설명 | | ||
| |-----------------------|-----------|--------------------|---------------------| | ||
| | product_like_count_id | BIGINT | PK, AUTO_INCREMENT | 좋아요 수 ID | | ||
| | product_id | BIGINT | NOT NULL, UNIQUE | 상품 ID (참조) | | ||
| | count | INT | NOT NULL | 좋아요 수 | | ||
| | created_at | TIMESTAMP | NOT NULL | 생성 시각 | | ||
| | updated_at | TIMESTAMP | NOT NULL | 수정 시각 | | ||
| | deleted_at | TIMESTAMP | NULL | 삭제 시각 (Soft Delete) | | ||
|
|
||
| **인덱스:** | ||
|
|
||
| - PK: product_like_count_id | ||
| - UK: product_id | ||
|
|
||
| **제약:** | ||
|
|
||
| - count >= 0 (CHECK) | ||
|
|
||
| **특이사항:** | ||
|
|
||
| - 좋아요 취소에 대해 하드 딜리트로 처리 |
There was a problem hiding this comment.
product_like_counts 테이블이 필요한 이유가 뭔가요?
단순히 1:1 관계인데 이 테이블이 있으므로 생기는 이점이 뭘까요?
특이사항:
- 좋아요 취소에 대해 하드 딜리트로 처리
count 가 0 이 되면 삭제가 되는걸까요?
제약은 count >= 0 인데 삭제가 되어야 할 이유가 궁금합니다.
또한 soft delete 를 위한 deleted_at 컬럼이 존재하는 이유도 궁금해요.
There was a problem hiding this comment.
@djawnstj 아 세가지 질문 차례로 말씀드리겠습니다.
- product_like_counts에 대하여
- 우선 최대한 비슷한 수정 케이스를 가진 데이터끼리 테이블을 두려고 설계를 했습니다. product_like_counts 테이블은 집계 방식에 따라 업데이트 주기가 빈번한 값이고, 그에 비해 products 테이블은 변경의 빈도가 비교적 훨씬 적은 테이블입니다. update 발생할 때마다 lock이 걸리고, postgresql 특성상 데이터가 새로 생기는 메커니즘을 고려했을 때 분리에 이점이 있다고 생각했습니다.
- 도메인 모델 관점에서도 분리가 좋다고 생각했습니다. product_like_counts 테이블은 거의 읽기 모델에 가까운 값이고, 도메인 모델에 있어야할 필요가 없는 값이라고 생각했습니다. 또한 도메인 모델의 범위를 너무 크게 잡으면 update 에 대한 동시성 문제도 발생하기 좋다고 생각했습니다. 때문에 도메인 모델 관점에서도 product와 product_like_counts를 분리하였는데요. 수정의 빈도를 고려했을 때 cache의 ttl도 각각 설정해주는 것이 좋겠다 생각이 들었습니다. 이런 근거를 갖고있는 상황에서 영속성 테이블을 분리하는 것이 더 직관적이고 유지보수하기 좋겠다 라고 생각이 들었습니다. 도메인 모델과 영속성 모델은 서로 별개이지만 경험상 구조가 많이 달라지기 시작하면 관리 측면에서 조금 패널티가 생기는데 이번 케이스는 구조를 비슷하게 가져갔을 때 얻는 패널티가 비교적 적다고 생각했기 때문입니다.
- 이 결정으로 인해 생긴 조회 시에 단점은 사실 다른 방법으로 해결이 가능하지 않을까 생각했습니다. 데이터 쓰기에 용이한 데이터 스키마 구조를 가져가고, 조회에 최적화된 cache나 다른 데이터 소스 등을 활용하는 것이 유지보수 관점에서 더 좋다고 생각해서 이와 같은 구조를 만들게 되었습니다.
-
우선 특이사항은 잘못 표기된 것 같습니다. product_likes 테이블에 대한 스펙인데 착각하고 집계 테이블에 넣게되었습니다.
해당 테이블은 상품 생성 시에 자동으로 같이 데이터를 생성하도록 만들 것 같습니다. -
deleted_at을 하드 딜리트 테이블인 product_likes에도 포함한 이유는 template이 base entity에 deleted_at을 넣어놨길레 아 우리팀의 컨벤션은 deleted_at을 항상 포함한다. 구나 라고 생각하고 설계하게 되었습니다. 이 상황에서 base entity 구현을 soft_delete_entity 등으로 확장해서 구분점을 주기보다 우선 동일한 스펙으로 구현하는 것이 효율적인 선택이라 생각했습니다.
docs/week2/04-erd.md
Outdated
|
|
||
| - PK: order_item_id | ||
| - FK: order_id → orders(order_id) ON DELETE CASCADE | ||
| - IDX: product_id (상품별 주문 이력 조회용) |
There was a problem hiding this comment.
@djawnstj 현재 제가 업무볼 때 상품단위로 주문이력을 보고싶다는 요구사항이 있어 인덱스를 걸어놨었는데, 다시 생각해보니 현재 과제할 때 필요한 상황은 아닌것같습니다. 우선 지우고 나중에 필요할 때 다시 넣겠습니다.
| #### payments (결제) | ||
|
|
||
| | 컬럼명 | 타입 | 제약 | 설명 | | ||
| |--------------|---------------|--------------------|---------------------| | ||
| | payment_id | BIGINT | PK, AUTO_INCREMENT | 결제 ID | | ||
| | order_id | BIGINT | NOT NULL, UNIQUE | 주문 ID (참조) | | ||
| | user_id | BIGINT | NOT NULL | 사용자 ID (참조) | | ||
| | total_amount | DECIMAL(15,2) | NOT NULL | 총 주문 금액 | | ||
| | used_point | DECIMAL(15,2) | NOT NULL | 사용 포인트 | | ||
| | paid_amount | DECIMAL(15,2) | NOT NULL | 실제 결제 금액 | | ||
| | status | VARCHAR(20) | NOT NULL | 결제 상태 (READY, PAID) | | ||
| | created_at | TIMESTAMP | NOT NULL | 생성 시각 | | ||
| | updated_at | TIMESTAMP | NOT NULL | 수정 시각 | | ||
| | deleted_at | TIMESTAMP | NULL | 삭제 시각 (Soft Delete) | | ||
|
|
||
| **인덱스:** | ||
|
|
||
| - PK: payment_id | ||
| - UK: order_id | ||
| - IDX: user_id (사용자별 결제 이력 조회용) |
There was a problem hiding this comment.
만약 PG 를 사용한다면, PG 사에서 우리의 주문을 어떤 방법으로 식별할까요?
예를 들어 준형님의 서버와 제 서버가 동시에 동일한 order_id 로 결제를 요청한다면 어떻게 될까요?
There was a problem hiding this comment.
@djawnstj 아 pg사 id 컬럼을 빼먹었습니다. 감사합니다ㅠ 제일 중요한걸 까먹었네요. 우선 iamport나 토스페이먼츠도 제휴사 단위로 order_id 관리해주는걸로 알고있긴한데 제 기억이 맞다면 iamport의 경우에는 제휴사-order_id를 unique을 보장해주지 않고, 제일 마지막에 요청한 order_id 건으로 데이터를 처리해주는 것으로 알고있습니다.
그래서 꼭 external pg id가 필요한데 놓쳤습니다. 그부분 반영하겠습니다 감사합니다ㅠ
simbokyung98
left a comment
simbokyung98
left a comment
There was a problem hiding this comment.
준형님 이렇게 열정적으로 과제를 진행해주시고 먼저 피드백 요청을 주셔서 감사합니다!
저의 작은 의견을 공유드리니 참고 부탁드립니다!
| 3. 외부 PG 시스템에 결제 요청 전송 시 오류가 발생한다 | ||
| 4. 시스템은 트랜잭션을 롤백한다 | ||
| 5. 시스템은 "결제 요청 실패" 오류를 반환한다 | ||
| 6. 주문 및 결제가 생성되지 않으며, 재고와 포인트도 차감되지 않는다 |
There was a problem hiding this comment.
서버개발자들과 소통하기 위한 설계서라면 예외시나리오에 대한 HTTP 상태코드도 함께 들어가며 좋을 것 같아요!
There was a problem hiding this comment.
@simbokyung98 음 API 스펙은 아직 단계가 아니라서 안적긴했는데, 같이 적어놓으면 좋을까요?
| 3. 시스템은 주문을 접수 상태로 생성한다 | ||
| 4. 시스템은 결제를 준비 상태로 생성한다 | ||
| 5. 시스템은 사용자의 포인트를 차감한다 | ||
| 6. 시스템은 외부 PG 시스템에 결제 요청을 전송한다 |
There was a problem hiding this comment.
현재는 포인트르 기준으로 결제를 하니 그 기준으로 유스케이스를 작성하는 것은 어떨까요?
이후 요구사항이 수정된다면 설계서도 같이 수정되어야 한다고 생각합니다!
There was a problem hiding this comment.
@simbokyung98 과제에 외부 시스템 연동에 대한 언급이 있는데 그럼에도 제외해야할까요?ㅠ mock으로라도 적어놓으라고 하시긴했거든요. 실제 구현할건 아니지만
|
|
||
| 사용자가 상품에 좋아요를 등록하는 시나리오입니다. 멱등성을 보장하여 중복 등록 시에도 오류 없이 처리됩니다. | ||
|
|
||
|  |
There was a problem hiding this comment.
상품과 좋아요 테이블 두곳에서 좋아요를 관리하면 어떤 점이 좋을까요?
There was a problem hiding this comment.
@simbokyung98 아 두 곳은 서로 다른 역할을 갖고 있습니다.
- ProductLike은 실제로 유저와 상품 사이의 좋아요를 기록하는 테이블입니다. 이 테이블을 기준으로 각 상품당 유저의 좋아요 여부를 확인하고, 추후에 등장할 내가 좋아요 한 상품 목록 조회에 사용됩니다.
- ProductLikeCount은 상품당 좋아요 갯수를 비정규화한 테이블입니다. 상품 리스트 조회 시에 count 집계에 대한 리소스 소모가 있을 것으로 예상되는데, 이커머스 특성상 조회의 비중이 높기 때문에 조회 시의 부하를 좀 줄이고 미리 집계하는 방향으로 갔습니다.
| 1. 재고를 비관적 락으로 조회하여 차감 (StockManager) | ||
| 2. 주문을 접수 상태(PLACED)로 생성 (Order.place) | ||
| 3. 포인트를 차감하고 이력 기록 (PointAccountManager) | ||
| 4. **결제 처리 (PaymentManager.pay)** |
There was a problem hiding this comment.
여기서 PG결제를 사용한다고 되어있네요!
이커머스 요구사항에 보면 "💡 이 시스템은 실제 결제(PG) 대신, 사전 충전된 포인트로 상품을 결제합니다. " 라는 조건이 있습니다.
개인적으로 함께 일하는 입장에서 보았을때 같이 정한 요구사항과 설계문서가 다를경우 한번 더 커뮤니케이션을 해야하기 때문에 비용이 더 추가된다고 생각합니다. 확장성에 대한 고려는 기본 설계 작성 후에 이루이지는게 더 좋지 않을까요?
There was a problem hiding this comment.
@simbokyung98 아 근데 이부분은 실제 수업은 또 내용이 다릅니다.
과제 설계범위도 이렇게 적혀있기도 해서 설계 범위에 외부 시스템 연동을 빼놓을 수가 없었습니다ㅠ
- 설계 범위
- 상품 목록 / 상품 상세 / 브랜드 조회
- 상품 좋아요 등록/취소 (멱등 동작)
- 주문 생성 및 결제 흐름 (재고 차감, 포인트 차감, 외부 시스템 연동)
…ss diagram in week 2
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/week2/03-class-diagram.md (1)
1-78: 주요 설계 결정 명확하고 well-structured — 단, Concurrency 처리 방식 추가 설명 권장클래스 다이어그램이 4개 도메인에 걸쳐 일관되게 구성되어 있습니다. Stock 분리, Aggregate 설계, Immutable PointHistory 등 설계 의도가 명확하게 드러나 있습니다.
다만 PR 설명에서 언급한 "point account와 stock이 exclusive locks로 동시성 처리" 하는 내용이 클래스 다이어그램에 명시되지 않았습니다. Stock 차감 시 동시성 제어 전략(Lock/Optimistic 등)을
StockManager의 책임 항목으로 추가하거나, 각 도메인의 설계 의도 섹션에서 언급하는 것을 고려해 주세요.예시:
- **StockManager**: 재고 차감 시 Stock과 Product를 함께 조율하는 도메인 서비스 (동시성 제어: exclusive locks 적용)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/week2/02-sequence-diagrams.md(1 hunks)docs/week2/03-class-diagram.md(1 hunks)docs/week2/04-erd.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/week2/04-erd.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/week2/02-sequence-diagrams.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-11-06T11:42:04.759Z
Learnt from: jikimee64
Repo: Loopers-dev-lab/loopers-spring-kotlin-template PR: 21
File: docs/week2/04-erd.md:116-246
Timestamp: 2025-11-06T11:42:04.759Z
Learning: User jikimee64 prefers content-focused reviews over markdown formatting suggestions when reviewing documentation files in Korean projects.
Applied to files:
docs/week2/03-class-diagram.md
… adjustments, and schema changes
3 participants
📌 Summary
💬 Review Points
1. 서버팀과 리뷰하기 위한 시퀀스 다이어그램 작성
2. stock 분리
3. 동시성 처리
4. product like count 비정규화
✅ Checklist
📎 References
Summary by CodeRabbit
문서화
참고