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

{ email: string; password: string }

{
  accessToken: string;
  accessExpiresInSeconds: number;  // access 토큰 수명(초, default 1800 = 30min)
  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) — SPEC #147: 약관 동의가 발급에서 이 단계로 이전
SetupVerifyRequest    { token: string }
SetupVerifyResponse   { email: string; role: "OPERATOR"|"HQ_MANAGER"|"STORE_MANAGER"; expiresAt: string;
                        activeTermsVersion?: string|null; activePrivacyPolicyVersion?: string|null }  // null = OPERATOR·미게시(동의 단계 생략)
SetupCompleteRequest  { token: string; newPassword: string;
                        termsVersion?: string|null; privacyPolicyVersion?: string|null;  // @Size 32 · 활성판과 일치
                        signerName?: string|null }   // @Size 255 · 생략 시 계정명. → 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

type EmailTemplateListItemType =
  "ACCOUNT_SETUP" | "PASSWORD_RESET" | "EMAIL_CHANGE_VERIFY" | "EMAIL_CHANGE_NOTICE"
 
// 목록·메타 (listEmailTemplates → EmailTemplateListItem[])
EmailTemplateListItem {
  type: EmailTemplateListItemType
  label: string          // 한글 라벨
  subject: string        // 현재 발송 제목(실 발송과 동일)
  placeholders: string[] // 이 종류가 렌더에 쓰는 변수명
}
 
// 미리보기 (previewEmailTemplate(type))
EmailTemplatePreviewResponse {
  subject: string
  html: string  // 샘플 데이터로 렌더한 이메일-세이프 HTML 단일 문서
                // — FE 가 iframe srcDoc + .force-dark 토글로 라이트/다크
}
 
// 테스트 발송 (testSendEmailTemplate(type))
EmailTemplateTestSendRequest  { to: string }  // ≤254, email 형식
EmailTemplateTestSendResponse {
  delivered: boolean        // 실제 발송 성공. 미설정·벤더 실패 시 false
  emailConfigured: boolean  // Azure 메일 인프라 설정 여부. false → '메일 미설정' 안내
}

