# 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) ` ## 확인된 기존 계약 - `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`에 추가(기존 테스트 유지): ```typescript 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`: ```typescript 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`: ```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`: ```typescript 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; 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 사용법으로: ```typescript 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; 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`: ```typescript 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 키 체크 전 또는 직후)에 인증·제한 추가: ```typescript 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`: ```typescript 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; 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: 게이트·검증** ```bash 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: 게이트·검증** ```bash 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 }`) - 렌더: 병합 내림차순에 음악 카드 추가(제목·스토리 요약·오디오 링크/`