Request · Response DTOs (전체 카탈로그)

{ email: string; password: string }

{
  accessToken: string;
  accessExpiresInSeconds: number;  // access 토큰 수명(초, default 900 = 15min)
  refreshToken: string;
  refreshExpiresAt: string;        // refresh 만료 ISO 8601 절대 시각
  accountId: string;
  role: "OPERATOR" | "HQ_MANAGER" | "STORE_MANAGER";
  passwordMustChange: boolean;
}

{ refreshToken: string }

{
  id: string;            // UUID
  email: string;
  name?: string;
  role: Role;
  hqId?: string;         // HQ_MANAGER 만
  storeId?: string;      // STORE_MANAGER 만
  passwordMustChange: boolean;
  termsRequiresAgreement: boolean;   // SPEC #005
  privacyRequiresAgreement: boolean;
  hqName?: string;       // SPEC #016 — HQ_MANAGER 만 값(hqId→Hq.name). 그 외 omit
}

{ currentPassword: string; newPassword: string }

// 계정 설정(setup)
SetupVerifyRequest    { token: string }
SetupVerifyResponse   { email: string; role: "OPERATOR"|"HQ_MANAGER"|"STORE_MANAGER"; expiresAt: string }
SetupCompleteRequest  { token: string; newPassword: string }   // → 204
 
// 비밀번호 재설정(reset)
PasswordResetRequestRequest { email: string }                  // → 204 (존재 은닉)
PasswordResetConfirmRequest { token: string; newPassword: string } // → 204
 
// 이메일 변경
EmailChangeRequestRequest   { newEmail: string }   // 인증된 본인(operator/hq/store me) → 204
EmailChangeConfirmRequest   { token: string }      // public, 새 주소 인증 → 204

{ exchangeToken: string }

{
  accessToken: string;
  accessExpiresInSeconds: number;
  refreshToken: string;
  refreshExpiresAt: string;       // 임퍼소네이션은 60분
  accountId: string;              // 대상 HQ_MANAGER 계정
  role: "OPERATOR" | "HQ_MANAGER" | "STORE_MANAGER";
  impersonatedBy: string;         // 운영자(OPERATOR) accountId
  operatorEmail: string;          // 배너 표시용 운영자 이메일
  hqName: string;                 // 배너·상단바 표시용 본사명
}

{
  version: string;          // 예 "v1.0"
  content: string;          // markdown (FE 가 react-markdown + rehype-sanitize 로 렌더)
  publishedAt: string;      // ISO instant — 게시(저장) 시각
  effectiveAt: string;      // ISO instant — 발효 시각. 이 시각 이후 "현재 유효본" 후보 (#033)
  status: "SCHEDULED" | "ACTIVE" | "SUPERSEDED"; // 저장된 상태(게시 시점, stale 가능). 유효본 판정은 effectiveAt 기준 (#033)
}

// GET /api/v1/admin/{terms,privacy-policy}
{ items: LegalDocumentHistoryItem[] }   // effectiveAt DESC, id DESC
 
// LegalDocumentHistoryItem — 본문(content) 제외 (목록 경량화)
{
  id: string;            // UUID — by-id 상세 조회 키
  version: string;
  publishedAt: string;   // ISO instant
  effectiveAt: string;   // ISO instant
  status: "SCHEDULED" | "ACTIVE" | "SUPERSEDED";
}

{
  version: string;        // maxLength 32. 동일 version 중복은 409
  content: string;        // markdown. maxLength 200000
  effectiveAt?: string | null; // ISO instant. null·과거(±60s)=즉시 발효, 미래=예약. 과거(>60s)=400 (#033)
}

{
  version: string;   // maxLength 32. 동의할 문서 버전 — 현재 유효본과 일치해야 함.
                     // 불일치 시 400 INVALID_LEGAL_VERSION
}

{
  hq: {
    name: string;
    businessNumber?: string;   // SPEC #013, ###-##-##### 패턴
    plan: "AI" | "TRUST";
    billingAnchorDay: number;  // 1~31
    llmKeywords?: string;
    llmMaxPerHour: number;     // 1~12
  };
  consent: { termsVersion: string; privacyPolicyVersion: string };
  manager: { email: string; tempPassword: string; name: string };
}

{ hqId: string; managerAccountId: string }

// generated `packages/api-client/src/generated/schemas/hqAdminListResponse.ts`
{
  items: HqAdminListItem[];
  page: number;   // 0-base 페이지 번호
  size: number;   // 페이지 크기 (1..100)
  total: number;  // 필터 적용 후 전체 건수
}

// generated `packages/api-client/src/generated/schemas/hqAdminListItem.ts`
{
  id: string;
  name: string;
  businessNumber?: string;
  type: "FRANCHISE" | "INDEPENDENT";   // HqType (Store 타입과 다름 — `DIRECT` 는 StoreType)
  plan?: "AI" | "TRUST";
  status: "ACTIVE" | "ONBOARDING" | "UNPAID" | "SUSPENDED";
  storeCount: number;                  // #045 — 현재 페이지 hqId 집합 한정 집계
  billingAnchorDay?: number;
  paymentDueDays?: number | null;  // #028 nullable — 미산정 시 null. generated `number | null`. FE `== null → "—"`
  createdAt: string;
}

// generated `packages/api-client/src/generated/schemas/adminListHqsParams.ts`
{
  q?: string;        // 본사명·사업자번호 부분일치(대소문자 무시, max 100)
  status?: "ACTIVE" | "ONBOARDING" | "UNPAID" | "SUSPENDED";  // 미지정 = 가상 본사 포함 전체
  type?: "FRANCHISE" | "INDEPENDENT";
  plan?: "AI" | "TRUST";
  page?: number;     // 0-base (기본 0)
  size?: number;     // 1..100 clamp (기본 20)
}

{ items: Array<{ id: string; name: string }> }

// generated `packages/api-client/src/generated/schemas/impersonationIssueResponse.ts`
{ exchangeToken: string; expiresInSeconds: number }

// generated `packages/api-client/src/generated/schemas/suspendRequest.ts`
{ reason: string }  // @NotBlank, @Size(max = 255)

// generated `packages/api-client/src/generated/schemas/hqStatusResponse.ts`
{
  hqId: string;
  status: HqStatusResponseStatus; // ACTIVE | ONBOARDING | UNPAID | SUSPENDED
  suspensionReason?: string;      // #024 — SUSPENDED 일 때만 채워짐. 그 외엔 미포함(optional)
}

// generated `packages/api-client/src/generated/schemas/storeSuspendRequest.ts`
{ reason: string }  // @NotBlank, @Size(max = 255)

// generated `packages/api-client/src/generated/schemas/storeStatusResponse.ts`
{
  storeId: string;
  status: StoreStatusResponseStatus; // ACTIVE | SUSPENDED | INACTIVE
  suspensionReason?: string | null;  // SUSPENDED 직후만 채워짐. reactivate 시 null/미포함
}

// generated `packages/api-client/src/generated/schemas/storeCloseRequest.ts`
{ reason: string }  // @NotBlank, @Size(max = 255)

// generated `packages/api-client/src/generated/schemas/storeCloseResponse.ts`
{
  storeId: string;
  closedAt: string;  // 폐점 시각 (ISO-8601). 이후 closedAt != null 이 폐점 판정
}

// generated `packages/api-client/src/generated/schemas/hqDetailResponse.ts`
{
  id: string;
  name: string;
  businessNumber?: string;
  type: "FRANCHISE" | "INDEPENDENT";          // HqType
  plan?: "AI" | "TRUST";
  status: "ACTIVE" | "ONBOARDING" | "UNPAID" | "SUSPENDED";  // HqStatus
  llmAutomentEnabled: boolean;
  llmKeywords?: string;
  llmMaxPerHour: number;
  billingAnchorDay?: number;
  storeCount: number;                         // countGroupedByHqId 재사용 (N+1 없음)
  suspensionReason?: string;                  // #024 — SUSPENDED 일 때만. 그 외엔 미포함(optional)
  createdAt: string;
  updatedAt: string;
  managers: HqManagerItem[];                  // role=HQ_MANAGER, findByHqIdAndRole
}

// generated `packages/api-client/src/generated/schemas/updateHqRequest.ts`
UpdateHqRequest {
  name: string;   // 변경할 본사 이름. 비-blank · @maxLength 255 (Hq.name 생성 제약 미러)
}

// generated `packages/api-client/src/generated/schemas/hqManagerItem.ts`
{
  id: string;
  email: string;
  name?: string;
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";  // AccountStatus
  passwordMustChange: boolean;                   // true → "변경 필요" 배지
  lastLoginAt?: string | null;                   // #028 nullable — 미로그인 시 null. FE `?? undefined → "—"`
  createdAt: string;
}

// generated `packages/api-client/src/generated/schemas/hqConsentsResponse.ts`
HqConsentsResponse {
  hqId: string;
  hqName: string;
  status: "ACTIVE" | "ONBOARDING" | "UNPAID" | "SUSPENDED";  // HqStatus (현재 협약 상태)
  terms: ConsentRecord[];                                    // 이용약관 동의 이력 (동의 시각 내림차순)
  privacy: ConsentRecord[];                                  // 개인정보처리방침 동의 이력 (동의 시각 내림차순)
  termsReagreeRequired: boolean;                             // 현재 유효 약관 버전 > 최신 동의 → true
  privacyReagreeRequired: boolean;                           // 현재 유효 개인정보 버전 > 최신 동의 → true
}

// generated `packages/api-client/src/generated/schemas/consentRecord.ts`
ConsentRecord {
  documentVersion: string;        // 동의한 문서 버전
  agreedAt: string;               // 동의 시각 (ISO-8601, FE 가 KST 표기)
  signerName?: string | null;     // 서명자 이름 (없으면 null → FE "—")
  agreedIp?: string | null;       // 동의 시 IP (없으면 null → FE "—")
}

