agentic-cms: Skill for Claude Code

traffic-report — agentic-cms 트래픽 헤비 리포트

dashboard /analytics/traffic 가 제공하는 3소스(self analytics_events + GA4 + GSC) 데이터를 한 호출로 병렬 수집하고, 룰 기반 해석·이상 감지·행동 제안을 대화창 markdown 한 장으로 출력한다.

설계 원칙:

• 기존 dashboard/src/app/api/analytics/*/route.ts + dashboard/src/lib/analytics/traffic.ts 계산 로직을 100% 재사용. 이 스킬은 얇은 HTTP 클라이언트 + 해석 레이어.
• dashboard 서버 기동 전제. 미기동이면 기동 안내만 하고 종료 (자동 기동 금지).
• 파일 저장·옵시디언 반영 없음. 인라인 출력만.

인자 규약

호출	의미
/traffic-report	기본. preset=7d + today 스냅샷 + GA4·GSC(env 있으면) + 30d 히스토리 렌즈
/traffic-report 7d|30d|90d|this_month|last_month	preset 지정
/traffic-report today	오늘 누적(KST) vs 어제 동시점까지 비교
/traffic-report --compare=none	비교 끔 (현재 값만)
/traffic-report --skip=ga4,gsc	외부 소스 스킵 (GA4/GSC env 미설정 시 자동 스킵)
/traffic-report --topn=N	breakdown 상위 N (기본 10, API 상한 25)

preset이 30d·90d·this_month·last_month 또는 today이면 30일 히스토리 렌즈 섹션은 생략 (중복·의미 없음).

Phase 0 — Preflight

아래를 순서대로 확인. 실패 시 Phase 1 진입 금지.

0-1. 포트 3150 LISTEN

lsof -iTCP:3150 -sTCP:LISTEN -n -P 2>/dev/null | grep LISTEN

출력 없으면 기동 안내 후 스킬 종료 (자동 기동 X):

dashboard가 기동되지 않았습니다. 아래 명령으로 먼저 기동해 주세요.

cd /Users/jinkihyeok/Projects/agentic-cms/dashboard && PORT=3150 npm run dev

0-2. 인자 파싱 · 기본값 확정

• preset: 기본 7d. today면 mode=today.
• compare: 기본 previous. --compare=none이면 none.
• topN: 기본 10. --topn=N 오면 1~25 clamp.
• skip 목록: --skip=ga4,gsc 쉼표 분리.

0-3. GA4 / GSC 기본 포함 · 500이면 자동 degrade

GA4·GSC는 항상 호출 시도. Phase 1에서 500/503 응답 오면 해당 섹션만 "[데이터 없음: env 미설정]"로 degrade (사용자에게 env.local 설정 안내 bullet 추가). --skip=ga4 또는 --skip=gsc 명시하면 호출 자체 생략.

dashboard가 살아있으면 Supabase 연결은 일반적으로 정상 (서버가 이미 env 로드 상태). main API가 500이면 그때 전체 중단 + 에러 메시지.

Phase 1 — 병렬 수집

bash 단일 호출에 & + wait 패턴으로 fan-out. 각 curl은 30s timeout, -o로 임시 파일 저장, -w로 HTTP 코드 캡처.

BASE=http://localhost:3150
TMPDIR=$(mktemp -d)
PRESET={preset}
COMPARE={compare}
TOPN={topN}
DAYS={mapped_days}   # preset→days: 7d→7 / 30d→30 / 90d→90 / this_month·last_month→30 / today→7

# 주 데이터 (compare 또는 today)
if [ "$PRESET" = "today" ]; then
  URL_MAIN="$BASE/api/analytics/traffic?mode=today&topN=$TOPN"
else
  URL_MAIN="$BASE/api/analytics/traffic?mode=compare&preset=$PRESET&compare=$COMPARE&topN=$TOPN"
fi

curl -sS --max-time 30 -o "$TMPDIR/main.json" -w "%{http_code}" "$URL_MAIN" > "$TMPDIR/main.code" &

# today 스냅샷 (preset≠today일 때만, 리포트 상단에 "지금 이 순간" pulse로)
if [ "$PRESET" != "today" ]; then
  curl -sS --max-time 30 -o "$TMPDIR/today.json" -w "%{http_code}" "$BASE/api/analytics/traffic?mode=today&topN=$TOPN" > "$TMPDIR/today.code" &
fi

# 30d 히스토리 렌즈 (preset=7d 일 때만)
if [ "$PRESET" = "7d" ]; then
  curl -sS --max-time 30 -o "$TMPDIR/lens30.json" -w "%{http_code}" "$BASE/api/analytics/traffic?mode=compare&preset=30d&compare=previous&topN=$TOPN" > "$TMPDIR/lens30.code" &
fi

# GA4 (--skip=ga4 아닐 때만, 500이면 Phase 2에서 degrade)
if [ "$SKIP_GA4" != "1" ]; then
  curl -sS --max-time 30 -o "$TMPDIR/ga4.json" -w "%{http_code}" "$BASE/api/analytics/ga4?days=$DAYS" > "$TMPDIR/ga4.code" &
fi

# GSC (--skip=gsc 아닐 때만, 500이면 Phase 2에서 degrade)
if [ "$SKIP_GSC" != "1" ]; then
  curl -sS --max-time 30 -o "$TMPDIR/gsc.json" -w "%{http_code}" "$BASE/api/analytics/gsc?days=$DAYS" > "$TMPDIR/gsc.code" &
fi

wait
echo "tmpdir=$TMPDIR"
for f in main today lens30 ga4 gsc; do
  [ -f "$TMPDIR/$f.code" ] && echo "$f=$(cat $TMPDIR/$f.code)"
done