Enums (도메인 enum 카탈로그)

Kotlin enum (backend) + TypeScript const enum / union (frontend packages/api-client/src/generated/). 모두 @Enumerated(EnumType.STRING) 저장 — 가독성 + migration 안전.

HqType

HqStatus

현재 도입 완료 — BE v0.7.0 (SPEC #013) Flyway V7. 4 종 enum. generated 스키마 HqAdminListItemStatus. 정지/복구 전이는 SPEC #018 (BE v0.11.0) 도입 완료 — suspend/reactivate endpoint + hq-list 액션. 자동 전환·사유 저장은 후속.

전이: ACTIVE \| ONBOARDING \| UNPAID → SUSPENDED (suspend) · SUSPENDED → ACTIVE (reactivate). INDEPENDENT 가상 본사는 전이 불가. 상세는 Status Lifecycle.

StoreType

StoreStatus

SPEC #019 매장 목록(/stores) 의 StoreAdminListItemStatus(generated) 와 정합: ACTIVE · INACTIVE · SUSPENDED. StoreAdminListItemType 도 INDEPENDENT · DIRECT · FRANCHISE 로 위 StoreType 과 일치. SPEC #037 정지/복구 전이 도입 — suspend(ACTIVE\|INACTIVE→SUSPENDED)·reactivate(SUSPENDED→ACTIVE). 상세는 Status Lifecycle 참고.

PlanType

Role

도메인 invariant — entity 생성자 require(...).

• HQ_MANAGER 는 본사 온보딩(POST /api/v1/admin/hq, #010)에서 발급된다.
• STORE_MANAGER 는 매장 생성과 분리해 POST /api/v1/admin/stores/{storeId}/managers(#021)로 사후 발급한다 — storeId tenancy, hqId=null, passwordMustChange=true. 매장당 복수 발급 가능(하드 블록 없음). 운영사 매장 목록(/stores)이 StoreAdminListItem.hasManagerAccount 로 발급 여부를 표시한다.

AccountStatus

STORE_MANAGER 계정은 SPEC #029 로 전이 액션이 도입됐다(ACTIVE ↔ SUSPENDED, ACTIVE/SUSPENDED → WITHDRAWN). generated 노출 enum StoreManagerListItemStatus = 같은 3값. 상세 전이·효과는 Status Lifecycle 참고.

HqAffiliatedStoreType (현재 미도입, 후속)

본사의 매장 구성 형태. 현재는 type 별 store row count 로 유추.

ImpersonationTokenStatus (현재 entity 컬럼 없음, 상태는 used_at 으로 유추)

TicketStatus (#027 — CS 티켓)

전이 규칙은 status-lifecycle 참고 (OPEN → IN_PROGRESS → RESOLVED → CLOSED

• 재오픈 RESOLVED/CLOSED → IN_PROGRESS). 잘못된 전이는 backend 409 TICKET_INVALID_STATUS_TRANSITION.

TicketPriority (#027 — CS 티켓)

v1 — 우선순위는 생성 시점에만 설정(변경 endpoint 없음). 색점은 전용 시안 부재로 기존 StatusPill tone 만 재사용한 임시 레이아웃.

TicketSlaState (#182 Part A — CS 첫 응답 SLA)

BE 서버 시각 기준 파생값이다 — FE 는 firstResponseDueAt 을 단말 시계와 비교해 재판정하지 않는다(A-D4). 재판정하면 목록 필터(overdueOnly — 서버의 now)와 화면 배지(브라우저의 now)가 서로 다른 시각을 본다. 기한은 우선순위별 상수(URGENT 2h · HIGH 8h · NORMAL 24h · LOW 72h, 달력 시간)이며 우선순위 변경 시 재계산된다. 운영사 채널 전용(본사·점장 view DTO 에 필드 없음 — A-D7). generated 는 응답별로 분리 emit(TicketListItemSlaState·TicketDetailSlaState — 값 동일). 목록 배지는 OVERDUE 에서만 그린다(신호 희석 방지 — A-D5).

CommentKind (#027 — CS 티켓 코멘트)

LegalDocumentStatus (#033 — 약관·개인정보 게시본 상태)

generated 노출 enum LegalDocumentResponseStatus·LegalDocumentHistoryItemStatus = 같은 3값. stale 주의: 스케줄러가 없어 status 는 게시 시점 스냅샷이다. 예약본이 발효 시각을 지나도 SCHEDULED 로 남을 수 있으므로, “현재 유효본” 판정은 effectiveAt (<= now 중 최신)으로 한다. /active 응답은 status 를 항상 ACTIVE 로 보정. 상세는 Status Lifecycle.

OperatorAuditAction (#026 — 운영자 액션 감사 로그 액션 종류)

운영자 핵심 변경 액션의 append-only 감사 로그 액션 enum. generated 노출 enum OperatorAuditItemAction(/audit/actions). 신규 액션은 VARCHAR 영속이라 마이그레이션 무관.

대상 타입(OperatorAuditItemTargetType): HQ · STORE · OPERATOR · TERMS · PRIVACY_POLICY · MUSIC(#041) · TICKET(#047). 매장 정지/복구/폐점의 targetType = STORE, targetId = storeId, targetLabel = 매장명, detail = 사유(suspend/close). 음원 업로드/교체의 targetType = MUSIC, targetId = 음원 PK, targetLabel = 곡 제목 스냅샷, detail = 원본 파일명·크기(#041). 음원 소프트삭제(MUSIC_DELETED)의 targetType = MUSIC(재사용), targetId = 음원 PK, targetLabel = 곡 제목 스냅샷(#042). 티켓 상태/우선순위/담당자 변경의 targetType = TICKET, targetId = 티켓 PK, targetLabel = 티켓 title 스냅샷. detail 은 상태/우선순위 이전→이후(예 OPEN→IN_PROGRESS·HIGH→URGENT), 담당자 배정: {email}(이메일) / 해제(#047).

MusicSource (#059 — 음원 타입)

음원의 출처 타입. 업로드 시 지정·불변. 라이브러리 타입(libraryType)과 동일 도메인으로, 음원을 라이브러리에 담을 때 musicSource == libraryType 이어야 한다(불일치 시 400 LIBRARY_TYPE_MISMATCH). generated 노출 enum MusicListItemMusicSource / MusicResponseMusicSource / UploadMusicMusicSource / ListMusicMusicSource. FE 는 MUSIC_SOURCE_META 단일 소스로 라벨/톤을 매핑하며 라이브러리 타입 배지와 동일 표현(색만으로 구분하지 않고 라벨 병기).

플랜(PlanType)의 AI/TRUST 는 본사 구독 등급, 음원의 musicSource 는 개별 음원의 출처 타입으로 의미 레이어가 다르다(라벨만 공유). 라이브러리·플랜·음원의 AI/TRUST 표현은 톤/라벨을 일관 유지한다.

MusicTagOptionType (#132 — 음원 태그 옵션 타입)

음원 분류 태그 옵션(music_tag_option)의 타입. 생성 후 불변. 같은 타입 내 value 는 unique (중복 시 409 MUSIC_TAG_OPTION_DUPLICATE). generated 노출 enum MusicTagOptionResponseType / CreateMusicTagOptionRequestType / ListMusicTagOptionsType(모두 동일 2값). FE /settings/music-options 는 타입별로 2 섹션(장르·무드)을 분리해 렌더한다.

라이브러리·플레이리스트 분류에 쓰일 태그 옵션의 마스터 데이터. 운영사가 CRUD 로 관리하며 삭제는 soft delete(active=false). 음원 업로드 폼이 이 옵션을 소비(드롭다운)하는 연동은 후속.

PlaylistStatus (#060 — 플레이리스트 파생 상태)

플레이리스트의 파생(계산) 상태. DB 컬럼·마이그레이션 없는 응답 계산값으로, BE 단일 함수 derivePlaylistStatus(libraryCount, appliedStoreCount, isDefault)(운영사·본사 서비스 공유)가 집계로 판정한다. 한 PL 은 정확히 1개 상태이며 배타적 우선순위로 결정한다. generated 노출 enum PlaylistResponseStatus / PlaylistListItemStatus / HqPlaylistListItemStatus / HqPlaylistDetailResponseStatus(모두 동일 4값). FE 는 표시만 하며(서버 파생값 신뢰) playlist-status-meta.ts 단일 소스로 라벨/톤을 매핑한다(운영사·본사 일치·라벨 항상 병기).

상태 모델은 5종 설계(EMPTY/MISMATCH/FALLBACK/ACTIVE/UNUSED)이나 PL 상태 배지는 비게이트 4종만 구현한다. SPEC #122(#060 F1)는 plan↔type 게이팅의 첫 구현이나, 운영사/본사 PL 화면의 MISMATCH 배지가 아니라 점장 재생 큐에서 plan 위반 음원을 서버가 제외하는 게이팅만 도입한다(effective plan=store.plan ?? hq.plan vs library.libraryType). 게이팅은 계층적(#169 — 정확일치가 아님): TRUST plan 은 TRUST + AI 라이브러리 모두 허용(TRUST ⊇ AI), AI plan 은 AI 라이브러리만, plan null 은 무제약(전곡). 전부 위반→EMPTY_PLAYLIST(Store Player §“플랜 위반 음원 큐 제외”). PL 상태 배지로서의 MISMATCH(운영사/본사 편집 화면 경고)는 여전히 후속 — 도입 시 우선순위에서 EMPTY 다음·FALLBACK 앞에 들어갈 예정. FALLBACK status 는 기존 isDefault “기본” 배지와 라벨이 겹치므로 FE 는 status 배지로 통합하고 별도 기본 배지를 숨긴다(status≠FALLBACK 인 기본 PL 은 병치 — 상세는 Playlist · HQ Mode 플레이리스트).

TtsVoice (#061 — TTS 안내방송 voice)

본사 TTS 안내방송 합성에 쓰는 voice. 5종. BE TtsVoice enum 이 actor_id·model_version·표시명을 내부 보유하고, API 에는 enum name + 한글 표시명만 노출(actor_id 비노출). generated 노출 enum CreateTtsAnnouncementRequestVoice / TtsAnnouncementListItemVoice / TtsAnnouncementDetailResponseVoice (모두 동일 5값). 목록·상세는 BE voiceDisplayName(한글)을 단일 소스로 표시한다. 생성 폼만 합성 전이라 BE 표시명을 받을 수 없으므로 FE tts-voice-meta.ts 가 value→한글 라벨을 보유(라벨 어긋나도 합성은 enum value 로 진행 — 안전).

✅ voice별 tone preset 선택 — #063 도착(아래 TtsTonePreset). FE 생성 폼 라벨은 BE TtsVoice.displayName 과 정합을 유지한다(BE 가 응답 voiceDisplayName 의 단일 소스).

TtsTonePreset (#063 — TTS 안내방송 톤 프리셋)

본사 TTS 안내방송 합성의 감정 톤(Typecast emotion). 6종. voice별 지원 집합이 다르며 모든 voice 가 NORMAL(기본) 을 지원한다. BE TtsTonePreset enum 이 Typecast emotion 파라미터·표시명을 내부 보유하고, API 에는 enum name + 한글 표시명(*DisplayName)만 노출. generated 노출 enum CreateTtsAnnouncementRequestTonePreset(@nullable) / UpdateTtsAnnouncementRequestTonePreset(@nullable) / TtsAnnouncementListItemTonePreset / TtsAnnouncementDetailResponseTonePreset / TtsTonePresetOptionPreset (모두 동일 6값). voice별 허용 매핑은 GET /api/v1/hq/tts-voices(TtsVoiceListResponse)가 단일 소스.

톤 표시명은 BE tonePresetDisplayName(voices 응답·목록·상세)이 단일 소스다. FE 는 voices 응답이 아직/실패일 때의 폴백 라벨만 tts-voice-meta.ts 에 보유(NORMAL 만 노출). 생성·수정 폼은 선택 voice 의 허용 톤만 옵션으로 보이고, voice 미지원 톤은 UI 가 차단(혹시 도달 시 BE 400 TTS_INVALID_TONE_PRESET).

DispatchRequestTarget (송출 슬라이스 — 안내방송 송출 대상)

본사 안내방송 송출(POST /api/v1/hq/announcements/{id}/dispatch) + 반복 예약 (POST /api/v1/hq/dispatch-schedules)의 대상 구분. 3종 (SPEC #144 REGION 추가). generated DispatchRequestTarget(DispatchRequest.target) / CreateDispatchScheduleRequestTarget / DispatchScheduleResponseTarget.

ALL/STORES/REGION 분기는 즉시 송출·반복 예약 양쪽에서 동일. FE 는 송출/예약 다이얼로그 target 라디오에 “지역” 옵션 + region select(시/도) 를 노출하고, target=REGION 인데 미선택이면 제출 disabled(BE 400 선검증). 상세는 HQ TTS 안내방송 송출.

Region (SPEC #144 — 매장 지역 시/도)

매장(Store.region, nullable)의 시/도 enum. REGION 모드 송출의 그룹핑 축. 17종. 본사가 매장 상세에서 태그하면 target=REGION 으로 같은 시/도 매장군에 일괄 송출한다. BE Region enum 이 displayName(한글)을 내부 보유하고, OpenAPI 에는 enum name 만 노출 → FE 는 한글 라벨 맵을 apps/space/src/lib/region.ts 에 단일 소스로 보유(generated 의 per-field region enum 17값을 value 소스로 재사용). generated 노출 enum: UpdateStoreRegionRequestRegion / HqStoreDetailResponseRegion / DispatchRequestRegion / CreateDispatchScheduleRequestRegion / DispatchScheduleResponseRegion(모두 동일 17값, nullable).

Store.region 이 null(미지정)이면 지역 송출에 포함되지 않는다. 편집은 본사 매장 상세 매장 지역 편집 참고. 자동 주소 파싱 채움은 범위 밖(수동 선택).

DispatchStatus (송출 슬라이스 — 안내방송 송출 상태)

송출 row(announcement_dispatch.status)의 생명주기. 5종 (SPEC #077 CANCELED 추가 + SPEC #078 SCHEDULED 추가 + SPEC #143 MISSED 추가). 전이는 단방향 — SCHEDULED → PENDING → PLAYED(정상 경로) · SCHEDULED → CANCELED(예약 직접 취소) · PENDING → CANCELED(즉시/예약-전이된 PENDING 취소) · PENDING → MISSED(들리지 않은 채 종결 — 사유 3종, 아래 DispatchMissedReason). PLAYED·CANCELED·MISSED 는 종착 상태(이후 전이 없음 — 시간 되감기 X · 중복 취소 가드).

SCHEDULED ──┬──> PENDING ──┬──> PLAYED   (ack outcome=PLAYED — 실제 재생 완료)
            │              ├──> MISSED   (EXPIRED · PLAYBACK_FAILED · SKIPPED)
            └──> CANCELED <─┘

DispatchMissedReason (미재생(MISSED) 사유 — 감사 #11)

announcement_dispatch.missed_reason. MISSED 가 아닌 송출은 항상 null. 상태를 더 쪼개지 않고 사유 컬럼으로 분리한 이유: 모든 조회·집계의 status IN (...) 을 동기화해야 해 오집계 위험이 커지기 때문이다 (같은 “들리지 않음” 버킷을 유지하고 사유로만 구분).

DispatchAckOutcome (점장 ack 재생 결과 — 감사 #11)

POST /api/v1/store/announcements/{dispatchId}/ack 의 선택 본문 AckAnnouncementRequest outcome. 생략 시 PLAYED(하위 호환). generated 타입은 endpoint scope AckAnnouncementRequestOutcome.

응답은 종착이든 재전달 대기든 동일한 204 — FE 는 결과 보고만 하고 상태를 판단하지 않는다. 재시도 정책은 BE 소유라 FE 는 자체 재시도 카운터를 두지 않고 실패할 때마다 그대로 FAILED 를 보고한다. 무한 재전달은 grace(10분) 자동 만료가 상한. 종착 이후 재전송은 outcome 과 무관하게 404(첫 결론 불변).

상세는 AnnouncementDispatch 테이블 · Store Player 동시재생 · 본사 송출 취소.

DispatchCalendarEventKind / DispatchCalendarEventStatus (송출 캘린더)

송출 캘린더(GET /api/v1/hq|store/dispatch-calendar, DispatchCalendarEvent)의 이벤트 분류 enum. 본사·점장 공용.

DispatchCalendarEventKind — is_emergency·is_hq_origin 에서 파생.

DispatchCalendarEventStatus — DispatchStatus 와 동일 5종(SCHEDULED → PENDING → {PLAYED, CANCELED, MISSED} 단방향). 캘린더 조회는 CANCELED(본사 취소)만 제외하고 MISSED(들리지 않은 채 종결)는 포함한다 — 안 나간 방송을 캘린더에서 지우면 본사가 결손을 못 본다. FE 캘린더 톤: SCHEDULED/PENDING=info, PLAYED=success, CANCELED·MISSED=muted(취소선).

상세는 DispatchCalendarResponse DTO · 본사 캘린더 · 점장 캘린더.

DispatchScheduleFrequency (반복 송출 예약 — 빈도, #139 확장)

본사 반복 송출 예약(dispatch_schedule.frequency)의 빈도. 5종 (#139 — 시각형 HOURLY·EVEN_HOURS· ODD_HOURS 추가, 기존 DAILY·WEEKLY 보존). generated CreateDispatchScheduleRequestFrequency / DispatchScheduleResponseFrequency(동일 값). FE radiogroup·라벨(dispatch-schedule-meta.ts FREQUENCY_LABELS)·타임테이블 전개(expandOperatingHours)가 이 enum 단일 소스를 재사용한다.

시각형(HOURLY/EVEN_HOURS/ODD_HOURS)은 startHour·endHour(운영시간)가 필수이며 slotTime 의 시(HH)는 무시된다(분 MM만 매시 오프셋). 빈도↔요일·빈도↔운영시간 불일치·범위 위반은 400 DISPATCH_SCHEDULE_INVALID. 백그라운드 디스패처가 시각형이면 하루 N건(운영시간 hour마다)으로 전개한다. 상세는 반복 송출 예약.

TtsAnnouncementSource (즉시방송 슬라이스 — 안내방송 출처)

tts_announcement.source(V24)의 출처 구분. 2종. 같은 테이블을 본사 안내방송과 점장 즉시방송이 공유하되 source 로 격리한다.

보안 불변식 — 본사-facing 쿼리는 모두 source='HQ' 로 격리해 STORE_BROADCAST row 가 본사 화면·계약에 노출되지 않는다. 점장 즉시방송 흐름은 점장 즉시방송 · TtsAnnouncement 테이블.

HqAuditAction (#067 도입 · #068 확장 — 본사 감사 액션)

hq_audit_log.action(V27)의 본사(HQ_MANAGER) 액션 enum. generated FE 도메인은 HqAuditItemAction·ListHqAuditDispatchesAction(value 동일) — 총 19종(#181 영업시간 기준). 아래 표는 안내방송 라이프사이클 핵심 + 원격중단·지역·CM송·점장 발급 액션이며, ticket·store·반복 예약 액션은 HQ Mode 감사 참조.

generated 도메인(HqAuditItemAction·ListHqAuditDispatchesAction)에는 추가 액션(ticket·store·반복 예약 등)도 포함된다 — 위는 안내방송 송출 라이프사이클 핵심 액션 + #144 지역 변경 + #174 CM송 등록/교체. Followups: 점장 즉시방송 audit 은 별도 enum/테이블(F3 — store_audit_log). 상세는 HqAuditLog · HQ Mode 감사.

HqAuditActorRole (#067 — 본사 감사 행위자 역할)

hq_audit_log.actor_role(V27). 2종. impersonate 컨텍스트 구분 — impersonated_by_operator_id 컬럼과 정합성을 CHECK 제약으로 강제한다((actor_role='OPERATOR_IMPERSONATING') = (impersonated_by_operator_id IS NOT NULL)). generated FE 도메인은 HqAuditItemActorRole(value 동일).

impersonate 미러 — principal.accountId = HQ_MANAGER 계정(actor_account_id), principal.impersonatedBy = 원본 운영자(impersonated_by_operator_id). 둘 다 lookup 실패 시 IllegalStateException → 액션 롤백. 상세는 HqAuditLog.

HqAuditTargetType (#067 — 본사 감사 대상 유형)

hq_audit_log.target_type(V27)의 대상 유형 enum. generated FE 도메인은 HqAuditItemTargetType (value 동일) — TTS_ANNOUNCEMENT(#067)·SUPPORT_TICKET(#101)·STORE(#105)·COMMERCIAL(#174) 4종.

Followups: 후속 액션 확장에 따라 대상 유형도 추가 가능(예: announcement create/update/delete 도 같은 유형). 상세는 HqAuditLog · HQ Mode 감사.

StoreAuditAction (#114 — 매장 감사 액션)

store_audit_log.action(V36)의 점장(STORE_MANAGER) 액션 enum. 현재 11종(HqAudit 처럼 점진 확장 — 새 점장 액션은 VARCHAR(48) 영속이라 마이그레이션 무관). HqAuditAction· OperatorAuditAction 과 의미가 분리된 별도 enum (actor·테넌트 스코프·UI 권한 모델이 다름). v1 은 기록만이라 generated FE 도메인 노출은 조회 view 후속에서.

⚠️ 기기 등록(registerStoreDevice)은 audit 하지 않는다 — player 마운트마다 일어나는 멱등 동작이라 남기면 감사 로그가 그것만으로 찬다(#178).

Followups: 점장 액션 도착 시 enum 확장. v1 은 기록만 — 조회 view(운영자/본사) 는 후속(D5). 상세는 StoreAuditLog · Store 감사.

StoreAuditActorRole (#114 — 매장 감사 행위자 역할)

store_audit_log.actor_role(V36). 2종. HqAuditActorRole 미러 — impersonate 컨텍스트를 구분하고 impersonated_by_operator_id 컬럼과 정합성을 CHECK 제약으로 강제한다 ((actor_role='OPERATOR_IMPERSONATING') = (impersonated_by_operator_id IS NOT NULL)).

impersonate 미러 — principal.accountId = 점장 계정(actor_account_id), principal.impersonatedBy = 원본 운영자(impersonated_by_operator_id). 둘 다 lookup 실패 시 IllegalStateException → 액션 롤백. 상세는 StoreAuditLog.

StoreAuditTargetType (#114 — 매장 감사 대상 유형)

store_audit_log.target_type(V36)의 대상 유형 enum. 현재 5종(ASCII 사전순). 후속 액션 확장에 따라 추가 가능.

상세는 StoreAuditLog · Store 감사.

OpenAPI 동기화

backend enum 변경 시 pnpm sync-api 로 packages/api-client/src/generated/ 의 TypeScript union / const enum 자동 갱신. 수기 정의 금지 (frontend [[feedback-15]] 정합).

References

• SPEC #002 §2-3 (HqType · StoreType · PlanType · StoreStatus)
• SPEC #003 §2-1 (Role · AccountStatus)
• SPEC #005 (ImpersonationToken)
• linkmusic-msa-space-was/src/main/kotlin/.../domain/enum/
• linkmusic-frontend-space/packages/api-client/src/generated/schemas/