{
  store: {
    name: string;
    address?: string;
    managerName?: string;
    managerEmail?: string;
    managerPhone?: string;
    plan: "AI" | "TRUST";
    billingAnchorDay: number;
  };
  consent: { termsVersion: string; privacyPolicyVersion: string };
}

{ storeId: string }

// generated `packages/api-client/src/generated/schemas/storeAdminListResponse.ts`
{
  items: StoreAdminListItem[];
  page: number;   // 0-base 페이지 번호
  size: number;   // 페이지 크기 (1..100)
  total: number;  // 필터 적용 후 전체 건수
}

// generated `packages/api-client/src/generated/schemas/storeAdminListItem.ts`
{
  id: string;
  name: string;
  type: "INDEPENDENT" | "DIRECT" | "FRANCHISE";  // StoreType (HqType 과 다름 — `DIRECT` 는 StoreType 전용)
  status: "ACTIVE" | "INACTIVE" | "SUSPENDED";    // StoreStatus
  hqId: string;
  hqName: string;                // Hq(name) join — N+1 회피
  plan?: "AI" | "TRUST";
  address?: string;
  managerName?: string;
  billingAnchorDay?: number;
  lastOnlineAt?: string | null;  // #028 nullable — 미접속 시 null. FE `?? undefined → "—"` (온/오프라인 판정 v1 미포함)
  closedAt?: string | null;      // SPEC #044 D2 — 폐점 시각(ISO-8601). 폐점 안 했으면 null. status 미지정 = 폐점 포함 전체이므로, FE 가 행에 폐점 배지를 노출
  createdAt: string;
  hasManagerAccount: boolean;    // SPEC #021 — 해당 매장에 role=STORE_MANAGER OperatorAccount 존재 여부(exists 집계, N+1 없음). FE 가 [계정 발급]/"발급됨" 분기
}

// generated `packages/api-client/src/generated/schemas/adminListStoresParams.ts`
{
  q?: string;        // 매장명·본사명·주소 부분일치(대소문자 무시, max 100)
  status?: "ACTIVE" | "SUSPENDED" | "INACTIVE";   // 미지정 = 폐점 포함 전체
  type?: "DIRECT" | "FRANCHISE" | "INDEPENDENT";
  plan?: "AI" | "TRUST";
  hqId?: string;     // 특정 본사 매장만 스코프 (#020 — HQ 상세 매장 탭). 미지정 시 전체
  page?: number;     // 0-base (기본 0)
  size?: number;     // 1..100 clamp (기본 20)
}

// generated `packages/api-client/src/generated/schemas/storeDetailResponse.ts`
{
  id: string;
  name: string;
  type: "INDEPENDENT" | "DIRECT" | "FRANCHISE";   // StoreType
  status: "ACTIVE" | "INACTIVE" | "SUSPENDED";     // StoreStatus
  hqId: string;
  hqName: string;                  // Hq(name) join — N+1 회피
  plan?: "AI" | "TRUST" | null;
  address?: string | null;
  managerName?: string | null;     // 매장 담당자(점장 연락처용)
  managerEmail?: string | null;
  managerPhone?: string | null;
  billingAnchorDay?: number | null;
  lastOnlineAt?: string | null;    // ISO-8601, 미접속 시 null → FE "—"
  lastHeartbeatAt?: string | null; // ISO-8601, 없으면 null → FE "—"
  closedAt?: string | null;        // 폐점 시각, 있으면 개요 "폐점일" danger highlight 행
  createdAt: string;
  updatedAt: string;
  managers: StoreManagerSummaryItem[];  // role=STORE_MANAGER, SUSPENDED·WITHDRAWN 포함
}

// generated `packages/api-client/src/generated/schemas/storeManagerSummaryItem.ts`
{
  id: string;
  email: string;
  name?: string | null;
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";  // AccountStatus
  passwordMustChange: boolean;                   // true → "변경 필요" 배지
  lastLoginAt?: string | null;                   // 미로그인 시 null → FE "—"
  createdAt: string;
}

// generated `packages/api-client/src/generated/schemas/storeManagerIssueRequest.ts`
{
  email: string;         // OpenAPI maxLength 255 (backend 런타임 @Email)
  tempPassword: string;  // OpenAPI minLength 8, maxLength 100 — 최초 로그인 시 변경(passwordMustChange)
  name: string;          // OpenAPI maxLength 255 (backend 런타임 @NotBlank)
}

// generated `packages/api-client/src/generated/schemas/storeManagerIssueResponse.ts`
{
  storeId: string;
  managerAccountId: string;  // 생성된 OperatorAccount(role=STORE_MANAGER, storeId tenancy) id
}

// generated `schemas/storeManagerListResponse.ts` · `schemas/storeManagerListItem.ts`
StoreManagerListResponse { items: StoreManagerListItem[] }   // createdAt asc, id asc
 
StoreManagerListItem {
  id: string;
  email: string;
  name?: string | null;                                  // 없으면 null
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";          // StoreManagerListItemStatus
  passwordMustChange: boolean;                            // 임시 비번 상태(첫 로그인 변경 강제)
  lastLoginAt?: string | null;                            // ISO-8601, 없으면 null
  createdAt: string;                                      // ISO-8601
}

// generated `schemas/resetPasswordRequest.ts` · `storeManagerSuspendRequest.ts` · `storeManagerAccountResponse.ts`
ResetPasswordRequest         { tempPassword: string; }    // OpenAPI minLength 8, maxLength 100
StoreManagerSuspendRequest   { reason: string; }          // OpenAPI maxLength 255 (backend 런타임 @NotBlank)
 
StoreManagerAccountResponse {
  id: string;
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";          // 전이 후 상태
  passwordMustChange: boolean;                            // 비번 재설정 시 true
}

// generated `packages/api-client/src/generated/schemas/hqMeResponse.ts`
{
  id: string;                          // 본사 id (UUID)
  name: string;                        // 본사명
  type: "FRANCHISE" | "INDEPENDENT";   // HqMeResponseType — HqType (Store 타입과 다름)
  plan?: "AI" | "TRUST" | null;        // @nullable — 요금제 없으면 null
  status: "ACTIVE" | "ONBOARDING" | "UNPAID" | "SUSPENDED";  // HqMeResponseStatus
  businessNumber?: string | null;      // @nullable — 사업자등록번호(NNN-NN-NNNNN), 없으면 null
  billingAnchorDay?: number | null;    // @nullable — 청구 기준일(1~31), 없으면 null
  storeCount: number;                  // 소속 매장 수
  commercialCycleSongs: number;        // SPEC #095 — 본사 CM송 사이클 빈도(N곡마다 1회). V32 default 5 · 1~100
  duckEnabled: boolean;                // 더킹 — 멘트 중 배경음악 감쇠 사용 여부 default. BE 신규 default true
  duckVolumePercent: number;           // 더킹 목표 볼륨(정상 대비 %, 0~100). BE 신규 default 20
  duckFadeMs: number;                  // 더킹 fade in/out 시간(ms, 0~5000). BE 신규 default 400
  createdAt: string;                   // 본사 생성 시각 (ISO-8601)
}

// generated `packages/api-client/src/generated/schemas/updateHqMeRequest.ts`
{
  /** 본사 매니저 본인 이름. 생략 또는 null = 미변경. non-null 이면 1~50자. */
  name?: string | null;  // @minLength 1 @maxLength 50 @nullable
  /** SPEC #095 — 본사 CM송 사이클 빈도(N곡마다 1회 삽입). 생략 또는 null = 미변경. non-null 이면 1~100. */
  commercialCycleSongs?: number | null;  // @minimum 1 @maximum 100 @nullable
}

// generated `packages/api-client/src/generated/schemas/updateHqDuckingRequest.ts`
UpdateHqDuckingRequest {
  duckEnabled: boolean;       // 필수
  duckVolumePercent: number;  // 필수 · @minimum 0 @maximum 100
  duckFadeMs: number;         // 필수 · @minimum 0 @maximum 5000
}

// generated `packages/api-client/src/generated/schemas/storeMeResponse.ts`
{
  id: string;                                    // 매장 id (UUID)
  name: string;                                  // 매장명
  type: "DIRECT" | "FRANCHISE" | "INDEPENDENT";  // StoreMeResponseType — StoreType (HqType 과 다름)
  status: "ACTIVE" | "SUSPENDED" | "INACTIVE";   // StoreMeResponseStatus
  hqId: string;                                  // 소속 본사 id (UUID)
  hqName: string;                                // 소속 본사명 (Hq(name) join)
  plan?: "AI" | "TRUST" | null;                  // @nullable — 요금제 없으면 null
  address?: string | null;                       // @nullable — 매장 주소, 없으면 null
  billingAnchorDay?: number | null;              // @nullable — 청구 기준일(1~31), 없으면 null
  hqCommercialCycleSongs: number;                // SPEC #095 — 소속 본사 CM송 사이클 빈도 default(N곡마다 1회, transparency 노출)
  storeCommercialCycleSongs: number | null;      // SPEC #103 — 매장 override (null=없음, 1..100=적용). 본사가 매장 상세에서 편집
  commercialCycleSongs: number;                  // SPEC #103 — **effective 값**(매장 override ?? HQ default). 점장 player 가 직접 소비
  duckEnabled: boolean;                          // 더킹 — **effective 값**(매장 override ?? HQ default). 점장 player 가 직접 소비
  duckVolumePercent: number;                     // 더킹 목표 볼륨(%) effective(0~100). 매장 override ?? HQ default
  duckFadeMs: number;                            // 더킹 fade 시간(ms) effective(0~5000). 매장 override ?? HQ default
  createdAt: string;                             // 매장 생성 시각 (ISO-8601)
}

