🔧 [기능개선][장바구니] 장바구니 수량 처리 API를 SET/DELTA로 분리하고 DELTA 멱등성(Idempotency-Key) 지원

[Chuseok22]

📝 현재 문제점

현재 장바구니 메뉴 추가 API는 quantity가 “해당 메뉴의 최종(누적) 수량” 으로 동작합니다.

• 요청 파라미터
  • menuId (Long, required): 장바구니에 담을 메뉴 ID
  • quantity (int, required)
    • 1 이상: 해당 수량으로 장바구니에 추가 또는 수정(= 최종 수량 SET)
    • 0: 해당 메뉴를 장바구니에서 삭제
• 응답 데이터
  • cartId (Long): 장바구니 ID
  • items (List): 장바구니에 담긴 메뉴 목록
  • totalPrice (int): 장바구니 전체 금액
• 특징
  • quantity=0 전달 시 해당 메뉴 삭제
  • 장바구니가 비워지면 장바구니 엔티티 자동 삭제(이 경우 응답에 cartId가 포함되지 않을 수 있음)

이 구조에서는 “추가하기(+N)” UX를 구현할 때 프론트에서

• 현재 수량 파악(조회/상태 보유)
• 추가할 수량 입력
• 최종 수량 계산(현재 + 추가) 후 quantity로 전송
  을 수행해야 합니다.

문제점은 아래와 같습니다.

1. 프론트 로직 복잡도 증가

• “담기” 기능이 단순히 +N을 의미함에도, 항상 현재 수량을 알고 있어야 하므로 구현/상태 동기화 비용이 증가합니다.

2. 동시성(멀티 탭/멀티 디바이스)에서 덮어쓰기 위험

• 클라이언트가 오래된 “현재 수량”을 기준으로 최종 수량을 계산해 전송하면, 서버가 이를 그대로 SET하여 의도치 않게 덮어씌우는(lost update) 상황이 발생할 수 있습니다.

3. API 의미 혼합으로 인한 확장성 저하

• 단일 quantity 값으로 “추가/설정/삭제” 의미를 모두 표현하고 있어 클라이언트 측 해석 혼선이 발생하며, 향후 기능 확장(감소, 증감형 UX, 재시도 안정성)에도 제약이 생깁니다.

🛠️ 해결 방안 / 제안 기능

본 이슈에서는 A안(권장)으로 SET(최종 수량 설정) API 와 DELTA(증감) API 를 분리 제공하고,
DELTA API에 대해 Idempotency-Key 기반 멱등성을 지원합니다.

1) SET API(최종 수량으로 맞추기, 멱등)

• 목적: 장바구니 화면에서 수량을 직접 편집(스텝퍼/직접 입력)하거나, 특정 수량으로 “정확히 맞추는” 동작
• 특징: 동일 요청을 여러 번 보내도 결과가 동일(멱등)
• 동작 규칙
  • quantity >= 1 → 해당 menu의 수량을 해당 값으로 설정
  • quantity == 0 → 해당 menu 삭제 (삭제는 별도 DELETE로 분리도 가능하나, 본 이슈에서는 기존 정책 유지 가능)

2) DELTA API(추가/감소, 서버가 누적 계산)

• 목적: “담기(+N)”, “한 개 더(+1)”, “한 개 빼기(-1)” 같은 증감형 UX를 단순하고 안전하게 지원
• 특징: 클라이언트는 “추가/감소할 수량(delta)”만 전달, 서버가 기존 수량을 조회해 누적 반영
• 동작 규칙
  • delta > 0 → 기존 수량 + delta
  • delta < 0 → 기존 수량 + delta (0 이하가 되면 해당 menu 삭제)
  • 결과적으로 장바구니가 비면 cart 엔티티 삭제(기존 정책과 동일)

3) DELTA 멱등성 보장: Idempotency-Key 지원(필수)

DELTA는 기본적으로 비멱등(중복 요청 시 수량이 중복 증가)하므로, 아래 정책을 반드시 적용합니다.

• 클라이언트는 DELTA 요청 시 헤더로 Idempotency-Key(요청 고유키)를 전송
• 서버는 (userId(or cartOwner), menuId, idempotencyKey) 단위로 요청을 기록하고,
  동일 키 재요청 시 최초 처리 결과(응답 바디)를 그대로 재반환하여 중복 반영을 방지
• 저장/만료 정책(TTL)은 운영 정책에 따라 설정(예: 24시간 등)하되, 정확한 값은 본 이슈에서 확정 필요

기대효과

• 프론트는 “추가하기”에서 누적 수량을 계산할 필요 없이 delta만 전송
• 모바일/불안정 네트워크 환경에서 재시도/중복 클릭이 발생해도 중복 반영 방지
• “편집(SET)”과 “추가/감소(DELTA)”가 목적별로 분리되어 API 의미가 명확해짐

⚙️ 작업 내용

