Story: 연동 세션 상태 머신

메타

항목	값
Story ID	E-05-S-04
Epic	E-05 연동 자동화
상태	ready-for-dev
우선순위	P0
규모	M
담당 개발자	하록 (BE)

---

사용자 스토리

As a 시스템,
I want 연동 세션의 상태를 추적하고 전이를 관리하고 싶다,
So that 셀러와 어드민이 현재 진행 상황을 정확히 알 수 있다.

---

수락 기준 (Acceptance Criteria)

AC-01: 세션 생성

항목	내용
Given	셀러가 연동을 시작할 때
When	연동 페이지에 진입하면
Then	새 세션이 생성되고 REQUESTED 상태가 된다

AC-02: 상태 전이

항목	내용
Given	세션이 존재할 때
When	각 단계가 완료되면
Then	정의된 상태 머신에 따라 상태가 전이된다

AC-03: 세션 조회

항목	내용
Given	활성 세션이 있을 때
When	세션 조회 API를 호출하면
Then	현재 상태와 관련 데이터가 반환된다

AC-04: 세션 만료

항목	내용
Given	세션이 30분 이상 비활성 상태일 때
When	만료 체크가 실행되면
Then	세션이 EXPIRED 상태로 변경된다

---

태스크 분해

Task 1: 데이터 모델 AC-01

• [ ] 1.1: IntegrationSession 테이블 설계

  CREATE TABLE IntegrationSession (
    id VARCHAR(36) PRIMARY KEY,
    vendorId VARCHAR(36) NOT NULL,
    status ENUM(...) NOT NULL,
    smsCode VARCHAR(6),
    emailCode VARCHAR(6),
    lockedAt DATETIME,
    lockExpiresAt DATETIME,
    createdAt DATETIME,
    updatedAt DATETIME,
    completedAt DATETIME
  );

• [ ] 1.2: 상태 ENUM 정의

Task 2: 상태 전이 로직 AC-02

• [ ] 2.1: 상태 머신 구현
• [ ] 2.2: 전이 유효성 검증 (잘못된 전이 방지)
• [ ] 2.3: 상태 변경 히스토리 기록

Task 3: API AC-03

• [ ] 3.1: POST /api/integration/session - 세션 생성
• [ ] 3.2: GET /api/integration/session/:id - 세션 조회
• [ ] 3.3: PATCH /api/integration/session/:id/status - 상태 변경

Task 4: 만료 처리 AC-04

• [ ] 4.1: 30분 비활성 세션 만료 스케줄러
• [ ] 4.2: 만료 시 Lock 해제 연동

---

상태 정의

REQUESTED        → 연동 신청됨
INFO_ENTERING    → 정보 입력 중
WAITING_FOR_LOCK → Lock 대기 중
LOCKED           → Lock 획득, SMS 대기
SMS_RECEIVED     → SMS 인증번호 수신
EMAIL_WAITING    → 이메일 인증 대기
EMAIL_RECEIVED   → 이메일 인증번호 수신
VERIFYING        → 셀러가 쿠팡에서 인증 중
COMPLETED        → 연동 완료

[예외]
LOCK_TIMEOUT     → Lock 시간 초과
FAILED           → 연동 실패
CANCELLED        → 셀러 취소
EXPIRED          → 세션 만료 (30분)

상태 전이 다이어그램

REQUESTED → INFO_ENTERING → WAITING_FOR_LOCK → LOCKED
                                                  │
                                                  ▼
                                            SMS_RECEIVED
                                                  │
                                                  ▼
                                           EMAIL_WAITING
                                                  │
                                                  ▼
                                           EMAIL_RECEIVED
                                                  │
                                                  ▼
                                             VERIFYING
                                                  │
                                                  ▼
                                             COMPLETED

---

Dev Notes

세션 데이터 예시

{
  "id": "uuid-xxx",
  "vendorId": "vendor_123",
  "status": "LOCKED",
  "smsCode": null,
  "emailCode": null,
  "lockedAt": "2026-01-20T10:00:00Z",
  "lockExpiresAt": "2026-01-20T10:02:00Z",
  "createdAt": "2026-01-20T09:55:00Z",
  "completedAt": null
}

의존성

• E-05-S-01: Exclusive Lock

---

생성일: 2026-01-20