// generated `packages/api-client/src/generated/schemas/updateStoreMeRequest.ts`
{
  /** 점장 매니저 본인 이름. 생략 또는 null = 미변경. non-null 이면 1~50자. */
  name?: string | null;  // @minLength 1 @maxLength 50 @nullable
}

// generated `packages/api-client/src/generated/schemas/storeOwnPlaylistListResponse.ts`
StoreOwnPlaylistListResponse {
  items: StoreOwnPlaylistListItemResponse[];  // 선택 가능 PL 목록(자기 본사 활성 PL)
  page: number;                               // 0-base
  size: number;
  total: number;
}
 
// storeOwnPlaylistListItemResponse.ts
StoreOwnPlaylistListItemResponse {
  id: string;
  name: string;
  isDefault: boolean;       // 본사 기본 PL 여부(활성 미선택 시 점장 큐 fallback 대상)
  libraryCount: number;     // 담긴 활성 라이브러리 수
  status: "EMPTY" | "UNUSED" | "ACTIVE" | "FALLBACK";  // 파생 상태(응답 계산값). 배타 우선순위 EMPTY>FALLBACK>ACTIVE>UNUSED
  active: boolean;          // 현재 이 매장의 활성 PL 인지(현재 선택 표시용)
  updatedAt: string;        // ISO-8601
}
 
// listStorePlaylistsParams.ts — query
ListStorePlaylistsParams { q?: string; page?: number; size?: number; }

// generated `packages/api-client/src/generated/schemas/setStoreOwnActivePlaylistRequest.ts`
SetStoreOwnActivePlaylistRequest {
  playlistId?: string | null;   // 적용할 PL id(자기 본사 활성 PL). null = 활성 해제(본사 기본 PL fallback)
}

// generated `packages/api-client/src/generated/schemas/storeActivePlaylistResponse.ts`
StoreActivePlaylistResponse {
  active: boolean;                // 활성 PL 적용 여부 (미적용 시 false)
  playlistId?: string | null;     // 적용된 PL id (미적용 시 null)
  name?: string | null;           // 적용된 PL 이름 (미적용 시 null)
  libraryCount?: number | null;   // 담긴 활성 라이브러리 수 (미적용 시 null)
  appliedAt?: string | null;      // 적용 시각 근사 (store 갱신 시각, 미적용 시 null, ISO-8601)
}

// generated `packages/api-client/src/generated/schemas/hqDashboardResponse.ts`
{
  totalStores: number;      // 산하 매장 총수 (ACTIVE+INACTIVE+SUSPENDED, 폐점 포함)
  activeStores: number;     // ACTIVE 매장 수
  inactiveStores: number;   // INACTIVE 매장 수
  suspendedStores: number;  // SUSPENDED 매장 수
  closedStores: number;     // 폐점(closedAt 설정) 매장 수
}

// generated `packages/api-client/src/generated/schemas/hqUndeliveredTodayResponse.ts`
{
  undeliveredStoreCount: number;  // 오늘(KST) 송출 중 미도달(PENDING) distinct 매장 수
}

// generated `packages/api-client/src/generated/schemas/hqSupportUnreadSignalResponse.ts`
{
  latestOperatorReplyAt?: string | null;  // 본인 본사 ticket 의 운영자 REPLY max createdAt(없으면 null)
  openOrInProgressCount: number;           // 미해결(OPEN+IN_PROGRESS) ticket 수(보조)
}

// generated `packages/api-client/src/generated/schemas/hqStoreListResponse.ts`·`hqStoreListItem.ts`
HqStoreListResponse {
  items: HqStoreListItem[];
  page: number;   // 0-base
  size: number;   // 1..100
  total: number;  // 필터 적용 후 전체 건수
}
 
HqStoreListItem {
  id: string;
  name: string;
  type: "DIRECT" | "FRANCHISE" | "INDEPENDENT";  // HqStoreListItemType
  status: "ACTIVE" | "SUSPENDED" | "INACTIVE";   // HqStoreListItemStatus
  address?: string | null;       // @nullable
  managerName?: string | null;   // @nullable — 매장 담당자 이름
  lastOnlineAt?: string | null;  // @nullable — ISO-8601
  closedAt?: string | null;      // @nullable — 폐점 시각 (FE 폐점 배지)
  createdAt: string;             // ISO-8601
  hasManagerAccount: boolean;    // STORE_MANAGER(점장) 계정 존재 여부
}

// generated `packages/api-client/src/generated/schemas/hqStoreDetailResponse.ts`·
// `hqStoreManagerInfo.ts`·`hqStoreActivePlaylistInfo.ts`
HqStoreDetailResponse {
  id: string;
  name: string;
  address?: string | null;       // @nullable
  managerName?: string | null;   // @nullable — store.manager_name 연락 컬럼 (#116). 점장 계정과 별개
  managerEmail?: string | null;  // @nullable — store.manager_email 연락 컬럼 (#116)
  phone?: string | null;         // @nullable — store.manager_phone 컬럼
  type: "DIRECT" | "FRANCHISE" | "INDEPENDENT";   // HqStoreDetailResponseType
  status: "ACTIVE" | "SUSPENDED" | "INACTIVE";    // HqStoreDetailResponseStatus
  closedAt?: string | null;      // @nullable — 폐점 시각 (FE 폐점 배지)
  storeManager?: HqStoreManagerInfo;     // null = 점장 계정 미발급
  activePlaylist?: HqStoreActivePlaylistInfo;  // null = 활성 PL 없음(본사 기본 PL fallback 가능)
  commercialCycleSongs?: number | null;  // SPEC #103 — 매장 CM 사이클 빈도 override (null=HQ default 사용, 1..100=매장 override)
  region?: Region | null;                // SPEC #144 — 매장 지역(시/도) enum 17종 (null=미지정). REGION 모드 송출 그룹핑 축. HqStoreDetailResponseRegion
  duckEnabled?: boolean | null;          // 더킹 사용 여부 override (null=없음, HQ default 사용)
  duckVolumePercent?: number | null;     // 더킹 목표 볼륨(%) override (null=없음, 0..100=매장 override)
  duckFadeMs?: number | null;            // 더킹 fade 시간(ms) override (null=없음, 0..5000=매장 override)
  hqDuckEnabled: boolean;                // 본사 더킹 사용 여부 default (참조용 — override UI 상속 표기)
  hqDuckVolumePercent: number;           // 본사 더킹 목표 볼륨(%) default (참조용, 0..100)
  hqDuckFadeMs: number;                  // 본사 더킹 fade 시간(ms) default (참조용, 0..5000)
  createdAt: string;             // ISO-8601
  updatedAt: string;             // ISO-8601
}
 
// 점장(STORE_MANAGER) 계정 정보 (미발급 시 null). 가장 먼저 생성된 1건.
HqStoreManagerInfo = {
  email: string;
  name?: string | null;          // @nullable
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";   // HqStoreManagerInfoStatus
} | null
 
// 매장 활성 플레이리스트 (없음/soft-delete 시 null — 본사 기본 PL fallback 상태는 별도 표현).
HqStoreActivePlaylistInfo = {
  id: string;
  name: string;
} | null

// generated `packages/api-client/src/generated/schemas/updateStoreCommercialCycleRequest.ts`
UpdateStoreCommercialCycleRequest {
  commercialCycleSongs?: number | null;  // null = override 제거(HQ default 로 복귀), 1..100 = 매장 override 적용
}

// generated `packages/api-client/src/generated/schemas/updateStoreDuckingRequest.ts`
UpdateStoreDuckingRequest {
  duckEnabled?: boolean | null;       // @nullable — null=override 제거(HQ default 복귀), non-null=override 적용
  duckVolumePercent?: number | null;  // @nullable @minimum 0 @maximum 100 — null=override 제거
  duckFadeMs?: number | null;         // @nullable @minimum 0 @maximum 5000 — null=override 제거
}

// generated `packages/api-client/src/generated/schemas/updateStoreRegionRequest.ts`
UpdateStoreRegionRequest {
  region?: Region | null;  // @nullable — Region 시/도 enum 17종. 키+value=set / 키+null=clear(미지정). UpdateStoreRegionRequestRegion
}

// generated `packages/api-client/src/generated/schemas/updateHqStoreRequest.ts`
// 모든 필드는 BE 에서 `JsonNullable<String>` 으로 받는다 — PATCH 의미 D2:
//   · 키 부재         = 미변경
//   · 키 + null       = clear (단 name 은 비-nullable 컬럼이라 null 시 400)
//   · 키 + value      = set (검증 통과 시)
// orval 이 JsonNullable 의 partial 의미를 OpenAPI 로 표현하지 못해 generated 타입은 5 필드 모두
// required 로 떨어진다. FE 는 변경된 필드만 담은 `Partial<>` payload 를 generated client 에 cast
// 해 보낸다(runtime 으로만 D2 의미 보존, FE 주석 `backend.ts BackendUpdateHqStoreRequest` 참조).
UpdateHqStoreRequest {
  name: string;                // 1..50 비-blank · null clear 불가(@nullable false)
  address: string | null;      // ≤200 · null=clear
  managerName: string | null;  // ≤50 · null=clear
  managerEmail: string | null; // @Email + ≤255 · null=clear
  managerPhone: string | null; // ≤30 free-form · null=clear
}

// generated `schemas/createHqStoreRequest.ts`. 단순 nullable 5 필드 — #105 `UpdateHqStoreRequest` 와 달리
// JsonNullable 가 아니다(신규 등록이라 `clear vs unchanged` 분기 불필요, null/생략 = 미입력 동일 의미).
// `type` 필드 없음 — 본사 유형 자동 결정(D2: INDEPENDENT 가상 본사 산하 → INDEPENDENT, 그 외 → FRANCHISE).
CreateHqStoreRequest {
  name: string;                  // 1..50 비-blank · @NotBlank 필수
  address?: string | null;       // ≤200 · 선택
  managerName?: string | null;   // ≤50 · 선택
  managerEmail?: string | null;  // @Email + ≤255 · 선택
  managerPhone?: string | null;  // ≤30 free-form · 선택
}

