개념 노트
소개컴포넌트 07

DESIGN SYSTEM / COMPONENTS

읽는 것에서,
이해하는 것으로.

개념을 풀어 보고, 구별하고, 직접 바꿔 보는 일곱 가지 요소.
실제 예시를 살펴보며 개념 노트에 어울리는 방식을 골라 보세요.

검토용 미리보기/기존 문서에 적용하기 전 비교하는 공간입니다.
컴포넌트 미리보기07개 · 커머스 예시
01

WorkedExample

결과에 이르는 이유까지

상황에서 출발해 풀이와 결과를 하나의 흐름으로 연결합니다.

정적
풀이가 있는 예시

중복 주문을 한 번만 집계하기

주문 이벤트가 재전송되어 같은 주문이 두 번 들어왔습니다. 주문 금액을 정확하게 집계하려면 어떻게 해야 할까요?

입력
order_id   amount
ORD-101    30,000원
ORD-101    30,000원
ORD-102    20,000원

  1. 무엇을 같은 주문으로 볼지 정합니다

    금액이 아니라 주문 ID를 기준으로 삼습니다. 금액이 같은 서로 다른 주문까지 제거하면 안 됩니다.

  2. 같은 주문 ID는 한 건만 남깁니다

    ORD-101 두 건 중 한 건을 남깁니다. 이 예시에서는 같은 ID의 금액도 같다고 가정합니다.

  3. 남은 주문의 금액을 합합니다

    ORD-101의 30,000원과 ORD-102의 20,000원을 합합니다.

결과

총 주문 금액은 80,000원이 아닌 50,000원입니다.

왜 이런 결과가 나왔나요?

전송 횟수와 실제 주문 수는 다릅니다. 주문 ID로 중복을 제거했기 때문에 재전송된 이벤트를 매출로 다시 세지 않습니다.

살펴볼 점

입력·처리·결과를 오가며 읽기 쉬운지, 결과 아래의 이유가 원리를 이해하는 데 도움이 되는지 살펴보세요.

사용 예시
<WorkedExample
  title="중복 주문을 한 번만 집계하기"
  situation="같은 주문이 두 번 들어왔습니다."
  input={"ORD-101 30,000원\nORD-101 30,000원"}
  steps={[{ title: "중복 제거", explanation: "주문 ID가 같은 항목을 한 건만 남깁니다." }]}
  result="합계는 30,000원입니다."
  reason="재전송을 별도의 주문으로 세지 않기 때문입니다."
/>
02

ExamplePair

비슷해 보이는 사례의 경계

해당하는 사례와 해당하지 않는 사례를 같은 기준으로 대조합니다.

정적
사례로 구별하기

같은 요청을 두 번 보내도 결과가 같을까요?

✓ 해당하는 사례

배송지를 “서울”로 설정

같은 요청을 여러 번 보내도 최종 배송지는 “서울”입니다.

반복 실행해도 한 번 실행했을 때와 최종 상태가 같습니다. 멱등적인 동작입니다.

× 해당하지 않는 사례

포인트를 1,000점 추가

두 번 보내면 2,000점이 추가됩니다.

실행할 때마다 최종 상태가 달라집니다. 별도의 중복 방지 장치가 없다면 멱등적이지 않습니다.

구별하는 기준

요청의 내용이 같은지가 아니라, 여러 번 실행한 결과가 한 번 실행한 결과와 같은지 확인합니다.

살펴볼 점

색상을 보지 않아도 두 사례를 구별할 수 있는지, 좁은 폭에서도 판단 기준을 놓치지 않는지 확인하세요.

사용 예시
<ExamplePair
  title="멱등적인 동작 구별하기"
  matches={{ title: "배송지 설정", description: "반복해도 같은 배송지", reason: "최종 상태가 같습니다." }}
  nonMatch={{ title: "포인트 추가", description: "반복할수록 포인트 증가", reason: "최종 상태가 다릅니다." }}
  criterion="한 번 실행한 결과와 반복 실행한 결과를 비교합니다."
/>
03

SelfCheck

알겠다는 느낌을 설명으로

답을 읽기 전에 내 설명을 떠올리고, 해설과 비교해 봅니다.

직접 조작
잠깐, 내 말로 설명하기

주문 금액이 같다는 이유로 중복을 제거하면 어떤 문제가 생길까요?

답을 보기 전에 이유를 떠올리거나 짧게 적어 보세요.

생각할 단서 보기

서로 다른 두 고객이 각각 30,000원짜리 상품을 주문했다고 생각해 보세요.

해설과 비교하기