{ 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
  };
  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/hqManager{ResetPasswordRequest,SuspendRequest,AccountResponse}.ts`
HqManagerResetPasswordRequest { tempPassword: string; }   // OpenAPI minLength 8, maxLength 100
HqManagerSuspendRequest       { reason: string; }         // OpenAPI maxLength 255 (backend 런타임 @NotBlank)
 
HqManagerAccountResponse {
  id: string;                                     // 본사 관리자 계정 id
  status: "ACTIVE" | "SUSPENDED" | "WITHDRAWN";   // 전이 후 계정 상태
  passwordMustChange: boolean;                    // 비번 재설정 시 true
}

// 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 "—")
}

// 독립 매장 — POST /api/v1/admin/stores/independent
StoreOnboardingRequest {
  store: {
    name: string;
    address?: string;
    managerName?: string;
    managerEmail?: string;
    managerPhone?: string;
    plan: "AI" | "TRUST";
    billingAnchorDay: number;
  };
}
 
// HQ 소속 매장 — POST /api/v1/admin/hq/{hqId}/stores (plan·billingAnchorDay 는 HQ 상속)
HqAffiliatedStoreOnboardingRequest {
  store: {
    name: string;
    address?: string;
    managerName?: string;
    managerEmail?: string;
    managerPhone?: string;
    storeType: "DIRECT" | "FRANCHISE";
  };
}

// generated `schemas/storeOnboardingResponse.ts`
{
  storeId: string;
  // SPEC #184 D1/D2 — 매장 생성 트랜잭션에 점장 계정 생성이 편입됐다.
  managerAccountId?: string | null;   // 함께 생성된 STORE_MANAGER 계정 id. "점장 미정"이면 null
  managerAccountCreated: boolean;     // 의도적 파생 필드(= managerAccountId != null). FE 분기 가독성
  setupEmailSent?: boolean | null;    // 계정 미발급이면 null · 발송 성공 true · **발송 실패 false**
}

// 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;      // 활성 PL 을 적용한 시각 (미적용 시 null, ISO-8601) — 전용 컬럼(V52)
}

// generated `packages/api-client/src/generated/schemas/storeScheduleResponse.ts`
StoreScheduleResponse {
  playlistId?: string | null;             // 적용 대상 PL id (활성 PL 없으면 null)
  playlistName?: string | null;            // 적용 대상 PL 이름(표시용, 활성 PL 없으면 null)
  isOverride: boolean;                     // true=매장 맞춤(override) · false=본사 기본 표시
  entries: StoreScheduleEntry[];           // 시간표 구간(startMinute 오름차순, 비면 전체 셔플)
  availableLibraries: ScheduleLibraryOption[]; // 편집 팔레트(활성 PL 멤버, position 순)
}
 
StoreScheduleEntry {
  startMinute: number;         // 구간 시작(하루 중 분, KST, 30분 배수)
  endMinute: number;           // 구간 종료(반열림 [start,end), 30분 배수)
  libraryId: string;           // 재생 라이브러리 id
  libraryName?: string | null; // 표시용 이름(없으면 null — stale entry 는 null)
}
 
ScheduleLibraryOption {
  id: string;    // 라이브러리 id
  name: string;  // 표시용 이름
}
 
// generated `schemas/getStoreScheduleParams.ts`·`customizeStoreScheduleParams.ts`
// ·`setStoreScheduleParams.ts`·`deleteStoreScheduleParams.ts` — 4종 동일 shape (SPEC #178)
GetStoreScheduleParams {
  deviceId?: string;  // 이 요청을 보내는 기기 id. 주면 큐와 **동일한 3단 해석**(기기 지정 PL → 매장 활성 PL → 본사 기본 PL, 공용 `StorePlaylistResolver`)으로 편집 대상 PL 을 정한다. 생략하면 종전 2단(매장 활성 → 본사 기본) — 기기 지정 PL 로 재생 중인 PC 에서는 저장이 200 이어도 **음악이 안 바뀌는 조용한 no-op**. 타 매장·회수된 기기 id 는 400 이 아니라 조용한 폴백.
}

// generated `packages/api-client/src/generated/schemas/setStoreScheduleRequest.ts`
SetStoreScheduleRequest {
  entries: ScheduleEntryRequest[]; // 전체 교체(1~48개, @minItems 1 · @maxItems 48)
}
 
ScheduleEntryRequest {
  startMinute: number; // 0~1410, 30분 배수 (KST)
  endMinute: number;   // 30~1440, 30분 배수, start<end, 반열림 [start,end)
  libraryId: string;   // 해당 PL 의 멤버여야 함
}

// generated `packages/api-client/src/generated/schemas/playlistScheduleResponse.ts`
PlaylistScheduleResponse {
  playlistId: string;              // 대상 PL id
  entries: PlaylistScheduleEntry[]; // 시간표 구간(startMinute 오름차순, 비면 전체 셔플)
}
 
PlaylistScheduleEntry {
  startMinute: number;         // 구간 시작(하루 중 분, KST, 30분 배수)
  endMinute: number;           // 구간 종료(반열림 [start,end), 30분 배수)
  libraryId: string;           // 재생 라이브러리 id
  libraryName?: string | null; // 표시용 이름(없으면 null — stale entry 는 null)
}

// generated `packages/api-client/src/generated/schemas/setPlaylistScheduleRequest.ts`
SetPlaylistScheduleRequest {
  entries: ScheduleEntryRequest[]; // 전체 교체(@minItems 0 · @maxItems 48)
}
// ScheduleEntryRequest 는 매장 시간표와 공유(위 참조).

// generated `schemas/registerStoreDeviceRequest.ts`·`storeDeviceResponse.ts`·`storeDeviceListResponse.ts`
RegisterStoreDeviceRequest {
  deviceKey: string;              // 클라 발급 기기 식별자(UUID 권장, @maxLength 64 · non-blank). 같은 값 재호출 = 멱등
  label?: string | null;          // 기기 이름(@maxLength 50). 생략하면 서버가 "기기 N" 으로 채움
}
 
StoreDeviceResponse {
  id: string;                     // 서버 발급 기기 id — 이후 요청의 deviceId
  label: string;                  // 기기 이름
  lastSeenAt: string;             // 마지막 신호 시각(등록·재생 보고 시 갱신, ISO-8601)
  createdAt: string;              // 등록 시각(ISO-8601)
}
 
StoreDeviceListResponse {
  items: StoreDeviceResponse[];   // 등록 순(created_at), 회수된 기기 제외. 상한 4대라 페이지네이션 없음
}

// generated `schemas/renameStoreDeviceRequest.ts`
RenameStoreDeviceRequest {
  label: string;                  // 새 기기 이름(1~50자 · non-blank)
}

// generated `schemas/storeDevicePlaylistResponse.ts`·`setStoreDevicePlaylistRequest.ts`
StoreDevicePlaylistResponse {
  deviceId: string;               // 기기 id
  playlistId?: string | null;     // 지정된 PL id. null = 지정 없음 → 매장 기본(매장 활성 PL → 본사 기본 PL)
  appliedAt?: string | null;      // 지정 시각(지정 이력이 없으면 null)
}
 
SetStoreDevicePlaylistRequest {
  playlistId?: string | null;     // 이 기기가 재생할 PL. null = 지정 해제(매장 기본으로 복귀)
}

// 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·MISSED) distinct 매장 수
}

// generated `packages/api-client/src/generated/schemas/hqUndeliveredStoreListResponse.ts`
{
  items: HqUndeliveredStoreItem[];  // 본사 송출 미도달(PENDING·MISSED) distinct 매장(매장명 오름차순)
  total: number;                    // count endpoint 값과 정합
}
 
// generated `packages/api-client/src/generated/schemas/hqUndeliveredStoreItem.ts`
interface HqUndeliveredStoreItem {
  storeId: string;    // 매장 상세 라우팅용(/admin/stores/{storeId})
  storeName: string;  // 매장명
}

// generated `packages/api-client/src/generated/schemas/hqPlaybackStatusResponse.ts`
{
  playingCount: number;   // 지금 재생 중(PLAYING) 매장 수
  silentCount: number;    // 무음(SILENT) 매장 수
  offlineCount: number;   // 신호 끊김(OFFLINE, 서버 파생) 매장 수
  total: number;          // 산하 미폐점 매장 전체 수. ⚠️ PAUSED 는 세 카운트 밖 → playing+silent+offline != total 가능(합계로 쓰지 말 것)
  items: HqPlaybackStatusStoreItem[];  // 매장별 상태(매장명 오름차순)
}
 
// generated `packages/api-client/src/generated/schemas/hqPlaybackStatusStoreItem.ts`
interface HqPlaybackStatusStoreItem {
  storeId: string;               // 매장 상세 라우팅용(/admin/stores/{storeId})
  storeName: string;             // 매장명
  state: HqPlaybackStatusStoreItemState;  // PLAYING·PAUSED·SILENT·OFFLINE(OFFLINE 만 서버 파생)
  lastSeenAt?: string | null;    // 마지막 heartbeat 시각. 한 번도 보고 안 한 매장은 null
  currentMusicId?: string | null;    // 현재 재생 곡 id. OFFLINE·무음이면 null
  currentMusicTitle?: string | null; // 현재 재생 곡 제목. OFFLINE·무음·삭제 곡이면 null
}

// generated `packages/api-client/src/generated/schemas/hqPlaybackSummaryResponse.ts`
interface HqPlaybackSummaryResponse {
  bucket: "DAY" | "WEEK" | "MONTH";  // series 추이 버킷 단위(total·stores 는 버킷 무관 기간 전체 합)
  from: string;                       // 조회 시작일(KST, 포함, YYYY-MM-DD)
  to: string;                         // 조회 종료일(KST, 포함)
  total: HqPlaybackSummaryTotalDto;   // 기간 전사 합
  series: HqPlaybackSummarySeriesItem[];  // 전사 버킷별 추이(bucketStart asc, 차트용)
  stores: HqPlaybackSummaryStoreItem[];   // 매장별 기간 합(playedMsTotal desc, 테이블용·폐점 포함)
}
 
// hqPlaybackSummaryTotalDto.ts — 신탁/비신탁 분리
interface HqPlaybackSummaryTotalDto {
  playedMsTotal: number;   // 총 재생시간(ms) — 전 매장·전 기간
  playedMsTrust: number;   // 신탁 곡 재생시간(ms)
  trackCount: number;      // 총 재생 곡수
  trackCountTrust: number; // 신탁 곡 재생 곡수
}
 
// hqPlaybackSummarySeriesItem.ts — 차트용(trackCountTrust 없음)
interface HqPlaybackSummarySeriesItem {
  bucketStart: string;     // 버킷 시작 일자(KST). DAY=당일·WEEK=주 시작(월)·MONTH=월 초
  playedMsTotal: number;
  playedMsTrust: number;
  trackCount: number;
}
 
// hqPlaybackSummaryStoreItem.ts — 테이블용
interface HqPlaybackSummaryStoreItem {
  storeId: string;         // 매장 상세 라우팅용(/admin/stores/{storeId})
  storeName: string;       // 매장명(폐점 매장도 표기)
  playedMsTotal: number;
  playedMsTrust: number;
  trackCount: number;
  trackCountTrust: number;
}

// generated `packages/api-client/src/generated/schemas/playbackLogItemDto.ts`
interface PlaybackLogItemDto {
  playedAt: string;        // 재생 시작 시각(started_at, ISO-8601)
  hqId: string;            // 본사 id
  hqName: string;          // 본사명
  storeId: string;         // 매장 id
  storeName: string;       // 매장명(폐점 매장도 표기)
  musicId: string;         // 곡 id
  musicTitle: string;      // 곡명(삭제된 곡도 표기)
  musicSource: "AI" | "TRUST";  // 음원 타입(업로드 시 지정·불변)
  isTrust: boolean;        // 신탁 곡 여부(= musicSource == TRUST)
  playedMs: number;        // 재생 시간(밀리초)
}
 
// generated `packages/api-client/src/generated/schemas/playbackLogListResponse.ts`
interface PlaybackLogListResponse {
  items: PlaybackLogItemDto[];  // 재생 로그 행 목록(started_at 내림차순)
  page: number;                 // 현재 페이지 번호(0-base)
  size: number;                 // 페이지 크기
  total: number;                // 필터 매칭 전체 행 수
}

// 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;         // 등록 실패 행 수
  // SPEC #184 — 점장 계정 발급 결과 합계.
  managerAccountCreatedCount: number;  // 계정까지 함께 발급된 행 수. successCount 와의 차이 = "점장 미정" 매장 수
  setupEmailFailedCount: number;       // 계정은 생겼지만 setup 메일 발송에 실패한 행 수(재발송 필요)
  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 · 이메일 중복은 DUPLICATE_EMAIL)
  errorMessage?: string | null;        // 실패 사유 안내 문구(사용자 안전 문구)
  // SPEC #184 — 행별 점장 계정 발급 결과.
  managerAccountCreated: boolean;      // 의도적 파생 필드(= setupEmailSent != null). 실패 행은 항상 false
  setupEmailSent?: boolean | null;     // 계정 미발급 행은 null · 발송 성공 true · **발송 실패 false**
}

// generated `schemas/createHqStoreResponse.ts`·`hqStoreManagerIssueResult.ts`
// ⚠️ SPEC #184 breaking — 이전에는 201 body 가 flat `HqStoreDetailResponse` 였다.
CreateHqStoreResponse {
  store: HqStoreDetailResponse;                 // 생성된 매장 상세(read-back)
  managerAccount?: HqStoreManagerIssueResult;   // 계정을 함께 발급했을 때만. "점장 미정"이면 null
}
 
HqStoreManagerIssueResult {
  managerAccountId: string;        // 발급된 점장 계정 id
  email: string;                   // 발급된 로그인 ID(정규화된 이메일)
  setupEmailSent?: boolean | null; // 발송 성공 true · **발송 실패 false**(계정 진입 경로 없음 → 재발송 필요)
}

// generated `schemas/issueHqStoreManagerRequest.ts`·`hqStoreManagerIssueResponse.ts`
IssueHqStoreManagerRequest {
  name?: string | null;  // 점장 이름 · ≤50 · 선택
  email: string;         // 점장 로그인 ID · @Email + ≤255 · **필수**
  // ⚠️ tempPassword 필드가 **없다** — 임시 비밀번호는 서버 생성이고 응답에도 노출하지 않는다(D6).
  //    계정 설정(setup) 메일이 유일한 진입 경로다.
}
 
HqStoreManagerIssueResponse {
  storeId: string;
  managerAccount: HqStoreManagerIssueResult;
}

// 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
  activeScheduleCount: number;  // (#152) 연결된 활성(ACTIVE) 반복예약 수. 0=없음. 삭제 시 함께 취소될 건수 — FE 삭제 다이얼로그 경고용.
}

// 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매장)` 보조 표기.
  activeScheduleCount: number;          // (#152) 연결된 활성(ACTIVE) 반복예약 수(CANCELED 제외). 0=없음. 삭제 시 cascade 취소될 건수 — FE 삭제 다이얼로그가 "반복예약 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`·`dispatchHistoryItemMissedReason.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·#143 5종) "SCHEDULED" | "PENDING" | "PLAYED" | "CANCELED" | "MISSED"
  createdAt: string;                      // 송출 row 생성 시각 (ISO-8601, 예약 등록 시각 = SCHEDULED 의 등록 시각)
  playedAt?: string | null;               // **실제 재생 완료** ack 시각 (ISO-8601). SCHEDULED/PENDING/CANCELED/MISSED 는 null — 실패·폐기 ack 는 채우지 않는다(정상 송출 집계의 단일 소스)
  // (감사 #11) 미도달 사유·재시도 진단 4필드 — ack outcome 계약 확장으로 신설.
  missedReason?: DispatchHistoryItemMissedReason | null; // "EXPIRED" | "PLAYBACK_FAILED" | "SKIPPED". MISSED 가 아닌 송출은 항상 null
  missedAt?: string | null;               // MISSED 종결 시각 (ISO-8601). MISSED 가 아니거나 V49 이전 만료 row 면 null
  playbackFailureCount: number;           // 점장 player 의 재생 실패 보고 누적 횟수(NOT NULL, 기본 0). **status=PENDING 인데 0보다 크면 지금 서버가 재전달 중**(재시도 중)이라는 운영 진단 신호
  lastFailedAt?: string | null;           // 마지막 실패 보고 시각 (ISO-8601). 실패 보고가 없으면 null. `missedAt` 과 다르다 — 임계치 미만이면 missedAt 은 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 만 카운트
  missed: number;                         // (감사 #11) 미재생 종결(MISSED) row 수 — grace 초과 자동 만료 + 점장 player 의 재생 실패·폐기 보고 합계
  canceled: number;                       // (감사 #11) 본사 취소(CANCELED) row 수 — 도달 의도가 철회된 송출(미도달과 구분)
  distinctStoreCount: number;             // (SPEC #075) 고유 매장 수 — COUNT(DISTINCT storeId), 매장 0건이면 0
}
// 감사 #11 — 상태 5종 분해가 완성되어 `scheduled + pending + played + missed + canceled == total` 이 성립한다
// (`distinctStoreCount` 는 매장 단위 지표라 이 합에 들어가지 않는다).