1) 백엔드(JAVA + Spring Boot)

• SET API 스펙 확정 및 구현
  • 요청/응답 DTO 정의(menuId, quantity)
  • quantity==0 삭제 처리 및 마지막 아이템 삭제 시 cart 엔티티 삭제 처리(기존 정책 준수)
• DELTA API 스펙 확정 및 구현
  • 요청 DTO 정의(menuId, delta)
  • delta < 0 감소 시 0 이하가 되면 cartItem 삭제 처리
  • 결과적으로 cart가 비면 cart 엔티티 삭제 처리
• DELTA 멱등성(Idempotency-Key) 구현
  • 헤더 Idempotency-Key 파싱 및 필수 여부 결정(DELTA에서만 필수 권장)
  • 저장소 설계
    • key: (userId, menuId, idempotencyKey) (정확한 식별자 구성은 본 이슈에서 확정)
    • value: 처리 결과(최소: 처리 완료 여부 + 응답 바디 또는 재구성 가능한 데이터)
    • TTL/만료 정책 적용
  • 동일 키 재요청 시 최초 응답 반환
• 예외/응답 규칙 정리
  • menuId 없음, 잘못된 delta/quantity, 품절/재고 정책 등(현재 존재하는 규칙이 있다면 해당 규칙에 맞춰 확정)
  • cart 비움으로 cart 엔티티 삭제되는 경우 응답(cartId nullable) 정책 명확화
• 테스트
  • SET: 멱등성(동일 quantity 반복), 0 삭제, 마지막 삭제 시 cart 삭제
  • DELTA: +N 누적, -1 감소, 0 이하 삭제, 마지막 삭제 시 cart 삭제
  • DELTA: Idempotency-Key 동일 요청 반복 시 중복 반영 없이 동일 응답 반환
  • DELTA: 키 미전달/잘못된 키의 처리 규칙 검증

2) 프론트(웹: TypeScript + Next.js App Router / 앱: ReactNative + EXPO)

• “담기(+N)” 및 증감 버튼은 DELTA API 사용
  • 클라이언트는 추가할 개수만 delta로 전달
  • 요청마다 Idempotency-Key 생성/전송(중복 클릭/재시도 대비)
• “수량 직접 편집(최종 수량 지정)”은 SET API 사용
• 응답(items/totalPrice)을 기준으로 UI 상태를 항상 갱신(서버 응답을 소스 오브 트루스로)
• cart가 비어 cartId가 누락될 수 있는 케이스 처리(응답 items 기준으로 empty 상태 처리)

3) 문서화/스펙 정비

• SET/DELTA 각각의 목적, 사용 시나리오, 요청/응답 예시를 분리하여 문서화
• DELTA의 Idempotency-Key 규약(생성 방법, 재사용 범위, TTL, 중복 처리)을 문서화
• “cart 비움 → cart 엔티티 삭제 → cartId 누락 가능” 케이스를 예시/주의사항으로 명확히 기재

✅ 완료 조건(AC)

• SET API로 최종 수량 설정이 가능하며 동일 요청 재시도 시 결과가 변하지 않는다(멱등).
• DELTA API로 증감이 가능하며 프론트는 누적 수량 계산 없이 delta만 전송한다.
• DELTA 요청에 동일 Idempotency-Key로 중복 요청이 발생해도 수량이 중복 반영되지 않고 동일 응답이 반환된다.
• delta 감소로 0 이하가 되면 해당 menu가 삭제되며, cart가 비면 cart 엔티티가 삭제된다(기존 정책 준수).
• 문서/예시가 실제 동작과 일치하여 프론트 개발자가 혼선 없이 구현 가능하다.

📌 추가로 필요한 데이터(추측 없이 스펙 확정 위해 요청)

아래 정보가 있어야 API Path/Method 및 멱등성 저장 전략을 정확히 확정할 수 있습니다.

• 현재 사용 중인 장바구니 관련 API의 HTTP Method / Path 목록(기존 “menu 추가/수정” 엔드포인트 포함)
• 사용자 식별 방식(인증: JWT 등) 및 “cart 소유자” 결정 방식
• DB 모델 정보
  • cartItem 유니크 제약(예: cartId+menuId unique 여부)
  • cart/cartItem에 version 컬럼 또는 공통 audit 컬럼 존재 여부
• Idempotency-Key를 이미 사용하는 공통 규약/미들웨어 존재 여부(있다면 헤더명/TTL/저장소)
• quantity=0 삭제 정책을 SET에서 그대로 유지할지, DELETE로 분리할지의 팀 컨벤션

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[github-actions]

Chuseok22 Issue Helper

브랜치명

20251231_#59_장바구니_수량_처리_API를_SET_DELTA로_분리하고_DELTA_멱등성_Idempotency_Key_지원

커밋 메시지

