createOrder 후속: 커스텀 입력 확장 시 잠정 가드 해제 + 멱등 키·통화 스냅샷 설계

[chanwoo7]

배경

주문 생성 mutation createOrder(PR #208, 릴리즈 #209)는 커스텀 단계 스펙 미확정 상태에서 정식 API의 확정 부분집합으로 릴리즈됐다.
그 과정에서 의도적으로 넣은 잠정 가드와 미반영 항목이 있어, 커스텀 체크아웃 확장 시 함께 처리해야 한다.

항목

• 커스텀 입력 확장 — CreateOrderInput에 커스텀 산출물(예: customDraftId) optional 필드 추가.
  참고: CustomDraft 스키마에는 옵션 선택·픽업 일시 컬럼이 없음(커스텀 텍스트·자유 편집만) — 주문 연결 설계 시 고려.
• OPTION_CUSTOMIZATION_REQUIRED 가드 해제(PR fix: 릴리즈 리뷰 반영 (설명/이미지 필수 옵션 선택 시 주문 거절) #210) — option_requires_description/option_requires_image 그룹 선택 시 현재는 주문을 거절한다.
  커스텀 입력이 생기면 이 가드를 실제 커스텀 데이터(문구·이미지) 검증으로 대체한다.
• 멱등 키 도입 (PR feat(order): createOrder 멱등 키 도입 (재시도 중복 생성 방지) #224 완료) — 재시도/중복 제출 시 동일 체크아웃이 SUBMITTED 주문을 중복 생성하고 capacity를 중복 점유할 수 있다(chore: 릴리즈 — 주문 생성 API (createOrder) #209 Codex P1, 미반영 답글로 후속 이관).
  클라이언트 요청 키 입력 + 계정 단위 unique 컬럼 + replay 시 기존 결과 반환. 스키마 마이그레이션 동반.
• 통화 스냅샷 — Order/OrderItem에 통화 컬럼이 없어 현재 KRW 외 상품은 주문 거절(UNSUPPORTED_CURRENCY).
  다국통화 도입 시 가격 스냅샷과 함께 통화를 저장하고 가드를 해제한다.

수행 조건

커스텀 단계 figma 스펙 확정 후 주문 생성 확장 설계와 함께 진행.
멱등 키는 결제 도입 전(운영 트래픽 발생 전)까지 처리 권장.

참고

• PR feat(order): 주문 생성 mutation(createOrder) — 정식 API의 확정 부분집합 #208(createOrder), fix: 릴리즈 리뷰 반영 (설명/이미지 필수 옵션 선택 시 주문 거절) #210(커스텀 필수 옵션 가드), fix: 릴리즈 리뷰 반영 (하루 넘는 리드타임을 미래 날짜에도 적용) #211(리드타임 절대 컷오프), 릴리즈 PR chore: 릴리즈 — 주문 생성 API (createOrder) #209
• 관련 이슈: Refactor: 매장 픽업 가능 판정 정책 단일화 (today-pickup / pickup-schedule / 주문 생성 공용) #206(픽업 판정 정책 단일화 — 주문 생성이 세 번째 소비자)

[chanwoo7]

멱등 키 항목 완료 — PR #224 (develop 머지).

• Order.idempotency_key(utf8mb4_bin) + (account_id, idempotency_key) unique, CreateOrderInput.idempotencyKey 필수(8~64자·공백 불가).
• replay는 입력 비교 없이 기존 주문 반환. capacity 계열 거절 직전에도 키 재조회(같은 키의 동시 재시도가 잔여를 채운 race에서 실패 대신 replay).
• FE 필요 작업: createOrder 호출 시 idempotencyKey 전송 필수(브레이킹). 체크아웃 진입 시 UUID 생성, 재시도에 재사용.

남은 항목(커스텀 입력 확장 · OPTION_CUSTOMIZATION_REQUIRED 가드 해제 · 통화 스냅샷)은 커스텀 figma/다국통화 확정 대기.