파메 플랫폼 운영 대시보드

기획팀용 플랫폼 총괄 KPI 대시보드. 거래액 중심이 아니라 North Star(WAU) → 8개 레이어 관점으로 본다.

현재는 더미 데이터로 동작한다. 화면 상단의 주황색 고지 띠가 그 사실을 계속 표시한다.

실행

npm install
npm run dev      # http://localhost:3000
npm run build    # 배포 전 타입체크 + 빌드

구조

src/
  lib/data/
    types.ts                    도메인 타입 + DashboardSource 계약
    index.ts                    DATA_SOURCE 로 어댑터 선택 — 서버 전용
    adapters/mock/
      build.ts                  명세 → 화면 데이터. 단위·증감색·기간반영이 전부 여기
      layer-specs.ts            8개 레이어의 지표 명세 ← 실제 내용은 이 파일
      overview.ts               L0 개요 (타일 8개는 layer-specs 에서 뽑는다)
  lib/metrics/dictionary.ts     지표 사전 76개 + 불변 id. 카드↔정의를 잇는 고리
  lib/settings.ts               목표·임계 (유일한 출처)
  lib/settings-context.tsx      브라우저 로컬 오버라이드 — DB 연동 시 이 훅만 교체
  app/api/
    overview/route.ts           GET /api/overview?period=d7
    layer/[id]/route.ts         GET /api/layer/acq?period=d7
  app/
    page.tsx                    L0 개요
    layer/[slug]/page.tsx       L1 — 8개 레이어가 공유하는 단 하나의 화면
  components/                   화면 조각 + 차트

레이어 8개는 화면이 하나다

layer/[slug]/page.tsx 한 벌이 획득·활성·전환·유지·공급·신뢰·재무·시스템을 전부 그린다. 구조는 메인 지표 → 서브 지표 → 분해(대상 × 축) → 레이어 고유 표로 고정이고, 레이어마다 달라지는 것은 layer-specs.ts 의 데이터뿐이다. 탭 하나를 고치겠다고 화면 코드를 건드리면 나머지 일곱이 같이 깨진다.

레이어	메인 지표	분해 축	고유 표
01 획득	신규 가입자	유입채널 · 가입방식 · 지역 · 등급	등급 승급 처리
02 활성	기능 활성률	기능영역 · 플랫폼 · 시간대 · 유저 구분	기능영역별 체류·이탈
03 전환	구매 전환율	결제수단 · 유입경로 · 가격대 · 플랫폼	결제 실패 사유
04 유지	D7 리텐션	유입채널 · 첫 구매 여부 · 가입방식 · 등급	이탈 위험군 세그먼트
05 공급	미니샵 활성률	카테고리 · 판매자 등급 · 개설 기간 · 지역	카테고리별 수급
06 신뢰·품질	CS 첫응답 시간	문의 유형 · 채널 · 접수 시간대 · 플랫폼	문의 유형별 처리
07 재무	GMV	카테고리 · 가격대 · 결제수단 · 플랫폼	카테고리별 거래
08 시스템	크래시프리율	플랫폼 · 화면 · 앱 버전 · OS 버전	화면별 크래시

개요의 타일 8개는 이 표의 메인 지표와 같은 값을 같은 곳에서 가져온다. 타일을 누르면 해당 레이어로 들어간다.

데이터 교체 지점은 한 곳이다

