From da332540764b180179c8037f87c5a047eb0bfdb9 Mon Sep 17 00:00:00 2001 From: gahusb Date: Fri, 3 Jul 2026 12:47:16 +0900 Subject: [PATCH] =?UTF-8?q?@=20docs(phase3a):=20=EC=9D=8C=EC=95=85=20?= =?UTF-8?q?=EA=B3=B5=EA=B0=9C=ED=99=94=20=EA=B5=AC=ED=98=84=20=ED=94=8C?= =?UTF-8?q?=EB=9E=9C=20(7=20Task)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01AAtcmKKtqDUe4NyVgy1aLQ @ --- .../plans/2026-07-03-phase3a-music-public.md | 436 ++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-03-phase3a-music-public.md diff --git a/docs/superpowers/plans/2026-07-03-phase3a-music-public.md b/docs/superpowers/plans/2026-07-03-phase3a-music-public.md new file mode 100644 index 0000000..97a7585 --- /dev/null +++ b/docs/superpowers/plans/2026-07-03-phase3a-music-public.md @@ -0,0 +1,436 @@ +# 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 }`) +- 렌더: 병합 내림차순에 음악 카드 추가(제목·스토리 요약·오디오 링크/`