본문으로 건너뛰기
Dot Design System
v0.3.1

비동기 작업

기다림 동안 실제 진행, 중단, 재방문과 결과 확인을 설계합니다.

목표

즉시 끝나지 않는 생성, 분석, 일괄 처리와 외부 연동 작업의 접수·진행·완료·실패를 분리한다. 사용자가 화면을 떠나도 작업의 연결을 잃지 않고, 돌아왔을 때 현재 상태와 다음 행동을 이해하게 한다.

즉시 요청과 작업 완료를 구분한다

  • button 클릭 성공은 작업 요청이 접수된 것일 수 있다.
  • 완료했어요는 실제 결과가 준비된 뒤에만 사용한다.
  • 접수 직후 job ID, 시작 시각, 대상 범위와 상태 확인 위치를 제공한다.
  • 화면을 떠나도 작업이 계속되는지 명시한다.
  • 완료 notification이 있다면 어디에서 다시 확인할 수 있는지 함께 말한다.

상태 모델

  • queued: 접수되었고 시작을 기다림
  • running: 실제 처리 중
  • succeeded: 전체 결과 준비 완료
  • partially_succeeded: 일부 완료, 일부 실패
  • failed: 완료하지 못함
  • retrying: 재시도 중
  • cancelling: 취소 요청 처리 중
  • cancelled: 취소 완료
  • expired: 결과 보관 기간 종료
  • unknown/stale: 최신 상태 확인 불가

제품의 backend 상태가 더 복잡하더라도 사용자에게는 다음 행동이 달라지는 상태만 구분한다.

시작 전

  • 대상 개수, 예상 영향과 결과 위치를 보여준다.
  • 긴 작업이면 화면을 떠나도 되는지 먼저 알린다.
  • 중복 요청이 같은 결과를 만들 수 있으면 기존 진행 job을 먼저 보여준다.
  • 비용이 크거나 외부 발송이 포함되면 확인 단계를 추가한다.
  • 취소 가능 여부와 취소가 이미 처리된 항목에 미치는 영향을 설명한다.

진행 표현

  • 측정 가능한 항목 수가 있으면 32/120 처리처럼 실제 progress를 사용한다.
  • 측정할 수 없으면 단계를 꾸며내지 말고 현재 처리 종류와 경과 상태를 말한다.
  • DotMotion processing은 실제 데이터 탐색·분석·답변 생성 중에만 사용한다.
  • 일반 batch import, 파일 업로드, 외부 동기화에는 일반 progress나 status를 사용한다.
  • progress가 뒤로 가거나 100%에서 오래 멈추지 않도록 backend 의미를 정리한다.

결과와 다음 행동

Success

  • 완료한 대상과 결과 위치
  • 다음 검토 또는 발행 행동
  • 결과가 자동 적용되었는지 초안으로 남았는지

Partial success

  • 성공·실패·건너뜀 개수
  • 실패 대상 다운로드 또는 filter된 목록
  • 전체 재시도가 아닌 실패 항목만 재시도할 수 있는지

Failure

  • 완료하지 못한 작업
  • 이미 반영된 변경이 있는지
  • 같은 요청 재시도의 안전성
  • 문의가 필요하면 오류 ID와 발생 시각

재시도와 중복 방지

  • retry가 idempotent한지 backend 계약으로 확인한다.
  • button 연속 클릭과 network retry가 duplicate job을 만들지 않게 한다.
  • 이미 진행 중이면 새 job을 만들기보다 기존 상태로 연결한다.
  • 부분 성공 뒤 전체 재시도가 중복 결과를 만들 수 있으면 실패 대상만 선택한다.
  • 사용자가 취소를 눌러도 이미 완료된 대상은 되돌아가지 않을 수 있음을 설명한다.

상태 확인과 갱신

  • job 상세 route 또는 목록에서 언제든 상태를 다시 찾을 수 있게 한다.
  • polling은 화면 visibility와 작업 상태에 맞춰 조절한다.
  • 새 상태를 확인하지 못하면 마지막 확인 시각과 stale 상태를 보여준다.
  • 자동 갱신이 focus, scroll, row order를 방해하지 않는다.
  • 완료되면 필요에 따라 toast, in-app notification 또는 현재 화면 status로 알린다.

좁은 화면

  • progress, 상태, 취소와 화면 이탈 안내를 한 좁은 row에 압축하지 않는다.
  • job 목록은 이름, 상태, 시작 시각, 핵심 결과 행동을 보존한다.
  • 세부 로그는 접을 수 있지만 실패 이유와 재시도는 먼저 보인다.
  • 긴 background 작업은 modal을 계속 열어 두게 하지 않는다.

접근성

  • 상태 텍스트를 role="status"와 polite live region으로 전달한다.
  • progress가 측정 가능하면 accessible name과 현재·최대 값을 제공한다.
  • 상태가 빠르게 바뀔 때 모든 tick을 낭독하지 않고 의미 있는 단계만 알린다.
  • animation 없이도 queued, running, failed, completed를 구분할 수 있어야 한다.
  • 취소·재시도 button은 어떤 job에 대한 행동인지 이름에 포함한다.
  • 완료 후 focus를 강제로 이동하지 말고 사용자가 현재 작업을 이어갈 수 있게 한다.

예제

사용 코드 · TSX
<WorkflowBar
  ariaLabel="답변 생성 작업 상태"
  title="다음 질문 생성"
  status="처리 중"
  statusTone="primary"
  description="학습 기록 42개를 살펴보고 있어요. 이 화면을 떠나도 작업은 계속돼요."
  secondaryActions={<Button variant="ghost">작업 상세 보기</Button>}
/>

실제 AI 처리 surface:

사용 코드 · TSX
<div role="status" aria-live="polite" className="flex items-center gap-3">
  <DotMotion variant="processing" size={64} />
  <span>학습 기록에서 다음 질문을 찾고 있어요.</span>
</div>

피해야 할 사용

  • 요청 접수를 실제 완료로 표현
  • 측정할 수 없는 가짜 percent progress
  • 모든 background job을 modal 안에서 기다리게 함
  • 일반 batch 작업에 Dot processing motion 사용
  • 부분 성공을 전체 실패 또는 전체 성공으로 뭉침
  • retry로 duplicate job이나 중복 결과 생성
  • 화면을 떠나면 작업이 취소되는지 설명하지 않음
  • 자동 갱신으로 focus와 row 위치 변경

검토 체크

  • 접수와 실제 완료 상태를 분리한다.
  • queued, running, success, partial, failed, cancelled, stale가 정의돼 있다.
  • 대상 범위, 결과 위치, 화면 이탈 가능 여부를 시작 전에 알린다.
  • 실제로 측정 가능한 progress만 표시한다.
  • Dot motion은 데이터 탐색·답변 생성에만 사용한다.
  • retry와 연속 클릭이 중복 결과를 만들지 않는다.
  • 부분 성공의 실패 대상만 복구할 수 있다.
  • job을 나중에 다시 찾을 안정적인 경로가 있다.
  • 상태 갱신이 focus·scroll·읽기를 방해하지 않는다.
  • reduced motion과 screen reader에 같은 상태를 제공한다.

관련 항목