장바구니_수량_처리_API를_SET_DELTA로_분리하고_DELTA_멱등성_Idempotency_Key_지원 : feat : {변경 사항에 대한 설명} https://github.com/CampusTable/campus-table-be/issues/59

[Chuseok22]

⏺ 좋은 질문입니다! API 설계의 핵심적인 부분이네요.

📊 현재 API 분석

현재 API는 **절대값 방식 (Absolute Value)**으로 동작합니다:

• quantity: 5 → 장바구니에 총 5개로 설정
• quantity: 0 → 삭제

프론트에서 계산:
// 현재 2개 → 1개 추가하려면
currentQuantity: 2
newQuantity: 2 + 1 = 3 // 프론트가 계산
API 요청: { menuId: 1, quantity: 3 }

---

✅ 어떤 방식이 맞는가?

일반적으로는 현재 방식 (절대값)이 더 선호됩니다.

이유:

1️⃣ 멱등성 (Idempotency)

// 절대값 방식 (현재)
API 요청: { quantity: 5 }
요청 3번 전송 → 결과: 5개 ✅ (예상대로)

// 상대값 방식
API 요청: { delta: +1 }
요청 3번 전송 → 결과: 3개 추가 ❌ (의도: 1개만 추가)

2️⃣ 명확한 최종 상태

// 절대값: 서버 상태를 명확히 지정
{ quantity: 3 } → "3개로 설정해줘"

// 상대값: 현재 상태에 의존
{ delta: +1 } → "1개 더해줘" (현재가 몇 개인지 모르면 최종 상태 불명확)

3️⃣ UI와의 일관성

장바구니 UI는 보통 현재 수량을 표시합니다:
[메뉴 A] [-] 2 [+]

• 사용자는 현재 수량을 보고 있음
• 그 값을 기준으로 증감하는 것이 자연스러움

---

⚠️ 단점과 해결책

단점 1: 동시성 문제 (Race Condition)

// 사용자가 빠르게 +1 버튼을 2번 클릭
// 현재 수량: 2

클릭 1: quantity: 3 요청 (서버 처리 중...)
클릭 2: quantity: 3 요청 (아직 응답 안 옴, 여전히 2개로 보임)

결과: 3개 ❌ (의도: 4개)

해결책:

A. 낙관적 UI 업데이트 (Optimistic Update)

const handleIncrement = async () => {
// UI 먼저 업데이트
setLocalQuantity(prev => prev + 1);

try {
  // API 요청
  await addToCart(menuId, localQuantity + 1);
} catch (error) {
  // 실패 시 롤백
  setLocalQuantity(prev => prev - 1);
}

};

B. 요청 직렬화

let pendingRequest: Promise | null = null;

const handleIncrement = async () => {
// 이전 요청이 완료될 때까지 대기
if (pendingRequest) {
await pendingRequest;
}

pendingRequest = addToCart(menuId, currentQuantity + 1);
await pendingRequest;
pendingRequest = null;

};

C. Debounce (추천)

import { debounce } from 'lodash';

const debouncedAddToCart = debounce(
(menuId: number, quantity: number) => {
addToCart(menuId, quantity);
},
300 // 300ms 대기
);

const handleIncrement = () => {
const newQuantity = localQuantity + 1;
setLocalQuantity(newQuantity); // UI 즉시 업데이트
debouncedAddToCart(menuId, newQuantity); // API는 debounce
};

---

🔄 대안: 두 가지 엔드포인트 제공

실무에서는 두 가지 방식을 모두 제공하는 경우도 많습니다:

1. 절대값 API (수정)

// PUT 또는 PATCH
PUT /api/cart/items
{
"menuId": 1,
"quantity": 5 // 총 5개로 설정
}

2. 상대값 API (증감)

// POST
POST /api/cart/items/increment
{
"menuId": 1,
"delta": 1 // +1개 추가
}

POST /api/cart/items/decrement
{
"menuId": 1,
"delta": 1 // -1개 감소
}

---

💡 결론 및 추천

현재 API 방식 (절대값)을 유지하는 것이 맞습니다.

이유:

1. ✅ REST 설계 원칙 (멱등성) 준수
2. ✅ 명확한 최종 상태
3. ✅ 네트워크 재시도 안전

프론트엔드에서 해야 할 일:
// 1. 현재 수량 추적
const currentQuantity = cartItem?.quantity ?? 0;

// 2. 증감 계산
const newQuantity = currentQuantity + 1;

// 3. API 요청
await addToCart(menuId, newQuantity);

// 4. Debounce 적용 (빠른 클릭 대응)

만약 백엔드 팀과 협의 가능하다면:

• 추가 엔드포인트: POST /api/cart/items/increment (상대값)
• 두 가지 모두 제공하면 프론트엔드가 상황에 맞게 선택 가능

현재 API 구조는 표준적이고 안전한 설계이므로, 프론트엔드에서 계산하는 것이 정상입니다. 다만 동시성 처리를 잘 해야 합니다! 🎯