// 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;          // 서버가 파일 업로드(#174) 후 채운 Azure blob URL (`{prefix}/commercials/{id}.mp3`)
  durationSeconds: number;   // 오디오 길이(초) — 1..3600
  isActive: boolean;         // 활성 여부 — 점장 player 사이클 재생 대상 토글(#094 라운드로빈 후보 필터)
  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/createHqCommercialBody.ts` (multipart body)
CreateHqCommercialBody {
  file: Blob;               // CM송 MP3 파일
}
// generated `schemas/createHqCommercialParams.ts` (query)
CreateHqCommercialParams {
  title: string;            // 1~200
  durationSeconds: number;  // 1~3600 (클라이언트 추출)
}

// generated `schemas/replaceHqCommercialFileBody.ts` (multipart body)
ReplaceHqCommercialFileBody {
  file: Blob;               // 새 CM송 MP3 파일
}
// generated `schemas/replaceHqCommercialFileParams.ts` (query)
ReplaceHqCommercialFileParams {
  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[];               // 생성순 오름차순(시간순)
  attachments: TicketAttachmentItem[];           // 생성순 오름차순(없으면 []) — visibility 필드 없음
}

// 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/hqStoreTicketListItem.ts` · `hqStoreTicketListResponse.ts`
HqStoreTicketListItem {
  id: string;
  title: string;
  status: HqStoreTicketListItemStatus;       // OPEN | IN_PROGRESS | RESOLVED | CLOSED
  priority: HqStoreTicketListItemPriority;   // URGENT | HIGH | NORMAL | LOW
  category?: HqStoreTicketListItemCategory;  // @nullable — PLAYBACK | BROADCAST | BILLING | ACCOUNT | OTHER | null
  storeId: string;                           // 작성 매장 id
  storeName: string;                         // 작성 매장명
  commentCount: number;
  createdAt: string;                         // ISO-8601
  updatedAt: string;
}
HqStoreTicketListResponse { items: HqStoreTicketListItem[]; page: number; size: number; total: number; }