서로 다른 주문도 금액은 같을 수 있습니다. 금액으로 중복을 제거하면 실제 주문을 없애 매출이 적게 집계될 수 있습니다. 이 예시에서는 같은 주문을 식별하는 주문 ID를 기준으로 삼아야 합니다.

내 설명에서 확인할 점
  • 전송된 이벤트와 실제 주문을 구별했나요?
  • 같은 금액이라고 같은 주문은 아니라는 점을 설명했나요?
  • 잘못 제거하면 매출이 적게 집계되는 결과까지 연결했나요?
살펴볼 점

질문이 단순 암기보다 이유를 생각하게 하는지, 단서와 해설을 나누어 확인하는 방식이 편한지 살펴보세요.

사용 예시
<SelfCheck
  question="중복 주문을 금액으로 제거하면 어떤 문제가 생길까요?"
  hint="같은 금액의 서로 다른 주문을 떠올려 보세요."
  explanation="서로 다른 주문이 제거되어 매출이 적게 집계될 수 있습니다."
  checkpoints={["주문 ID와 금액의 역할을 구별했나요?"]}
/>
04

DecisionGuide

차이를 넘어, 선택할 수 있게

상황을 선택하면 그 조건에 맞는 선택과 판단 이유를 보여줍니다.

직접 조작
조건에 따라 선택하기

어떤 데이터 저장 방식을 검토할까요?

가장 가까운 상황을 선택해 판단 이유를 확인하세요.

이 조건에서의 선택

데이터 웨어하우스

주문·매출 같은 정형 데이터를 공통 기준으로 정리해 반복적으로 조회하는 데 적합합니다.

함께 고려할 조건

가공 기준과 데이터 모델을 관리해야 합니다. 원본 보관이 필요하면 별도 저장소를 함께 사용할 수 있습니다.

모든 선택 기준 펼쳐 보기
정해진 지표를 반복 분석 → 데이터 웨어하우스
주문·매출 같은 정형 데이터를 공통 기준으로 정리해 반복적으로 조회하는 데 적합합니다. 가공 기준과 데이터 모델을 관리해야 합니다. 원본 보관이 필요하면 별도 저장소를 함께 사용할 수 있습니다.
다양한 원본을 먼저 보관 → 데이터 레이크
로그·이미지·이벤트 등 여러 형식의 데이터를 원본에 가깝게 보관하고 나중에 활용할 수 있습니다. 저장만으로 분석 준비가 끝나지는 않습니다. 메타데이터·품질·접근 권한 관리가 필요합니다.
원본 보관과 반복 분석 모두 → 두 저장 방식을 함께 검토
원본은 레이크에 보관하고, 반복 분석용 데이터는 웨어하우스로 정제하는 구성을 사용할 수 있습니다. 레이크하우스 같은 대안도 있습니다. 이 가이드는 선택 기준을 설명하는 예시이며 제품 선택을 확정하는 진단은 아닙니다.
살펴볼 점

상황을 바꿨을 때 선택뿐 아니라 이유와 예외도 이해되는지 확인하세요. 전체 기준을 펼쳐 비교할 수도 있습니다.

사용 예시
<DecisionGuide
  question="어떤 저장 방식을 검토할까요?"
  options={[{
    condition: "정해진 지표를 반복 분석", choice: "데이터 웨어하우스",
    reason: "공통 기준으로 정리한 데이터를 반복 조회합니다.",
    caveat: "데이터 모델과 가공 기준을 관리해야 합니다."
  }]}
/>
05

Term

낯선 단어를 만난 바로 그곳에서

본문 속 용어를 눌러 짧은 정의를 확인하고 읽던 문장으로 돌아옵니다.

직접 조작
본문에서 읽어 보기

재시도해도 안전한 요청

네트워크 오류가 나면 같은 요청을 다시 보낼 수 있습니다. 이때 멱등성같은 동작을 여러 번 실행해도 한 번 실행했을 때와 최종 상태가 같은 성질입니다. 응답 내용까지 항상 같다는 뜻은 아닙니다.이 보장되면 반복 요청으로 인한 상태 변경을 예측하기 쉽습니다.

결제 요청에는 멱등성 키같은 작업의 재시도를 식별하기 위해 보내는 고유 값입니다. 서버는 이 값을 이용해 같은 작업이 중복 실행되지 않도록 처리할 수 있습니다.를 함께 보내 같은 결제가 중복 처리되지 않도록 할 수 있습니다.

살펴볼 점

