용어
Core 도메인
| 용어 | 정의 |
|---|---|
| HQ (본사) | 음원 송출 권한을 가진 상위 조직. FRANCHISE (가맹 본부) 또는 INDEPENDENT (개인 매장용 가상 본사 1개). |
| Store (매장) | 송출 endpoint 단위. DIRECT (본사 직영) / FRANCHISE (가맹) / INDEPENDENT (개인). 결제 단위는 type 별 분기. |
| Plan (플랜) | AI (자체 음원) · TRUST (AI + 신탁음원). 라이브러리는 단일 type. |
| Tenant | HQ + 산하 Store 의 운영 단위. 권한 격리의 기본. |
| 가상 본사 (INDEPENDENT singleton) | 시스템 전체 1개. id = 00000000-0000-0000-0000-000000000001. 개인 매장이 모두 산하. partial unique 로 race condition 차단. |
인증 / 권한
| 용어 | 정의 |
|---|---|
| OperatorAccount | 모든 사람 단일 entity. role 로 권한 분기. |
| Role | OPERATOR (운영사) · HQ_MANAGER (본사) · STORE_MANAGER (매장 점장). |
| AccountStatus | ACTIVE · SUSPENDED · WITHDRAWN. SUSPENDED 는 로그인 차단, WITHDRAWN 은 soft-delete 의 명시적 의도. |
| JWT access | 15분. HS256 + JWT_SECRET. claims {sub, role, hqId?, storeId?, type:'access', iat, exp}. |
| JWT refresh | opaque random 32B base64url. DB 저장 hash (SHA-256). 7일 (impersonation 60min). rotation 시 prev revokedAt 채움. |
| sealed cookie | iron-session lm_session — BFF 가 access/refresh 를 HttpOnly+Secure+SameSite=Lax 쿠키로 봉인. 클라이언트는 토큰을 직접 보유 X. |
| Impersonation | 운영사가 본사 모드로 대신 진입. 60초 1회 exchange token + 새 탭 + impersonatedBy JWT claim + 빨간 배너 항시. |
결제 / 정산
| 용어 | 정의 |
|---|---|
| billingAnchorDay | 결제 기준일 (1~31). FRANCHISE = Hq.billingAnchorDay, INDEPENDENT = Store.billingAnchorDay. |
| 결제 단위 | FRANCHISE = HQ 단위 (한 본사가 모든 산하 매장의 청구 받음) · INDEPENDENT = Store 단위. |
| 경과일 색 | 미결 1--info·--warn·--danger 활용. billing 전용 ramp (--color-status-billing-*) 는 아직 없으며 필요 시 후속 추가. |
약관 / 법무
| 용어 | 정의 |
|---|---|
| TermsDocument | 이용약관. 활성 1개만 (is_active=true partial unique). 본문은 content TEXT 컬럼. |
| PrivacyPolicy | 개인정보처리방침. TermsDocument 와 별개 entity (PIPA). |
| Consent | 동의 row. 4종 — HqConsent · HqPrivacyConsent · StoreConsent · StorePrivacyConsent. agreedIp · agreedUserAgent · signerName 자동 캡처. |
| 재동의 (re-agree) | 약관 version 변경 후 사용자에게 추가 동의 요구. /auth/me 의 termsRequiresAgreement flag. |
UI / 디자인 시스템
| 용어 | 정의 |
|---|---|
| Surface | 디자인 인격 단위. 10 (운영사) · 11 (본사 모드) · 12 (점장 모드). |
| OKLCH v2 | 디자인 시스템 v2. 3 계층 토큰 (Layer 1 primitive · Layer 2 semantic · Layer 3 surface-specific). |
| 운영사 백오피스 셸 | Surface 10 전역 셸 (Topbar + Sidebar). @linkmusic/ui 의 단일 컴포넌트가 아니라 apps/admin/src/app/(protected)/layout.tsx 가 조합. |
| AuthShell | 로그인 / 비밀번호 변경 등 인증 화면 셸. packages/ui/src/components/auth-shell.tsx. |
@linkmusic/ui 컴포넌트 | Button · Banner · StatusPill · OrgAvatar · Card · Dialog · DropdownMenu · Tabs/Tab · Toast · Switch · Field · Input · Label · FormSection · AuthShell · AuthCard (packages/ui/src/components/, flat). |
| OpsStepper | 다단계 폼의 시각 indicator. /hq/new 5-step · /stores/new 3-step. apps/admin/src/components/shell/ops-stepper.tsx (ui 패키지 아님). |
| PageHeader | 페이지 상단 헤더 (title + subtitle + actions). apps/admin/src/components/shell/page-header.tsx (ui 패키지 아님). |
인프라
| 용어 | 정의 |
|---|---|
| BFF | Backend-For-Frontend. apps/admin/src/app/api/* route handler — 쿠키에서 access 꺼내 backend 호출 + refresh 자동 갱신. |
| OpenAPI 단일 소스 | Springdoc 이 emit 한 /v3/api-docs → orval 로 packages/api-client/src/generated/ 생성. 수기 type 정의 금지. |
/sync-api | claude code skill. pnpm sync-api 실행 → fetch · orval · barrel 재생성 + typecheck. |
| Render | Backend PaaS. branch main → auto-deploy. |
| Vercel | Frontend PaaS. monorepo sub-app Root Directory = apps/admin 또는 apps/docs. |
References
- 백엔드 entity:
linkmusic-msa-space-was/src/main/kotlin/.../domain/entity/ - 프론트엔드:
linkmusic-frontend-space/apps/admin/src/lib/ - handoff:
design_handoff_linkmusic/briefs/