jaengseung-made/docs/superpowers/plans/2026-07-03-phase3a-music-public.md

Phase 3a 음악 서비스 공개화 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 숨김 상태의 Suno 음악 스튜디오를 공개·무료화하고 "스토리→음악"(Gemini) 흐름·회원 저장·라이트 디자인을 붙인다.

Architecture: 사주·타로의 "공개+무료+로그인 저장+일일제한" 패턴을 음악에 적용. Gemini가 스토리→가사/스타일 변환, Suno가 음악 생성(폴링), 완료 시 회원 저장. 음악 페이지는 --jsm 라이트로 재스킨.

Tech Stack: Next.js 16 (App Router, TS), Tailwind v4(--jsm-*), Supabase, @google/generative-ai, Suno API, vitest

Spec: docs/superpowers/specs/2026-07-03-phase3a-music-public-design.md

Global Constraints

• 순수 시각 변경 태스크에서는 로직 라인 미변경(className/style만); API 태스크에서는 인증→제한→호출→(성공)recordUsage 순서 준수
• 신규 색 토큰 금지 — 11개 --jsm-*만. 음악 신규/재스킨 파일에서 gradient/violet/purple/blur/이모지 0건
• 일일 제한: MUSIC_DAILY_LIMIT = 1. 생성(Suno) 성공 시에만 recordUsage('music'). story(Gemini) 단계는 인증만, 미집계
• GEMINI_API_KEY/SUNO_API_KEY 미설정 시 각각 503(예시 폴백 금지)
• ai_usage_log CHECK ALTER는 phase2-saju-tarot 마이그 DB 적용 후 실행 전제(플랜/CEO 안내에 명시)
• next.config.ts 수정 금지, 기존 supabase/migrations/ 파일 수정 금지(신규만)
• 커밋은 스코프 파일만 — git add -A·git commit -a 금지, 커밋 전 git status 확인
• 각 Task 종료 시 npm run build 성공 + npm test(30→) 유지 후 커밋
• 커밋 트레일러: Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

확인된 기존 계약

• POST /api/studio/generate(무인증): body {mode:'simple'|'custom', prompt?, title?, lyrics?, tags?, make_instrumental?, model?} → Suno /api/v1/generate → { ok, data }. callBackUrl=${origin}/api/studio/callback(부재)
• GET /api/studio/status?taskId=(무인증) → Suno record-info { ok, data }
• lib/ai-usage.ts: AiService='saju'|'tarot', kstDayStartISO, getTodayUsage(admin,userId,service), recordUsage(admin,userId,service)
• supabase 헬퍼: createClient()(세션·RLS), createAdminClient()(service role). 타로 prompt 방어 패턴: app/api/tarot/interpret/route.ts, lib/tarot/prompt.ts

---

Task 1: ai-usage 확장 + DB 마이그레이션

Files:

• Modify: lib/ai-usage.ts
• Create: supabase/migrations/2026-07-03-phase3a-music.sql
• Modify: lib/__tests__/ai-usage.test.ts

Interfaces:

• Produces: AiService = 'saju'|'tarot'|'music', MUSIC_DAILY_LIMIT = 1, music_tracks 테이블. Task 3·4·6이 소비

• Step 1: 테스트에 music 상수 추가

lib/__tests__/ai-usage.test.ts의 상수 검증 it에 추가(기존 테스트 유지):

import { kstDayStartISO, SAJU_DAILY_LIMIT, TAROT_DAILY_LIMIT, MUSIC_DAILY_LIMIT } from '../ai-usage';
// ... 기존 KST 테스트 유지 ...
it('음악 일일 제한 상수', () => {
  expect(MUSIC_DAILY_LIMIT).toBe(1);
});

• Step 2: 실패 확인 — npx vitest run lib/__tests__/ai-usage.test.ts → FAIL(MUSIC_DAILY_LIMIT 없음)

• Step 3: ai-usage.ts 확장