강조된 용어를 눌러 보세요. 닫기 버튼·바깥 영역·Esc로 설명을 닫을 수 있습니다. 본문을 떠나지 않고 뜻을 확인하는 경험을 살펴보세요.

사용 예시
<p>같은 요청이 반복되어도 결과가 같은 성질을
  <Term name="멱등성" definition="여러 번 실행해도 한 번 실행했을 때와 최종 상태가 같은 성질입니다." />
  이라고 합니다.
</p>
06

ScenarioLab

조건을 바꾸면, 결과도 달라질까요?

유입량과 처리량을 직접 바꾸며 대기열의 증가를 관찰합니다.

실험 · 재생
조건을 바꿔 보는 실험

요청이 처리보다 빠르게 들어오면?

유입량과 처리량을 조절해 10초 동안 대기열이 어떻게 변하는지 살펴보세요.

관찰 시점10초 후
대기 중인 요청30건
누적 처리50건
시간에 따른 대기 요청세로축: 0–190건

경과 시간 (초)

재생 속도: 1배

동작 줄이기 설정에 따라 10초 결과를 정적으로 표시합니다.

처리하지 못한 요청이 계속 쌓입니다.

유입이 처리량보다 매초 3건 많아, 10초 후 30건이 대기합니다.

계산 방식과 시간별 수치 보기

매초 같은 수의 요청이 들어오고, 같은 처리 용량이 유지되는 단순 모형입니다. 처음 대기열은 0건이며 실패·재시도·처리 지연의 변동은 제외합니다.

다음 대기열 = max(0, 이전 대기열 + 유입량 − 최대 처리량)

경과 시간대기 요청누적 처리
1초3건5건
2초6건10건
3초9건15건
4초12건20건
5초15건25건
6초18건30건
7초21건35건
8초24건40건
9초27건45건
10초30건50건
살펴볼 점

처리량을 유입량보다 크거나 같게 바꿔 보세요. 먼저 정적인 결과를 읽고, ‘변화 재생’으로 시간 흐름을 비교할 수 있습니다.

사용 예시
<ScenarioLab
  title="요청이 처리보다 빠르게 들어오면?"
  arrival={8}
  capacity={5}
/>
07

StepPlayer

지금 이 단계에서 달라진 것

Flow 확장 후보. 전체 순서를 유지하면서 각 단계의 상태 변화와 이유를 설명합니다.

단계 탐색 · 재생
변화를 따라가기

주문은 어떤 상태를 거칠까요?

단계를 선택해 무엇이 바뀌고, 왜 바뀌는지 확인하세요.

변경 전주문 없음
변경 후결제 대기

주문을 생성하고 결제를 기다립니다. 아직 결제가 끝나지 않았으므로 출고를 시작하지 않습니다.

1 / 4

자동 재생은 단계마다 4초씩 머뭅니다. 언제든 멈추거나 직접 단계를 선택할 수 있습니다.

동작 줄이기 설정이 켜져 있습니다. 이전·다음 버튼으로 탐색하세요.

모든 단계를 글로 보기
  1. 주문 접수: 주문 없음 → 결제 대기

    주문을 생성하고 결제를 기다립니다. 아직 결제가 끝나지 않았으므로 출고를 시작하지 않습니다.

  2. 결제 확인: 결제 대기 → 결제 완료

    결제 승인 결과를 확인한 뒤 상태를 바꿉니다. 요청을 보냈다는 사실만으로 결제 완료로 처리하지 않습니다.

  3. 재고 확보: 결제 완료 → 상품 준비

    판매 가능한 재고를 확보합니다. 이 예시는 결제 후 재고를 확보하는 단순한 흐름이며, 실패 시 취소·환불 분기가 필요합니다.

  4. 출고 처리: 상품 준비 → 배송 중

    상품을 택배사에 인계한 뒤 배송 상태로 전환합니다. 앞 단계의 결과가 다음 단계의 출발점이 됩니다.

살펴볼 점

이전·다음 또는 단계 이름으로 탐색하세요. 자동 재생과 ‘모든 단계를 글로 보기’를 비교해 어떤 방식이 이해에 도움이 되는지 살펴보세요.

사용 예시
<StepPlayer
  title="주문은 어떤 상태를 거칠까요?"
  steps={[{
    title: "결제 확인", before: "결제 대기", after: "결제 완료",
    explanation: "승인 결과를 확인한 뒤 상태를 변경합니다."
  }]}
/>
NEXT, IN CONTEXT

읽는 흐름에 도움이 되는 요소를 골랐다면,
실제 개념 노트 안에서 다시 확인해 보세요.

목록으로 돌아가기 ↑