[refactor][queue-service] QueueToken Aggregate 재설계 검토

[rlaxxwls13]

📌 개요

현재 QueueToken 이 Aggregate Root 로 모델링되어 있으며, 도메인 식별자(QueueTokenId)가 곧 클라이언트에 노출되는 토큰 값으로 사용되고 있다. Issue #5 (대기열 API 구현) 토론 중 다음과 같은 한계가 드러났다:

• 도메인 표현의 모호성: 사용자 모델은 "대기열에 있는 상태"인데, 코드에서는 "토큰" 으로 표현되어 있어 의미가 흐려짐. DDD 의 일반 안티패턴 (식별자를 Aggregate 로 승격) 에 해당할 수 있음.
• 보안 한계: 서버 내부 식별자와 외부 노출 토큰이 동일 값이라, 토큰 노출 시 내부 식별자도 같이 노출됨.
  기능 변경은 없으며, 도메인 표현과 식별자 구조를 더 본질에 맞게 재설계하는 목적.

🎯 목표

• 도메인 표현 명확화 — "대기열 자리(QueueEntry)" 와 "자격증명(QueueToken)" 의 책임 분리
• 보안 강화 — 서버 내부 식별자와 외부 노출 토큰의 분리
• 실서비스 패턴과의 정합성 향상

🧩 리팩토링 범위

• 클래스 / 패키지 구조 개선
• 메서드 분리 / 네이밍 개선
• 중복 로직 제거
• 트랜잭션 / 예외 처리 정리

🏗️ 변경 설계

Before

QueueToken (Aggregate Root)
  - QueueTokenId  ← 서버 식별자 = 클라 노출 토큰 (동일)
  - userId, programId, status, issuedAt
  - issue(), restore(), admit(), cancel(), expire()

• 식별자 1개 (QueueTokenId) 가 두 역할 겸함
• "토큰" 이라는 단어가 도메인 객체와 식별자를 동시에 의미 → 모호성

After

QueueEntry (Aggregate Root)  ← 대기열 자리 (도메인 본질)
  - QueueEntryId      ← 서버 내부 식별자
  - QueueToken (VO)   ← 클라 노출용 자격증명
  - userId, programId, status, issuedAt
  - issue(), restore(), admit(), cancel(), expire()
 
QueueToken (Value Object)
  - value: 암호화 토큰 값 또는 별도 UUID

• 식별자 2개로 분리:
  • QueueEntryId: 서버 내부 관리용
  • QueueToken: 클라이언트 노출용
• 도메인 용어 명확화: "대기열 자리" 는 Entry, "자격증명" 은 Token

영향 범위

영역	변경
Domain	QueueToken → QueueEntry, QueueToken (VO) 신설
Repository	QueueTokenRepository → QueueEntryRepository, 토큰 ↔ 엔트리 매핑 추가
Redis 키 구조	queue:token:{id} → queue:entry:{entryId}, 토큰 → entryId 룩업 키 추가
API	URL / DTO 의 식별자 표현 변경 (token 값을 노출)
Service	토큰 발급 / 검증 로직 분리

추가 결정 필요 사항

• 토큰 발급 메커니즘: 단순 UUID / 암호화 토큰 / JWT 중 어느 방식?
• 토큰 ↔ 엔트리 매핑 저장 방식 (Redis 키 추가 등)
• 마이그레이션 전략 (운영 시점에 따라)

⚠️ 주의 사항

• 기능 동작은 기존과 동일해야 함 — 사용자 관점 동작 변화 없음
• API 스펙 변경 발생 — URL path / DTO 의 식별자 필드 변경
  • Issue [feat][queue-service] 대기열 API 구현 (진입/조회/이탈) #5 의 /tokens/{tokenId} 경로가 토큰 분리 후 어떻게 표현될지 재설계 필요

🧪 검증 방법

• 기존 도메인 테스트 통과 여부 확인 (이름 / 시그니처 변경 후)
• Repository 통합 테스트로 Redis 키 구조 변경 검증
• API 통합 테스트로 토큰 발급 / 조회 / 취소 흐름 검증
• 보안 검증 — 서버 식별자가 외부에 노출되지 않는지 확인

📚 참고

• 우선순위: v0.2.0 이후 / 별도 리팩토링 이슈