lib/ai-usage.ts:

export const SAJU_DAILY_LIMIT = 1;
export const TAROT_DAILY_LIMIT = 3;
export const MUSIC_DAILY_LIMIT = 1;
export type AiService = 'saju' | 'tarot' | 'music';

(getTodayUsage/recordUsage/kstDayStartISO 본문 무변경 — AiService 타입만 확장되어 'music' 허용)

• Step 4: 통과 확인 — npx vitest run lib/__tests__/ai-usage.test.ts → PASS

• Step 5: 마이그레이션 파일

supabase/migrations/2026-07-03-phase3a-music.sql:

-- Phase 3a (2026-07-03): 음악 회원 저장 + 사용량 로그 확장 + 음악 숨김 해제
-- 의존성: 2026-07-02-phase2-saju-tarot.sql(ai_usage_log 생성) 적용 후 실행
-- 적용: 클라우드 Supabase + NAS self-host 양쪽

CREATE TABLE IF NOT EXISTS music_tracks (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  title text,
  story text,
  lyrics text,
  style text,
  audio_url text,
  task_id text,
  created_at timestamptz NOT NULL DEFAULT now()
);
ALTER TABLE music_tracks ENABLE ROW LEVEL SECURITY;
CREATE POLICY music_select_own ON music_tracks FOR SELECT USING (auth.uid() = user_id);

-- ai_usage_log CHECK에 'music' 추가 (phase2의 인라인 CHECK auto-name 제거 후 재정의)
ALTER TABLE ai_usage_log DROP CONSTRAINT IF EXISTS ai_usage_log_service_check;
ALTER TABLE ai_usage_log ADD CONSTRAINT ai_usage_log_service_check CHECK (service IN ('saju','tarot','music'));

DELETE FROM service_settings WHERE id = 'music';

• Step 6: 검증·커밋 — npm test && npm run build PASS. git add lib/ai-usage.ts lib/__tests__/ai-usage.test.ts supabase/migrations/2026-07-03-phase3a-music.sql && git commit -m "feat(phase3a): ai-usage에 music 추가 + music_tracks·CHECK 마이그레이션"

---

Task 2: 음악 공개화 (가드 제거)

Files:

• Modify: app/music/layout.tsx
• Modify: lib/service-visibility.ts
• Modify: app/api/admin/services/route.ts

Interfaces:

• Consumes: 없음

• Produces: /music* 공개

• Step 1: layout 가드 제거

app/music/layout.tsx: isServiceVisible/notFound import·호출 제거, metadata 있으면 유지, 단순 return <>{children}</>. (파일 먼저 Read — metadata 유무 확인)

• Step 2: HideableService에서 music 제거

lib/service-visibility.ts: export type HideableService = 'gyeol' | 'lotto';

• Step 3: DEFAULT_SERVICES music 행 제거

app/api/admin/services/route.ts DEFAULT_SERVICES에서 { id: 'music', ... } 한 줄 삭제(gyeol/lotto 유지). (service_settings music DELETE는 Task 1 마이그레이션이 담당)

• Step 4: 검증·커밋 — npm test && npm run build(빌드 라우트에 /music이 static/공개로 등장). git add app/music/layout.tsx lib/service-visibility.ts app/api/admin/services/route.ts && git commit -m "feat(phase3a): 음악 서비스 공개화 — 가드·HideableService·DEFAULT_SERVICES 정리"

---

Task 3: 스토리→음악 (story-prompt + story API + generate 인증/제한 + callback)

Files:

• Create: lib/music/story-prompt.ts
• Create: app/api/studio/story/route.ts
• Create: app/api/studio/callback/route.ts
• Modify: app/api/studio/generate/route.ts

Interfaces:

• Consumes: getTodayUsage/recordUsage/MUSIC_DAILY_LIMIT(T1), createClient/createAdminClient