// generated `schemas/hqStoreTicketDetailResponse.ts` · `hqStoreTicketCommentItem.ts`
HqStoreTicketDetailResponse {
  id: string; title: string; body: string;
  status: HqStoreTicketDetailResponseStatus;
  priority: HqStoreTicketDetailResponsePriority;
  category?: HqStoreTicketDetailResponseCategory;   // @nullable
  storeId: string; storeName: string;
  submitterEmail: string;                           // 작성 점장 이메일 스냅샷
  createdAt: string; updatedAt: string;
  comments: HqStoreTicketCommentItem[];             // 생성순 오름차순, REPLY 만
  attachments: TicketAttachmentItem[];              // 운영자 INTERNAL 첨부 제외 · visibility 필드 없음
}
HqStoreTicketCommentItem {
  id: string; body: string;                         // @maxLength 5000
  authorRole: HqStoreTicketCommentItemAuthorRole;   // STORE_MANAGER | OPERATOR | HQ_MANAGER
  authorEmail: string; createdAt: string;
}

// generated `schemas/hqStoreTicketStatusChangeRequest.ts` · `...Response.ts`
HqStoreTicketStatusChangeRequest { status: HqStoreTicketStatusChangeRequestStatus; }   // 표준 전이 전체
HqStoreTicketStatusChangeResponse { status: HqStoreTicketStatusChangeResponseStatus; }