// generated `schemas/bulkCreateHqStoreResponse.ts`·`bulkRowResult.ts`·`bulkRowResultStatus.ts`.
// 요청은 DTO 가 아니라 multipart `file`(CSV) — generated `BulkCreateHqStoresBody{ file: Blob }`.
// CSV 헤더 5컬럼 정확 일치: 매장명,주소,담당자명,담당자이메일,담당자전화 (UTF-8, BOM 제거, RFC4180).
BulkCreateHqStoreResponse {
  totalRows: number;            // 처리한 전체 데이터 행 수(헤더 제외)
  successCount: number;         // 등록 성공 행 수
  failureCount: number;         // 등록 실패 행 수
  results: BulkRowResult[];     // 행별 처리 결과(입력 순서, rowNumber asc)
}
 
BulkRowResult {
  rowNumber: number;                   // 헤더 제외 1-base 데이터 행 번호
  status: "SUCCESS" | "FAILED";        // BulkRowResultStatus — SUCCESS(등록됨)/FAILED(거부됨, 다른 행 무영향)
  storeId?: string | null;             // 등록된 매장 id(성공 시에만)
  storeName?: string | null;           // 성공=등록된 이름 / 실패=입력값(비면 null)
  errorCode?: string | null;           // 실패 사유 코드(주로 HQ_STORE_INVALID_FIELD)
  errorMessage?: string | null;        // 실패 사유 안내 문구(사용자 안전 문구)
}

// generated `schemas/hqPlaylistListResponse.ts`·`hqPlaylistListItem.ts`·`listHqPlaylistsParams.ts`
ListHqPlaylistsParams {
  q?: string;     // 이름 부분일치(대소문자 무시), 0..100
  page?: number;  // 0-base
  size?: number;  // 1..100 clamp
}
 
HqPlaylistListResponse {
  items: HqPlaylistListItem[];
  page: number;   // 0-base
  size: number;   // 1..100
  total: number;  // 필터 적용 후 전체 건수
}
 
HqPlaylistListItem {
  id: string;
  name: string;
  isDefault: boolean;         // (#058) 본사 기본 PL 여부 — read-only 배지(지정은 운영사 전용)
  libraryCount: number;       // 담긴 활성 라이브러리 수
  appliedStoreCount: number;  // 이 PL 을 활성으로 쓰는 본인 본사 매장 수
  status: PlaylistStatus;     // (#060) 파생 상태 EMPTY|UNUSED|ACTIVE|FALLBACK — read-only 상태 배지
  updatedAt: string;          // ISO-8601
}

// generated `schemas/hqPlaylistDetailResponse.ts`·`hqPlaylistLibraryItem.ts`
HqPlaylistDetailResponse {
  id: string;
  name: string;
  isDefault: boolean;         // (#058) 본사 기본 PL 여부 — read-only 배지(헤더)
  libraryCount: number;       // 담긴 활성 라이브러리 수
  appliedStoreCount: number;  // 이 PL 을 활성으로 쓰는 본인 본사 매장 수
  status: PlaylistStatus;     // (#060) 파생 상태 EMPTY|UNUSED|ACTIVE|FALLBACK — read-only 상태 배지(헤더)
  libraries: HqPlaylistLibraryItem[];  // position 순(server 정렬)
  createdAt: string;          // ISO-8601
  updatedAt: string;          // ISO-8601
}
 
HqPlaylistLibraryItem {
  libraryId: string;
  name: string;
  libraryType: string;  // "AI" · "TRUST" (그 외 타입은 원문 노출)
  musicCount: number;   // 담긴 활성 음원 수
  position: number;     // 0-base
}

// generated `schemas/hqLibraryListResponse.ts`·`hqLibraryListItem.ts`·`listHqLibrariesParams.ts`
ListHqLibrariesParams {
  q?: string;            // 이름 부분일치(대소문자 무시), 0..100
  type?: "AI" | "TRUST"; // 라이브러리 타입 필터(생략=전체)
  page?: number;         // 0-base
  size?: number;         // 1..100 clamp
}
 
HqLibraryListResponse {
  items: HqLibraryListItem[];
  page: number;   // 0-base
  size: number;   // 1..100
  total: number;  // 필터 적용 후 전체 건수
}
 
HqLibraryListItem {
  id: string;
  name: string;
  type: "AI" | "TRUST";  // 라이브러리는 단일 타입 묶음(음원 enforcement #059)
  trackCount: number;     // 소속 활성 음원 수
  playlistCount: number;  // 이 라이브러리를 사용 중인 본인 본사 PL 수(타 본사 PL 제외)
  createdAt: string;      // ISO-8601
  updatedAt: string;      // ISO-8601
}

// generated `schemas/hqLibraryDetailResponse.ts`·`hqLibraryMusicListResponse.ts`·
//           `hqLibraryMusicListItem.ts`·`listHqLibraryMusicParams.ts`·`hqLibraryDetailResponseType.ts`
HqLibraryDetailResponse {
  id: string;
  name: string;
  type: "AI" | "TRUST";  // HqLibraryDetailResponseType — 라이브러리는 단일 타입 묶음(상세 헤더 배지 한 곳)
  trackCount: number;     // 소속 활성 음원 수
  playlistCount: number;  // 이 라이브러리를 사용 중인 본인 본사 활성 PL 수(타 본사 PL 제외)
  createdAt: string;      // ISO-8601
  updatedAt: string;      // ISO-8601
}
 
ListHqLibraryMusicParams {
  page?: number;  // 0-base
  size?: number;  // 1..100 clamp (기본 20)
}
 
HqLibraryMusicListResponse {
  items: HqLibraryMusicListItem[];
  page: number;   // 0-base
  size: number;   // 1..100
  total: number;  // 라이브러리에 담긴 활성 음원 전체 건수
}
 
HqLibraryMusicListItem {  // 트랙(담긴 음원) 행 — 할당 시각 DESC
  id: string;
  title: string;
  durationSeconds: number;  // 곡 길이(초) — FE 에서 mm:ss(또는 h:mm:ss) 포맷
  createdAt: string;        // ISO-8601 (할당 시각)
  updatedAt: string;        // ISO-8601
}

// generated `schemas/createTtsAnnouncementRequest.ts`
CreateTtsAnnouncementRequest {
  title: string;  // @maxLength 255 — 목록/식별용 제목
  text: string;   // @NotBlank @maxLength 1000 — 합성할 본문
  voice: CreateTtsAnnouncementRequestVoice;  // TtsVoice 5종(SHEAN·WOOSUNG·CYRUS·AERAN·SEUNGA)
  tonePreset?: CreateTtsAnnouncementRequestTonePreset;  // TtsTonePreset 6종, @nullable, 기본 NORMAL (#063)
  tempo?: number;  // (#139) @minimum 0.5 @maximum 2 @nullable — 발화 속도 배수, 미지정 시 서버 기본 1.0
}

// generated `schemas/updateTtsAnnouncementRequest.ts`
UpdateTtsAnnouncementRequest {
  title: string;  // @maxLength 255
  text: string;   // @maxLength 1000 — 기존과 다르면 재합성된다
  voice: UpdateTtsAnnouncementRequestVoice;  // TtsVoice 5종(동일 enum)
  tonePreset?: UpdateTtsAnnouncementRequestTonePreset;  // TtsTonePreset 6종, @nullable (#063)
  tempo?: number;  // (#139) @minimum 0.5 @maximum 2 @nullable — 기존과 다르면 재합성된다
}

// generated `schemas/ttsVoiceListResponse.ts`·`ttsVoiceOption.ts`·`ttsTonePresetOption.ts`
TtsVoiceListResponse {
  voices: TtsVoiceOption[];  // 5종, voice 별 허용 톤 프리셋 매핑
}
 
TtsVoiceOption {
  voice: TtsVoiceOptionVoice;       // TtsVoice
  voiceDisplayName: string;         // voice 한글 표시명
  presets: TtsTonePresetOption[];   // 이 voice 가 지원하는 톤(항상 NORMAL 포함)
}
 
TtsTonePresetOption {
  preset: TtsTonePresetOptionPreset;  // TtsTonePreset
  presetDisplayName: string;          // 톤 한글 표시명(BE 단일 소스)
}

// generated `schemas/ttsAnnouncementDetailResponse.ts`
TtsAnnouncementDetailResponse {
  id: string;
  title: string;
  text: string;                 // 합성에 쓴 원문
  voice: TtsAnnouncementDetailResponseVoice;  // TtsVoice
  voiceDisplayName: string;     // voice 한글 표시명(BE 단일 소스)
  tonePreset: TtsAnnouncementDetailResponseTonePreset;  // TtsTonePreset (#063)
  tonePresetDisplayName: string;  // 톤 한글 표시명(BE 단일 소스, #063)
  audioUrl: string;             // Azure public blob — 직접 재생
  durationSeconds?: number | null;  // Typecast 가 줄 때만(nullable)
  createdAt: string;            // ISO-8601
  updatedAt: string;            // ISO-8601
}

// generated `schemas/ttsAnnouncementListResponse.ts`·`ttsAnnouncementListItem.ts`
TtsAnnouncementListResponse {
  items: TtsAnnouncementListItem[];
  page: number;   // 0-base
  size: number;   // 1..100 clamp
  total: number;  // 활성(soft-delete 제외) 전체 건수
}
 
