Overview시스템 한눈에

시스템 한눈에

기준 BE v0.19.0 / FE v0.20.0 / SPEC #001~#027 (#009 결번) — 최근 갱신 2026-06-04

LinkMusic 은 매장 배경음악 + 멘트 송출 SaaS. 베타 출시 단계로 운영사(링크뮤직 내부) / 본사(프랜차이즈) / 점장(매장) 3 페르소나를 단일 시스템에서 다룬다.

핵심 구조

linkmusic-msa-space-was  (Kotlin · Spring · PostgreSQL on Render)
        │
        │ REST  ─ access JWT(15min) · refresh(7d) · BCrypt(12)
        ▼
linkmusic-frontend-space  (pnpm workspace)
        ├── apps/admin       Next.js 16 · App Router · iron-session BFF  → 운영사 백오피스
        ├── apps/docs        Next.js 15 · Nextra v3 · MDX                → 이 문서
        ├── packages/ui      OKLCH v2 토큰 + shells + atoms
        ├── packages/api-client   orval generated · OpenAPI 단일 소스
        └── packages/config  eslint · tsconfig · tailwind preset

3 디자인 surface (design_handoff_linkmusic/briefs/):

  • Surface 10 — 운영사 백오피스 — 정보 밀도 高, 대량 작업, 키보드 우선 (admin.linkmusic.space)
  • Surface 11 — 매장 클라이언트 본사 모드 — 안전성·확인 흐름·미리듣기 (app.linkmusic.space/admin/*)
  • Surface 12 — 매장 클라이언트 점장 모드 — 단순성·큰 버튼·40~50대 가독성 (app.linkmusic.space/store/*)

v1 구현은 Surface 10 (운영사 백오피스) 중심. Surface 11·12 는 후속 SPEC.

현재 도입된 기능 (SPEC #001~#027, #009 결번)

영역도입
인증login · refresh · me · logout · change-password · production OPERATOR seed · HQ_MANAGER 로그인 라우팅 + /admin 이중 세션 · passwordMustChange enforcement
본사(HQ)등록(5-step) · 목록 · 상세(/hq/:id) · 정지/복구 + 정지 사유 · 임퍼소네이션 confirm + 새 탭 + 토큰 교환
매장(Store)INDEPENDENT 매장 등록(3-step) · ops 매장 목록(/stores) · STORE_MANAGER 계정 발급
운영(Ops)본사 모드 셸 + 임퍼소네이션 배너 · ops 대시보드 stats 연동
약관TermsDocument · PrivacyPolicy · 동의 4종 (HqConsent · StoreConsent · *PrivacyConsent) · 약관 게시 UI(/settings/policies)
감사(Audit)임퍼소네이션 감사 로그(/audit/impersonation) · 운영자 액션 감사 로그(/audit/actions)
CSCS 티켓 v1 (/tickets)
디자인 시스템 v2OKLCH 3계층 토큰 · AuthShell · 운영사 셸(Topbar+Sidebar) · @linkmusic/ui 컴포넌트 세트
인프라BFF sealed cookie · orval /sync-api · GitHub Actions · Vercel · Render

후속 SPEC 들은 /roadmap/pending-features 참고.

이 문서 읽는 법

  1. 처음 진입이면 Overview 전체를 먼저 읽는다 (vision · personas · 3-surface · tech-stack · glossary).
  2. 재구현 Blueprint가 필요하면 Contracts (3층위 계약) · Domain · Architecture 를 본다.
  3. 특정 기능 동작을 알고 싶으면 Features 의 해당 페이지.
  4. 백엔드와 통신할 일 있으면 API 카탈로그.
  5. 다음 무엇을 만들지 알고 싶으면 Roadmap.

페이지 작성 정책

각 페이지는 (해당하는 것만) 다음 섹션을 가집니다.

  1. Overview — 한 줄 요약 + WHY
  2. Spec — WHAT (입력 · 출력 · UI · 동작)
  3. Constraints (①) — 변경 불가 (보안 · 정책 · 데이터 분기)
  4. Design Goals (②) — 측정 가능 목표
  5. Implementation — HOW (data model · API · 코드 흐름)
  6. States & Edge Cases
  7. Decisions — 대안 · tradeoff
  8. Roadmap — 후속 SPEC · gap
  9. References — SPEC #NNN · code path · handoff 출처

References

  • 워크스페이스 루트 (<workspace>): 부모 폴더에 linkmusic-frontend-space/ · linkmusic-msa-space-was/ · design_handoff_linkmusic/ · docs/ 가 형제로 위치
  • 디자인 handoff: design_handoff_linkmusic/briefs/
  • SPEC: docs/specs/001-backend-bootstrap.md ~ 027-cs-tickets.md (#009 결번)
  • 백엔드 레포: linkmusic-msa-space-was/
  • 프론트엔드 레포: linkmusic-frontend-space/
홈비전 · KPI