// generated `schemas/addHqStoreTicketCommentRequest.ts`
AddHqStoreTicketCommentRequest { body: string; }   // @maxLength 5000 · NotBlank → 201 HqStoreTicketCommentItem(authorRole=HQ_MANAGER)

// generated `schemas/hqStoreSupportUnreadSignalResponse.ts`
HqStoreSupportUnreadSignalResponse {
  openOrInProgressCount: number;         // 산하 매장 미해결(OPEN+IN_PROGRESS) 수 — 미해결 count 배지
  latestStoreActivityAt?: string | null; // 최신 점장 활동(신규 티켓·신규 답글) 시각 — 새 활동 dot
}

// 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 만
  attachments: TicketAttachmentItem[];  // 운영자 INTERNAL 첨부 제외 · visibility 필드 없음
}

// 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 후속).
  playAt?: string | null;             // (SPEC #178) 절대 재생 시각(ISO-8601) — 전 기기가 이 시각에 동시에 재생 시작. null 이면 종전대로 받는 즉시 재생.
}
 
// query (generated `listStorePendingAnnouncementsParams.ts`)
ListStorePendingAnnouncementsParams {
  deviceId?: string;                  // (SPEC #178) 이 요청을 보내는 기기 id. 주면 "이 기기가 아직 재생하지 않은 방송"까지 포함(전 기기 재생 보장). 생략 = 종전 매장 단위
}