• Produces:

  • type MusicStory = { title: string; lyrics: string; style: string; mood: string }
  • POST /api/studio/story (로그인) → 200 { story: MusicStory } / 401 / 503
  • POST /api/studio/generate (로그인+제한) → 기존 { ok, data } / 401 / 429 / 503
  • POST /api/studio/callback → { ok: true }
  • Task 6이 소비

• Step 1: story-prompt 모듈 (타로 prompt.ts 방어 패턴 포팅)

lib/music/story-prompt.ts:

export type MusicStory = { title: string; lyrics: string; style: string; mood: string };

export const STORY_SYSTEM_PROMPT = `당신은 사용자의 개인적 이야기를 노래로 바꾸는 작사가 겸 음악 프로듀서입니다.
사용자가 들려준 이야기를 바탕으로:
1. title: 노래 제목(짧고 인상적으로)
2. lyrics: 이야기의 감정과 장면을 담은 한국어 가사(절/후렴 구조, 6~16줄)
3. style: 어울리는 음악 장르·악기·템포를 영어 키워드로(Suno style, 예 "acoustic ballad, warm piano, mid tempo")
4. mood: 전체 정서를 한 단어로(예 "그리움", "희망")
반드시 코드블록 없이 순수 JSON만 출력합니다: {"title","lyrics","style","mood"}
사용자 이야기에 없는 사실을 지어내지 말고, 감정에 충실하게 각색합니다.`;

export function buildStoryUserMessage(story: string): string {
  return `사용자의 이야기:\n${story}\n\n위 이야기를 노래로 만들기 위한 JSON을 생성하세요.`;
}