TtsAnnouncementListItem {
  id: string;
  title: string;
  voice: TtsAnnouncementListItemVoice;  // TtsVoice
  voiceDisplayName: string;             // voice 한글 표시명
  tonePreset: TtsAnnouncementListItemTonePreset;  // TtsTonePreset (#063)
  tonePresetDisplayName: string;        // 톤 한글 표시명 (#063)
  durationSeconds?: number | null;      // null 가능
  createdAt: string;                    // ISO-8601
  updatedAt: string;                    // ISO-8601
  dispatchCount: number;                // (#066) 누적 송출 row 수(=중복 송출 포함). 0=미송출. **고유 매장 수 아님** — 같은 매장에 N 번 송출하면 N. 매장 그룹핑은 후속(F).
  lastDispatchedAt?: string | null;     // (#066) 가장 최근 송출 시각 ISO-8601(`MAX(announcement_dispatch.created_at)`). null=미송출.
  lastDispatchStoreCount?: number | null; // (#097) 마지막 송출 호출의 distinct 매장 수(fan-out 사이즈). null=미송출. **누적 아님** — 마지막 1회 호출만 카운트. audit_id 그룹핑(V28+) + legacy created_at fallback. UI 는 같은 셀에 `(N매장)` 보조 표기.
}

// generated `schemas/dispatchRequest.ts`·`dispatchResponse.ts`·`dispatchRequestTarget.ts`
DispatchRequest {
  target: DispatchRequestTarget;            // "ALL" | "STORES" | "REGION" (#144)
  storeIds?: (string | null)[] | null;       // STORES 일 때 필수, 모두 본인 본사 산하 (ALL/REGION 이면 무시). 크기 ≤1000 은 target 무관 적용(페이로드 가드)
  region?: Region | null;                    // (SPEC #144) REGION 일 때 필수(시/도 enum). 누락 시 400 DISPATCH_REGION_REQUIRED. ALL/STORES 면 무시. DispatchRequestRegion
  scheduledAt?: string | null;               // (SPEC #078) ISO-8601. null=즉시 송출(기존 동작·PENDING fan-out), non-null=예약(SCHEDULED row 적재 → 디스패처 전이). 과거=400 DISPATCH_SCHEDULED_AT_PAST · 1년 초과=400 DISPATCH_SCHEDULED_AT_TOO_FAR
}
 
DispatchResponse {
  dispatchedCount: number;   // 생성된 송출 row 수 (매장 0건이면 0)
  dispatchIds: string[];     // 생성된 송출 id 목록 (매장당 1개)
}

// generated `schemas/createDispatchScheduleRequest.ts`·`dispatchScheduleResponse.ts`·`*Frequency.ts`·`*Target.ts`
CreateDispatchScheduleRequest {
  announcementId: string;                    // 반복 송출할 안내방송 id (본인 본사 활성 HQ 출처)
  target: CreateDispatchScheduleRequestTarget;  // "ALL" | "STORES" | "REGION" (#144)
  storeIds?: (string | null)[] | null;       // STORES 일 때 필수(1~1000, 모두 산하). ALL/REGION 이면 무시
  region?: Region | null;                    // (#144) REGION 일 때 필수(시/도). 누락 시 400 DISPATCH_REGION_REQUIRED. ALL/STORES 면 무시. CreateDispatchScheduleRequestRegion
  frequency: CreateDispatchScheduleRequestFrequency;  // (#139) DAILY|WEEKLY|HOURLY|EVEN_HOURS|ODD_HOURS
  byWeekday?: string | null;                 // WEEKLY 필수 — 요일 CSV(MON~SUN, @maxLength 32). 그 외 무시
  startHour?: number | null;                 // (#139) 시각형 빈도 운영시간 시작 hour. @minimum 0 @maximum 23, ≤endHour. 시각형이면 필수, DAILY/WEEKLY 무시
  endHour?: number | null;                   // (#139) 시각형 빈도 운영시간 종료 hour. @minimum 0 @maximum 23, ≥startHour. 시각형이면 필수
  slotTime: string;                          // 'HH:MM' KST 5분 슬롯(분 5배수). @maxLength 5. 시각형은 분(MM)만 매시 :MM 오프셋(시 무시)
  startsOn: string;                          // 전개 시작일 (KST date, 포함)
  endsOn?: string | null;                    // 종료일(포함). null=무한. 지정 시 ≥startsOn
}
 
DispatchScheduleResponse {  // 동일 필드 + id·timezone·status·createdAt
  id: string; announcementId: string;
  target: DispatchScheduleResponseTarget; storeIds: string[];   // REGION/ALL 이면 storeIds 빈 배열
  region?: Region | null;                    // (#144) REGION 이면 시/도, ALL/STORES 면 null. DispatchScheduleResponseRegion
  frequency: DispatchScheduleResponseFrequency;  // (#139) 5종
  byWeekday?: string | null;                 // WEEKLY 정규화 CSV, 그 외 null
  startHour?: number | null;                 // (#139) 시각형이면 운영시간, DAILY/WEEKLY 면 null
  endHour?: number | null;                   // (#139) 동일
  slotTime: string; startsOn: string; endsOn?: string | null;
  timezone: string;                          // KST 고정
  status: DispatchScheduleResponseStatus;    // ACTIVE → CANCELED 단방향
  createdAt: string;
}

// generated `schemas/dispatchCalendarResponse.ts`·`dispatchCalendarEvent.ts`·`dispatchCalendarEventKind.ts`·`dispatchCalendarEventStatus.ts`
DispatchCalendarResponse {
  from: string;   // 조회 시작일(KST day, 포함) — 요청 echo
  to: string;     // 조회 종료일(KST day, 포함) — 요청 echo
  events: DispatchCalendarEvent[];   // effective time ASC → id ASC 결정적·0건이면 빈 배열
}
DispatchCalendarEvent {
  dispatchId: string;
  scheduledAt: string;        // 캘린더 배치 시각(UTC ISO). 예약=scheduled_at·즉시=created_at COALESCE 파생.
                              // FE 가 KST day 로 변환해 셀에 배치.
  storeId: string;
  storeName?: string | null;  // 본사 캘린더만 채워짐(점장은 본인 매장 고정 → null)
  announcementTitle: string;
  kind: DispatchCalendarEventKind;     // "EMERGENCY" | "HQ_ANNOUNCEMENT" | "STORE_BROADCAST"
  status: DispatchCalendarEventStatus; // "SCHEDULED" | "PENDING" | "PLAYED" | "CANCELED"
  isEmergency: boolean;
  scheduleId?: string | null;          // 반복 전개분이면 규칙 id, 1회성은 null
}

// generated `schemas/dispatchHistoryResponse.ts`·`dispatchHistoryItem.ts`·`dispatchHistoryAggregate.ts`·`dispatchHistoryItemStatus.ts`·`dispatchHistoryItemActorRole.ts`
DispatchHistoryResponse {
  items: DispatchHistoryItem[];           // 현재 페이지 송출 이력 행
  page: number;                           // 0-base
  size: number;                           // 1..100 clamp
  total: number;                          // 해당 announcement scope 의 전체 송출 row 수
  aggregate: DispatchHistoryAggregate;    // 페이지 무관 전체 카운트
}
 
DispatchHistoryItem {
  dispatchId: string;                     // 송출 id (announcement_dispatch.id)
  storeId: string;                        // 수신 매장 id
  storeName: string;                      // 수신 매장 이름 (BE 단일 소스 — store join)
  status: DispatchHistoryItemStatus;      // (#077·#078 4종) "SCHEDULED" | "PENDING" | "PLAYED" | "CANCELED"
  createdAt: string;                      // 송출 row 생성 시각 (ISO-8601, 예약 등록 시각 = SCHEDULED 의 등록 시각)
  playedAt?: string | null;               // 재생(ack) 시각 (ISO-8601). SCHEDULED/PENDING/CANCELED 동안 null
  scheduledAt?: string | null;            // (SPEC #078) 예약 송출 시각 (ISO-8601). null=즉시 송출 row · non-null=예약 송출 row(SCHEDULED 또는 디스패처 전이 후 PENDING/PLAYED/CANCELED — 시각 정보 그대로 보존). FE 가 SCHEDULED 행 "송출 시각" 셀에 노출
  // (#071) 송출 수행자 actor 정보 — `announcement_dispatch.audit_id` (V28) FK 로 `hq_audit_log` 와 LEFT JOIN 한 스냅샷.
  actorEmail?: string | null;             // (#071) 송출 수행자 이메일 스냅샷. HQ_MANAGER 면 본사 매니저 본인, OPERATOR_IMPERSONATING 면 위장 대상 본사 매니저. V28 이전 row 또는 audit 누락 시 null
  actorRole?: DispatchHistoryItemActorRole;// (#071) "HQ_MANAGER" | "OPERATOR_IMPERSONATING". V28 이전 row 는 null
  impersonatedByEmail?: string | null;    // (#071) 위장 운영자 이메일 스냅샷. OPERATOR_IMPERSONATING 일 때만 채워짐 — 직접 송출(HQ_MANAGER)·V28 이전 row 는 null
}
 
DispatchHistoryAggregate {
  total: number;                          // 전체 송출 row 수
  played: number;                         // 재생 완료(PLAYED) row 수
  pending: number;                        // 미재생(PENDING) row 수
  scheduled: number;                      // (SPEC #078) 예약 대기(SCHEDULED) row 수 — 디스패처 전이 전 row 만 카운트
  distinctStoreCount: number;             // (SPEC #075) 고유 매장 수 — COUNT(DISTINCT storeId), 매장 0건이면 0
}

// generated `schemas/hqAuditListResponse.ts`·`hqAuditItem.ts`·`hqAuditItemAction.ts`·`hqAuditItemActorRole.ts`·`hqAuditItemTargetType.ts`·`listHqAuditDispatchesParams.ts`·`listHqAuditDispatchesAction.ts`
HqAuditListResponse {
  items: HqAuditItem[];                    // 현재 페이지 본사 감사 행
  page: number;                            // 0-base
  size: number;                            // 1..100 clamp
  total: number;                           // 본사 scope 의 전체 감사 행 수
}
 