화면은 어댑터를 직접 import 하지 않는다. 항상 getDashboardSource() 를 거치고, 그 호출은 app/api/* 라우트에서만 일어난다. GA4 서비스 계정 키나 DB 접속 정보가 브라우저 번들에 실리지 않게 하기 위한 것이다.

실데이터를 붙일 때는 src/lib/data/adapters/ 에 어댑터를 하나 추가하고 index.ts 의 switch 에 case 를 붙이면 끝난다. 화면 코드는 바뀌지 않는다.

DATA_SOURCE=mock   (기본)
DATA_SOURCE=ga4    GA4 Data API — user_id 전송 반영 후
DATA_SOURCE=db     PostgreSQL daily_metrics 집계 테이블

로그인

@pharmearth.kr 구글 계정만 들어올 수 있다. 로그인 화면과 인증 콜백을 빼고 전부 막혀 있고, 새 화면을 추가해도 자동으로 막힌다 (src/middleware.ts 는 화이트리스트가 아니라 블랙리스트다).

• 도메인 검사는 서버(src/auth.ts 의 signIn 콜백)에서 한다. 구글의 hd 파라미터는 계정 선택 화면의 힌트일 뿐이고, 요청을 직접 만들면 우회된다.
• API 는 401 JSON 을 준다. 로그인 화면 HTML 로 리다이렉트하면 fetch 쪽에서 JSON 파싱 에러가 나고, 화면에는 "로그인이 풀렸다" 대신 엉뚱한 메시지가 뜬다.
• 환경변수가 없으면 운영에서는 열리지 않는다. 개발에서만 로그인을 건너뛰고, 그때는 레일 하단에 "로그인 없음 — 아무나 접근 가능" 이라고 표시된다.

Google Cloud 설정

1. console.cloud.google.com → 프로젝트 선택(또는 새로 만들기)
2. API 및 서비스 → OAuth 동의 화면
   • User Type: 내부(Internal) — Workspace 조직 계정만 쓸 수 있게 한다
   • 앱 이름 파메 운영 대시보드, 지원 이메일 입력 후 저장
3. API 및 서비스 → 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID
   • 애플리케이션 유형: 웹 애플리케이션
   • 승인된 리디렉션 URI 에 아래 둘을 등록
     • http://localhost:3000/api/auth/callback/google (로컬 개발용)
     • https://<배포주소>/api/auth/callback/google (Vercel 주소)
4. 발급된 클라이언트 ID / 보안 비밀번호를 .env.local 에 넣는다 (.env.example 참고)
5. AUTH_SECRET 은 npx auth secret 으로 만든다

Vercel 에 올릴 때는 같은 값을 Project Settings → Environment Variables 에 넣는다.

설계 규칙 (지키지 않으면 화면이 거짓말을 한다)

• 델타 색은 방향이 아니라 good(좋아졌나)을 따른다. CS 첫응답 시간처럼 lower_is_better 지표는 ▼가 초록이다. Delta.good 을 반드시 채울 것.
• flow 와 stock 을 섞지 않는다. 신규 가입자(flow)는 기간에 따라 변하고, 누적 회원(stock)은 변하지 않는다. stock 을 보여줄 때는 "기간 필터 비적용" 배지를 단다.
• 기간 필터를 따르지 않는 카드는 칩으로 명시한다. WAU 추이·WAU 구성·코호트가 그렇다 (주 단위 지표 / 코호트 축).
• 상태색(good/warn/crit)은 시리즈 색과 분리돼 있고, 항상 텍스트 라벨과 함께 쓴다.
• 작은 라벨은 12px 아래로 내리지 않는다. 한글은 그 아래에서 뭉개진다. 자간도 넓히지 않는다.
• 시리즈 3색과 등급 램프는 색각이상(CVD) 전체 쌍 검증을 통과한 값이다. 임의로 바꾸지 말 것.
• 막대는 0을 바닥으로 읽힌다. 99.66% 같이 변동폭이 아주 작은 지표는 막대로 그리면 전부 같은 높이가 되는데, 축을 잘라서 속이는 대신 선으로 바꾼다 (trend.kind, 판정은 어댑터가 한다). 판정 기준은 지표이지 기간이 아니다 — 기간을 바꿀 때마다 차트 종류가 바뀌면 같은 지표로 안 읽힌다.
• 증감의 자릿수는 값의 자릿수와 맞춘다. 99.66% 지표의 -0.04를 "0.0%p"로 쓰면 변화가 없는 것처럼 읽힌다.
• 0과 미계측을 같이 쓰지 않는다. 시스템 탭의 Web 크래시는 0이 아니라 측정하지 않는 것이고, 그 사실이 화면에 경고로 나와야 한다.
• 목표 미달은 경고가 아니다. 목표는 늘 앞에 있는 값이라 미달을 경고로 만들면 경고가 상시 켜지고, 그러면 아무도 안 본다. 경고는 kind: "limit"(지금 문제가 있다는 선)과 위험선에만 붙인다. 목표 미달은 타일에 "미달" 표시만 남긴다.
• 목표·임계는 src/lib/settings.ts 한 곳에만 적는다. 타일 하단 표시, 경고 점, "주의 필요" 목록이 전부 여기서 계산된다. 화면에 숫자를 직접 적으면 목표를 한 번 바꿀 때 세 군데가 어긋난다.

이미지 저장

상단 이미지 저장 하나로만 한다 — 현재 화면 전체를 PNG 로 굽는다. html-to-image 로 DOM 을 그대로 굽고, 저장 버튼 자신은 data-capture="exclude" 로 빠진다.

카드마다 ↓ 를 달아 뒀다가 뺐다. 화면 어디를 봐도 버튼이 먼저 눈에 들어와서 정작 읽어야 할 숫자가 뒤로 밀렸다.

구매·판매 관점

상단 필터의 전체 / 구매 관점 / 판매 관점 은 세그먼트가 아니라 렌즈다. 판매자도 구매하므로 두 관점은 인원이 겹치고, 더해도 전체가 되지 않는다. 그래서 "구매자 / 판매자" 가 아니라 "구매 관점 / 판매 관점" 이라고 쓴다.

• 관점을 고르면 작업 영역 바탕색이 바뀐다 (구매=파랑 / 판매=주황). 분해 차트의 등급 색과 같은 계열이라, 이 연결은 화면 안에서 한 번만 익히면 된다.
• 관점이 적용되지 않는 지표는 조용히 전체 값을 보여주지 않는다. 레이어에는 안내 띠가, 개요 타일에는 전체 배지가 붙는다 (03 전환=구매 전용, 05 공급=판매 전용, 08 시스템=역할 무관).
• 등급은 하나의 사다리가 아니다. 파머 → 파머셀러 에서 역할이 바뀌므로 분해 축의 색을 두 계열로 나눈다. 정의는 src/lib/segments.ts 한 곳에 있다.

남은 일

• 각 레이어의 메인 지표·분해 축 확정 — 현재 구성은 지표 사전 기준 제안이다
• 개발팀 회신 대기 P0 2건(소급 불가라 오픈 전에 들어가야 한다) — user_type user property (North Star WAU 구성의 양면 분해용) / 가입 시점 유입정보 users 적재(유입채널 분해용). user_id는 더 이상 막는 조건이 아니다 — 없으면 기기 단위 근사치로 대체(활성·유지 레이어), 단 North Star 카드의 신규/복귀/유지 구성(WAU composition)은 여전히 코호트 단위 식별이 필요해서 지금은 목데이터로만 채워져 있다. 이 부분은 실측 전환 시 재검토 필요.
• daily_metrics 집계 테이블 설계 (DB 스키마 수령 후)
• CAC 는 광고비가 아니라 추천 보상·쿠폰 기준이다. 유료 광고를 집행하지 않으므로 광고비는 측정 불가가 아니라 값이 0 이다. 유료 채널을 시작하면 이 전제가 바뀌므로 그때 07 재무의 단위 경제 표를 다시 잡아야 한다.