export function parseStoryJson(raw: string): MusicStory | null {
  let text = raw.trim().replace(/^\`\`\`(json)?/i, '').replace(/\`\`\`$/,'').trim();
  const first = text.indexOf('{'); const last = text.lastIndexOf('}');
  if (first >= 0 && last > first) text = text.slice(first, last + 1);
  try { return JSON.parse(text) as MusicStory; } catch { return null; }
}

export function validateStory(obj: unknown): string | null {
  if (!obj || typeof obj !== 'object') return 'not an object';
  const o = obj as Record<string, unknown>;
  for (const k of ['title', 'lyrics', 'style', 'mood']) {
    if (typeof o[k] !== 'string' || !(o[k] as string).trim()) return `${k} 누락`;
  }
  return null;
}

• Step 2: story API (타로 interpret의 Gemini 폴백·45s 가드·reroll 패턴)

app/api/studio/story/route.ts — app/api/tarot/interpret/route.ts를 참고해 동일 SDK 사용법으로:

import { NextResponse } from 'next/server';
import { GoogleGenerativeAI } from '@google/generative-ai';
import { createClient } from '@/lib/supabase/server';
import { STORY_SYSTEM_PROMPT, buildStoryUserMessage, parseStoryJson, validateStory } from '@/lib/music/story-prompt';
import { config as loadDotenv } from 'dotenv';
import { resolve } from 'path';

export const runtime = 'nodejs';
export const maxDuration = 60;
loadDotenv({ path: resolve(process.cwd(), '.env.local'), override: true });

const MODELS = [{ id: 'gemini-2.5-pro', maxTokens: 8192 }, { id: 'gemini-2.5-flash', maxTokens: 8192 }, { id: 'gemini-2.0-flash', maxTokens: 8192 }];
const MAX_ATTEMPTS = 3;
const TIME_BUDGET_MS = 45_000;

export async function POST(request: Request) {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) return NextResponse.json({ error: '로그인이 필요합니다.' }, { status: 401 });

  let body: Record<string, unknown>;
  try { body = await request.json(); } catch { return NextResponse.json({ error: '잘못된 요청 형식' }, { status: 400 }); }
  const story = typeof body.story === 'string' ? body.story.trim() : '';
  if (!story) return NextResponse.json({ error: '이야기를 입력해주세요.' }, { status: 400 });

  const apiKey = process.env.GEMINI_API_KEY;
  if (!apiKey) return NextResponse.json({ error: 'AI 서비스가 준비 중입니다.' }, { status: 503 });
  const genAI = new GoogleGenerativeAI(apiKey);
  const userMsg = buildStoryUserMessage(story);

  const startedAt = Date.now();
  let attempts = 0; let feedback = '';
  for (const m of MODELS) {
    for (let retry = 0; retry < 2; retry += 1) {
      if (attempts >= MAX_ATTEMPTS || Date.now() - startedAt > TIME_BUDGET_MS) break;
      attempts += 1;
      try {
        const model = genAI.getGenerativeModel({ model: m.id, systemInstruction: STORY_SYSTEM_PROMPT, generationConfig: { temperature: 0.9, topP: 0.95, maxOutputTokens: m.maxTokens } });
        const prompt = feedback ? `${userMsg}\n\n[이전 오류: ${feedback}] 스키마를 지켜 다시 출력하세요.` : userMsg;
        const res = await model.generateContent(prompt);
        const parsed = parseStoryJson(res.response.text());
        const invalid = parsed ? validateStory(parsed) : 'JSON 파싱 실패';
        if (parsed && !invalid) return NextResponse.json({ story: parsed });
        feedback = invalid ?? 'JSON 파싱 실패';
      } catch (e) { feedback = e instanceof Error ? e.message : 'model error'; break; }
    }
    if (attempts >= MAX_ATTEMPTS) break;
  }
  return NextResponse.json({ error: '가사 생성에 실패했습니다. 잠시 후 다시 시도해주세요.' }, { status: 502 });
}

(작성 전 app/api/tarot/interpret/route.ts를 Read해 실제 SDK 시그니처와 일치시킬 것)

• Step 3: callback 최소 라우트

app/api/studio/callback/route.ts:

import { NextResponse } from 'next/server';
export const runtime = 'nodejs';
// Suno webhook 수신용 최소 엔드포인트. 회원 저장은 폴링+클라 트리거(/api/studio/tracks)가 담당하므로 여기선 200만.
export async function POST() { return NextResponse.json({ ok: true }); }

• Step 4: generate에 인증 + 일일제한

app/api/studio/generate/route.ts POST 최상단(Suno 키 체크 전 또는 직후)에 인증·제한 추가:

import { createClient } from '@/lib/supabase/server';
import { createAdminClient } from '@/lib/supabase/admin';
import { getTodayUsage, recordUsage, MUSIC_DAILY_LIMIT } from '@/lib/ai-usage';
// POST 시작부:
const supabase = await createClient();
const { data: { user } } = await supabase.auth.getUser();
if (!user) return NextResponse.json({ error: '로그인이 필요합니다.' }, { status: 401 });
const admin = createAdminClient();
if ((await getTodayUsage(admin, user.id, 'music')) >= MUSIC_DAILY_LIMIT) {
  return NextResponse.json({ error: `오늘 음악 생성을 모두 사용했습니다. (${MUSIC_DAILY_LIMIT}회/일)` }, { status: 429 });
}

그리고 Suno task 생성이 성공 반환(return NextResponse.json({ ok: true, data }))되기 직전에 await recordUsage(admin, user.id, 'music'); 추가. (503/502/400 실패 경로엔 넣지 않음)

• Step 5: 검증·커밋 — npm test && npm run build(라우트 /api/studio/story·/callback 등장). git add lib/music/story-prompt.ts app/api/studio/story/route.ts app/api/studio/callback/route.ts app/api/studio/generate/route.ts && git commit -m "feat(phase3a): 스토리→가사(Gemini) + generate 인증·일일제한 + callback 정리"

---

Task 4: 음악 저장·조회 API

Files:

• Create: app/api/studio/tracks/route.ts

Interfaces:

• Consumes: createClient/createAdminClient, music_tracks(T1)

• Produces:

  • POST /api/studio/tracks (로그인) body { title?, story?, lyrics?, style?, audio_url?, task_id? } → { id, created_at } / 401
  • GET /api/studio/tracks (로그인) → { tracks: [{ id, title, story, lyrics, style, audio_url, task_id, created_at }] } / 401
  • Task 6이 소비

• Step 1: 구현 (타로 readings 패턴)

app/api/studio/tracks/route.ts:

import { NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { createAdminClient } from '@/lib/supabase/admin';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) return NextResponse.json({ error: '로그인이 필요합니다.' }, { status: 401 });
  let body: Record<string, unknown>;
  try { body = await request.json(); } catch { return NextResponse.json({ error: '잘못된 요청 형식' }, { status: 400 }); }
  const str = (k: string) => (typeof body[k] === 'string' ? (body[k] as string) : null);
  const admin = createAdminClient();
  const { data, error } = await admin.from('music_tracks').insert({
    user_id: user.id,
    title: str('title'), story: str('story'), lyrics: str('lyrics'),
    style: str('style'), audio_url: str('audio_url'), task_id: str('task_id'),
  }).select('id, created_at').single();
  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
  return NextResponse.json(data);
}

export async function GET() {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) return NextResponse.json({ error: '로그인이 필요합니다.' }, { status: 401 });
  const { data, error } = await supabase
    .from('music_tracks')
    .select('id, title, story, lyrics, style, audio_url, task_id, created_at')
    .order('created_at', { ascending: false });
  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
  return NextResponse.json({ tracks: data ?? [] });
}

• Step 2: 검증·커밋 — npm test && npm run build. git add app/api/studio/tracks/route.ts && git commit -m "feat(phase3a): 음악 트랙 저장·조회 API (user_id + RLS)"

---

Task 5: music/page·samples 라이트 재스킨

Files:

• Modify: app/music/page.tsx (72줄)
• Modify: app/music/samples/page.tsx (102줄)

Interfaces:

• Consumes: 없음

• Produces: 없음

• Step 1: 두 파일 Read 후 --jsm 치환

색상 매핑(사주 재스킨과 동일): 다크 hex/gradient/violet/purple/blur/amber → --jsm-navy(밴드 플랫)/accent/accent-soft/surface/line/ink. 이모지 있으면 제거 또는 인라인 SVG. 로직·데이터 조회·JSX 구조 미변경. navy 밴드=무테두리 flat + 흰 CTA 관용구.

• Step 2: 게이트·검증

grep -nE "gradient|violet|purple|blur" app/music/page.tsx app/music/samples/page.tsx   # 0
npm run build && npm test

• Step 3: 커밋 — git add app/music/page.tsx app/music/samples/page.tsx && git commit -m "feat(phase3a): 음악 랜딩·샘플 라이트 재스킨"

---

Task 6: studio 라이트 재스킨 + 스토리 UI 흐름

Files:

• Modify: app/music/studio/page.tsx (543줄)

Interfaces:

• Consumes: /api/studio/story(T3), /api/studio/generate(T3), /api/studio/status(기존), /api/studio/tracks(T4)

• Produces: 없음

• Step 1: Read 후 라이트 재스킨 + 스토리 흐름 재구성

app/music/studio/page.tsx 전체 Read. 두 가지 동시:

1. 라이트 재스킨: 다크/gradient/violet/purple/amber/이모지 → --jsm 토큰(사주 스튜디오 아님 — 신규 라이트). 폼 필드는 라이트 관용구(bg-white+border-[var(--jsm-line)]+focus:border-[var(--jsm-accent)])
2. 스토리 UI 흐름(기존 prompt/lyrics 직접입력 → 스토리 우선 흐름으로 확장, 기존 custom/simple 모드는 "직접 입력" 탭으로 보존 가능):
   • ①스토리 textarea + "가사 만들기" → POST /api/studio/story → 401이면 로그인 CTA(/login?next=/music/studio), 503/502면 안내
   • ②반환된 {title, lyrics, style, mood} 미리보기(편집 가능한 필드)
   • ③"음악 만들기" → POST /api/studio/generate(custom 모드, title/lyrics/tags=style) → 429면 제한 안내
   • ④기존 status 폴링 로직 유지 → 완료 시 오디오 URL 표시(플레이어)
   • ⑤완료+로그인 시 POST /api/studio/tracks로 자동 저장(best-effort, 실패해도 재생 유지)

• 디자인 가드레일: gradient/blur/보라/이모지 0건

• Step 2: 게이트·검증

grep -nE "gradient|violet|purple|blur" app/music/studio/page.tsx   # 0
npm run build && npm test

• Step 3: 커밋 — git add app/music/studio/page.tsx && git commit -m "feat(phase3a): 음악 스튜디오 라이트 재스킨 + 스토리→음악 흐름"

---

Task 7: TopNav + 마이페이지 AI기록 음악 + CLAUDE.md + 최종 검증

Files:

• Modify: app/components/TopNav.tsx
• Modify: app/mypage/page.tsx
• Modify: CLAUDE.md

Interfaces:

• Consumes: /api/studio/tracks(T4)

• Produces: 문서·네비 정합

• Step 1: TopNav 링크

app/components/TopNav.tsx LINKS에 { href: '/music', label: '음악' } 추가(외주/소프트웨어/제작사례/사주/타로/음악 = 6링크). 다른 항목 무변.

• Step 2: 마이페이지 AI 기록 탭에 음악 통합

app/mypage/page.tsx의 'AI 기록' 탭(사주·타로 병합 리스트)에 음악 트랙 추가:

• 타입 type MusicTrackRow = { id: string; title: string | null; story: string | null; audio_url: string | null; created_at: string } 추가

• state·로드: loadAiRecords에 fetch('/api/studio/tracks') 추가(try/catch, { tracks })

• 렌더: 병합 내림차순에 음악 카드 추가(제목·스토리 요약·오디오 링크/<audio>), 빈 상태 CTA에 /music 추가

• 기존 사주·타로 렌더·로직 미변경, 음악만 추가

• Step 3: CLAUDE.md 갱신

• 핵심 IA 표에 /music(공개 음악 — 스토리→음악) 추가

• 숨김 서비스 표에서 /music/* 행 제거

• 파일 구조에 lib/music/, api/studio/{story,tracks,callback} 반영

• /mypage 탭 서술에 음악 포함(AI 기록: 사주·타로·음악)

• Step 4: 최종 검증

grep -rnE "gradient|violet|purple|blur" app/music --include="*.tsx"   # 0
npm run build   # /music·/music/studio·/music/samples·/api/studio/{story,tracks,callback} 라우트 존재
npm test        # 30+ PASS

• Step 5: 커밋 — git add app/components/TopNav.tsx app/mypage/page.tsx CLAUDE.md && git commit -m "feat(phase3a): TopNav 음악 + 마이페이지 AI기록 음악 통합 + CLAUDE.md"

• Step 6: CEO 안내(보고)

• 마이그레이션 2026-07-03-phase3a-music.sql을 클라우드+NAS 양쪽 적용(phase2 마이그 적용 후)

• SUNO_API_KEY·GEMINI_API_KEY 운영 설정 확인(미설정 시 각 503)

• 수동 E2E: 비로그인 /music/studio → 스토리 입력→가사→로그인 CTA→로그인 후 생성(일1회)→저장→마이페이지 AI기록 음악

---

검증 요약

검증	명령	기대
음악 가드레일	grep -rnE "gradient|violet|purple|blur" app/music --include="*.tsx"	0건
단위 테스트	npm test	ai-usage music 포함 전체 PASS
빌드	npm run build	/music·studio·samples·api/studio/{story,tracks,callback}