HqAuditItem {
  id: string;                              // 감사 행 id (hq_audit_log.id)
  occurredAt: string;                      // 발생 시각 (ISO-8601 UTC)
  actorEmail: string;                      // 행위자 본사 매니저 이메일 (스냅샷)
  actorRole: HqAuditItemActorRole;         // "HQ_MANAGER" | "OPERATOR_IMPERSONATING"
  impersonatedByEmail?: string | null;     // 임퍼소네이션 중인 운영자 이메일 (위장 컨텍스트에서만, 그 외 null)
  action: HqAuditItemAction;               // "HQ_ANNOUNCEMENT_DISPATCHED" (현재 1종, 후속 확장)
  targetType: HqAuditItemTargetType;       // "TTS_ANNOUNCEMENT"
  targetId?: string | null;                // 대상 id (예: 안내방송 id). null 가능
  targetLabel?: string | null;             // 대상 라벨 스냅샷(안내방송 제목). null 가능
  detail?: string | null;                  // 액션 상세 (예: "target=ALL·count=3·storeIds=[…]"). 1024자 cap
}
 
ListHqAuditDispatchesParams {              // GET /api/v1/hq/audit/dispatches query
  from?: string;                           // 기간 시작 (occurred_at 기준, ISO-8601 date-time)
  to?: string;                             // 기간 종료 (ISO-8601 date-time)
  actorAccountId?: string;                 // 수행 본사 매니저 계정 id (UUID)
  action?: ListHqAuditDispatchesAction;    // HqAuditItemAction 과 동값 (현재 1종)
  targetId?: string;                       // 대상 id (예: 안내방송 id)
  q?: string;                              // 대상 라벨·상세 부분 검색 (대소문자 무시, ≤100)
  page?: number;                           // 0-base
  size?: number;                           // 1..100 clamp
}

// generated `schemas/hqAuditActorListResponse.ts`·`hqAuditActorOption.ts`·`hqAuditActorOptionRole.ts`
HqAuditActorListResponse {
  items: HqAuditActorOption[];             // 본인 본사 audit 등장 actor 옵션 (상한 200)
}
 
HqAuditActorOption {
  accountId: string;                       // actor 계정 id (UUID — HQ_MANAGER 면 본사 매니저, OPERATOR_IMPERSONATING 이면 원본 운영자)
  email: string;                           // actor 이메일 스냅샷 (같은 actor 가 이메일을 바꿨으면 최신 audit 행 기준)
  role: HqAuditActorOptionRole;            // "HQ_MANAGER" | "OPERATOR_IMPERSONATING"
  occurrenceCount: number;                 // 해당 actor 의 audit 행 총 수 (정렬·label 보조)
}

// generated `schemas/hqCommercialListItem.ts`·`hqCommercialDetailResponse.ts` (동일 필드)
HqCommercialListItem {
  id: string;
  title: string;             // 표시명 (1~200자)
  audioUrl: string;          // Azure blob 등의 공개 오디오 URL (≤2048자)
  durationSeconds: number;   // 오디오 길이(초) — 1..3600
  isActive: boolean;         // 활성 여부 — F1 점장 player 사이클 삽입 대상 토글
  createdAt: string;         // ISO-8601
  updatedAt: string;         // ISO-8601
}

// generated `schemas/hqCommercialListResponse.ts`
HqCommercialListResponse {
  items: HqCommercialListItem[];
  page: number;   // 0-base
  size: number;   // 1..100 clamp
  total: number;  // 필터 적용 후 전체 건수(soft-delete 제외)
}

// generated `schemas/listHqCommercialsParams.ts`
ListHqCommercialsParams = {
  q?: string;          // 제목 부분일치(대소문자 무시), ≤100
  isActive?: boolean;  // true/false. 미지정 시 전체
  page?: number;       // 0-base
  size?: number;       // 1..100 clamp
};

// generated `schemas/createHqCommercialRequest.ts`
CreateHqCommercialRequest {
  title: string;            // 1~200
  audioUrl: string;         // ≤2048 (URL 형식)
  durationSeconds: number;  // 1~3600
}

// generated `schemas/updateHqCommercialRequest.ts`
UpdateHqCommercialRequest {
  title?: string | null;     // null = 미변경, non-null 이면 1~200
  isActive?: boolean | null; // null = 미변경
}

// generated `schemas/hqTicketListItem.ts`
HqTicketListItem {
  id: string;
  title: string;
  status: HqTicketListItemStatus;       // OPEN | IN_PROGRESS | RESOLVED | CLOSED
  priority: HqTicketListItemPriority;   // URGENT | HIGH | NORMAL | LOW
  commentCount: number;
  createdAt: string;                    // ISO-8601
  updatedAt: string;                    // ISO-8601
}

// generated `schemas/hqTicketListResponse.ts`
HqTicketListResponse {
  items: HqTicketListItem[];
  page: number;   // 0-base
  size: number;
  total: number;
}

// generated `schemas/listHqTicketsParams.ts`
ListHqTicketsParams {
  q?: string;                       // @maxLength 100 — 제목 부분일치(대소문자 무시)
  status?: ListHqTicketsStatus;     // OPEN | IN_PROGRESS | RESOLVED | CLOSED
  priority?: ListHqTicketsPriority; // URGENT | HIGH | NORMAL | LOW
  page?: number;                    // 0-base
  size?: number;                    // 1..100 clamp
}

// generated `schemas/hqTicketDetailResponse.ts`
HqTicketDetailResponse {
  id: string;
  title: string;
  body: string;                                  // 본문(작성 시 입력, 최대 5000자)
  status: HqTicketDetailResponseStatus;          // 동일 enum
  priority: HqTicketDetailResponsePriority;
  submitterEmail: string;                        // 본사 매니저 이메일 스냅샷(BE D6)
  createdAt: string;
  updatedAt: string;
  comments: HqTicketCommentItem[];               // 생성순 오름차순(시간순)
}

// generated `schemas/hqTicketCommentItem.ts`
HqTicketCommentItem {
  id: string;
  body: string;                                  // @maxLength 5000
  authorRole: HqTicketCommentItemAuthorRole;     // HQ_MANAGER | OPERATOR
  authorEmail: string;                           // 작성자 이메일 스냅샷
  createdAt: string;                             // ISO-8601
}

// generated `schemas/createHqTicketRequest.ts`
CreateHqTicketRequest {
  title: string;                                 // @maxLength 200 · NotBlank
  body: string;                                  // @maxLength 5000 · NotBlank
  priority?: CreateHqTicketRequestPriority;      // @nullable — 누락 시 NORMAL default (BE D1)
}

// generated `schemas/addHqTicketCommentRequest.ts`
AddHqTicketCommentRequest {
  body: string;                                  // @maxLength 5000 · NotBlank
}

// generated `schemas/hqTicketStatusChangeRequest.ts` · `hqTicketStatusChangeResponse.ts`
HqTicketStatusChangeRequest {
  status: HqTicketStatusChangeRequestStatus;     // OPEN | IN_PROGRESS | RESOLVED | CLOSED
}
HqTicketStatusChangeResponse {
  status: HqTicketStatusChangeResponseStatus;    // 변경 후 status
}

// generated `schemas/hqTicketPriorityChangeRequest.ts` · `hqTicketPriorityChangeResponse.ts`
HqTicketPriorityChangeRequest {
  priority: HqTicketPriorityChangeRequestPriority; // URGENT | HIGH | NORMAL | LOW
}
HqTicketPriorityChangeResponse {
  priority: HqTicketPriorityChangeResponsePriority; // 변경 후 priority
}

// generated `schemas/storeTicketListItem.ts`
StoreTicketListItem {
  id: string;
  title: string;
  status: StoreTicketListItemStatus;       // OPEN | IN_PROGRESS | RESOLVED | CLOSED
  category?: StoreTicketListItemCategory;   // PLAYBACK | BROADCAST | BILLING | ACCOUNT | OTHER (nullable — 공용 테이블)
  commentCount: number;
  createdAt: string;                        // ISO-8601
  updatedAt: string;
}

StoreTicketListResponse { items: StoreTicketListItem[]; page; size; total; }
 
// generated `schemas/listStoreTicketsParams.ts`, operationId `listStoreTickets`
ListStoreTicketsParams {
  q?: string;                        // 제목 부분검색 ≤100
  status?: ListStoreTicketsStatus;   // OPEN | IN_PROGRESS | RESOLVED | CLOSED
  category?: ListStoreTicketsCategory; // PLAYBACK | BROADCAST | BILLING | ACCOUNT | OTHER
  page?: number;                     // 0-base
  size?: number;                     // 1..100 clamp
}

// generated `schemas/storeTicketDetailResponse.ts`
StoreTicketDetailResponse {
  id: string;
  title: string;
  body: string;
  status: StoreTicketDetailResponseStatus;
  category?: StoreTicketDetailResponseCategory;
  createdAt: string;
  updatedAt: string;
  comments: StoreTicketCommentItem[];   // 생성순 오름차순, REPLY 만
}

// generated `schemas/storeTicketCommentItem.ts`
StoreTicketCommentItem {
  id: string;
  body: string;
  authorRole: StoreTicketCommentItemAuthorRole;   // STORE_MANAGER | OPERATOR
  createdAt: string;
}

// generated `schemas/createStoreTicketRequest.ts`
CreateStoreTicketRequest {
  title: string;                          // 1~200, NotBlank
  body: string;                           // 1~5000, NotBlank
  category: CreateStoreTicketRequestCategory;  // 필수(@NotNull) — 본사 priority? 와 달리 nullable 아님
}
 
AddStoreTicketCommentRequest { body: string; }  // 1~5000

// generated `schemas/storeSupportUnreadSignalResponse.ts`
{
  latestOperatorReplyAt?: string | null;  // 본인 매장 ticket 의 운영자 REPLY max createdAt(없으면 null)
}

