FeaturesHQ (본사)HQ Mode 신탁 재생 로그 (apps/space /admin/playback/logs)

HQ Mode — 신탁 재생 로그 (apps/space /admin/playback/logs)

SPEC #176 (#172 FU-3) 도입. 실 HQ_MANAGER 직접 로그인 표면(apps/space · space.linkmusic.io).

Overview

본사(HQ_MANAGER)가 산하 매장의 재생 로그(곡당 1행·전량) 를 조회하고 서버 CSV 로 내보내는 전용 페이지다. #172 로 play_log(곡별·매장별·시각·is_trust·music_source·played_ms·hq_id)에 재생이 전량 적재되나 조회 화면이 없던 갭을 메운다. 재생 리포트(#175, 일/주/월 집계)와 인접한 원자 로그 축 — 집계 KPI 가 아니라 개별 재생 이벤트를 시간 역순으로 나열한다.

  • KOMCA 신고 근거: 신탁(TRUST) 음원 재생 이력이 저작권 신고의 원천 데이터다. 공식 신고 포맷은 외부 규격 게이트(권리자 필드·집계 규격 확정 후 별도) — 이번은 raw 조회·CSV 까지.
  • hqId 격리: BE verifyHqScope 가 토큰 주체 산하 매장만 반환(타 본사 storeId 지정해도 0). FE 는 본사 필터를 노출하지 않는다(자기 hq 고정).
  • 전량 + 신탁 필터: trustOnly 토글(기본 true=신탁만·해제 시 전량)로 “신탁 신고” 와 “전량 재생 이력” 두 요구를 한 화면이 커버한다.

시안: 전용 시안 부재. 본사 감사(#067)·재생 리포트(#175) 목록·필터 idiom 미러(atom-grounded, design-debt 등재).

페이지 구조 (/admin/playback/logs)

page.tsx(server 셸, force-dynamic) + playback-logs-client.tsx(client) + playback-logs-format.ts (순수 helper — 재생시간 m:ss·음원 라벨·CSV 경계/파일명, 기간 산술은 재생 리포트 ../playback-format 재사용). 본사 모드 셸 layout(/admin/layout.tsx)이 role 가드 + HQShell 을 제공하므로 별도 refresh-aware 가드 없이 client 영역만 렌더한다. 조회 파라미터는 client state(단일 페이지라 deep-link 가치 낮음). 사이드바 HQSidebar 에 재생 리포트 바로 아래 신탁 재생 로그 항목 추가 (icon ListMusic). /admin/playback 은 하위 라우트를 갖게 되어 active 판정을 정확 일치로 좁힌다 (EXACT_MATCH_HREFS — /admin/playback/logs 진입 시 재생 리포트 항목까지 강조되던 문제 차단).

필터 · 목록

  • 필터: 기간(from·to·필수·기본 최근 30일·366일 상한 클라 사전검증 → 위반 시 fetch 차단 + 경고 배너) + 신탁 토글(기본 신탁만) + 매장 select(useListHqStores 자기 산하 매장). 컨트롤 변경 시 page 0 리셋(free-text 없음 → 즉시 적용).
  • 목록 테이블: 재생 시각(KST)·매장명·곡명·음원 구분(AI/TRUST 배지)·재생 시간(m:ss). 정렬은 BE 고정(started_at desc → id desc — 헤더에 “(서버 정렬)” 보조라벨). 로딩·빈 상태(진짜 0건 vs 필터 0건)·out-of-range page-empty·에러(401/403/5xx/네트워크 분리) 분기.
  • 페이지네이션: ListPagination(20/page). total·현재 페이지·총 페이지.

CSV 내보내기

[CSV 내보내기] → 현재 필터 매칭 전체 행(상한 50,000) 을 서버 CSV 로. generated export 훅은 text/csv blob 이라 사용하지 않고, BFF catch-all /api/backend/api/v1/hq/playback-logs/export 을 직접 fetch 하는 공용 downloadCsvFromBackend(본사 감사 CSV #070 관례)로 blob 스트림 → <a download>. 파일명은 서버 Content-Disposition filename*(trust-playback-logs-{yyyyMMdd-HHmmss}.csv KST) 우선, 파싱 실패 시 클라 fallback. 상한 초과 시 응답 헤더 X-Export-Truncated: true → 잘림 경고 배너 (“기간을 좁힌 뒤 다시 시도”). 401 은 helper 가 /login?next= 리다이렉트.

계약

HQ Mode 재생 리포트 (apps/space /admin/playback)HQ Mode 매장 상세 조회 (apps/space /admin/stores/[id])