// generated `schemas/pendingAnnouncementsResponse.ts`·`pendingAnnouncementItem.ts`
PendingAnnouncementsResponse {
  items: PendingAnnouncementItem[];   // 본인 매장의 미재생(PENDING) 송출 — created_at ASC
  revokedDispatchIds: string[];       // (SPEC #077 확장) 본사 원격 즉시중단(revoke) 신호 — 오늘 KST 윈도우 본인 매장에서 본사가 revoke 한 dispatchId 목록. revoke 시 CANCELED 전이로 items 에선 자동 제외되므로 별도 신호로 노출. player 가 재생 중 멘트의 dispatchId 가 이 목록에 있으면 즉시 중단(best-effort, ack 안 함)·재선출 차단.
}
 
PendingAnnouncementItem {
  dispatchId: string;                 // 송출 id (ack 시 사용)
  announcementId: string;             // 안내방송 id
  title: string;                      // 안내방송 제목
  audioUrl: string;                   // 합성 오디오 재생 URL (Azure public blob)
  durationSeconds?: number | null;    // 오디오 길이(초), null 가능
  isEmergency: boolean;               // (SPEC #082) 긴급방송 여부 — 점장 즉시방송 옵션. 본 슬라이스는 노출만(player 인터럽트 F1·audit 누적 F2 후속).
}

// generated `schemas/broadcastPreviewRequest.ts`·`broadcastPreviewResponse.ts`·`broadcastSendRequest.ts`·`broadcastSendResponse.ts`·`broadcastRecordingResponse.ts`·`recordStoreBroadcastParams.ts`
BroadcastPreviewRequest {                  // POST /api/v1/store/broadcasts/preview body (TTS)
  text: string;                            // 방송 텍스트 (@minLength 1 @maxLength 200)
  voice: BroadcastPreviewRequestVoice;     // TtsVoice 5종(SHEAN·WOOSUNG·CYRUS·AERAN·SEUNGA), 톤 NORMAL 고정
  isEmergency?: boolean | null;            // (SPEC #082) 긴급방송 여부. null/생략=일반 · true=긴급. FE 는 true 만 명시 전송.
}
 
BroadcastPreviewResponse {                 // TTS preview 201
  announcementId: string;                  // 생성된 draft 안내방송 id (send 시 사용)
  audioUrl: string;                        // 합성 오디오 미리듣기 URL (Azure public blob)
  durationSeconds?: number | null;         // 오디오 길이(초), Typecast 제공 시만
  isEmergency: boolean;                    // (SPEC #082) preview 단계에서 확정된 긴급 여부(null=false 정규화). send 단계에서 재확정 가능.
}
 
// POST /api/v1/store/broadcasts/recording (녹음): multipart file=Blob + query (durationSeconds, isEmergency?)
// RecordStoreBroadcastBody{ file: Blob }
// RecordStoreBroadcastParams{ durationSeconds: number; isEmergency?: boolean }  // (SPEC #082) query param — null/생략=false
BroadcastRecordingResponse {               // 녹음 업로드 201
  announcementId: string;                  // 생성된 draft 안내방송 id (send 시 사용 — preview 와 동형)
  audioUrl: string;                        // 업로드된 녹음 미리듣기 URL (Azure public blob)
  durationSeconds?: number | null;         // 녹음 길이(초), 클라 측정값을 서버가 1~30 검증
  isEmergency: boolean;                    // (SPEC #082) multipart query 의 isEmergency 를 반영(null=false). send 단계에서 재확정 가능.
}
 
BroadcastSendRequest {                     // POST /api/v1/store/broadcasts/{announcementId}/send body (SPEC #082·#083)
  isEmergency?: boolean | null;            // (SPEC #082) 송출 마지막 단계의 isEmergency 확정. null/생략 시 preview 단계 값 유지. true=긴급. FE 는 일반이면 생략, 긴급이면 true 명시 전송.
  scheduledAt?: string | null;             // (SPEC #083) ISO-8601 nullable. null/생략=즉시 송출(기존 동작·status=PENDING). non-null=예약 송출(status=SCHEDULED, scheduled_at 적재 → 본사 #078 `HqDispatchScheduler` 1분 cron 이 도래 시 PENDING 자동 전이 → 점장 player polling 자동 픽업, 코드 변경 0). 과거(`<= now`) → 400 BROADCAST_SCHEDULED_AT_PAST · 1년 초과 → 400 BROADCAST_SCHEDULED_AT_TOO_FAR. isEmergency 와 자유 조합 가능(긴급 예약 = 정당한 use case). FE 는 일반 즉시 송출이면 `{}` 빈 body, 예약이면 `{ scheduledAt }`, 긴급 예약이면 `{ isEmergency: true, scheduledAt }`.
}
 
BroadcastSendResponse {                    // POST /api/v1/store/broadcasts/{announcementId}/send 201 (공유)
  dispatchId: string;                      // 생성된 송출 id
}

// generated `schemas/broadcastTemplateResponse.ts`·`broadcastTemplateListResponse.ts`·`createBroadcastTemplateRequest.ts`·`updateBroadcastTemplateRequest.ts`
BroadcastTemplateResponse {                // 본인 매장 활성 템플릿 행 (updated_at DESC)
  id: string;                              // 템플릿 id
  name: string;                            // 표시 이름
  text: string;                            // 방송할 텍스트
  voice: BroadcastTemplateResponseVoice;   // TtsVoice 5종(SHEAN·WOOSUNG·CYRUS·AERAN·SEUNGA)
  createdAt: string;                       // 생성 시각 (ISO-8601)
  updatedAt: string;                       // 수정 시각 (ISO-8601)
}
 
BroadcastTemplateListResponse {            // GET /api/v1/store/broadcast-templates 200
  items: BroadcastTemplateResponse[];      // updated_at DESC
  total: number;                           // 활성 템플릿 건수 (매장당 최대 20)
}
 
CreateBroadcastTemplateRequest {           // POST body (201)
  name: string;                            // @minLength 1 @maxLength 60
  text: string;                            // @minLength 1 @maxLength 200 (즉시방송 text 와 동일 제약)
  voice: CreateBroadcastTemplateRequestVoice;
}
 
UpdateBroadcastTemplateRequest {           // PUT /{id} body (200) — Create 와 동형
  name: string;                            // @minLength 1 @maxLength 60
  text: string;                            // @minLength 1 @maxLength 200
  voice: UpdateBroadcastTemplateRequestVoice;
}

// generated `schemas/storeScheduledBroadcastItem.ts` · `storeScheduledBroadcastListResponse.ts`
StoreScheduledBroadcastItem {              // GET /api/v1/store/scheduled-broadcasts 200 item
  dispatchId: string;                      // SCHEDULED dispatch row id (UUID)
  announcementTitle: string;               // announcement 와 JOIN — 표 첫 컬럼
  audioUrl: string;                        // announcement.audio_url 스냅샷 (Azure public blob, 미리듣기 후속)
  scheduledAt: string;                     // ISO-8601 UTC — 도래 시 디스패처가 PENDING 전이
  isEmergency: boolean;                    // (SPEC #082) 긴급 예약 여부 — 표에 "긴급" pill 분기
  createdAt: string;                       // ISO-8601 UTC — 예약 row 등록 시각
}
 
StoreScheduledBroadcastListResponse {      // GET 200
  items: StoreScheduledBroadcastItem[];    // scheduled_at ASC, 현재 페이지 size 만큼
  page: number;                            // (#102) 0-base 현재 페이지
  size: number;                            // (#102) 페이지 크기 (1..50 clamp, default 20)
  total: number;                           // (#102) 페이지 무관 본인 매장 SCHEDULED 전체 카운트
}

// generated `schemas/operatorListResponse.ts` · `operatorListItem.ts` · `listOperatorsParams.ts`
 
// #043 — 검색·상태필터·페이지네이션 query 파라미터(전부 optional).
ListOperatorsParams {
  q?: string;                                         // email·name 부분일치(대소문자 무시), max 100
  status?: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";       // ListOperatorsStatus — 미지정 시 전체(WITHDRAWN 포함)
  page?: number;                                       // 0-base, default 0
  size?: number;                                       // default 20, 1..100 clamp
}
 
// #043 — envelope 전환(`{items}` → `{items,page,size,total}`).
OperatorListResponse {
  items: OperatorListItem[];                           // 현재 페이지(createdAt asc, id asc)
  page: number;                                        // 0-base 페이지 번호
  size: number;                                        // 페이지 크기(1..100)
  total: number;                                       // 필터 적용 후 전체 건수
}
 
OperatorListItem {
  id: string;
  email: string;
  name?: string | null;                              // 없으면 null → FE '—'
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";       // OperatorListItemStatus
  passwordMustChange: boolean;                        // 임시 비번 상태(첫 로그인 변경 강제)
  lastLoginAt?: string | null;                        // ISO, 없으면 null
  createdAt: string;                                  // ISO
  isSelf: boolean;                                    // 현재 로그인 운영자 본인 여부(FE 자기 행 액션 비활성)
}

OperatorIssueRequest  { email: string; name: string; tempPassword: string; } // tempPassword OpenAPI minLength 8/maxLength 100, email·name max 255 (런타임 @Email·@NotBlank)
OperatorIssueResponse { id: string; }                                          // 201, passwordMustChange=true

OperatorResetPasswordRequest { tempPassword: string; } // OpenAPI minLength 8, maxLength 100
OperatorSuspendRequest       { reason: string; }       // OpenAPI maxLength 255 (런타임 @NotBlank)
 
OperatorAccountResponse {
  id: string;
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";        // 전이 후 상태
  passwordMustChange: boolean;                          // 비번 재설정 시 true
}

{
  totalHqs: number;            // Hq count
  hqsByStatus: HqStatusCounts; // group by status
  newHqs7d: number;            // Hq createdAt ≥ now−7d
  totalStores: number;         // Store count
  activeImpersonations: number; // active(미revoke·미만료) impersonated RefreshToken 수
  // — #035 추가 —
  storesByStatus: StoreStatusCounts; // Store.status group by (합 = totalStores)
  hqsByType: HqTypeCounts;           // Hq.type group by
  accounts: AccountStatsCounts;      // OperatorAccount role×status 단일 group by(최소셋)
  tickets: TicketStatsCounts;        // Ticket.status group by + 미배정·긴급 OPEN 보조 count
  hqSignups30d: DailyCount[];        // 최근 30일 본사 가입 추이(가입 있는 날만 — FE 가 0 채움)
  // — #126 추가 —
  dispatch: DispatchStatsCounts;     // AnnouncementDispatch.status group by + 최근 7일 송출 건수
  dispatchTrend30d: DailyCount[];    // 최근 30일 송출 추이(송출 있는 날만 — FE 가 0 채움)
  storeAuditActivity7d: number;      // 최근 7일 매장 audit(store_audit_log) 활동 수
}

{
  active: number;
  onboarding: number;
  unpaid: number;
  suspended: number;
}

{
  active: number;     // ACTIVE 매장 수
  suspended: number;  // SUSPENDED 매장 수
  inactive: number;   // INACTIVE 매장 수
}

{
  franchise: number;    // FRANCHISE 본사 수
  independent: number;  // INDEPENDENT(가상 본사) 수
}

{
  operatorsActive: number;     // ACTIVE 운영자 수
  operatorsSuspended: number;  // SUSPENDED 운영자 수
  hqManagersActive: number;    // ACTIVE HQ매니저 수
  storeManagersActive: number; // ACTIVE 점장 수
}

{
  open: number;
  inProgress: number;
  resolved: number;
  closed: number;
  unassignedOpen: number; // 미배정(assignee NULL) OPEN 수
  urgentOpen: number;     // 긴급(URGENT) OPEN 수
}

{
  pending: number;     // PENDING(미재생) 송출 수
  played: number;      // PLAYED(재생 완료) 송출 수
  scheduled: number;   // SCHEDULED(예약 대기) 송출 수
  canceled: number;    // CANCELED(본사 취소) 송출 수
  last7dCount: number; // 최근 7일 송출 건수(전역 dispatch row 수)
}

{
  date: string;   // 일자 ISO date (YYYY-MM-DD)
  count: number;  // 해당 일자 건수
}

TtsSmokeTestResponse {
  ok: boolean;              // 항상 true (성공 응답에서만)
  voice: string;           // 진단에 쓴 voice enum name (SHEAN)
  durationSeconds?: number | null; // 합성 오디오 길이(초). 미제공 시 null
  audioByteSize: number;   // 합성 오디오 bytes 크기
  elapsedMs: number;       // smoke-test 호출 소요(ms)
}

{
  id: string;            // 세션 식별자
  operatorEmail: string; // 진입한 운영자 email (운영자 표시명은 BE v1 미제공)
  hqName: string;        // 진입 대상 본사명 (진입 시점 스냅샷)
  startedAt: string;     // ISO — exchange(실제 진입) 시각
  endedAt?: string;      // ISO — 명시적 종료(EXITED) 시각. 미종료/만료면 omit
  durationSec: number;   // 파생 — 종료 시각(없으면 now) − startedAt (초)
  status: ImpersonationAuditItemStatus; // 파생 — 아래 enum
}

"ACTIVE" | "COMPLETED" | "EXPIRED"

{
  items: ImpersonationAuditItem[];
  page: number;   // 0-based
  size: number;
  total: number;
}

{
  from?: string;       // ISO — startedAt ≥ from
  to?: string;         // ISO — startedAt ≤ to
  operatorId?: string;
  hqId?: string;
  status?: "ACTIVE" | "COMPLETED" | "EXPIRED";
  page?: number;       // 0-based
  size?: number;
}

{
  id: string;          // 감사 row 식별자
  occurredAt: string;  // ISO — 액션 발생 시각
  actorEmail: string;  // 액션을 수행한 운영자 email (스냅샷)
  action: OperatorAuditItemAction;         // 아래 enum
  targetType: OperatorAuditItemTargetType; // 아래 enum
  targetId?: string;     // 대상 식별자(UUID). 일부 액션은 omit
  targetLabel?: string;  // 대상 표시 스냅샷(hqName·storeName·약관 version 등)
  detail?: string;       // 부가 상세(HQ_SUSPENDED 정지 사유·게시 version 등)
}

"HQ_SUSPENDED" | "HQ_REACTIVATED" | "STORE_MANAGER_ISSUED"
  | "STORE_MANAGER_PASSWORD_RESET" | "STORE_MANAGER_SUSPENDED"
  | "STORE_MANAGER_REACTIVATED" | "STORE_MANAGER_REVOKED"
  | "OPERATOR_ISSUED" | "OPERATOR_PASSWORD_RESET" | "OPERATOR_SUSPENDED"
  | "OPERATOR_REACTIVATED" | "OPERATOR_REVOKED"
  | "TERMS_PUBLISHED" | "PRIVACY_POLICY_PUBLISHED" | "HQ_ONBOARDED"

"HQ" | "STORE" | "OPERATOR" | "TERMS" | "PRIVACY_POLICY"

{
  items: OperatorAuditItem[];
  page: number;   // 0-based
  size: number;
  total: number;
}

{
  from?: string;            // ISO — occurredAt ≥ from
  to?: string;              // ISO — occurredAt ≤ to
  action?: OperatorAuditItemAction;
  actorOperatorId?: string;
  targetType?: OperatorAuditItemTargetType;
  q?: string;               // #034 — targetLabel+detail 부분일치(ILIKE, 대소문자 무시), max 100
  page?: number;            // 0-based
  size?: number;
}

{
  id: string;            // audit row 식별자
  hqId: string;          // 본사 id (audit 행이 속한 본사)
  hqName: string;        // 본사명 (hq JOIN 결과 — 현재값 스냅샷)
  occurredAt: string;    // ISO — 액션 발생 시각
  actorEmail: string;    // 본사 매니저 이메일 (스냅샷)
  actorRole: OperatorHqAuditItemActorRole;          // "HQ_MANAGER" | "OPERATOR_IMPERSONATING"
  impersonatedByEmail?: string | null;              // 위장 컨텍스트에서만, 그 외 null
  action: OperatorHqAuditItemAction;                // 아래 enum (5종)
  targetType: OperatorHqAuditItemTargetType;        // 아래 enum
  targetId?: string | null;       // 대상 식별자(없으면 null)
  targetLabel?: string | null;    // 대상 라벨 스냅샷(없으면 null)
  detail?: string | null;         // 액션 상세(없으면 null)
}

"HQ_ANNOUNCEMENT_DISPATCHED" | "HQ_ANNOUNCEMENT_CREATED"
  | "HQ_ANNOUNCEMENT_UPDATED" | "HQ_ANNOUNCEMENT_DELETED"
  | "HQ_ANNOUNCEMENT_DISPATCH_CANCELED"

"TTS_ANNOUNCEMENT"

"HQ_MANAGER" | "OPERATOR_IMPERSONATING"

{
  items: OperatorHqAuditItem[];
  page: number;   // 0-based
  size: number;
  total: number;
}

{
  from?: string;          // ISO — occurredAt ≥ from
  to?: string;            // ISO — occurredAt ≤ to
  hqId?: string;          // 본사 id 필터(null=전체 본사 통합)
  actorAccountId?: string;
  action?: OperatorHqAuditItemAction;
  targetType?: OperatorHqAuditItemTargetType;
  q?: string;             // targetLabel+detail 부분일치(ILIKE), max 100
  page?: number;          // 0-based
  size?: number;
}

{
  id: string;
  storeId: string;                              // store JOIN 키(audit 행이 속한 매장)
  storeName: string;                            // 매장명(현재값, store JOIN 결과)
  occurredAt: string;                           // ISO-8601
  actorEmail: string;                           // 행위자 점장 이메일(스냅샷)
  actorRole: StoreAuditListItemActorRole;       // "STORE_MANAGER" | "OPERATOR_IMPERSONATING"
  impersonatedByEmail?: string | null;          // 위장 컨텍스트에서만(그 외 null)
  action: StoreAuditListItemAction;             // 아래 enum (7종)
  targetType: StoreAuditListItemTargetType;     // 아래 enum
  targetId?: string | null;
  targetLabel?: string | null;
  detail?: string | null;
}

"STORE_TICKET_CREATED"            // 티켓 생성
"STORE_TICKET_COMMENT_ADDED"      // 티켓 댓글
"STORE_TICKET_CLOSED"             // 티켓 확인 종료 (#121)
"STORE_PROFILE_UPDATED"           // 프로필 수정
"STORE_PASSWORD_CHANGED"          // 비밀번호 변경
"STORE_DISPATCH_CANCELED"         // 송출 취소
"STORE_ACTIVE_PLAYLIST_CHANGED"   // 활성 PL 변경 (#129 — 선택·해제)

"DISPATCH"          // 송출
"STORE_MANAGER"     // 점장 계정
"SUPPORT_TICKET"    // CS 티켓
"PLAYLIST"          // 플레이리스트 (#129 — 활성 PL 변경 대상)

"STORE_MANAGER"           // 점장 본인 직접 액션
"OPERATOR_IMPERSONATING"  // 운영자가 점장 모드로 위장

{
  items: StoreAuditListItem[];
  page: number;   // 0-based
  size: number;
  total: number;
}

{
  from?: string;          // ISO — occurredAt ≥ from
  to?: string;            // ISO — occurredAt ≤ to
  storeId?: string;       // 매장 id 필터(null=전체 매장 통합)
  actorId?: string;       // 행위자(점장/임퍼소네이션 운영자) 계정 id
  action?: ListStoreAuditAction;
  q?: string;             // targetLabel+detail 부분일치(ILIKE), max 100
  page?: number;          // 0-based
  size?: number;
}