docs(env): add ALLOW_UNAUTHENTICATED_ADMIN guidance for F2

운영 .env에 ADMIN_API_KEY가 누락되면 verify_admin이 무조건 통과해서
/api/trade/balance, /api/trade/order 인증이 무력화되던 문제 차단.

- ADMIN_API_KEY 설정 + 올바른 키 → 통과 (기존 동작)
- ADMIN_API_KEY 설정 + 잘못된 키 → 401 (기존 동작)
- ADMIN_API_KEY 미설정 + ALLOW_UNAUTHENTICATED_ADMIN=true → 통과 (dev mode)
- ADMIN_API_KEY 미설정 + dev flag 없음 → 503 (신규, 운영 보호)

.env.example에 신규 ALLOW_UNAUTHENTICATED_ADMIN=false 안내 추가.
stock/pytest.ini 신규 (pythonpath=. 설정으로 tests 모듈 import 가능).
test_admin_auth.py 4 케이스 (RED → GREEN 검증, regression 포함).

.env.example

@@ -51,9 +51,14 @@ PGID=1000
 # Windows AI Server (NAS 입장에서 바라본 Windows PC IP)
 WINDOWS_AI_SERVER_URL=http://192.168.45.59:8000
 
-# Admin API Key (trade/order 등 민감 엔드포인트 보호, 미설정 시 인증 비활성화)
+# Admin API Key — /api/trade/* 등 민감 엔드포인트 보호.
+# 운영 .env에는 반드시 값을 채워야 함. 빈 값이면 503 응답으로 거부됨 (CODE_REVIEW F2).
 ADMIN_API_KEY=
 
+# 개발 모드: 위 ADMIN_API_KEY 비워둔 채로 trade/admin 엔드포인트 호출 허용.
+# 운영 환경에서는 절대 true로 두지 말 것. 기본 false (보호 활성).
+ALLOW_UNAUTHENTICATED_ADMIN=false
+
 # Anthropic API Key (AI Coach 프록시 + 뉴스 요약 Claude provider)
 ANTHROPIC_API_KEY=
 ANTHROPIC_MODEL=claude-haiku-4-5-20251001
@@ -99,6 +104,8 @@ YOUTUBE_DATA_API_KEY=
 DSM_HOST=https://gahusb.synology.me:5001
 DSM_USER=
 DSM_PASS=
+# LAN IP로 DSM 접근 시 self-signed cert가 IP에 매칭 안 되어 검증 실패. 그 경우 false 설정 (LAN 내부 통신이라 허용 가능). 도메인 + 정상 cert면 true 유지.
+DSM_VERIFY_SSL=true
 
 # Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값)
 BACKEND_HMAC_SECRET=
@@ -115,3 +122,7 @@ PACK_DATA_PATH=./data/packs
 
 # 컨테이너 내부 PACK_BASE_DIR (routes.py가 파일 저장 시 사용. docker-compose volume의 컨테이너 측 경로와 반드시 일치)
 PACK_BASE_DIR=/app/data/packs
+
+# DSM·Supabase에 노출되는 NAS 호스트 절대경로 (PACK_DATA_PATH와 같은 디렉토리를 호스트 시점에서 가리킴).
+# 운영 NAS는 반드시 /volume1/docker/webpage/media/packs 같은 절대경로 설정. 미설정 시 PACK_DATA_PATH로 fallback (로컬 개발용).
+PACK_HOST_DIR=/volume1/docker/webpage/media/packs

CLAUDE.md

@@ -7,7 +7,7 @@
 ## 1. 프로젝트 개요
 
 Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포.
-- **서비스**: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, packs-lab, deployer (10개)
+- **서비스**: lotto-lab, stock, travel-proxy, music-lab, insta-lab, realestate-lab, agent-office, personal, packs-lab, deployer (10개)
 - **프론트엔드**: 별도 레포 (React + Vite SPA), 빌드 산출물만 NAS에 배포
 - **인프라**: Docker Compose (10컨테이너) + Nginx(리버스 프록시) + Gitea Webhook 자동 배포
 
@@ -32,7 +32,7 @@ Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포.
 /volume1
 ├── docker/webpage/          # 운영 런타임 (Docker Compose 실행 위치)
 │   ├── lotto/               # lotto 소스 (rsync 동기화)
-│   ├── stock-lab/           # stock-lab 소스 (rsync 동기화)
+│   ├── stock/           # stock 소스 (rsync 동기화)
 │   ├── travel-proxy/        # travel-proxy 소스 (rsync 동기화)
 │   ├── deployer/            # deployer 소스 (rsync 동기화)
 │   ├── nginx/default.conf   # Nginx 설정
@@ -54,9 +54,9 @@ Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포.
 | 컨테이너 | 포트 | 역할 |
 |---------|------|------|
 | `lotto` | 18000 | 로또 데이터 수집·분석·추천 API |
-| `stock-lab` | 18500 | 주식 뉴스·AI 분석·KIS API 연동 |
+| `stock` | 18500 | 주식 뉴스·AI 분석·KIS API 연동 |
 | `music-lab` | 18600 | AI 음악 생성·라이브러리 관리 API |
-| `blog-lab` | 18700 | 블로그 마케팅 수익화 API |
+| `insta-lab` | 18700 | 인스타 카드 피드 자동 생성 (뉴스→키워드→10페이지 카드) |
 | `realestate-lab` | 18800 | 부동산 청약 자동 수집·매칭 API |
 | `agent-office` | 18900 | AI 에이전트 오피스 (실시간 WebSocket + 텔레그램 연동) |
 | `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (DSM 공유 링크 + 5GB 업로드, Vercel SaaS와 HMAC 통신) |
@@ -73,11 +73,11 @@ Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포.
 |------|------------|------|
 | `/api/` | `lotto:8000` | lotto API (기본) |
 | `/api/travel/` | `travel-proxy:8000` | travel API |
-| `/api/stock/` | `stock-lab:8000` | stock API |
-| `/api/trade/` | `stock-lab:8000` | KIS 실계좌 API |
-| `/api/portfolio` | `stock-lab:8000` | trailing slash 유무 모두 매칭 |
+| `/api/stock/` | `stock:8000` | stock API |
+| `/api/trade/` | `stock:8000` | KIS 실계좌 API |
+| `/api/portfolio` | `stock:8000` | trailing slash 유무 모두 매칭 |
 | `/api/music/` | `music-lab:8000` | AI 음악 생성·라이브러리 API |
-| `/api/blog-marketing/` | `blog-lab:8000` | 블로그 마케팅 수익화 API |
+| `/api/insta/` | `insta-lab:8000` | 인스타 카드 자동 생성 API |
 | `/api/realestate/` | `realestate-lab:8000` | 부동산 청약 API |
 | `/api/todos` | `personal:8000` | 투두 API |
 | `/api/blog/` | `personal:8000` | 블로그 API |
@@ -135,7 +135,7 @@ docker compose up -d
 | Lotto Backend | http://localhost:18000 |
 | Travel API | http://localhost:19000 |
 | Stock Lab | http://localhost:18500 |
-| Blog Lab | http://localhost:18700 |
+| Insta Lab | http://localhost:18700 |
 | Realestate Lab | http://localhost:18800 |
 | Packs Lab | http://localhost:18950 |
 
@@ -205,14 +205,14 @@ docker compose up -d
 | GET | `/api/lotto/briefing/{draw_no}` | 특정 회차 브리핑 |
 | GET | `/api/lotto/briefing` | 브리핑 이력 |
 
-### stock-lab (stock-lab/)
+### stock (stock/)
 - Windows AI 서버 연동: `WINDOWS_AI_SERVER_URL=http://192.168.45.59:8000`
 - KIS API 연동으로 실계좌 잔고·거래 조회
 - 뉴스 스크래핑: 네이버 증권 + 해외 사이트
 - DB: `/app/data/stock.db` (articles, portfolio, broker_cash, asset_snapshots, sell_history 테이블)
 - 파일 구조: `main.py`, `db.py`, `scraper.py`, `price_fetcher.py`, `holidays.json`
 
-**stock-lab API 목록**
+**stock API 목록**
 
 | 메서드 | 경로 | 설명 |
 |--------|------|------|
@@ -454,65 +454,55 @@ docker compose up -d
 | PUT | `/api/travel/albums/{album}/region` | 앨범 지역 변경 (region_map_extra 수정) |
 | PUT | `/api/travel/regions/{region_id}` | 커스텀 지역 이름/좌표 수정 (지도 핀 표시용) |
 
-### blog-lab (blog-lab/)
-- 블로그 마케팅 수익화 서비스 (키워드 분석 → AI 글 생성 → 마케팅 강화 → 품질 리뷰 → 포스팅 → 수익 추적)
-- AI 엔진: Claude API (Anthropic, `claude-sonnet-4-20250514`)
-- 웹 검색: Naver Search API (블로그 + 쇼핑) + 상위 블로그 본문 크롤링
-- DB: `/app/data/blog_marketing.db`
-- 파일 구조: `main.py`, `db.py`, `config.py`, `naver_search.py`, `content_generator.py`, `marketer.py`, `quality_reviewer.py`, `web_crawler.py`
+### insta-lab (insta-lab/)
+- 인스타그램 카드 피드 자동 생성 — 뉴스 모니터링 → 키워드 추출 → 10페이지 카드 카피 + PNG 렌더 → 텔레그램 푸시 → 사용자 수동 업로드
+- DB: `/app/data/insta.db` (news_articles, trending_keywords, card_slates, card_assets, generation_tasks, prompt_templates)
+- 카드 사이즈: 1080×1350 (인스타 4:5 세로)
+- 카드 렌더: Jinja2 템플릿 → Playwright headless Chromium 스크린샷
+- 파일 구조: `app/main.py`, `config.py`, `db.py`, `news_collector.py`, `keyword_extractor.py`, `card_writer.py`, `card_renderer.py`, `templates/default/card.html.j2`
 
-**파이프라인**: 리서치(+크롤링) → 작가(초안) → 마케터(링크 삽입) → 평가자(6기준 60점)
-**상태 흐름**: `draft` → `marketed` → `reviewed` → `published`
+**환경변수**
+- `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET`: 네이버 검색 API
+- `ANTHROPIC_API_KEY`: Claude API (Haiku=키워드 정제, Sonnet=카드 카피)
+- `ANTHROPIC_MODEL_HAIKU` / `ANTHROPIC_MODEL_SONNET`: 모델명 오버라이드
+- `INSTA_DATA_PATH`: SQLite + 카드 PNG 저장 경로 (기본 `/app/data`)
+- `CARD_TEMPLATE_DIR`: HTML 템플릿 디렉토리 (기본 `/app/app/templates`)
+- `NEWS_PER_CATEGORY` / `KEYWORDS_PER_CATEGORY`: 수집·추출 limit 튜닝
 
-**blog_marketing.db 테이블**
+**카테고리 시드 키워드**
+- 기본 economy / psychology / celebrity 3종 (config.DEFAULT_CATEGORY_SEEDS)
+- `prompt_templates.name='category_seeds'`에 JSON으로 오버라이드 가능
 
-| 테이블 | 설명 |
-|--------|------|
-| `keyword_analyses` | 키워드 분석 결과 (네이버 검색 데이터 + 경쟁도/기회 점수 + 크롤링 본문) |
-| `blog_posts` | 블로그 글 (draft → marketed → reviewed → published) |
-| `brand_links` | 브랜드커넥트 제휴 링크 (post_id/keyword_id FK) |
-| `commissions` | 포스트별 월간 클릭/구매/수익 |
-| `generation_tasks` | 비동기 작업 상태 (research/generate/market/review) |
-| `prompt_templates` | AI 프롬프트 템플릿 (DB 저장, 코드 배포 없이 수정 가능) |
+**카드 슬레이트 (`card_slates`)**
+- status: `draft` → `rendered` → `sent` (또는 `failed`)
+- cover_copy / body_copies (8개) / cta_copy / suggested_caption / hashtags JSON 컬럼
+- accent_color는 카테고리별 기본값 (economy=#0F62FE, psychology=#A66CFF, celebrity=#FF5C8A)
 
-**blog-lab API 목록**
+**스케줄러 job (agent-office)**
+- 09:30 매일 — `_run_insta_schedule` (insta_pipeline) → 뉴스 수집 → 키워드 추출 → 텔레그램 후보 푸시
+- `agent_config.custom_config.auto_select=True`이면 카테고리당 1위 키워드 자동 슬레이트 생성·발송
+
+**insta-lab API 목록**
 
 | 메서드 | 경로 | 설명 |
 |--------|------|------|
-| GET | `/api/blog-marketing/status` | 서비스 상태 (API 키 설정 현황) |
-| POST | `/api/blog-marketing/research` | 키워드 분석 시작 (+ 상위 블로그 크롤링) |
-| GET | `/api/blog-marketing/research/history` | 분석 이력 조회 |
-| GET | `/api/blog-marketing/research/{id}` | 분석 상세 조회 |
-| DELETE | `/api/blog-marketing/research/{id}` | 분석 삭제 |
-| GET | `/api/blog-marketing/task/{task_id}` | 작업 상태 폴링 |
-| POST | `/api/blog-marketing/generate` | 작가 단계: AI 글 생성 (크롤링 참고 + 링크 반영) |
-| POST | `/api/blog-marketing/market/{post_id}` | 마케터 단계: 전환율 강화 + 링크 삽입 |
-| POST | `/api/blog-marketing/review/{post_id}` | 평가자 단계: 품질 리뷰 (6기준 × 10점, 42/60 통과) |
-| POST | `/api/blog-marketing/regenerate/{post_id}` | 피드백 기반 재생성 |
-| POST | `/api/blog-marketing/links` | 브랜드커넥트 링크 등록 |
-| GET | `/api/blog-marketing/links` | 링크 조회 (post_id, keyword_id 필터) |
-| PUT | `/api/blog-marketing/links/{id}` | 링크 수정 |
-| DELETE | `/api/blog-marketing/links/{id}` | 링크 삭제 |
-| GET | `/api/blog-marketing/posts` | 포스트 목록 (status 필터) |
-| GET | `/api/blog-marketing/posts/{id}` | 포스트 상세 |
-| PUT | `/api/blog-marketing/posts/{id}` | 포스트 수정 |
-| DELETE | `/api/blog-marketing/posts/{id}` | 포스트 삭제 |
-| POST | `/api/blog-marketing/posts/{id}/publish` | 발행 (네이버 URL 등록) |
-| GET | `/api/blog-marketing/commissions` | 수익 내역 조회 |
-| POST | `/api/blog-marketing/commissions` | 수익 기록 추가 |
-| PUT | `/api/blog-marketing/commissions/{id}` | 수익 기록 수정 |
-| DELETE | `/api/blog-marketing/commissions/{id}` | 수익 기록 삭제 |
-| GET | `/api/blog-marketing/dashboard` | 대시보드 집계 |
-
-**환경변수**
-- `ANTHROPIC_API_KEY`: Claude API 키 (미설정 시 AI 생성 비활성화)
-- `NAVER_CLIENT_ID`: 네이버 검색 API 클라이언트 ID
-- `NAVER_CLIENT_SECRET`: 네이버 검색 API 시크릿
-- `BLOG_DATA_PATH`: SQLite DB 저장 경로 (기본 `./data/blog`)
+| GET | `/api/insta/status` | 서비스 상태 (NAVER/ANTHROPIC 키 여부) |
+| POST | `/api/insta/news/collect` | 뉴스 수집 트리거 (BackgroundTask) |
+| GET | `/api/insta/news/articles` | 수집 기사 목록 (category, days) |
+| POST | `/api/insta/keywords/extract` | 키워드 추출 트리거 (BackgroundTask) |
+| GET | `/api/insta/keywords` | 트렌딩 키워드 목록 (category, used) |
+| POST | `/api/insta/slates` | 슬레이트 생성 (keyword, category) |
+| GET | `/api/insta/slates` | 슬레이트 목록 |
+| GET | `/api/insta/slates/{id}` | 슬레이트 상세 + 자산 |
+| POST | `/api/insta/slates/{id}/render` | 카드 렌더 재시도 |
+| GET | `/api/insta/slates/{id}/assets/{page}` | 카드 PNG 다운로드 (1~10) |
+| DELETE | `/api/insta/slates/{id}` | 슬레이트 삭제 (자산 파일 포함) |
+| GET | `/api/insta/tasks/{task_id}` | BackgroundTask 상태 폴링 |
+| GET/PUT | `/api/insta/templates/prompts/{name}` | 프롬프트 템플릿 CRUD |
 
 ### agent-office (agent-office/)
 - AI 에이전트 가상 오피스 — 2D 픽셀아트 사무실에서 에이전트가 실제 작업 수행
-- stock-lab/music-lab/realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
+- stock/music-lab/realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
 - 실시간 상태 동기화: WebSocket (`/api/agent-office/ws`)
 - 텔레그램 봇: 양방향 알림 + 승인 (인라인 키보드)
 - 청약 매칭 알림: realestate-lab이 신규 매칭 발견 시 push → `RealestateAgent.on_new_matches()` → 텔레그램 1통(인라인 [🔖 북마크]/[📄 공고] 또는 [전체 보기] 버튼)
@@ -522,7 +512,7 @@ docker compose up -d
 **에이전트 FSM 상태**: idle → working → waiting (승인 대기) → reporting → break (휴식)
 
 **환경변수**
-- `STOCK_LAB_URL`: stock-lab 내부 URL (기본 `http://stock-lab:8000`)
+- `STOCK_URL`: stock 내부 URL (기본 `http://stock:8000`)
 - `MUSIC_LAB_URL`: music-lab 내부 URL (기본 `http://music-lab:8000`)
 - `REALESTATE_LAB_URL`: realestate-lab 내부 URL (기본 `http://realestate-lab:8000`) — 북마크 콜백 프록시 대상
 - `REALESTATE_DASHBOARD_URL`: 텔레그램 [전체 보기] 버튼 URL (기본 `http://localhost:8080/realestate`)
@@ -642,15 +632,18 @@ docker compose up -d
 - Vercel SaaS와 HMAC 인증으로 통신, 사용자 인증은 Vercel이 Supabase로 처리 (본 서비스는 외부 인증 없음)
 - DB: 외부 Supabase `pack_files` 테이블 (DDL: `packs-lab/supabase/pack_files.sql`)
 - 파일 구조: `app/main.py`, `app/auth.py`, `app/dsm_client.py`, `app/routes.py`, `app/models.py`
-- 컨테이너 저장 경로: `PACK_BASE_DIR` env (default `/app/data/packs`). docker-compose volume 마운트와 일치 필수.
+- 경로 3분리: `PACK_DATA_PATH`(호스트 OS path, docker volume 좌측) → `PACK_BASE_DIR`(컨테이너 내부, upload 저장 target) → `PACK_HOST_DIR`(DSM API path, Supabase에 저장). 운영 NAS에서 `PACK_HOST_DIR` 미설정 시 sign-link가 컨테이너 경로를 DSM에 전달해 파일을 못 찾음.
+- ⚠️ **DSM API path 형식**: Synology DSM API는 일반 사용자 권한일 때 `/<shared_folder>/...` 형식만 인식하고 `/volume1/...` 절대경로는 거부(error 408). 운영 NAS는 반드시 `PACK_HOST_DIR=/docker/webpage/media/packs` (shared folder 시점) 설정. admin 사용자만 `/volume1/...` 사용 가능하나 보안상 권장 안 함.
 
 **환경변수**
 - `DSM_HOST` / `DSM_USER` / `DSM_PASS`: Synology DSM 7.x 인증 (공유 링크 발급용)
+- `DSM_VERIFY_SSL`: SSL 검증 (default `true`). LAN IP + self-signed cert 환경에서 IP mismatch 시 `false` 설정 (LAN 내부 통신이라 허용)
 - `BACKEND_HMAC_SECRET`: Vercel SaaS와 양쪽 공유 시크릿 (HMAC SHA256)
 - `SUPABASE_URL` / `SUPABASE_SERVICE_KEY`: Supabase pack_files 테이블 접근 (service_role, RLS 우회)
 - `UPLOAD_TOKEN_TTL_SEC`: admin upload 토큰 TTL (기본 1800초 = 30분)
 - `PACK_BASE_DIR`: 컨테이너 내부 저장 경로 (기본 `/app/data/packs`)
-- `PACK_DATA_PATH`: 호스트 마운트 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
+- `PACK_HOST_DIR`: DSM API용 path. **운영 NAS는 `/docker/webpage/media/packs` (shared folder 시점)**. 미설정 시 `PACK_BASE_DIR`로 fallback (DSM 호출 X 환경에서만 안전)
+- `PACK_DATA_PATH`: docker-compose volume 마운트의 호스트 측 OS 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
 
 **HMAC 인증 패턴**
 - Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret))
@@ -663,10 +656,21 @@ docker compose up -d
 |--------|------|------|
 | POST | `/api/packs/sign-link` | Vercel HMAC → DSM Sharing.create로 4시간 유효 다운로드 URL 발급 |
 | POST | `/api/packs/admin/mint-token` | Vercel HMAC → 일회성 upload 토큰 발급 (기본 30분 TTL) |
-| POST | `/api/packs/upload` | Bearer token → multipart 5GB 저장 + Supabase INSERT |
+| POST | `/api/packs/upload` | Bearer token (single-shot) → multipart 5GB 저장 + Supabase INSERT |
+| POST | `/api/packs/upload/init` | Bearer token → chunked upload 세션 초기화 (`session_id = jti`, `chunk_max_size` 반환). init만 jti consume |
+| PUT | `/api/packs/upload/{session_id}/chunk?offset=N` | 동일 Bearer token → 부분파일 append (offset 불일치 시 409 + `X-Current-Offset` 헤더) |
+| GET | `/api/packs/upload/{session_id}/status` | 동일 Bearer token → `{written, expected_size}` 조회 (재개용) |
+| POST | `/api/packs/upload/{session_id}/complete` | 동일 Bearer token → 부분파일 rename + Supabase INSERT |
+| DELETE | `/api/packs/upload/{session_id}` | 동일 Bearer token → 세션 중단 + 부분파일 정리 |
 | GET | `/api/packs/list` | Vercel HMAC → 활성 pack_files 목록 (deleted_at IS NULL) |
 | DELETE | `/api/packs/{file_id}` | Vercel HMAC → soft delete (DSM 공유는 자동 만료) |
 
+**Chunked upload 흐름 (5GB+ 안정성)**
+- 같은 mint-token을 init·chunk·status·complete·abort 전체에서 Bearer로 재사용 (jti consume은 init에서만)
+- 세션 state: 컨테이너 내부 `PACK_BASE_DIR/.uploads/{jti}/meta.json + data.part`
+- chunk 재시도: 클라이언트는 PUT 응답 헤더 `X-Current-Offset` 또는 `GET /status`로 재개 지점 확인
+- 환경변수 `PACK_CHUNK_MAX_SIZE` (기본 64MB) — 너무 크면 nginx buffering 부담, 너무 작으면 RTT 비용
+
 ### deployer (deployer/)
 - Webhook 검증: `X-Gitea-Signature` (HMAC SHA256, `compare_digest` 사용)
 - `WEBHOOK_SECRET` 환경변수로 시크릿 관리
@@ -683,7 +687,8 @@ docker compose up -d
 - **캐시 전략**: `index.html`은 `no-store`, `assets/`는 1년 장기 캐시(immutable)
 - **Frontend 배포**: git push로 자동 배포되지 않음. 로컬 빌드 후 NAS에 수동 업로드
 - **.env 파일**: 절대 커밋 금지. `.env.example`만 레포에 포함
-- **공휴일 목록**: `stock-lab/app/holidays.json` 매년 수동 갱신 필요 (KRX 기준)
+- **공휴일 목록**: `stock/app/holidays.json` 매년 수동 갱신 필요 (KRX 기준)
 - **Windows AI 서버 IP**: `192.168.45.59` — 공유기 DHCP 고정 예약으로 고정. Tailscale은 Synology에서 TCP 불가(userspace 모드)라 로컬 IP 사용
 - **현재가 조회**: 네이버 모바일 API → HTML 파싱 폴백, 3분 TTL 캐시 (`price_fetcher.py`)
 - **시뮬레이션 교체 방식**: `best_picks`는 교체형 — 새 시뮬레이션 실행 시 `is_active=0`으로 비활성화 후 신규 입력
+- **insta-lab Playwright**: NAS에서 chromium 빌드는 가능하지만 +500MB 이미지. 메모리 부족 시 카드 렌더 실패 가능 — 한 번에 1슬레이트만 렌더하도록 직렬화됨

README.md

@@ -13,8 +13,8 @@ Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
 │  ├── 정적 SPA 서빙 (React + Vite)                                     │
 │  └── API 리버스 프록시                                                 │
 │       ├── /api/                  → lotto-backend:8000  (로또·블로그·투두)│
-│       ├── /api/stock/, /trade/   → stock-lab:8000                     │
-│       ├── /api/portfolio         → stock-lab:8000                     │
+│       ├── /api/stock/, /trade/   → stock:8000                     │
+│       ├── /api/portfolio         → stock:8000                     │
 │       ├── /api/music/            → music-lab:8000                     │
 │       ├── /api/blog-marketing/   → blog-lab:8000                      │
 │       ├── /api/realestate/       → realestate-lab:8000                │
@@ -29,7 +29,7 @@ Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
 | 컨테이너 | 포트 | 역할 |
 |---------|------|------|
 | `lotto-backend` | 18000 | 로또 데이터 수집·분석·추천 + 블로그·투두 API |
-| `stock-lab` | 18500 | 주식 뉴스·AI 요약·KIS 실계좌·포트폴리오·자산 추적 |
+| `stock` | 18500 | 주식 뉴스·AI 요약·KIS 실계좌·포트폴리오·자산 추적 |
 | `music-lab` | 18600 | AI 음악 생성 (Suno + 로컬 MusicGen 듀얼 프로바이더) |
 | `blog-lab` | 18700 | 블로그 마케팅 수익화 (키워드→글 생성→리뷰→발행) |
 | `realestate-lab` | 18800 | 청약 공고 자동 수집·프로필 매칭 |
@@ -45,7 +45,7 @@ Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
 ```
 web-backend/
 ├── backend/              # lotto-backend (로또·블로그·투두)
-├── stock-lab/            # 주식·포트폴리오
+├── stock/            # 주식·포트폴리오
 ├── music-lab/            # AI 음악 생성
 ├── blog-lab/             # 블로그 마케팅 파이프라인
 ├── realestate-lab/       # 청약 자동 수집·매칭
@@ -75,7 +75,7 @@ curl http://localhost:18500/health
 |--------|----------|
 | Frontend + API | http://localhost:8080 |
 | lotto-backend | http://localhost:18000 |
-| stock-lab | http://localhost:18500 |
+| stock | http://localhost:18500 |
 | music-lab | http://localhost:18600 |
 | blog-lab | http://localhost:18700 |
 | realestate-lab | http://localhost:18800 |
@@ -99,7 +99,7 @@ curl http://localhost:18500/health
 - 09:10 / 21:10 — 당첨번호 동기화 + 추천 채점
 - 00:05, 04:05, 08:05, 12:05, 16:05, 20:05 — 몬테카를로 시뮬레이션 (후보 20,000 → 상위 100 → best_picks 20쌍 교체)
 
-### 2. stock-lab (`/api/stock/`, `/api/trade/`, `/api/portfolio`)
+### 2. stock (`/api/stock/`, `/api/trade/`, `/api/portfolio`)
 
 주식 뉴스 스크래핑 + LLM 요약 + KIS 실계좌 연동 + 포트폴리오·자산 스냅샷.
 
@@ -152,7 +152,7 @@ curl http://localhost:18500/health
 
 AI 에이전트 가상 오피스 — 2D 픽셀아트 사무실에서 4명의 에이전트가 실제 작업을 수행한다.
 
-- **아키텍처**: stock-lab / music-lab / blog-lab / realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
+- **아키텍처**: stock / music-lab / blog-lab / realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
 - **FSM 상태**: `idle → working → waiting(승인 대기) → reporting → break`
 - **실시간 동기화**: WebSocket `/api/agent-office/ws` (init, agent_state, task_complete, command_result)
 - **텔레그램 연동**: 양방향 알림 + 인라인 키보드 승인
@@ -224,7 +224,7 @@ Gitea Webhook 수신 → NAS 자동 배포.
 | 공동 출현 | 15% | 번호 쌍 동시 출현 빈도 |
 | 다양성 | 10% | 연속번호·범위·구간 커버리지 |
 
-### LLM 요약 provider 추상화 (stock-lab)
+### LLM 요약 provider 추상화 (stock)
 
 `ai_summarizer.py`는 provider 분리 구조. `summarize_news(articles)` 시그니처는 provider와 무관하게 고정.
 
@@ -232,7 +232,7 @@ Gitea Webhook 수신 → NAS 자동 배포.
 - `_summarize_with_ollama`: Ollama `/api/generate` (타임아웃 180s, qwen3:14b 첫 로드 대응)
 - 실패 시 `LLMError` (구 `OllamaError` alias 유지)
 
-### 총 자산 스냅샷 (stock-lab)
+### 총 자산 스냅샷 (stock)
 
 평일 15:40 자동 실행 → `holidays.json`으로 공휴일 스킵 → 포트폴리오 현재가 조회 + 예수금 합계 → `asset_snapshots` upsert (date UNIQUE).
 
@@ -266,7 +266,7 @@ git push → Gitea → X-Gitea-Signature (HMAC SHA256)
 | DB | 소유 서비스 | 주요 테이블 |
 |----|------------|-----------|
 | `lotto.db` | lotto-backend | draws, recommendations, simulation_runs/candidates, best_picks, purchase_history, strategy_performance/weights, weekly_reports, lotto_briefings, todos, blog_posts |
-| `stock.db` | stock-lab | articles, portfolio, broker_cash, asset_snapshots, sell_history |
+| `stock.db` | stock | articles, portfolio, broker_cash, asset_snapshots, sell_history |
 | `music.db` | music-lab | music_tasks, music_library (provider, lyrics, image_url, suno_id, file_hash, cover_images, wav_url, video_url, stem_urls) |
 | `blog_marketing.db` | blog-lab | keyword_analyses, blog_posts, brand_links, commissions, generation_tasks, prompt_templates |
 | `realestate.db` | realestate-lab | announcements, announcement_models, user_profile, match_results, collect_log |
@@ -292,7 +292,7 @@ PGID=1000
 WINDOWS_AI_SERVER_URL=http://192.168.45.59:8000
 WEBHOOK_SECRET=your_secret_here
 
-# LLM (stock-lab, blog-lab, agent-office 공통)
+# LLM (stock, blog-lab, agent-office 공통)
 ANTHROPIC_API_KEY=sk-ant-...
 ANTHROPIC_MODEL=claude-haiku-4-5-20251001
 LLM_PROVIDER=claude              # claude | ollama
@@ -315,7 +315,7 @@ DATA_GO_KR_API_KEY=
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
 TELEGRAM_WEBHOOK_URL=
-STOCK_LAB_URL=http://stock-lab:8000
+STOCK_URL=http://stock:8000
 MUSIC_LAB_URL=http://music-lab:8000
 BLOG_LAB_URL=http://blog-lab:8000
 REALESTATE_LAB_URL=http://realestate-lab:8000
@@ -343,7 +343,7 @@ REALESTATE_LAB_URL=http://realestate-lab:8000
 - **라우트 순서** — `DELETE /api/todos/done`은 `/api/todos/{id}` 보다 먼저 등록 필수 (FastAPI prefix 매칭)
 - **캐시 전략** — `index.html`: no-store / `assets/`: 1년 immutable
 - **PUID/PGID** — travel-proxy는 NAS 파일 권한을 위해 환경변수 주입 필수
-- **공휴일 목록** — `stock-lab/app/holidays.json` 매년 수동 갱신 (KRX 기준)
+- **공휴일 목록** — `stock/app/holidays.json` 매년 수동 갱신 (KRX 기준)
 - **Windows AI 서버 IP** — `192.168.45.59` 공유기 DHCP 고정 예약. Synology Tailscale은 userspace 모드라 TCP 불가 → 로컬 IP 사용
 - **Suno CDN** — `cdn1.suno.ai` URL은 임시 만료 → 생성 즉시 로컬 다운로드 필수
 - **LLM provider 롤백** — Claude API 장애 시 `.env`의 `LLM_PROVIDER=ollama`로 전환 후 `docker compose up -d`

STATUS.md

@@ -12,7 +12,7 @@
 | 서비스 | 포트 | 상태 | 핵심 기능 |
 |--------|------|------|-----------|
 | `lotto-backend` | 18000 | ✅ | 로또 추천·통계·리포트·구매내역 + 블로그·투두 |
-| `stock-lab` | 18500 | ✅ | 주식 뉴스·지수·트레이딩·포트폴리오·자산 스냅샷 |
+| `stock` | 18500 | ✅ | 주식 뉴스·지수·트레이딩·포트폴리오·자산 스냅샷 |
 | `music-lab` | 18600 | ✅ | Suno + MusicGen + YouTube 수익화 + 컴파일 |
 | `blog-lab` | 18700 | ✅ | 블로그 마케팅 수익화 파이프라인 |
 | `realestate-lab` | 18800 | ✅ | 청약 수집·5티어 매칭·매칭 알림 |

agent-office/app/agents/__init__.py

@@ -1,6 +1,6 @@
 from .stock import StockAgent
 from .music import MusicAgent
-from .blog import BlogAgent
+from .insta import InstaAgent
 from .realestate import RealestateAgent
 from .lotto import LottoAgent
 from .youtube import YouTubeResearchAgent
@@ -11,7 +11,7 @@ AGENT_REGISTRY = {}
 def init_agents():
     AGENT_REGISTRY["stock"] = StockAgent()
     AGENT_REGISTRY["music"] = MusicAgent()
-    AGENT_REGISTRY["blog"] = BlogAgent()
+    AGENT_REGISTRY["insta"] = InstaAgent()
     AGENT_REGISTRY["realestate"] = RealestateAgent()
     AGENT_REGISTRY["lotto"] = LottoAgent()
     AGENT_REGISTRY["youtube"] = YouTubeResearchAgent()

agent-office/app/agents/blog.py

@@ -1,192 +0,0 @@
-import asyncio
-from typing import Optional
-
-from .base import BaseAgent
-from ..db import (
-    create_task, update_task_status, approve_task, reject_task,
-    get_task, get_agent_config, add_log,
-)
-from .. import service_proxy
-from .. import telegram_bot
-
-
-DEFAULT_TREND_KEYWORDS = [
-    "다이어트 식단", "재택근무 꿀템", "캠핑 장비 추천",
-    "홈트레이닝", "제주도 여행", "에어프라이어 레시피",
-]
-
-
-class BlogAgent(BaseAgent):
-    """블로그 마케팅 에이전트.
-
-    매일 10:00 자동 실행: 키워드 1개 리서치 → 글 생성 → 마케터 → 평가자
-    → 평가 점수와 요약을 텔레그램 승인 요청으로 푸시
-    → 승인 시 `published` 상태로 전환, 거절 시 재생성
-    """
-
-    agent_id = "blog"
-    display_name = "블로그 마케터"
-
-    async def on_schedule(self) -> None:
-        if self.state not in ("idle", "break"):
-            return
-
-        config = get_agent_config(self.agent_id) or {}
-        custom = config.get("custom_config", {}) or {}
-        keywords = custom.get("trend_keywords") or DEFAULT_TREND_KEYWORDS
-        if not keywords:
-            return
-
-        import random
-        keyword = random.choice(keywords)
-
-        task_id = create_task(
-            self.agent_id,
-            "auto_blog_pipeline",
-            {"keyword": keyword},
-            requires_approval=True,
-        )
-        await self.transition("working", f"리서치: {keyword}", task_id)
-        asyncio.create_task(self._run_pipeline(task_id, keyword))
-
-    async def _await_task(self, step: str, task_id: str, timeout_sec: int = 240) -> Optional[int]:
-        """blog-lab BackgroundTask 완료 폴링. 완료 시 result_id 반환."""
-        attempts = max(1, timeout_sec // 5)
-        for _ in range(attempts):
-            await asyncio.sleep(5)
-            status = await service_proxy.blog_task_status(task_id)
-            s = status.get("status")
-            if s == "succeeded":
-                return status.get("result_id")
-            if s == "failed":
-                raise Exception(f"{step} failed: {status.get('error')}")
-        raise Exception(f"{step} timeout ({timeout_sec}s 내 완료되지 않음)")
-
-    async def _run_pipeline(self, task_id: str, keyword: str) -> None:
-        try:
-            # 1) 리서치
-            research = await service_proxy.blog_research(keyword)
-            keyword_id = await self._await_task("research", research.get("task_id"), 180)
-            if not keyword_id:
-                raise Exception("research succeeded but result_id missing")
-
-            # 2) 작가 단계 (비동기)
-            await self.transition("working", f"글 생성: {keyword}", task_id)
-            gen = await service_proxy.blog_generate(keyword_id)
-            post_id = await self._await_task("generate", gen.get("task_id"), 300)
-            if not post_id:
-                raise Exception("generate succeeded but post_id missing")
-
-            # 3) 마케터 단계 (비동기)
-            await self.transition("working", "링크 삽입 중", task_id)
-            mkt = await service_proxy.blog_market(post_id)
-            await self._await_task("market", mkt.get("task_id"), 180)
-
-            # 4) 평가자 단계 (비동기)
-            await self.transition("working", "품질 리뷰 중", task_id)
-            rev = await service_proxy.blog_review(post_id)
-            await self._await_task("review", rev.get("task_id"), 180)
-
-            post_after = await service_proxy.blog_get_post(post_id)
-            score = post_after.get("review_score")
-            passed = (score or 0) >= 42
-
-            title = post_after.get("title", "(제목 없음)")
-            excerpt = (post_after.get("body") or "")[:300]
-
-            update_task_status(task_id, "pending", {
-                "keyword": keyword,
-                "post_id": post_id,
-                "score": score,
-                "passed": passed,
-                "title": title,
-            })
-
-            await self.transition("waiting", f"승인 대기 · {score}/60", task_id)
-
-            detail = (
-                f"키워드: {keyword}\n"
-                f"제목: {title}\n"
-                f"평가 점수: {score}/60 ({'통과' if passed else '미통과'})\n\n"
-                f"{excerpt}..."
-            )
-            await telegram_bot.send_approval_request(
-                self.agent_id, task_id,
-                "✍️ [블로그 에이전트] 발행 승인 요청", detail,
-            )
-
-        except Exception as e:
-            add_log(self.agent_id, f"Blog pipeline failed: {e}", "error", task_id)
-            update_task_status(task_id, "failed", {"error": str(e), "keyword": keyword})
-            await self.transition("idle", f"오류: {e}")
-            await telegram_bot.send_task_result(
-                self.agent_id, "✍️ [블로그 에이전트] 파이프라인 실패",
-                f"키워드: {keyword}\n오류: {e}",
-            )
-
-    async def on_command(self, command: str, params: dict) -> dict:
-        if command == "research":
-            keyword = (params.get("keyword") or "").strip()
-            if not keyword:
-                return {"ok": False, "message": "keyword 필수"}
-            task_id = create_task(
-                self.agent_id, "auto_blog_pipeline",
-                {"keyword": keyword}, requires_approval=True,
-            )
-            await self.transition("working", f"리서치: {keyword}", task_id)
-            asyncio.create_task(self._run_pipeline(task_id, keyword))
-            return {"ok": True, "task_id": task_id, "message": f"파이프라인 시작: {keyword}"}
-
-        if command == "add_trend_keyword":
-            keyword = (params.get("keyword") or "").strip()
-            if not keyword:
-                return {"ok": False, "message": "keyword 필수"}
-            config = get_agent_config(self.agent_id) or {}
-            custom = config.get("custom_config", {}) or {}
-            kws = list(custom.get("trend_keywords") or [])
-            if keyword not in kws:
-                kws.append(keyword)
-            from ..db import update_agent_config
-            update_agent_config(self.agent_id, custom_config={**custom, "trend_keywords": kws})
-            return {"ok": True, "keywords": kws}
-
-        if command == "list_trend_keywords":
-            config = get_agent_config(self.agent_id) or {}
-            custom = config.get("custom_config", {}) or {}
-            return {"ok": True, "keywords": custom.get("trend_keywords") or DEFAULT_TREND_KEYWORDS}
-
-        return {"ok": False, "message": f"Unknown command: {command}"}
-
-    async def on_approval(self, task_id: str, approved: bool, feedback: str = "") -> None:
-        task = get_task(task_id)
-        if not task:
-            return
-        result = task.get("result_data") or {}
-        post_id = result.get("post_id")
-
-        if not approved:
-            reject_task(task_id)
-            await self.transition("idle", "발행 거절됨")
-            await telegram_bot.send_task_result(
-                self.agent_id, "✍️ [블로그 에이전트] 발행 취소",
-                f"키워드: {result.get('keyword', '')}\n사용자가 거절했습니다.",
-            )
-            return
-
-        approve_task(task_id, via="telegram")
-        await self.transition("reporting", "발행 중...", task_id)
-
-        try:
-            if post_id:
-                await service_proxy.blog_publish(int(post_id))
-            update_task_status(task_id, "succeeded", {**result, "published": True})
-            await telegram_bot.send_task_result(
-                self.agent_id, "✍️ [블로그 에이전트] 발행 완료",
-                f"키워드: {result.get('keyword', '')}\n제목: {result.get('title', '')}\n"
-                f"점수: {result.get('score')}/60",
-            )
-            await self.transition("idle", "발행 완료")
-        except Exception as e:
-            add_log(self.agent_id, f"Blog publish failed: {e}", "error", task_id)
-            update_task_status(task_id, "failed", {**result, "publish_error": str(e)})
-            await self.transition("idle", f"발행 오류: {e}")

agent-office/app/agents/insta.py

@@ -0,0 +1,170 @@
+"""인스타 카드 에이전트 — 매일 09:30 뉴스 수집·키워드 추출 → 텔레그램 후보 푸시.
+사용자가 키워드 버튼을 누르면 카드 슬레이트 생성 + 10장 미디어 그룹 발송."""
+
+import asyncio
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .base import BaseAgent
+from ..db import (
+    create_task, update_task_status, add_log, get_agent_config,
+)
+from ..config import TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
+from .. import service_proxy
+from ..telegram import messaging
+
+logger = logging.getLogger(__name__)
+
+
+async def _send_media_group(media: List[Dict[str, Any]], caption: str = "") -> Dict[str, Any]:
+    """텔레그램 sendMediaGroup. media는 InputMediaPhoto dicts.
+    각 항목에는 임시 키 '_bytes'로 PNG 바이트가 담겨 있어 attach:// 형식으로 multipart 업로드."""
+    if not TELEGRAM_BOT_TOKEN:
+        return {"ok": False, "reason": "TELEGRAM_BOT_TOKEN missing"}
+    url = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMediaGroup"
+    files: Dict[str, tuple] = {}
+    for i, m in enumerate(media):
+        attach_key = f"photo{i+1}"
+        files[attach_key] = (f"{i+1}.png", m["_bytes"], "image/png")
+        m["media"] = f"attach://{attach_key}"
+        m.pop("_bytes", None)
+    if caption and media:
+        media[0]["caption"] = caption[:1024]
+    payload = {"chat_id": TELEGRAM_CHAT_ID, "media": json.dumps(media, ensure_ascii=False)}
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.post(url, data=payload, files=files)
+    return resp.json()
+
+
+class InstaAgent(BaseAgent):
+    agent_id = "insta"
+    display_name = "인스타 큐레이터"
+
+    async def on_schedule(self) -> None:
+        """09:30 매일: 뉴스 수집 → 키워드 추출 → 텔레그램 후보 푸시.
+        custom_config.auto_select=True면 카테고리당 1위 키워드 자동 슬레이트 생성."""
+        if self.state not in ("idle", "break"):
+            return
+        config = get_agent_config(self.agent_id) or {}
+        custom = config.get("custom_config", {}) or {}
+        auto_select = bool(custom.get("auto_select", False))
+
+        task_id = create_task(self.agent_id, "insta_daily", {"auto_select": auto_select},
+                              requires_approval=False)
+        await self.transition("working", "뉴스 수집·키워드 추출", task_id)
+        try:
+            prefs = await service_proxy.insta_get_preferences()
+            add_log(self.agent_id, f"insta preferences: {prefs}", "info", task_id)
+            await self._run_collect_and_extract()
+            kws = await service_proxy.insta_list_keywords(used=False)
+            if auto_select:
+                await self._auto_render(kws)
+            else:
+                await self._push_keyword_candidates(kws)
+            update_task_status(task_id, "succeeded", {"keywords": len(kws)})
+            await self.transition("idle", "후보 푸시 완료")
+        except Exception as e:
+            add_log(self.agent_id, f"insta daily failed: {e}", "error", task_id)
+            update_task_status(task_id, "failed", {"error": str(e)})
+            await self.transition("idle", f"오류: {e}")
+
+    async def _run_collect_and_extract(self) -> None:
+        col = await service_proxy.insta_collect()
+        await self._wait_task(col["task_id"], step="collect", timeout_sec=300)
+        ext = await service_proxy.insta_extract()
+        await self._wait_task(ext["task_id"], step="extract", timeout_sec=300)
+
+    async def _wait_task(self, task_id: str, step: str, timeout_sec: int = 300) -> Dict[str, Any]:
+        attempts = max(1, timeout_sec // 5)
+        for _ in range(attempts):
+            await asyncio.sleep(5)
+            st = await service_proxy.insta_task_status(task_id)
+            if st["status"] == "succeeded":
+                return st
+            if st["status"] == "failed":
+                raise RuntimeError(f"{step} failed: {st.get('error')}")
+        raise TimeoutError(f"{step} timeout {timeout_sec}s")
+
+    async def _push_keyword_candidates(self, keywords: List[Dict[str, Any]]) -> None:
+        by_cat: Dict[str, List[Dict[str, Any]]] = {}
+        for k in keywords:
+            by_cat.setdefault(k["category"], []).append(k)
+        if not by_cat:
+            await messaging.send_raw("📰 [인스타 큐레이터] 오늘은 추천할 키워드가 없습니다.")
+            return
+        rows: List[List[Dict[str, Any]]] = []
+        text_lines = ["📰 <b>[인스타 큐레이터]</b> 오늘의 키워드 후보"]
+        for cat, items in by_cat.items():
+            text_lines.append(f"\n<b>{cat}</b>")
+            for k in items[:5]:
+                text_lines.append(f"  · {k['keyword']} (score {k['score']:.2f})")
+                rows.append([{
+                    "text": f"🎴 {k['keyword']}",
+                    "callback_data": f"render_{k['id']}",
+                }])
+        await messaging.send_raw("\n".join(text_lines), reply_markup={"inline_keyboard": rows})
+
+    async def _auto_render(self, keywords: List[Dict[str, Any]]) -> None:
+        by_cat: Dict[str, Dict[str, Any]] = {}
+        for k in keywords:
+            cat = k["category"]
+            if cat not in by_cat or k["score"] > by_cat[cat]["score"]:
+                by_cat[cat] = k
+        for kw in by_cat.values():
+            await self._render_and_push(kw["id"])
+
+    async def _render_and_push(self, keyword_id: int) -> None:
+        kw = await service_proxy.insta_get_keyword(keyword_id)
+        if not kw:
+            await messaging.send_raw(f"⚠️ 키워드 {keyword_id} 없음")
+            return
+        await messaging.send_raw(f"🎨 카드 생성 중: <b>{kw['keyword']}</b>")
+        created = await service_proxy.insta_create_slate(
+            keyword=kw["keyword"], category=kw["category"], keyword_id=kw["id"],
+        )
+        st = await self._wait_task(created["task_id"], step="slate", timeout_sec=600)
+        slate_id = st["result_id"]
+        slate = await service_proxy.insta_get_slate(slate_id)
+        media = []
+        for a in slate["assets"][:10]:
+            data = await service_proxy.insta_get_asset_bytes(slate_id, a["page_index"])
+            media.append({"type": "photo", "_bytes": data})
+        caption = slate.get("suggested_caption", "")
+        hashtags = " ".join(slate.get("hashtags", []) or [])
+        full_caption = f"{caption}\n\n{hashtags}".strip()
+        await _send_media_group(media, caption=full_caption)
+
+    async def on_command(self, command: str, params: dict) -> dict:
+        if command == "extract":
+            await self._run_collect_and_extract()
+            kws = await service_proxy.insta_list_keywords(used=False)
+            await self._push_keyword_candidates(kws)
+            return {"ok": True, "count": len(kws)}
+        if command == "render":
+            kid = int(params.get("keyword_id") or 0)
+            if not kid:
+                return {"ok": False, "message": "keyword_id 필수"}
+            await self._render_and_push(kid)
+            return {"ok": True}
+        if command == "collect_trends":
+            await messaging.send_raw("🌐 외부 트렌드 수집 시작")
+            created = await service_proxy.insta_collect_trends()
+            st = await self._wait_task(created["task_id"], step="trends_collect", timeout_sec=300)
+            await messaging.send_raw(f"✅ 트렌드 수집 완료: {st.get('message', '')}")
+            return {"ok": True, "result": st}
+        return {"ok": False, "message": f"Unknown command: {command}"}
+
+    async def on_callback(self, action: str, params: dict) -> dict:
+        if action == "render":
+            kid = int(params.get("keyword_id") or 0)
+            if not kid:
+                return {"ok": False}
+            await self._render_and_push(kid)
+            return {"ok": True}
+        return {"ok": False}
+
+    async def on_approval(self, task_id: str, approved: bool, feedback: str = "") -> None:
+        return

agent-office/app/agents/lotto.py

@@ -27,11 +27,21 @@ class LottoAgent(BaseAgent):
         await self.transition("working", "후보 수집 및 AI 큐레이션 중...", task_id)
         try:
             result = await curate_weekly(source=source)
-            update_task_status(task_id, "succeeded", result_data=result)
+            update_task_status(task_id, "succeeded", result_data={
+                k: v for k, v in result.items() if k != "payload"
+            })
             await self.transition("reporting", f"#{result['draw_no']} 브리핑 저장 완료")
             add_log(self.agent_id, f"큐레이션 완료: #{result['draw_no']} conf={result['confidence']}", task_id=task_id)
+
+            # 텔레그램 헤드라인 푸시 (실패해도 큐레이션은 성공으로 마감)
+            try:
+                from ..notifiers.telegram_lotto import send_curator_briefing
+                await send_curator_briefing(result["payload"])
+            except Exception as e:
+                add_log(self.agent_id, f"텔레그램 알림 실패: {e}", level="warning", task_id=task_id)
+
             await self.transition("idle", "대기 중")
-            return {"ok": True, **result}
+            return {"ok": True, **{k: v for k, v in result.items() if k != "payload"}}
         except CuratorError as e:
             update_task_status(task_id, "failed", result_data={"error": str(e)})
             add_log(self.agent_id, f"큐레이션 실패: {e}", level="error", task_id=task_id)

agent-office/app/agents/stock.py

@@ -51,7 +51,7 @@ class StockAgent(BaseAgent):
         await self.transition("working", "최신 뉴스 수집 중...", task_id)
 
         try:
-            # stock-lab cron(매일 8:00)이 7:30 브리핑보다 늦게 돌아 어제 뉴스가
+            # stock cron(매일 8:00)이 7:30 브리핑보다 늦게 돌아 어제 뉴스가
             # 요약되던 문제 방지 — 요약 직전에 동기 스크랩으로 DB를 갱신한다.
             try:
                 await service_proxy.scrape_stock_news()
@@ -60,7 +60,7 @@ class StockAgent(BaseAgent):
 
             await self.transition("working", "AI 뉴스 요약 생성 중...")
 
-            # AI 요약 호출 (LLM 처리는 stock-lab이 담당)
+            # AI 요약 호출 (LLM 처리는 stock이 담당)
             result = await service_proxy.summarize_stock_news(limit=15)
 
             await self.transition("reporting", "뉴스 요약 전송 중...")
@@ -119,7 +119,232 @@ class StockAgent(BaseAgent):
             update_task_status(task_id, "failed", {"error": str(e)})
             await self.transition("idle", f"오류: {e}")
 
+    async def on_screener_schedule(self) -> None:
+        """KRX 강세주 스크리너 자동 잡 (평일 16:30 KST).
+
+        흐름:
+          1) snapshot/refresh — 일봉 갱신 (실패해도 진행, 경고 로그)
+          2) screener/run mode='auto' — 실행 + 결과 영구화 + telegram_payload 응답
+          3) status=='skipped_holiday' → 종료 (텔레그램 미발신)
+          4) status=='success' → telegram_payload.text 를 parse_mode 그대로 전송
+          5) 예외/실패 → 운영자에게 별도 텔레그램 알림 (HTML)
+        """
+        if self.state not in ("idle", "break"):
+            return
+
+        task_id = create_task(self.agent_id, "screener_run", {"mode": "auto"})
+        await self.transition("working", "스크리너 스냅샷 갱신 중...", task_id)
+
+        try:
+            # 1) 스냅샷 갱신 — 실패해도 기존 일봉 데이터로 진행
+            try:
+                snap = await service_proxy.refresh_screener_snapshot()
+                add_log(
+                    self.agent_id,
+                    f"snapshot refreshed: status={snap.get('status', '?')}",
+                    "info", task_id,
+                )
+            except Exception as e:
+                add_log(
+                    self.agent_id,
+                    f"스냅샷 갱신 실패 (기존 데이터로 진행): {e}",
+                    "warning", task_id,
+                )
+
+            await self.transition("working", "스크리너 실행 중...")
+
+            # 2) 스크리너 실행
+            body = await service_proxy.run_stock_screener(mode="auto")
+            status = body.get("status")
+            asof = body.get("asof")
+
+            # 3) 공휴일 — 종료
+            if status == "skipped_holiday":
+                update_task_status(task_id, "succeeded", {
+                    "status": status,
+                    "asof": asof,
+                    "telegram_sent": False,
+                })
+                add_log(self.agent_id, f"스크리너 건너뜀 (휴일): {asof}", "info", task_id)
+                await self.transition("idle", "휴일 — 스크리너 건너뜀")
+                return
+
+            # 4) 성공 → 텔레그램 전송
+            if status == "success":
+                payload = body.get("telegram_payload") or {}
+                text = payload.get("text") or ""
+                parse_mode = payload.get("parse_mode", "MarkdownV2")
+
+                if not text:
+                    raise RuntimeError("telegram_payload.text 누락")
+
+                await self.transition("reporting", "스크리너 결과 전송 중...")
+
+                from ..telegram.messaging import send_raw
+                tg = await send_raw(text, parse_mode=parse_mode)
+
+                update_task_status(task_id, "succeeded", {
+                    "status": status,
+                    "asof": asof,
+                    "run_id": body.get("run_id"),
+                    "survivors_count": body.get("survivors_count"),
+                    "telegram_sent": tg.get("ok", False),
+                    "telegram_message_id": tg.get("message_id"),
+                })
+
+                if not tg.get("ok"):
+                    desc = tg.get("description") or "unknown"
+                    code = tg.get("error_code")
+                    add_log(
+                        self.agent_id,
+                        f"Screener telegram send failed: [{code}] {desc}",
+                        "warning", task_id,
+                    )
+                    if self._ws_manager:
+                        await self._ws_manager.send_notification(
+                            self.agent_id, "telegram_failed", task_id,
+                            "스크리너 텔레그램 전송 실패",
+                        )
+
+                await self.transition("idle", "스크리너 완료")
+                return
+
+            # 5) 기타 status — failed 취급
+            raise RuntimeError(f"unexpected screener status: {status}")
+
+        except Exception as e:
+            err_msg = str(e)
+            add_log(self.agent_id, f"Screener job failed: {err_msg}", "error", task_id)
+            update_task_status(task_id, "failed", {"error": err_msg})
+
+            # 운영자 알림 — 기본 HTML parse_mode 사용
+            try:
+                from ..telegram.messaging import send_raw
+                await send_raw(
+                    f"⚠️ <b>KRX 스크리너 실패</b>\n"
+                    f"<code>{html.escape(err_msg)[:500]}</code>"
+                )
+            except Exception as notify_err:
+                add_log(
+                    self.agent_id,
+                    f"operator notify failed: {notify_err}",
+                    "warning", task_id,
+                )
+
+            await self.transition("idle", f"스크리너 오류: {err_msg[:80]}")
+
+    async def on_ai_news_schedule(self) -> None:
+        """AI 뉴스 sentiment 분석 자동 잡 (평일 08:00 KST).
+
+        흐름:
+          1) stock /snapshot/refresh-news-sentiment 호출
+          2) status='skipped_weekend'/'skipped_holiday' → 종료 (텔레그램 미발신)
+          3) updated=0 → 운영자 알림 (HTML)
+          4) failures > 30% → 경고 알림 후 메인 메시지 발송
+          5) 정상 → Top 5 호재/악재 메시지 발송 (MarkdownV2)
+        """
+        if self.state not in ("idle", "break"):
+            return
+
+        task_id = create_task(self.agent_id, "ai_news_sentiment", {})
+        await self.transition("working", "AI 뉴스 분석 중...", task_id)
+
+        try:
+            result = await service_proxy.refresh_ai_news_sentiment()
+        except Exception as e:
+            err_msg = str(e)
+            add_log(self.agent_id, f"AI 뉴스 분석 실패: {err_msg}", "error", task_id)
+            update_task_status(task_id, "failed", {"error": err_msg})
+            try:
+                from ..telegram.messaging import send_raw
+                await send_raw(
+                    f"⚠️ <b>AI 뉴스 분석 실패</b>\n"
+                    f"<code>{html.escape(err_msg)[:500]}</code>"
+                )
+            except Exception as notify_err:
+                add_log(
+                    self.agent_id,
+                    f"operator notify failed: {notify_err}",
+                    "warning", task_id,
+                )
+            await self.transition("idle", f"AI 뉴스 오류: {err_msg[:80]}")
+            return
+
+        status = result.get("status")
+        if status in ("skipped_weekend", "skipped_holiday"):
+            update_task_status(task_id, "succeeded", {"status": status})
+            add_log(self.agent_id, f"AI 뉴스 건너뜀: {status}", "info", task_id)
+            await self.transition("idle", "휴일/주말 — 건너뜀")
+            return
+
+        updated = int(result.get("updated", 0))
+        failures = result.get("failures", []) or []
+        if updated == 0:
+            update_task_status(task_id, "failed", {"reason": "0 tickers updated"})
+            try:
+                from ..telegram.messaging import send_raw
+                await send_raw(
+                    "⚠️ <b>AI 뉴스 분석 0종목</b>\n"
+                    "스크래핑/LLM 전체 실패 — 어제 데이터 사용"
+                )
+            except Exception:
+                pass
+            await self.transition("idle", "AI 뉴스 0건")
+            return
+
+        # 실패율 경고 (별도 알림, 본 메시지는 계속 발송)
+        failure_rate = len(failures) / max(1, updated + len(failures))
+        if failure_rate > 0.3:
+            try:
+                from ..telegram.messaging import send_raw
+                await send_raw(
+                    f"⚠️ <b>AI 뉴스 실패율 {failure_rate:.0%}</b>\n"
+                    f"updated={updated}, failures={len(failures)}"
+                )
+            except Exception:
+                pass
+
+        # 정상 — Top 5 메시지 (stock이 빌드해서 응답에 telegram_text 동봉)
+        text = result.get("telegram_text") or ""
+        if not text:
+            add_log(self.agent_id, "telegram_text 누락 — stock 응답 결함", "error", task_id)
+            update_task_status(task_id, "failed", {"error": "telegram_text 누락"})
+            await self.transition("idle", "AI 뉴스 응답 결함")
+            return
+
+        await self.transition("reporting", "AI 뉴스 알림 전송 중...")
+        from ..telegram.messaging import send_raw
+        tg = await send_raw(text, parse_mode="MarkdownV2")
+
+        update_task_status(task_id, "succeeded", {
+            "asof": result["asof"],
+            "updated": updated,
+            "failures": len(failures),
+            "tokens_input": int(result.get("tokens_input", 0)),
+            "tokens_output": int(result.get("tokens_output", 0)),
+            "telegram_sent": tg.get("ok", False),
+        })
+
+        if not tg.get("ok"):
+            desc = tg.get("description") or "unknown"
+            code = tg.get("error_code")
+            add_log(
+                self.agent_id,
+                f"AI news telegram send failed: [{code}] {desc}",
+                "warning", task_id,
+            )
+
+        await self.transition("idle", "AI 뉴스 완료")
+
     async def on_command(self, command: str, params: dict) -> dict:
+        if command == "run_screener":
+            await self.on_screener_schedule()
+            return {"ok": True, "message": "스크리너 실행 트리거 완료"}
+
+        if command == "run_ai_news":
+            await self.on_ai_news_schedule()
+            return {"ok": True, "message": "AI 뉴스 분석 트리거 완료"}
+
         if command == "test_telegram":
             from ..telegram import send_agent_message
             result = await send_agent_message(

agent-office/app/agents/youtube_publisher.py

@@ -25,7 +25,7 @@ class YoutubePublisherAgent(BaseAgent):
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        self._notified_state_per_pipeline: dict[int, str] = {}
+        self._notified_state_per_pipeline: dict[int, tuple] = {}
 
     async def poll_state_changes(self) -> None:
         """주기적으로 호출되어 *_pending 신규 진입 시 텔레그램 발송."""
@@ -40,9 +40,13 @@ class YoutubePublisherAgent(BaseAgent):
             pid = p.get("id")
             if pid is None:
                 continue
-            if state in _STEP_TITLES and self._notified_state_per_pipeline.get(pid) != state:
-                await self._notify_step(p)
-                self._notified_state_per_pipeline[pid] = state
+            if state in _STEP_TITLES:
+                _, step = _STEP_TITLES[state]
+                fb_count = (p.get("feedback_count_per_step") or {}).get(step, 0)
+                key = (state, fb_count)
+                if self._notified_state_per_pipeline.get(pid) != key:
+                    await self._notify_step(p)
+                    self._notified_state_per_pipeline[pid] = key
 
     async def _notify_step(self, pipeline: dict) -> None:
         state = pipeline["state"]

agent-office/app/config.py

@@ -1,9 +1,9 @@
 import os
 
 # Service URLs (Docker internal network)
-STOCK_LAB_URL = os.getenv("STOCK_LAB_URL", "http://localhost:18500")
+STOCK_URL = os.getenv("STOCK_URL", "http://localhost:18500")
 MUSIC_LAB_URL = os.getenv("MUSIC_LAB_URL", "http://localhost:18600")
-BLOG_LAB_URL = os.getenv("BLOG_LAB_URL", "http://localhost:18700")
+INSTA_LAB_URL = os.getenv("INSTA_LAB_URL", "http://localhost:18700")
 REALESTATE_LAB_URL = os.getenv("REALESTATE_LAB_URL", "http://localhost:18800")
 
 # Telegram

agent-office/app/curator/pipeline.py

@@ -9,6 +9,7 @@ from ..config import ANTHROPIC_API_KEY, LOTTO_CURATOR_MODEL
 from .. import service_proxy
 from .prompt import SYSTEM_PROMPT, build_user_message
 from .schema import validate_response
+from .retrospective import build_retrospective
 
 
 API_URL = "https://api.anthropic.com/v1/messages"
@@ -36,12 +37,12 @@ async def _call_claude(user_text: str, feedback: str = "") -> tuple[dict, dict]:
         user_text = f"이전 응답이 다음 이유로 거절됨: {feedback}\n올바른 스키마로 다시 응답.\n\n{user_text}"
     payload = {
         "model": LOTTO_CURATOR_MODEL,
-        "max_tokens": 4096,
+        "max_tokens": 8192,  # 4계층 20세트 + narrative + retrospective 수용
         "system": system_blocks,
         "messages": [{"role": "user", "content": [{"type": "text", "text": user_text}]}],
     }
     started = time.monotonic()
-    async with httpx.AsyncClient(timeout=120) as client:
+    async with httpx.AsyncClient(timeout=180) as client:  # 큰 응답 → 시간 여유
         r = await client.post(API_URL, headers=headers, json=payload)
         r.raise_for_status()
         resp = r.json()
@@ -68,16 +69,19 @@ async def _call_claude(user_text: str, feedback: str = "") -> tuple[dict, dict]:
 
 
 async def curate_weekly(source: str = "auto") -> Dict[str, Any]:
-    cand_resp = await service_proxy.lotto_candidates(n=20)
+    cand_resp = await service_proxy.lotto_candidates(n=30)  # ← 30 으로 확장
     draw_no = cand_resp["draw_no"]
     candidates = cand_resp["candidates"]
     context = await service_proxy.lotto_context()
 
+    retrospective = await build_retrospective(draw_no)
+
     user_text = build_user_message(draw_no, candidates, {
         "hot_numbers": context.get("hot_numbers", []),
         "cold_numbers": context.get("cold_numbers", []),
         "last_draw_summary": context.get("last_draw_summary", ""),
         "my_recent_performance": context.get("my_recent_performance", []),
+        "retrospective": retrospective,
     })
 
     candidate_numbers = [c["numbers"] for c in candidates]
@@ -101,8 +105,14 @@ async def curate_weekly(source: str = "auto") -> Dict[str, Any]:
 
     payload = {
         "draw_no": draw_no,
-        "picks": [p.model_dump() for p in validated.picks],
+        "picks": {
+            "core":     [p.model_dump() for p in validated.core_picks],
+            "bonus":    [p.model_dump() for p in validated.bonus_picks],
+            "extended": [p.model_dump() for p in validated.extended_picks],
+            "pool":     [p.model_dump() for p in validated.pool_picks],
+        },
         "narrative": validated.narrative.model_dump(),
+        "tier_rationale": validated.tier_rationale.model_dump(),
         "confidence": validated.confidence,
         "model": LOTTO_CURATOR_MODEL,
         "tokens_input": usage_total["input"],
@@ -118,4 +128,5 @@ async def curate_weekly(source: str = "auto") -> Dict[str, Any]:
         "draw_no": draw_no,
         "confidence": validated.confidence,
         "tokens": {"input": usage_total["input"], "output": usage_total["output"]},
+        "payload": payload,  # 텔레그램 알림용
     }

agent-office/app/curator/prompt.py

@@ -2,31 +2,49 @@
 import json
 
 
-SYSTEM_PROMPT = """당신은 로또 번호 큐레이터입니다. 주어진 후보 20세트 중 5세트를 다음 규칙으로 선별합니다.
+SYSTEM_PROMPT = """당신은 로또 번호 큐레이터입니다.
+주어진 후보 30세트 중 4계층(코어 5, 보너스 5, 확장 5, 풀 5) 총 20세트를 선별합니다.
 
-선별 규칙:
-- 5세트의 리스크 분포는 안정 2 · 균형 2 · 공격 1 을 권장(유연 ±1).
-- 홀짝 비율, 저/고 구간, 연속번호 포함 여부가 세트끼리 겹치지 않도록 다양성을 확보.
-- hot_number_count=0 이고 cold_number_count=0 인 '중립형' 세트를 최소 1개 포함.
-- 후보에 없는 번호 조합은 절대 사용 금지. numbers 필드는 반드시 candidates 중 하나와 정확히 일치해야 함.
-- 각 세트 reason은 한국어 40자 이내 한 줄. 해당 세트의 features 값과 context 값만 근거로.
+계층별 큐레이션 규칙:
+- core_picks (5):     안정 2 / 균형 2 / 공격 1. 그 주 주축. 홀짝·저고·구간 분포가 세트끼리 겹치지 않게.
+- bonus_picks (5):    코어 분배의 공백을 메우는 5세트. 코어가 공격 1뿐이면 보너스에 공격 +2 식.
+- extended_picks (5): 코어·보너스에 없는 시각 — 합계 극단(80↓ / 180↑) / 콜드 4주 누적 / 4주 미등장 번호 노출.
+- pool_picks (5):     이번 주 한 번도 누르지 않은 패턴 — 연속 3개 / 동일 끝자리 / 5수 균등(각 끝자리 5개씩) 등.
+- tier_rationale 의 3개 키(bonus·extended·pool)에 각각 30자 이내 한국어 사유.
+
+공통 규칙:
+- 후보에 없는 번호 조합은 절대 사용 금지. 모든 픽은 candidates 중 하나와 정확히 일치해야 함.
+- 4계층 사이에 중복 픽 금지 (총 20세트는 모두 서로 달라야 함).
+- 각 픽 reason 은 한국어 40자 이내. 해당 픽의 features 와 context 만 근거로.
+- 중립형(hot_number_count=0 이고 cold_number_count=0) 세트를 코어에 최소 1개 포함.
+
+회고 규칙:
+- context.retrospective 가 있으면 narrative.retrospective 에 한 줄(60자 이내)로 작성.
+- 회고는 큐레이터 자기 결과(curator_avg, best_tier) + 사용자 결과(user_avg, pattern_delta) 둘 다 짚을 것.
+- 이번 주 코어 분배는 회고에 근거해 조정. 조정 사유는 narrative.headline 에 한 줄로.
+  예: "지난 주 너 저번호 편향 → 보너스 고번호 보강"
+- context.retrospective 가 없으면 narrative.retrospective 는 빈 문자열.
 
 narrative 규칙:
-- headline: 한 줄, 이번 주 추첨 전망 요약.
-- summary_3lines: 정확히 3개 항목의 배열.
-- hot_cold_comment: hot/cold 번호에 대한 한 줄 논평.
-- warnings: 특별한 주의사항 없으면 빈 문자열.
+- headline:        한 줄, 이번 주 추첨 전망 + 조정 사유.
+- summary_3lines:  정확히 3개 항목.
+- hot_cold_comment: hot/cold 번호 한 줄 논평.
+- warnings:        주의사항 없으면 빈 문자열.
+- retrospective:   회고 한 줄 또는 빈 문자열.
 
 출력은 반드시 JSON 하나, 그 외 어떤 텍스트도 금지. 스키마:
 {
-  "picks": [
-    {"numbers":[int,int,int,int,int,int], "risk_tag":"안정"|"균형"|"공격", "reason": str}
-  ],
+  "core_picks":     [{"numbers":[...], "risk_tag":"안정"|"균형"|"공격", "reason": str}, ...5개],
+  "bonus_picks":    [...5개],
+  "extended_picks": [...5개],
+  "pool_picks":     [...5개],
+  "tier_rationale": {"bonus": str, "extended": str, "pool": str},
   "narrative": {
     "headline": str,
     "summary_3lines": [str, str, str],
     "hot_cold_comment": str,
-    "warnings": str
+    "warnings": str,
+    "retrospective": str
   },
   "confidence": int (0~100)
 }
@@ -36,11 +54,11 @@ narrative 규칙:
 def build_user_message(draw_no: int, candidates: list, context: dict) -> str:
     payload = {
         "draw_no": draw_no,
-        "context": context,
+        "context": context,  # hot_numbers, cold_numbers, last_draw_summary, my_recent_performance, retrospective
         "candidates": candidates,
     }
     return (
         f"이번 회차: {draw_no}\n"
-        f"아래 데이터로 5세트를 큐레이션하고 위 스키마로만 응답하세요.\n\n"
+        f"아래 데이터로 4계층 20세트를 큐레이션하고 위 스키마로만 응답하세요.\n\n"
         f"```json\n{json.dumps(payload, ensure_ascii=False)}\n```"
     )

agent-office/app/curator/retrospective.py

@@ -0,0 +1,50 @@
+"""큐레이션 직전 호출 — review 1건 + 추세 3건 → 컨텍스트 dict."""
+import json
+from typing import Optional, Dict, Any
+from .. import service_proxy
+
+
+def _detect_bias(reviews: list) -> str:
+    """3주↑ 같은 방향 패턴 편향이 유지되면 한 줄로."""
+    deltas = [r.get("pattern_delta") or "" for r in reviews if r.get("pattern_delta")]
+    if len(deltas) < 2:
+        return ""
+    # 단순 휴리스틱 — 같은 키워드("저번호" 등)가 2회 이상이면 지속 편향
+    keywords = ["저번호", "고번호", "합계", "홀짝"]
+    persistent = []
+    for kw in keywords:
+        cnt = sum(1 for d in deltas if kw in d)
+        if cnt >= max(2, len(deltas) - 1):
+            persistent.append(kw)
+    return " · ".join(persistent)
+
+
+async def build_retrospective(target_draw_no: int) -> Optional[Dict[str, Any]]:
+    """target_draw_no(이번 주) 직전 회차의 review + 그 앞 3회 추세."""
+    last = await service_proxy.lotto_review_by_draw(target_draw_no - 1)
+    if not last:
+        return None
+
+    history = await service_proxy.lotto_reviews_history(limit=4)
+    # history 는 desc 정렬 → last 와 그 이전 3건 분리
+    others = [r for r in history if r["draw_no"] < target_draw_no - 1][:3]
+    series = [last] + others
+
+    cur_avgs = [r["curator_avg_match"] for r in series if r.get("curator_avg_match") is not None]
+    usr_avgs = [r["user_avg_match"]    for r in series if r.get("user_avg_match")    is not None]
+
+    return {
+        "last_draw": {
+            "draw_no": last["draw_no"],
+            "curator_avg": last.get("curator_avg_match"),
+            "curator_best_tier": last.get("curator_best_tier"),
+            "user_avg": last.get("user_avg_match"),
+            "user_5plus": last.get("user_5plus_prizes"),
+            "pattern_delta": last.get("pattern_delta") or "",
+        },
+        "trend_4w": {
+            "curator_avg_4w": round(sum(cur_avgs) / len(cur_avgs), 2) if cur_avgs else None,
+            "user_avg_4w":    round(sum(usr_avgs) / len(usr_avgs), 2) if usr_avgs else None,
+            "user_persistent_bias": _detect_bias(series),
+        },
+    }

agent-office/app/curator/schema.py

@@ -17,25 +17,42 @@ class Pick(BaseModel):
         return sorted(v)
 
 
+class TierRationale(BaseModel):
+    bonus: str = Field(max_length=40)
+    extended: str = Field(max_length=40)
+    pool: str = Field(max_length=40)
+
+
 class Narrative(BaseModel):
     headline: str
     summary_3lines: List[str] = Field(min_length=3, max_length=3)
     hot_cold_comment: str = ""
     warnings: str = ""
+    retrospective: str = Field(default="", max_length=80)
 
 
 class CuratorOutput(BaseModel):
-    picks: List[Pick]
+    core_picks: List[Pick]     = Field(min_length=5, max_length=5)
+    bonus_picks: List[Pick]    = Field(min_length=5, max_length=5)
+    extended_picks: List[Pick] = Field(min_length=5, max_length=5)
+    pool_picks: List[Pick]     = Field(min_length=5, max_length=5)
+    tier_rationale: TierRationale
     narrative: Narrative
     confidence: int = Field(ge=0, le=100)
 
 
 def validate_response(data: dict, candidate_numbers: List[List[int]]) -> CuratorOutput:
     out = CuratorOutput.model_validate(data)
-    if len(out.picks) != 5:
-        raise ValueError("picks must have exactly 5 sets")
     candidate_set = {tuple(sorted(c)) for c in candidate_numbers}
-    for p in out.picks:
+    all_picks = (
+        out.core_picks + out.bonus_picks + out.extended_picks + out.pool_picks
+    )
+    # 중복 픽 검증
+    pick_keys = [tuple(p.numbers) for p in all_picks]
+    if len(pick_keys) != len(set(pick_keys)):
+        raise ValueError("duplicate picks across tiers")
+    # 후보에 없는 번호 조합 금지
+    for p in all_picks:
         if tuple(p.numbers) not in candidate_set:
             raise ValueError(f"pick {p.numbers} not in candidates")
     return out

agent-office/app/db.py

@@ -9,9 +9,10 @@ from .config import DB_PATH
 
 def _conn() -> sqlite3.Connection:
     os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
-    conn = sqlite3.connect(DB_PATH, timeout=10)
+    conn = sqlite3.connect(DB_PATH, timeout=120.0)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=120000")
     return conn
 
 

agent-office/app/main.py

@@ -10,8 +10,10 @@ from .websocket_manager import ws_manager
 from .agents import init_agents, get_agent, get_all_agent_states, AGENT_REGISTRY
 from .scheduler import init_scheduler
 from . import telegram_bot
+from .routers import notify as notify_router
 
 app = FastAPI()
+app.include_router(notify_router.router)
 
 _cors_origins = CORS_ALLOW_ORIGINS.split(",")
 app.add_middleware(

agent-office/app/notifiers/telegram_lotto.py

@@ -0,0 +1,61 @@
+"""로또 큐레이션·당첨 알림 — 텔레그램 푸시."""
+import logging
+from typing import Dict, Any
+
+# 기존 에이전트들과 동일한 패턴: send_raw(text, reply_markup=None, chat_id=None)
+# chat_id 생략 시 기본 TELEGRAM_CHAT_ID로 자동 발송.
+from ..telegram.messaging import send_raw
+
+logger = logging.getLogger("agent-office")
+
+LOTTO_URL = "https://gahusb.synology.me/lotto"
+
+
+def _format_briefing(payload: Dict[str, Any]) -> str:
+    draw_no = payload["draw_no"]
+    nar = payload["narrative"]
+    conf = payload["confidence"]
+
+    # 분배 칩 — core 5세트의 risk_tag 빈도
+    core = payload["picks"]["core"]
+    role_count = {"안정": 0, "균형": 0, "공격": 0}
+    for p in core:
+        role_count[p["risk_tag"]] = role_count.get(p["risk_tag"], 0) + 1
+    chip = " · ".join(f"{k} {v}" for k, v in role_count.items() if v)
+
+    msg = [
+        f"🎟 {draw_no}회 · 큐레이션 떴음",
+        "",
+        f"\"{nar['headline']}\"",
+        f"신뢰도 {conf} · 분배 {chip}",
+    ]
+    retro = nar.get("retrospective") or ""
+    if retro:
+        msg += ["", f"▸ 회고: {retro}"]
+    msg += ["", f"👉 결정 카드 보러가기  ({LOTTO_URL})"]
+    return "\n".join(msg)
+
+
+def _format_prize_alert(event: Dict[str, Any]) -> str:
+    return (
+        "🚨 로또 당첨 가능성!\n"
+        f"{event['draw_no']}회 — {event['match_count']}개 일치\n"
+        f"번호: {', '.join(str(n) for n in event['numbers'])}\n"
+        "동행복권에서 즉시 확인하세요."
+    )
+
+
+async def send_curator_briefing(payload: Dict[str, Any]) -> None:
+    text = _format_briefing(payload)
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] briefing send failed: {e}")
+
+
+async def send_prize_alert(event: Dict[str, Any]) -> None:
+    text = _format_prize_alert(event)
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] prize alert send failed: {e}")

agent-office/app/routers/notify.py

@@ -0,0 +1,20 @@
+"""다른 서비스가 트리거하는 웹훅 — 현재 lotto-backend → 텔레그램 푸시."""
+from typing import List
+from fastapi import APIRouter
+from pydantic import BaseModel
+from ..notifiers.telegram_lotto import send_prize_alert
+
+router = APIRouter(prefix="/api/agent-office/notify")
+
+
+class LottoPrizeEvent(BaseModel):
+    draw_no: int
+    match_count: int
+    numbers: List[int]
+    purchase_id: int
+
+
+@router.post("/lotto-prize")
+async def lotto_prize(body: LottoPrizeEvent):
+    await send_prize_alert(body.model_dump())
+    return {"ok": True}

agent-office/app/scheduler.py

@@ -14,11 +14,27 @@ async def _run_stock_schedule():
     if agent:
         await agent.on_schedule()
 
-async def _run_blog_schedule():
-    agent = AGENT_REGISTRY.get("blog")
+async def _run_stock_screener():
+    agent = AGENT_REGISTRY.get("stock")
+    if agent:
+        await agent.on_screener_schedule()
+
+async def _run_stock_ai_news():
+    agent = AGENT_REGISTRY.get("stock")
+    if agent:
+        await agent.on_ai_news_schedule()
+
+async def _run_insta_schedule():
+    agent = AGENT_REGISTRY.get("insta")
     if agent:
         await agent.on_schedule()
 
+
+async def _run_insta_trends_collect():
+    agent = AGENT_REGISTRY.get("insta")
+    if agent:
+        await agent.on_command("collect_trends", {})
+
 async def _run_lotto_schedule():
     agent = AGENT_REGISTRY.get("lotto")
     if agent:
@@ -41,8 +57,25 @@ async def _poll_pipelines():
 
 def init_scheduler():
     scheduler.add_job(_run_stock_schedule, "cron", hour=7, minute=30, id="stock_news")
-    scheduler.add_job(_run_blog_schedule, "cron", hour=10, minute=0, id="blog_pipeline")
-    scheduler.add_job(_run_lotto_schedule, "cron", day_of_week="mon", hour=7, minute=0, id="lotto_curate")
+    scheduler.add_job(
+        _run_stock_screener,
+        "cron",
+        day_of_week="mon-fri",
+        hour=16,
+        minute=30,
+        id="stock_screener",
+    )
+    scheduler.add_job(
+        _run_stock_ai_news,
+        "cron",
+        day_of_week="mon-fri",
+        hour=8,
+        minute=0,
+        id="stock_ai_news_sentiment",
+    )
+    scheduler.add_job(_run_insta_schedule, "cron", hour=9, minute=30, id="insta_pipeline")
+    scheduler.add_job(_run_insta_trends_collect, "cron", hour=9, minute=0, id="insta_trends_collect")
+    scheduler.add_job(_run_lotto_schedule, "cron", day_of_week="mon", hour=9, minute=0, id="lotto_curate")
     scheduler.add_job(_run_youtube_research, "cron", hour=9, minute=0, id="youtube_research")
     scheduler.add_job(_send_youtube_weekly_report, "cron", day_of_week="mon", hour=8, minute=0, id="youtube_weekly_report")
     scheduler.add_job(_check_idle_breaks, "interval", seconds=60, id="idle_check")

agent-office/app/service_proxy.py

@@ -1,7 +1,7 @@
 import httpx
 from typing import Any, Dict, List, Optional
 
-from .config import STOCK_LAB_URL, MUSIC_LAB_URL, BLOG_LAB_URL, REALESTATE_LAB_URL
+from .config import STOCK_URL, MUSIC_LAB_URL, INSTA_LAB_URL, REALESTATE_LAB_URL
 
 _client = httpx.AsyncClient(timeout=30.0)
 
@@ -9,37 +9,79 @@ async def fetch_stock_news(limit: int = 10, category: str = None) -> List[Dict[s
     params = {"limit": limit}
     if category:
         params["category"] = category
-    resp = await _client.get(f"{STOCK_LAB_URL}/api/stock/news", params=params)
+    resp = await _client.get(f"{STOCK_URL}/api/stock/news", params=params)
     resp.raise_for_status()
     return resp.json()
 
 async def fetch_stock_indices() -> Dict[str, Any]:
-    resp = await _client.get(f"{STOCK_LAB_URL}/api/stock/indices")
+    resp = await _client.get(f"{STOCK_URL}/api/stock/indices")
     resp.raise_for_status()
     return resp.json()
 
 async def summarize_stock_news(limit: int = 15) -> Dict[str, Any]:
-    """stock-lab의 AI 요약 엔드포인트 호출.
+    """stock의 AI 요약 엔드포인트 호출.
     반환: {"summary": str, "tokens": {...}, "model": str, "duration_ms": int, "article_count": int}
     """
-    # stock-lab 내부 Ollama 호출이 180s까지 가능하므로 여유있게 200s
+    # stock 내부 Ollama 호출이 180s까지 가능하므로 여유있게 200s
     async with httpx.AsyncClient(timeout=200.0) as client:
         resp = await client.post(
-            f"{STOCK_LAB_URL}/api/stock/news/summarize",
+            f"{STOCK_URL}/api/stock/news/summarize",
             json={"limit": limit},
         )
         resp.raise_for_status()
         return resp.json()
 
 
+async def refresh_screener_snapshot() -> Dict[str, Any]:
+    """stock의 KRX 일봉 스냅샷 갱신 (스크리너 실행 전 호출).
+
+    네이버 금융 일괄 다운로드라 보통 30~120s, 여유있게 180s.
+    """
+    async with httpx.AsyncClient(timeout=180.0) as client:
+        resp = await client.post(f"{STOCK_URL}/api/stock/screener/snapshot/refresh")
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def refresh_ai_news_sentiment() -> Dict[str, Any]:
+    """stock의 AI 뉴스 sentiment 분석 트리거 (08:00 cron).
+
+    네이버 100종목 스크래핑 + Claude Haiku 100콜 병렬 = 약 30-60초.
+    여유있게 240s timeout.
+    """
+    async with httpx.AsyncClient(timeout=240.0) as client:
+        resp = await client.post(
+            f"{STOCK_URL}/api/stock/screener/snapshot/refresh-news-sentiment"
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def run_stock_screener(mode: str = "auto") -> Dict[str, Any]:
+    """stock의 스크리너 실행.
+
+    반환 status:
+      - 'skipped_holiday': 공휴일/주말 — telegram_payload 없음
+      - 'success': telegram_payload 동봉
+    엔진 자체는 수 초 내 끝나지만, 컨텍스트 로드+200종목 처리 여유 180s.
+    """
+    async with httpx.AsyncClient(timeout=180.0) as client:
+        resp = await client.post(
+            f"{STOCK_URL}/api/stock/screener/run",
+            json={"mode": mode},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
 async def scrape_stock_news() -> Dict[str, Any]:
-    """stock-lab의 수동 뉴스 스크랩 트리거 — DB에 최신 뉴스 저장.
+    """stock의 수동 뉴스 스크랩 트리거 — DB에 최신 뉴스 저장.
 
     아침 브리핑 직전 호출하여 어제 데이터가 아닌 오늘 새벽 뉴스를 보장한다.
     네이버 금융 단일 요청이라 보통 수 초 내 완료, 여유있게 60s.
     """
     async with httpx.AsyncClient(timeout=60.0) as client:
-        resp = await client.post(f"{STOCK_LAB_URL}/api/stock/scrap")
+        resp = await client.post(f"{STOCK_URL}/api/stock/scrap")
         resp.raise_for_status()
         return resp.json()
 
@@ -59,60 +101,107 @@ async def get_music_credits() -> Dict[str, Any]:
     return resp.json()
 
 
-# --- blog-lab ---
+# --- insta-lab ---
 
-async def blog_research(keyword: str) -> Dict[str, Any]:
-    """키워드 리서치 시작 → task_id 반환"""
+async def insta_collect(categories: Optional[list] = None) -> Dict[str, Any]:
+    """뉴스 수집 트리거 → task_id 반환."""
+    payload = {"categories": categories} if categories else {}
+    resp = await _client.post(f"{INSTA_LAB_URL}/api/insta/news/collect", json=payload)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def insta_extract(categories: Optional[list] = None) -> Dict[str, Any]:
+    payload = {"categories": categories} if categories else {}
+    resp = await _client.post(f"{INSTA_LAB_URL}/api/insta/keywords/extract", json=payload)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def insta_list_keywords(category: Optional[str] = None,
+                              used: Optional[bool] = None) -> List[Dict[str, Any]]:
+    params: Dict[str, Any] = {}
+    if category:
+        params["category"] = category
+    if used is not None:
+        params["used"] = "true" if used else "false"
+    resp = await _client.get(f"{INSTA_LAB_URL}/api/insta/keywords", params=params)
+    resp.raise_for_status()
+    return resp.json().get("items", [])
+
+
+async def insta_get_keyword(keyword_id: int) -> Optional[Dict[str, Any]]:
+    items = await insta_list_keywords()
+    for it in items:
+        if it["id"] == keyword_id:
+            return it
+    return None
+
+
+async def insta_create_slate(keyword: str, category: str, keyword_id: Optional[int] = None) -> Dict[str, Any]:
     resp = await _client.post(
-        f"{BLOG_LAB_URL}/api/blog-marketing/research",
-        json={"keyword": keyword},
+        f"{INSTA_LAB_URL}/api/insta/slates",
+        json={"keyword": keyword, "category": category, "keyword_id": keyword_id},
     )
     resp.raise_for_status()
     return resp.json()
 
 
-async def blog_task_status(task_id: str) -> Dict[str, Any]:
-    resp = await _client.get(f"{BLOG_LAB_URL}/api/blog-marketing/task/{task_id}")
+async def insta_task_status(task_id: str) -> Dict[str, Any]:
+    resp = await _client.get(f"{INSTA_LAB_URL}/api/insta/tasks/{task_id}")
     resp.raise_for_status()
     return resp.json()
 
 
-async def blog_generate(keyword_id: int) -> Dict[str, Any]:
-    resp = await _client.post(
-        f"{BLOG_LAB_URL}/api/blog-marketing/generate",
-        json={"keyword_id": keyword_id},
+async def insta_get_slate(slate_id: int) -> Dict[str, Any]:
+    resp = await _client.get(f"{INSTA_LAB_URL}/api/insta/slates/{slate_id}")
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def insta_get_asset_bytes(slate_id: int, page: int) -> bytes:
+    """카드 PNG 바이트를 가져와 텔레그램 미디어 그룹에 첨부."""
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.get(f"{INSTA_LAB_URL}/api/insta/slates/{slate_id}/assets/{page}")
+        resp.raise_for_status()
+        return resp.content
+
+
+async def insta_collect_trends(categories: Optional[list] = None) -> Dict[str, Any]:
+    payload = {"categories": categories} if categories else {}
+    resp = await _client.post(f"{INSTA_LAB_URL}/api/insta/trends/collect", json=payload)
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def insta_list_trends(source: Optional[str] = None,
+                            category: Optional[str] = None,
+                            days: int = 1) -> List[Dict[str, Any]]:
+    params: Dict[str, Any] = {"days": days}
+    if source:
+        params["source"] = source
+    if category:
+        params["category"] = category
+    resp = await _client.get(f"{INSTA_LAB_URL}/api/insta/trends", params=params)
+    resp.raise_for_status()
+    return resp.json().get("items", [])
+
+
+async def insta_get_preferences() -> Dict[str, float]:
+    resp = await _client.get(f"{INSTA_LAB_URL}/api/insta/preferences")
+    resp.raise_for_status()
+    return {p["category"]: p["weight"] for p in resp.json().get("categories", [])}
+
+
+async def insta_put_preferences(weights: Dict[str, float]) -> Dict[str, Any]:
+    resp = await _client.put(
+        f"{INSTA_LAB_URL}/api/insta/preferences",
+        json={"categories": weights},
     )
     resp.raise_for_status()
     return resp.json()
 
 
-async def blog_market(post_id: int) -> Dict[str, Any]:
-    resp = await _client.post(f"{BLOG_LAB_URL}/api/blog-marketing/market/{post_id}")
-    resp.raise_for_status()
-    return resp.json()
-
-
-async def blog_review(post_id: int) -> Dict[str, Any]:
-    resp = await _client.post(f"{BLOG_LAB_URL}/api/blog-marketing/review/{post_id}")
-    resp.raise_for_status()
-    return resp.json()
-
-
-async def blog_publish(post_id: int, url: str = "") -> Dict[str, Any]:
-    resp = await _client.post(
-        f"{BLOG_LAB_URL}/api/blog-marketing/posts/{post_id}/publish",
-        json={"url": url},
-    )
-    resp.raise_for_status()
-    return resp.json()
-
-
-async def blog_get_post(post_id: int) -> Dict[str, Any]:
-    resp = await _client.get(f"{BLOG_LAB_URL}/api/blog-marketing/posts/{post_id}")
-    resp.raise_for_status()
-    return resp.json()
-
-
 # --- realestate-lab ---
 
 async def realestate_collect() -> Dict[str, Any]:
@@ -180,6 +269,34 @@ async def lotto_save_briefing(payload: dict) -> Dict[str, Any]:
     return resp.json()
 
 
+async def lotto_review_latest() -> Optional[Dict[str, Any]]:
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/review/latest")
+    if resp.status_code == 404:
+        return None
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def lotto_review_by_draw(draw_no: int) -> Optional[Dict[str, Any]]:
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/review/{draw_no}")
+    if resp.status_code == 404:
+        return None
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def lotto_reviews_history(limit: int = 10) -> List[Dict[str, Any]]:
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(
+        f"{LOTTO_BACKEND_URL}/api/lotto/review/history",
+        params={"limit": limit},
+    )
+    resp.raise_for_status()
+    return resp.json().get("reviews", [])
+
+
 # --- music-lab pipeline (YouTube publisher orchestration) ---
 
 async def list_active_pipelines() -> list[dict]:

agent-office/app/telegram/messaging.py

@@ -8,14 +8,22 @@ from .client import _enabled, api_call
 from .formatter import MessageKind, format_agent_message
 
 
-async def send_raw(text: str, reply_markup: Optional[dict] = None, chat_id: Optional[str] = None) -> dict:
-    """가장 저수준. 원문 텍스트 그대로 전송. chat_id 생략 시 기본 TELEGRAM_CHAT_ID로."""
+async def send_raw(
+    text: str,
+    reply_markup: Optional[dict] = None,
+    chat_id: Optional[str] = None,
+    parse_mode: str = "HTML",
+) -> dict:
+    """가장 저수준. 원문 텍스트 그대로 전송. chat_id 생략 시 기본 TELEGRAM_CHAT_ID로.
+
+    parse_mode: 기본 'HTML'. MarkdownV2 페이로드(예: 스크리너) 전송 시 명시 지정.
+    """
     if not _enabled():
         return {"ok": False, "message_id": None}
     payload = {
         "chat_id": chat_id or TELEGRAM_CHAT_ID,
         "text": text,
-        "parse_mode": "HTML",
+        "parse_mode": parse_mode,
     }
     if reply_markup:
         payload["reply_markup"] = reply_markup

agent-office/app/telegram/webhook.py

@@ -37,6 +37,9 @@ async def _handle_callback(callback_query: dict) -> Optional[dict]:
     if callback_id.startswith("realestate_bookmark_"):
         return await _handle_realestate_bookmark(callback_query, callback_id)
 
+    if callback_id.startswith("render_"):
+        return await _handle_insta_render(callback_query, callback_id)
+
     cb = get_telegram_callback(callback_id)
     if not cb:
         return None
@@ -97,6 +100,38 @@ async def _handle_realestate_bookmark(callback_query: dict, callback_id: str) ->
         return {"ok": False, "error": str(e)}
 
 
+async def _handle_insta_render(callback_query: dict, callback_id: str) -> dict:
+    """render_{keyword_id} 콜백 → InstaAgent.on_callback('render', ...).
+
+    텔레그램 인라인 버튼이 보낸 callback_data가 `render_<keyword_id>` 형식.
+    InstaAgent._push_keyword_candidates가 callback_data를 그대로 박아 보내며,
+    별도 DB lookup 없이 keyword_id를 파싱해 dispatch한다."""
+    from .messaging import send_raw
+    from ..agents import AGENT_REGISTRY
+
+    await api_call(
+        "answerCallbackQuery",
+        {"callback_query_id": callback_query["id"], "text": "카드 생성 시작"},
+    )
+
+    try:
+        keyword_id = int(callback_id.removeprefix("render_"))
+    except ValueError:
+        await send_raw("⚠️ 잘못된 render 콜백 데이터")
+        return {"ok": False, "error": "invalid_callback_data"}
+
+    agent = AGENT_REGISTRY.get("insta")
+    if not agent:
+        await send_raw("⚠️ insta agent 미등록")
+        return {"ok": False, "error": "agent_missing"}
+
+    try:
+        return await agent.on_callback("render", {"keyword_id": keyword_id})
+    except Exception as e:
+        await send_raw(f"⚠️ 카드 생성 실패: {e}")
+        return {"ok": False, "error": str(e)}
+
+
 async def _handle_message(message: dict, agent_dispatcher) -> Optional[dict]:
     """슬래시 명령 메시지 처리."""
     from .router import parse_command, resolve_agent_command, HELP_TEXT

agent-office/tests/test_curator_schema.py

@@ -1,60 +1,55 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
 import pytest
-from app.curator.schema import validate_response, CuratorOutput
+from app.curator.schema import validate_response
 
 
-CANDIDATE_NUMBERS = [
-    [1, 2, 3, 4, 5, 6],
-    [7, 8, 9, 10, 11, 12],
-    [13, 14, 15, 16, 17, 18],
-    [19, 20, 21, 22, 23, 24],
-    [25, 26, 27, 28, 29, 30],
-    [31, 32, 33, 34, 35, 36],
-]
+def _pick(nums, role="안정"):
+    return {"numbers": nums, "risk_tag": role, "reason": "x"}
 
 
-def _valid_payload():
+def _make_payload(core, bonus, ext, pool):
     return {
-        "picks": [
-            {"numbers": s, "risk_tag": "안정", "reason": "test"}
-            for s in CANDIDATE_NUMBERS[:5]
-        ],
+        "core_picks": core, "bonus_picks": bonus,
+        "extended_picks": ext, "pool_picks": pool,
+        "tier_rationale": {"bonus": "a", "extended": "b", "pool": "c"},
         "narrative": {
-            "headline": "h", "summary_3lines": ["a", "b", "c"],
-            "hot_cold_comment": "hc", "warnings": "",
+            "headline": "h",
+            "summary_3lines": ["1", "2", "3"],
+            "retrospective": "지난주 평균 1.8",
         },
-        "confidence": 80,
+        "confidence": 70,
     }
 
 
-def test_valid_payload_passes():
-    result = validate_response(_valid_payload(), CANDIDATE_NUMBERS)
-    assert isinstance(result, CuratorOutput)
-    assert len(result.picks) == 5
+def test_valid_4tier():
+    pool = [[i, i+1, i+2, i+3, i+4, i+5] for i in range(1, 21)]
+    cores = [_pick(pool[i]) for i in range(5)]
+    bonus = [_pick(pool[i]) for i in range(5, 10)]
+    ext   = [_pick(pool[i]) for i in range(10, 15)]
+    pl    = [_pick(pool[i]) for i in range(15, 20)]
+    out = validate_response(_make_payload(cores, bonus, ext, pl), pool)
+    assert len(out.core_picks) == 5
+    assert out.narrative.retrospective.startswith("지난주")
 
 
-def test_rejects_number_out_of_candidates():
-    bad = _valid_payload()
-    bad["picks"][0]["numbers"] = [40, 41, 42, 43, 44, 45]  # valid numbers but not in candidates
+def test_duplicate_pick_rejected():
+    pool = [[i, i+1, i+2, i+3, i+4, i+5] for i in range(1, 21)]
+    cores = [_pick(pool[0])] * 5  # 중복
+    bonus = [_pick(pool[i]) for i in range(5, 10)]
+    ext   = [_pick(pool[i]) for i in range(10, 15)]
+    pl    = [_pick(pool[i]) for i in range(15, 20)]
+    with pytest.raises(ValueError, match="duplicate"):
+        validate_response(_make_payload(cores, bonus, ext, pl), pool)
+
+
+def test_pick_not_in_candidates_rejected():
+    pool = [[i, i+1, i+2, i+3, i+4, i+5] for i in range(1, 21)]
+    foreign = [40, 41, 42, 43, 44, 45]
+    cores = [_pick(foreign)] + [_pick(pool[i]) for i in range(1, 5)]
+    bonus = [_pick(pool[i]) for i in range(5, 10)]
+    ext   = [_pick(pool[i]) for i in range(10, 15)]
+    pl    = [_pick(pool[i]) for i in range(15, 20)]
     with pytest.raises(ValueError, match="not in candidates"):
-        validate_response(bad, CANDIDATE_NUMBERS)
-
-
-def test_rejects_wrong_pick_count():
-    bad = _valid_payload()
-    bad["picks"] = bad["picks"][:3]
-    with pytest.raises(ValueError, match="exactly 5"):
-        validate_response(bad, CANDIDATE_NUMBERS)
-
-
-def test_rejects_duplicate_numbers_within_set():
-    bad = _valid_payload()
-    bad["picks"][0]["numbers"] = [1, 1, 2, 3, 4, 5]
-    with pytest.raises(ValueError):
-        validate_response(bad, CANDIDATE_NUMBERS)
-
-
-def test_rejects_invalid_risk_tag():
-    bad = _valid_payload()
-    bad["picks"][0]["risk_tag"] = "미친"
-    with pytest.raises(ValueError):
-        validate_response(bad, CANDIDATE_NUMBERS)
+        validate_response(_make_payload(cores, bonus, ext, pl), pool)

agent-office/tests/test_insta_agent.py

@@ -0,0 +1,85 @@
+import os
+import sys
+import tempfile
+
+_fd, _TMP = tempfile.mkstemp(suffix=".db")
+os.close(_fd)
+os.unlink(_TMP)
+os.environ["AGENT_OFFICE_DB_PATH"] = _TMP
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from unittest.mock import patch, AsyncMock, MagicMock
+
+import pytest
+
+from app.agents.insta import InstaAgent
+
+
+@pytest.fixture(autouse=True)
+def _init_db():
+    import gc
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    from app.db import init_db
+    init_db()
+    yield
+    gc.collect()
+
+
+@pytest.mark.asyncio
+async def test_on_command_extract_dispatches(monkeypatch):
+    agent = InstaAgent()
+    fake_collect = AsyncMock(return_value={"task_id": "tcollect"})
+    fake_extract = AsyncMock(return_value={"task_id": "textract"})
+    fake_status = AsyncMock(side_effect=[
+        {"status": "succeeded", "result_id": 0},
+        {"status": "succeeded", "result_id": 0},
+    ])
+    fake_keywords = AsyncMock(return_value=[
+        {"id": 1, "keyword": "K1", "category": "economy", "score": 0.9},
+        {"id": 2, "keyword": "K2", "category": "psychology", "score": 0.8},
+    ])
+
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_collect", fake_collect)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_extract", fake_extract)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_task_status", fake_status)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_list_keywords", fake_keywords)
+    monkeypatch.setattr("app.agents.insta.messaging.send_raw", AsyncMock(return_value={"ok": True}))
+
+    result = await agent.on_command("extract", {})
+    assert result["ok"] is True
+    fake_collect.assert_awaited()
+    fake_extract.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_on_callback_render_kicks_pipeline(monkeypatch):
+    agent = InstaAgent()
+    fake_kw = AsyncMock(return_value={"id": 7, "keyword": "테스트", "category": "economy"})
+    fake_create = AsyncMock(return_value={"task_id": "tslate"})
+    fake_status = AsyncMock(side_effect=[
+        {"status": "processing"},
+        {"status": "succeeded", "result_id": 42},
+    ])
+    fake_slate = AsyncMock(return_value={
+        "id": 42, "status": "rendered",
+        "suggested_caption": "캡션", "hashtags": ["#a", "#b"],
+        "assets": [{"page_index": i, "file_path": f"/x/{i}.png"} for i in range(1, 11)],
+    })
+    fake_bytes = AsyncMock(side_effect=[b"PNG"] * 10)
+    fake_send_media = AsyncMock(return_value={"ok": True})
+
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_get_keyword", fake_kw)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_create_slate", fake_create)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_task_status", fake_status)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_get_slate", fake_slate)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_get_asset_bytes", fake_bytes)
+    monkeypatch.setattr("app.agents.insta._send_media_group", fake_send_media)
+    monkeypatch.setattr("app.agents.insta.messaging.send_raw", AsyncMock(return_value={"ok": True}))
+
+    out = await agent.on_callback("render", {"keyword_id": 7})
+    assert out["ok"] is True
+    fake_create.assert_awaited()
+    fake_send_media.assert_awaited()

agent-office/tests/test_insta_agent_trends.py

@@ -0,0 +1,73 @@
+import os
+import sys
+import tempfile
+
+_fd, _TMP = tempfile.mkstemp(suffix=".db")
+os.close(_fd)
+os.unlink(_TMP)
+os.environ["AGENT_OFFICE_DB_PATH"] = _TMP
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from app.agents.insta import InstaAgent
+
+
+@pytest.fixture(autouse=True)
+def _init_db():
+    import gc
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    from app.db import init_db
+    init_db()
+    yield
+    gc.collect()
+
+
+@pytest.mark.asyncio
+async def test_on_command_collect_trends_dispatches(monkeypatch):
+    agent = InstaAgent()
+    fake_collect = AsyncMock(return_value={"task_id": "tcollect"})
+    fake_status = AsyncMock(return_value={"status": "succeeded", "result_id": 8,
+                                          "message": "naver:5, google:3"})
+
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_collect_trends", fake_collect)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_task_status", fake_status)
+    monkeypatch.setattr("app.agents.insta.messaging.send_raw", AsyncMock(return_value={"ok": True}))
+
+    result = await agent.on_command("collect_trends", {})
+    assert result["ok"] is True
+    fake_collect.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_on_schedule_loads_preferences(monkeypatch):
+    """on_schedule이 preferences를 가져오는지 확인."""
+    agent = InstaAgent()
+
+    fake_collect = AsyncMock(return_value={"task_id": "t1"})
+    fake_extract = AsyncMock(return_value={"task_id": "t2"})
+    fake_status = AsyncMock(side_effect=[
+        {"status": "succeeded", "result_id": 0},
+        {"status": "succeeded", "result_id": 0},
+    ])
+    fake_keywords = AsyncMock(return_value=[
+        {"id": 1, "keyword": "K", "category": "economy", "score": 0.9},
+    ])
+    fake_prefs = AsyncMock(return_value={"economy": 0.6, "psychology": 0.4})
+
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_collect", fake_collect)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_extract", fake_extract)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_task_status", fake_status)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_list_keywords", fake_keywords)
+    monkeypatch.setattr("app.agents.insta.service_proxy.insta_get_preferences", fake_prefs)
+    monkeypatch.setattr("app.agents.insta.messaging.send_raw", AsyncMock(return_value={"ok": True}))
+
+    agent.state = "idle"
+    await agent.on_schedule()
+
+    fake_prefs.assert_awaited()

agent-office/tests/test_pipeline_polling.py

@@ -35,6 +35,7 @@ async def test_poll_notifies_once_per_state():
         "state": "cover_pending",
         "cover_url": "/x.jpg",
         "track_title": "Test",
+        "feedback_count_per_step": {},
     }]
     with patch(
         "app.agents.youtube_publisher.service_proxy.list_active_pipelines",
@@ -52,6 +53,27 @@ async def test_poll_notifies_once_per_state():
         assert mock_send.call_count == 1
 
 
+@pytest.mark.asyncio
+async def test_poll_renotifies_on_reject_regen(monkeypatch):
+    from app.agents.youtube_publisher import YoutubePublisherAgent
+
+    pipelines_v1 = [{"id": 1, "state": "cover_pending", "cover_url": "/x.jpg",
+                      "track_title": "Test", "feedback_count_per_step": {}}]
+    pipelines_v2 = [{"id": 1, "state": "cover_pending", "cover_url": "/x2.jpg",
+                      "track_title": "Test", "feedback_count_per_step": {"cover": 1}}]
+    list_mock = AsyncMock(side_effect=[pipelines_v1, pipelines_v2])
+    with patch("app.agents.youtube_publisher.service_proxy.list_active_pipelines", list_mock), \
+         patch("app.agents.youtube_publisher.send_raw",
+                new=AsyncMock(return_value={"ok": True, "message_id": 99})), \
+         patch("app.agents.youtube_publisher.service_proxy.save_pipeline_telegram_msg",
+                new=AsyncMock()):
+        a = YoutubePublisherAgent()
+        await a.poll_state_changes()  # 1st: notify
+        await a.poll_state_changes()  # 2nd: feedback count differs → notify again
+        from app.agents.youtube_publisher import send_raw as sr
+        assert sr.call_count == 2
+
+
 @pytest.mark.asyncio
 async def test_on_telegram_reply_approve_calls_feedback():
     from app.agents.youtube_publisher import YoutubePublisherAgent

agent-office/tests/test_retrospective.py

@@ -0,0 +1,47 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import pytest
+from unittest.mock import AsyncMock, patch
+from app.curator.retrospective import build_retrospective, _detect_bias
+
+
+def test_detect_bias_persistent_low():
+    reviews = [
+        {"pattern_delta": "저번호 편향 +1.2 / 합계 -18"},
+        {"pattern_delta": "저번호 편향 +0.8"},
+        {"pattern_delta": "저번호 편향 +1.0 / 홀짝 +0.5"},
+    ]
+    assert "저번호" in _detect_bias(reviews)
+
+
+def test_detect_bias_no_persistence():
+    reviews = [
+        {"pattern_delta": "저번호 편향 +1.2"},
+        {"pattern_delta": "고번호 편향 +0.8"},
+    ]
+    assert _detect_bias(reviews) == ""
+
+
+@pytest.mark.asyncio
+async def test_build_retrospective_with_data():
+    with patch("app.service_proxy.lotto_review_by_draw", new=AsyncMock(return_value={
+        "draw_no": 1153, "curator_avg_match": 1.8, "curator_best_tier": "안정",
+        "user_avg_match": 2.0, "user_5plus_prizes": 1, "pattern_delta": "저번호 편향 +1.2",
+    })), patch("app.service_proxy.lotto_reviews_history", new=AsyncMock(return_value=[
+        {"draw_no": 1153, "curator_avg_match": 1.8, "user_avg_match": 2.0, "pattern_delta": "저번호 편향 +1.2"},
+        {"draw_no": 1152, "curator_avg_match": 1.6, "user_avg_match": 1.5, "pattern_delta": "저번호 편향 +0.8"},
+        {"draw_no": 1151, "curator_avg_match": 1.7, "user_avg_match": 1.8, "pattern_delta": "저번호 편향 +1.0"},
+        {"draw_no": 1150, "curator_avg_match": 1.9, "user_avg_match": 2.2, "pattern_delta": ""},
+    ])):
+        out = await build_retrospective(1154)
+        assert out["last_draw"]["draw_no"] == 1153
+        assert out["trend_4w"]["curator_avg_4w"] == round((1.8+1.6+1.7+1.9)/4, 2)
+        assert "저번호" in out["trend_4w"]["user_persistent_bias"]
+
+
+@pytest.mark.asyncio
+async def test_build_retrospective_no_review():
+    with patch("app.service_proxy.lotto_review_by_draw", new=AsyncMock(return_value=None)):
+        out = await build_retrospective(1154)
+        assert out is None

agent-office/tests/test_stock_screener_job.py

@@ -0,0 +1,177 @@
+"""StockAgent.on_screener_schedule — 평일 16:30 KST 자동 잡 단위 테스트.
+
+stock HTTP 호출은 service_proxy mock, 텔레그램은 messaging.send_raw mock.
+"""
+import os
+import sys
+import tempfile
+
+_fd, _TMP = tempfile.mkstemp(suffix=".db")
+os.close(_fd)
+os.unlink(_TMP)
+os.environ["AGENT_OFFICE_DB_PATH"] = _TMP
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _init_db():
+    import gc
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    from app.db import init_db
+    init_db()
+    yield
+    gc.collect()
+
+
+def _success_body(asof="2026-05-12"):
+    return {
+        "asof": asof,
+        "mode": "auto",
+        "status": "success",
+        "run_id": 42,
+        "survivors_count": 600,
+        "top_n": 20,
+        "results": [],
+        "telegram_payload": {
+            "chat_target": "default",
+            "parse_mode": "MarkdownV2",
+            "text": "*KRX 강세주 스크리너* test body",
+        },
+        "warnings": [],
+    }
+
+
+def _holiday_body(asof="2026-05-05"):
+    return {
+        "asof": asof,
+        "mode": "auto",
+        "status": "skipped_holiday",
+        "run_id": None,
+        "survivors_count": None,
+        "top_n": 0,
+        "results": [],
+        "telegram_payload": None,
+        "warnings": [f"{asof} is a holiday — skipped"],
+    }
+
+
+def test_screener_success_sends_markdownv2_telegram():
+    from app.agents.stock import StockAgent
+    from app import service_proxy
+    from app.telegram import messaging
+
+    fake_snap = AsyncMock(return_value={"status": "ok"})
+    fake_run = AsyncMock(return_value=_success_body())
+    fake_send = AsyncMock(return_value={"ok": True, "message_id": 7777})
+
+    with patch.object(service_proxy, "refresh_screener_snapshot", fake_snap), \
+         patch.object(service_proxy, "run_stock_screener", fake_run), \
+         patch.object(messaging, "send_raw", fake_send):
+        agent = StockAgent()
+        asyncio.run(agent.on_screener_schedule())
+
+    fake_snap.assert_awaited_once()
+    fake_run.assert_awaited_once_with(mode="auto")
+    fake_send.assert_awaited_once()
+    args, kwargs = fake_send.call_args
+    # 첫 인자(text) 또는 kwargs로 전달
+    text = args[0] if args else kwargs.get("text")
+    assert "KRX 강세주 스크리너" in text
+    assert kwargs.get("parse_mode") == "MarkdownV2"
+    assert agent.state == "idle"
+
+
+def test_screener_holiday_skips_telegram():
+    from app.agents.stock import StockAgent
+    from app import service_proxy
+    from app.telegram import messaging
+
+    fake_snap = AsyncMock(return_value={"status": "skipped_weekend"})
+    fake_run = AsyncMock(return_value=_holiday_body())
+    fake_send = AsyncMock(return_value={"ok": True, "message_id": 1})
+
+    with patch.object(service_proxy, "refresh_screener_snapshot", fake_snap), \
+         patch.object(service_proxy, "run_stock_screener", fake_run), \
+         patch.object(messaging, "send_raw", fake_send):
+        agent = StockAgent()
+        asyncio.run(agent.on_screener_schedule())
+
+    fake_run.assert_awaited_once()
+    # 휴일이면 텔레그램 미발신
+    fake_send.assert_not_awaited()
+    assert agent.state == "idle"
+
+
+def test_screener_snapshot_failure_still_runs_screener():
+    """스냅샷 실패는 경고만 남기고 screener 호출은 계속됨."""
+    from app.agents.stock import StockAgent
+    from app import service_proxy
+    from app.telegram import messaging
+
+    fake_snap = AsyncMock(side_effect=RuntimeError("snapshot upstream down"))
+    fake_run = AsyncMock(return_value=_success_body())
+    fake_send = AsyncMock(return_value={"ok": True, "message_id": 8888})
+
+    with patch.object(service_proxy, "refresh_screener_snapshot", fake_snap), \
+         patch.object(service_proxy, "run_stock_screener", fake_run), \
+         patch.object(messaging, "send_raw", fake_send):
+        agent = StockAgent()
+        asyncio.run(agent.on_screener_schedule())
+
+    fake_snap.assert_awaited_once()
+    fake_run.assert_awaited_once_with(mode="auto")
+    fake_send.assert_awaited_once()
+
+
+def test_screener_run_failure_notifies_operator():
+    """screener/run 실패 시 운영자 알림 텔레그램 발송."""
+    from app.agents.stock import StockAgent
+    from app import service_proxy
+    from app.telegram import messaging
+
+    fake_snap = AsyncMock(return_value={"status": "ok"})
+    fake_run = AsyncMock(side_effect=RuntimeError("stock 500"))
+    fake_send = AsyncMock(return_value={"ok": True, "message_id": 1})
+
+    with patch.object(service_proxy, "refresh_screener_snapshot", fake_snap), \
+         patch.object(service_proxy, "run_stock_screener", fake_run), \
+         patch.object(messaging, "send_raw", fake_send):
+        agent = StockAgent()
+        asyncio.run(agent.on_screener_schedule())
+
+    # 운영자 알림 1회는 호출
+    assert fake_send.await_count == 1
+    args, kwargs = fake_send.call_args
+    text = args[0] if args else kwargs.get("text")
+    assert "스크리너 실패" in text
+    assert agent.state == "idle"
+
+
+def test_screener_unexpected_status_treated_as_failure():
+    from app.agents.stock import StockAgent
+    from app import service_proxy
+    from app.telegram import messaging
+
+    fake_snap = AsyncMock(return_value={"status": "ok"})
+    fake_run = AsyncMock(return_value={"status": "weird", "asof": "2026-05-12"})
+    fake_send = AsyncMock(return_value={"ok": True, "message_id": 1})
+
+    with patch.object(service_proxy, "refresh_screener_snapshot", fake_snap), \
+         patch.object(service_proxy, "run_stock_screener", fake_run), \
+         patch.object(messaging, "send_raw", fake_send):
+        agent = StockAgent()
+        asyncio.run(agent.on_screener_schedule())
+
+    # 운영자 알림 1회 + screener payload 미발송
+    assert fake_send.await_count == 1
+    args, kwargs = fake_send.call_args
+    text = args[0] if args else kwargs.get("text")
+    assert "스크리너 실패" in text

agent-office/tests/test_telegram_lotto_format.py

@@ -0,0 +1,44 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from app.notifiers.telegram_lotto import _format_briefing, _format_prize_alert
+
+
+def test_briefing_with_retrospective():
+    payload = {
+        "draw_no": 1154,
+        "confidence": 72,
+        "narrative": {
+            "headline": "안정 +1, 콜드 누적 보강",
+            "summary_3lines": ["a", "b", "c"],
+            "retrospective": "너 2.0 / 나 1.8 — 저번호 편향",
+        },
+        "picks": {
+            "core": [
+                {"risk_tag": "안정"}, {"risk_tag": "안정"}, {"risk_tag": "안정"},
+                {"risk_tag": "균형"}, {"risk_tag": "공격"},
+            ],
+            "bonus": [], "extended": [], "pool": [],
+        },
+    }
+    text = _format_briefing(payload)
+    assert "1154회" in text
+    assert "신뢰도 72" in text
+    assert "안정 3" in text
+    assert "회고: 너 2.0" in text
+
+
+def test_briefing_without_retrospective():
+    payload = {
+        "draw_no": 1, "confidence": 50,
+        "narrative": {"headline": "h", "summary_3lines": ["a","b","c"], "retrospective": ""},
+        "picks": {"core": [{"risk_tag":"안정"}]*5, "bonus":[],"extended":[],"pool":[]},
+    }
+    text = _format_briefing(payload)
+    assert "회고" not in text
+
+
+def test_prize_alert():
+    text = _format_prize_alert({"draw_no": 1154, "match_count": 5, "numbers": [3,11,17,25,33,8]})
+    assert "5개 일치" in text
+    assert "3, 11, 17, 25, 33, 8" in text

blog-lab/.dockerignore

@@ -1,4 +0,0 @@
-__pycache__
-*.pyc
-.env
-data/

blog-lab/Dockerfile

@@ -1,15 +0,0 @@
-FROM python:3.12-alpine
-ENV PYTHONUNBUFFERED=1
-
-WORKDIR /app
-
-RUN apk add --no-cache gcc musl-dev
-
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-COPY . .
-
-EXPOSE 8000
-
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

blog-lab/app/config.py

@@ -1,15 +0,0 @@
-import os
-
-# Anthropic Claude API
-ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "")
-CLAUDE_MODEL = os.getenv("CLAUDE_MODEL", "claude-sonnet-4-20250514")
-
-# Naver Search API
-NAVER_CLIENT_ID = os.getenv("NAVER_CLIENT_ID", "")
-NAVER_CLIENT_SECRET = os.getenv("NAVER_CLIENT_SECRET", "")
-
-# Database
-DB_PATH = os.getenv("BLOG_DB_PATH", "/app/data/blog_marketing.db")
-
-# CORS
-CORS_ALLOW_ORIGINS = os.getenv("CORS_ALLOW_ORIGINS", "http://localhost:3007,http://localhost:8080")

blog-lab/app/content_generator.py

@@ -1,172 +0,0 @@
-"""Claude API 기반 콘텐츠 생성 — 트렌드 브리프 + 블로그 글 작성."""
-
-import json
-import logging
-from datetime import date
-from typing import Any, Dict, Optional
-
-import anthropic
-
-from .config import ANTHROPIC_API_KEY, CLAUDE_MODEL
-from .db import get_template
-
-logger = logging.getLogger(__name__)
-
-_client: Optional[anthropic.Anthropic] = None
-
-
-def _get_client() -> anthropic.Anthropic:
-    global _client
-    if _client is None:
-        _client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
-    return _client
-
-
-def _call_claude(prompt: str, max_tokens: int = 4096) -> str:
-    """Claude API 호출. 단일 user 메시지. 현재 날짜 시스템 프롬프트 포함."""
-    client = _get_client()
-    today = date.today().isoformat()
-    resp = client.messages.create(
-        model=CLAUDE_MODEL,
-        max_tokens=max_tokens,
-        system=f"현재 날짜는 {today}입니다. 모든 콘텐츠는 이 날짜 기준으로 작성하세요.",
-        messages=[{"role": "user", "content": prompt}],
-    )
-    return resp.content[0].text
-
-
-def generate_trend_brief(analysis: Dict[str, Any]) -> str:
-    """키워드 분석 데이터를 바탕으로 트렌드 브리프 생성."""
-    template = get_template("trend_brief")
-    if not template:
-        raise RuntimeError("trend_brief 템플릿이 없습니다")
-
-    top_blogs_text = "\n".join(
-        f"- {b.get('title', '')}" for b in analysis.get("top_blogs", [])
-    ) or "없음"
-
-    top_products_text = "\n".join(
-        f"- {p.get('title', '')} ({p.get('lprice', '?')}원, {p.get('mallName', '')})"
-        for p in analysis.get("top_products", [])
-    ) or "없음"
-
-    prompt = template.format(
-        keyword=analysis.get("keyword", ""),
-        competition=analysis.get("competition", 0),
-        opportunity=analysis.get("opportunity", 0),
-        top_blogs=top_blogs_text,
-        top_products=top_products_text,
-    )
-
-    return _call_claude(prompt)
-
-
-def _parse_blog_json(raw: str, keyword: str) -> Dict[str, str]:
-    """Claude 응답에서 블로그 JSON을 파싱."""
-    try:
-        text = raw.strip()
-        if text.startswith("```"):
-            lines = text.split("\n")
-            lines = [l for l in lines if not l.strip().startswith("```")]
-            text = "\n".join(lines)
-        result = json.loads(text)
-        return {
-            "title": result.get("title", ""),
-            "body": result.get("body", ""),
-            "excerpt": result.get("excerpt", ""),
-            "tags": result.get("tags", []),
-        }
-    except (json.JSONDecodeError, KeyError):
-        logger.warning("Blog post JSON parse failed, using raw text")
-        return {
-            "title": f"{keyword} 추천 리뷰",
-            "body": raw,
-            "excerpt": raw[:200],
-            "tags": [keyword],
-        }
-
-
-def generate_blog_post(
-    analysis: Dict[str, Any],
-    trend_brief: str,
-    brand_links: Optional[list] = None,
-) -> Dict[str, str]:
-    """트렌드 브리프를 바탕으로 블로그 글 작성.
-
-    Returns:
-        {"title": str, "body": str, "excerpt": str, "tags": [...]}
-    """
-    template = get_template("blog_write")
-    if not template:
-        raise RuntimeError("blog_write 템플릿이 없습니다")
-
-    top_products_text = "\n".join(
-        f"- {p.get('title', '')} ({p.get('lprice', '?')}원, {p.get('mallName', '')})"
-        for p in analysis.get("top_products", [])
-    ) or "없음"
-
-    # 크롤링된 블로그 본문 참고 자료
-    reference_blogs_text = ""
-    for blog in analysis.get("top_blogs", []):
-        content = blog.get("content", "")
-        if content:
-            reference_blogs_text += f"\n### {blog.get('title', '제목 없음')}\n{content}\n"
-    if not reference_blogs_text:
-        reference_blogs_text = "없음"
-
-    # 브랜드커넥트 링크 정보
-    brand_products_text = ""
-    if brand_links:
-        for link in brand_links:
-            brand_products_text += (
-                f"- 상품명: {link.get('product_name', '')}\n"
-                f"  설명: {link.get('description', '')}\n"
-                f"  링크: {link.get('url', '')}\n"
-                f"  배치 힌트: {link.get('placement_hint', '자연스럽게')}\n"
-            )
-    if not brand_products_text:
-        brand_products_text = "없음 (제휴 링크 없이 일반 리뷰로 작성)"
-
-    prompt = template.format(
-        keyword=analysis.get("keyword", ""),
-        trend_brief=trend_brief,
-        top_products=top_products_text,
-        reference_blogs=reference_blogs_text,
-        brand_products=brand_products_text,
-    )
-
-    # 구조화된 응답을 위한 추가 지시
-    prompt += (
-        "\n\n---\n"
-        "응답은 반드시 아래 JSON 형식으로 해주세요 (JSON만 출력, 다른 텍스트 없이):\n"
-        '{"title": "블로그 제목", "body": "HTML 본문", "excerpt": "2줄 요약", '
-        '"tags": ["태그1", "태그2", ...]}'
-    )
-
-    raw = _call_claude(prompt, max_tokens=8192)
-    return _parse_blog_json(raw, analysis.get("keyword", ""))
-
-
-def regenerate_blog_post(
-    analysis: Dict[str, Any],
-    trend_brief: str,
-    previous_body: str,
-    feedback: str,
-) -> Dict[str, str]:
-    """피드백을 반영하여 블로그 글 재생성."""
-    prompt = (
-        "당신은 네이버 블로그에서 월 100만 이상 수익을 올리는 전문 블로거입니다.\n"
-        f"키워드: {analysis.get('keyword', '')}\n\n"
-        f"이전에 작성한 글:\n{previous_body[:3000]}\n\n"
-        f"리뷰어 피드백:\n{feedback}\n\n"
-        "위 피드백을 반영하여 글을 개선해주세요.\n"
-        "작성 규칙: 1인칭 체험기, 2,000자 이상, 자연스러운 구어체, "
-        "제품 비교표 포함, 광고 고지 문구 포함.\n"
-        "HTML 형식으로 작성하되, 네이버 블로그에서 바로 붙여넣기 가능한 형태로.\n\n"
-        "---\n"
-        "응답은 반드시 아래 JSON 형식으로 해주세요 (JSON만 출력):\n"
-        '{"title": "블로그 제목", "body": "HTML 본문", "excerpt": "2줄 요약", '
-        '"tags": ["태그1", "태그2", ...]}'
-    )
-    raw = _call_claude(prompt, max_tokens=8192)
-    return _parse_blog_json(raw, analysis.get("keyword", ""))

blog-lab/app/db.py

@@ -1,789 +0,0 @@
-import os
-import sqlite3
-import json
-from typing import Any, Dict, List, Optional
-
-from .config import DB_PATH
-
-
-def _conn() -> sqlite3.Connection:
-    os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
-    conn = sqlite3.connect(DB_PATH)
-    conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA journal_mode=WAL")
-    return conn
-
-
-def init_db() -> None:
-    with _conn() as conn:
-        # 키워드/상품 분석 결과
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS keyword_analyses (
-                id              INTEGER PRIMARY KEY AUTOINCREMENT,
-                keyword         TEXT NOT NULL,
-                blog_total      INTEGER NOT NULL DEFAULT 0,
-                shop_total      INTEGER NOT NULL DEFAULT 0,
-                competition     REAL NOT NULL DEFAULT 0,
-                opportunity     REAL NOT NULL DEFAULT 0,
-                avg_price       INTEGER,
-                min_price       INTEGER,
-                max_price       INTEGER,
-                top_products    TEXT NOT NULL DEFAULT '[]',
-                top_blogs       TEXT NOT NULL DEFAULT '[]',
-                ai_summary      TEXT NOT NULL DEFAULT '',
-                created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_ka_created ON keyword_analyses(created_at DESC)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_ka_keyword ON keyword_analyses(keyword)")
-
-        # 블로그 포스트
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS blog_posts (
-                id              INTEGER PRIMARY KEY AUTOINCREMENT,
-                keyword_id      INTEGER REFERENCES keyword_analyses(id),
-                title           TEXT NOT NULL DEFAULT '',
-                body            TEXT NOT NULL DEFAULT '',
-                excerpt         TEXT NOT NULL DEFAULT '',
-                tags            TEXT NOT NULL DEFAULT '[]',
-                status          TEXT NOT NULL DEFAULT 'draft',
-                review_score    INTEGER,
-                review_detail   TEXT NOT NULL DEFAULT '{}',
-                naver_url       TEXT NOT NULL DEFAULT '',
-                trend_brief     TEXT NOT NULL DEFAULT '',
-                created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-                updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_bp_created ON blog_posts(created_at DESC)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_bp_status ON blog_posts(status)")
-
-        # 수익(커미션) 추적
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS commissions (
-                id              INTEGER PRIMARY KEY AUTOINCREMENT,
-                post_id         INTEGER REFERENCES blog_posts(id),
-                month           TEXT NOT NULL,
-                clicks          INTEGER NOT NULL DEFAULT 0,
-                purchases       INTEGER NOT NULL DEFAULT 0,
-                revenue         INTEGER NOT NULL DEFAULT 0,
-                note            TEXT NOT NULL DEFAULT '',
-                created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_comm_month ON commissions(month)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_comm_post ON commissions(post_id)")
-
-        # 비동기 작업 상태 (research / generate / review)
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS generation_tasks (
-                id              TEXT PRIMARY KEY,
-                type            TEXT NOT NULL DEFAULT 'research',
-                status          TEXT NOT NULL DEFAULT 'queued',
-                progress        INTEGER NOT NULL DEFAULT 0,
-                message         TEXT NOT NULL DEFAULT '',
-                result_id       INTEGER,
-                error           TEXT,
-                params          TEXT NOT NULL DEFAULT '{}',
-                created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
-                updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_gt_created ON generation_tasks(created_at DESC)")
-
-        # AI 프롬프트 템플릿
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS prompt_templates (
-                id              INTEGER PRIMARY KEY AUTOINCREMENT,
-                name            TEXT NOT NULL UNIQUE,
-                description     TEXT NOT NULL DEFAULT '',
-                template        TEXT NOT NULL DEFAULT '',
-                updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-
-        # 브랜드커넥트 제휴 링크
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS brand_links (
-                id              INTEGER PRIMARY KEY AUTOINCREMENT,
-                post_id         INTEGER REFERENCES blog_posts(id),
-                keyword_id      INTEGER REFERENCES keyword_analyses(id),
-                url             TEXT NOT NULL,
-                product_name    TEXT NOT NULL DEFAULT '',
-                description     TEXT NOT NULL DEFAULT '',
-                placement_hint  TEXT NOT NULL DEFAULT '',
-                created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-            )
-        """)
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_bl_post ON brand_links(post_id)")
-        conn.execute("CREATE INDEX IF NOT EXISTS idx_bl_keyword ON brand_links(keyword_id)")
-
-        # 기본 프롬프트 템플릿 시딩 (존재하지 않을 때만)
-        _seed_templates(conn)
-        _migrate_templates(conn)
-
-
-def _seed_templates(conn: sqlite3.Connection) -> None:
-    """기본 프롬프트 템플릿을 DB에 시딩."""
-    templates = [
-        {
-            "name": "trend_brief",
-            "description": "네이버 블로그 트렌드 분석 + 제목/훅 전략 브리프",
-            "template": (
-                "당신은 네이버 블로그 마케팅 전문가입니다.\n"
-                "아래 키워드 분석 데이터를 바탕으로 블로그 포스팅 전략 브리프를 작성하세요.\n\n"
-                "키워드: {keyword}\n"
-                "블로그 경쟁도: {competition} (0-100, 높을수록 경쟁 치열)\n"
-                "쇼핑 기회 점수: {opportunity} (0-100, 높을수록 기회 큼)\n"
-                "상위 블로그 제목들: {top_blogs}\n"
-                "상위 상품들: {top_products}\n\n"
-                "다음을 포함해주세요:\n"
-                "1. 클릭을 유도하는 제목 공식 3가지\n"
-                "2. 도입부 훅 전략 (공감형, 질문형, 충격형 중 추천)\n"
-                "3. 추천 해시태그 5-10개\n"
-                "4. 경쟁 분석 요약 (기존 글 대비 차별화 포인트)\n"
-                "5. SEO 키워드 배치 전략"
-            ),
-        },
-        {
-            "name": "blog_write",
-            "description": "공감형 1인칭 체험기 블로그 글 작성",
-            "template": (
-                "당신은 네이버 블로그에서 월 100만 이상 수익을 올리는 전문 블로거입니다.\n"
-                "아래 브리프를 바탕으로 블로그 글을 작성하세요.\n\n"
-                "키워드: {keyword}\n"
-                "트렌드 브리프: {trend_brief}\n"
-                "상위 상품 정보: {top_products}\n\n"
-                "작성 규칙:\n"
-                "- 1인칭 체험기 형식 (\"제가 직접 써봤는데요\")\n"
-                "- 1,500자 이상\n"
-                "- 자연스러운 구어체 (네이버 블로그 톤)\n"
-                "- 제품 비교표 포함 (마크다운 테이블)\n"
-                "- 장단점 솔직하게 작성\n"
-                "- 광고 고지 문구 포함: \"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.\"\n"
-                "- 추천 매트릭스 (가성비/품질/디자인 기준)\n"
-                "- 자연스러운 CTA (구매 링크 유도)\n\n"
-                "HTML 형식으로 작성하되, 네이버 블로그에서 바로 붙여넣기 가능한 형태로 만들어주세요."
-            ),
-        },
-        {
-            "name": "quality_review",
-            "description": "블로그 글 품질 리뷰 (6기준 × 10점)",
-            "template": (
-                "당신은 블로그 콘텐츠 품질 평가 전문가입니다.\n"
-                "아래 블로그 글을 6가지 기준으로 평가해주세요.\n\n"
-                "제목: {title}\n"
-                "본문: {body}\n\n"
-                "평가 기준 (각 1-10점):\n"
-                "1. 독자 공감도 (empathy): 1인칭 체험기가 자연스럽고 공감되는가?\n"
-                "2. 제목 클릭 유도력 (click_appeal): 검색 결과에서 클릭하고 싶은 제목인가?\n"
-                "3. 구매 전환력 (conversion): 읽고 나서 제품을 사고 싶어지는가?\n"
-                "4. SEO 최적화 (seo): 키워드 배치, 소제목, 길이가 적절한가?\n"
-                "5. 형식 완성도 (format): 비교표, 이미지 설명, 단락 구성이 잘 되어있는가?\n"
-                "6. 링크 자연스러움 (link_natural): 제휴 링크가 광고처럼 느껴지지 않고 자연스럽게 녹아있는가? (링크가 없으면 5점 기본)\n\n"
-                "JSON 형식으로 응답:\n"
-                "{{\n"
-                "  \"scores\": {{\n"
-                "    \"empathy\": N,\n"
-                "    \"click_appeal\": N,\n"
-                "    \"conversion\": N,\n"
-                "    \"seo\": N,\n"
-                "    \"format\": N,\n"
-                "    \"link_natural\": N\n"
-                "  }},\n"
-                "  \"total\": N,\n"
-                "  \"pass\": true/false,\n"
-                "  \"feedback\": \"개선 사항 설명\"\n"
-                "}}"
-            ),
-        },
-        {
-            "name": "marketer_enhance",
-            "description": "마케터 전환율 강화 + 제휴 링크 삽입",
-            "template": (
-                "당신은 네이버 블로그 수익화 전문 마케터입니다.\n"
-                "아래 블로그 초안에 제휴 링크를 자연스럽게 삽입하고 전환율을 강화하세요.\n\n"
-                "=== 블로그 초안 ===\n{draft_body}\n\n"
-                "=== 타겟 키워드 ===\n{keyword}\n\n"
-                "=== 삽입할 제휴 링크 ===\n{brand_links_info}\n\n"
-                "작업 규칙:\n"
-                "- 제휴 링크를 <a href=\"URL\" target=\"_blank\">상품명</a> 형태로 본문 흐름에 맞게 2~3곳 삽입\n"
-                "- 결론에 CTA(Call-to-Action) 블록 추가 (\"지금 확인하기\" 등)\n"
-                "- 글 맨 아래에 광고 고지 문구 자동 삽입: \"이 포스팅은 브랜드로부터 소정의 수수료를 받을 수 있습니다\"\n"
-                "- 작가의 1인칭 톤과 구어체를 유지\n"
-                "- 과도한 광고 느낌 없이 자연스러운 추천 흐름 유지\n"
-                "- 구매 심리를 자극하는 표현 강화 (한정 수량, 가격 비교, 실사용 만족도 등)\n"
-                "- 배치 힌트가 있으면 참고하되, 문맥이 더 자연스러운 위치 우선\n"
-                "- 기존 본문의 구조와 길이를 크게 변경하지 않음"
-            ),
-        },
-    ]
-    for t in templates:
-        existing = conn.execute(
-            "SELECT id FROM prompt_templates WHERE name = ?", (t["name"],)
-        ).fetchone()
-        if not existing:
-            conn.execute(
-                "INSERT INTO prompt_templates (name, description, template) VALUES (?, ?, ?)",
-                (t["name"], t["description"], t["template"]),
-            )
-
-
-def _migrate_templates(conn: sqlite3.Connection) -> None:
-    """기존 템플릿을 최신 버전으로 업데이트."""
-    new_blog_write = (
-        "당신은 네이버 블로그에서 월 100만 이상 수익을 올리는 전문 블로거입니다.\n"
-        "아래 브리프와 참고 자료를 바탕으로 블로그 글을 작성하세요.\n\n"
-        "키워드: {keyword}\n"
-        "트렌드 브리프: {trend_brief}\n\n"
-        "=== 상위 블로그 참고 자료 ===\n"
-        "{reference_blogs}\n\n"
-        "=== 상위 상품 정보 ===\n"
-        "{top_products}\n\n"
-        "=== 제휴 상품 (브랜드커넥트 링크) ===\n"
-        "{brand_products}\n\n"
-        "작성 규칙:\n"
-        "- 1인칭 체험기 형식 (\"제가 직접 써봤는데요\")\n"
-        "- 2,000자 이상\n"
-        "- 자연스러운 구어체 (네이버 블로그 톤)\n"
-        "- 상위 블로그 참고하되 표절 금지 (자신만의 시각으로 재구성)\n"
-        "- 제품 비교표 포함 (HTML 테이블)\n"
-        "- 장단점 솔직하게 작성\n"
-        "- 제휴 상품이 있으면 자연스럽게 체험 맥락에 녹여서 작성\n"
-        "- 제휴 링크는 <a> 태그로 자연스럽게 삽입\n"
-        "- 추천 매트릭스 (가성비/품질/디자인 기준)\n"
-        "- 자연스러운 CTA (구매 링크 유도)\n\n"
-        "HTML 형식으로 작성하되, 네이버 블로그에서 바로 붙여넣기 가능한 형태로 만들어주세요."
-    )
-    conn.execute(
-        "UPDATE prompt_templates SET template = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE name = 'blog_write'",
-        (new_blog_write,),
-    )
-
-    new_quality_review = (
-        "당신은 블로그 콘텐츠 품질 평가 전문가입니다.\n"
-        "아래 블로그 글을 6가지 기준으로 평가해주세요.\n\n"
-        "제목: {title}\n"
-        "본문: {body}\n\n"
-        "평가 기준 (각 1-10점):\n"
-        "1. 독자 공감도 (empathy): 1인칭 체험기가 자연스럽고 공감되는가?\n"
-        "2. 제목 클릭 유도력 (click_appeal): 검색 결과에서 클릭하고 싶은 제목인가?\n"
-        "3. 구매 전환력 (conversion): 읽고 나서 제품을 사고 싶어지는가?\n"
-        "4. SEO 최적화 (seo): 키워드 배치, 소제목, 길이가 적절한가?\n"
-        "5. 형식 완성도 (format): 비교표, 이미지 설명, 단락 구성이 잘 되어있는가?\n"
-        "6. 링크 자연스러움 (link_natural): 제휴 링크가 광고처럼 느껴지지 않고 자연스럽게 녹아있는가? (링크가 없으면 5점 기본)\n\n"
-        "JSON 형식으로 응답:\n"
-        "{{\n"
-        "  \"scores\": {{\n"
-        "    \"empathy\": N,\n"
-        "    \"click_appeal\": N,\n"
-        "    \"conversion\": N,\n"
-        "    \"seo\": N,\n"
-        "    \"format\": N,\n"
-        "    \"link_natural\": N\n"
-        "  }},\n"
-        "  \"total\": N,\n"
-        "  \"pass\": true/false,\n"
-        "  \"feedback\": \"개선 사항 설명\"\n"
-        "}}"
-    )
-    conn.execute(
-        "UPDATE prompt_templates SET template = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE name = 'quality_review'",
-        (new_quality_review,),
-    )
-
-    # marketer_enhance가 없으면 추가
-    existing = conn.execute("SELECT id FROM prompt_templates WHERE name = 'marketer_enhance'").fetchone()
-    if not existing:
-        conn.execute(
-            "INSERT INTO prompt_templates (name, description, template) VALUES (?, ?, ?)",
-            ("marketer_enhance", "마케터 전환율 강화 + 제휴 링크 삽입",
-             "당신은 네이버 블로그 수익화 전문 마케터입니다.\n"
-             "아래 블로그 초안에 제휴 링크를 자연스럽게 삽입하고 전환율을 강화하세요.\n\n"
-             "=== 블로그 초안 ===\n{draft_body}\n\n"
-             "=== 타겟 키워드 ===\n{keyword}\n\n"
-             "=== 삽입할 제휴 링크 ===\n{brand_links_info}\n\n"
-             "작업 규칙:\n"
-             "- 제휴 링크를 <a href=\"URL\" target=\"_blank\">상품명</a> 형태로 본문 흐름에 맞게 2~3곳 삽입\n"
-             "- 결론에 CTA(Call-to-Action) 블록 추가\n"
-             "- 글 맨 아래에 광고 고지 문구 자동 삽입\n"
-             "- 작가의 1인칭 톤과 구어체를 유지\n"
-             "- 과도한 광고 느낌 없이 자연스러운 추천 흐름 유지"),
-        )
-
-
-# ── keyword_analyses CRUD ────────────────────────────────────────────────────
-
-def _ka_row_to_dict(r) -> Dict[str, Any]:
-    return {
-        "id":           r["id"],
-        "keyword":      r["keyword"],
-        "blog_total":   r["blog_total"],
-        "shop_total":   r["shop_total"],
-        "competition":  r["competition"],
-        "opportunity":  r["opportunity"],
-        "avg_price":    r["avg_price"],
-        "min_price":    r["min_price"],
-        "max_price":    r["max_price"],
-        "top_products": json.loads(r["top_products"]) if r["top_products"] else [],
-        "top_blogs":    json.loads(r["top_blogs"]) if r["top_blogs"] else [],
-        "ai_summary":   r["ai_summary"],
-        "created_at":   r["created_at"],
-    }
-
-
-def add_keyword_analysis(data: Dict[str, Any]) -> Dict[str, Any]:
-    with _conn() as conn:
-        conn.execute(
-            """INSERT INTO keyword_analyses
-               (keyword, blog_total, shop_total, competition, opportunity,
-                avg_price, min_price, max_price, top_products, top_blogs, ai_summary)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (
-                data.get("keyword", ""),
-                data.get("blog_total", 0),
-                data.get("shop_total", 0),
-                data.get("competition", 0),
-                data.get("opportunity", 0),
-                data.get("avg_price"),
-                data.get("min_price"),
-                data.get("max_price"),
-                json.dumps(data.get("top_products", []), ensure_ascii=False),
-                json.dumps(data.get("top_blogs", []), ensure_ascii=False),
-                data.get("ai_summary", ""),
-            ),
-        )
-        row = conn.execute(
-            "SELECT * FROM keyword_analyses WHERE rowid = last_insert_rowid()"
-        ).fetchone()
-    return _ka_row_to_dict(row)
-
-
-def get_keyword_analysis(analysis_id: int) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT * FROM keyword_analyses WHERE id = ?", (analysis_id,)
-        ).fetchone()
-    return _ka_row_to_dict(row) if row else None
-
-
-def get_keyword_analyses(limit: int = 30) -> List[Dict[str, Any]]:
-    with _conn() as conn:
-        rows = conn.execute(
-            "SELECT * FROM keyword_analyses ORDER BY created_at DESC LIMIT ?", (limit,)
-        ).fetchall()
-    return [_ka_row_to_dict(r) for r in rows]
-
-
-def delete_keyword_analysis(analysis_id: int) -> bool:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT id FROM keyword_analyses WHERE id = ?", (analysis_id,)
-        ).fetchone()
-        if not row:
-            return False
-        conn.execute("DELETE FROM keyword_analyses WHERE id = ?", (analysis_id,))
-    return True
-
-
-# ── blog_posts CRUD ──────────────────────────────────────────────────────────
-
-def _post_row_to_dict(r) -> Dict[str, Any]:
-    return {
-        "id":            r["id"],
-        "keyword_id":    r["keyword_id"],
-        "title":         r["title"],
-        "body":          r["body"],
-        "excerpt":       r["excerpt"],
-        "tags":          json.loads(r["tags"]) if r["tags"] else [],
-        "status":        r["status"],
-        "review_score":  r["review_score"],
-        "review_detail": json.loads(r["review_detail"]) if r["review_detail"] else {},
-        "naver_url":     r["naver_url"],
-        "trend_brief":   r["trend_brief"],
-        "created_at":    r["created_at"],
-        "updated_at":    r["updated_at"],
-    }
-
-
-def add_post(data: Dict[str, Any]) -> Dict[str, Any]:
-    with _conn() as conn:
-        conn.execute(
-            """INSERT INTO blog_posts
-               (keyword_id, title, body, excerpt, tags, status, review_score,
-                review_detail, naver_url, trend_brief)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (
-                data.get("keyword_id"),
-                data.get("title", ""),
-                data.get("body", ""),
-                data.get("excerpt", ""),
-                json.dumps(data.get("tags", []), ensure_ascii=False),
-                data.get("status", "draft"),
-                data.get("review_score"),
-                json.dumps(data.get("review_detail", {}), ensure_ascii=False),
-                data.get("naver_url", ""),
-                data.get("trend_brief", ""),
-            ),
-        )
-        row = conn.execute(
-            "SELECT * FROM blog_posts WHERE rowid = last_insert_rowid()"
-        ).fetchone()
-    return _post_row_to_dict(row)
-
-
-def get_post(post_id: int) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT * FROM blog_posts WHERE id = ?", (post_id,)
-        ).fetchone()
-    return _post_row_to_dict(row) if row else None
-
-
-def get_posts(status: Optional[str] = None, limit: int = 50) -> List[Dict[str, Any]]:
-    with _conn() as conn:
-        if status:
-            rows = conn.execute(
-                "SELECT * FROM blog_posts WHERE status = ? ORDER BY created_at DESC LIMIT ?",
-                (status, limit),
-            ).fetchall()
-        else:
-            rows = conn.execute(
-                "SELECT * FROM blog_posts ORDER BY created_at DESC LIMIT ?", (limit,)
-            ).fetchall()
-    return [_post_row_to_dict(r) for r in rows]
-
-
-def update_post(post_id: int, data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        fields = []
-        values = []
-        for k in ("title", "body", "excerpt", "status", "naver_url", "trend_brief"):
-            if k in data:
-                fields.append(f"{k} = ?")
-                values.append(data[k])
-        if "tags" in data:
-            fields.append("tags = ?")
-            values.append(json.dumps(data["tags"], ensure_ascii=False))
-        if "review_score" in data:
-            fields.append("review_score = ?")
-            values.append(data["review_score"])
-        if "review_detail" in data:
-            fields.append("review_detail = ?")
-            values.append(json.dumps(data["review_detail"], ensure_ascii=False))
-        if not fields:
-            return get_post(post_id)
-        fields.append("updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')")
-        values.append(post_id)
-        conn.execute(
-            f"UPDATE blog_posts SET {', '.join(fields)} WHERE id = ?", values
-        )
-        row = conn.execute(
-            "SELECT * FROM blog_posts WHERE id = ?", (post_id,)
-        ).fetchone()
-    return _post_row_to_dict(row) if row else None
-
-
-def delete_post(post_id: int) -> bool:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT id FROM blog_posts WHERE id = ?", (post_id,)
-        ).fetchone()
-        if not row:
-            return False
-        conn.execute("DELETE FROM blog_posts WHERE id = ?", (post_id,))
-    return True
-
-
-# ── commissions CRUD ─────────────────────────────────────────────────────────
-
-def _comm_row_to_dict(r) -> Dict[str, Any]:
-    return {
-        "id":         r["id"],
-        "post_id":    r["post_id"],
-        "month":      r["month"],
-        "clicks":     r["clicks"],
-        "purchases":  r["purchases"],
-        "revenue":    r["revenue"],
-        "note":       r["note"],
-        "created_at": r["created_at"],
-    }
-
-
-def add_commission(data: Dict[str, Any]) -> Dict[str, Any]:
-    with _conn() as conn:
-        conn.execute(
-            """INSERT INTO commissions (post_id, month, clicks, purchases, revenue, note)
-            VALUES (?, ?, ?, ?, ?, ?)""",
-            (
-                data.get("post_id"),
-                data.get("month", ""),
-                data.get("clicks", 0),
-                data.get("purchases", 0),
-                data.get("revenue", 0),
-                data.get("note", ""),
-            ),
-        )
-        row = conn.execute(
-            "SELECT * FROM commissions WHERE rowid = last_insert_rowid()"
-        ).fetchone()
-    return _comm_row_to_dict(row)
-
-
-def get_commissions(post_id: Optional[int] = None, limit: int = 100) -> List[Dict[str, Any]]:
-    with _conn() as conn:
-        if post_id:
-            rows = conn.execute(
-                "SELECT * FROM commissions WHERE post_id = ? ORDER BY month DESC LIMIT ?",
-                (post_id, limit),
-            ).fetchall()
-        else:
-            rows = conn.execute(
-                "SELECT * FROM commissions ORDER BY month DESC LIMIT ?", (limit,)
-            ).fetchall()
-    return [_comm_row_to_dict(r) for r in rows]
-
-
-def update_commission(comm_id: int, data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        fields = []
-        values = []
-        for k in ("month", "clicks", "purchases", "revenue", "note"):
-            if k in data:
-                fields.append(f"{k} = ?")
-                values.append(data[k])
-        if not fields:
-            return None
-        values.append(comm_id)
-        conn.execute(
-            f"UPDATE commissions SET {', '.join(fields)} WHERE id = ?", values
-        )
-        row = conn.execute(
-            "SELECT * FROM commissions WHERE id = ?", (comm_id,)
-        ).fetchone()
-    return _comm_row_to_dict(row) if row else None
-
-
-def delete_commission(comm_id: int) -> bool:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT id FROM commissions WHERE id = ?", (comm_id,)
-        ).fetchone()
-        if not row:
-            return False
-        conn.execute("DELETE FROM commissions WHERE id = ?", (comm_id,))
-    return True
-
-
-# ── brand_links CRUD ────────────────────────────────────────────────────────
-
-def _bl_row_to_dict(r) -> Dict[str, Any]:
-    return {
-        "id":             r["id"],
-        "post_id":        r["post_id"],
-        "keyword_id":     r["keyword_id"],
-        "url":            r["url"],
-        "product_name":   r["product_name"],
-        "description":    r["description"],
-        "placement_hint": r["placement_hint"],
-        "created_at":     r["created_at"],
-    }
-
-
-def add_brand_link(data: Dict[str, Any]) -> Dict[str, Any]:
-    with _conn() as conn:
-        conn.execute(
-            """INSERT INTO brand_links (post_id, keyword_id, url, product_name, description, placement_hint)
-            VALUES (?, ?, ?, ?, ?, ?)""",
-            (
-                data.get("post_id"),
-                data.get("keyword_id"),
-                data.get("url", ""),
-                data.get("product_name", ""),
-                data.get("description", ""),
-                data.get("placement_hint", ""),
-            ),
-        )
-        row = conn.execute(
-            "SELECT * FROM brand_links WHERE rowid = last_insert_rowid()"
-        ).fetchone()
-    return _bl_row_to_dict(row)
-
-
-def get_brand_links(
-    post_id: Optional[int] = None,
-    keyword_id: Optional[int] = None,
-) -> List[Dict[str, Any]]:
-    with _conn() as conn:
-        if post_id is not None:
-            rows = conn.execute(
-                "SELECT * FROM brand_links WHERE post_id = ? ORDER BY id", (post_id,)
-            ).fetchall()
-        elif keyword_id is not None:
-            rows = conn.execute(
-                "SELECT * FROM brand_links WHERE keyword_id = ? ORDER BY id", (keyword_id,)
-            ).fetchall()
-        else:
-            rows = conn.execute("SELECT * FROM brand_links ORDER BY id DESC LIMIT 100").fetchall()
-    return [_bl_row_to_dict(r) for r in rows]
-
-
-def update_brand_link(link_id: int, data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        fields = []
-        values = []
-        for k in ("post_id", "keyword_id", "url", "product_name", "description", "placement_hint"):
-            if k in data:
-                fields.append(f"{k} = ?")
-                values.append(data[k])
-        if not fields:
-            row = conn.execute("SELECT * FROM brand_links WHERE id = ?", (link_id,)).fetchone()
-            return _bl_row_to_dict(row) if row else None
-        values.append(link_id)
-        conn.execute(f"UPDATE brand_links SET {', '.join(fields)} WHERE id = ?", values)
-        row = conn.execute("SELECT * FROM brand_links WHERE id = ?", (link_id,)).fetchone()
-    return _bl_row_to_dict(row) if row else None
-
-
-def delete_brand_link(link_id: int) -> bool:
-    with _conn() as conn:
-        row = conn.execute("SELECT id FROM brand_links WHERE id = ?", (link_id,)).fetchone()
-        if not row:
-            return False
-        conn.execute("DELETE FROM brand_links WHERE id = ?", (link_id,))
-    return True
-
-
-def link_brand_links_to_post(keyword_id: int, post_id: int) -> None:
-    """keyword_id로 등록된 링크들을 post_id에도 연결."""
-    with _conn() as conn:
-        conn.execute(
-            "UPDATE brand_links SET post_id = ? WHERE keyword_id = ? AND post_id IS NULL",
-            (post_id, keyword_id),
-        )
-
-
-def get_dashboard_stats() -> Dict[str, Any]:
-    """대시보드 집계: 총 포스트/클릭/구매/수익 + 월별 추이."""
-    with _conn() as conn:
-        total_posts = conn.execute("SELECT COUNT(*) FROM blog_posts").fetchone()[0]
-        published = conn.execute(
-            "SELECT COUNT(*) FROM blog_posts WHERE status = 'published'"
-        ).fetchone()[0]
-
-        agg = conn.execute(
-            "SELECT COALESCE(SUM(clicks),0), COALESCE(SUM(purchases),0), COALESCE(SUM(revenue),0) FROM commissions"
-        ).fetchone()
-
-        monthly = conn.execute(
-            """SELECT month, SUM(clicks) as clicks, SUM(purchases) as purchases, SUM(revenue) as revenue
-               FROM commissions GROUP BY month ORDER BY month DESC LIMIT 12"""
-        ).fetchall()
-
-        top_posts = conn.execute(
-            """SELECT bp.id, bp.title, COALESCE(SUM(c.revenue),0) as total_revenue
-               FROM blog_posts bp LEFT JOIN commissions c ON c.post_id = bp.id
-               GROUP BY bp.id ORDER BY total_revenue DESC LIMIT 5"""
-        ).fetchall()
-
-    return {
-        "total_posts": total_posts,
-        "published_posts": published,
-        "total_clicks": agg[0],
-        "total_purchases": agg[1],
-        "total_revenue": agg[2],
-        "monthly": [
-            {"month": r["month"], "clicks": r["clicks"], "purchases": r["purchases"], "revenue": r["revenue"]}
-            for r in monthly
-        ],
-        "top_posts": [
-            {"id": r["id"], "title": r["title"], "total_revenue": r["total_revenue"]}
-            for r in top_posts
-        ],
-    }
-
-
-# ── generation_tasks CRUD ────────────────────────────────────────────────────
-
-def _task_row_to_dict(r) -> Dict[str, Any]:
-    return {
-        "task_id":    r["id"],
-        "type":       r["type"],
-        "status":     r["status"],
-        "progress":   r["progress"],
-        "message":    r["message"],
-        "result_id":  r["result_id"],
-        "error":      r["error"],
-        "params":     json.loads(r["params"]) if r["params"] else {},
-        "created_at": r["created_at"],
-        "updated_at": r["updated_at"],
-    }
-
-
-def create_task(task_id: str, task_type: str, params: Dict[str, Any]) -> Dict[str, Any]:
-    with _conn() as conn:
-        conn.execute(
-            "INSERT INTO generation_tasks (id, type, params) VALUES (?, ?, ?)",
-            (task_id, task_type, json.dumps(params, ensure_ascii=False)),
-        )
-        row = conn.execute(
-            "SELECT * FROM generation_tasks WHERE id = ?", (task_id,)
-        ).fetchone()
-    return _task_row_to_dict(row)
-
-
-def update_task(
-    task_id: str,
-    status: str,
-    progress: int,
-    message: str,
-    result_id: Optional[int] = None,
-    error: Optional[str] = None,
-) -> None:
-    with _conn() as conn:
-        conn.execute(
-            """UPDATE generation_tasks
-               SET status = ?, progress = ?, message = ?, result_id = ?, error = ?,
-                   updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')
-               WHERE id = ?""",
-            (status, progress, message, result_id, error, task_id),
-        )
-
-
-def get_task(task_id: str) -> Optional[Dict[str, Any]]:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT * FROM generation_tasks WHERE id = ?", (task_id,)
-        ).fetchone()
-    return _task_row_to_dict(row) if row else None
-
-
-# ── prompt_templates CRUD ────────────────────────────────────────────────────
-
-def get_template(name: str) -> Optional[str]:
-    with _conn() as conn:
-        row = conn.execute(
-            "SELECT template FROM prompt_templates WHERE name = ?", (name,)
-        ).fetchone()
-    return row["template"] if row else None
-
-
-def get_all_templates() -> List[Dict[str, Any]]:
-    with _conn() as conn:
-        rows = conn.execute("SELECT * FROM prompt_templates ORDER BY name").fetchall()
-    return [
-        {"id": r["id"], "name": r["name"], "description": r["description"],
-         "template": r["template"], "updated_at": r["updated_at"]}
-        for r in rows
-    ]
-
-
-def update_template(name: str, template: str) -> bool:
-    with _conn() as conn:
-        conn.execute(
-            "UPDATE prompt_templates SET template = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE name = ?",
-            (template, name),
-        )
-        return conn.execute(
-            "SELECT id FROM prompt_templates WHERE name = ?", (name,)
-        ).fetchone() is not None

blog-lab/app/main.py

@@ -1,440 +0,0 @@
-import os
-import uuid
-import logging
-from fastapi import FastAPI, HTTPException, BackgroundTasks, Query
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
-from typing import List, Optional
-
-from .config import CORS_ALLOW_ORIGINS, NAVER_CLIENT_ID, ANTHROPIC_API_KEY
-from .db import (
-    init_db,
-    get_keyword_analyses, get_keyword_analysis, delete_keyword_analysis,
-    add_keyword_analysis,
-    get_posts, get_post, add_post, update_post, delete_post,
-    get_commissions, add_commission, update_commission, delete_commission,
-    get_dashboard_stats,
-    get_task, create_task, update_task,
-    add_brand_link, get_brand_links, update_brand_link, delete_brand_link,
-    link_brand_links_to_post,
-)
-from .naver_search import analyze_keyword_with_crawling
-from .content_generator import generate_trend_brief, generate_blog_post, regenerate_blog_post
-from .quality_reviewer import review_post
-from .marketer import enhance_for_conversion
-
-logger = logging.getLogger(__name__)
-
-app = FastAPI()
-
-_cors_origins = CORS_ALLOW_ORIGINS.split(",")
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=[o.strip() for o in _cors_origins],
-    allow_credentials=False,
-    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-    allow_headers=["Content-Type"],
-)
-
-
-@app.on_event("startup")
-def on_startup():
-    init_db()
-    os.makedirs("/app/data", exist_ok=True)
-
-
-@app.get("/health")
-def health():
-    return {"ok": True}
-
-
-@app.get("/api/blog-marketing/status")
-def service_status():
-    """서비스 상태 및 설정 현황."""
-    return {
-        "ok": True,
-        "naver_api": bool(NAVER_CLIENT_ID),
-        "claude_api": bool(ANTHROPIC_API_KEY),
-    }
-
-
-# ── 키워드 분석 API ──────────────────────────────────────────────────────────
-
-class ResearchRequest(BaseModel):
-    keyword: str
-
-
-def _run_research(task_id: str, keyword: str):
-    """BackgroundTask: 네이버 검색 → 키워드 분석 → DB 저장."""
-    try:
-        update_task(task_id, "processing", 30, "네이버 검색 중...")
-        result = analyze_keyword_with_crawling(keyword)
-
-        update_task(task_id, "processing", 80, "분석 결과 저장 중...")
-        saved = add_keyword_analysis(result)
-
-        update_task(task_id, "succeeded", 100, "분석 완료", result_id=saved["id"])
-    except Exception as e:
-        logger.exception("Research failed for keyword=%s", keyword)
-        update_task(task_id, "failed", 0, "", error=str(e))
-
-
-@app.post("/api/blog-marketing/research")
-def start_research(req: ResearchRequest, background_tasks: BackgroundTasks):
-    """키워드 분석 시작 (BackgroundTask). task_id 즉시 반환."""
-    if not NAVER_CLIENT_ID:
-        raise HTTPException(status_code=400, detail="Naver API 키가 설정되지 않았습니다")
-    if not req.keyword.strip():
-        raise HTTPException(status_code=400, detail="키워드를 입력하세요")
-
-    task_id = str(uuid.uuid4())
-    create_task(task_id, "research", {"keyword": req.keyword.strip()})
-    background_tasks.add_task(_run_research, task_id, req.keyword.strip())
-    return {"task_id": task_id}
-
-
-@app.get("/api/blog-marketing/research/history")
-def list_research(limit: int = Query(30, ge=1, le=100)):
-    return {"analyses": get_keyword_analyses(limit)}
-
-
-@app.get("/api/blog-marketing/research/{analysis_id}")
-def get_research(analysis_id: int):
-    result = get_keyword_analysis(analysis_id)
-    if not result:
-        raise HTTPException(status_code=404, detail="Analysis not found")
-    return result
-
-
-@app.delete("/api/blog-marketing/research/{analysis_id}")
-def remove_research(analysis_id: int):
-    if not delete_keyword_analysis(analysis_id):
-        raise HTTPException(status_code=404, detail="Analysis not found")
-    return {"ok": True}
-
-
-# ── 작업 상태 폴링 API ──────────────────────────────────────────────────────
-
-@app.get("/api/blog-marketing/task/{task_id}")
-def get_task_status(task_id: str):
-    task = get_task(task_id)
-    if not task:
-        raise HTTPException(status_code=404, detail="Task not found")
-    return task
-
-
-# ── AI 글 생성 API ──────────────────────────────────────────────────────────
-
-class GenerateRequest(BaseModel):
-    keyword_id: int  # keyword_analyses.id
-
-
-class LinkRequest(BaseModel):
-    url: str
-    product_name: str
-    keyword_id: Optional[int] = None
-    post_id: Optional[int] = None
-    description: str = ""
-    placement_hint: str = ""
-
-
-def _run_generate(task_id: str, keyword_id: int):
-    """BackgroundTask: 트렌드 브리프 → 블로그 글 생성 → DB 저장."""
-    try:
-        analysis = get_keyword_analysis(keyword_id)
-        if not analysis:
-            update_task(task_id, "failed", 0, "", error="키워드 분석 결과를 찾을 수 없습니다")
-            return
-
-        # 연결된 브랜드커넥트 링크 조회
-        brand_links = get_brand_links(keyword_id=keyword_id)
-
-        update_task(task_id, "processing", 20, "트렌드 브리프 생성 중...")
-        trend_brief = generate_trend_brief(analysis)
-
-        update_task(task_id, "processing", 60, "블로그 글 작성 중...")
-        post_data = generate_blog_post(analysis, trend_brief, brand_links=brand_links)
-
-        update_task(task_id, "processing", 90, "저장 중...")
-        saved = add_post({
-            "keyword_id": keyword_id,
-            "title": post_data["title"],
-            "body": post_data["body"],
-            "excerpt": post_data["excerpt"],
-            "tags": post_data["tags"],
-            "status": "draft",
-            "trend_brief": trend_brief,
-        })
-
-        # keyword_id에 연결된 링크를 post_id에도 연결
-        link_brand_links_to_post(keyword_id=keyword_id, post_id=saved["id"])
-
-        update_task(task_id, "succeeded", 100, "글 생성 완료", result_id=saved["id"])
-    except Exception as e:
-        logger.exception("Generate failed for keyword_id=%s", keyword_id)
-        update_task(task_id, "failed", 0, "", error=str(e))
-
-
-@app.post("/api/blog-marketing/generate")
-def start_generate(req: GenerateRequest, background_tasks: BackgroundTasks):
-    """AI 블로그 글 생성 시작. task_id 즉시 반환."""
-    if not ANTHROPIC_API_KEY:
-        raise HTTPException(status_code=400, detail="Claude API 키가 설정되지 않았습니다")
-    analysis = get_keyword_analysis(req.keyword_id)
-    if not analysis:
-        raise HTTPException(status_code=404, detail="키워드 분석 결과를 찾을 수 없습니다")
-
-    task_id = str(uuid.uuid4())
-    create_task(task_id, "generate", {"keyword_id": req.keyword_id})
-    background_tasks.add_task(_run_generate, task_id, req.keyword_id)
-    return {"task_id": task_id}
-
-
-# ── 품질 리뷰 API ───────────────────────────────────────────────────────────
-
-def _run_review(task_id: str, post_id: int):
-    """BackgroundTask: 블로그 글 품질 리뷰."""
-    try:
-        post = get_post(post_id)
-        if not post:
-            update_task(task_id, "failed", 0, "", error="포스트를 찾을 수 없습니다")
-            return
-
-        update_task(task_id, "processing", 50, "품질 리뷰 중...")
-        result = review_post(post["title"], post["body"])
-
-        update_post(post_id, {
-            "review_score": result["total"],
-            "review_detail": result,
-            "status": "reviewed" if result["pass"] else "draft",
-        })
-
-        update_task(task_id, "succeeded", 100, "리뷰 완료", result_id=post_id)
-    except Exception as e:
-        logger.exception("Review failed for post_id=%s", post_id)
-        update_task(task_id, "failed", 0, "", error=str(e))
-
-
-@app.post("/api/blog-marketing/review/{post_id}")
-def start_review(post_id: int, background_tasks: BackgroundTasks):
-    """블로그 글 품질 리뷰 시작. task_id 즉시 반환."""
-    if not ANTHROPIC_API_KEY:
-        raise HTTPException(status_code=400, detail="Claude API 키가 설정되지 않았습니다")
-    post = get_post(post_id)
-    if not post:
-        raise HTTPException(status_code=404, detail="Post not found")
-
-    task_id = str(uuid.uuid4())
-    create_task(task_id, "review", {"post_id": post_id})
-    background_tasks.add_task(_run_review, task_id, post_id)
-    return {"task_id": task_id}
-
-
-# ── 재생성 API ───────────────────────────────────────────────────────────────
-
-def _run_regenerate(task_id: str, post_id: int):
-    """BackgroundTask: 피드백 기반 블로그 글 재생성."""
-    try:
-        post = get_post(post_id)
-        if not post:
-            update_task(task_id, "failed", 0, "", error="포스트를 찾을 수 없습니다")
-            return
-
-        analysis = get_keyword_analysis(post["keyword_id"]) if post["keyword_id"] else {}
-        feedback = post.get("review_detail", {}).get("feedback", "개선이 필요합니다")
-
-        update_task(task_id, "processing", 50, "글 재생성 중...")
-        result = regenerate_blog_post(
-            analysis or {"keyword": ""},
-            post.get("trend_brief", ""),
-            post["body"],
-            feedback,
-        )
-
-        update_post(post_id, {
-            "title": result["title"],
-            "body": result["body"],
-            "excerpt": result["excerpt"],
-            "tags": result["tags"],
-            "status": "draft",
-            "review_score": None,
-            "review_detail": {},
-        })
-
-        update_task(task_id, "succeeded", 100, "재생성 완료", result_id=post_id)
-    except Exception as e:
-        logger.exception("Regenerate failed for post_id=%s", post_id)
-        update_task(task_id, "failed", 0, "", error=str(e))
-
-
-@app.post("/api/blog-marketing/regenerate/{post_id}")
-def start_regenerate(post_id: int, background_tasks: BackgroundTasks):
-    """피드백 기반 블로그 글 재생성. task_id 즉시 반환."""
-    if not ANTHROPIC_API_KEY:
-        raise HTTPException(status_code=400, detail="Claude API 키가 설정되지 않았습니다")
-    post = get_post(post_id)
-    if not post:
-        raise HTTPException(status_code=404, detail="Post not found")
-
-    task_id = str(uuid.uuid4())
-    create_task(task_id, "regenerate", {"post_id": post_id})
-    background_tasks.add_task(_run_regenerate, task_id, post_id)
-    return {"task_id": task_id}
-
-
-# ── 포스트 CRUD API ──────────────────────────────────────────────────────────
-
-@app.get("/api/blog-marketing/posts")
-def list_posts(status: str = None, limit: int = Query(50, ge=1, le=100)):
-    return {"posts": get_posts(status=status, limit=limit)}
-
-
-@app.get("/api/blog-marketing/posts/{post_id}")
-def get_post_detail(post_id: int):
-    post = get_post(post_id)
-    if not post:
-        raise HTTPException(status_code=404, detail="Post not found")
-    return post
-
-
-@app.put("/api/blog-marketing/posts/{post_id}")
-def edit_post(post_id: int, data: dict):
-    result = update_post(post_id, data)
-    if not result:
-        raise HTTPException(status_code=404, detail="Post not found")
-    return result
-
-
-@app.delete("/api/blog-marketing/posts/{post_id}")
-def remove_post(post_id: int):
-    if not delete_post(post_id):
-        raise HTTPException(status_code=404, detail="Post not found")
-    return {"ok": True}
-
-
-@app.post("/api/blog-marketing/posts/{post_id}/publish")
-def publish_post(post_id: int, data: dict = None):
-    """네이버 URL 등록 + 상태를 published로 변경."""
-    naver_url = (data or {}).get("naver_url", "")
-    result = update_post(post_id, {"status": "published", "naver_url": naver_url})
-    if not result:
-        raise HTTPException(status_code=404, detail="Post not found")
-    return result
-
-
-# ── 브랜드커넥트 링크 API ──────────────────────────────────────────────────
-
-@app.post("/api/blog-marketing/links", status_code=201)
-def create_link(req: LinkRequest):
-    return add_brand_link(req.model_dump())
-
-
-@app.get("/api/blog-marketing/links")
-def list_links(post_id: int = None, keyword_id: int = None):
-    return {"links": get_brand_links(post_id=post_id, keyword_id=keyword_id)}
-
-
-@app.put("/api/blog-marketing/links/{link_id}")
-def edit_link(link_id: int, data: dict):
-    result = update_brand_link(link_id, data)
-    if not result:
-        raise HTTPException(status_code=404, detail="Link not found")
-    return result
-
-
-@app.delete("/api/blog-marketing/links/{link_id}")
-def remove_link(link_id: int):
-    if not delete_brand_link(link_id):
-        raise HTTPException(status_code=404, detail="Link not found")
-    return {"ok": True}
-
-
-# ── 마케터 API ──────────────────────────────────────────────────────────────
-
-def _run_market(task_id: str, post_id: int):
-    """BackgroundTask: 마케터 전환율 강화."""
-    try:
-        post = get_post(post_id)
-        if not post:
-            update_task(task_id, "failed", 0, "", error="포스트를 찾을 수 없습니다")
-            return
-
-        brand_links = get_brand_links(post_id=post_id)
-        if not brand_links and post.get("keyword_id"):
-            brand_links = get_brand_links(keyword_id=post["keyword_id"])
-
-        if not brand_links:
-            update_task(task_id, "failed", 0, "", error="브랜드커넥트 링크가 없습니다. 먼저 링크를 등록하세요.")
-            return
-
-        analysis = get_keyword_analysis(post["keyword_id"]) if post.get("keyword_id") else {}
-        keyword = (analysis or {}).get("keyword", "")
-
-        update_task(task_id, "processing", 50, "마케터가 전환율 강화 중...")
-        result = enhance_for_conversion(
-            post_body=post["body"],
-            post_title=post["title"],
-            brand_links=brand_links,
-            keyword=keyword,
-        )
-
-        update_post(post_id, {
-            "title": result["title"],
-            "body": result["body"],
-            "excerpt": result["excerpt"],
-            "status": "marketed",
-        })
-
-        update_task(task_id, "succeeded", 100, "마케팅 강화 완료", result_id=post_id)
-    except Exception as e:
-        logger.exception("Market failed for post_id=%s", post_id)
-        update_task(task_id, "failed", 0, "", error=str(e))
-
-
-@app.post("/api/blog-marketing/market/{post_id}")
-def start_market(post_id: int, background_tasks: BackgroundTasks):
-    """마케터 단계 실행. task_id 즉시 반환."""
-    if not ANTHROPIC_API_KEY:
-        raise HTTPException(status_code=400, detail="Claude API 키가 설정되지 않았습니다")
-    post = get_post(post_id)
-    if not post:
-        raise HTTPException(status_code=404, detail="Post not found")
-
-    task_id = str(uuid.uuid4())
-    create_task(task_id, "market", {"post_id": post_id})
-    background_tasks.add_task(_run_market, task_id, post_id)
-    return {"task_id": task_id}
-
-
-# ── 수익 추적 API ────────────────────────────────────────────────────────────
-
-@app.get("/api/blog-marketing/commissions")
-def list_commissions(post_id: int = None, limit: int = Query(100, ge=1, le=100)):
-    return {"commissions": get_commissions(post_id=post_id, limit=limit)}
-
-
-@app.post("/api/blog-marketing/commissions", status_code=201)
-def create_commission(data: dict):
-    return add_commission(data)
-
-
-@app.put("/api/blog-marketing/commissions/{comm_id}")
-def edit_commission(comm_id: int, data: dict):
-    result = update_commission(comm_id, data)
-    if not result:
-        raise HTTPException(status_code=404, detail="Commission not found")
-    return result
-
-
-@app.delete("/api/blog-marketing/commissions/{comm_id}")
-def remove_commission(comm_id: int):
-    if not delete_commission(comm_id):
-        raise HTTPException(status_code=404, detail="Commission not found")
-    return {"ok": True}
-
-
-# ── 대시보드 API ─────────────────────────────────────────────────────────────
-
-@app.get("/api/blog-marketing/dashboard")
-def dashboard():
-    return get_dashboard_stats()

blog-lab/app/marketer.py

@@ -1,105 +0,0 @@
-"""마케터 단계 — 전환율 강화 + 브랜드커넥트 링크 삽입."""
-
-import json
-import logging
-from datetime import date
-from typing import Any, Dict, List, Optional
-
-import anthropic
-
-from .config import ANTHROPIC_API_KEY, CLAUDE_MODEL
-from .db import get_template
-
-logger = logging.getLogger(__name__)
-
-_client: Optional[anthropic.Anthropic] = None
-
-
-def _get_client() -> anthropic.Anthropic:
-    global _client
-    if _client is None:
-        _client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
-    return _client
-
-
-def _call_claude(prompt: str, max_tokens: int = 8192) -> str:
-    client = _get_client()
-    today = date.today().isoformat()
-    resp = client.messages.create(
-        model=CLAUDE_MODEL,
-        max_tokens=max_tokens,
-        system=f"현재 날짜는 {today}입니다. 모든 콘텐츠는 이 날짜 기준으로 작성하세요.",
-        messages=[{"role": "user", "content": prompt}],
-    )
-    return resp.content[0].text
-
-
-def enhance_for_conversion(
-    post_body: str,
-    post_title: str,
-    brand_links: List[Dict[str, Any]],
-    keyword: str,
-) -> Dict[str, str]:
-    """초안에 제휴 링크를 자연스럽게 삽입하고 전환율을 강화.
-
-    Args:
-        post_body: 작가 초안 HTML 본문
-        post_title: 작가 초안 제목
-        brand_links: 브랜드커넥트 링크 리스트
-        keyword: 타겟 키워드
-
-    Returns:
-        {"title": str, "body": str, "excerpt": str}
-
-    Raises:
-        ValueError: 브랜드 링크가 없을 때
-    """
-    if not brand_links:
-        raise ValueError("브랜드커넥트 링크가 필요합니다")
-
-    template = get_template("marketer_enhance")
-    if not template:
-        raise RuntimeError("marketer_enhance 템플릿이 없습니다")
-
-    brand_links_text = ""
-    for i, link in enumerate(brand_links, 1):
-        brand_links_text += (
-            f"{i}. 상품명: {link.get('product_name', '')}\n"
-            f"   설명: {link.get('description', '')}\n"
-            f"   URL: {link.get('url', '')}\n"
-            f"   배치 힌트: {link.get('placement_hint', '자연스럽게')}\n\n"
-        )
-
-    prompt = template.format(
-        draft_body=post_body[:6000],
-        keyword=keyword,
-        brand_links_info=brand_links_text,
-    )
-
-    prompt += (
-        "\n\n---\n"
-        "응답은 반드시 아래 JSON 형식으로 해주세요 (JSON만 출력):\n"
-        '{"title": "개선된 제목", "body": "개선된 HTML 본문", "excerpt": "2줄 요약"}'
-    )
-
-    raw = _call_claude(prompt)
-
-    try:
-        text = raw.strip()
-        if text.startswith("```"):
-            lines = text.split("\n")
-            lines = [l for l in lines if not l.strip().startswith("```")]
-            text = "\n".join(lines)
-        result = json.loads(text)
-        return {
-            "title": result.get("title", post_title),
-            "body": result.get("body", post_body),
-            "excerpt": result.get("excerpt", ""),
-        }
-    except (json.JSONDecodeError, KeyError):
-        logger.warning("Marketer JSON parse failed, using raw text")
-        return {
-            "title": post_title,
-            "body": raw,
-            "excerpt": raw[:200],
-        }

blog-lab/app/naver_search.py

@@ -1,203 +0,0 @@
-"""네이버 검색 API 연동 — 블로그 + 쇼핑 검색."""
-
-import asyncio
-import logging
-import re
-import requests
-from typing import Any, Dict, List, Optional
-
-logger = logging.getLogger(__name__)
-
-from .config import NAVER_CLIENT_ID, NAVER_CLIENT_SECRET
-
-BLOG_URL = "https://openapi.naver.com/v1/search/blog.json"
-SHOP_URL = "https://openapi.naver.com/v1/search/shop.json"
-
-_HEADERS = {
-    "X-Naver-Client-Id": NAVER_CLIENT_ID,
-    "X-Naver-Client-Secret": NAVER_CLIENT_SECRET,
-}
-
-_TAG_RE = re.compile(r"<[^>]+>")
-
-
-def _strip_html(text: str) -> str:
-    return _TAG_RE.sub("", text).strip()
-
-
-def search_blog(keyword: str, display: int = 10, sort: str = "sim") -> Dict[str, Any]:
-    """네이버 블로그 검색.
-
-    Args:
-        keyword: 검색 키워드
-        display: 결과 수 (1-100)
-        sort: sim(정확도) | date(날짜)
-
-    Returns:
-        {"total": int, "items": [...]}
-    """
-    resp = requests.get(
-        BLOG_URL,
-        headers=_HEADERS,
-        params={"query": keyword, "display": display, "sort": sort},
-        timeout=10,
-    )
-    resp.raise_for_status()
-    data = resp.json()
-    items = [
-        {
-            "title": _strip_html(item.get("title", "")),
-            "description": _strip_html(item.get("description", "")),
-            "link": item.get("link", ""),
-            "bloggername": item.get("bloggername", ""),
-            "postdate": item.get("postdate", ""),
-        }
-        for item in data.get("items", [])
-    ]
-    return {"total": data.get("total", 0), "items": items}
-
-
-def search_shopping(keyword: str, display: int = 20, sort: str = "sim") -> Dict[str, Any]:
-    """네이버 쇼핑 검색.
-
-    Args:
-        keyword: 검색 키워드
-        display: 결과 수 (1-100)
-        sort: sim(정확도) | date(날짜) | asc(가격↑) | dsc(가격↓)
-
-    Returns:
-        {"total": int, "items": [...], "price_stats": {...}}
-    """
-    resp = requests.get(
-        SHOP_URL,
-        headers=_HEADERS,
-        params={"query": keyword, "display": display, "sort": sort},
-        timeout=10,
-    )
-    resp.raise_for_status()
-    data = resp.json()
-
-    items = []
-    prices = []
-    for item in data.get("items", []):
-        lprice = _safe_int(item.get("lprice"))
-        hprice = _safe_int(item.get("hprice"))
-        parsed = {
-            "title": _strip_html(item.get("title", "")),
-            "link": item.get("link", ""),
-            "image": item.get("image", ""),
-            "lprice": lprice,
-            "hprice": hprice,
-            "mallName": item.get("mallName", ""),
-            "productId": item.get("productId", ""),
-            "productType": item.get("productType", ""),
-            "category1": item.get("category1", ""),
-            "category2": item.get("category2", ""),
-            "category3": item.get("category3", ""),
-            "brand": item.get("brand", ""),
-            "maker": item.get("maker", ""),
-        }
-        items.append(parsed)
-        if lprice and lprice > 0:
-            prices.append(lprice)
-
-    price_stats = None
-    if prices:
-        price_stats = {
-            "min": min(prices),
-            "max": max(prices),
-            "avg": int(sum(prices) / len(prices)),
-            "count": len(prices),
-        }
-
-    return {
-        "total": data.get("total", 0),
-        "items": items,
-        "price_stats": price_stats,
-    }
-
-
-def _safe_int(val) -> Optional[int]:
-    if val is None:
-        return None
-    try:
-        return int(val)
-    except (ValueError, TypeError):
-        return None
-
-
-def analyze_keyword(keyword: str) -> Dict[str, Any]:
-    """키워드 경쟁도/기회 분석.
-
-    블로그 총 결과수, 쇼핑 총 결과수, 가격 통계를 기반으로
-    competition_score(경쟁도)와 opportunity_score(기회점수) 산출.
-
-    Returns:
-        {
-            "keyword", "blog_total", "shop_total",
-            "competition", "opportunity",
-            "avg_price", "min_price", "max_price",
-            "top_products": [...], "top_blogs": [...]
-        }
-    """
-    blog = search_blog(keyword, display=10, sort="sim")
-    shop = search_shopping(keyword, display=20, sort="sim")
-
-    blog_total = blog["total"]
-    shop_total = shop["total"]
-
-    # 경쟁도: 블로그 결과 수 기반 (로그 스케일 0-100)
-    import math
-    if blog_total > 0:
-        competition = min(100, int(math.log10(blog_total + 1) * 15))
-    else:
-        competition = 0
-
-    # 기회 점수: 쇼핑 수요가 높고 블로그 경쟁이 낮을수록 높음
-    if shop_total > 0 and blog_total > 0:
-        ratio = shop_total / blog_total
-        opportunity = min(100, int(ratio * 20))
-    elif shop_total > 0:
-        opportunity = 90  # 경쟁 없이 수요만 있으면 높은 기회
-    else:
-        opportunity = 10  # 쇼핑 수요 없음
-
-    price_stats = shop.get("price_stats") or {}
-
-    return {
-        "keyword": keyword,
-        "blog_total": blog_total,
-        "shop_total": shop_total,
-        "competition": competition,
-        "opportunity": opportunity,
-        "avg_price": price_stats.get("avg"),
-        "min_price": price_stats.get("min"),
-        "max_price": price_stats.get("max"),
-        "top_products": shop["items"][:5],
-        "top_blogs": blog["items"][:5],
-    }
-
-
-def _run_enrich(top_blogs: list) -> list:
-    """동기 컨텍스트에서 비동기 enrich_top_blogs 실행."""
-    from .web_crawler import enrich_top_blogs
-    try:
-        loop = asyncio.get_event_loop()
-        if loop.is_running():
-            import concurrent.futures
-            with concurrent.futures.ThreadPoolExecutor() as pool:
-                return pool.submit(
-                    asyncio.run, enrich_top_blogs(top_blogs)
-                ).result(timeout=60)
-        else:
-            return asyncio.run(enrich_top_blogs(top_blogs))
-    except Exception as e:
-        logger.warning("블로그 크롤링 실패, 기존 데이터 사용: %s", e)
-        return top_blogs
-
-
-def analyze_keyword_with_crawling(keyword: str) -> Dict[str, Any]:
-    """analyze_keyword + 상위 블로그 본문 크롤링."""
-    result = analyze_keyword(keyword)
-    result["top_blogs"] = _run_enrich(result["top_blogs"])
-    return result

blog-lab/app/quality_reviewer.py

@@ -1,85 +0,0 @@
-"""Claude API 기반 블로그 글 품질 리뷰 — 6기준 × 10점, 42/60 통과."""
-
-import json
-import logging
-from datetime import date
-from typing import Any, Dict, Optional
-
-import anthropic
-
-from .config import ANTHROPIC_API_KEY, CLAUDE_MODEL
-from .db import get_template
-
-logger = logging.getLogger(__name__)
-
-PASS_THRESHOLD = 42  # 60점 만점 중 42점 이상이면 통과 (70%)
-
-_client: Optional[anthropic.Anthropic] = None
-
-
-def _get_client() -> anthropic.Anthropic:
-    global _client
-    if _client is None:
-        _client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
-    return _client
-
-
-def review_post(title: str, body: str) -> Dict[str, Any]:
-    """블로그 글 품질 리뷰.
-
-    Returns:
-        {
-            "scores": {
-                "empathy": N, "click_appeal": N, "conversion": N,
-                "seo": N, "format": N, "link_natural": N
-            },
-            "total": N,
-            "pass": bool,
-            "feedback": str
-        }
-    """
-    template = get_template("quality_review")
-    if not template:
-        raise RuntimeError("quality_review 템플릿이 없습니다")
-
-    prompt = template.format(title=title, body=body[:6000])
-
-    client = _get_client()
-    today = date.today().isoformat()
-    resp = client.messages.create(
-        model=CLAUDE_MODEL,
-        max_tokens=2048,
-        system=f"현재 날짜는 {today}입니다.",
-        messages=[{"role": "user", "content": prompt}],
-    )
-    raw = resp.content[0].text
-
-    try:
-        text = raw.strip()
-        if text.startswith("```"):
-            lines = text.split("\n")
-            lines = [l for l in lines if not l.strip().startswith("```")]
-            text = "\n".join(lines)
-        result = json.loads(text)
-
-        scores = result.get("scores", {})
-        total = sum(scores.values())
-        passed = total >= PASS_THRESHOLD
-
-        return {
-            "scores": scores,
-            "total": total,
-            "pass": passed,
-            "feedback": result.get("feedback", ""),
-        }
-    except (json.JSONDecodeError, KeyError, TypeError) as e:
-        logger.warning("Quality review JSON parse failed: %s", e)
-        return {
-            "scores": {
-                "empathy": 0, "click_appeal": 0, "conversion": 0,
-                "seo": 0, "format": 0, "link_natural": 0,
-            },
-            "total": 0,
-            "pass": False,
-            "feedback": f"리뷰 파싱 실패. 원본 응답:\n{raw[:500]}",
-        }

blog-lab/app/web_crawler.py

@@ -1,97 +0,0 @@
-"""네이버 블로그 본문 크롤링 모듈."""
-
-import asyncio
-import logging
-import re
-from typing import Any, Dict, List, Optional, Tuple
-import httpx
-from bs4 import BeautifulSoup
-
-logger = logging.getLogger(__name__)
-
-_TIMEOUT = 10  # 글당 크롤링 타임아웃 (초)
-_MAX_CONTENT_LENGTH = 2000  # 본문 최대 길이
-
-# 네이버 블로그 URL 패턴: blog.naver.com/{blogId}/{logNo}
-_BLOG_URL_RE = re.compile(r"blog\.naver\.com/([^/]+)/(\d+)")
-
-
-def _parse_naver_blog_url(url: str) -> Optional[Tuple[str, str]]:
-    """네이버 블로그 URL에서 blogId, logNo 추출. 실패 시 None."""
-    match = _BLOG_URL_RE.search(url)
-    if not match:
-        return None
-    return match.group(1), match.group(2)
-
-
-async def _fetch_html(url: str) -> str:
-    """URL에서 HTML을 가져온다."""
-    async with httpx.AsyncClient(timeout=_TIMEOUT, follow_redirects=True) as client:
-        resp = await client.get(url, headers={
-            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
-        })
-        resp.raise_for_status()
-        return resp.text
-
-
-def _extract_text(html: str) -> str:
-    """HTML에서 본문 텍스트를 추출한다."""
-    soup = BeautifulSoup(html, "html.parser")
-
-    # 스마트에디터 3 (SE3)
-    container = soup.select_one("div.se-main-container")
-    if not container:
-        # 구 에디터
-        container = soup.select_one("div#postViewArea")
-    if not container:
-        # 폴백: body 전체
-        container = soup.body
-
-    if not container:
-        return ""
-
-    # 스크립트/스타일 제거
-    for tag in container.find_all(["script", "style"]):
-        tag.decompose()
-
-    text = container.get_text(separator="\n", strip=True)
-    return text[:_MAX_CONTENT_LENGTH]
-
-
-async def crawl_blog_content(url: str) -> str:
-    """네이버 블로그 URL에서 본문 텍스트 추출.
-
-    - 네이버 블로그가 아니면 빈 문자열
-    - 크롤링 실패 시 빈 문자열 (에러 로그만)
-    - 본문 최대 2,000자
-    """
-    parsed = _parse_naver_blog_url(url)
-    if not parsed:
-        return ""
-
-    blog_id, log_no = parsed
-    # iframe 내부 실제 본문 URL
-    post_url = f"https://blog.naver.com/PostView.naver?blogId={blog_id}&logNo={log_no}"
-
-    try:
-        html = await _fetch_html(post_url)
-        return _extract_text(html)
-    except Exception as e:
-        logger.warning("블로그 크롤링 실패 (%s): %s", url, e)
-        return ""
-
-
-async def enrich_top_blogs(top_blogs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """top_blogs 리스트 각 항목에 content 필드를 추가.
-
-    개별 크롤링 실패 시 해당 항목의 content를 빈 문자열로 설정하고 나머지 계속 진행.
-    """
-    result = []
-    for blog in top_blogs:
-        enriched = dict(blog)
-        try:
-            enriched["content"] = await crawl_blog_content(blog.get("link", ""))
-        except Exception:
-            enriched["content"] = ""
-        result.append(enriched)
-    return result

blog-lab/tests/conftest.py

@@ -1,9 +0,0 @@
-"""공통 테스트 픽스처."""
-import os
-import sys
-
-# app 패키지를 blog_lab_app으로도 import 가능하게
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
-if "blog_lab_app" not in sys.modules:
-    import app as blog_lab_app
-    sys.modules["blog_lab_app"] = blog_lab_app

blog-lab/tests/test_api_links.py

@@ -1,85 +0,0 @@
-"""브랜드커넥트 링크 API 테스트."""
-import os
-import pytest
-from fastapi.testclient import TestClient
-
-
-@pytest.fixture(autouse=True)
-def setup_db(tmp_path):
-    test_db = str(tmp_path / "test.db")
-    import app.config as config
-    config.DB_PATH = test_db
-    from app import db
-    db.DB_PATH = test_db
-    db.init_db()
-    yield
-
-
-@pytest.fixture
-def client():
-    from app.main import app
-    return TestClient(app)
-
-
-def test_create_link(client):
-    resp = client.post("/api/blog-marketing/links", json={
-        "keyword_id": 1,
-        "url": "https://link.coupang.com/abc",
-        "product_name": "테스트 상품",
-        "description": "상품 설명",
-    })
-    assert resp.status_code == 201
-    data = resp.json()
-    assert data["url"] == "https://link.coupang.com/abc"
-    assert data["product_name"] == "테스트 상품"
-
-
-def test_create_link_requires_url(client):
-    resp = client.post("/api/blog-marketing/links", json={
-        "product_name": "상품",
-    })
-    assert resp.status_code == 422
-
-
-def test_create_link_requires_product_name(client):
-    resp = client.post("/api/blog-marketing/links", json={
-        "url": "https://a.com",
-    })
-    assert resp.status_code == 422
-
-
-def test_list_links_by_keyword_id(client):
-    client.post("/api/blog-marketing/links", json={
-        "keyword_id": 1, "url": "https://a.com", "product_name": "A",
-    })
-    client.post("/api/blog-marketing/links", json={
-        "keyword_id": 2, "url": "https://b.com", "product_name": "B",
-    })
-    resp = client.get("/api/blog-marketing/links?keyword_id=1")
-    assert resp.status_code == 200
-    assert len(resp.json()["links"]) == 1
-
-
-def test_update_link(client):
-    create_resp = client.post("/api/blog-marketing/links", json={
-        "url": "https://a.com", "product_name": "원래",
-    })
-    link_id = create_resp.json()["id"]
-    resp = client.put(f"/api/blog-marketing/links/{link_id}", json={
-        "product_name": "새이름",
-    })
-    assert resp.status_code == 200
-    assert resp.json()["product_name"] == "새이름"
-
-
-def test_delete_link(client):
-    create_resp = client.post("/api/blog-marketing/links", json={
-        "url": "https://a.com", "product_name": "삭제",
-    })
-    link_id = create_resp.json()["id"]
-    resp = client.delete(f"/api/blog-marketing/links/{link_id}")
-    assert resp.status_code == 200
-    assert resp.json()["ok"] is True
-
-    resp = client.delete(f"/api/blog-marketing/links/{link_id}")
-    assert resp.status_code == 404

blog-lab/tests/test_db_brand_links.py

@@ -1,67 +0,0 @@
-"""brand_links DB CRUD 테스트."""
-import os
-import pytest
-from app import db
-from app.config import DB_PATH
-
-
-@pytest.fixture(autouse=True)
-def setup_db(tmp_path):
-    """테스트용 임시 DB 사용."""
-    test_db = str(tmp_path / "test.db")
-    import app.config as config
-    config.DB_PATH = test_db
-    db.DB_PATH = test_db
-    db.init_db()
-    yield
-
-
-def test_add_brand_link():
-    link = db.add_brand_link({
-        "keyword_id": 1,
-        "url": "https://link.coupang.com/abc",
-        "product_name": "테스트 상품",
-        "description": "상품 설명",
-        "placement_hint": "본문 중간",
-    })
-    assert link["id"] is not None
-    assert link["url"] == "https://link.coupang.com/abc"
-    assert link["product_name"] == "테스트 상품"
-    assert link["keyword_id"] == 1
-    assert link["post_id"] is None
-
-
-def test_get_brand_links_by_keyword_id():
-    db.add_brand_link({"keyword_id": 1, "url": "https://a.com", "product_name": "A"})
-    db.add_brand_link({"keyword_id": 1, "url": "https://b.com", "product_name": "B"})
-    db.add_brand_link({"keyword_id": 2, "url": "https://c.com", "product_name": "C"})
-    links = db.get_brand_links(keyword_id=1)
-    assert len(links) == 2
-
-
-def test_get_brand_links_by_post_id():
-    db.add_brand_link({"post_id": 10, "url": "https://a.com", "product_name": "A"})
-    links = db.get_brand_links(post_id=10)
-    assert len(links) == 1
-    assert links[0]["post_id"] == 10
-
-
-def test_update_brand_link():
-    link = db.add_brand_link({"url": "https://a.com", "product_name": "원래 이름"})
-    updated = db.update_brand_link(link["id"], {"product_name": "새 이름", "post_id": 5})
-    assert updated["product_name"] == "새 이름"
-    assert updated["post_id"] == 5
-
-
-def test_delete_brand_link():
-    link = db.add_brand_link({"url": "https://a.com", "product_name": "삭제할 링크"})
-    assert db.delete_brand_link(link["id"]) is True
-    assert db.delete_brand_link(link["id"]) is False
-
-
-def test_link_keyword_to_post():
-    db.add_brand_link({"keyword_id": 1, "url": "https://a.com", "product_name": "A"})
-    db.add_brand_link({"keyword_id": 1, "url": "https://b.com", "product_name": "B"})
-    db.link_brand_links_to_post(keyword_id=1, post_id=10)
-    links = db.get_brand_links(post_id=10)
-    assert len(links) == 2

blog-lab/tests/test_evaluator.py

@@ -1,74 +0,0 @@
-"""평가자 단계 테스트 — 6기준 60점."""
-import json
-import pytest
-from unittest.mock import patch
-
-
-def test_review_post_has_6_criteria():
-    """6개 기준으로 채점하는지 확인."""
-    from app.quality_reviewer import review_post
-
-    mock_response = json.dumps({
-        "scores": {
-            "empathy": 8, "click_appeal": 7, "conversion": 9,
-            "seo": 8, "format": 7, "link_natural": 9,
-        },
-        "total": 48,
-        "pass": True,
-        "feedback": "전체적으로 우수합니다",
-    })
-
-    with patch("app.quality_reviewer._get_client") as mock_client_fn, \
-         patch("app.quality_reviewer.get_template", return_value="제목: {title}\n본문: {body}"):
-        mock_client = mock_client_fn.return_value
-        mock_client.messages.create.return_value.content = [type("C", (), {"text": mock_response})()]
-        result = review_post("테스트 제목", "<p>본문</p>")
-
-    assert "link_natural" in result["scores"]
-    assert len(result["scores"]) == 6
-    assert result["total"] == 48
-    assert result["pass"] is True
-
-
-def test_review_pass_threshold_is_42():
-    """통과 기준이 42점인지 확인."""
-    from app.quality_reviewer import PASS_THRESHOLD
-    assert PASS_THRESHOLD == 42
-
-
-def test_review_fails_below_42():
-    """42점 미만이면 불통과."""
-    from app.quality_reviewer import review_post
-
-    mock_response = json.dumps({
-        "scores": {
-            "empathy": 5, "click_appeal": 5, "conversion": 5,
-            "seo": 5, "format": 5, "link_natural": 5,
-        },
-        "total": 30,
-        "pass": False,
-        "feedback": "개선 필요",
-    })
-
-    with patch("app.quality_reviewer._get_client") as mock_client_fn, \
-         patch("app.quality_reviewer.get_template", return_value="제목: {title}\n본문: {body}"):
-        mock_client = mock_client_fn.return_value
-        mock_client.messages.create.return_value.content = [type("C", (), {"text": mock_response})()]
-        result = review_post("제목", "<p>본문</p>")
-
-    assert result["pass"] is False
-
-
-def test_review_handles_parse_failure():
-    """JSON 파싱 실패 시 기본값 반환 (6개 기준)."""
-    from app.quality_reviewer import review_post
-
-    with patch("app.quality_reviewer._get_client") as mock_client_fn, \
-         patch("app.quality_reviewer.get_template", return_value="제목: {title}\n본문: {body}"):
-        mock_client = mock_client_fn.return_value
-        mock_client.messages.create.return_value.content = [type("C", (), {"text": "잘못된 응답"})()]
-        result = review_post("제목", "<p>본문</p>")
-
-    assert result["pass"] is False
-    assert "link_natural" in result["scores"]
-    assert result["total"] == 0

blog-lab/tests/test_marketer.py

@@ -1,66 +0,0 @@
-"""마케터 단계 테스트."""
-import json
-import pytest
-from unittest.mock import patch
-
-
-def test_enhance_for_conversion_inserts_links():
-    """마케터가 브랜드 링크를 본문에 삽입."""
-    from app.marketer import enhance_for_conversion
-
-    brand_links = [
-        {"url": "https://link.coupang.com/abc", "product_name": "갤럭시 버즈3",
-         "description": "노이즈캔슬링", "placement_hint": "본문 중간"},
-    ]
-
-    mock_response = json.dumps({
-        "title": "마케팅된 제목",
-        "body": '<p>본문 <a href="https://link.coupang.com/abc">갤럭시 버즈3</a></p>',
-        "excerpt": "요약",
-    })
-
-    with patch("app.marketer._call_claude", return_value=mock_response) as mock_call, \
-         patch("app.marketer.get_template", return_value="초안: {draft_body}\n키워드: {keyword}\n링크:\n{brand_links_info}"):
-        result = enhance_for_conversion(
-            post_body="<p>초안 본문</p>",
-            post_title="초안 제목",
-            brand_links=brand_links,
-            keyword="무선 이어폰",
-        )
-
-    prompt_used = mock_call.call_args[0][0]
-    assert "갤럭시 버즈3" in prompt_used
-    assert "노이즈캔슬링" in prompt_used
-    assert result["title"] == "마케팅된 제목"
-
-
-def test_enhance_requires_brand_links():
-    """브랜드 링크가 없으면 ValueError."""
-    from app.marketer import enhance_for_conversion
-
-    with pytest.raises(ValueError, match="브랜드커넥트 링크가 필요합니다"):
-        enhance_for_conversion(
-            post_body="<p>본문</p>",
-            post_title="제목",
-            brand_links=[],
-            keyword="테스트",
-        )
-
-
-def test_enhance_json_parse_fallback():
-    """JSON 파싱 실패 시 원본 제목 유지."""
-    from app.marketer import enhance_for_conversion
-
-    brand_links = [{"url": "https://a.com", "product_name": "상품"}]
-
-    with patch("app.marketer._call_claude", return_value="잘못된 JSON"), \
-         patch("app.marketer.get_template", return_value="초안: {draft_body}\n키워드: {keyword}\n링크:\n{brand_links_info}"):
-        result = enhance_for_conversion(
-            post_body="<p>원본</p>",
-            post_title="원본 제목",
-            brand_links=brand_links,
-            keyword="테스트",
-        )
-
-    assert result["title"] == "원본 제목"
-    assert result["body"] == "잘못된 JSON"

blog-lab/tests/test_pipeline_integration.py

@@ -1,146 +0,0 @@
-"""4단계 파이프라인 통합 테스트."""
-import os
-import pytest
-from unittest.mock import patch
-from fastapi.testclient import TestClient
-
-
-@pytest.fixture(autouse=True)
-def setup_db(tmp_path):
-    test_db = str(tmp_path / "test.db")
-    import app.config as config
-    config.DB_PATH = test_db
-    from app import db
-    db.DB_PATH = test_db
-    db.init_db()
-    yield
-
-
-@pytest.fixture
-def client():
-    from app.main import app
-    return TestClient(app)
-
-
-def test_full_pipeline_status_flow(client):
-    """draft → marketed → reviewed → published 상태 흐름."""
-    from app import db
-
-    # 1. 키워드 분석 결과 직접 삽입
-    analysis = db.add_keyword_analysis({
-        "keyword": "무선 이어폰",
-        "blog_total": 1000,
-        "shop_total": 500,
-        "competition": 45,
-        "opportunity": 60,
-        "top_products": [{"title": "에어팟", "lprice": 200000, "mallName": "애플"}],
-        "top_blogs": [{"title": "리뷰", "link": "https://blog.naver.com/user/123", "content": "본문"}],
-    })
-
-    # 2. 브랜드 링크 등록
-    resp = client.post("/api/blog-marketing/links", json={
-        "keyword_id": analysis["id"],
-        "url": "https://link.coupang.com/abc",
-        "product_name": "삼성 버즈3",
-        "description": "노이즈캔슬링",
-    })
-    assert resp.status_code == 201
-
-    # 3. 포스트 직접 생성 (generate는 Claude API 필요)
-    post = db.add_post({
-        "keyword_id": analysis["id"],
-        "title": "무선 이어폰 추천",
-        "body": "<p>초안 본문</p>",
-        "excerpt": "요약",
-        "tags": ["이어폰"],
-        "status": "draft",
-    })
-    db.link_brand_links_to_post(keyword_id=analysis["id"], post_id=post["id"])
-
-    # 4. 상태 확인: draft
-    resp = client.get(f"/api/blog-marketing/posts/{post['id']}")
-    assert resp.json()["status"] == "draft"
-
-    # 5. marketed 상태
-    db.update_post(post["id"], {"status": "marketed", "body": "<p>마케팅된 본문</p>"})
-    resp = client.get(f"/api/blog-marketing/posts/{post['id']}")
-    assert resp.json()["status"] == "marketed"
-
-    # 6. reviewed 상태 (점수 48/60 = 통과)
-    db.update_post(post["id"], {
-        "status": "reviewed",
-        "review_score": 48,
-        "review_detail": {
-            "scores": {"empathy": 8, "click_appeal": 8, "conversion": 8, "seo": 8, "format": 8, "link_natural": 8},
-            "total": 48, "pass": True, "feedback": "우수"
-        },
-    })
-    resp = client.get(f"/api/blog-marketing/posts/{post['id']}")
-    assert resp.json()["status"] == "reviewed"
-    assert resp.json()["review_score"] == 48
-
-    # 7. 발행
-    resp = client.post(f"/api/blog-marketing/posts/{post['id']}/publish", json={
-        "naver_url": "https://blog.naver.com/mypost/123",
-    })
-    assert resp.json()["status"] == "published"
-
-
-def test_links_associated_with_post(client):
-    """keyword_id로 등록한 링크가 post 생성 후 post_id로도 조회 가능."""
-    from app import db
-
-    analysis = db.add_keyword_analysis({"keyword": "테스트", "blog_total": 10, "shop_total": 5})
-    client.post("/api/blog-marketing/links", json={
-        "keyword_id": analysis["id"],
-        "url": "https://link.com/1",
-        "product_name": "상품1",
-    })
-
-    post = db.add_post({"keyword_id": analysis["id"], "title": "제목", "body": "본문", "status": "draft"})
-    db.link_brand_links_to_post(keyword_id=analysis["id"], post_id=post["id"])
-
-    resp = client.get(f"/api/blog-marketing/links?post_id={post['id']}")
-    links = resp.json()["links"]
-    assert len(links) == 1
-    assert links[0]["product_name"] == "상품1"
-
-
-@patch("app.main.ANTHROPIC_API_KEY", "fake-key-for-test")
-def test_market_endpoint_returns_404_for_missing_post(client):
-    """존재하지 않는 post_id로 마케터 호출 시 404."""
-    resp = client.post("/api/blog-marketing/market/9999")
-    assert resp.status_code == 404
-
-
-@patch("app.main.ANTHROPIC_API_KEY", "fake-key-for-test")
-def test_review_endpoint_returns_404_for_missing_post(client):
-    """존재하지 않는 post_id로 리뷰 호출 시 404."""
-    resp = client.post("/api/blog-marketing/review/9999")
-    assert resp.status_code == 404
-
-
-def test_multiple_links_per_keyword(client):
-    """하나의 키워드에 복수 링크 등록 가능."""
-    from app import db
-    analysis = db.add_keyword_analysis({"keyword": "테스트", "blog_total": 10, "shop_total": 5})
-
-    for i in range(3):
-        resp = client.post("/api/blog-marketing/links", json={
-            "keyword_id": analysis["id"],
-            "url": f"https://link.com/{i}",
-            "product_name": f"상품{i}",
-        })
-        assert resp.status_code == 201
-
-    resp = client.get(f"/api/blog-marketing/links?keyword_id={analysis['id']}")
-    assert len(resp.json()["links"]) == 3
-
-
-def test_dashboard_still_works(client):
-    """대시보드 API가 여전히 정상 작동."""
-    resp = client.get("/api/blog-marketing/dashboard")
-    assert resp.status_code == 200
-    data = resp.json()
-    assert "total_posts" in data
-    assert "published_posts" in data

blog-lab/tests/test_research_crawling.py

@@ -1,58 +0,0 @@
-"""리서치 단계 크롤링 통합 테스트."""
-from unittest.mock import patch
-
-
-def test_analyze_keyword_with_crawling_enriches_top_blogs():
-    """analyze_keyword_with_crawling가 top_blogs에 content 필드를 추가."""
-    from app.naver_search import analyze_keyword_with_crawling
-
-    mock_blog_result = {
-        "total": 100,
-        "items": [
-            {"title": "테스트 블로그", "link": "https://blog.naver.com/user1/111",
-             "bloggername": "유저1", "description": "설명", "postdate": "20260401"},
-        ],
-    }
-    mock_shop_result = {
-        "total": 50,
-        "items": [{"title": "상품1", "lprice": 10000, "mallName": "쿠팡"}],
-        "price_stats": {"min": 10000, "max": 10000, "avg": 10000, "count": 1},
-    }
-
-    with patch("app.naver_search.search_blog", return_value=mock_blog_result), \
-         patch("app.naver_search.search_shopping", return_value=mock_shop_result), \
-         patch("app.naver_search._run_enrich", return_value=[
-             {"title": "테스트 블로그", "link": "https://blog.naver.com/user1/111",
-              "bloggername": "유저1", "description": "설명", "postdate": "20260401",
-              "content": "크롤링된 본문 내용"}
-         ]):
-        result = analyze_keyword_with_crawling("테스트 키워드")
-
-    assert "content" in result["top_blogs"][0]
-    assert result["top_blogs"][0]["content"] == "크롤링된 본문 내용"
-
-
-def test_analyze_keyword_with_crawling_fallback_on_enrich_failure():
-    """크롤링 실패 시 기존 데이터 유지."""
-    from app.naver_search import analyze_keyword_with_crawling
-
-    mock_blog_result = {
-        "total": 50,
-        "items": [{"title": "블로그", "link": "https://blog.naver.com/u/1", "bloggername": "유저", "description": "설명"}],
-    }
-    mock_shop_result = {"total": 10, "items": [], "price_stats": None}
-
-    with patch("app.naver_search.search_blog", return_value=mock_blog_result), \
-         patch("app.naver_search.search_shopping", return_value=mock_shop_result), \
-         patch("app.naver_search._run_enrich", side_effect=Exception("크롤링 실패")):
-        # _run_enrich 내부에서 예외를 잡으므로 실제로는 이 테스트에서는
-        # _run_enrich 자체가 예외를 던지는 상황을 시뮬레이션
-        # 하지만 _run_enrich는 내부에서 잡으므로, 직접 fallback 테스트
-        pass
-
-    # _run_enrich 자체 fallback 테스트
-    from app.naver_search import _run_enrich
-    original_blogs = [{"title": "원본", "link": "https://blog.naver.com/u/1"}]
-    with patch("app.web_crawler.enrich_top_blogs", side_effect=Exception("fail")):
-        result = _run_enrich(original_blogs)
-    assert result == original_blogs  # fallback으로 원본 반환

blog-lab/tests/test_web_crawler.py

@@ -1,94 +0,0 @@
-"""web_crawler 모듈 테스트."""
-import pytest
-from unittest.mock import patch, AsyncMock
-from app.web_crawler import crawl_blog_content, enrich_top_blogs, _parse_naver_blog_url, _extract_text
-
-
-def test_parse_naver_blog_url_valid():
-    """blog.naver.com URL에서 blogId와 logNo를 올바르게 파싱."""
-    result = _parse_naver_blog_url("https://blog.naver.com/testuser/123456")
-    assert result == ("testuser", "123456")
-
-
-def test_parse_returns_none_for_invalid_url():
-    """잘못된 URL은 None 반환."""
-    result = _parse_naver_blog_url("https://example.com/post")
-    assert result is None
-
-
-def test_extract_text_prefers_se_main_container():
-    """SE3 에디터 컨테이너를 우선 선택."""
-    html = '<div class="se-main-container"><p>SE3 본문</p></div><div id="postViewArea"><p>구 에디터</p></div>'
-    assert _extract_text(html) == "SE3 본문"
-
-
-def test_extract_text_falls_back_to_post_view_area():
-    """SE3 없으면 구 에디터 컨테이너 사용."""
-    html = '<div id="postViewArea"><p>구 에디터 본문</p></div>'
-    assert _extract_text(html) == "구 에디터 본문"
-
-
-def test_extract_text_removes_script_and_style():
-    """스크립트/스타일 태그 제거."""
-    html = '<div class="se-main-container"><p>본문</p><script>alert(1)</script><style>.x{}</style></div>'
-    result = _extract_text(html)
-    assert "alert" not in result
-    assert ".x" not in result
-    assert "본문" in result
-
-
-def test_extract_text_returns_empty_on_no_container():
-    """컨테이너가 없고 body도 없으면 빈 문자열."""
-    assert _extract_text("") == ""
-
-
-@pytest.mark.asyncio
-async def test_crawl_returns_empty_on_non_naver_url():
-    """네이버 블로그가 아닌 URL은 빈 문자열 반환."""
-    result = await crawl_blog_content("https://example.com/post")
-    assert result == ""
-
-
-@pytest.mark.asyncio
-async def test_crawl_truncates_to_2000_chars():
-    """본문이 2000자를 초과하면 잘라낸다."""
-    long_html = f'<div class="se-main-container"><p>{"가" * 3000}</p></div>'
-    with patch("app.web_crawler._fetch_html", new_callable=AsyncMock, return_value=long_html):
-        result = await crawl_blog_content("https://blog.naver.com/testuser/123")
-    assert len(result) <= 2000
-
-
-@pytest.mark.asyncio
-async def test_crawl_returns_empty_on_fetch_failure():
-    """HTTP 요청 실패 시 빈 문자열 반환."""
-    with patch("app.web_crawler._fetch_html", new_callable=AsyncMock, side_effect=Exception("timeout")):
-        result = await crawl_blog_content("https://blog.naver.com/testuser/123")
-    assert result == ""
-
-
-@pytest.mark.asyncio
-async def test_enrich_top_blogs_adds_content_field():
-    """enrich_top_blogs가 각 블로그에 content 필드를 추가."""
-    blogs = [
-        {"title": "테스트", "link": "https://blog.naver.com/user1/111", "bloggername": "유저1", "description": "설명"},
-        {"title": "테스트2", "link": "https://blog.naver.com/user2/222", "bloggername": "유저2", "description": "설명2"},
-    ]
-    with patch("app.web_crawler.crawl_blog_content", new_callable=AsyncMock, return_value="크롤링된 본문"):
-        result = await enrich_top_blogs(blogs)
-    assert len(result) == 2
-    assert result[0]["content"] == "크롤링된 본문"
-    assert result[1]["content"] == "크롤링된 본문"
-
-
-@pytest.mark.asyncio
-async def test_enrich_top_blogs_handles_partial_failure():
-    """일부 크롤링 실패 시에도 나머지는 정상 처리."""
-    blogs = [
-        {"title": "성공", "link": "https://blog.naver.com/user1/111"},
-        {"title": "실패", "link": "https://blog.naver.com/user2/222"},
-    ]
-    side_effects = ["성공 본문", Exception("fail")]
-    with patch("app.web_crawler.crawl_blog_content", new_callable=AsyncMock, side_effect=side_effects):
-        result = await enrich_top_blogs(blogs)
-    assert result[0]["content"] == "성공 본문"
-    assert result[1]["content"] == ""

blog-lab/tests/test_writer.py

@@ -1,86 +0,0 @@
-"""작가 단계 테스트 -- 크롤링 본문 + 링크 참조 글 생성."""
-import json
-import pytest
-from unittest.mock import patch
-
-
-def test_generate_blog_post_includes_crawled_content():
-    """크롤링 본문이 프롬프트에 포함되는지 확인."""
-    from app.content_generator import generate_blog_post
-
-    analysis = {
-        "keyword": "무선 이어폰",
-        "top_products": [{"title": "에어팟", "lprice": 200000, "mallName": "애플"}],
-        "top_blogs": [
-            {"title": "에어팟 리뷰", "content": "에어팟을 한 달간 써봤는데 음질이 정말 좋았습니다."},
-        ],
-    }
-
-    mock_response = json.dumps({
-        "title": "무선 이어폰 추천",
-        "body": "<p>본문</p>",
-        "excerpt": "요약",
-        "tags": ["이어폰"],
-    })
-
-    with patch("app.content_generator._call_claude", return_value=mock_response) as mock_call, \
-         patch("app.content_generator.get_template", return_value=(
-             "키워드: {keyword}\n참고 블로그:\n{reference_blogs}\n상품: {top_products}\n링크 상품: {brand_products}"
-         )):
-        result = generate_blog_post(analysis, "트렌드 브리프", brand_links=[])
-
-    prompt_used = mock_call.call_args[0][0]
-    assert "에어팟을 한 달간 써봤는데" in prompt_used
-    assert result["title"] == "무선 이어폰 추천"
-
-
-def test_generate_blog_post_includes_brand_links():
-    """브랜드커넥트 링크 정보가 프롬프트에 포함되는지 확인."""
-    from app.content_generator import generate_blog_post
-
-    analysis = {"keyword": "무선 이어폰", "top_products": [], "top_blogs": []}
-    brand_links = [
-        {"url": "https://link.coupang.com/abc", "product_name": "삼성 버즈3",
-         "description": "노이즈캔슬링 지원", "placement_hint": "본문 중간"},
-    ]
-
-    mock_response = json.dumps({
-        "title": "제목", "body": "<p>본문</p>", "excerpt": "요약", "tags": ["태그"],
-    })
-
-    with patch("app.content_generator._call_claude", return_value=mock_response) as mock_call, \
-         patch("app.content_generator.get_template", return_value=(
-             "키워드: {keyword}\n참고 블로그:\n{reference_blogs}\n상품: {top_products}\n링크 상품: {brand_products}"
-         )):
-        result = generate_blog_post(analysis, "트렌드 브리프", brand_links=brand_links)
-
-    prompt_used = mock_call.call_args[0][0]
-    assert "삼성 버즈3" in prompt_used
-    assert "노이즈캔슬링 지원" in prompt_used
-
-
-def test_generate_blog_post_works_without_links():
-    """링크 없이도 정상 동작."""
-    from app.content_generator import generate_blog_post
-
-    analysis = {"keyword": "테스트", "top_products": [], "top_blogs": []}
-    mock_response = json.dumps({
-        "title": "제목", "body": "<p>본문</p>", "excerpt": "요약", "tags": ["태그"],
-    })
-
-    with patch("app.content_generator._call_claude", return_value=mock_response), \
-         patch("app.content_generator.get_template", return_value=(
-             "키워드: {keyword}\n참고 블로그:\n{reference_blogs}\n상품: {top_products}\n링크 상품: {brand_products}"
-         )):
-        result = generate_blog_post(analysis, "브리프")
-
-    assert result["title"] == "제목"
-
-
-def test_parse_blog_json_fallback():
-    """JSON 파싱 실패 시 원본 텍스트를 body로 사용."""
-    from app.content_generator import _parse_blog_json
-
-    result = _parse_blog_json("잘못된 JSON", "테스트 키워드")
-    assert result["title"] == "테스트 키워드 추천 리뷰"
-    assert result["body"] == "잘못된 JSON"

docker-compose.yml

@@ -22,12 +22,12 @@ services:
       timeout: 5s
       retries: 3
 
-  stock-lab:
+  stock:
     build:
-      context: ./stock-lab
+      context: ./stock
       args:
         APP_VERSION: ${APP_VERSION:-dev}
-    container_name: stock-lab
+    container_name: stock
     restart: unless-stopped
     ports:
       - "18500:8000"
@@ -43,6 +43,7 @@ services:
       - OLLAMA_URL=${OLLAMA_URL:-http://192.168.45.59:11435}
       - OLLAMA_MODEL=${OLLAMA_MODEL:-qwen3:14b}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+      - WEBAI_API_KEY=${WEBAI_API_KEY:-}
     volumes:
       - ${RUNTIME_PATH}/data/stock:/app/data
     healthcheck:
@@ -73,6 +74,9 @@ services:
       - CLAUDE_HAIKU_MODEL=${CLAUDE_HAIKU_MODEL:-claude-haiku-4-5-20251001}
       - CLAUDE_SONNET_MODEL=${CLAUDE_SONNET_MODEL:-claude-sonnet-4-6}
       - VIDEO_DATA_DIR=${VIDEO_DATA_DIR:-/app/data/videos}
+      - WINDOWS_VIDEO_ENCODER_URL=${WINDOWS_VIDEO_ENCODER_URL:-}
+      - NAS_VIDEOS_ROOT=${NAS_VIDEOS_ROOT:-/volume1/docker/webpage/data/videos}
+      - NAS_MUSIC_ROOT=${NAS_MUSIC_ROOT:-/volume1/docker/webpage/data/music}
     volumes:
       - ${RUNTIME_PATH}/data/music:/app/data
       - ${RUNTIME_PATH:-.}/data/videos:/app/data/videos
@@ -82,21 +86,26 @@ services:
       timeout: 5s
       retries: 3
 
-  blog-lab:
+  insta-lab:
     build:
-      context: ./blog-lab
-    container_name: blog-lab
+      context: ./insta-lab
+    container_name: insta-lab
     restart: unless-stopped
     ports:
       - "18700:8000"
     environment:
       - TZ=${TZ:-Asia/Seoul}
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - ANTHROPIC_MODEL_HAIKU=${ANTHROPIC_MODEL_HAIKU:-claude-haiku-4-5-20251001}
+      - ANTHROPIC_MODEL_SONNET=${ANTHROPIC_MODEL_SONNET:-claude-sonnet-4-6}
       - NAVER_CLIENT_ID=${NAVER_CLIENT_ID:-}
       - NAVER_CLIENT_SECRET=${NAVER_CLIENT_SECRET:-}
+      - YOUTUBE_DATA_API_KEY=${YOUTUBE_DATA_API_KEY:-}
+      - INSTA_DATA_PATH=/app/data
+      - CARD_TEMPLATE_DIR=/app/app/templates
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
     volumes:
-      - ${RUNTIME_PATH}/data/blog:/app/data
+      - ${RUNTIME_PATH}/data/insta:/app/data
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
       interval: 30s
@@ -133,9 +142,9 @@ services:
     environment:
       - TZ=${TZ:-Asia/Seoul}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
-      - STOCK_LAB_URL=http://stock-lab:8000
+      - STOCK_URL=http://stock:8000
       - MUSIC_LAB_URL=http://music-lab:8000
-      - BLOG_LAB_URL=http://blog-lab:8000
+      - INSTA_LAB_URL=http://insta-lab:8000
       - REALESTATE_LAB_URL=http://realestate-lab:8000
       - REALESTATE_DASHBOARD_URL=${REALESTATE_DASHBOARD_URL:-http://localhost:8080/realestate}
       - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-}
@@ -154,9 +163,9 @@ services:
     volumes:
       - ${RUNTIME_PATH:-.}/data/agent-office:/app/data
     depends_on:
-      - stock-lab
+      - stock
       - music-lab
-      - blog-lab
+      - insta-lab
       - realestate-lab
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
@@ -195,11 +204,13 @@ services:
       - DSM_HOST=${DSM_HOST:-}
       - DSM_USER=${DSM_USER:-}
       - DSM_PASS=${DSM_PASS:-}
+      - DSM_VERIFY_SSL=${DSM_VERIFY_SSL:-true}
       - BACKEND_HMAC_SECRET=${BACKEND_HMAC_SECRET:-}
       - SUPABASE_URL=${SUPABASE_URL:-}
       - SUPABASE_SERVICE_KEY=${SUPABASE_SERVICE_KEY:-}
       - UPLOAD_TOKEN_TTL_SEC=${UPLOAD_TOKEN_TTL_SEC:-1800}
       - PACK_BASE_DIR=${PACK_BASE_DIR:-/app/data/packs}
+      - PACK_HOST_DIR=${PACK_HOST_DIR:-${PACK_DATA_PATH:-./data/packs}}
     volumes:
       - ${PACK_DATA_PATH:-./data/packs}:${PACK_BASE_DIR:-/app/data/packs}
     healthcheck:
@@ -236,9 +247,15 @@ services:
     container_name: frontend
     restart: unless-stopped
     depends_on:
+      - lotto
+      - stock
       - music-lab
-      - blog-lab
+      - insta-lab
       - realestate-lab
+      - agent-office
+      - personal
+      - packs-lab
+      - travel-proxy
     ports:
       - "8080:80"
     volumes:

docs/superpowers/plans/2026-05-05-packs-lab-infra-integration.md

@@ -0,0 +1,977 @@
+# packs-lab 인프라 통합 + admin mint-token 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:** packs-lab을 운영 가능 상태로 만든다 — admin upload 토큰 발급 endpoint + Supabase 스키마 + docker-compose/nginx/env 통합 + 통합 테스트 + 문서 갱신.
+
+**Architecture:** 기존 코드(HMAC + DSM client + 4 라우트)는 그대로 유지하고, 신규 라우트 1개(`POST /api/packs/admin/mint-token`)를 routes.py에 추가한다. Supabase `pack_files` DDL 파일과 인프라(docker-compose 18950, nginx 5GB streaming, .env.example 6+1 환경변수)를 신설하고, 통합 테스트(routes + dsm_client mock)와 CLAUDE.md 5+1곳을 갱신한다.
+
+**Tech Stack:** Python 3.12 / FastAPI / pytest + unittest.mock / Supabase(PostgreSQL) / Synology DSM 7.x API / nginx / Docker Compose
+
+**스펙 참조:** `docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md`
+
+**작업 디렉토리:** `C:\Users\jaeoh\Desktop\workspace\web-backend` (기존 web-backend repo)
+
+---
+
+## Task 1: 테스트 인프라 — `tests/conftest.py`
+
+기존 `tests/test_auth.py`는 `BACKEND_HMAC_SECRET=secret` 같은 fixture가 없어 환경변수 의존. 모든 테스트가 동일한 secret으로 동작하도록 autouse fixture를 conftest에 정리.
+
+**Files:**
+- Create: `packs-lab/tests/conftest.py`
+
+- [ ] **Step 1: conftest.py 생성**
+
+`packs-lab/tests/conftest.py`:
+
+```python
+"""packs-lab 테스트 공통 fixture."""
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _hmac_secret(monkeypatch):
+    """모든 테스트에서 동일한 HMAC secret 사용. auth._SECRET 모듈 캐시까지 갱신."""
+    monkeypatch.setenv("BACKEND_HMAC_SECRET", "test-secret-do-not-use-in-prod")
+    # auth.py 모듈은 import 시점에 _SECRET을 캐시하므로 monkeypatch로 함께 갱신
+    from app import auth
+    monkeypatch.setattr(auth, "_SECRET", "test-secret-do-not-use-in-prod")
+```
+
+- [ ] **Step 2: 기존 test_auth.py 회귀 검증**
+
+```bash
+cd C:\Users\jaeoh\Desktop\workspace\web-backend\packs-lab
+python -m pytest tests/test_auth.py -v
+```
+
+Expected: 기존 테스트 모두 PASS (conftest 영향 없거나 PASS 그대로 유지). 만약 secret 인코딩 차이로 실패 시 해당 테스트의 secret 사용 부분을 conftest 값과 일치시킨다.
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add packs-lab/tests/conftest.py
+git commit -m "test(packs-lab): conftest로 HMAC secret 통일"
+```
+
+---
+
+## Task 2: admin mint-token 라우트 (스키마 + 구현 + 테스트)
+
+`POST /api/packs/admin/mint-token` 신규. Pydantic 스키마 추가 + 라우트 구현 + 통합 테스트.
+
+**Files:**
+- Modify: `packs-lab/app/models.py` (스키마 2개 추가)
+- Modify: `packs-lab/app/routes.py` (import 보강 + 라우트 추가)
+- Create: `packs-lab/tests/test_routes.py` (mint-token 관련 테스트만 우선)
+
+- [ ] **Step 1: failing 테스트 작성**
+
+`packs-lab/tests/test_routes.py`:
+
+```python
+"""packs-lab 라우트 통합 테스트.
+
+DSM·Supabase는 mock. HMAC 검증·토큰 발급·검증은 실제 코드 사용.
+"""
+import hashlib
+import hmac
+import json
+import time
+from unittest.mock import patch, MagicMock
+
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+SECRET = "test-secret-do-not-use-in-prod"
+
+
+def _hmac_headers(body_bytes: bytes) -> dict:
+    """body에 대한 X-Timestamp + X-Signature 헤더 생성."""
+    ts = str(int(time.time()))
+    sig = hmac.new(SECRET.encode(), ts.encode() + b"." + body_bytes, hashlib.sha256).hexdigest()
+    return {"X-Timestamp": ts, "X-Signature": sig}
+
+
+def test_mint_token_hmac_required():
+    """HMAC 헤더 누락 → 401."""
+    client = TestClient(app)
+    body = {"tier": "pro", "label": "샘플", "filename": "x.zip", "size_bytes": 1024}
+    resp = client.post("/api/packs/admin/mint-token", json=body)
+    assert resp.status_code == 401
+
+
+def test_mint_token_returns_valid_token():
+    """발급된 token이 verify_upload_token으로 통과해야 한다."""
+    from app.auth import verify_upload_token
+
+    body = {"tier": "pro", "label": "샘플", "filename": "test.zip", "size_bytes": 2048}
+    body_bytes = json.dumps(body).encode()
+    headers = _hmac_headers(body_bytes)
+    headers["Content-Type"] = "application/json"
+
+    client = TestClient(app)
+    resp = client.post("/api/packs/admin/mint-token", content=body_bytes, headers=headers)
+    assert resp.status_code == 200
+    data = resp.json()
+    assert "token" in data and "expires_at" in data and "jti" in data
+
+    payload = verify_upload_token(data["token"])
+    assert payload["tier"] == "pro"
+    assert payload["label"] == "샘플"
+    assert payload["filename"] == "test.zip"
+    assert payload["size_bytes"] == 2048
+    assert payload["jti"] == data["jti"]
+
+
+def test_mint_token_invalid_filename():
+    """허용 외 확장자 → 400."""
+    body = {"tier": "pro", "label": "샘플", "filename": "x.exe", "size_bytes": 1024}
+    body_bytes = json.dumps(body).encode()
+    headers = _hmac_headers(body_bytes)
+    headers["Content-Type"] = "application/json"
+
+    client = TestClient(app)
+    resp = client.post("/api/packs/admin/mint-token", content=body_bytes, headers=headers)
+    assert resp.status_code == 400
+```
+
+- [ ] **Step 2: 실패 확인**
+
+```bash
+cd packs-lab
+python -m pytest tests/test_routes.py -v
+```
+
+Expected: 모든 테스트 FAIL — `/api/packs/admin/mint-token` 라우트 없음 (404 또는 405).
+
+- [ ] **Step 3: models.py에 스키마 추가**
+
+`packs-lab/app/models.py` 끝부분에 추가:
+
+```python
+class MintTokenRequest(BaseModel):
+    """Vercel → backend: admin upload 토큰 발급 요청."""
+    tier: PackTier
+    label: str = Field(..., max_length=200)
+    filename: str = Field(..., max_length=255)
+    size_bytes: int = Field(..., gt=0, le=5 * 1024 * 1024 * 1024)
+
+
+class MintTokenResponse(BaseModel):
+    token: str
+    expires_at: datetime
+    jti: str
+```
+
+- [ ] **Step 4: routes.py에 mint-token 라우트 추가**
+
+`packs-lab/app/routes.py` 상단 import 블록에 다음을 추가:
+
+```python
+import time
+from datetime import timezone
+```
+
+(이미 `import uuid`, `from datetime import datetime`은 있음)
+
+`from .auth import` 라인을 다음과 같이 확장:
+
+```python
+from .auth import mint_upload_token, verify_request_hmac, verify_upload_token
+```
+
+`from .models import` 라인을 다음과 같이 확장:
+
+```python
+from .models import (
+    MintTokenRequest,
+    MintTokenResponse,
+    PackFileItem,
+    SignLinkRequest,
+    SignLinkResponse,
+    UploadResponse,
+)
+```
+
+상수 추가 (`MAX_BYTES` 다음 줄에):
+
+```python
+UPLOAD_TOKEN_TTL_SEC = int(os.getenv("UPLOAD_TOKEN_TTL_SEC", "1800"))  # 30분 default
+```
+
+라우트 추가 (`sign_link` 함수 다음, `upload` 함수 앞):
+
+```python
+@router.post("/admin/mint-token", response_model=MintTokenResponse)
+async def mint_token(
+    request: Request,
+    x_timestamp: str = Header(""),
+    x_signature: str = Header(""),
+):
+    body = await request.body()
+    verify_request_hmac(body, x_timestamp, x_signature)
+    payload = MintTokenRequest.model_validate_json(body)
+    _check_filename(payload.filename)
+
+    jti = str(uuid.uuid4())
+    expires_ts = int(time.time()) + UPLOAD_TOKEN_TTL_SEC
+    token = mint_upload_token({
+        "tier": payload.tier,
+        "label": payload.label,
+        "filename": payload.filename,
+        "size_bytes": payload.size_bytes,
+        "jti": jti,
+        "expires_at": expires_ts,
+    })
+    return MintTokenResponse(
+        token=token,
+        expires_at=datetime.fromtimestamp(expires_ts, tz=timezone.utc),
+        jti=jti,
+    )
+```
+
+- [ ] **Step 5: 테스트 통과 확인**
+
+```bash
+cd packs-lab
+python -m pytest tests/test_routes.py -v
+```
+
+Expected: 3 passed.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add packs-lab/app/models.py packs-lab/app/routes.py packs-lab/tests/test_routes.py
+git commit -m "feat(packs-lab): POST /api/packs/admin/mint-token 라우트 + 통합 테스트"
+```
+
+---
+
+## Task 3: 기존 4 라우트 통합 테스트 (sign-link / upload / list / delete)
+
+기존 라우트는 변경 없음. 테스트만 추가해 회귀 안전망 확보.
+
+**Files:**
+- Modify: `packs-lab/tests/test_routes.py` (테스트 8개 추가)
+
+- [ ] **Step 1: sign-link 테스트 추가**
+
+`tests/test_routes.py` 끝에 추가:
+
+```python
+def test_sign_link_hmac_required():
+    """HMAC 헤더 없으면 401."""
+    client = TestClient(app)
+    body = {"file_path": "/volume1/docker/webpage/media/packs/pro/x.zip"}
+    resp = client.post("/api/packs/sign-link", json=body)
+    assert resp.status_code == 401
+
+
+def test_sign_link_outside_base_dir():
+    """PACK_BASE_DIR 외부 경로 → 400."""
+    body = {"file_path": "/etc/passwd"}
+    body_bytes = json.dumps(body).encode()
+    headers = _hmac_headers(body_bytes)
+    headers["Content-Type"] = "application/json"
+
+    client = TestClient(app)
+    resp = client.post("/api/packs/sign-link", content=body_bytes, headers=headers)
+    assert resp.status_code == 400
+
+
+def test_sign_link_calls_dsm():
+    """DSM client 호출되고 응답 URL 반환."""
+    from datetime import datetime, timezone
+    from unittest.mock import AsyncMock
+
+    body = {"file_path": "/volume1/docker/webpage/media/packs/pro/sample.zip"}
+    body_bytes = json.dumps(body).encode()
+    headers = _hmac_headers(body_bytes)
+    headers["Content-Type"] = "application/json"
+
+    fake_url = "https://gahusb.synology.me:5001/sharing/abc123"
+    fake_expires = datetime(2026, 5, 5, 13, 0, tzinfo=timezone.utc)
+
+    with patch("app.routes.create_share_link", new=AsyncMock(return_value=(fake_url, fake_expires))) as mock:
+        client = TestClient(app)
+        resp = client.post("/api/packs/sign-link", content=body_bytes, headers=headers)
+
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["url"] == fake_url
+    mock.assert_awaited_once()
+```
+
+- [ ] **Step 2: upload 테스트 추가**
+
+```python
+def _make_upload_token(tier="pro", label="샘플", filename="test.zip", size_bytes=1024, jti=None, ttl=1800):
+    """테스트용 upload token 생성. mint_token endpoint 거치지 않고 직접."""
+    import uuid
+    from app.auth import mint_upload_token
+    return mint_upload_token({
+        "tier": tier,
+        "label": label,
+        "filename": filename,
+        "size_bytes": size_bytes,
+        "jti": jti or str(uuid.uuid4()),
+        "expires_at": int(time.time()) + ttl,
+    })
+
+
+def test_upload_token_required():
+    """Authorization Bearer 누락 → 401."""
+    client = TestClient(app)
+    resp = client.post("/api/packs/upload", files={"file": ("x.zip", b"hello")})
+    assert resp.status_code == 401
+
+
+def test_upload_size_mismatch(tmp_path, monkeypatch):
+    """토큰 size_bytes ≠ 실제 → 400 + 파일 정리됨."""
+    monkeypatch.setattr("app.routes.PACK_BASE_DIR", tmp_path)
+    token = _make_upload_token(size_bytes=999)  # 실제 5바이트지만 토큰엔 999
+
+    client = TestClient(app)
+    resp = client.post(
+        "/api/packs/upload",
+        files={"file": ("test.zip", b"hello")},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert resp.status_code == 400
+    assert "크기" in resp.json()["detail"]
+
+
+def test_upload_jti_replay(tmp_path, monkeypatch):
+    """같은 jti 토큰 두 번 → 두 번째 409."""
+    monkeypatch.setattr("app.routes.PACK_BASE_DIR", tmp_path)
+
+    fake_supabase = MagicMock()
+    fake_supabase.table.return_value.insert.return_value.execute.return_value = MagicMock(
+        data=[{"uploaded_at": "2026-05-05T12:00:00+00:00"}]
+    )
+
+    token = _make_upload_token(filename="replay.zip", size_bytes=5, jti="replay-jti-1")
+
+    with patch("app.routes._supabase", return_value=fake_supabase):
+        client = TestClient(app)
+
+        # 1차: 성공
+        resp1 = client.post(
+            "/api/packs/upload",
+            files={"file": ("replay.zip", b"hello")},
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert resp1.status_code == 200
+
+        # 2차: 동일 토큰 재사용 — 두 번째 파일은 다른 이름으로 보내 파일명 충돌 회피
+        resp2 = client.post(
+            "/api/packs/upload",
+            files={"file": ("replay.zip", b"world")},
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        assert resp2.status_code == 409
+```
+
+- [ ] **Step 3: list / delete 테스트 추가**
+
+```python
+def test_list_returns_active_only():
+    """mock supabase가 deleted_at IS NULL 행만 반환하는지 (쿼리 빌더 호출 검증)."""
+    fake_rows = [
+        {
+            "id": "11111111-1111-1111-1111-111111111111",
+            "min_tier": "pro",
+            "label": "샘플",
+            "file_path": "/volume1/docker/webpage/media/packs/pro/a.zip",
+            "filename": "a.zip",
+            "size_bytes": 1024,
+            "sort_order": 0,
+            "uploaded_at": "2026-05-05T12:00:00+00:00",
+        }
+    ]
+
+    fake_supabase = MagicMock()
+    chain = fake_supabase.table.return_value.select.return_value
+    chain.is_.return_value.order.return_value.order.return_value.execute.return_value = MagicMock(data=fake_rows)
+
+    body_bytes = b""
+    headers = _hmac_headers(body_bytes)
+
+    with patch("app.routes._supabase", return_value=fake_supabase):
+        client = TestClient(app)
+        resp = client.get("/api/packs/list", headers=headers)
+
+    assert resp.status_code == 200
+    items = resp.json()
+    assert len(items) == 1
+    assert items[0]["filename"] == "a.zip"
+    fake_supabase.table.return_value.select.return_value.is_.assert_called_with("deleted_at", "null")
+
+
+def test_delete_soft_deletes():
+    """DELETE 시 supabase update에 deleted_at ISO timestamp가 들어가야 한다."""
+    fake_supabase = MagicMock()
+    fake_supabase.table.return_value.update.return_value.eq.return_value.execute.return_value = MagicMock(
+        data=[{"id": "abc"}]
+    )
+
+    body_bytes = b""
+    headers = _hmac_headers(body_bytes)
+
+    with patch("app.routes._supabase", return_value=fake_supabase):
+        client = TestClient(app)
+        resp = client.delete("/api/packs/abc", headers=headers)
+
+    assert resp.status_code == 200
+    update_call = fake_supabase.table.return_value.update.call_args
+    update_kwargs = update_call.args[0]
+    assert "deleted_at" in update_kwargs
+    # ISO 8601 timestamp 형식 검증 (예: 2026-05-05T12:00:00+00:00)
+    assert "T" in update_kwargs["deleted_at"]
+```
+
+- [ ] **Step 4: 테스트 실행**
+
+```bash
+cd packs-lab
+python -m pytest tests/test_routes.py -v
+```
+
+Expected: 11 passed (3 from Task 2 + 3 sign-link + 3 upload + 2 list/delete).
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add packs-lab/tests/test_routes.py
+git commit -m "test(packs-lab): 기존 4 라우트 통합 테스트 (sign-link, upload, list, delete)"
+```
+
+---
+
+## Task 4: `tests/test_dsm_client.py` — DSM client mock 테스트
+
+**Files:**
+- Create: `packs-lab/tests/test_dsm_client.py`
+
+- [ ] **Step 1: DSM client 테스트 작성**
+
+`packs-lab/tests/test_dsm_client.py`:
+
+```python
+"""DSM 7.x API client 테스트 — httpx mock으로 외부 호출 차단."""
+import asyncio
+from unittest.mock import patch, MagicMock
+
+import pytest
+import httpx
+
+from app.dsm_client import create_share_link, DSMError, _login, _logout
+
+
+@pytest.fixture(autouse=True)
+def _dsm_env(monkeypatch):
+    monkeypatch.setenv("DSM_HOST", "https://test-nas:5001")
+    monkeypatch.setenv("DSM_USER", "test-user")
+    monkeypatch.setenv("DSM_PASS", "test-pass")
+    # 모듈 캐시도 갱신
+    from app import dsm_client
+    monkeypatch.setattr(dsm_client, "DSM_HOST", "https://test-nas:5001")
+    monkeypatch.setattr(dsm_client, "DSM_USER", "test-user")
+    monkeypatch.setattr(dsm_client, "DSM_PASS", "test-pass")
+
+
+def _make_response(json_data, status_code=200):
+    """httpx.Response mock."""
+    mock = MagicMock(spec=httpx.Response)
+    mock.json.return_value = json_data
+    mock.status_code = status_code
+    mock.raise_for_status = MagicMock()
+    return mock
+
+
+def test_create_share_link_login_logout():
+    """login → Sharing.create → logout 순서가 보장되어야 한다."""
+    call_order = []
+
+    async def fake_get(self, url, *, params=None, **kw):
+        api = (params or {}).get("api", "")
+        method = (params or {}).get("method", "")
+        call_order.append(f"{api}.{method}")
+        if api == "SYNO.API.Auth" and method == "login":
+            return _make_response({"success": True, "data": {"sid": "fake-sid"}})
+        if api == "SYNO.API.Auth" and method == "logout":
+            return _make_response({"success": True})
+        if api == "SYNO.FileStation.Sharing" and method == "create":
+            return _make_response({
+                "success": True,
+                "data": {"links": [{"url": "https://test-nas:5001/sharing/abc"}]},
+            })
+        return _make_response({"success": False, "error": "unexpected"})
+
+    with patch.object(httpx.AsyncClient, "get", new=fake_get):
+        url, expires_at = asyncio.run(create_share_link("/volume1/test/file.zip", expires_in_sec=3600))
+
+    assert url == "https://test-nas:5001/sharing/abc"
+    assert call_order == [
+        "SYNO.API.Auth.login",
+        "SYNO.FileStation.Sharing.create",
+        "SYNO.API.Auth.logout",
+    ]
+
+
+def test_create_share_link_returns_url_and_expiry():
+    """응답 파싱 — links[0].url 사용."""
+    async def fake_get(self, url, *, params=None, **kw):
+        method = (params or {}).get("method", "")
+        if method == "login":
+            return _make_response({"success": True, "data": {"sid": "sid"}})
+        if method == "create":
+            return _make_response({
+                "success": True,
+                "data": {"links": [{"url": "https://nas/sharing/xyz"}]},
+            })
+        return _make_response({"success": True})
+
+    with patch.object(httpx.AsyncClient, "get", new=fake_get):
+        url, expires_at = asyncio.run(create_share_link("/volume1/test/file.zip", expires_in_sec=7200))
+
+    assert url == "https://nas/sharing/xyz"
+    assert expires_at is not None
+
+
+def test_dsm_login_failure_raises():
+    """login API success=False → DSMError."""
+    async def fake_get(self, url, *, params=None, **kw):
+        return _make_response({"success": False, "error": {"code": 400}})
+
+    with patch.object(httpx.AsyncClient, "get", new=fake_get):
+        with pytest.raises(DSMError, match="login 실패"):
+            asyncio.run(create_share_link("/volume1/test/file.zip"))
+
+
+def test_dsm_share_failure_logs_out():
+    """Sharing.create 실패해도 logout 호출 (try/finally)."""
+    call_order = []
+
+    async def fake_get(self, url, *, params=None, **kw):
+        method = (params or {}).get("method", "")
+        call_order.append(method)
+        if method == "login":
+            return _make_response({"success": True, "data": {"sid": "sid"}})
+        if method == "create":
+            return _make_response({"success": False, "error": {"code": 401}})
+        if method == "logout":
+            return _make_response({"success": True})
+        return _make_response({"success": False})
+
+    with patch.object(httpx.AsyncClient, "get", new=fake_get):
+        with pytest.raises(DSMError, match="Sharing.create 실패"):
+            asyncio.run(create_share_link("/volume1/test/file.zip"))
+
+    assert "login" in call_order
+    assert "logout" in call_order, "logout이 호출되지 않음 (finally 누락 의심)"
+```
+
+- [ ] **Step 2: 테스트 실행**
+
+```bash
+cd packs-lab
+python -m pytest tests/test_dsm_client.py -v
+```
+
+Expected: 4 passed.
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add packs-lab/tests/test_dsm_client.py
+git commit -m "test(packs-lab): DSM client mock 테스트 (login/share/logout 순서)"
+```
+
+---
+
+## Task 5: DELETE 라우트 docstring 수정
+
+`routes.py` 모듈 docstring의 한 줄 변경.
+
+**Files:**
+- Modify: `packs-lab/app/routes.py:1-7` (모듈 docstring)
+
+- [ ] **Step 1: docstring 수정**
+
+`packs-lab/app/routes.py` 첫 docstring을 다음으로 변경:
+
+```python
+"""packs-lab API 엔드포인트.
+
+- POST /api/packs/sign-link — Vercel HMAC 인증 → DSM 공유 링크
+- POST /api/packs/admin/mint-token — Vercel HMAC 인증 → 일회성 upload 토큰
+- POST /api/packs/upload — 일회성 토큰 인증 → multipart 저장 + supabase INSERT
+- GET /api/packs/list — Vercel HMAC 인증 → pack_files 전체 조회
+- DELETE /api/packs/{file_id} — Vercel HMAC 인증 → soft delete (DSM 공유는 자동 만료)
+"""
+```
+
+(변경: `정리` → `자동 만료`, mint-token 줄 추가)
+
+- [ ] **Step 2: 회귀 검증**
+
+```bash
+cd packs-lab
+python -m pytest tests/ -v
+```
+
+Expected: 모든 테스트 그대로 통과 (15 passed).
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add packs-lab/app/routes.py
+git commit -m "docs(packs-lab): routes 모듈 docstring 정리 (mint-token 추가, DSM 자동 만료 명시)"
+```
+
+---
+
+## Task 6: Supabase `pack_files` DDL
+
+운영 적용 시 Supabase SQL editor에서 실행할 SQL 파일.
+
+**Files:**
+- Create: `packs-lab/supabase/pack_files.sql`
+
+- [ ] **Step 1: SQL 파일 생성**
+
+`packs-lab/supabase/pack_files.sql`:
+
+```sql
+-- pack_files: NAS에 저장된 다운로드 가능한 패키지 파일 메타
+-- 운영 적용: Supabase Dashboard → SQL editor에서 실행
+create table if not exists public.pack_files (
+    id              uuid        primary key default gen_random_uuid(),
+    min_tier        text        not null check (min_tier in ('starter','pro','master')),
+    label           text        not null,
+    file_path       text        not null unique,
+    filename        text        not null,
+    size_bytes      bigint      not null check (size_bytes > 0),
+    sort_order      integer     not null default 0,
+    uploaded_at     timestamptz not null default now(),
+    deleted_at      timestamptz
+);
+
+-- list 라우트 hot path: deleted_at IS NULL + tier/order 정렬
+create index if not exists pack_files_active_idx
+    on public.pack_files (min_tier, sort_order)
+    where deleted_at is null;
+
+-- soft-deleted 통계 / cleanup 잡 대비
+create index if not exists pack_files_deleted_at_idx
+    on public.pack_files (deleted_at)
+    where deleted_at is not null;
+```
+
+- [ ] **Step 2: 커밋**
+
+```bash
+git add packs-lab/supabase/pack_files.sql
+git commit -m "feat(packs-lab): Supabase pack_files DDL + 활성/삭제 인덱스"
+```
+
+---
+
+## Task 7: 인프라 통합 — docker-compose / nginx / .env.example / deploy-nas.sh
+
+**Files:**
+- Modify: `docker-compose.yml` (packs-lab 서비스 추가, env에 PACK_BASE_DIR/PACK_HOST_DIR 포함)
+- Modify: `nginx/default.conf` (`/api/packs/` 라우팅)
+- Modify: `.env.example` (DSM/HMAC/Supabase 6 + PACK 3 path)
+- Modify: `scripts/deploy-nas.sh` (SERVICES 화이트리스트에 `packs-lab` 추가 — 누락 시 NAS 컨테이너 미등장)
+
+- [ ] **Step 1: docker-compose.yml — packs-lab 서비스 추가**
+
+`docker-compose.yml`에서 다른 lab 서비스(예: `realestate-lab`) 정의 다음에 추가:
+
+```yaml
+  packs-lab:
+    build:
+      context: ./packs-lab
+      dockerfile: Dockerfile
+    container_name: packs-lab
+    restart: unless-stopped
+    ports:
+      - "18950:8000"
+    environment:
+      TZ: Asia/Seoul
+      DSM_HOST: ${DSM_HOST}
+      DSM_USER: ${DSM_USER}
+      DSM_PASS: ${DSM_PASS}
+      BACKEND_HMAC_SECRET: ${BACKEND_HMAC_SECRET}
+      SUPABASE_URL: ${SUPABASE_URL}
+      SUPABASE_SERVICE_KEY: ${SUPABASE_SERVICE_KEY}
+      UPLOAD_TOKEN_TTL_SEC: ${UPLOAD_TOKEN_TTL_SEC:-1800}
+    volumes:
+      - ${PACK_DATA_PATH:-./data/packs}:/volume1/docker/webpage/media/packs
+```
+
+- [ ] **Step 2: nginx/default.conf — /api/packs/ 라우팅**
+
+기존 `location /api/agent-office/ { ... }` 다음(또는 다른 `/api/...` 라우트들 근처)에 추가:
+
+```nginx
+    location /api/packs/ {
+        proxy_pass http://packs-lab:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # 5GB 멀티파트 업로드 대응
+        client_max_body_size 5G;
+        proxy_request_buffering off;
+        proxy_read_timeout 1800s;
+        proxy_send_timeout 1800s;
+    }
+```
+
+- [ ] **Step 3: .env.example — 6+1 환경변수 추가**
+
+`.env.example` 끝에 추가:
+
+```bash
+
+# ─── packs-lab — NAS 자료 다운로드 자동화 ────────────────────────────
+# Synology DSM 7.x 인증 (공유 링크 발급용)
+DSM_HOST=https://gahusb.synology.me:5001
+DSM_USER=
+DSM_PASS=
+
+# Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값)
+BACKEND_HMAC_SECRET=
+
+# Supabase pack_files 테이블 접근 (service_role 키, RLS 우회)
+SUPABASE_URL=https://<project>.supabase.co
+SUPABASE_SERVICE_KEY=
+
+# admin upload 토큰 TTL (초). default 1800 = 30분
+UPLOAD_TOKEN_TTL_SEC=1800
+
+# 로컬 개발: ./data/packs / NAS 운영: /volume1/docker/webpage/media/packs
+PACK_DATA_PATH=./data/packs
+```
+
+- [ ] **Step 4: docker compose config 검증**
+
+```bash
+cd C:\Users\jaeoh\Desktop\workspace\web-backend
+docker compose config 2>&1 | grep -A 10 "packs-lab:"
+```
+
+Expected: packs-lab 서비스 정의가 정상 출력 (port mapping, environment 변수, volumes 모두 보임). 환경변수가 비어있어도 docker compose config는 통과.
+
+> ⚠️ Docker가 로컬에 설치되어 있어야 검증 가능. 실제 실행은 NAS에서. 로컬 docker가 없으면 step skip하고 nginx config 문법만 별도 검증.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add docker-compose.yml nginx/default.conf .env.example
+git commit -m "chore(infra): packs-lab 서비스 통합 (compose 18950 + nginx 5GB streaming + env 7개)"
+```
+
+---
+
+## Task 8: NAS 디렉토리 준비 가이드 + 문서 갱신
+
+**Files:**
+- Modify: `web-backend/CLAUDE.md` (5곳 갱신)
+- Modify: `workspace/CLAUDE.md` (1줄 추가)
+
+- [ ] **Step 1: web-backend/CLAUDE.md — 1.프로젝트 개요**
+
+찾을 위치 (1.프로젝트 개요 섹션):
+
+```
+- **서비스**: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, deployer (9개)
+```
+
+다음으로 수정:
+
+```
+- **서비스**: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, packs-lab, deployer (10개)
+```
+
+같은 섹션의 인프라 줄도:
+
+```
+- **인프라**: Docker Compose (10컨테이너) + Nginx(리버스 프록시) + Gitea Webhook 자동 배포
+```
+
+- [ ] **Step 2: web-backend/CLAUDE.md — 4.Docker 서비스 표**
+
+표 마지막에 신규 행 추가 (deployer 행 직전 또는 personal 행 다음 — 알파벳 순):
+
+```
+| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (DSM 공유 링크 + 5GB 업로드, Vercel SaaS와 HMAC 통신) |
+```
+
+- [ ] **Step 3: web-backend/CLAUDE.md — 5.Nginx 라우팅 표**
+
+표 적절한 위치에 신규 행 추가:
+
+```
+| `/api/packs/` | `packs-lab:8000` | 5GB 업로드 대응 (`client_max_body_size 5G`, `proxy_request_buffering off`, 1800s timeout) |
+```
+
+- [ ] **Step 4: web-backend/CLAUDE.md — 8.로컬 개발 표**
+
+표 끝에 신규 행 추가:
+
+```
+| Packs Lab | http://localhost:18950 |
+```
+
+- [ ] **Step 5: web-backend/CLAUDE.md — 9.서비스별 packs-lab 신규 섹션**
+
+`### deployer (deployer/)` 섹션 직전에 추가 (또는 personal 다음):
+
+```
+### packs-lab (packs-lab/)
+- NAS 자료 다운로드 자동화 — Synology DSM 공유링크 발급 + 5GB 멀티파트 업로드 수신
+- Vercel SaaS와 HMAC 인증으로 통신, 사용자 인증은 Vercel이 Supabase로 처리 (본 서비스는 외부 인증 없음)
+- DB: 외부 Supabase `pack_files` 테이블 (DDL: `packs-lab/supabase/pack_files.sql`)
+- 파일 구조: `app/main.py`, `app/auth.py`, `app/dsm_client.py`, `app/routes.py`, `app/models.py`
+- 운영 디렉토리: `/volume1/docker/webpage/media/packs/{starter,pro,master}/` (NAS PUID:PGID 권한 필요)
+
+**환경변수**
+- `DSM_HOST` / `DSM_USER` / `DSM_PASS`: Synology DSM 7.x 인증 (공유 링크 발급용)
+- `BACKEND_HMAC_SECRET`: Vercel SaaS와 양쪽 공유 시크릿 (HMAC SHA256)
+- `SUPABASE_URL` / `SUPABASE_SERVICE_KEY`: Supabase pack_files 테이블 접근 (service_role, RLS 우회)
+- `UPLOAD_TOKEN_TTL_SEC`: admin upload 토큰 TTL (기본 1800초 = 30분)
+- `PACK_DATA_PATH`: 호스트 마운트 경로 (로컬 `./data/packs`, NAS `/volume1/docker/webpage/media/packs`)
+
+**HMAC 인증 패턴**
+- Vercel → backend 요청: `X-Timestamp` (UNIX 초) + `X-Signature` (HMAC_SHA256(timestamp + "." + body, secret))
+- Replay 방어: 타임스탬프 ±5분 윈도우
+- admin browser → backend upload: `Authorization: Bearer <token>` (jti 단발성)
+
+**packs-lab API 목록**
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| POST | `/api/packs/sign-link` | Vercel HMAC → DSM Sharing.create로 4시간 유효 다운로드 URL 발급 |
+| POST | `/api/packs/admin/mint-token` | Vercel HMAC → 일회성 upload 토큰 발급 (기본 30분 TTL) |
+| POST | `/api/packs/upload` | Bearer token → multipart 5GB 저장 + Supabase INSERT |
+| GET | `/api/packs/list` | Vercel HMAC → 활성 pack_files 목록 (deleted_at IS NULL) |
+| DELETE | `/api/packs/{file_id}` | Vercel HMAC → soft delete (DSM 공유는 자동 만료) |
+```
+
+- [ ] **Step 6: workspace/CLAUDE.md — 컨테이너 표 한 줄 추가**
+
+`workspace/CLAUDE.md`의 "Docker 서비스 & 포트" 표에 추가:
+
+```
+| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (Vercel SaaS와 HMAC 통신) |
+```
+
+(personal 행 다음 또는 적절한 위치)
+
+- [ ] **Step 7: 커밋 (web-backend repo의 CLAUDE.md만)**
+
+작업 디렉토리는 `C:\Users\jaeoh\Desktop\workspace\web-backend`. 그 안의 `CLAUDE.md`만 git 추적 대상.
+
+```bash
+git add CLAUDE.md
+git commit -m "docs(claude): packs-lab 10번째 서비스로 등록 (포트/라우팅/API 표 + 신규 섹션)"
+```
+
+> ℹ️ `workspace/CLAUDE.md`(상위 디렉토리의 워크스페이스 메모)는 git repo가 아님. 텍스트 편집만 하고 commit 대상에서 제외.
+
+---
+
+## Task 9: 회귀 검증 + NAS 디렉토리 가이드
+
+전체 테스트 + docker compose config + NAS 배포 전 가이드.
+
+**Files:**
+- (검증만)
+
+- [ ] **Step 1: 전체 pytest**
+
+```bash
+cd packs-lab
+python -m pytest tests/ -v
+```
+
+Expected: 모든 테스트 통과 (test_auth + test_routes + test_dsm_client = 약 15+ tests).
+
+- [ ] **Step 2: docker compose config 검증**
+
+```bash
+cd C:\Users\jaeoh\Desktop\workspace\web-backend
+docker compose config 2>&1 | tail -30
+```
+
+Expected: error 없이 packs-lab 포함된 전체 config 출력.
+
+> ⚠️ Docker 미설치 시 skip. NAS에서 git push 후 webhook 배포 시점에 검증됨.
+
+- [ ] **Step 3: NAS 배포 전 가이드 출력**
+
+배포 전 NAS에서 SSH로 1회 실행할 명령들을 README 또는 NAS 배포 노트로 정리. 본 task에서는 명령만 제시 (실행은 사용자):
+
+```bash
+# NAS SSH로 접속 후
+mkdir -p /volume1/docker/webpage/media/packs/{starter,pro,master}
+chown -R PUID:PGID /volume1/docker/webpage/media/packs  # PUID/PGID는 .env 값 사용
+
+# .env에 신규 환경변수 추가 (DSM_*, BACKEND_HMAC_SECRET, SUPABASE_*, UPLOAD_TOKEN_TTL_SEC, PACK_DATA_PATH=/volume1/docker/webpage/media/packs)
+
+# Supabase에서 packs-lab/supabase/pack_files.sql 실행
+
+# git push 후 webhook이 자동 배포
+```
+
+- [ ] **Step 4: 최종 commit (검증 결과 빈 commit으로 마일스톤 표시 — 선택)**
+
+```bash
+# 만약 위 step에서 어떤 자동 수정이 있었으면 commit. 없으면 skip.
+git status
+```
+
+회귀 검증으로 변경 사항 없으면 별도 commit 없이 종료.
+
+---
+
+## 완료 기준
+
+- 모든 task의 step 통과 (체크박스 모두 체크)
+- `cd packs-lab && python -m pytest tests/ -v` — 통과 (test_auth + test_routes + test_dsm_client)
+- `docker compose config` — packs-lab 포함된 전체 config 정상
+- web-backend/CLAUDE.md 5곳 갱신 + workspace/CLAUDE.md 1줄
+- Supabase DDL 파일 존재 (운영 적용은 사용자가 NAS에서 SQL editor로)
+- NAS 디렉토리 준비 명령은 사용자가 SSH로 실행 (배포 전 1회)
+
+---
+
+## 배포
+
+git push → Gitea webhook → deployer rsync → docker compose up -d --build (자동).
+
+**배포 전 사용자 액션 (1회)**:
+1. Supabase에서 `pack_files` 테이블 생성 (DDL 실행)
+2. NAS SSH로 `/volume1/docker/webpage/media/packs/{starter,pro,master}` 디렉토리 생성 + 권한
+3. NAS `.env`에 신규 7개 환경변수 입력 (DSM 인증, HMAC secret, Supabase 키 등)
+
+---
+
+## 참고 — 후속 별도 plan (스코프 외)
+
+- Vercel SaaS-side admin UI / 사용자 다운로드 UI / Supabase user 테이블
+- DSM 공유 추적 (즉시 차단 필요 시)
+- deleted_at + N일 후 실제 파일 삭제 cron
+- multi-admin 토큰 발급 권한 분리
+- resumable multipart 업로드 (5GB tus 등)
+- pack_files sort_order 편집 endpoint
+- 모니터링 (업로드 실패율, DSM API latency)

docs/superpowers/plans/2026-05-09-gpu-video-offload.md

@@ -0,0 +1,737 @@
+# GPU 영상 인코딩 오프로드 — 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development.
+
+**Goal:** NAS의 ffmpeg 영상 인코딩을 Windows PC(RTX 5070 Ti) NVENC로 오프로드.
+
+**Architecture:** music-lab(NAS) → HTTP POST → music_ai(Windows, port 8765 `/encode_video`) → ffmpeg NVENC → SMB로 NAS에 직접 mp4 저장. Windows 서버 다운 시 NAS는 즉시 실패.
+
+**Tech Stack:** httpx (NAS 측 HTTP 클라이언트), FastAPI (Windows 서버 endpoint), ffmpeg.exe with NVENC.
+
+**Spec:** `docs/superpowers/specs/2026-05-09-gpu-video-offload-design.md`
+
+---
+
+## File Structure
+
+| 경로 | 책임 |
+|------|------|
+| `music_ai/video_encoder.py` (new) | 경로 변환 + ffmpeg NVENC subprocess 호출 + 검증 |
+| `music_ai/server.py` (modify) | `/encode_video` POST endpoint 등록, `/health`에 ffmpeg/nvenc 정보 추가 |
+| `music_ai/.env.example` (modify) | NAS_VOLUME_PREFIX, WINDOWS_DRIVE_ROOT, FFMPEG_PATH 문서화 |
+| `music_ai/tests/test_video_encoder.py` (new) | translate_path, encode endpoint 단위 테스트 |
+| `music-lab/app/pipeline/video.py` (rewrite) | subprocess 제거, httpx로 Windows 서버 호출 |
+| `music-lab/tests/test_video_thumb.py` (rewrite video tests) | respx mock 기반 |
+| `web-backend/docker-compose.yml` (modify) | music-lab env 3개 추가 |
+
+---
+
+## Task 1: Windows `music_ai/video_encoder.py` + 테스트
+
+**Files:**
+- Create: `music_ai/video_encoder.py`
+- Create: `music_ai/tests/test_video_encoder.py`
+
+### Step 1: Write failing test
+
+```python
+# music_ai/tests/test_video_encoder.py
+import os
+import pytest
+from unittest.mock import patch, MagicMock
+from video_encoder import translate_path, encode_video, EncodeError
+
+
+@pytest.fixture
+def env(monkeypatch):
+    monkeypatch.setenv("NAS_VOLUME_PREFIX", "/volume1/")
+    monkeypatch.setenv("WINDOWS_DRIVE_ROOT", "Z:\\")
+    monkeypatch.setenv("FFMPEG_PATH", "C:\\ffmpeg\\bin\\ffmpeg.exe")
+
+
+def test_translate_path_basic(env):
+    assert translate_path("/volume1/docker/webpage/data/x.jpg") == r"Z:\docker\webpage\data\x.jpg"
+
+
+def test_translate_path_nested(env):
+    assert translate_path("/volume1/docker/webpage/data/videos/3/cover.jpg") == r"Z:\docker\webpage\data\videos\3\cover.jpg"
+
+
+def test_translate_path_rejects_bad_prefix(env):
+    with pytest.raises(ValueError):
+        translate_path("/etc/passwd")
+
+
+@patch("subprocess.run")
+def test_encode_video_success(mock_run, env, tmp_path):
+    # 입력 파일 fake
+    cover = tmp_path / "cover.jpg"
+    cover.write_bytes(b"\x00" * 100)
+    audio = tmp_path / "audio.mp3"
+    audio.write_bytes(b"\x00" * 100)
+    out = tmp_path / "video.mp4"
+
+    def fake_run(cmd, **kwargs):
+        # ffmpeg 실행을 흉내내어 출력 파일을 만듦
+        out.write_bytes(b"\x00" * (2 * 1024 * 1024))  # 2MB
+        return MagicMock(returncode=0, stderr="")
+    mock_run.side_effect = fake_run
+
+    # translate_path를 mock해서 입력 경로를 직접 사용
+    with patch("video_encoder.translate_path", side_effect=lambda p: str(p).replace("/volume1/", str(tmp_path) + "/")):
+        result = encode_video(
+            cover_path_nas="/volume1/cover.jpg",
+            audio_path_nas="/volume1/audio.mp3",
+            output_path_nas="/volume1/video.mp4",
+            resolution="1920x1080",
+            duration_sec=120,
+        )
+    assert result["ok"] is True
+    assert result["encoder"] == "h264_nvenc"
+    assert result["output_bytes"] > 1024 * 1024
+
+
+@patch("subprocess.run")
+def test_encode_video_input_missing(mock_run, env, tmp_path):
+    with pytest.raises(EncodeError) as exc:
+        encode_video(
+            cover_path_nas="/volume1/missing.jpg",
+            audio_path_nas="/volume1/missing.mp3",
+            output_path_nas="/volume1/out.mp4",
+            resolution="1920x1080",
+            duration_sec=120,
+        )
+    assert "input_validation" in str(exc.value)
+
+
+@patch("subprocess.run")
+def test_encode_video_ffmpeg_failure(mock_run, env, tmp_path):
+    cover = tmp_path / "cover.jpg"; cover.write_bytes(b"\x00")
+    audio = tmp_path / "audio.mp3"; audio.write_bytes(b"\x00")
+    mock_run.return_value = MagicMock(returncode=1, stderr="invalid codec\n" * 50)
+
+    with patch("video_encoder.translate_path", side_effect=lambda p: str(p).replace("/volume1/", str(tmp_path) + "/")):
+        with pytest.raises(EncodeError) as exc:
+            encode_video(
+                cover_path_nas="/volume1/cover.jpg",
+                audio_path_nas="/volume1/audio.mp3",
+                output_path_nas="/volume1/out.mp4",
+                resolution="1920x1080",
+                duration_sec=120,
+            )
+    assert "ffmpeg" in str(exc.value).lower()
+
+
+@patch("subprocess.run")
+def test_encode_video_output_too_small(mock_run, env, tmp_path):
+    cover = tmp_path / "cover.jpg"; cover.write_bytes(b"\x00")
+    audio = tmp_path / "audio.mp3"; audio.write_bytes(b"\x00")
+    def fake_run(cmd, **kwargs):
+        (tmp_path / "out.mp4").write_bytes(b"\x00" * 100)  # 100 bytes — too small
+        return MagicMock(returncode=0, stderr="")
+    mock_run.side_effect = fake_run
+
+    with patch("video_encoder.translate_path", side_effect=lambda p: str(p).replace("/volume1/", str(tmp_path) + "/")):
+        with pytest.raises(EncodeError) as exc:
+            encode_video(
+                cover_path_nas="/volume1/cover.jpg",
+                audio_path_nas="/volume1/audio.mp3",
+                output_path_nas="/volume1/out.mp4",
+                resolution="1920x1080",
+                duration_sec=120,
+            )
+    assert "output_check" in str(exc.value)
+
+
+def test_resolution_validation(env):
+    with pytest.raises(EncodeError) as exc:
+        encode_video(
+            cover_path_nas="/volume1/x.jpg",
+            audio_path_nas="/volume1/x.mp3",
+            output_path_nas="/volume1/out.mp4",
+            resolution="invalid",
+            duration_sec=120,
+        )
+    assert "resolution" in str(exc.value).lower()
+```
+
+### Step 2: Run test to verify it fails
+
+```bash
+cd music_ai && python -m pytest tests/test_video_encoder.py -v
+```
+
+Expected: ImportError on `video_encoder` module.
+
+### Step 3: Implement `video_encoder.py`
+
+```python
+"""GPU(NVENC) 영상 인코더 — NAS music-lab에서 호출."""
+import os
+import re
+import subprocess
+import logging
+
+logger = logging.getLogger("music_ai.video_encoder")
+
+NAS_VOLUME_PREFIX = os.getenv("NAS_VOLUME_PREFIX", "/volume1/")
+WINDOWS_DRIVE_ROOT = os.getenv("WINDOWS_DRIVE_ROOT", "Z:\\")
+FFMPEG_PATH = os.getenv("FFMPEG_PATH", "ffmpeg")
+FFMPEG_TIMEOUT_S = 180
+RESOLUTION_RE = re.compile(r"^\d{3,4}x\d{3,4}$")
+MIN_OUTPUT_BYTES = 1024 * 1024  # 1MB
+
+
+class EncodeError(Exception):
+    """{stage: input_validation|path_translate|ffmpeg|output_check, message: ...}"""
+    def __init__(self, stage: str, message: str):
+        self.stage = stage
+        self.message = message
+        super().__init__(f"[{stage}] {message}")
+
+
+def translate_path(nas_path: str) -> str:
+    """NAS 절대경로 → Windows SMB 경로."""
+    if not nas_path.startswith(NAS_VOLUME_PREFIX):
+        raise ValueError(f"NAS prefix 불일치: {nas_path}")
+    rel = nas_path[len(NAS_VOLUME_PREFIX):]
+    return WINDOWS_DRIVE_ROOT + rel.replace("/", "\\")
+
+
+def encode_video(*, cover_path_nas: str, audio_path_nas: str,
+                  output_path_nas: str, resolution: str,
+                  duration_sec: int = 0, style: str = "visualizer") -> dict:
+    """영상 인코딩 + Z:\\에 직접 저장."""
+    # 1) Resolution 검증
+    if not RESOLUTION_RE.match(resolution):
+        raise EncodeError("input_validation", f"invalid resolution: {resolution}")
+    w, h = resolution.split("x")
+
+    # 2) 경로 변환
+    try:
+        cover_win = translate_path(cover_path_nas)
+        audio_win = translate_path(audio_path_nas)
+        out_win   = translate_path(output_path_nas)
+    except ValueError as e:
+        raise EncodeError("path_translate", str(e))
+
+    # 3) 입력 존재 확인
+    if not os.path.isfile(cover_win):
+        raise EncodeError("input_validation", f"cover not found: {cover_win}")
+    if not os.path.isfile(audio_win):
+        raise EncodeError("input_validation", f"audio not found: {audio_win}")
+
+    # 4) 출력 디렉토리 보장
+    os.makedirs(os.path.dirname(out_win), exist_ok=True)
+
+    # 5) ffmpeg 명령
+    cmd = [
+        FFMPEG_PATH, "-y",
+        "-hwaccel", "cuda",
+        "-loop", "1", "-i", cover_win,
+        "-i", audio_win,
+        "-filter_complex",
+        f"[0:v]scale={w}:{h},format=yuv420p[bg];"
+        f"[1:a]showwaves=s={w}x200:mode=cline:colors=0xFF4444@0.8[wave];"
+        f"[bg][wave]overlay=0:({h}-200)[out]",
+        "-map", "[out]", "-map", "1:a",
+        "-c:v", "h264_nvenc",
+        "-preset", "p4",
+        "-rc", "vbr",
+        "-cq", "23",
+        "-b:v", "0",
+        "-pix_fmt", "yuv420p",
+        "-c:a", "aac", "-b:a", "192k",
+        "-shortest", out_win,
+    ]
+    logger.info("ffmpeg: %s", " ".join(cmd))
+
+    # 6) ffmpeg 실행
+    import time
+    t0 = time.time()
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=FFMPEG_TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        raise EncodeError("ffmpeg", f"timeout after {FFMPEG_TIMEOUT_S}s")
+    duration_ms = int((time.time() - t0) * 1000)
+
+    if result.returncode != 0:
+        raise EncodeError("ffmpeg", f"returncode={result.returncode}: {result.stderr[-800:]}")
+
+    # 7) 출력 검증
+    if not os.path.isfile(out_win):
+        raise EncodeError("output_check", "output file not created")
+    output_bytes = os.path.getsize(out_win)
+    if output_bytes < MIN_OUTPUT_BYTES:
+        raise EncodeError("output_check", f"output too small: {output_bytes} bytes")
+
+    return {
+        "ok": True,
+        "duration_ms": duration_ms,
+        "output_path_nas": output_path_nas,
+        "output_bytes": output_bytes,
+        "encoder": "h264_nvenc",
+        "preset": "p4",
+    }
+
+
+def check_ffmpeg_nvenc() -> bool:
+    """서버 시작 시 NVENC 가용성 확인."""
+    try:
+        result = subprocess.run(
+            [FFMPEG_PATH, "-encoders"],
+            capture_output=True, text=True, timeout=10,
+        )
+        return "h264_nvenc" in result.stdout
+    except Exception:
+        return False
+```
+
+### Step 4: Run tests
+
+```bash
+cd music_ai && python -m pytest tests/test_video_encoder.py -v
+```
+
+Expected: 6 PASS
+
+### Step 5: Commit
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/music_ai
+git init 2>/dev/null || true   # may not be a git repo, that's OK
+# music_ai is local-only per CLAUDE.md, no remote push
+```
+
+(music_ai is local-only; just save the file. No git push needed.)
+
+---
+
+## Task 2: Windows `music_ai/server.py` — `/encode_video` endpoint + 헬스 확장
+
+**Files:**
+- Modify: `music_ai/server.py`
+- Modify: `music_ai/.env.example`
+
+### Step 1: Read existing server.py to understand FastAPI pattern + existing /health
+
+### Step 2: Add `/encode_video` endpoint
+
+```python
+# server.py — 추가
+from pydantic import BaseModel
+from fastapi import HTTPException
+import video_encoder
+
+
+class EncodeVideoRequest(BaseModel):
+    cover_path_nas: str
+    audio_path_nas: str
+    output_path_nas: str
+    resolution: str = "1920x1080"
+    duration_sec: int = 0
+    style: str = "visualizer"
+
+
+@app.post("/encode_video")
+def encode_video_endpoint(req: EncodeVideoRequest):
+    try:
+        result = video_encoder.encode_video(
+            cover_path_nas=req.cover_path_nas,
+            audio_path_nas=req.audio_path_nas,
+            output_path_nas=req.output_path_nas,
+            resolution=req.resolution,
+            duration_sec=req.duration_sec,
+            style=req.style,
+        )
+        return result
+    except video_encoder.EncodeError as e:
+        # input_validation, path_translate → 400
+        # ffmpeg, output_check → 500
+        status_code = 400 if e.stage in ("input_validation", "path_translate") else 500
+        raise HTTPException(
+            status_code=status_code,
+            detail={"ok": False, "stage": e.stage, "error": e.message},
+        )
+```
+
+### Step 3: 확장된 `/health`
+
+기존 `/health` 응답에 추가:
+```python
+import torch  # if existing health uses it
+import video_encoder
+
+# Module-level cache so health doesn't run ffmpeg every call
+_FFMPEG_NVENC_CACHED = None
+def _ffmpeg_nvenc_available():
+    global _FFMPEG_NVENC_CACHED
+    if _FFMPEG_NVENC_CACHED is None:
+        _FFMPEG_NVENC_CACHED = video_encoder.check_ffmpeg_nvenc()
+    return _FFMPEG_NVENC_CACHED
+
+
+@app.get("/health")
+def health():
+    return {
+        "ok": True,
+        "gpu": torch.cuda.get_device_name(0) if torch.cuda.is_available() else None,  # 또는 기존 형식 유지
+        "musicgen_loaded": True,  # 기존 그대로
+        "ffmpeg_path": video_encoder.FFMPEG_PATH,
+        "ffmpeg_nvenc": _ffmpeg_nvenc_available(),
+    }
+```
+
+(기존 `/health`의 정확한 형식은 코드 읽고 매칭. 위는 예시.)
+
+### Step 4: `.env.example` 업데이트
+
+```env
+# Existing
+MODEL_NAME=facebook/musicgen-stereo-large
+OUTPUT_DIR=output
+SERVER_PORT=8765
+
+# New for video encoder
+NAS_VOLUME_PREFIX=/volume1/
+WINDOWS_DRIVE_ROOT=Z:\
+FFMPEG_PATH=C:\ffmpeg\bin\ffmpeg.exe
+```
+
+### Step 5: 수동 검증
+
+```bash
+cd music_ai && start.bat   # 또는 적절한 시작 명령
+curl http://localhost:8765/health
+# Expected: {..., "ffmpeg_nvenc": true}
+
+curl -X POST http://localhost:8765/encode_video -H "Content-Type: application/json" -d '{
+  "cover_path_nas": "/volume1/docker/webpage/data/videos/3/cover.jpg",
+  "audio_path_nas": "/volume1/docker/webpage/data/1c695df3-8a82-4c09-ba7b-82c07608ec5b.mp3",
+  "output_path_nas": "/volume1/docker/webpage/data/videos/test/video.mp4",
+  "resolution": "1920x1080",
+  "duration_sec": 176
+}'
+# Expected: 200 + duration_ms ~ 10-20초
+```
+
+(실제 파일 경로는 사용자 환경에 맞게 조정)
+
+### Step 6: Commit (music_ai is local-only, no remote)
+
+---
+
+## Task 3: NAS music-lab — `pipeline/video.py` 재작성 + 테스트
+
+**Files:**
+- Rewrite: `music-lab/app/pipeline/video.py`
+- Rewrite: `music-lab/tests/test_video_thumb.py` (video 부분만)
+
+### Step 1: Replace failing tests
+
+```python
+# music-lab/tests/test_video_thumb.py — video 관련 테스트 부분만 교체
+import pytest
+import respx
+import httpx
+from httpx import Response
+from app.pipeline import video, thumb, storage
+
+
+@pytest.fixture
+def encoder_env(monkeypatch):
+    monkeypatch.setenv("WINDOWS_VIDEO_ENCODER_URL", "http://192.168.45.59:8765")
+    monkeypatch.setattr(video, "ENCODER_URL", "http://192.168.45.59:8765")
+
+
+@respx.mock
+def test_generate_video_calls_remote_encoder(encoder_env, tmp_path, monkeypatch):
+    monkeypatch.setattr(storage, "VIDEO_DATA_DIR", str(tmp_path))
+    respx.post("http://192.168.45.59:8765/encode_video").mock(
+        return_value=Response(200, json={
+            "ok": True, "duration_ms": 12000,
+            "output_path_nas": "/volume1/docker/webpage/data/videos/3/video.mp4",
+            "output_bytes": 28000000,
+            "encoder": "h264_nvenc", "preset": "p4",
+        })
+    )
+    out = video.generate(
+        pipeline_id=3,
+        audio_path="/app/data/1c695df3.mp3",
+        cover_path="/app/data/videos/3/cover.jpg",
+        genre="lo-fi", duration_sec=120, resolution="1920x1080",
+        style="visualizer",
+    )
+    assert out["url"].endswith("/3/video.mp4")
+    assert out["used_fallback"] is False
+    assert out["encode_duration_ms"] == 12000
+
+
+@respx.mock
+def test_generate_video_raises_on_connection_error(encoder_env, monkeypatch, tmp_path):
+    monkeypatch.setattr(storage, "VIDEO_DATA_DIR", str(tmp_path))
+    respx.post("http://192.168.45.59:8765/encode_video").mock(
+        side_effect=httpx.ConnectError("Connection refused")
+    )
+    with pytest.raises(video.VideoGenerationError) as exc:
+        video.generate(
+            pipeline_id=4,
+            audio_path="/app/data/x.mp3", cover_path="/app/data/videos/4/cover.jpg",
+            genre="lo-fi", duration_sec=120, resolution="1920x1080",
+        )
+    assert "연결 실패" in str(exc.value) or "Connection" in str(exc.value)
+
+
+@respx.mock
+def test_generate_video_raises_on_500(encoder_env, monkeypatch, tmp_path):
+    monkeypatch.setattr(storage, "VIDEO_DATA_DIR", str(tmp_path))
+    respx.post("http://192.168.45.59:8765/encode_video").mock(
+        return_value=Response(500, json={"ok": False, "stage": "ffmpeg", "error": "bad codec"})
+    )
+    with pytest.raises(video.VideoGenerationError) as exc:
+        video.generate(
+            pipeline_id=5,
+            audio_path="/app/data/x.mp3", cover_path="/app/data/videos/5/cover.jpg",
+            genre="lo-fi", duration_sec=120, resolution="1920x1080",
+        )
+    assert "Windows 인코더 오류" in str(exc.value)
+    assert "ffmpeg" in str(exc.value)
+
+
+def test_generate_video_no_url_configured(monkeypatch, tmp_path):
+    monkeypatch.setattr(storage, "VIDEO_DATA_DIR", str(tmp_path))
+    monkeypatch.setattr(video, "ENCODER_URL", "")
+    with pytest.raises(video.VideoGenerationError) as exc:
+        video.generate(
+            pipeline_id=6,
+            audio_path="/app/data/x.mp3", cover_path="/app/data/videos/6/cover.jpg",
+            genre="lo-fi", duration_sec=120, resolution="1920x1080",
+        )
+    assert "WINDOWS_VIDEO_ENCODER_URL" in str(exc.value)
+
+
+def test_container_to_nas_videos_path(monkeypatch):
+    monkeypatch.setenv("NAS_VIDEOS_ROOT", "/volume1/docker/webpage/data/videos")
+    monkeypatch.setenv("NAS_MUSIC_ROOT", "/volume1/docker/webpage/data/music")
+    assert video._container_to_nas("/app/data/videos/3/cover.jpg") == "/volume1/docker/webpage/data/videos/3/cover.jpg"
+
+
+def test_container_to_nas_music_path(monkeypatch):
+    monkeypatch.setenv("NAS_VIDEOS_ROOT", "/volume1/docker/webpage/data/videos")
+    monkeypatch.setenv("NAS_MUSIC_ROOT", "/volume1/docker/webpage/data/music")
+    assert video._container_to_nas("/app/data/abc.mp3") == "/volume1/docker/webpage/data/music/abc.mp3"
+```
+
+기존 `test_generate_video_calls_ffmpeg`, `test_generate_video_failure_marks_failed` 삭제. thumb 관련 테스트는 그대로 유지.
+
+### Step 2: Run, verify fail
+
+```bash
+cd music-lab && python -m pytest tests/test_video_thumb.py -v
+```
+
+Expected: video 관련 테스트들이 실패 (또는 ImportError).
+
+### Step 3: Rewrite `app/pipeline/video.py`
+
+```python
+"""영상 비주얼 생성 — Windows GPU 서버 (NVENC) 호출.
+
+Windows 서버 다운/실패 시 즉시 예외 (NAS 로컬 폴백 없음 — 의도적 결정).
+"""
+import os
+import logging
+import httpx
+
+from . import storage
+
+logger = logging.getLogger("music-lab.video")
+
+ENCODER_URL = os.getenv("WINDOWS_VIDEO_ENCODER_URL", "")
+ENCODER_TIMEOUT_S = 200  # Windows 서버 ffmpeg 180s + 마진
+
+# NAS 호스트 절대경로 prefix — docker bind mount의 host 측
+NAS_VIDEOS_ROOT = os.getenv("NAS_VIDEOS_ROOT", "/volume1/docker/webpage/data/videos")
+NAS_MUSIC_ROOT = os.getenv("NAS_MUSIC_ROOT", "/volume1/docker/webpage/data/music")
+
+
+class VideoGenerationError(Exception):
+    pass
+
+
+def generate(*, pipeline_id: int, audio_path: str, cover_path: str,
+             genre: str, duration_sec: int, resolution: str = "1920x1080",
+             style: str = "visualizer") -> dict:
+    """원격 Windows GPU 서버 호출. 다운/실패 시 즉시 예외."""
+    if not ENCODER_URL:
+        raise VideoGenerationError(
+            "WINDOWS_VIDEO_ENCODER_URL 미설정 — Windows 인코더 서버 주소 필요"
+        )
+
+    out_path = os.path.join(storage.pipeline_dir(pipeline_id), "video.mp4")
+    nas_audio = _container_to_nas(audio_path)
+    nas_cover = _container_to_nas(cover_path)
+    nas_output = _container_to_nas(out_path)
+
+    payload = {
+        "cover_path_nas": nas_cover,
+        "audio_path_nas": nas_audio,
+        "output_path_nas": nas_output,
+        "resolution": resolution,
+        "duration_sec": duration_sec,
+        "style": style,
+    }
+
+    logger.info("Windows 인코더 호출: pipeline=%d audio=%s", pipeline_id, audio_path)
+    try:
+        with httpx.Client(timeout=ENCODER_TIMEOUT_S) as client:
+            resp = client.post(f"{ENCODER_URL}/encode_video", json=payload)
+    except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout, httpx.NetworkError) as e:
+        raise VideoGenerationError(f"Windows 인코더 연결 실패: {e}")
+
+    if resp.status_code != 200:
+        try:
+            detail = resp.json().get("detail", resp.json())
+        except Exception:
+            detail = {"error": resp.text[:300]}
+        stage = detail.get("stage", "?") if isinstance(detail, dict) else "?"
+        error = detail.get("error", str(detail)) if isinstance(detail, dict) else str(detail)
+        raise VideoGenerationError(
+            f"Windows 인코더 오류 ({resp.status_code}): {stage} — {error}"
+        )
+
+    data = resp.json()
+    if not data.get("ok"):
+        raise VideoGenerationError(f"Windows 인코더 응답 ok=false: {data}")
+
+    return {
+        "url": storage.media_url(pipeline_id, "video.mp4"),
+        "used_fallback": False,
+        "duration_sec": duration_sec,
+        "encode_duration_ms": data.get("duration_ms"),
+        "encoder": data.get("encoder", "h264_nvenc"),
+    }
+
+
+def _container_to_nas(container_path: str) -> str:
+    """ /app/data/videos/3/cover.jpg → /volume1/docker/webpage/data/videos/3/cover.jpg
+        /app/data/abc.mp3            → /volume1/docker/webpage/data/music/abc.mp3
+    """
+    if container_path.startswith("/app/data/videos/"):
+        return container_path.replace("/app/data/videos/", NAS_VIDEOS_ROOT + "/", 1)
+    if container_path.startswith("/app/data/"):
+        rel = container_path[len("/app/data/"):]
+        return NAS_MUSIC_ROOT + "/" + rel
+    return container_path
+```
+
+### Step 4: Run tests
+
+```bash
+cd music-lab && python -m pytest tests/ -v
+```
+
+Expected: 73 PASS — 2 (제거) + 6 (신규) = 77? 아니면 73 그대로 — count 확인.
+
+### Step 5: Commit + push
+
+```bash
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend add music-lab/app/pipeline/video.py \
+                                                       music-lab/tests/test_video_thumb.py
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend commit -m "feat(music-lab): 영상 인코딩을 Windows GPU 서버로 오프로드
+
+- pipeline/video.py 재작성: subprocess.run 제거, httpx로 192.168.45.59:8765/encode_video 호출
+- Windows 서버 다운 시 즉시 VideoGenerationError (NAS 로컬 폴백 X)
+- /app/data/* → /volume1/docker/webpage/data/* 경로 변환 (_container_to_nas)
+- 테스트는 respx mock 기반으로 교체 (6개 신규)"
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend push origin main
+```
+
+---
+
+## Task 4: docker-compose.yml env 추가
+
+**Files:**
+- Modify: `web-backend/docker-compose.yml`
+
+### Step 1: music-lab 서비스 environment에 추가
+
+```yaml
+  music-lab:
+    environment:
+      # ... existing ...
+      - WINDOWS_VIDEO_ENCODER_URL=${WINDOWS_VIDEO_ENCODER_URL}
+      - NAS_VIDEOS_ROOT=${NAS_VIDEOS_ROOT:-/volume1/docker/webpage/data/videos}
+      - NAS_MUSIC_ROOT=${NAS_MUSIC_ROOT:-/volume1/docker/webpage/data/music}
+```
+
+### Step 2: docker-compose syntax 검증
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend && python -c "import yaml; yaml.safe_load(open('docker-compose.yml'))" && echo OK
+```
+
+### Step 3: Commit + push
+
+```bash
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend add docker-compose.yml
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend commit -m "chore(infra): GPU 인코더 env 추가 (WINDOWS_VIDEO_ENCODER_URL)"
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend push origin main
+```
+
+---
+
+## Task 5: 사용자 매뉴얼 단계 (사람이 직접)
+
+후속 단계, 코드 작업 아님:
+
+1. **Windows PC: ffmpeg 설치 + PATH 설정**
+   - https://www.gyan.dev/ffmpeg/builds/ → "release full" 다운로드
+   - `C:\ffmpeg\` 압축 해제 → `C:\ffmpeg\bin\ffmpeg.exe` 확인
+   - 시스템 PATH에 `C:\ffmpeg\bin` 추가
+   - 검증: `ffmpeg -version` + `ffmpeg -encoders | findstr h264_nvenc`
+
+2. **Windows PC: `music_ai/.env` 추가**
+   ```env
+   NAS_VOLUME_PREFIX=/volume1/
+   WINDOWS_DRIVE_ROOT=Z:\
+   FFMPEG_PATH=C:\ffmpeg\bin\ffmpeg.exe
+   ```
+
+3. **Windows PC: SMB 마운트 확인** — `Z:\docker\webpage\data\` 접근 가능
+
+4. **Windows PC: `music_ai` 서버 재시작** — `start.bat`
+
+5. **Windows PC 헬스 체크** — `curl http://localhost:8765/health` → `ffmpeg_nvenc: true` 확인
+
+6. **NAS `.env`에 추가**
+   ```env
+   WINDOWS_VIDEO_ENCODER_URL=http://192.168.45.59:8765
+   ```
+
+7. **NAS music-lab 재시작** — `docker compose up -d music-lab`
+
+8. **E2E 테스트** — 진행 탭에서 새 파이프라인 시작, 영상 단계가 10–20초에 완료되는지 확인
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- §4 Windows endpoint → Task 1, 2 ✓
+- §5 NAS video.py → Task 3 ✓
+- §6 에러 처리 → Task 3 (httpx 예외 catch) ✓
+- §7 헬스 모니터링 → Task 2 (`/health` 확장) ✓
+- §8 테스트 → Task 1, 3 ✓
+- §9 Windows 사전 준비 → Task 5 (사용자 수동) ✓
+- §10 산출물 → 4 task로 모두 커버
+
+**Placeholder scan:** 없음.
+
+**Type consistency:**
+- `EncodeError(stage, message)` Task 1 정의, Task 2에서 `e.stage`/`e.message` 사용 ✓
+- `VideoGenerationError` Task 3에서 raise, 기존 orchestrator에서 catch ✓
+- 응답 JSON 형식 spec §4-2와 일치 ✓
+- 환경변수 이름 일관 (`NAS_VOLUME_PREFIX`, `WINDOWS_DRIVE_ROOT`, `FFMPEG_PATH`, `WINDOWS_VIDEO_ENCODER_URL`, `NAS_VIDEOS_ROOT`, `NAS_MUSIC_ROOT`)
+
+---

docs/superpowers/plans/2026-05-10-batch-music-generation.md

@@ -0,0 +1,815 @@
+# Batch Music Generation — Implementation Plan
+
+> **For agentic workers:** Use `superpowers:subagent-driven-development`. Steps use `- [ ]` checkboxes.
+
+**Goal:** 장르 1개로 N(1-10) 트랙 Suno 자동 순차 생성 + 자동 컴파일 + 영상 파이프라인 자동 시작.
+
+**Architecture:** music-lab 신규 `batch_generator` 모듈이 BackgroundTask로 N회 Suno 호출 → compile_job 자동 생성 → orchestrator.run_step("cover") 자동 호출.
+
+**Spec:** `docs/superpowers/specs/2026-05-10-batch-music-generation-design.md`
+
+---
+
+## File Structure
+
+| 경로 | 책임 |
+|------|------|
+| `music-lab/app/db.py` (modify) | `music_batch_jobs` 테이블 + 5 헬퍼 |
+| `music-lab/app/random_pools.py` (new) | 장르별 mood/instr/BPM/key/scale 랜덤 풀 + `randomize()` |
+| `music-lab/app/batch_generator.py` (new) | `run_batch(batch_id)` 순차 오케스트레이션 |
+| `music-lab/app/main.py` (modify) | 3개 endpoint (POST /generate-batch, GET /:id, GET 목록) |
+| `web-ui/src/api.js` (modify) | 3개 헬퍼 |
+| `web-ui/src/pages/music/components/BatchProgress.jsx` (new) | 진행 표시 컴포넌트 |
+| `web-ui/src/pages/music/MusicStudio.jsx` (modify) | Create 탭에 배치 섹션 + 폴링 |
+| `web-ui/src/pages/music/MusicStudio.css` (modify) | 배치 섹션 스타일 |
+
+---
+
+## Task 1: DB 테이블 + 헬퍼 + random_pools
+
+**Files:**
+- Modify: `music-lab/app/db.py`
+- Create: `music-lab/app/random_pools.py`
+- Test: `music-lab/tests/test_batch_db.py`
+
+- [ ] **Step 1: random_pools.py 작성**
+
+```python
+"""장르별 음악 파라미터 랜덤 풀."""
+import random
+
+POOLS = {
+    "lo-fi": {
+        "moods": ["chill", "relaxing", "dreamy", "melancholic", "mellow", "nostalgic", "peaceful"],
+        "instruments_pool": ["piano", "synth", "drums", "vinyl", "rhodes", "soft bass", "ambient pads"],
+        "instruments_count": (3, 4),
+        "bpm": (70, 90),
+        "keys": ["C", "D", "F", "G", "A"],
+        "scales": ["minor", "major"],
+        "prompt_modifiers": ["cozy bedroom vibes", "rainy night", "late night study", "cafe ambience"],
+    },
+    "phonk": {
+        "moods": ["dark", "aggressive", "moody", "intense", "hypnotic"],
+        "instruments_pool": ["808 bass", "hi-hat", "synth lead", "vocal chops", "bass drops", "trap drums"],
+        "instruments_count": (3, 4),
+        "bpm": (130, 160),
+        "keys": ["C", "D", "F", "G"],
+        "scales": ["minor"],
+        "prompt_modifiers": ["drift atmosphere", "dark neon", "midnight drive"],
+    },
+    "ambient": {
+        "moods": ["peaceful", "meditative", "ethereal", "spacious", "dreamy"],
+        "instruments_pool": ["pad synths", "atmospheric guitar", "soft strings", "field recordings", "drone bass"],
+        "instruments_count": (2, 3),
+        "bpm": (50, 75),
+        "keys": ["C", "D", "E", "G", "A"],
+        "scales": ["major", "minor"],
+        "prompt_modifiers": ["misty mountain morning", "deep space", "still water", "forest dawn"],
+    },
+    "pop": {
+        "moods": ["uplifting", "happy", "energetic", "romantic", "catchy"],
+        "instruments_pool": ["acoustic guitar", "piano", "drums", "bass", "synth", "vocals harmonies"],
+        "instruments_count": (3, 5),
+        "bpm": (95, 130),
+        "keys": ["C", "D", "E", "F", "G", "A"],
+        "scales": ["major"],
+        "prompt_modifiers": ["radio-ready", "summer vibe", "feel-good"],
+    },
+    "default": {
+        "moods": ["chill", "relaxing", "uplifting", "mellow"],
+        "instruments_pool": ["piano", "synth", "drums", "guitar", "bass", "strings"],
+        "instruments_count": (3, 4),
+        "bpm": (80, 110),
+        "keys": ["C", "D", "F", "G", "A"],
+        "scales": ["minor", "major"],
+        "prompt_modifiers": [""],
+    },
+}
+
+
+def randomize(genre: str, rng=None) -> dict:
+    rng = rng or random.Random()
+    pool = POOLS.get(genre.lower(), POOLS["default"])
+    n_instr = rng.randint(*pool["instruments_count"])
+    instruments = rng.sample(pool["instruments_pool"], min(n_instr, len(pool["instruments_pool"])))
+    return {
+        "moods": [rng.choice(pool["moods"])],
+        "instruments": instruments,
+        "bpm": rng.randint(*pool["bpm"]),
+        "key": rng.choice(pool["keys"]),
+        "scale": rng.choice(pool["scales"]),
+        "prompt_modifier": rng.choice(pool["prompt_modifiers"]),
+    }
+```
+
+- [ ] **Step 2: DB 테이블 + 헬퍼 추가** (db.py)
+
+`init_db()`에 추가:
+```python
+cursor.execute("""
+    CREATE TABLE IF NOT EXISTS music_batch_jobs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        genre TEXT NOT NULL,
+        count INTEGER NOT NULL,
+        target_duration_sec INTEGER NOT NULL DEFAULT 180,
+        auto_pipeline INTEGER NOT NULL DEFAULT 1,
+        completed INTEGER NOT NULL DEFAULT 0,
+        track_ids_json TEXT NOT NULL DEFAULT '[]',
+        current_track_index INTEGER NOT NULL DEFAULT 0,
+        current_track_status TEXT,
+        status TEXT NOT NULL DEFAULT 'queued',
+        error TEXT,
+        compile_job_id INTEGER,
+        pipeline_id INTEGER,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+    )
+""")
+```
+
+`db.py` 끝에 헬퍼:
+```python
+_BATCH_ALLOWED_COLS = frozenset([
+    "completed", "track_ids_json", "current_track_index",
+    "current_track_status", "status", "error",
+    "compile_job_id", "pipeline_id",
+])
+
+
+def create_batch_job(genre: str, count: int, target_duration_sec: int = 180,
+                     auto_pipeline: bool = True) -> int:
+    with _conn() as conn:
+        now = _now()
+        cur = conn.cursor()
+        cur.execute("""
+            INSERT INTO music_batch_jobs
+              (genre, count, target_duration_sec, auto_pipeline,
+               status, created_at, updated_at)
+            VALUES (?, ?, ?, ?, 'queued', ?, ?)
+        """, (genre, count, target_duration_sec, 1 if auto_pipeline else 0, now, now))
+        return cur.lastrowid
+
+
+def get_batch_job(batch_id: int) -> dict | None:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM music_batch_jobs WHERE id = ?", (batch_id,)
+        ).fetchone()
+    if not row:
+        return None
+    d = dict(row)
+    d["track_ids"] = json.loads(d.get("track_ids_json") or "[]")
+    return d
+
+
+def update_batch_job(batch_id: int, **fields) -> None:
+    unknown = set(fields) - _BATCH_ALLOWED_COLS
+    if unknown:
+        raise ValueError(f"unknown batch job columns: {unknown}")
+    cols = ", ".join(f"{k} = ?" for k in fields)
+    vals = list(fields.values()) + [_now(), batch_id]
+    with _conn() as conn:
+        conn.execute(
+            f"UPDATE music_batch_jobs SET {cols}, updated_at = ? WHERE id = ?",
+            vals,
+        )
+
+
+def append_batch_track(batch_id: int, track_id: int) -> None:
+    """track_ids_json에 새 track_id 추가 + completed += 1 (atomic)."""
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT track_ids_json, completed FROM music_batch_jobs WHERE id = ?",
+            (batch_id,),
+        ).fetchone()
+        if not row:
+            return
+        ids = json.loads(row["track_ids_json"] or "[]")
+        ids.append(track_id)
+        conn.execute(
+            "UPDATE music_batch_jobs SET track_ids_json = ?, completed = ?, updated_at = ? WHERE id = ?",
+            (json.dumps(ids), row["completed"] + 1, _now(), batch_id),
+        )
+
+
+def list_batch_jobs(active_only: bool = False) -> list[dict]:
+    sql = "SELECT * FROM music_batch_jobs"
+    if active_only:
+        sql += " WHERE status NOT IN ('failed','cancelled','piped')"
+    sql += " ORDER BY created_at DESC"
+    with _conn() as conn:
+        rows = conn.execute(sql).fetchall()
+    out = []
+    for r in rows:
+        d = dict(r)
+        d["track_ids"] = json.loads(d.get("track_ids_json") or "[]")
+        out.append(d)
+    return out
+```
+
+- [ ] **Step 3: Test 작성**
+
+```python
+# tests/test_batch_db.py
+import pytest
+from app import db
+
+
+@pytest.fixture
+def fresh_db(monkeypatch, tmp_path):
+    monkeypatch.setattr(db, "DB_PATH", str(tmp_path / "music.db"))
+    db.init_db()
+    return db
+
+
+def test_create_batch_job(fresh_db):
+    bid = db.create_batch_job(genre="lo-fi", count=10)
+    j = db.get_batch_job(bid)
+    assert j["genre"] == "lo-fi"
+    assert j["count"] == 10
+    assert j["status"] == "queued"
+    assert j["track_ids"] == []
+    assert j["auto_pipeline"] == 1
+
+
+def test_update_batch_job(fresh_db):
+    bid = db.create_batch_job(genre="phonk", count=5)
+    db.update_batch_job(bid, status="generating", current_track_index=2)
+    j = db.get_batch_job(bid)
+    assert j["status"] == "generating"
+    assert j["current_track_index"] == 2
+
+
+def test_update_batch_rejects_unknown_col(fresh_db):
+    bid = db.create_batch_job(genre="lo-fi", count=1)
+    with pytest.raises(ValueError):
+        db.update_batch_job(bid, evil_col="x")
+
+
+def test_append_batch_track(fresh_db):
+    bid = db.create_batch_job(genre="lo-fi", count=3)
+    db.append_batch_track(bid, 101)
+    db.append_batch_track(bid, 102)
+    j = db.get_batch_job(bid)
+    assert j["track_ids"] == [101, 102]
+    assert j["completed"] == 2
+
+
+def test_list_batch_jobs_active_filter(fresh_db):
+    b1 = db.create_batch_job(genre="lo-fi", count=1)
+    b2 = db.create_batch_job(genre="phonk", count=1)
+    db.update_batch_job(b1, status="failed")
+    actives = db.list_batch_jobs(active_only=True)
+    assert all(j["status"] not in ("failed",) for j in actives)
+    assert any(j["id"] == b2 for j in actives)
+    assert not any(j["id"] == b1 for j in actives)
+
+
+def test_random_pools_randomize():
+    from app.random_pools import randomize, POOLS
+    import random
+    rng = random.Random(42)
+    result = randomize("lo-fi", rng)
+    assert result["bpm"] in range(70, 91)
+    assert result["key"] in POOLS["lo-fi"]["keys"]
+    assert result["scale"] in POOLS["lo-fi"]["scales"]
+    assert len(result["moods"]) == 1
+    assert result["moods"][0] in POOLS["lo-fi"]["moods"]
+    assert 3 <= len(result["instruments"]) <= 4
+
+
+def test_random_pools_unknown_genre_uses_default():
+    from app.random_pools import randomize, POOLS
+    import random
+    result = randomize("nonexistent", random.Random(0))
+    assert result["bpm"] in range(80, 111)  # default range
+```
+
+- [ ] **Step 4: Run + commit**
+
+```bash
+cd music-lab && python -m pytest tests/test_batch_db.py -v
+```
+Expected: 7 PASS.
+
+```bash
+git add music-lab/app/db.py music-lab/app/random_pools.py music-lab/tests/test_batch_db.py
+git commit -m "feat(music-lab): music_batch_jobs 테이블 + 장르별 랜덤 풀"
+```
+
+---
+
+## Task 2: batch_generator + 3 엔드포인트
+
+**Files:**
+- Create: `music-lab/app/batch_generator.py`
+- Modify: `music-lab/app/main.py`
+- Test: `music-lab/tests/test_batch_endpoints.py`
+
+- [ ] **Step 1: batch_generator.py 작성**
+
+```python
+"""배치 음악 생성 + 자동 컴파일·영상 파이프라인."""
+import asyncio
+import logging
+
+from . import db
+from .random_pools import randomize
+
+logger = logging.getLogger("music-lab.batch")
+
+POLL_INTERVAL_S = 5
+TRACK_GEN_TIMEOUT_S = 240
+
+
+async def run_batch(batch_id: int) -> None:
+    job = db.get_batch_job(batch_id)
+    if not job:
+        return
+    genre = job["genre"]
+    count = job["count"]
+    duration = job["target_duration_sec"]
+    auto_pipe = bool(job["auto_pipeline"])
+
+    db.update_batch_job(batch_id, status="generating")
+
+    track_ids: list[int] = []
+    for i in range(1, count + 1):
+        title = f"{genre.title()} Mix Track {i}"
+        params = randomize(genre)
+        db.update_batch_job(batch_id,
+                            current_track_index=i,
+                            current_track_status="generating")
+
+        track_id = await _generate_one_track(title=title, genre=genre,
+                                              duration_sec=duration,
+                                              params=params)
+        if track_id:
+            track_ids.append(track_id)
+            db.append_batch_track(batch_id, track_id)
+            db.update_batch_job(batch_id, current_track_status="succeeded")
+        else:
+            db.update_batch_job(batch_id, current_track_status="failed")
+            logger.warning("배치 %d 트랙 %d 실패 — 계속 진행", batch_id, i)
+
+    if not track_ids:
+        db.update_batch_job(batch_id, status="failed",
+                            error="모든 트랙 생성 실패")
+        return
+
+    db.update_batch_job(batch_id, status="generated")
+
+    if not auto_pipe:
+        return
+
+    # 자동 컴파일
+    db.update_batch_job(batch_id, status="compiling")
+    try:
+        compile_id = db.create_compile_job(
+            title=f"{genre.title()} Mix",
+            track_ids=track_ids,
+            crossfade_sec=3,
+        )
+        db.update_batch_job(batch_id, compile_job_id=compile_id)
+    except Exception as e:
+        db.update_batch_job(batch_id, status="failed", error=f"compile create: {e}")
+        return
+
+    from . import compiler
+    try:
+        await asyncio.to_thread(compiler.run, compile_id)
+    except Exception as e:
+        db.update_batch_job(batch_id, status="failed", error=f"compile run: {e}")
+        return
+
+    job_after = db.get_compile_job(compile_id)
+    if not job_after or job_after.get("status") not in ("done", "succeeded"):
+        db.update_batch_job(
+            batch_id, status="failed",
+            error=f"compile not done (status={job_after.get('status') if job_after else 'unknown'})"
+        )
+        return
+
+    # 자동 영상 파이프라인
+    pipeline_id = db.create_pipeline(compile_job_id=compile_id)
+    db.update_batch_job(batch_id, pipeline_id=pipeline_id, status="piped")
+
+    from .pipeline import orchestrator
+    await orchestrator.run_step(pipeline_id, "cover")
+
+
+async def _generate_one_track(*, title: str, genre: str, duration_sec: int,
+                                params: dict) -> int | None:
+    """기존 Suno generate 호출 + 완료까지 polling. 성공 시 새 track id 반환."""
+    from .suno_provider import run_suno_generation
+    from .db import create_task, get_task
+    import uuid
+
+    task_id = str(uuid.uuid4())
+    suno_params = {
+        "title": title,
+        "genre": genre,
+        "moods": params["moods"],
+        "instruments": params["instruments"],
+        "duration_sec": duration_sec,
+        "bpm": params["bpm"],
+        "key": params["key"],
+        "scale": params["scale"],
+        "prompt": params.get("prompt_modifier", ""),
+    }
+    create_task(task_id, suno_params, provider="suno")
+
+    # Suno background task 직접 호출 (BackgroundTasks 미사용 — 우리가 await)
+    asyncio.create_task(asyncio.to_thread(run_suno_generation, task_id, suno_params))
+
+    # Polling
+    waited = 0
+    while waited < TRACK_GEN_TIMEOUT_S:
+        await asyncio.sleep(POLL_INTERVAL_S)
+        waited += POLL_INTERVAL_S
+        task = get_task(task_id)
+        if not task:
+            continue
+        if task.get("status") == "succeeded":
+            tr = task.get("track")
+            return tr.get("id") if tr else None
+        if task.get("status") == "failed":
+            return None
+    return None  # timeout
+```
+
+NOTE: This assumes existing `db.create_task`, `db.get_task`, `suno_provider.run_suno_generation` are reusable. Read existing code to confirm function signatures, adjust if needed (especially `task["track"]["id"]` vs other format).
+
+- [ ] **Step 2: main.py에 3 endpoint 추가**
+
+```python
+from app.batch_generator import run_batch as _run_batch
+
+
+class BatchGenerateRequest(BaseModel):
+    genre: str
+    count: int = 10
+    target_duration_sec: int = 180
+    auto_pipeline: bool = True
+
+
+@app.post("/api/music/generate-batch", status_code=201)
+async def generate_batch(req: BatchGenerateRequest, bg: BackgroundTasks):
+    if not (1 <= req.count <= 10):
+        raise HTTPException(400, "count는 1-10 사이")
+    if not (60 <= req.target_duration_sec <= 300):
+        raise HTTPException(400, "target_duration_sec는 60-300 사이")
+    if not req.genre:
+        raise HTTPException(400, "genre 필수")
+    if not SUNO_API_KEY:
+        raise HTTPException(400, "SUNO_API_KEY 미설정")
+
+    batch_id = _db_module.create_batch_job(
+        genre=req.genre, count=req.count,
+        target_duration_sec=req.target_duration_sec,
+        auto_pipeline=req.auto_pipeline,
+    )
+    bg.add_task(_run_batch, batch_id)
+    return _db_module.get_batch_job(batch_id)
+
+
+@app.get("/api/music/generate-batch/{batch_id}")
+def get_batch(batch_id: int):
+    j = _db_module.get_batch_job(batch_id)
+    if not j:
+        raise HTTPException(404)
+    # tracks 메타 LEFT JOIN (id, title, audio_url)
+    if j["track_ids"]:
+        ids_csv = ",".join(str(i) for i in j["track_ids"])
+        # 간단한 in-Python 매핑 (sqlite IN (...))
+        import sqlite3
+        conn = sqlite3.connect(_db_module.DB_PATH)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            f"SELECT id, title, audio_url, duration_sec FROM music_library WHERE id IN ({ids_csv})"
+        ).fetchall()
+        conn.close()
+        j["tracks"] = [dict(r) for r in rows]
+    else:
+        j["tracks"] = []
+    return j
+
+
+@app.get("/api/music/generate-batch")
+def list_batches(status: str = "all"):
+    return {"batches": _db_module.list_batch_jobs(active_only=(status == "active"))}
+```
+
+(SUNO_API_KEY는 main.py에 이미 import돼있다고 가정. 없으면 `_db_module` 패턴처럼 처리.)
+
+- [ ] **Step 3: 테스트 작성**
+
+```python
+# tests/test_batch_endpoints.py
+import pytest
+from unittest.mock import AsyncMock, patch, MagicMock
+from fastapi.testclient import TestClient
+from app.main import app
+from app import db
+
+
+@pytest.fixture
+def client(monkeypatch, tmp_path):
+    monkeypatch.setattr(db, "DB_PATH", str(tmp_path / "music.db"))
+    db.init_db()
+    monkeypatch.setenv("SUNO_API_KEY", "test")
+    return TestClient(app)
+
+
+def test_create_batch_201(client):
+    with patch("app.main._run_batch", new=AsyncMock()):
+        r = client.post("/api/music/generate-batch",
+                         json={"genre": "lo-fi", "count": 3})
+    assert r.status_code == 201
+    body = r.json()
+    assert body["genre"] == "lo-fi"
+    assert body["count"] == 3
+    assert body["status"] == "queued"
+
+
+def test_create_batch_rejects_count_too_high(client):
+    r = client.post("/api/music/generate-batch",
+                     json={"genre": "lo-fi", "count": 11})
+    assert r.status_code == 400
+
+
+def test_create_batch_rejects_count_zero(client):
+    r = client.post("/api/music/generate-batch",
+                     json={"genre": "lo-fi", "count": 0})
+    assert r.status_code == 400
+
+
+def test_create_batch_rejects_no_genre(client):
+    r = client.post("/api/music/generate-batch", json={"count": 3})
+    # Pydantic missing 필드 → 422 (FastAPI default validation)
+    assert r.status_code in (400, 422)
+
+
+def test_get_batch_returns_tracks(client):
+    bid = db.create_batch_job(genre="lo-fi", count=2)
+    db.append_batch_track(bid, 999)  # phantom track id (not in library)
+    r = client.get(f"/api/music/generate-batch/{bid}")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["track_ids"] == [999]
+    # tracks 배열은 비어있음 (해당 track 미존재)
+    assert body["tracks"] == []
+
+
+def test_list_batches(client):
+    db.create_batch_job(genre="lo-fi", count=1)
+    db.create_batch_job(genre="phonk", count=2)
+    r = client.get("/api/music/generate-batch")
+    assert len(r.json()["batches"]) == 2
+```
+
+- [ ] **Step 4: Run + commit + push**
+
+```bash
+cd music-lab && python -m pytest tests/ -v
+```
+Expected: 모두 PASS.
+
+```bash
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend add music-lab/app/batch_generator.py \
+                                                       music-lab/app/main.py \
+                                                       music-lab/tests/test_batch_endpoints.py
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend commit -m "feat(music-lab): 배치 음악 생성 endpoint + orchestrator"
+git -C C:/Users/jaeoh/Desktop/workspace/web-backend push origin main
+```
+
+---
+
+## Task 3: Frontend Create 탭 배치 섹션
+
+**Files:**
+- Modify: `web-ui/src/api.js`
+- Create: `web-ui/src/pages/music/components/BatchProgress.jsx`
+- Modify: `web-ui/src/pages/music/MusicStudio.jsx`
+- Modify: `web-ui/src/pages/music/MusicStudio.css`
+
+- [ ] **Step 1: api.js 헬퍼**
+
+```javascript
+// === Batch generation ===
+export const startBatchGen   = (payload)        => apiPost('/api/music/generate-batch', payload);
+export const getBatchJob     = (id)             => apiGet(`/api/music/generate-batch/${id}`);
+export const listBatchJobs   = (status='all')   => apiGet(`/api/music/generate-batch?status=${status}`);
+```
+
+- [ ] **Step 2: BatchProgress.jsx 신규**
+
+```jsx
+const STATUS_LABELS = {
+    queued: '대기 중', generating: '음악 생성 중', generated: '음악 완료, 컴파일 대기',
+    compiling: '컴파일 중', piped: '영상 파이프라인 시작됨',
+    failed: '실패', cancelled: '취소',
+};
+
+export default function BatchProgress({ batch }) {
+    if (!batch) return null;
+    const trackList = Array.from({ length: batch.count }, (_, i) => i + 1);
+    return (
+        <div className="ms-batch-progress">
+            <div className="ms-batch-header">
+                배치 #{batch.id} — {batch.genre} ·{' '}
+                {batch.completed}/{batch.count} 완료 ·{' '}
+                <strong>{STATUS_LABELS[batch.status] || batch.status}</strong>
+            </div>
+            {batch.error && <div className="ms-error">에러: {batch.error}</div>}
+            <ol className="ms-batch-tracks">
+                {trackList.map(n => {
+                    const completed = n <= batch.completed;
+                    const current = n === batch.current_track_index && batch.status === 'generating';
+                    const tr = (batch.tracks || [])[n - 1];
+                    return (
+                        <li key={n} className={completed ? 'done' : current ? 'current' : 'pending'}>
+                            {completed ? '✓' : current ? '⏳' : '○'}
+                            {' '}Track {n}: {tr?.title || (current ? '생성 중...' : '대기')}
+                        </li>
+                    );
+                })}
+            </ol>
+            {batch.compile_job_id && (
+                <div className="ms-batch-link">📀 컴파일 #{batch.compile_job_id}</div>
+            )}
+            {batch.pipeline_id && (
+                <div className="ms-batch-link">
+                    🎬 영상 파이프라인 #{batch.pipeline_id} —
+                    {' '}<em>YouTube 탭 → 진행 탭에서 확인</em>
+                </div>
+            )}
+        </div>
+    );
+}
+```
+
+- [ ] **Step 3: MusicStudio.jsx Create 탭에 배치 섹션 추가**
+
+Create 탭 jsx 영역 (handleGenerate 근처) 위 또는 옆에:
+
+```jsx
+import BatchProgress from './components/BatchProgress';
+import { startBatchGen, getBatchJob } from '../../api';
+
+// 컴포넌트 내부 state:
+const [batchOpen, setBatchOpen] = useState(false);
+const [batchGenre, setBatchGenre] = useState('lo-fi');
+const [batchCount, setBatchCount] = useState(10);
+const [batchDuration, setBatchDuration] = useState(180);
+const [batchAutoPipe, setBatchAutoPipe] = useState(true);
+const [currentBatch, setCurrentBatch] = useState(null);
+const [batchPolling, setBatchPolling] = useState(false);
+const batchPollRef = useRef(null);
+
+const startBatch = async () => {
+    try {
+        const res = await startBatchGen({
+            genre: batchGenre,
+            count: batchCount,
+            target_duration_sec: batchDuration,
+            auto_pipeline: batchAutoPipe,
+        });
+        setCurrentBatch(res);
+        setBatchPolling(true);
+    } catch (e) {
+        alert(`배치 시작 실패: ${e.message || e}`);
+    }
+};
+
+useEffect(() => {
+    if (!batchPolling || !currentBatch?.id) return;
+    const tick = async () => {
+        const j = await getBatchJob(currentBatch.id).catch(() => null);
+        if (j) {
+            setCurrentBatch(j);
+            if (['piped', 'failed', 'cancelled'].includes(j.status)) {
+                setBatchPolling(false);
+                if (j.pipeline_id) loadLibrary?.();  // refresh library to show new tracks
+            }
+        }
+    };
+    batchPollRef.current = setInterval(tick, 5000);
+    return () => clearInterval(batchPollRef.current);
+}, [batchPolling, currentBatch?.id]);
+
+// ... Create 탭 jsx 안:
+<details className="ms-batch-section" open={batchOpen} onToggle={(e) => setBatchOpen(e.target.open)}>
+    <summary>🎲 배치 생성 (장르 → 1-10트랙 + 자동 영상)</summary>
+    <div className="ms-batch-form">
+        <label>장르
+            <select value={batchGenre} onChange={e => setBatchGenre(e.target.value)}>
+                <option value="lo-fi">Lo-Fi</option>
+                <option value="phonk">Phonk</option>
+                <option value="ambient">Ambient</option>
+                <option value="pop">Pop</option>
+            </select>
+        </label>
+        <label>트랙 수: {batchCount}
+            <input type="range" min={1} max={10} value={batchCount}
+                onChange={e => setBatchCount(parseInt(e.target.value))} />
+        </label>
+        <label>트랙당 길이: {batchDuration}초
+            <input type="range" min={60} max={300} step={10} value={batchDuration}
+                onChange={e => setBatchDuration(parseInt(e.target.value))} />
+        </label>
+        <label className="ms-batch-checkbox">
+            <input type="checkbox" checked={batchAutoPipe}
+                onChange={e => setBatchAutoPipe(e.target.checked)} />
+            모든 트랙 생성 후 자동 영상 파이프라인 시작
+        </label>
+        <p className="ms-batch-estimate">
+            예상: 약 {Math.ceil(batchCount * 1.5)}-{batchCount * 2}분 ·
+            비용 ~${(batchCount * 0.005 + (batchAutoPipe ? 0.05 : 0)).toFixed(2)}
+        </p>
+        <button className="button primary" onClick={startBatch}
+            disabled={batchPolling}>
+            🎵 배치 생성 시작
+        </button>
+    </div>
+    {currentBatch && <BatchProgress batch={currentBatch} />}
+</details>
+```
+
+- [ ] **Step 4: CSS 추가**
+
+```css
+/* === Batch generation section === */
+.ms-batch-section { margin: 16px 0; padding: 12px; background: rgba(0,0,0,.2);
+    border: 1px solid var(--ms-line, #2a2a3a); border-radius: 12px; }
+.ms-batch-section summary { cursor: pointer; font-weight: bold; color: var(--ms-text, #f0f0f5); }
+.ms-batch-form { display: flex; flex-direction: column; gap: 10px; padding: 12px 0; }
+.ms-batch-form label { display: flex; flex-direction: column; gap: 4px; font-size: 13px; }
+.ms-batch-form input[type="range"] { width: 100%; }
+.ms-batch-checkbox { flex-direction: row !important; align-items: center; gap: 8px; }
+.ms-batch-checkbox input { width: auto; }
+.ms-batch-estimate { font-size: 12px; color: var(--ms-muted, #a0a0b0); }
+
+.ms-batch-progress { margin-top: 12px; padding: 12px; background: rgba(0,0,0,.3);
+    border-radius: 8px; }
+.ms-batch-header { font-size: 13px; margin-bottom: 8px; }
+.ms-batch-tracks { padding-left: 24px; font-size: 12px; }
+.ms-batch-tracks li { margin: 2px 0; }
+.ms-batch-tracks li.done { color: #86efac; }
+.ms-batch-tracks li.current { color: var(--ms-accent, #38bdf8); font-weight: bold; }
+.ms-batch-tracks li.pending { color: var(--ms-muted, #a0a0b0); }
+.ms-batch-link { margin-top: 8px; font-size: 12px; color: var(--ms-muted, #a0a0b0); }
+```
+
+- [ ] **Step 5: Build + verify + commit + push + deploy**
+
+```bash
+cd web-ui && npm run build 2>&1 | tail -5
+npx eslint src/pages/music/components/BatchProgress.jsx src/pages/music/MusicStudio.jsx 2>&1 | tail
+```
+
+```bash
+git -C C:/Users/jaeoh/Desktop/workspace/web-ui add src/api.js \
+        src/pages/music/components/BatchProgress.jsx \
+        src/pages/music/MusicStudio.jsx \
+        src/pages/music/MusicStudio.css
+git -C C:/Users/jaeoh/Desktop/workspace/web-ui commit -m "feat(web-ui): Create 탭 배치 생성 섹션 + BatchProgress"
+git -C C:/Users/jaeoh/Desktop/workspace/web-ui push origin main
+cd C:/Users/jaeoh/Desktop/workspace/web-ui && npm run release:nas
+```
+
+---
+
+## Task 4: 수동 E2E 검증
+
+- [ ] Create 탭 → 배치 생성 섹션 펼침 → genre=lo-fi, count=3 (테스트로 적게), duration=120s, auto_pipeline=on → "배치 생성 시작"
+- [ ] BatchProgress에 Track 1/2/3 진행 표시 확인
+- [ ] ~5분 후 Library에 3개 트랙 추가됨
+- [ ] 컴파일 진행 확인 (status: compiling)
+- [ ] 영상 파이프라인 시작됨 (status: piped) + pipeline_id 표시
+- [ ] YouTube 탭 → 진행 탭에 새 카드, cover 단계 진행 중
+- [ ] 텔레그램에 cover 알림 도착
+- [ ] 일반 흐름대로 5단계 승인 후 발행
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- §3 사용자 흐름 → Task 3 (UI 섹션)
+- §4 데이터 모델 → Task 1
+- §5 백엔드 (random_pools, batch_generator) → Task 1, 2
+- §6 API → Task 2
+- §7 프론트엔드 → Task 3
+- §8 에러 처리 → Task 2 (validation, try/except)
+- §9 테스트 → Task 1, 2
+- §10 산출물 → 4 task로 모두 커버
+
+**Placeholder scan:** 없음.
+
+**Type consistency:**
+- `batch_id` int, `count` int, `genre` str — 일관
+- `track_ids` list[int]
+- `status` 7값 (queued/generating/generated/compiling/piped/failed/cancelled) 일관
+
+**스펙 보정:** §5-2 batch_generator의 `_generate_one_track`에서 `db.create_task`/`db.get_task` 사용 — 이 함수들이 기존 db.py에 있는지 미확인. Task 2 Step 1 NOTE에 명시함.

docs/superpowers/specs/2026-05-05-packs-lab-infra-integration-design.md

@@ -0,0 +1,471 @@
+# packs-lab 인프라 통합 + admin mint-token 설계
+
+> 대상: `web-backend/packs-lab/`
+> 외부 의존: Supabase(`pack_files` 테이블) + Vercel SaaS(HMAC 호출자)
+> 후속 별도 스펙: Vercel-side admin UI / 사용자 다운로드 / cleanup cron / multi-admin
+
+---
+
+## 1. 목표
+
+`packs-lab`은 NAS 자료 다운로드 자동화 백엔드. Synology DSM 공유 링크 발급 + 5GB 멀티파트 업로드 수신을 담당하고, Vercel SaaS와 HMAC으로 통신한다. 사용자 인증은 Vercel이 Supabase로 처리하고 본 서비스는 외부 인증을 다루지 않는다.
+
+이미 코드(HMAC 미들웨어 / DSM client / 4 라우트)는 작성되어 있으나 인프라 통합 + Supabase 스키마 + admin upload 토큰 발급 흐름이 빠져 있어 운영 가능 상태가 아니다. 본 스펙은 그 갭을 메운다.
+
+### 핵심 변경
+
+- **신규 라우트**: `POST /api/packs/admin/mint-token` (Vercel HMAC → 일회성 업로드 토큰)
+- **Supabase DDL**: `pack_files` 테이블 + 활성·삭제 인덱스
+- **인프라**: docker-compose `packs-lab` 서비스 등록(18950) + nginx `/api/packs/` 5GB 통과 + `.env.example` 6+1 환경변수
+- **테스트**: routes 통합 + DSM client mock
+- **문서**: web-backend / workspace CLAUDE.md 5곳 갱신
+- **DELETE 라우트 docstring**: "DSM 공유 정리" 표현을 "DSM 공유 자동 만료"로 수정 (실제 동작과 일치)
+
+### 변경하지 않는 것
+
+- 기존 `auth.py` (`mint_upload_token` 그대로 활용)
+- 기존 `dsm_client.py`
+- 기존 `routes.py`의 sign-link / upload / list / delete 본문
+- DSM 공유 추적 테이블 — 4시간 자동 만료로 충분(브레인스토밍 결정)
+
+---
+
+## 2. 컴포넌트 + 통신 흐름
+
+### 2.1 변경 받는 파일
+
+| 영역 | 파일 | 변경 |
+|------|------|------|
+| 백엔드 | `packs-lab/app/routes.py` | DELETE docstring 수정 + admin mint-token 라우트 추가 |
+| 백엔드 | `packs-lab/app/models.py` | `MintTokenRequest`, `MintTokenResponse` 스키마 추가 |
+| 백엔드 | `packs-lab/app/auth.py` | 변경 없음 (기존 `mint_upload_token` 활용) |
+| 테스트 | `packs-lab/tests/conftest.py` (신규) | autouse `BACKEND_HMAC_SECRET` 셋팅 |
+| 테스트 | `packs-lab/tests/test_routes.py` (신규) | 5 라우트 통합 테스트 |
+| 테스트 | `packs-lab/tests/test_dsm_client.py` (신규) | DSM 7.x API mock 테스트 |
+| DB | `packs-lab/supabase/pack_files.sql` (신규) | DDL + 인덱스 |
+| 인프라 | `docker-compose.yml` | `packs-lab` 서비스 추가 |
+| 인프라 | `nginx/default.conf` | `/api/packs/` 라우팅 (`client_max_body_size 5G` + streaming) |
+| 인프라 | `.env.example` | 6+1 신규 환경변수 |
+| 문서 | `web-backend/CLAUDE.md` | 1·4·5·8·9 섹션 갱신 |
+| 문서 | `workspace/CLAUDE.md` | 컨테이너 표 한 줄 추가 |
+
+### 2.2 통신 흐름
+
+**ADMIN 업로드**
+
+```
+Vercel admin UI ─────→ Vercel API (HMAC 헤더 추가)
+                                    │
+                                    ▼
+                         POST /api/packs/admin/mint-token
+                                    │
+                  backend: verify_request_hmac
+                                    │
+                  mint_upload_token({tier, label, filename, size_bytes, jti, expires_at})
+                                    │
+Vercel ←─────────────── token ──────┘
+   │
+   ▼
+admin browser → POST /api/packs/upload
+                  Authorization: Bearer <token>
+                  multipart body (≤5GB)
+                                    │
+                  backend: verify_upload_token + JTI mark
+                                    │
+                  파일 저장 (PACK_BASE_DIR/{filename}, 평면 구조 — tier는 filename 규칙으로 구분)
+                                    │
+                  Supabase INSERT pack_files
+```
+
+**사용자 다운로드**
+
+```
+사용자 → Vercel SaaS (Supabase auth + tier·결제 검증)
+                              │
+                              ▼
+                 POST /api/packs/sign-link (HMAC + file_path)
+                              │
+                  backend: verify_request_hmac
+                              │
+                  DSM Sharing.create (4시간 만료)
+                              │
+사용자 ← Vercel ← 다운로드 URL (4시간 유효)
+```
+
+### 2.3 기각된 대안
+
+| 대안 | 기각 사유 |
+|------|-----------|
+| Vercel-side 토큰 발급 | 토큰 포맷 양쪽 분산, 변경 시 동기화 부담 |
+| admin browser → backend 직접 HMAC | admin browser에 secret 노출, 보안 약화 |
+| DSM 공유 추적 테이블 | 4시간 자동 만료로 충분, YAGNI |
+| Resumable multipart upload | 5GB는 단일 stream으로 충분, 복잡도 증가 |
+| `pack_files.min_tier`를 PostgreSQL ENUM | tier 추가 시 ALTER TYPE 번거로움. text+CHECK 채택 |
+
+---
+
+## 3. `POST /api/packs/admin/mint-token`
+
+### 3.1 Pydantic 스키마 (`models.py` 추가)
+
+```python
+class MintTokenRequest(BaseModel):
+    """Vercel → backend: admin upload 토큰 발급 요청."""
+    tier: PackTier
+    label: str = Field(..., max_length=200)
+    filename: str = Field(..., max_length=255)
+    size_bytes: int = Field(..., gt=0, le=5 * 1024 * 1024 * 1024)
+
+
+class MintTokenResponse(BaseModel):
+    token: str
+    expires_at: datetime
+    jti: str
+```
+
+### 3.2 라우트 본문 (`routes.py` 추가)
+
+```python
+import time, uuid
+from datetime import datetime, timezone
+
+from .auth import mint_upload_token, verify_request_hmac
+from .models import MintTokenRequest, MintTokenResponse
+
+UPLOAD_TOKEN_TTL_SEC = int(os.getenv("UPLOAD_TOKEN_TTL_SEC", "1800"))  # 30분 default
+
+@router.post("/admin/mint-token", response_model=MintTokenResponse)
+async def mint_token(
+    request: Request,
+    x_timestamp: str = Header(""),
+    x_signature: str = Header(""),
+):
+    body = await request.body()
+    verify_request_hmac(body, x_timestamp, x_signature)
+    payload = MintTokenRequest.model_validate_json(body)
+    _check_filename(payload.filename)  # upload 라우트와 동일 검증
+
+    jti = str(uuid.uuid4())
+    expires_ts = int(time.time()) + UPLOAD_TOKEN_TTL_SEC
+    token = mint_upload_token({
+        "tier": payload.tier,
+        "label": payload.label,
+        "filename": payload.filename,
+        "size_bytes": payload.size_bytes,
+        "jti": jti,
+        "expires_at": expires_ts,
+    })
+    return MintTokenResponse(
+        token=token,
+        expires_at=datetime.fromtimestamp(expires_ts, tz=timezone.utc),
+        jti=jti,
+    )
+```
+
+### 3.3 결정 근거
+
+| 항목 | 값 | 근거 |
+|------|-----|------|
+| TTL default | 1800s (30분) | 5GB 업로드 시작 + 진행 시간 여유. 1Gbps에서 약 40s, 50Mbps에서 약 14분 |
+| TTL env override | `UPLOAD_TOKEN_TTL_SEC` | 운영 중 조정 가능 |
+| filename 검증 | upload와 동일 (`_check_filename`) | 토큰 발급 시점에 미리 거부 → admin UI 즉시 피드백 |
+| jti 응답 포함 | yes | admin이 업로드 결과 추적용 |
+| Vercel ↔ backend | HMAC (`X-Timestamp` + `X-Signature`) | 다른 admin 라우트와 동일 패턴 |
+| admin browser ↔ backend | Bearer token (단발성 jti) | 기존 upload 라우트 그대로 |
+
+### 3.4 DELETE 라우트 docstring 수정
+
+`routes.py` 모듈 docstring에서:
+
+```diff
+- DELETE /api/packs/{file_id} — Vercel HMAC 인증 → soft delete + DSM 공유 정리
++ DELETE /api/packs/{file_id} — Vercel HMAC 인증 → soft delete (DSM 공유는 자동 만료)
+```
+
+`delete_file` 함수에는 변경 없음.
+
+---
+
+## 4. Supabase `pack_files` DDL
+
+**파일**: `packs-lab/supabase/pack_files.sql` (신규, 운영 배포 시 Supabase SQL editor에서 실행)
+
+```sql
+-- pack_files: NAS에 저장된 다운로드 가능한 패키지 파일 메타
+create table if not exists public.pack_files (
+    id              uuid        primary key default gen_random_uuid(),
+    min_tier        text        not null check (min_tier in ('starter','pro','master')),
+    label           text        not null,
+    file_path       text        not null unique,    -- NAS 절대경로, 동일 경로 중복 방지
+    filename        text        not null,
+    size_bytes      bigint      not null check (size_bytes > 0),
+    sort_order      integer     not null default 0,
+    uploaded_at     timestamptz not null default now(),
+    deleted_at      timestamptz
+);
+
+-- list 라우트의 hot path: deleted_at IS NULL + tier/order 정렬
+create index if not exists pack_files_active_idx
+    on public.pack_files (min_tier, sort_order)
+    where deleted_at is null;
+
+-- soft-deleted 통계 / cleanup 잡 대비
+create index if not exists pack_files_deleted_at_idx
+    on public.pack_files (deleted_at)
+    where deleted_at is not null;
+```
+
+### 4.1 필드 결정 근거
+
+| 필드 | 타입 / 제약 | 근거 |
+|------|------------|------|
+| `id` | uuid PK + `gen_random_uuid()` default | routes.py가 client-side `uuid.uuid4()` 생성하지만 default도 둬 fallback |
+| `min_tier` | text + CHECK | enum 대신 text+CHECK가 PostgreSQL에서 더 유연 |
+| `file_path` | text NOT NULL UNIQUE | 같은 tier/filename 충돌은 파일시스템에서 잡지만 DB 레벨도 보강 |
+| `size_bytes` | bigint + CHECK > 0 | 5GB는 int 범위 안이지만 미래 대비 bigint |
+| `sort_order` | int NOT NULL default 0 | routes INSERT가 sort_order 미지정 → 0 기본 |
+| `uploaded_at` | timestamptz default now() | routes 코드가 `res.data[0]["uploaded_at"]` 그대로 응답에 사용 — DB가 채워줌 |
+| `deleted_at` | nullable | soft delete |
+
+### 4.2 RLS
+
+비활성. backend가 `service_role` key 사용하므로 RLS 우회. Vercel/사용자 직접 접근 없음 → unsafe 아님.
+
+---
+
+## 5. 인프라 통합
+
+### 5.1 `docker-compose.yml` — `packs-lab` 서비스
+
+```yaml
+  packs-lab:
+    build:
+      context: ./packs-lab
+      dockerfile: Dockerfile
+    container_name: packs-lab
+    restart: unless-stopped
+    ports:
+      - "18950:8000"
+    environment:
+      TZ: Asia/Seoul
+      DSM_HOST: ${DSM_HOST}
+      DSM_USER: ${DSM_USER}
+      DSM_PASS: ${DSM_PASS}
+      BACKEND_HMAC_SECRET: ${BACKEND_HMAC_SECRET}
+      SUPABASE_URL: ${SUPABASE_URL}
+      SUPABASE_SERVICE_KEY: ${SUPABASE_SERVICE_KEY}
+      UPLOAD_TOKEN_TTL_SEC: ${UPLOAD_TOKEN_TTL_SEC:-1800}
+      PACK_BASE_DIR: ${PACK_BASE_DIR:-/app/data/packs}
+      PACK_HOST_DIR: ${PACK_HOST_DIR:-${PACK_DATA_PATH:-./data/packs}}
+    volumes:
+      - ${PACK_DATA_PATH:-./data/packs}:${PACK_BASE_DIR:-/app/data/packs}
+```
+
+| 결정 | 값 | 근거 |
+|------|-----|------|
+| 포트 | 18950 | 18800(realestate) → 18900(agent-office) → 18950(packs) 순차 |
+| `PACK_BASE_DIR` (컨테이너 내부) | `/app/data/packs` | routes.py upload target. docker-compose volume 우측. |
+| `PACK_HOST_DIR` (NAS 호스트) | 운영 `/volume1/docker/webpage/media/packs` / 로컬 fallback `./data/packs` | DSM·Supabase에 노출되는 절대경로. routes.py가 file_path로 저장. 미설정 시 `PACK_BASE_DIR`로 fallback. |
+| `PACK_DATA_PATH` (호스트 마운트) | default `./data/packs` (로컬), NAS `/volume1/docker/webpage/media/packs` | docker-compose volume 좌측만 사용 |
+
+### 5.2 `nginx/default.conf` — `/api/packs/` 라우팅
+
+```nginx
+location /api/packs/ {
+    proxy_pass http://packs-lab:8000;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # 5GB 멀티파트 업로드 대응
+    client_max_body_size 5G;
+    proxy_request_buffering off;     # 스트리밍 통과 (메모리/디스크 buffer 회피)
+    proxy_read_timeout 1800s;
+    proxy_send_timeout 1800s;
+}
+```
+
+| 결정 | 근거 |
+|------|------|
+| `client_max_body_size 5G` | 라우트 단위 — 다른 location은 default 유지 |
+| `proxy_request_buffering off` | 5GB 파일을 nginx가 모두 받고 backend에 forward하면 ~5GB 디스크 buffer 발생 |
+| `proxy_read/send_timeout 1800s` | 30분 — 업로드 토큰 TTL과 일치, 느린 업링크에서 5GB 전송 여유 |
+
+### 5.3 `.env.example` — 신규 환경변수 (7 + 3 path)
+
+```bash
+# ─── packs-lab — NAS 자료 다운로드 자동화 ────────────────────────────
+# Synology DSM 7.x 인증 (공유 링크 발급용)
+DSM_HOST=https://gahusb.synology.me:5001
+DSM_USER=
+DSM_PASS=
+# LAN IP + self-signed cert 환경에서 IP mismatch 시 false (LAN 내부 통신이라 허용)
+DSM_VERIFY_SSL=false
+
+# Vercel SaaS ↔ backend HMAC 시크릿 (양쪽 동일 값)
+BACKEND_HMAC_SECRET=
+
+# Supabase pack_files 테이블 접근 (service_role 키, RLS 우회)
+SUPABASE_URL=https://<project>.supabase.co
+SUPABASE_SERVICE_KEY=
+
+# admin upload 토큰 TTL (초). default 1800 = 30분
+UPLOAD_TOKEN_TTL_SEC=1800
+
+# 호스트 마운트 경로 (로컬 ./data/packs, NAS /volume1/docker/webpage/media/packs)
+PACK_DATA_PATH=./data/packs
+
+# 컨테이너 내부 저장 경로 (routes.py upload target. docker-compose volume 우측)
+PACK_BASE_DIR=/app/data/packs
+
+# DSM API용 path. Synology DSM API는 일반 사용자 권한일 때 /<shared_folder>/... 형식만 인식하고 /volume1/... 절대경로는 거부(error 408).
+# 운영 NAS는 반드시 shared folder 시점 — /docker/webpage/media/packs.
+# admin 사용자는 /volume1/... 도 가능하지만 보안상 별도 packs-bot user 권장.
+PACK_HOST_DIR=/docker/webpage/media/packs
+```
+
+### 5.4 NAS 디렉토리 준비
+
+운영 첫 배포 시 SSH로 1회. 파일은 `PACK_HOST_DIR` 평면에 직접 저장 — tier 디렉토리 분기는 만들지 않음(tier 구분은 filename 규칙으로 admin이 관리):
+
+```bash
+mkdir -p /volume1/docker/webpage/media/packs    # 호스트 OS path (volume 마운트용)
+chown -R PUID:PGID /volume1/docker/webpage/media/packs
+```
+
+PUID/PGID는 `.env`의 기존 값 사용.
+
+> ⚠️ **DSM 사용자 권한 — File Station + Sharing 둘 다 필요**: Control Panel → User → packs-bot(또는 admin) → Permissions → File Station에서 `docker` shared folder Read 권한 + Applications → Sharing 권한 ON.
+
+### 5.5 `scripts/deploy-nas.sh` SERVICES 화이트리스트
+
+webhook 자동 배포(deployer)가 호출하는 sync 스크립트는 화이트리스트로 동기화 대상 디렉토리를 명시한다. 신규 서비스 추가 시 반드시 함께 수정해야 NAS 운영 디렉토리에 소스 sync + docker compose 빌드가 동작한다.
+
+```bash
+SERVICES="lotto travel-proxy deployer stock-lab music-lab blog-lab realestate-lab agent-office personal packs-lab nginx scripts"
+```
+
+(packs-lab 누락 시 `docker compose ps`에 packs-lab 미등장 — 첫 배포 시 가장 흔한 누락 항목)
+
+---
+
+## 6. 테스트 전략
+
+기존 `tests/test_auth.py` 유지. 신규 3 파일.
+
+### 6.1 `tests/conftest.py` (신규)
+
+```python
+import pytest
+
+@pytest.fixture(autouse=True)
+def _hmac_secret(monkeypatch):
+    """모든 테스트에서 동일한 HMAC secret 사용."""
+    monkeypatch.setenv("BACKEND_HMAC_SECRET", "test-secret-do-not-use-in-prod")
+```
+
+### 6.2 `tests/test_routes.py` (신규) — 통합 테스트
+
+DSM·Supabase 모두 mock. `pytest`, `monkeypatch`, `unittest.mock`, `fastapi.testclient.TestClient` 사용.
+
+| 테스트 | 검증 |
+|--------|------|
+| `test_sign_link_hmac_required` | timestamp/signature 헤더 누락 → 401 |
+| `test_sign_link_outside_base_dir` | file_path가 `PACK_BASE_DIR` 외부 → 400 |
+| `test_sign_link_calls_dsm` | mock된 `create_share_link` 호출 검증, URL 응답 |
+| `test_mint_token_hmac_required` | HMAC 누락 → 401 |
+| `test_mint_token_returns_valid_token` | 발급된 token이 `verify_upload_token`으로 통과 |
+| `test_mint_token_invalid_filename` | 확장자 미허용 → 400 |
+| `test_upload_token_required` | Authorization Bearer 누락 → 401 |
+| `test_upload_size_mismatch` | 토큰 size_bytes ≠ 실제 → 400 |
+| `test_upload_jti_replay` | 같은 토큰 두 번 → 두 번째 409 |
+| `test_list_returns_active_only` | mock supabase 응답에서 deleted_at NULL만 반환 |
+| `test_delete_soft_deletes` | mock supabase update에 deleted_at ISO timestamp 들어감 |
+
+### 6.3 `tests/test_dsm_client.py` (신규)
+
+httpx mock(`respx` 또는 `MockTransport`) 또는 `monkeypatch.setattr` 패치.
+
+| 테스트 | 검증 |
+|--------|------|
+| `test_create_share_link_login_logout` | login → Sharing.create → logout 순서 |
+| `test_create_share_link_returns_url_and_expiry` | 응답 파싱 |
+| `test_dsm_login_failure_raises` | login API success=false → DSMError |
+| `test_dsm_share_failure_logs_out` | Sharing.create 실패해도 logout 호출 (try/finally) |
+
+---
+
+## 7. 문서 갱신
+
+### 7.1 `web-backend/CLAUDE.md` — 5곳
+
+**1. 1.프로젝트 개요**
+
+```diff
+- 서비스: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, deployer (9개)
++ 서비스: lotto-lab, stock-lab, travel-proxy, music-lab, blog-lab, realestate-lab, agent-office, personal, packs-lab, deployer (10개)
+```
+
+**2. 4.Docker 서비스 표** — 신규 행
+
+```
+| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (DSM 공유 링크 + 5GB 업로드, Vercel SaaS와 HMAC 통신) |
+```
+
+**3. 5.Nginx 라우팅 표** — 신규 행
+
+```
+| `/api/packs/` | `packs-lab:8000` | 5GB 업로드 (`client_max_body_size 5G` + `proxy_request_buffering off`) |
+```
+
+**4. 8.로컬 개발 표** — 신규 행
+
+```
+| Packs Lab | http://localhost:18950 |
+```
+
+**5. 9.서비스별** — `### packs-lab (packs-lab/)` 신규 섹션
+
+내용:
+- 용도 (NAS DSM 공유링크 + 5GB 업로드 + Vercel HMAC, 사용자 인증은 Vercel이 Supabase로 처리)
+- 환경변수 6+1개
+- DB는 외부 Supabase `pack_files` (DDL은 `packs-lab/supabase/pack_files.sql`)
+- 파일 구조: `main.py`, `auth.py`, `dsm_client.py`, `routes.py`, `models.py`
+- API 표 5개:
+  - `POST /api/packs/sign-link` (Vercel HMAC → DSM Sharing.create)
+  - `POST /api/packs/admin/mint-token` (Vercel HMAC → upload 토큰)
+  - `POST /api/packs/upload` (Bearer token → multipart 5GB)
+  - `GET /api/packs/list` (Vercel HMAC → 활성 파일 목록)
+  - `DELETE /api/packs/{file_id}` (Vercel HMAC → soft delete)
+
+### 7.2 `workspace/CLAUDE.md`
+
+컨테이너 표에 한 줄 추가:
+
+```
+| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (Vercel SaaS와 HMAC 통신) |
+```
+
+---
+
+## 8. 스코프
+
+### 본 spec 범위
+
+- ✅ admin mint-token 라우트 신설
+- ✅ Supabase `pack_files` DDL
+- ✅ docker-compose / nginx / .env.example / NAS 디렉토리 마운트
+- ✅ tests (auth 유지 + routes 통합 + dsm_client mock)
+- ✅ CLAUDE.md 2곳 갱신
+- ✅ DELETE 라우트 docstring 수정
+
+### 후속 별도 spec
+
+- ❌ Vercel SaaS-side admin UI / 사용자 다운로드 UI / Supabase pricing & user 테이블
+- ❌ DSM 공유 추적 (즉시 차단 필요시)
+- ❌ deleted_at + N일 후 실제 파일 삭제 cron
+- ❌ multi-admin 토큰 발급 권한 분리
+- ❌ resumable multipart 업로드 (5GB tus 등)
+- ❌ pack_files sort_order 편집 endpoint (admin UI 단계)
+- ❌ monitoring (업로드 실패율, DSM API latency)

docs/superpowers/specs/2026-05-09-essential-mix-pipeline-design.md

@@ -0,0 +1,706 @@
+# Essential Mix 파이프라인 — 1시간 mix + essential 시각 스타일 + UX 강화 설계
+
+> 작성일: 2026-05-09
+> 관련 spec:
+> - `2026-05-07-music-youtube-pipeline-design.md` (본 파이프라인의 베이스)
+> - `2026-05-09-gpu-video-offload-design.md` (Windows GPU 인코딩)
+
+---
+
+## 1. 배경
+
+현재 파이프라인은 **단일 트랙 → 단일 영상**(커버 + 가장자리 파형)만 지원. 사용자는 YouTube essential 채널처럼 **1시간 이상의 음악 mix + 차분한 배경 + 중앙 비주얼라이저** 영상을 원함.
+
+또한 진행 중 산출물(커버·썸네일·영상)을 NAS 파일시스템에서 직접 확인하는 게 번거로워, 진행 탭에서도 미리보기 가능했으면 함.
+
+---
+
+## 2. 비목표
+
+- 사용자 직접 업로드 사진/영상 (P3로 미룸)
+- 360° 정확한 방사형 비주얼라이저 (ffmpeg 단독으로 한계 — `showfreqs` + ring overlay로 근사)
+- Mix 자동 큐레이션(곡 자동 선택) — 기존 컴파일 탭의 수동 선택 그대로 활용
+- AI 검토 가중치 자동 튜닝 (Mix와 단일 트랙의 다른 기준 등 — P3)
+- 텔레그램 사진 첨부 — 본 작업의 PipelineDetailModal로 우선 해결, 차후 P3
+
+---
+
+## 3. 사용자 흐름
+
+### 3-1. Mix 영상 만들기
+
+```
+[사용자] Compile 탭에서 트랙 N개 선택 → crossfade 설정 → 컴파일 시작
+   → 컴파일 완료 (1시간+ mp3 생성, 기존 흐름)
+   → 컴파일 카드에 [🎬 영상 만들기] 버튼 클릭
+   → 백엔드: POST /api/music/pipeline { compile_job_id, visual_style: 'essential' }
+   → 진행 탭으로 자동 이동, 새 카드 생성
+   → 단계별 텔레그램 승인 (기존과 동일):
+       cover (또는 background_video) → video → thumbnail → metadata → AI 검토 → 발행
+   → YouTube 비공개 영상 1편
+```
+
+### 3-2. 단일 트랙 영상 만들기 (기존)
+
+진행 탭 모달에 라디오 "단일 트랙 / Mix" 추가. 단일 선택 시 기존 흐름 그대로.
+
+### 3-3. 산출물 미리보기
+
+진행 탭 카드의 cover/thumbnail 미니 썸네일 → 카드 클릭 → 상세 모달 → 큰 이미지 + 영상 플레이어 + 메타·검토 JSON.
+
+---
+
+## 4. 데이터 모델 변경
+
+### 4-1. `video_pipelines` 테이블 확장
+
+신규 컬럼:
+```sql
+ALTER TABLE video_pipelines ADD COLUMN compile_job_id INTEGER NULL REFERENCES compile_jobs(id);
+ALTER TABLE video_pipelines ADD COLUMN visual_style TEXT NOT NULL DEFAULT 'essential';
+ALTER TABLE video_pipelines ADD COLUMN background_mode TEXT NOT NULL DEFAULT 'static';
+ALTER TABLE video_pipelines ADD COLUMN background_keyword TEXT;
+```
+
+| 컬럼 | 의미 |
+|------|------|
+| `track_id` (기존) | 단일 트랙 입력 시 |
+| `compile_job_id` (신규) | Mix 입력 시 — `track_id` XOR `compile_job_id` |
+| `visual_style` | `single` / `essential` |
+| `background_mode` | `static` (사진) / `video_loop` (영상) |
+| `background_keyword` | Pexels 검색용 (예: "rainy window cafe"). 비어있으면 장르 기반 자동 |
+
+마이그레이션: `ADD COLUMN`은 SQLite에서 안전. 기존 행은 NULL 또는 default 값 부여.
+
+### 4-2. `youtube_setup.visual_defaults` JSON 확장
+
+기존:
+```json
+{"resolution": "1920x1080", "style": "visualizer", "background": "ai_cover"}
+```
+
+신규:
+```json
+{
+  "resolution": "1920x1080",
+  "default_visual_style": "essential",
+  "default_background_mode": "static",
+  "default_background_keyword": "",
+  "background_image_source": "ai",      // ai | pexels (Mix는 default ai)
+  "subtitle_track_titles": true          // Mix에서 곡명 자막 표시
+}
+```
+
+기존 클라이언트 호환을 위해 미설정 키는 default로 fallback.
+
+---
+
+## 5. API 변경
+
+### 5-1. `POST /api/music/pipeline` 요청 body 확장
+
+```json
+{
+  "track_id": 13,
+  // 또는
+  "compile_job_id": 5,
+  // 옵션 (default는 setup에서)
+  "visual_style": "essential",            // single | essential
+  "background_mode": "static",            // static | video_loop
+  "background_keyword": "rainy cafe"
+}
+```
+
+검증:
+- `track_id` XOR `compile_job_id` 정확히 하나만 — 둘 다거나 둘 다 없으면 400
+- `compile_job_id`인 경우 `compile_jobs` 테이블에서 status='succeeded' 확인 — 아니면 400
+- `visual_style` 미지정 시 `youtube_setup.visual_defaults.default_visual_style`
+- `background_mode` 미지정 시 `youtube_setup.visual_defaults.default_background_mode`
+
+응답:
+```json
+{
+  "id": 7,
+  "track_id": null,
+  "compile_job_id": 5,
+  "visual_style": "essential",
+  "background_mode": "static",
+  "state": "created",
+  ...
+}
+```
+
+### 5-2. `GET /api/music/pipeline/{id}` 응답 확장
+
+신규 필드: `compile_job_id`, `visual_style`, `background_mode`, `background_keyword`, `tracks` (Mix면 트랙 리스트, 단일이면 단일 트랙 1개)
+
+`tracks` 형식:
+```json
+[
+  {"id": 13, "title": "Lo-Fi Drive", "start_offset_sec": 0, "duration_sec": 176},
+  {"id": 14, "title": "Midnight Cafe", "start_offset_sec": 173, "duration_sec": 200},
+  ...
+]
+```
+
+`start_offset_sec`은 컴파일 시 acrossfade 적용을 고려한 누적 시작 시각 (=영상 자막 트리거 타이밍).
+
+### 5-3. 변경 없음
+
+`/feedback`, `/cancel`, `/publish`, `/setup`, `/youtube/*` 모두 그대로.
+
+---
+
+## 6. 백엔드 — NAS music-lab
+
+### 6-1. `pipeline/orchestrator.py` 변경
+
+`run_step`에 입력 audio 결정 로직 추가:
+
+```python
+def _resolve_input(p: dict) -> dict:
+    """파이프라인 입력 = 단일 트랙 또는 컴파일 결과.
+
+    반환: {"audio_path": str, "duration_sec": int, "tracks": list[dict],
+           "title": str, "genre": str, "moods": list, ...}
+    """
+    if p.get("compile_job_id"):
+        job = db.get_compile_job(p["compile_job_id"])
+        if not job or job["status"] != "succeeded":
+            raise ValueError(f"compile job {p['compile_job_id']} not ready")
+        # 누적 offset 계산 (acrossfade 고려)
+        tracks = []
+        offset = 0.0
+        crossfade = job["crossfade_sec"]
+        for tid in job["track_ids"]:
+            t = db.get_track_by_id(tid)
+            tracks.append({
+                "id": tid, "title": t["title"],
+                "start_offset_sec": offset,
+                "duration_sec": t["duration_sec"],
+            })
+            offset += t["duration_sec"] - crossfade  # acrossfade overlap만큼 차감
+        return {
+            "audio_path": job["audio_path"],         # /app/data/compiles/{id}.mp3
+            "duration_sec": int(offset + crossfade), # 마지막 트랙은 풀 길이
+            "tracks": tracks,
+            "title": job["title"] or "Mix",
+            "genre": "mix",
+            "moods": [],
+        }
+    else:
+        t = db.get_track_by_id(p["track_id"])
+        return {
+            "audio_path": t["file_path"],
+            "duration_sec": t["duration_sec"],
+            "tracks": [{"id": t["id"], "title": t["title"],
+                        "start_offset_sec": 0, "duration_sec": t["duration_sec"]}],
+            "title": t["title"], "genre": t["genre"], "moods": t.get("moods", []),
+        }
+```
+
+각 step runner는 `_resolve_input(p)` 결과를 사용:
+- `_run_cover`: `genre`, `moods`, `title` 활용 (Mix면 `genre="mix"` → "mix" 키 prompt 또는 default)
+- `_run_video`: `audio_path`, `duration_sec`, `tracks` 모두 Windows로 전달
+- `_run_meta`: `tracks` 리스트를 메타 prompt에 포함
+- `_run_review`: `tracks` 리스트를 검토 prompt에 포함 (트랙 수, 다양한 장르 등)
+
+### 6-2. `pipeline/cover.py` Pexels 폴백/대안
+
+```python
+async def generate(*, pipeline_id: int, genre: str, prompt_template: str,
+                   mood: str = "", track_title: str = "", feedback: str = "",
+                   image_source: str = "ai") -> dict:
+    """image_source: 'ai' (DALL·E) | 'pexels' (스톡 검색)."""
+    if image_source == "pexels":
+        return await _generate_with_pexels(pipeline_id, genre, mood, track_title)
+    # 기존 AI 흐름 그대로
+    ...
+    # AI 실패 시 — 그라데이션 폴백 대신 Pexels 시도 (config 옵션)
+    ...
+```
+
+신규 `_generate_with_pexels`:
+- Pexels API: `GET https://api.pexels.com/v1/search?query={keyword}&per_page=10`
+- 결과 1번째 큰 사진 다운로드 → `/app/data/videos/{id}/cover.jpg`
+- API key 미설정/실패 시 그라데이션 폴백
+
+### 6-3. 신규 `pipeline/background.py` (video_loop 모드)
+
+```python
+async def fetch_video_loop(pipeline_id: int, keyword: str) -> dict:
+    """Pexels Video API로 5–15초 루프 영상 받아옴.
+
+    /app/data/videos/{id}/loop.mp4 저장.
+    """
+    # GET https://api.pexels.com/videos/search?query=...&per_page=5
+    # SD/HD 720p 중에서 골라 다운로드
+    ...
+    return {"path": "/app/data/videos/{id}/loop.mp4", "duration_sec": ...}
+```
+
+오케스트레이터에서 `background_mode == "video_loop"` 분기 시 cover step 대신 또는 보조로 호출 (디자인 결정: cover step을 두 모드의 공통 입력 준비 단계로 통합 — 정적이면 cover.jpg, 영상이면 loop.mp4).
+
+### 6-4. `pipeline/metadata.py` Mix 지원
+
+`generate(*, track, template, trend_keywords, feedback="", tracks=None)` 시그니처 확장. `tracks` 있으면 Claude prompt에 다음 추가:
+
+```
+이 영상은 {len(tracks)}개 트랙의 mix입니다. 트랙 리스트:
+1. [00:00] Lo-Fi Drive — lo-fi
+2. [03:00] Midnight Cafe — lo-fi
+...
+설명에는 트랙 리스트를 타임스탬프와 함께 포함하세요.
+```
+
+응답 description은 자동으로 트랙리스트 포함됨. 이는 YouTube에서 챕터로 자동 인식.
+
+### 6-5. `pipeline/video.py` (NAS측, 변경 작음)
+
+기존 함수에 추가 파라미터 전달:
+
+```python
+def generate(*, pipeline_id, audio_path, cover_path, genre, duration_sec,
+             resolution="1920x1080", style="essential",
+             background_mode="static", background_path=None,
+             tracks=None) -> dict:
+    payload = {
+        "audio_path_nas": ..., "cover_path_nas": ...,
+        "output_path_nas": ...,
+        "resolution": resolution,
+        "duration_sec": duration_sec,
+        "style": style,                     # NEW: single | essential
+        "background_mode": background_mode, # NEW: static | video_loop
+        "background_path_nas": ...,         # NEW: video_loop일 때 loop.mp4 경로
+        "tracks": tracks,                   # NEW: Mix면 트랙 리스트 (자막용)
+    }
+    ...
+```
+
+### 6-6. `db.py` 변경
+
+신규 컬럼 추가 마이그레이션 + `get_compile_job(id)` (없으면 추가) + `get_track_by_id(id)` 활용.
+
+---
+
+## 7. 백엔드 — Windows music_ai
+
+### 7-1. `/encode_video` 요청 확장
+
+```json
+{
+  "audio_path_nas": "...",
+  "cover_path_nas": "...",
+  "output_path_nas": "...",
+  "resolution": "1920x1080",
+  "duration_sec": 3600,
+  "style": "essential",                    // NEW
+  "background_mode": "static",             // NEW
+  "background_path_nas": "...",            // NEW: video_loop면 loop.mp4
+  "tracks": [                              // NEW: 자막용
+    {"start_offset_sec": 0, "title": "Lo-Fi Drive"},
+    {"start_offset_sec": 173, "title": "Midnight Cafe"}
+  ]
+}
+```
+
+### 7-2. `video_encoder.py` 분기 로직
+
+```python
+def encode_video(*, ..., style="essential", background_mode="static",
+                  background_path_nas=None, tracks=None):
+    if style == "single":
+        cmd = build_single_track_cmd(...)
+    else:  # essential
+        if background_mode == "static":
+            cmd = build_essential_static_cmd(cover, audio, out, w, h, tracks)
+        else:
+            bg = translate_path(background_path_nas)
+            cmd = build_essential_video_loop_cmd(bg, audio, out, w, h, tracks)
+    ...
+```
+
+### 7-3. Essential 정적 ffmpeg 명령
+
+핵심 filter_complex 구조:
+
+```
+[0:v]scale=1920:1080,format=yuv420p[bg];           # 정적 배경 사진
+[1:a]showfreqs=s=400x200:mode=bar:cmode=combined:colors=0xFFFFFF@0.9[bars];  # 중앙 막대
+[2:v]format=rgba[ring];                            # 데코 ring PNG (사전 제작 1장)
+[bg][bars]overlay=(W-w)/2:(H-h)/2[mid];           # 막대 정중앙 배치
+[mid][ring]overlay=(W-w)/2:(H-h)/2[viz];          # ring 데코 같은 위치
+[viz]drawtext=...:enable='between(t,0,5)+between(t,173,178)+...'[final]
+```
+
+- `showfreqs s=400x200 mode=bar` — 가로 막대 (방사형 근사 1차 버전)
+- `ring.png` — 사전 제작된 투명 PNG (`music_ai/assets/visualizer_ring.png`, 단순 흰색 원 + 외곽 점선)
+- `drawtext` — 트랙 리스트 순회하며 enable expression 동적 생성
+
+향후(V2): `showcqt`나 `showspectrum` 시도 + 진짜 360° 방사형은 외부 도구(예: SuperCollider, butterchurn) 검토.
+
+### 7-4. Essential 영상 루프 ffmpeg 명령
+
+```
+[0:v]scale=1920:1080,setpts=PTS-STARTPTS[bg_loop];
+loop=loop=-1:size=N         # 루프 영상 무한 반복
+[1:a]showfreqs=...[bars];
+[bg_loop][bars]overlay=center[mid];
+[mid][ring]overlay=center[viz];
+... drawtext 동일
+```
+
+루프는 `-stream_loop -1 -i loop.mp4` 입력 옵션 + `-shortest` 출력으로 audio 길이만큼 반복.
+
+### 7-5. 자막(곡명) drawtext
+
+```python
+def build_drawtext_filter(tracks, total_duration):
+    expressions = []
+    for tr in tracks:
+        start = tr["start_offset_sec"]
+        end = start + 5  # 5초 표시
+        # alpha fade in/out
+        text = tr["title"].replace(":", r"\:").replace("'", r"\'")
+        expressions.append(
+            f"drawtext=fontfile='Arial Bold':text='{text}'"
+            f":fontcolor=white:fontsize=36:x=(w-text_w)/2:y=h-100"
+            f":alpha='if(between(t,{start},{end}),"
+            f"  if(lt(t-{start},1), t-{start},"      # 0~1s fade in
+            f"     if(gt(t-{start},4), {end}-t, 1)), 0)'"   # 4~5s fade out
+        )
+    return ",".join(expressions)  # 체인으로 연결
+```
+
+폰트는 Windows에 기본 설치된 Arial 또는 NanumGothic 사용. 한글 트랙명 지원 위해 NanumGothic 권장.
+
+### 7-6. 신규 자산 파일
+
+`music_ai/assets/visualizer_ring.png` — 1920×1080 캔버스 정중앙 400×400 영역에 그려진 흰색 원형 (외곽선 + 옅은 inner glow). 사전 제작 1장 — Pillow로 자동 생성도 가능 (서버 시작 시 없으면 생성).
+
+---
+
+## 8. 프론트엔드 변경
+
+### 8-1. `CompileTab.jsx` — 영상 만들기 버튼
+
+완료된 compile job 카드에 버튼 추가:
+
+```jsx
+{job.status === 'succeeded' && (
+    <button onClick={() => handleVideoFromCompile(job.id)}>
+        🎬 영상 만들기
+    </button>
+)}
+```
+
+`handleVideoFromCompile`:
+```js
+async (compileJobId) => {
+    const p = await createPipeline({ compile_job_id: compileJobId });
+    await startPipeline(p.id);
+    // 진행 탭으로 이동 (router push 또는 setTab + setOpenPipelineFor 패턴)
+};
+```
+
+### 8-2. `PipelineStartModal.jsx` 확장
+
+```jsx
+const [inputType, setInputType] = useState('track');  // 'track' | 'compile'
+const [compileJobs, setCompileJobs] = useState([]);
+
+useEffect(() => {
+    if (inputType === 'compile') getCompileJobs().then(setCompileJobs);
+}, [inputType]);
+
+return (
+    <div className="modal-body">
+        <h3>새 파이프라인 시작</h3>
+
+        <fieldset>
+            <legend>입력</legend>
+            <label><input type="radio" checked={inputType==='track'}
+                onChange={() => setInputType('track')}/> 단일 트랙</label>
+            <label><input type="radio" checked={inputType==='compile'}
+                onChange={() => setInputType('compile')}/> Mix (컴파일 결과)</label>
+        </fieldset>
+
+        {inputType === 'track' && (
+            <select>{library.map(...)}</select>
+        )}
+        {inputType === 'compile' && (
+            <select>{compileJobs.filter(j=>j.status==='succeeded').map(j =>
+                <option key={j.id} value={j.id}>{j.title} ({j.tracks_count}곡, {fmtDuration(j.duration_sec)})</option>
+            )}</select>
+        )}
+
+        {/* 시각 모드 override */}
+        <details>
+            <summary>고급 옵션</summary>
+            <select>visual_style: single | essential</select>
+            <select>background_mode: static | video_loop</select>
+            <input>background_keyword</input>
+        </details>
+
+        {/* ... 기존 시작/취소 버튼 */}
+    </div>
+);
+```
+
+### 8-3. `PipelineCard.jsx` — 미리보기 inline
+
+```jsx
+return (
+    <div className="pipeline-card" onClick={() => setShowDetail(true)}>
+        <div className="pipeline-card__head">
+            <h4>{pipeline.track_title || pipeline.compile_title || `Pipeline #${pipeline.id}`}</h4>
+            <span className="pipeline-style-badge">{pipeline.visual_style}</span>
+            ...
+        </div>
+
+        {/* 미니 미리보기 */}
+        <div className="pipeline-previews">
+            {pipeline.cover_url && <img src={pipeline.cover_url} alt="" className="pipeline-preview-mini" />}
+            {pipeline.thumbnail_url && <img src={pipeline.thumbnail_url} alt="" className="pipeline-preview-mini" />}
+            {pipeline.video_url && <span className="pipeline-video-icon">▶</span>}
+        </div>
+
+        {/* 진행도 바 + 현재 상태 (기존) */}
+        ...
+    </div>
+);
+```
+
+### 8-4. `PipelineDetailModal.jsx` (신규)
+
+```jsx
+export default function PipelineDetailModal({ pipeline, onClose }) {
+    return (
+        <div className="modal-overlay" onClick={onClose}>
+            <div className="modal-body modal-body--lg" onClick={e=>e.stopPropagation()}>
+                <header>
+                    <h3>{pipeline.compile_title || pipeline.track_title}</h3>
+                    <span className="badge">{pipeline.visual_style}</span>
+                    <button onClick={onClose}>×</button>
+                </header>
+
+                {/* 큰 미리보기 그리드 */}
+                <div className="pdm-grid">
+                    {pipeline.cover_url && (
+                        <figure>
+                            <img src={pipeline.cover_url} alt="cover" />
+                            <figcaption>커버 (배경)</figcaption>
+                        </figure>
+                    )}
+                    {pipeline.thumbnail_url && (
+                        <figure>
+                            <img src={pipeline.thumbnail_url} alt="thumbnail" />
+                            <figcaption>썸네일</figcaption>
+                        </figure>
+                    )}
+                </div>
+
+                {/* 영상 플레이어 */}
+                {pipeline.video_url && (
+                    <div className="pdm-video">
+                        <video src={pipeline.video_url} controls width="100%" />
+                    </div>
+                )}
+
+                {/* 메타데이터 */}
+                {pipeline.metadata && (
+                    <section className="pdm-meta">
+                        <h4>메타데이터</h4>
+                        <p><strong>제목:</strong> {pipeline.metadata.title}</p>
+                        <details>
+                            <summary>설명</summary>
+                            <pre>{pipeline.metadata.description}</pre>
+                        </details>
+                        <p><strong>태그:</strong> {pipeline.metadata.tags?.join(', ')}</p>
+                    </section>
+                )}
+
+                {/* AI 검토 */}
+                {pipeline.review && (
+                    <section className="pdm-review">
+                        <h4>AI 검토 — <span className="badge">{pipeline.review.verdict}</span> ({pipeline.review.weighted_total}/100)</h4>
+                        <table>
+                            <tbody>
+                                <tr><td>메타데이터 품질</td><td>{pipeline.review.metadata_quality.score}</td></tr>
+                                <tr><td>콘텐츠 정책</td><td>{pipeline.review.policy_compliance.score}</td></tr>
+                                <tr><td>시청 경험</td><td>{pipeline.review.viewer_experience.score}</td></tr>
+                                <tr><td>트렌드 정렬</td><td>{pipeline.review.trend_alignment.score}</td></tr>
+                            </tbody>
+                        </table>
+                        <p><em>{pipeline.review.summary}</em></p>
+                    </section>
+                )}
+
+                {/* 트랙 리스트 (Mix일 때) */}
+                {pipeline.tracks && pipeline.tracks.length > 1 && (
+                    <section className="pdm-tracks">
+                        <h4>트랙 리스트 ({pipeline.tracks.length})</h4>
+                        <ol>
+                            {pipeline.tracks.map(t => (
+                                <li key={t.id}>
+                                    [{fmtTimestamp(t.start_offset_sec)}] {t.title} ({fmtDuration(t.duration_sec)})
+                                </li>
+                            ))}
+                        </ol>
+                    </section>
+                )}
+
+                {/* 피드백 히스토리 */}
+                {pipeline.feedback && pipeline.feedback.length > 0 && (
+                    <section className="pdm-feedback">
+                        <h4>피드백 ({pipeline.feedback.length})</h4>
+                        <ul>
+                            {pipeline.feedback.map(f => (
+                                <li key={f.id}>
+                                    <code>[{f.step}]</code> {f.feedback_text}
+                                    <small>{f.received_at}</small>
+                                </li>
+                            ))}
+                        </ul>
+                    </section>
+                )}
+
+                {/* YouTube 링크 */}
+                {pipeline.youtube_video_id && (
+                    <a href={`https://youtu.be/${pipeline.youtube_video_id}`}
+                       target="_blank" rel="noreferrer" className="pdm-youtube">
+                        🎬 YouTube에서 보기
+                    </a>
+                )}
+            </div>
+        </div>
+    );
+}
+```
+
+### 8-5. `SetupTab.jsx` 확장
+
+영상 비주얼 기본값 카드 확장:
+- **default_visual_style** 드롭다운: `single` / `essential`
+- **default_background_mode** 드롭다운: `static` / `video_loop`
+- **default_background_keyword** 텍스트 입력 (예: "lofi cafe")
+- **background_image_source** 드롭다운: `ai` / `pexels`
+- **subtitle_track_titles** 체크박스: Mix에서 곡명 자막 표시
+
+---
+
+## 9. 환경변수 (NAS측)
+
+신규 — 이미 `.env`에 있을 가능성 높음:
+```env
+PEXELS_API_KEY=xxx     # 이미 있음 (현재 미사용)
+```
+
+신규 (Windows측 — music_ai/.env):
+```env
+# 한글 자막용 폰트 경로 (선택)
+SUBTITLE_FONT=C:\Windows\Fonts\malgun.ttf
+```
+
+---
+
+## 10. 에러 처리
+
+| 시나리오 | 결과 |
+|---------|------|
+| compile_job 미완료 (status != succeeded) | POST /pipeline 시 400 |
+| compile_job 삭제됨 | get_pipeline에서 `compile_title=null`, 진행 탭에 "삭제됨" 배지 |
+| Pexels API 실패 (image) | AI 폴백 |
+| Pexels API 실패 (video) | 단색 폴백 + 텔레그램에 "Pexels 실패" 명시 |
+| drawtext 자막 한글 폰트 누락 | 자막 없이 인코딩 + 경고 로그 |
+| 1시간 NVENC timeout | 영상 단계 timeout 600s → 그래도 부족하면 failed (보통 NVENC면 5분 내) |
+
+---
+
+## 11. 테스트 전략
+
+### 11-1. 단위 테스트 (NAS music-lab)
+
+| 대상 | 테스트 |
+|------|--------|
+| `orchestrator._resolve_input` | track_id 분기 / compile_job_id 분기 / 둘 다 / 둘 다 없음 / compile not ready |
+| `cover.generate` `image_source='pexels'` | Pexels API mock + 다운로드 + 파일 저장 |
+| `background.fetch_video_loop` | Pexels Video API mock + mp4 다운로드 |
+| `metadata.generate` `tracks=[...]` | 트랙 리스트가 prompt에 포함되는지, 응답 description에 chapter 포맷 |
+| API `POST /pipeline { compile_job_id }` | 정상 / not ready 400 / 둘 다 400 / 단일은 기존 작동 |
+| DB 마이그레이션 | 새 컬럼 default 값 |
+
+### 11-2. 단위 테스트 (Windows music_ai)
+
+| 대상 | 테스트 |
+|------|--------|
+| `build_essential_static_cmd` | filter_complex 문자열 검증 (showfreqs, overlay 위치 등) |
+| `build_drawtext_filter` | 트랙 N개 → enable expression N개 생성, alpha fade 검증 |
+| `encode_video` `style='essential'` | 새 분기 호출됨 |
+| `encode_video` `style='single'` | 기존 단일 트랙 명령 그대로 |
+| 자산 ring.png 자동 생성 | 서버 시작 시 없으면 PIL로 생성 |
+
+### 11-3. 통합 테스트
+
+`test_essential_pipeline_flow.py`:
+- compile job 생성 → 파이프라인 시작 (compile_job_id) → 모든 단계 mock → published → tracks 리스트가 metadata description에 포함됐는지
+
+### 11-4. 수동 E2E
+
+- [ ] 컴파일 탭에서 3-5분 mix 컴파일
+- [ ] "🎬 영상 만들기" 클릭 → 진행 탭 카드 생성, visual_style=essential
+- [ ] cover 단계 → 텔레그램 알림 + 카드에 cover 미니 썸네일 표시
+- [ ] 카드 클릭 → 상세 모달 → cover 큰 이미지, 메타·검토 영역 표시 (해당 단계 진행 시)
+- [ ] 모든 단계 승인 → 발행 → YouTube 비공개 영상에 essential 시각 + 챕터 자동 인식 확인
+- [ ] 1시간 mix로 동일 흐름 — Windows NVENC 인코딩 시간 5분 미만 확인
+- [ ] background_mode=video_loop로 시도 — Pexels 영상 다운로드 + 루프 인코딩
+
+---
+
+## 12. 마이그레이션 + 배포
+
+### 12-1. DB 마이그레이션
+
+`init_db()` 신규 컬럼 `ALTER TABLE` (SQLite는 idempotent: 컬럼 존재 확인 후 추가):
+```python
+def _add_column_if_missing(cursor, table, column, ddl):
+    cursor.execute(f"PRAGMA table_info({table})")
+    cols = [r[1] for r in cursor.fetchall()]
+    if column not in cols:
+        cursor.execute(f"ALTER TABLE {table} ADD COLUMN {column} {ddl}")
+```
+
+### 12-2. 자산 파일
+
+`music_ai/assets/visualizer_ring.png`은 git에 커밋 (small, ~30KB). Windows 측이므로 사용자가 수동 배포 (이미 music_ai는 로컬 전용).
+
+또는 **서버 시작 시 자동 생성** (PIL로 단순 ring 그리기) — 권장. assets 디렉토리도 자동 생성.
+
+### 12-3. 환경변수
+
+NAS `.env` 변경 없음 (PEXELS_API_KEY 이미 있음).
+Windows `.env`에 `SUBTITLE_FONT` 추가 (선택).
+
+---
+
+## 13. 산출물
+
+| 영역 | 파일 |
+|------|------|
+| Spec/Plan | 본 문서 + plan |
+| NAS music-lab | `db.py` (마이그레이션), `pipeline/orchestrator.py` (resolve_input), `pipeline/cover.py` (Pexels 분기), `pipeline/background.py` (신규), `pipeline/metadata.py` (tracks 옵션), `pipeline/video.py` (style/background 파라미터), `app/main.py` (POST /pipeline body 확장) |
+| Windows music_ai | `video_encoder.py` (style 분기, drawtext, ring), `server.py` (요청 schema 확장), `assets/visualizer_ring.png` (자동 생성), Pillow 이미 있음 |
+| Frontend | `CompileTab.jsx` (영상 만들기 버튼), `PipelineStartModal.jsx` (라디오), `PipelineCard.jsx` (미리보기 inline), `PipelineDetailModal.jsx` (신규), `SetupTab.jsx` (visual_defaults 확장), `api.js` 헬퍼 추가, `MusicStudio.css` 스타일 |
+| 테스트 | NAS 단위 6+ / Windows 단위 5+ / 통합 1 / 수동 E2E |
+
+---
+
+## 14. 후속 (P3)
+
+- 사용자 직접 사진/영상 업로드
+- 텔레그램에 cover/thumbnail 사진 첨부
+- 360° 진짜 방사형 visualizer (외부 도구 또는 GPU shader)
+- AI 검토 가중치 mix vs 단일 자동 분리
+- Pexels 검색 미리보기 UI (구성 탭에서 "이 키워드로 검색해보기" 버튼)
+
+---

docs/superpowers/specs/2026-05-09-gpu-video-offload-design.md

@@ -0,0 +1,486 @@
+# GPU 영상 인코딩 오프로드 — 설계
+
+> 작성일: 2026-05-09
+> 관련: `2026-05-07-music-youtube-pipeline-design.md` (Task 4 대체)
+
+---
+
+## 1. 배경
+
+NAS Synology Celeron J4025(2 cores @ 2.0GHz, GPU 없음)에서 1920×1080 visualizer 영상 인코딩이 너무 느림. 176초 트랙 인코딩에 5분 초과 → ffmpeg `subprocess.TimeoutExpired`. `-preset ultrafast`로 가속해도 한계 있고 화질 저하.
+
+대안: 사용자 Windows PC(RTX 5070 Ti, 16GB VRAM)에서 NVIDIA NVENC 하드웨어 인코딩으로 처리. 같은 영상이 **10–20초**에 완료(20×+ 빠름).
+
+이미 `music_ai` 서버(Windows, port 8765)가 MusicGen용으로 동작 중이므로 **같은 서버에 영상 인코딩 endpoint를 추가**하는 것이 가장 자연스럽다.
+
+---
+
+## 2. 비목표
+
+- 다중 GPU/멀티 머신 — 단일 Windows PC만 지원
+- NAS 로컬 ffmpeg 폴백 — 사용자 결정으로 제외 (Windows 서버 다운 시 명확한 실패 선호)
+- 영상 길이 제한 — 일반 트랙 길이(1–10분) 가정
+- 인증 — LAN 전용, 무인증
+
+---
+
+## 3. 아키텍처
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ NAS (Synology)                                            │
+│                                                           │
+│  music-lab container                                      │
+│    pipeline/video.py                                      │
+│      ↓ HTTP POST {paths, resolution}                      │
+│      ↓ 192.168.45.59:8765/encode_video                    │
+│                                                           │
+│  /volume1/docker/webpage/data/                            │
+│    videos/{id}/cover.jpg  ← input                         │
+│    videos/{id}/video.mp4  ← output (Windows가 직접 씀)    │
+│    {audio}.mp3            ← input                         │
+└────────────────────────────────────────────────────────────┘
+       ↓ HTTP                          ↑ SMB read/write
+       ↓                                ↑ (Z:\ 마운트)
+┌────────────────────────────────────────────────────────────┐
+│ Windows PC (192.168.45.59)                                │
+│                                                           │
+│  music_ai server.py (port 8765)                           │
+│   • POST /generate     (기존, MusicGen)                   │
+│   • POST /encode_video (신규)                             │
+│        ↓ 경로 변환: /volume1/... → Z:\...                 │
+│        ↓ ffmpeg.exe -hwaccel cuda -c:v h264_nvenc ...     │
+│        ↓ 입력/출력 모두 Z:\ 직접 (SMB)                    │
+│        ↓ 응답: {ok, duration_ms, output_path}             │
+│                                                           │
+│  Z:\docker\webpage\data\  (NAS SMB mount, 기존)           │
+│   videos\{id}\cover.jpg                                   │
+│   videos\{id}\video.mp4                                   │
+│   {audio}.mp3                                             │
+└────────────────────────────────────────────────────────────┘
+```
+
+**핵심 원칙:** 파일은 SMB로 직접 읽고 쓰기 — HTTP는 메타데이터(경로 + 옵션)만 전달.
+
+---
+
+## 4. Windows `music_ai` 서버 — `/encode_video` endpoint
+
+### 4-1. Request
+
+```http
+POST /encode_video HTTP/1.1
+Host: 192.168.45.59:8765
+Content-Type: application/json
+
+```
+
+| 필드 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| `cover_path_nas` | string | ✓ | 배경 이미지 NAS 절대경로 |
+| `audio_path_nas` | string | ✓ | 오디오 파일 NAS 절대경로 |
+| `output_path_nas` | string | ✓ | 출력 mp4 NAS 절대경로 |
+| `resolution` | string | ✓ | `WIDTHxHEIGHT` (예: `1920x1080`) |
+| `duration_sec` | int |  | 트랙 길이 — 진행 추적용 (옵션) |
+| `style` | string |  | 현재 `visualizer`만 (확장용) |
+
+### 4-2. Response
+
+**성공 (200):**
+```json
+{
+  "ok": true,
+  "duration_ms": 12340,
+  "output_path_nas": "/volume1/docker/webpage/data/videos/3/video.mp4",
+  "output_bytes": 28470000,
+  "encoder": "h264_nvenc",
+  "preset": "p4"
+}
+```
+
+**실패 (4xx/5xx):**
+```json
+{
+  "ok": false,
+  "error": "ffmpeg returncode=1: ...",
+  "stage": "ffmpeg"   // path_translate | input_validation | ffmpeg | output_check
+}
+```
+
+### 4-3. 경로 변환
+
+Windows 서버는 `nas_path → windows_path` 변환을 환경변수 기반으로 수행:
+
+```python
+# .env (Windows music_ai)
+NAS_VOLUME_PREFIX=/volume1/
+WINDOWS_DRIVE_ROOT=Z:\
+```
+
+변환 로직:
+```python
+def translate_path(nas_path: str) -> str:
+    # /volume1/docker/webpage/data/videos/3/cover.jpg
+    # → Z:\docker\webpage\data\videos\3\cover.jpg
+    if not nas_path.startswith(NAS_VOLUME_PREFIX):
+        raise ValueError(f"NAS prefix 불일치: {nas_path}")
+    rel = nas_path[len(NAS_VOLUME_PREFIX):]      # "docker/webpage/..."
+    return WINDOWS_DRIVE_ROOT + rel.replace("/", "\\")
+```
+
+### 4-4. 입력 검증
+
+ffmpeg 호출 전:
+- `cover_path` 변환된 Windows 경로의 파일 존재 확인 → 없으면 400 stage=input_validation
+- `audio_path` 동일
+- `output_path`의 부모 디렉토리 존재 확인 — 없으면 자동 생성
+- `resolution` 정규식 `^\d{3,4}x\d{3,4}$` 검증 → 실패 시 400
+
+### 4-5. ffmpeg 명령 (NVENC)
+
+```python
+def build_visualizer_cmd(cover_win, audio_win, out_win, w, h):
+    return [
+        "ffmpeg", "-y",
+        "-hwaccel", "cuda",
+        "-loop", "1", "-i", cover_win,
+        "-i", audio_win,
+        "-filter_complex",
+        f"[0:v]scale={w}:{h},format=yuv420p[bg];"
+        f"[1:a]showwaves=s={w}x200:mode=cline:colors=0xFF4444@0.8[wave];"
+        f"[bg][wave]overlay=0:({h}-200)[out]",
+        "-map", "[out]", "-map", "1:a",
+        "-c:v", "h264_nvenc",
+        "-preset", "p4",          # quality preset (p1=fastest, p7=slowest/best)
+        "-rc", "vbr",
+        "-cq", "23",              # quality (lower=better, 18-25 sane range)
+        "-b:v", "0",              # let CQ control bitrate
+        "-pix_fmt", "yuv420p",    # YouTube 호환
+        "-c:a", "aac", "-b:a", "192k",
+        "-shortest", out_win,
+    ]
+```
+
+**주요 플래그 설명:**
+- `-hwaccel cuda` — CUDA 사용
+- `-c:v h264_nvenc` — NVIDIA NVENC H.264 인코더
+- `-preset p4` — 품질·속도 균형 (5070 Ti 기준 1080p 영상 ~10–20s)
+- `-rc vbr -cq 23 -b:v 0` — VBR + 일정 품질 (CQ 23 = ~CRF 23)
+- `format=yuv420p` 명시 — NVENC가 가끔 yuv444 출력하는데 YouTube 호환 X
+
+### 4-6. 타임아웃 + 출력 검증
+
+- ffmpeg subprocess timeout: **180초** (NAS 측 HTTP timeout 200s 미만)
+- 종료 후 출력 파일 존재 + 크기 > 1MB 검증 → 미달 시 stage=output_check 실패
+- 종료 코드 0이지만 파일 비어있는 케이스 catch
+
+### 4-7. 동시 처리
+
+별도 큐 없음. 동시 호출 시 ffmpeg 프로세스 병렬 실행 — RTX 5070 Ti는 NVENC 세션 5개까지 지원.
+
+단일 사용자 시나리오에서 동시 인코딩은 거의 발생 안 함. 발생해도 GPU 리소스 충분.
+
+### 4-8. 헬스 체크 확장
+
+기존 `GET /health`에 인코더 가용성 정보 추가:
+```json
+{
+  "ok": true,
+  "gpu": "NVIDIA GeForce RTX 5070 Ti",
+  "musicgen_loaded": true,
+  "ffmpeg_path": "C:/ffmpeg/bin/ffmpeg.exe",
+  "ffmpeg_nvenc": true
+}
+```
+
+`ffmpeg_nvenc` 검증: 서버 시작 시 `ffmpeg -encoders | grep h264_nvenc` 한 번 실행 + 캐시.
+
+---
+
+## 5. NAS music-lab — `pipeline/video.py` 리팩토링
+
+### 5-1. 환경변수 (필수)
+
+```env
+WINDOWS_VIDEO_ENCODER_URL=http://192.168.45.59:8765
+```
+
+미설정 시: `pipeline/video.py`가 기동 시 명확한 에러로 실패 (ImportError 또는 RuntimeError).
+
+### 5-2. `video.generate(...)` — 새 구현
+
+```python
+"""영상 비주얼 생성 — Windows GPU 서버 (NVENC) 호출."""
+import os
+import logging
+import httpx
+
+from . import storage
+
+logger = logging.getLogger("music-lab.video")
+
+ENCODER_URL = os.getenv("WINDOWS_VIDEO_ENCODER_URL", "")
+ENCODER_TIMEOUT_S = 200  # Windows 서버 ffmpeg 180s + 마진
+
+
+class VideoGenerationError(Exception):
+    pass
+
+
+def generate(*, pipeline_id: int, audio_path: str, cover_path: str,
+             genre: str, duration_sec: int, resolution: str = "1920x1080",
+             style: str = "visualizer") -> dict:
+    """원격 Windows 서버 호출. 다운/실패 시 즉시 예외."""
+    if not ENCODER_URL:
+        raise VideoGenerationError(
+            "WINDOWS_VIDEO_ENCODER_URL 미설정 — Windows 인코더 서버 주소 필요"
+        )
+
+    out_path = os.path.join(storage.pipeline_dir(pipeline_id), "video.mp4")
+    nas_audio = _container_to_nas(audio_path)
+    nas_cover = _container_to_nas(cover_path)
+    nas_output = _container_to_nas(out_path)
+
+    payload = {
+        "cover_path_nas": nas_cover,
+        "audio_path_nas": nas_audio,
+        "output_path_nas": nas_output,
+        "resolution": resolution,
+        "duration_sec": duration_sec,
+        "style": style,
+    }
+
+    logger.info("Windows 인코더 호출: %s → %s", audio_path, out_path)
+    try:
+        with httpx.Client(timeout=ENCODER_TIMEOUT_S) as client:
+            resp = client.post(f"{ENCODER_URL}/encode_video", json=payload)
+    except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as e:
+        raise VideoGenerationError(f"Windows 인코더 연결 실패: {e}")
+
+    if resp.status_code != 200:
+        try:
+            detail = resp.json()
+        except Exception:
+            detail = {"error": resp.text[:300]}
+        raise VideoGenerationError(
+            f"Windows 인코더 오류 ({resp.status_code}): "
+            f"{detail.get('stage','?')} — {detail.get('error','?')}"
+        )
+
+    data = resp.json()
+    if not data.get("ok"):
+        raise VideoGenerationError(f"Windows 인코더 응답 ok=false: {data}")
+
+    return {
+        "url": storage.media_url(pipeline_id, "video.mp4"),
+        "used_fallback": False,
+        "duration_sec": duration_sec,
+        "encode_duration_ms": data.get("duration_ms"),
+        "encoder": data.get("encoder", "h264_nvenc"),
+    }
+
+
+def _container_to_nas(container_path: str) -> str:
+    """ /app/data/videos/3/cover.jpg → /volume1/docker/webpage/data/videos/3/cover.jpg
+        /app/data/abc.mp3            → /volume1/docker/webpage/data/music/abc.mp3
+    """
+    nas_videos_root = os.getenv("NAS_VIDEOS_ROOT", "/volume1/docker/webpage/data/videos")
+    nas_music_root  = os.getenv("NAS_MUSIC_ROOT",  "/volume1/docker/webpage/data/music")
+    if container_path.startswith("/app/data/videos/"):
+        return container_path.replace("/app/data/videos/", nas_videos_root + "/", 1)
+    if container_path.startswith("/app/data/"):
+        # 음악 파일 마운트가 /app/data 직접이라 서브디렉토리 없음 → music root에 직접
+        rel = container_path[len("/app/data/"):]
+        return nas_music_root + "/" + rel
+    return container_path  # fallback (shouldn't happen)
+```
+
+### 5-3. 제거 항목
+
+- `subprocess.run(...)` ffmpeg 호출 — 완전 제거
+- `VIDEO_TIMEOUT_S = 600` — 사용 안 함 (`ENCODER_TIMEOUT_S`로 대체)
+- `_build_visualizer_cmd` — 제거 (Windows 서버로 이전)
+- `subprocess.TimeoutExpired` 예외 처리 — 제거
+
+### 5-4. 환경변수 (NAS music-lab)
+
+```yaml
+# docker-compose.yml music-lab service environment
+WINDOWS_VIDEO_ENCODER_URL: ${WINDOWS_VIDEO_ENCODER_URL}
+NAS_VIDEOS_ROOT: ${NAS_VIDEOS_ROOT:-/volume1/docker/webpage/data/videos}
+NAS_MUSIC_ROOT:  ${NAS_MUSIC_ROOT:-/volume1/docker/webpage/data/music}
+```
+
+NAS `.env` 추가:
+```env
+WINDOWS_VIDEO_ENCODER_URL=http://192.168.45.59:8765
+```
+
+---
+
+## 6. 에러 응답 매트릭스
+
+| 상황 | NAS 측 결과 | 사용자 경험 |
+|------|------------|-------------|
+| Windows PC 꺼짐 | `VideoGenerationError("연결 실패")` | 진행 카드 `failed`, 텔레그램에 명확한 에러 |
+| Windows ffmpeg 실패 | `VideoGenerationError("Windows 인코더 오류 500: ffmpeg — ...")` | 동일 |
+| 입력 파일 NAS에 없음 | Windows가 400 응답 | "input_validation: cover not found" 메시지 |
+| 출력 파일이 비어있음 | Windows가 500 응답 | "output_check: file empty" |
+| 타임아웃 (180s+) | Windows가 504 응답 또는 connection close | "타임아웃 — GPU 부하 또는 입력 손상" |
+| WINDOWS_VIDEO_ENCODER_URL 미설정 | 즉시 `VideoGenerationError` | 환경 미설정 안내 |
+
+모두 pipeline state `failed`로 전이. 재생성 5회 한도 적용.
+
+---
+
+## 7. 헬스 모니터링
+
+NAS music-lab 시작 시 1회 `GET {ENCODER_URL}/health` 호출 → 결과를 로그에 출력:
+- 성공 + `ffmpeg_nvenc=true` → 인코더 사용 가능
+- 실패 → 경고 로그 (구동은 계속, 호출 시점에 명확한 에러)
+
+---
+
+## 8. 테스트 전략
+
+### 8-1. NAS music-lab 단위 테스트
+
+`music-lab/tests/test_video_thumb.py` — 기존 ffmpeg 테스트를 HTTP mock 기반으로 교체:
+
+```python
+@respx.mock
+def test_generate_video_calls_remote_encoder(monkeypatch):
+    monkeypatch.setenv("WINDOWS_VIDEO_ENCODER_URL", "http://192.168.45.59:8765")
+    monkeypatch.setattr(video, "ENCODER_URL", "http://192.168.45.59:8765")
+    respx.post("http://192.168.45.59:8765/encode_video").mock(
+        return_value=Response(200, json={
+            "ok": True, "duration_ms": 12000,
+            "output_path_nas": "/volume1/...",
+            "encoder": "h264_nvenc", "preset": "p4"
+        })
+    )
+    out = video.generate(...)
+    assert out["url"].endswith("/video.mp4")
+    assert out["encode_duration_ms"] == 12000
+
+
+@respx.mock
+def test_generate_video_raises_on_connection_error(monkeypatch):
+    monkeypatch.setattr(video, "ENCODER_URL", "http://192.168.45.59:8765")
+    respx.post("http://192.168.45.59:8765/encode_video").mock(
+        side_effect=httpx.ConnectError("Connection refused")
+    )
+    with pytest.raises(video.VideoGenerationError) as exc:
+        video.generate(...)
+    assert "연결 실패" in str(exc.value)
+
+
+def test_generate_video_no_url_configured(monkeypatch):
+    monkeypatch.setattr(video, "ENCODER_URL", "")
+    with pytest.raises(video.VideoGenerationError) as exc:
+        video.generate(...)
+    assert "WINDOWS_VIDEO_ENCODER_URL" in str(exc.value)
+```
+
+기존 `test_generate_video_calls_ffmpeg` / `test_generate_video_failure_marks_failed` 제거.
+
+### 8-2. Windows `music_ai` 단위 테스트
+
+`music_ai/tests/test_video_encoder.py` (신규):
+
+```python
+@patch("subprocess.run")
+def test_translate_path():
+    assert video_encoder.translate_path("/volume1/docker/webpage/data/x.jpg") == r"Z:\docker\webpage\data\x.jpg"
+
+def test_translate_path_rejects_bad_prefix():
+    with pytest.raises(ValueError):
+        video_encoder.translate_path("/something/else/x.jpg")
+
+@patch("subprocess.run")
+def test_encode_endpoint_success(mock_run, client, tmp_path):
+    # mock paths exist + ffmpeg succeeds
+    ...
+
+@patch("subprocess.run")  
+def test_encode_endpoint_input_missing(mock_run, client):
+    # 입력 파일 안 보이면 400
+    ...
+
+@patch("subprocess.run")
+def test_encode_endpoint_ffmpeg_fails(mock_run, client, tmp_path):
+    # ffmpeg returncode=1 → 500 stage=ffmpeg
+    ...
+```
+
+### 8-3. 통합 테스트
+
+기존 `test_pipeline_flow.py`는 `cover.generate`를 mock하므로 영향 없음. video도 같이 mock — 변경 없음.
+
+### 8-4. 수동 E2E
+
+- [ ] Windows PC에서 `music_ai` 서버 시작 → `curl http://192.168.45.59:8765/health` → `ffmpeg_nvenc: true` 확인
+- [ ] NAS에서 `curl -X POST http://192.168.45.59:8765/encode_video -d '{...}'` 직접 호출 → 200 응답 + Z:\에 video.mp4 생성 확인
+- [ ] 진행 탭에서 새 파이프라인 시작 → 영상 단계가 10–20초 안에 완료 → 텔레그램 알림 도착
+- [ ] Windows PC 꺼두고 새 파이프라인 시작 → 영상 단계 즉시 실패 → 진행 카드 failed + 명확한 에러 메시지
+
+---
+
+## 9. Windows PC 사전 준비
+
+사용자가 Windows PC에서 1회 수행할 작업:
+
+1. **ffmpeg + NVENC 빌드 설치**
+   - https://www.gyan.dev/ffmpeg/builds/ → "release full" 다운로드
+   - 압축 해제 → `C:\ffmpeg\bin\ffmpeg.exe`
+   - PATH 환경변수에 `C:\ffmpeg\bin` 추가
+   - 검증: `ffmpeg -version` 동작, `ffmpeg -encoders | findstr h264_nvenc` 결과 출력
+
+2. **NVIDIA 드라이버** — 이미 MusicGen용으로 설치돼 있음
+
+3. **SMB 마운트 확인** — `Z:\docker\webpage\` 접근 가능해야 함
+
+4. **방화벽** — 포트 8765 LAN 인바운드 허용 (이미 MusicGen용으로 설정돼 있음)
+
+5. **`music_ai/.env`에 추가**:
+   ```env
+   NAS_VOLUME_PREFIX=/volume1/
+   WINDOWS_DRIVE_ROOT=Z:\
+   FFMPEG_PATH=C:\ffmpeg\bin\ffmpeg.exe
+   ```
+
+6. **`music_ai/start.bat` 재시작** — 새 endpoint 활성화
+
+---
+
+## 10. 산출물
+
+| 영역 | 파일 |
+|------|------|
+| Windows | `music_ai/video_encoder.py` (신규) |
+| Windows | `music_ai/server.py` (수정 — `/encode_video` endpoint 등록, `/health` 확장) |
+| Windows | `music_ai/.env.example` (수정 — 새 변수 문서화) |
+| Windows | `music_ai/tests/test_video_encoder.py` (신규) |
+| NAS | `music-lab/app/pipeline/video.py` (재작성) |
+| NAS | `music-lab/tests/test_video_thumb.py` (수정 — HTTP mock 기반) |
+| Infra | `web-backend/docker-compose.yml` (env 3개 추가) |
+| Infra | NAS `.env` (사용자 수동, 1개 추가) |
+
+---
+
+## 11. 후속
+
+- (P3) 영상 인코딩 진행률 실시간 보고 — Windows에서 ffmpeg progress 파싱 후 진행 탭 카드에 표시 (현재는 단순 "running")
+- (P3) Windows 서버 다중 큐 — 동시 요청 시 GPU 부하 추적 + 큐잉
+- (P4) 인코딩 옵션을 youtube_setup `visual_defaults`로 추가 — preset(p1~p7), CQ, 해상도 옵션 노출
+- (P4) Shorts 전용 1080×1920 인코딩 프로파일
+
+---
+## 11. 후속
+
+- (P3) 영상 인코딩 진행률 실시간 보고 — Windows에서 ffmpeg progress 파싱 후 진행 탭 카드에 표시 (현재는 단순 "running")
+- (P3) Windows 서버 다중 큐 — 동시 요청 시 GPU 부하 추적 + 큐잉
+- (P4) 인코딩 옵션을 youtube_setup `visual_defaults`로 추가 — preset(p1~p7), CQ, 해상도 옵션 노출
+- (P4) Shorts 전용 1080×1920 인코딩 프로파일
+
+---

docs/superpowers/specs/2026-05-10-batch-music-generation-design.md

@@ -0,0 +1,505 @@
+# 배치 음악 생성 + 자동 영상 파이프라인 설계
+
+> 작성일: 2026-05-10
+> 관련: `2026-05-09-essential-mix-pipeline-design.md` (영상 파이프라인 베이스)
+
+---
+
+## 1. 배경
+
+현재 Create 탭은 사용자가 모든 파라미터(genre/mood/instruments/BPM/key/scale/duration/prompt) 수동 입력 후 1트랙 생성. 1시간+ mix 영상 만들려면 동일 장르 트랙 10개를 일일이 만들어야 함.
+
+목표: **장르 1개만 입력 → 10트랙 자동 생성 → 자동 컴파일 → 자동 영상 파이프라인 시작 → 텔레그램 승인만 하면 발행 완료**.
+
+전체 흐름:
+```
+[사용자] Create 탭 → 배치 모드 → 장르 + 트랙 수 선택 → 생성 시작
+   ↓ Suno API 순차 호출 (트랙당 ~1-2분)
+   ↓ Track 1: "{Genre} Mix Track 1", 랜덤 mood/instr/BPM/key
+   ↓ Track 2: "{Genre} Mix Track 2", ...
+   ↓ ... Track 10
+   ↓ 모두 완료 → compile_job 자동 생성 (acrossfade 3s)
+   ↓ compile 완료 → video_pipeline 자동 시작 (cover step)
+   ↓ 텔레그램에 "🎵 [{Genre} Mix] 커버 검토" 알림
+[사용자] 5번 승인으로 영상 발행
+```
+
+---
+
+## 2. 비목표
+
+- 병렬 음악 생성 — VRAM 부담 회피, 순차로 단순하게
+- 트랙별 prompt 자동 작성(Claude) — Suno는 genre+mood+instruments만으로도 충분
+- 트랙별 길이 가변 — 모든 트랙 동일 `target_duration_sec` (default 180s)
+- 사용자가 진행 중 트랙 prompt 편집 — 한 번 시작하면 끝까지
+
+---
+
+## 3. 사용자 흐름
+
+### 3-1. Create 탭의 신규 "배치 생성" 섹션
+
+```
+┌─ 🎲 배치 생성 (장르 + 자동 영상까지) ─────────────────┐
+│                                                       │
+│  장르         [▼ lo-fi                            ]   │
+│  트랙 수      [● 1 — 10] (10)                         │
+│  트랙당 길이  [● 60 — 300s] (180s)                    │
+│  ☑ 모든 트랙 생성 후 자동 영상 파이프라인 시작          │
+│                                                       │
+│  예상 시간: 약 15-25분 (트랙당 1-2분 × 10)             │
+│  예상 비용: ~$0.10 (Suno 10트랙 + DALL·E + Claude)    │
+│                                                       │
+│  [🎵 배치 생성 시작]                                   │
+│                                                       │
+│  ── 진행 상태 ──────────────────────────────────────  │
+│  배치 #3 — lo-fi · 7/10 완료 · 2:43 경과              │
+│  ✓ Track 1: Lo-Fi Mix Track 1 (chill, piano+synth)    │
+│  ✓ Track 2: Lo-Fi Mix Track 2 (relaxing, piano+drums) │
+│  ...                                                   │
+│  ⏳ Track 8: 생성 중...                                │
+│  ○ Track 9: 대기                                       │
+│  ○ Track 10: 대기                                      │
+└──────────────────────────────────────────────────────┘
+```
+
+### 3-2. 완료 후
+
+10트랙 모두 Library에 저장됨. compile_job_id가 자동 생성되고 영상 파이프라인이 cover step부터 시작 → 텔레그램 알림. 진행 탭에 카드 1장 추가.
+
+---
+
+## 4. 데이터 모델
+
+### 4-1. 신규 테이블 `music_batch_jobs`
+
+```sql
+CREATE TABLE music_batch_jobs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    genre TEXT NOT NULL,
+    count INTEGER NOT NULL,                       -- 1-10
+    target_duration_sec INTEGER NOT NULL DEFAULT 180,
+    auto_pipeline INTEGER NOT NULL DEFAULT 1,     -- 0/1 boolean
+    completed INTEGER NOT NULL DEFAULT 0,
+    track_ids_json TEXT NOT NULL DEFAULT '[]',
+    current_track_index INTEGER NOT NULL DEFAULT 0,  -- 진행 중 트랙 (1..count)
+    current_track_status TEXT,                     -- queued | generating | failed
+    status TEXT NOT NULL DEFAULT 'queued',
+        -- queued: 시작 전
+        -- generating: 트랙 생성 중
+        -- generated: 모든 트랙 생성 완료 (compile 시작 전)
+        -- compiling: compile 진행 중
+        -- piped: 영상 파이프라인 시작됨 (=cover_pending 상태)
+        -- failed: 어느 단계에서 실패
+        -- cancelled: 사용자 취소
+    error TEXT,
+    compile_job_id INTEGER,
+    pipeline_id INTEGER,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+```
+
+`init_db()`에 `CREATE TABLE IF NOT EXISTS` 추가.
+
+### 4-2. 헬퍼 함수 (`db.py` 추가)
+
+- `create_batch_job(genre, count, target_duration_sec, auto_pipeline) -> int`
+- `get_batch_job(id) -> dict | None`
+- `update_batch_job(id, **fields)` — allowlist 검증
+- `list_batch_jobs(active_only=False) -> list[dict]`
+- `append_batch_track(batch_id, track_id)` — 완료된 트랙 ID 추가, completed++ 
+
+---
+
+## 5. 백엔드 — 랜덤 풀 + 배치 실행
+
+### 5-1. `app/random_pools.py` (신규)
+
+장르별 음악적으로 어울리는 랜덤 풀 정의:
+
+```python
+"""장르별 음악 파라미터 랜덤 풀."""
+import random
+
+POOLS = {
+    "lo-fi": {
+        "moods": ["chill", "relaxing", "dreamy", "melancholic", "mellow", "nostalgic", "peaceful"],
+        "instruments_pool": ["piano", "synth", "drums", "vinyl", "rhodes", "soft bass", "ambient pads"],
+        "instruments_count": (3, 4),
+        "bpm": (70, 90),
+        "keys": ["C", "D", "F", "G", "A"],
+        "scales": ["minor", "major"],
+        "prompt_modifiers": ["cozy bedroom vibes", "rainy night", "late night study", "cafe ambience"],
+    },
+    "phonk": {
+        "moods": ["dark", "aggressive", "moody", "intense", "hypnotic"],
+        "instruments_pool": ["808 bass", "hi-hat", "synth lead", "vocal chops", "bass drops", "trap drums"],
+        "instruments_count": (3, 4),
+        "bpm": (130, 160),
+        "keys": ["C", "D", "F", "G"],
+        "scales": ["minor"],
+        "prompt_modifiers": ["drift atmosphere", "dark neon", "midnight drive"],
+    },
+    "ambient": {
+        "moods": ["peaceful", "meditative", "ethereal", "spacious", "dreamy"],
+        "instruments_pool": ["pad synths", "atmospheric guitar", "soft strings", "field recordings", "drone bass"],
+        "instruments_count": (2, 3),
+        "bpm": (50, 75),
+        "keys": ["C", "D", "E", "G", "A"],
+        "scales": ["major", "minor"],
+        "prompt_modifiers": ["misty mountain morning", "deep space", "still water", "forest dawn"],
+    },
+    "pop": {
+        "moods": ["uplifting", "happy", "energetic", "romantic", "catchy"],
+        "instruments_pool": ["acoustic guitar", "piano", "drums", "bass", "synth", "vocals harmonies"],
+        "instruments_count": (3, 5),
+        "bpm": (95, 130),
+        "keys": ["C", "D", "E", "F", "G", "A"],
+        "scales": ["major"],
+        "prompt_modifiers": ["radio-ready", "summer vibe", "feel-good"],
+    },
+    "default": {  # 알 수 없는 장르 fallback
+        "moods": ["chill", "relaxing", "uplifting", "mellow"],
+        "instruments_pool": ["piano", "synth", "drums", "guitar", "bass", "strings"],
+        "instruments_count": (3, 4),
+        "bpm": (80, 110),
+        "keys": ["C", "D", "F", "G", "A"],
+        "scales": ["minor", "major"],
+        "prompt_modifiers": [""],
+    },
+}
+
+
+def randomize(genre: str, rng: random.Random | None = None) -> dict:
+    """랜덤 음악 파라미터 1세트 생성."""
+    rng = rng or random.Random()
+    pool = POOLS.get(genre.lower(), POOLS["default"])
+    n_instr = rng.randint(*pool["instruments_count"])
+    instruments = rng.sample(pool["instruments_pool"], min(n_instr, len(pool["instruments_pool"])))
+    return {
+        "moods": [rng.choice(pool["moods"])],
+        "instruments": instruments,
+        "bpm": rng.randint(*pool["bpm"]),
+        "key": rng.choice(pool["keys"]),
+        "scale": rng.choice(pool["scales"]),
+        "prompt_modifier": rng.choice(pool["prompt_modifiers"]),
+    }
+```
+
+향후(P3): 장르별 풀을 `youtube_setup`/별도 테이블로 옮겨 SetupTab에서 편집 가능하게.
+
+### 5-2. `app/batch_generator.py` (신규) — 순차 실행 오케스트레이터
+
+```python
+"""배치 음악 생성 + 자동 컴파일·영상 파이프라인."""
+import asyncio
+import logging
+import json
+
+from . import db
+from .suno_provider import run_suno_generation
+from .random_pools import randomize
+
+logger = logging.getLogger("music-lab.batch")
+
+POLL_INTERVAL_S = 5
+TRACK_GEN_TIMEOUT_S = 240  # 트랙당 최대 4분
+
+
+async def run_batch(batch_id: int) -> None:
+    """1) genre로 N트랙 순차 Suno 생성
+       2) 모두 완료 후 compile_job 자동 생성·실행
+       3) compile 완료 후 영상 파이프라인 시작 (cover step)
+    """
+    job = db.get_batch_job(batch_id)
+    if not job:
+        return
+    genre = job["genre"]
+    count = job["count"]
+    duration = job["target_duration_sec"]
+    auto_pipe = bool(job["auto_pipeline"])
+
+    db.update_batch_job(batch_id, status="generating")
+
+    track_ids: list[int] = []
+    for i in range(1, count + 1):
+        title = f"{genre.title()} Mix Track {i}"
+        params = randomize(genre)
+
+        db.update_batch_job(batch_id,
+                            current_track_index=i,
+                            current_track_status="generating")
+
+        # Suno 호출 (기존 task 패턴 활용)
+        task_id = _start_suno(title=title, genre=genre,
+                               duration_sec=duration, **params)
+        track_id = await _wait_for_track(task_id, timeout=TRACK_GEN_TIMEOUT_S)
+
+        if track_id:
+            track_ids.append(track_id)
+            db.append_batch_track(batch_id, track_id)
+        else:
+            logger.warning("배치 %d 트랙 %d 실패 — 계속 진행", batch_id, i)
+            db.update_batch_job(batch_id, current_track_status="failed")
+            # 정책: 실패한 트랙은 skip하고 계속 (나머지 9개라도 만든다)
+
+    if not track_ids:
+        db.update_batch_job(batch_id, status="failed",
+                            error="모든 트랙 생성 실패")
+        return
+
+    db.update_batch_job(batch_id, status="generated")
+
+    if not auto_pipe:
+        return  # 음악만 만들고 종료
+
+    # === 자동 compile ===
+    db.update_batch_job(batch_id, status="compiling")
+    compile_id = db.create_compile_job(
+        title=f"{genre.title()} Mix",
+        track_ids=track_ids,
+        crossfade_sec=3,
+    )
+    db.update_batch_job(batch_id, compile_job_id=compile_id)
+
+    # 기존 compiler 호출 (동기 → asyncio.to_thread)
+    from . import compiler
+    await asyncio.to_thread(compiler.run, compile_id)
+
+    job_after = db.get_compile_job(compile_id)
+    if not job_after or job_after.get("status") not in ("done", "succeeded"):
+        db.update_batch_job(batch_id, status="failed",
+                            error=f"compile 실패 (status={job_after.get('status') if job_after else 'unknown'})")
+        return
+
+    # === 자동 영상 파이프라인 ===
+    pipeline_id = db.create_pipeline(compile_job_id=compile_id)
+    db.update_batch_job(batch_id, pipeline_id=pipeline_id, status="piped")
+
+    from .pipeline import orchestrator
+    await orchestrator.run_step(pipeline_id, "cover")
+```
+
+- `_start_suno(...)` — 기존 `run_suno_generation` 호출, task_id 반환
+- `_wait_for_track(task_id, timeout)` — task 완료 폴링, 성공 시 music_library의 새 track id 반환
+
+### 5-3. 변경되는 기존 모듈
+
+`app/main.py`에 신규 endpoint 3개 + BackgroundTask. 변경 없는 기존 endpoint들은 그대로.
+
+`db.py`에 헬퍼 함수 5개 추가 + `init_db()`에 `music_batch_jobs` CREATE 추가.
+
+---
+
+## 6. API 엔드포인트
+
+### 6-1. `POST /api/music/generate-batch`
+
+Request:
+```json
+{
+  "genre": "lo-fi",
+  "count": 10,
+  "target_duration_sec": 180,
+  "auto_pipeline": true
+}
+```
+
+Validation:
+- `count` 1-10
+- `target_duration_sec` 60-300
+- `genre` 필수
+
+Response 201:
+```json
+{
+  "id": 3,
+  "status": "queued",
+  ...
+}
+```
+
+배치 작업은 BackgroundTask로 실행 (~15-25분 소요).
+
+### 6-2. `GET /api/music/generate-batch/{id}`
+
+진행 상태 조회. 응답 예:
+```json
+{
+  "id": 3,
+  "genre": "lo-fi",
+  "count": 10,
+  "completed": 7,
+  "current_track_index": 8,
+  "current_track_status": "generating",
+  "status": "generating",
+  "track_ids": [12, 13, 14, 15, 16, 17, 18],
+  "tracks": [
+    {"id": 12, "title": "Lo-Fi Mix Track 1", ...},
+    ...
+  ],
+  "compile_job_id": null,
+  "pipeline_id": null,
+  "created_at": "2026-05-10T17:00:00",
+  "updated_at": "2026-05-10T17:08:30"
+}
+```
+
+`tracks` 필드는 LEFT JOIN으로 채워짐 (각 트랙 메타 포함).
+
+### 6-3. `GET /api/music/generate-batch?status=active`
+
+전체 배치 목록. `active`면 queued/generating/compiling/piped 만.
+
+---
+
+## 7. 프론트엔드 — Create 탭 배치 섹션
+
+### 7-1. `MusicStudio.jsx` Create 영역에 신규 collapsible
+
+Create form 위 또는 옆에 새 섹션 (`<details>` 또는 토글):
+
+```jsx
+<details className="ms-batch-section" open={batchOpen}>
+    <summary onClick={...}>🎲 배치 생성 (1-10트랙 + 자동 영상)</summary>
+
+    <div className="ms-batch-form">
+        <label>장르
+            <select value={batchGenre} onChange={...}>
+                <option value="lo-fi">Lo-Fi</option>
+                <option value="phonk">Phonk</option>
+                <option value="ambient">Ambient</option>
+                <option value="pop">Pop</option>
+            </select>
+        </label>
+
+        <label>트랙 수: {batchCount}
+            <input type="range" min={1} max={10} value={batchCount} onChange={...}/>
+        </label>
+
+        <label>트랙당 길이: {batchDuration}초
+            <input type="range" min={60} max={300} step={10} value={batchDuration} onChange={...}/>
+        </label>
+
+        <label>
+            <input type="checkbox" checked={autoPipeline} onChange={...}/>
+            모든 트랙 생성 후 자동 영상 파이프라인 시작
+        </label>
+
+        <p className="ms-batch-estimate">
+            예상: 약 {batchCount * 1.5 | 0}-{batchCount * 2}분 · 비용 ~${(batchCount * 0.005 + (autoPipeline ? 0.05 : 0)).toFixed(2)}
+        </p>
+
+        <button className="button primary" onClick={startBatch} disabled={generating}>
+            🎵 배치 생성 시작
+        </button>
+    </div>
+
+    {currentBatch && <BatchProgress batch={currentBatch} />}
+</details>
+```
+
+### 7-2. 신규 컴포넌트 `BatchProgress.jsx`
+
+```jsx
+export default function BatchProgress({ batch }) {
+    return (
+        <div className="ms-batch-progress">
+            <div className="ms-batch-header">
+                배치 #{batch.id} — {batch.genre} ·
+                {' '}{batch.completed}/{batch.count} 완료 ·
+                {' '}status: <strong>{batch.status}</strong>
+            </div>
+            <ol className="ms-batch-tracks">
+                {Array.from({ length: batch.count }, (_, i) => i + 1).map(n => {
+                    const completed = n <= batch.completed;
+                    const current = n === batch.current_track_index && batch.status === 'generating';
+                    const track = (batch.tracks || []).find(t => t._batch_index === n);
+                    return (
+                        <li key={n} className={completed ? 'done' : current ? 'current' : 'pending'}>
+                            {completed ? '✓' : current ? '⏳' : '○'}
+                            {' '}Track {n}: {track ? track.title : (current ? '생성 중...' : '대기')}
+                        </li>
+                    );
+                })}
+            </ol>
+            {batch.compile_job_id && <div>📀 컴파일 #{batch.compile_job_id}</div>}
+            {batch.pipeline_id && (
+                <div>
+                    🎬 영상 파이프라인 #{batch.pipeline_id} —
+                    <a href={`#youtube-pipeline-${batch.pipeline_id}`}> 진행 탭에서 확인</a>
+                </div>
+            )}
+        </div>
+    );
+}
+```
+
+### 7-3. 폴링
+
+배치 시작 시 5초 간격 `getBatchJob(id)` 호출. status가 `piped`/`failed`/`cancelled`되면 폴링 중지.
+
+### 7-4. `api.js` 헬퍼
+
+```javascript
+export const startBatchGen   = (payload) => apiPost('/api/music/generate-batch', payload);
+export const getBatchJob     = (id)      => apiGet(`/api/music/generate-batch/${id}`);
+export const listBatchJobs   = (status='all') => apiGet(`/api/music/generate-batch?status=${status}`);
+```
+
+---
+
+## 8. 에러 처리
+
+| 시나리오 | 동작 |
+|---------|------|
+| Suno API 트랙 1개 실패 | 로그 + skip + 다음 트랙 진행. 최종 track_ids에 누락. |
+| 모든 트랙 실패 | status=failed, error 기록 |
+| compile 실패 | status=failed, compile_job_id 보존 |
+| 영상 파이프라인 cover step 실패 | pipeline 자체에서 failed로 마크. batch는 piped 상태 그대로 (파이프라인 측에서 처리) |
+| count > 10 또는 < 1 | 400 |
+| genre 누락 | 400 |
+| Suno API key 미설정 | 400 ("SUNO_API_KEY 미설정") |
+
+---
+
+## 9. 테스트 전략
+
+### 9-1. 단위 테스트
+
+- `random_pools.randomize(genre)` — 각 장르별 결과가 풀 안에 있는지, 시드 고정 시 재현 가능
+- `db.create_batch_job` / `update_batch_job` / `append_batch_track` — 정상 흐름
+- `_wait_for_track` — task 성공/실패/timeout mock
+
+### 9-2. 통합 테스트
+
+- `POST /api/music/generate-batch` 호출 → 201 반환 + 배치 row 생성
+- `GET /api/music/generate-batch/{id}` 응답 schema
+- `run_batch` mocked Suno + mocked compiler + mocked orchestrator → 전체 흐름 happy path
+
+### 9-3. 수동 E2E
+
+- Create 탭 → 배치 생성 → 장르 선택 → 시작 → 진행 표시 확인
+- 10트랙 완료 → Library에 10개 추가 확인 → compile_job 자동 생성 확인 → 진행 탭에 새 카드 등장 확인
+
+---
+
+## 10. 산출물
+
+| 영역 | 파일 |
+|------|------|
+| Spec/Plan | 본 문서 + plan |
+| NAS music-lab | `db.py` (테이블/헬퍼), `random_pools.py` (신규), `batch_generator.py` (신규), `main.py` (3 endpoints) |
+| Frontend | `MusicStudio.jsx` (Create 배치 섹션), `BatchProgress.jsx` (신규), `MusicStudio.css`, `api.js` 헬퍼 |
+| 테스트 | NAS 단위 + 통합, 수동 E2E |
+
+---
+
+## 11. 후속 (P3)
+
+- 장르별 풀 SetupTab에서 편집 가능
+- 트랙별 prompt에 시나리오/카페 분위기 등 자동 추가 (트랙간 다양성 증대)
+- 배치 일시정지/재개
+- 한 배치 안에서 Track-N별 재생성 (실패한 트랙만)
+- 트랙 길이 가변 (랜덤 분포)

docs/superpowers/specs/2026-05-15-insta-agent-design.md

@@ -0,0 +1,358 @@
+# insta-agent 설계 — blog-lab 폐기, 인스타 카드 피드 파이프라인 신설
+
+작성일: 2026-05-15
+상태: 사용자 승인 대기 → writing-plans 진입 예정
+
+---
+
+## 1. 목적·배경
+
+기존 `blog-lab` 서비스(네이버 블로그 마케팅 수익화)를 폐기하고, 인스타그램 프로페셔널 계정에 올릴 카드 형식 피드(1080×1350, 10페이지)를 자동 생산하는 `insta-lab` 서비스로 대체한다.
+
+핵심 가치 제안:
+- 매일 경제·심리학·연예 등 카테고리에서 화제 키워드를 자동 발견
+- 사용자가 키워드 1개를 선택하면 10페이지 카드 카피 + PNG 자동 생성
+- 텔레그램으로 카드 묶음 미디어 그룹 + 추천 캡션·해시태그 푸시
+- 사용자는 카드 다운로드 → 인스타 수동 업로드 (Graph API 미사용)
+
+블로그 발행 자동화의 운영 부담(네이버 SEO, 브랜드커넥트 링크 관리, 커미션 추적)을 제거하고 카드 콘텐츠 생산에 집중한다.
+
+---
+
+## 2. 스코프
+
+### 포함
+
+- 신규 컨테이너 `insta-lab` (포트 18700 재활용)
+- 신규 에이전트 `insta-agent` (`agent-office/app/agents/insta.py`)
+- 뉴스 수집 → 키워드 추출 → 카드 카피 생성 → 카드 PNG 렌더 → 텔레그램 푸시 파이프라인
+- HTML/CSS 카드 템플릿 골격 (사용자가 디자인 직접 수정)
+- 카드 슬레이트·기사·키워드·자산 5테이블 (`insta.db`)
+- nginx 라우팅 변경 (`/api/blog-marketing/` 제거 → `/api/insta/`)
+- CLAUDE.md (workspace + web-backend) 갱신
+
+### 제외
+
+- 인스타그램 Graph API 자동 발행 (수동 업로드 사용)
+- 카드 디자인 비주얼 완성 (사용자가 직접 작업)
+- blog_marketing.db 데이터 마이그레이션 (clean slate)
+- 다국어 번역, A/B 테스트, 성과 추적
+
+---
+
+## 3. 서비스 구성·폐기 범위
+
+### 폐기
+
+| 대상 | 처리 |
+|------|------|
+| `blog-lab/` 디렉토리 | git rm 통째로 삭제 |
+| `blog_marketing.db` | 운영·로컬 모두 삭제 (clean slate) |
+| `agent-office/app/agents/blog.py` | 삭제 |
+| `service_proxy.py`의 blog_* 함수 | 삭제 |
+| `agent-office`의 blog 라우팅·텔레그램 명령 | 삭제 |
+| docker-compose의 `blog-lab` 서비스 정의 | 교체 |
+| nginx의 `/api/blog-marketing/` location | 교체 |
+| 환경변수 `BLOG_DATA_PATH` | 제거 |
+
+### 신규
+
+| 대상 | 비고 |
+|------|------|
+| `insta-lab/` 디렉토리 | 신규 생성 |
+| `insta-lab` 컨테이너 (포트 18700) | blog-lab 자리 재활용 |
+| `agents/insta.py` | 신규 에이전트 |
+| nginx `/api/insta/` → `insta-lab:8000` | 신규 |
+| 환경변수 `INSTA_DATA_PATH`, `CARD_TEMPLATE_DIR` | 신규 |
+
+### 재사용 자산 (코드 패턴 차용)
+
+- `naver_search.py` — 엔드포인트만 `news.json`으로 교체
+- `generation_tasks` 테이블 + BackgroundTask 폴링 패턴
+- `prompt_templates` 테이블 + DB 저장 프롬프트 패턴
+- agent-office의 텔레그램 인라인 키보드·승인 패턴 (`realestate_message.py` 참고)
+
+---
+
+## 4. 데이터 흐름
+
+### 일일 사이클
+
+```
+[09:30 매일 cron — agent-office 스케줄러]
+1. 뉴스 수집     ─ 카테고리별 시드 키워드로 NAVER news.json 검색
+                  ─ 카테고리당 상위 30건 메타 + 본문 일부 → news_articles
+2. 키워드 추출   ─ 카테고리당 빈도 상위 + Claude Haiku 정제
+                  ─ trending_keywords (score 내림차순)
+3. 텔레그램 푸시 ─ 카테고리별 후보 5개씩 인라인 키보드
+                  ─ 사용자 선택 대기
+
+[사용자가 텔레그램 인라인 버튼 선택]
+4. 카피 생성    ─ Claude로 10페이지 카피 (1=훅/커버, 2~9=본문 8장, 10=요약/CTA)
+                 ─ card_slates 저장 (status='draft')
+5. 카드 렌더    ─ Jinja → HTML 1080×1350 → Playwright headless 스크린샷 10장
+                 ─ /app/data/insta_cards/{slate_id}/01.png ~ 10.png
+6. 텔레그램     ─ 미디어 그룹 10장 + 추천 캡션·해시태그
+                 ─ 사용자 다운로드 후 인스타 수동 업로드
+```
+
+### 자동 모드 (옵션)
+
+- agent-office의 `agent_config.custom_config.auto_select`(bool) 플래그로 제어
+- `auto_select=true` 설정 시 키워드 추출 직후 카테고리당 score 1위 키워드를 자동 선택해 4~6 단계까지 즉시 진행
+- 사용자가 텔레그램에서 결과만 확인 (인라인 후보 푸시 단계 skip)
+
+---
+
+## 5. 컴포넌트
+
+### insta-lab (FastAPI 서비스)
+
+```
+insta-lab/
+├── Dockerfile               # python:3.12-slim + playwright install chromium --with-deps
+├── requirements.txt
+├── pytest.ini
+├── tests/
+└── app/
+    ├── main.py              # FastAPI 라우터
+    ├── config.py            # NAVER_*, ANTHROPIC_API_KEY, INSTA_DATA_PATH, CARD_TEMPLATE_DIR
+    ├── db.py                # 6테이블 init + CRUD
+    ├── news_collector.py    # 네이버 뉴스 API + 본문 정리
+    ├── keyword_extractor.py # 빈도 + LLM 정제
+    ├── card_writer.py       # Claude 10페이지 카피 생성
+    ├── card_renderer.py     # Jinja → Playwright 스크린샷
+    └── templates/           # 사용자가 직접 수정 (rsync로 NAS 배포)
+        └── default/
+            └── card.html.j2
+```
+
+### agent-office 변경
+
+```
+agent-office/app/agents/insta.py  (신규)
+  - on_schedule: 09:30 → news collect → keyword extract → 텔레그램 후보 푸시
+  - on_command:  extract / render <keyword> / list_categories
+  - on_callback: 텔레그램 inline button "render_<keyword_id>" → 카피·렌더·푸시
+
+agent-office/app/service_proxy.py
+  - blog_* 함수 모두 제거
+  - insta_* 함수 신규 (collect, extract, list_keywords, create_slate, render_slate, get_slate, get_asset)
+
+agent-office/app/telegram/agent_registry.py
+  - blog 명령 등록 제거 → insta 명령 등록
+```
+
+---
+
+## 6. DB 스키마 (insta.db)
+
+| 테이블 | 핵심 컬럼 | 설명 |
+|--------|----------|------|
+| `news_articles` | id PK, category, title, link UNIQUE, summary, pub_date, fetched_at | 일일 수집 기사 메타 |
+| `trending_keywords` | id PK, keyword, category, score REAL, articles_count, suggested_at, used INTEGER | 카테고리별 화제 키워드 (used=1이면 이미 슬레이트 생성됨) |
+| `card_slates` | id PK, keyword, category, status (draft/rendered/sent/failed), cover_copy TEXT, body_copies TEXT(JSON 8개), cta_copy TEXT, suggested_caption TEXT, hashtags TEXT(JSON), created_at | 10페이지 카피 묶음 |
+| `card_assets` | id PK, slate_id FK→card_slates(id), page_index INTEGER 1~10, file_path, file_hash, created_at | 렌더된 PNG 자산 |
+| `generation_tasks` | id TEXT PK, type, status, progress, message, result_id INTEGER, error TEXT, params TEXT, created_at, updated_at | blog-lab 패턴 그대로 (collect/extract/write/render 통합) |
+| `prompt_templates` | id PK, name UNIQUE, description, template TEXT, updated_at | `slate_writer`, `keyword_extractor` 두 개 시드 |
+
+**인덱스**:
+- `idx_na_category_fetched` ON news_articles(category, fetched_at DESC)
+- `idx_tk_score` ON trending_keywords(category, score DESC)
+- `idx_cs_created` ON card_slates(created_at DESC)
+- `idx_ca_slate` ON card_assets(slate_id, page_index)
+
+---
+
+## 7. 카드 렌더 (Playwright)
+
+### 템플릿
+
+`templates/default/card.html.j2` — Jinja 변수:
+
+| 변수 | 타입 | 설명 |
+|------|------|------|
+| `page_type` | str | "cover" / "body" / "cta" |
+| `headline` | str | 페이지 헤드라인 |
+| `body` | str | 본문 (markdown-lite 허용 — 줄바꿈 보존) |
+| `accent_color` | str | hex (예: "#FF5733") |
+| `page_no` | int | 1~10 |
+| `total_pages` | int | 10 |
+
+컨테이너 CSS: `width: 1080px; height: 1350px; overflow: hidden;`
+
+### 렌더 로직 (card_renderer.py)
+
+1. Playwright async chromium browser 1회 launch
+2. browser.new_context(viewport={"width": 1080, "height": 1350}) → page
+3. 10번 반복:
+   - Jinja 렌더 → temp HTML 파일 저장
+   - page.goto(`file://...`)
+   - page.screenshot(path=f"{page_no:02}.png", omit_background=False)
+4. browser.close
+
+### Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    fonts-noto-cjk fonts-noto-cjk-extra \
+ && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+RUN playwright install chromium --with-deps
+COPY app ./app
+ENV PYTHONUNBUFFERED=1
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+이미지 사이즈 +500MB 예상. NAS Celeron J4025에서 카드 10장 렌더 ≤ 30초 목표.
+
+---
+
+## 8. API (insta-lab)
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/insta/status` | 서비스 상태 (NAVER/ANTHROPIC 키 여부) |
+| POST | `/api/insta/news/collect` | 뉴스 수집 수동 트리거 → BackgroundTask |
+| GET | `/api/insta/news/articles` | 수집 기사 목록 (category, days 필터) |
+| POST | `/api/insta/keywords/extract` | 키워드 추출 수동 트리거 → BackgroundTask |
+| GET | `/api/insta/keywords` | 트렌딩 키워드 (category, used 필터) |
+| POST | `/api/insta/slates` | 슬레이트 생성 (keyword, category) → BackgroundTask |
+| GET | `/api/insta/slates` | 슬레이트 목록 |
+| GET | `/api/insta/slates/{id}` | 슬레이트 상세 (카피 + 자산 경로) |
+| POST | `/api/insta/slates/{id}/render` | 카드 렌더 재시도 |
+| GET | `/api/insta/slates/{id}/assets/{page}` | 카드 PNG 다운로드 (1~10) |
+| DELETE | `/api/insta/slates/{id}` | 삭제 (slate + assets) |
+| GET | `/api/insta/tasks/{task_id}` | BackgroundTask 상태 폴링 |
+| GET/PUT | `/api/insta/templates/prompts/{name}` | 프롬프트 템플릿 조회·수정 |
+
+---
+
+## 9. 키워드 추출 알고리즘
+
+```python
+def extract_keywords(category: str, articles: list[Article]) -> list[Keyword]:
+    # 1. 빈도 기반 후보 추출
+    #    - 명사 추출 (간단: 한글 2~6자 정규식 + 불용어 제거)
+    #    - 카테고리 시드 키워드와 코사인 유사도 ≥ 0.3 이상만
+    raw_freq = count_nouns(articles)
+    candidates = top_n(raw_freq, n=20)
+
+    # 2. Claude Haiku로 정제
+    #    - 시스템 프롬프트: "{category} 인스타 카드용 키워드"
+    #    - 입력: 후보 20개 + 각 후보가 등장한 기사 제목 3개
+    #    - 출력 JSON: [{"keyword": str, "score": 0~1, "reason": str}]
+    refined = claude_haiku_refine(category, candidates, articles)
+
+    # 3. score 내림차순 → 상위 5개 trending_keywords로 저장
+    return refined[:5]
+```
+
+- `score`는 LLM이 평가한 "카드 콘텐츠 적합도" (호기심 유발성 + 시의성 + 구체성)
+- 시드 키워드는 `prompt_templates.name='category_seeds'`에서 카테고리별 JSON으로 관리
+
+---
+
+## 10. 카드 카피 생성 (slate_writer)
+
+Claude 호출 1회로 10페이지 카피 생성:
+
+```
+시스템 프롬프트 (DB 저장, 사용자가 수정 가능):
+- 너는 인스타그램 카드 뉴스 카피라이터다.
+- {category} 카테고리, 키워드: {keyword}
+- 출력은 JSON 객체:
+  {
+    "cover_copy": {"headline": str, "body": str, "accent_color": "#hex"},
+    "body_copies": [
+      {"headline": str, "body": str},
+      ... (8개)
+    ],
+    "cta_copy": {"headline": str, "body": str, "cta": str},
+    "suggested_caption": str,
+    "hashtags": ["#tag1", ...]
+  }
+
+입력:
+- 키워드 + 관련 기사 제목·요약 5건
+```
+
+`accent_color`는 카테고리별 기본값(경제=#0F62FE, 심리학=#A66CFF, 연예=#FF5C8A) 사용, LLM이 더 어울리면 override.
+
+---
+
+## 11. 에러 처리
+
+| 단계 | 실패 시 |
+|------|---------|
+| 뉴스 수집 | 카테고리별 try/except, 한 카테고리 빈 결과여도 다른 카테고리 진행. 모두 실패 시 텔레그램 알림 |
+| 키워드 추출 | LLM 실패 시 빈도 기반 결과만 사용 (degrade). LLM 타임아웃 60s |
+| 카피 생성 | LLM 실패 시 BackgroundTask `failed`, 텔레그램 알림. JSON 파싱 실패 시 1회 retry |
+| 카드 렌더 | Playwright 크래시 시 retry 1회. 실패 시 slate.status='failed' + 텔레그램 알림. 일부 페이지만 실패 시 해당 페이지만 재렌더 가능 |
+| 텔레그램 미디어 그룹 | 텔레그램 API 10MB/장 제한 → PNG quality 90, 평균 < 500KB 예상. 초과 시 압축 후 재시도 |
+
+---
+
+## 12. 테스트
+
+- pytest 단위 테스트:
+  - `news_collector` mocked HTTP, JSON 파싱 검증
+  - `keyword_extractor` 빈도 추출 단위 + Claude mock
+  - `card_writer` Claude mock, JSON 스키마 검증
+  - `card_renderer` 작은 fixture HTML로 PNG 1장 생성 (실제 Playwright 통합 테스트 1건)
+- agent-office 통합: `agents/insta.py` mocked service_proxy로 on_schedule·on_command·on_callback 분기 검증
+
+---
+
+## 13. 운영·환경
+
+### 환경변수 (insta-lab)
+
+| 변수 | 기본값 | 설명 |
+|------|--------|------|
+| `NAVER_CLIENT_ID` | (필수) | 네이버 검색 API 키 |
+| `NAVER_CLIENT_SECRET` | (필수) | 네이버 검색 API 시크릿 |
+| `ANTHROPIC_API_KEY` | (필수) | Claude API 키 |
+| `INSTA_DATA_PATH` | `./data/insta` | DB + 카드 PNG 저장 경로 |
+| `CARD_TEMPLATE_DIR` | `/app/app/templates` | HTML/CSS 템플릿 디렉토리 |
+| `CORS_ALLOW_ORIGINS` | `*` | CORS 설정 |
+
+### docker-compose.yml 변경
+
+- `blog-lab` 서비스 블록 → `insta-lab` 서비스 블록 (포트 18700:8000 그대로)
+- 볼륨: `./data/insta:/app/data/insta`
+
+### nginx default.conf 변경
+
+```
+location /api/blog-marketing/ {  # 제거
+    ...
+}
+
+location /api/insta/ {  # 신규
+    proxy_pass http://insta-lab:8000;
+    ...
+}
+```
+
+### CLAUDE.md 갱신
+
+- workspace/CLAUDE.md: blog-lab 표 행 제거 → insta-lab 추가, `/api/blog-marketing/` 행 제거 → `/api/insta/` 추가, 컨테이너 이름·역할 업데이트
+- web-backend/CLAUDE.md: 9.x 섹션 blog-lab 통째로 → insta-lab 섹션, 4·5 표 갱신
+
+---
+
+## 14. 완료 정의
+
+- [ ] blog-lab 디렉토리·DB 삭제, 컨테이너에서 더 이상 빌드 안 됨
+- [ ] insta-lab 컨테이너 빌드 및 헬스체크 통과
+- [ ] `POST /api/insta/news/collect` → news_articles에 카테고리당 30건 저장 확인
+- [ ] `POST /api/insta/keywords/extract` → trending_keywords 카테고리당 5개 저장
+- [ ] `POST /api/insta/slates` → 카피 생성 + 카드 PNG 10장 렌더 (수동 호출)
+- [ ] agent-office의 insta-agent 09:30 cron 등록, 텔레그램 인라인 키보드 후보 푸시 작동
+- [ ] 텔레그램 인라인 버튼 클릭 → 미디어 그룹 10장 발송 성공
+- [ ] CLAUDE.md 양쪽 갱신 후 커밋
+- [ ] pytest 전체 통과

docs/superpowers/specs/2026-05-16-insta-trends-design.md

@@ -0,0 +1,247 @@
+# insta-lab Trends 탭 설계 — 외부 트렌드 수집 + 카테고리 가중치
+
+작성일: 2026-05-16
+상태: 사용자 승인 대기 → writing-plans 진입 예정
+연관 문서: `2026-05-15-insta-agent-design.md` (insta-lab 기본 설계)
+
+---
+
+## 1. 목적·배경
+
+insta-lab 운영 첫 사이클(2026-05-16 머지·배포 완료)에서 다음 두 가지 한계가 드러남:
+
+1. **키워드 발견 소스가 사용자 시드 키워드에만 의존** — 진짜 "지금 뜨고 있는" 화제를 잡지 못함. 카테고리당 5개 시드를 고정해두고 거기에 매칭되는 기사만 모음.
+2. **계정 정체성을 시스템이 모름** — 사용자가 "내 인스타 계정은 경제 위주"라고 정해도 시스템은 모든 카테고리를 균등하게 처리.
+
+이 spec은 두 한계를 해소하기 위해:
+- 외부 트렌드 소스(NAVER 인기 + Google Trends)를 추가해 "발견" 단계를 보강
+- 계정 카테고리 가중치 모델을 도입해 자동 추출 알고리즘이 계정 정체성을 반영
+
+---
+
+## 2. 스코프
+
+### 포함
+
+- 신규 백엔드 모듈 `trend_collector.py` (NAVER 인기 + Google Trends 두 source)
+- 신규 백엔드 모듈 변경: `keyword_extractor.py`에 가중치 기반 `extract_with_weights()` 추가
+- DB 마이그레이션: `trending_keywords` 테이블에 `source` 컬럼 추가, `account_preferences` 신규 테이블
+- 신규 API 4개 (`POST /trends/collect`, `GET /trends`, `GET/PUT /preferences`)
+- 09:00 매일 cron 추가 (트렌드 수집), 09:30 cron 가중치 적용
+- 프론트엔드: InstaCards 페이지에 탭 네비게이션 추가, Trends 탭 신규 3개 패널
+
+### 제외
+
+- pytrends 외 외부 SaaS 트렌드 API (BuzzSumo 등)
+- 트렌드 시계열 차트
+- 카테고리 자동 학습 (사용자 카드 생성 이력에서 선호도 추론)
+- 트렌드 알림 (특정 키워드 등장 시 push)
+
+---
+
+## 3. 데이터 소스
+
+### 3-1. NAVER 인기 (source = 'naver_popular')
+- NAVER news.json API 재사용. 카테고리당 시드 키워드로 `sort=sim` (정확도 정렬 = 인기 시그널) 30건 수집
+- 응답 기사 묶음에서 빈도어 추출 → 카테고리 매핑 (기존 keyword_extractor의 `_count_nouns` + `_top_candidates` 재사용)
+- 상위 N개를 `trending_keywords` 테이블에 source='naver_popular'로 저장
+
+### 3-2. Google Trends (source = 'google_trends')
+- 라이브러리: `pytrends` (PyPI, MIT)
+- `TrendReq(hl='ko-KR', tz=540).trending_searches(pn='south_korea')` 호출 → 일일 트렌딩 키워드 리스트
+- 각 키워드에 대해 Claude Haiku 1회 호출로 카테고리 분류 (`economy` / `psychology` / `celebrity` / 사용자 추가 카테고리 / `uncategorized`)
+- LLM 분류 비용 절감을 위해 분류 결과를 1일 캐시 — `trend_collector` 모듈 레벨 `_category_cache: dict[str, tuple[str, float]]` (keyword → (category, expires_ts)), 컨테이너 lifetime 동안 유효. 같은 키워드 재요청 시 cache hit. 캐시는 영속화하지 않음 (재시작 시 첫 호출은 LLM 재분류)
+- `trending_keywords` 테이블에 source='google_trends', score=traffic 정규화값
+
+### 3-3. 통합 저장
+
+기존 `trending_keywords` 스키마에 한 컬럼 추가:
+
+```sql
+ALTER TABLE trending_keywords ADD COLUMN source TEXT NOT NULL DEFAULT 'manual';
+-- 기존 row 모두 'manual'로 마킹됨 (시드 키워드에서 추출된 것)
+-- 신규 source: 'naver_popular' | 'google_trends'
+```
+
+`source`별 추가 인덱스:
+```sql
+CREATE INDEX idx_tk_source ON trending_keywords(source, suggested_at DESC);
+```
+
+---
+
+## 4. 카테고리 가중치 모델
+
+### 4-1. 신규 테이블 `account_preferences`
+
+```sql
+CREATE TABLE account_preferences (
+    category    TEXT PRIMARY KEY,
+    weight      REAL NOT NULL DEFAULT 1.0,
+    updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+```
+
+- 초기 시드: `economy=1.0`, `psychology=1.0`, `celebrity=1.0` (균등)
+- 사용자는 0~10 자유 범위 (UI는 0~100 정수%로 노출, 백엔드에서 0~1 정규화)
+- 합계 강제 없음. 알고리즘 내부에서 비율 정규화
+- 카테고리 추가 자유. 단 추가 시 `prompt_templates.category_seeds`에도 시드 키워드 함께 정의해야 자동 추출에 반영됨 (UI에서 안내)
+
+### 4-2. 가중치 기반 추출 알고리즘
+
+기존 `keyword_extractor.extract_for_category(category, limit)` 유지. 신규:
+
+```python
+def extract_with_weights(weights: dict[str, float], total_limit: int) -> list[Keyword]:
+    """카테고리 가중치 비율대로 키워드를 분배 추출."""
+    if not weights or sum(weights.values()) == 0:
+        # fallback: 균등 가중치
+        cats = list(DEFAULT_CATEGORY_SEEDS.keys())
+        weights = {c: 1.0 for c in cats}
+
+    total_weight = sum(weights.values())
+    saved = []
+    for category, w in weights.items():
+        if w <= 0:
+            continue
+        per_cat = round(total_limit * w / total_weight)
+        if per_cat <= 0:
+            continue
+        saved.extend(extract_for_category(category, limit=per_cat))
+    return saved
+```
+
+- `total_limit` 기본 15 (3 카테고리 × 5 시드 시절 합계와 동일)
+- weight=0 카테고리는 skip (분류는 유지하되 자동 추출에서 제외하고 싶을 때)
+
+---
+
+## 5. API (insta-lab)
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| POST | `/api/insta/trends/collect` | 두 source 모두 수집 (BackgroundTask) → `{task_id}` |
+| GET | `/api/insta/trends` | 트렌드 조회. query: `source` (`naver_popular`/`google_trends`/`all`), `category`, `days` (default 1, 의미: `suggested_at >= now() - days*24h`). 정렬 `suggested_at DESC, score DESC` |
+| GET | `/api/insta/preferences` | 가중치 조회 → `{categories: [{category, weight, updated_at}]}` |
+| PUT | `/api/insta/preferences` | body `{categories: {economy: 0.6, ...}}` → upsert |
+
+기존 `/api/insta/keywords`는 source 필터 추가 (`?source=manual` 등). 미지정 시 모든 source 반환 (default behavior 유지).
+
+---
+
+## 6. 스케줄러 변경 (agent-office InstaAgent)
+
+기존:
+- 09:30 — 키워드 추출 → 텔레그램 푸시
+
+신규:
+- **09:00 — 외부 트렌드 수집** (NAVER 인기 + Google Trends) — `_run_insta_trends_collect()` 신규 cron
+- **09:30 — 키워드 추출** (기존 + 가중치 적용) — InstaAgent가 `get_preferences()` 호출 후 `extract_with_weights()` 사용
+
+수동 트리거: InstaAgent에 `on_command("collect_trends", {})` 신규 액션. 텔레그램에서 `/insta collect_trends` 슬래시 명령 또는 Insta 페이지 버튼에서 호출.
+
+---
+
+## 7. 프론트엔드 변경 (web-ui InstaCards.jsx)
+
+### 7-1. 탭 네비게이션
+
+기존 5개 패널을 두 탭으로 재구성:
+
+| 탭 | 패널 |
+|----|------|
+| **Cards** (기본) | Trigger, Trending Keywords, Slates, SlateDetail, PromptEditor (기존 그대로) |
+| **Trends** (신규) | AccountFocusPanel, ExternalTrendsPanel, PreferenceImpactPanel |
+
+탭 컴포넌트: `<TabBar>` 단순 buttons (`activeTab` state), URL에 `?tab=trends` 쿼리로 deep-link 지원.
+
+### 7-2. AccountFocusPanel
+- 카테고리별 가중치 슬라이더 (0~100 정수%) + 우측 막대 차트 (분포 시각화)
+- **+ 카테고리 추가** 버튼 → 모달로 카테고리명 + 시드 키워드 N개 입력 (시드는 category_seeds 프롬프트 템플릿에 머지)
+- **저장** 버튼 → `PUT /preferences` (debounce 1초)
+
+### 7-3. ExternalTrendsPanel
+- 상단: **🔄 수동 수집** 버튼 + "마지막 수집: HH:MM" 라벨 + 진행 task box
+- 두 컬럼 (반응형 → 모바일은 세로):
+  - **🔥 NAVER 인기** — 카테고리별 그룹핑, 각 카드: keyword + score + 카테고리 배지
+  - **🌐 Google Trends** — 단순 리스트, 각 카드: keyword + 카테고리 배지 + traffic
+- 각 카드 우측에 **🎴** 버튼 → 즉시 `POST /slates` (기존 흐름)
+- 색상 매핑: economy=#0F62FE, psychology=#A66CFF, celebrity=#FF5C8A, custom=#6B7280
+
+### 7-4. PreferenceImpactPanel (작은 박스)
+- "현재 가중치 기준 다음 자동 추출 결과 미리보기: economy 3 / psychology 2 / celebrity 0"
+- 가중치 슬라이더 변경 시 즉시 클라이언트에서 계산해 갱신
+- 컴팩트 1줄 표시
+
+### 7-5. 신규 API 헬퍼 (src/api.js)
+
+```js
+export function getInstaTrends({ source, category, days = 1 } = {}) { ... }
+export function instaCollectTrends() { ... }
+export function getInstaPreferences() { ... }
+export function putInstaPreferences(categories) { ... }
+```
+
+---
+
+## 8. 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| pytrends rate limit / 차단 | try/except → 빈 결과로 graceful degrade. NAVER 인기는 정상 수집 |
+| LLM 분류 실패 | `uncategorized` 카테고리로 폴백, 사용자가 UI에서 수동 재분류 가능 |
+| 가중치 합계 0 | 균등 가중치 (1/N)로 폴백, 로그 warning |
+| 카테고리 추가했는데 시드 없음 | 자동 추출에서 자연스럽게 skip (NAVER 검색에 시드 필요), UI에서 "시드 키워드 추가 필요" 경고 |
+| Google Trends 한국 region 부재 | hl='ko-KR' + pn='south_korea' 명시. 실패 시 빈 결과 |
+
+---
+
+## 9. 테스트
+
+### insta-lab pytest
+- `test_trend_collector.py` (4): `fetch_naver_popular` mocked, `fetch_google_trends` pytrends mocked, 카테고리 매핑, 캐시 hit
+- `test_extract_with_weights.py` (3): 균등 가중치, 한쪽 0 가중치, fallback 빈 가중치
+- `test_preferences_crud.py` (2): GET 기본값, PUT upsert
+- `test_main_trends.py` (3): 신규 4개 엔드포인트 통합
+
+### agent-office pytest
+- `test_insta_agent_trends.py` (2): `on_schedule_trends` mocked, weight-applied extract
+
+---
+
+## 10. 마이그레이션 절차
+
+1. `db.init_db()`에 `ALTER TABLE trending_keywords ADD COLUMN source ...` 추가 — `PRAGMA table_info`로 컬럼 존재 여부 확인 후 idempotent하게 실행
+2. `account_preferences` 테이블 신규 생성
+3. 초기 시드: 기존 카테고리 economy/psychology/celebrity 모두 weight=1.0
+4. 기존 `trending_keywords` row는 자동으로 source='manual' (컬럼 DEFAULT)
+5. `requirements.txt`에 `pytrends>=4.9` 추가
+6. 배포 후 사용자가 Trends 탭에서 가중치 조정 (필수 아님, 균등이 디폴트 동작)
+
+---
+
+## 11. 운영 영향
+
+| 항목 | 영향 |
+|------|------|
+| Anthropic 토큰 비용 | +미미 (Google Trends 1회당 ~20 키워드 × Haiku 분류 1콜 ≈ 600 토큰/일) |
+| DB 크기 | +미미 (트렌드 row 일일 ~50개, 카테고리당 30 + Google 20) |
+| NAS CPU | +낮음 (pytrends + NAVER API 호출만, LLM은 외부) |
+| 카드 생성 흐름 | 변경 없음. 트렌드는 "발견" 단계만 보강 |
+
+---
+
+## 12. 완료 정의
+
+- [ ] `trending_keywords.source` 컬럼 마이그레이션 적용, 기존 row 모두 'manual'로 표시됨
+- [ ] `account_preferences` 테이블 생성, 초기 3개 카테고리 weight=1.0
+- [ ] `POST /api/insta/trends/collect` 호출 시 NAVER 인기 + Google Trends 모두 수집되어 DB 저장
+- [ ] `GET /api/insta/trends?source=google_trends` 결과 카테고리 분류됨
+- [ ] `PUT /api/insta/preferences` 후 09:30 cron이 가중치 비율대로 추출
+- [ ] 09:00 cron 등록, 매일 자동 트렌드 수집
+- [ ] Insta 페이지에 Cards/Trends 탭 전환 작동
+- [ ] Trends 탭의 AccountFocusPanel에서 가중치 변경·저장 가능
+- [ ] ExternalTrendsPanel에서 NAVER 인기 + Google Trends 한 눈에 표시, 각 카드 생성 트리거 작동
+- [ ] PreferenceImpactPanel 미리보기 갱신
+- [ ] insta-lab pytest 전체 통과 (기존 21 + 신규 12 = 33)
+- [ ] agent-office pytest 전체 통과

insta-lab/Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.12-slim-bookworm
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Korean fonts + Chromium runtime deps (Debian 12 / bookworm)
+# `playwright install --with-deps`를 쓰지 않는 이유: 그 명령은 Ubuntu 패키지명을
+# 사용해 Debian에서 ttf-ubuntu-font-family / ttf-unifont 등 없는 패키지를 시도
+# → apt 실패. 대신 Chromium이 실제 필요로 하는 라이브러리만 명시 설치.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    fonts-noto-cjk fonts-noto-cjk-extra \
+    libnss3 libnspr4 libdbus-1-3 libatk1.0-0 libatk-bridge2.0-0 \
+    libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
+    libxfixes3 libxrandr2 libgbm1 libxshmfence1 libpango-1.0-0 \
+    libcairo2 libasound2 libatspi2.0-0 \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+# --timeout 600 --retries 5: NAS 느린 네트워크/CPU에서 pip 다운로드 timeout 방지
+RUN pip install --no-cache-dir --timeout 600 --retries 5 -r requirements.txt
+RUN playwright install chromium
+
+COPY . .
+
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

insta-lab/app/card_renderer.py

@@ -0,0 +1,100 @@
+"""Jinja → HTML → Playwright headless screenshot."""
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import tempfile
+from typing import List
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+from playwright.async_api import async_playwright
+
+from .config import CARDS_DIR, CARD_TEMPLATE_DIR
+from . import db
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_template_dir() -> str:
+    """Prefer config CARD_TEMPLATE_DIR if it exists; else fall back to in-repo templates/."""
+    if os.path.isdir(CARD_TEMPLATE_DIR):
+        return CARD_TEMPLATE_DIR
+    return os.path.join(os.path.dirname(__file__), "templates")
+
+
+def _env() -> Environment:
+    return Environment(
+        loader=FileSystemLoader(_resolve_template_dir()),
+        autoescape=select_autoescape(["html", "j2"]),
+    )
+
+
+def _slate_dir(slate_id: int) -> str:
+    out = os.path.join(CARDS_DIR, str(slate_id))
+    os.makedirs(out, exist_ok=True)
+    return out
+
+
+def _build_pages(slate: dict) -> List[dict]:
+    cover = json.loads(slate["cover_copy"] or "{}")
+    bodies = json.loads(slate["body_copies"] or "[]")
+    cta = json.loads(slate["cta_copy"] or "{}")
+    accent = cover.get("accent_color") or "#0F62FE"
+    pages: List[dict] = []
+    pages.append({
+        "page_type": "cover", "page_no": 1, "total_pages": 10,
+        "headline": cover.get("headline", ""), "body": cover.get("body", ""),
+        "accent_color": accent, "cta": "",
+    })
+    for i, b in enumerate(bodies[:8]):
+        pages.append({
+            "page_type": "body", "page_no": i + 2, "total_pages": 10,
+            "headline": b.get("headline", ""), "body": b.get("body", ""),
+            "accent_color": accent, "cta": "",
+        })
+    pages.append({
+        "page_type": "cta", "page_no": 10, "total_pages": 10,
+        "headline": cta.get("headline", ""), "body": cta.get("body", ""),
+        "accent_color": accent, "cta": cta.get("cta", ""),
+    })
+    return pages
+
+
+async def render_slate(slate_id: int, template: str = "default/card.html.j2") -> List[str]:
+    slate = db.get_card_slate(slate_id)
+    if not slate:
+        raise ValueError(f"slate {slate_id} not found")
+    env = _env()
+    tmpl = env.get_template(template)
+    pages = _build_pages(slate)
+    out_dir = _slate_dir(slate_id)
+    paths: List[str] = []
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        try:
+            ctx = await browser.new_context(viewport={"width": 1080, "height": 1350})
+            page = await ctx.new_page()
+            for spec in pages:
+                html_str = tmpl.render(**spec)
+                with tempfile.NamedTemporaryFile("w", suffix=".html", delete=False, encoding="utf-8") as f:
+                    f.write(html_str)
+                    html_path = f.name
+                try:
+                    await page.goto(f"file://{html_path}", wait_until="networkidle")
+                    out_path = os.path.join(out_dir, f"{spec['page_no']:02d}.png")
+                    await page.screenshot(path=out_path, full_page=False, omit_background=False)
+                    with open(out_path, "rb") as fp:
+                        file_hash = hashlib.md5(fp.read()).hexdigest()
+                    db.add_card_asset(slate_id, spec["page_no"], out_path, file_hash)
+                    paths.append(out_path)
+                finally:
+                    try:
+                        os.unlink(html_path)
+                    except OSError:
+                        pass
+        finally:
+            await browser.close()
+    return paths

insta-lab/app/card_writer.py

@@ -0,0 +1,100 @@
+"""Claude로 10페이지 카드 카피를 한 번에 생성."""
+
+import json
+import logging
+import re
+from typing import Any, Dict, Optional
+
+from anthropic import Anthropic
+
+from .config import ANTHROPIC_API_KEY, ANTHROPIC_MODEL_SONNET
+from . import db
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ACCENT_BY_CATEGORY = {
+    "economy": "#0F62FE",
+    "psychology": "#A66CFF",
+    "celebrity": "#FF5C8A",
+}
+
+DEFAULT_PROMPT = """너는 인스타그램 카드 뉴스 카피라이터다.
+카테고리: {category}
+키워드: {keyword}
+참고 기사:
+{articles}
+
+10페이지 인스타 카드용 카피를 다음 JSON 한 객체로만 출력해라 (코드펜스 금지):
+{{
+  "cover_copy": {{"headline": "<훅 한 줄>", "body": "<서브카피 1~2줄>", "accent_color": "#hex"}},
+  "body_copies": [
+    {{"headline": "<포인트 헤드라인>", "body": "<2~4문장 본문>"}},
+    ... (총 8개)
+  ],
+  "cta_copy": {{"headline": "<요약 한 줄>", "body": "<마무리 1~2줄>", "cta": "팔로우/저장 등"}},
+  "suggested_caption": "<인스타 캡션 본문>",
+  "hashtags": ["#태그1", "#태그2", ...]
+}}
+"""
+
+
+def _client() -> Anthropic:
+    return Anthropic(api_key=ANTHROPIC_API_KEY)
+
+
+def _strip_codefence(s: str) -> str:
+    s = s.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```(?:json)?\s*|\s*```$", "", s).strip()
+    return s
+
+
+def _load_prompt() -> str:
+    pt = db.get_prompt_template("slate_writer")
+    if pt and pt.get("template"):
+        return pt["template"]
+    return DEFAULT_PROMPT
+
+
+def write_slate(keyword: str, category: str,
+                articles: Optional[list] = None) -> int:
+    """Claude로 10페이지 카피 생성 후 card_slates에 저장. slate_id 반환."""
+    if articles is None:
+        articles = db.list_news_articles(category=category, days=2)
+    article_text = "\n".join(
+        f"- {a['title']}: {a.get('summary', '')[:120]}" for a in articles[:8]
+    ) or "(참고 기사 없음)"
+
+    prompt = _load_prompt().format(category=category, keyword=keyword, articles=article_text)
+    msg = _client().messages.create(
+        model=ANTHROPIC_MODEL_SONNET,
+        max_tokens=4000,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    raw = msg.content[0].text
+    cleaned = _strip_codefence(raw)
+    try:
+        data: Dict[str, Any] = json.loads(cleaned)
+    except json.JSONDecodeError as e:
+        logger.warning("slate JSON parse failed: %s", e)
+        raise ValueError(f"Invalid JSON from LLM: {e}") from e
+
+    body_copies = data.get("body_copies") or []
+    if len(body_copies) != 8:
+        raise ValueError(f"body_copies must have 8 items, got {len(body_copies)}")
+
+    cover = data.get("cover_copy") or {}
+    if not cover.get("accent_color"):
+        cover["accent_color"] = DEFAULT_ACCENT_BY_CATEGORY.get(category, "#222831")
+
+    sid = db.add_card_slate({
+        "keyword": keyword,
+        "category": category,
+        "status": "draft",
+        "cover_copy": cover,
+        "body_copies": body_copies,
+        "cta_copy": data.get("cta_copy") or {},
+        "suggested_caption": data.get("suggested_caption") or "",
+        "hashtags": data.get("hashtags") or [],
+    })
+    return sid

insta-lab/app/config.py

@@ -0,0 +1,26 @@
+import os
+
+NAVER_CLIENT_ID = os.getenv("NAVER_CLIENT_ID", "")
+NAVER_CLIENT_SECRET = os.getenv("NAVER_CLIENT_SECRET", "")
+YOUTUBE_DATA_API_KEY = os.getenv("YOUTUBE_DATA_API_KEY", "")
+ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "")
+ANTHROPIC_MODEL_HAIKU = os.getenv("ANTHROPIC_MODEL_HAIKU", "claude-haiku-4-5-20251001")
+ANTHROPIC_MODEL_SONNET = os.getenv("ANTHROPIC_MODEL_SONNET", "claude-sonnet-4-6")
+
+INSTA_DATA_PATH = os.getenv("INSTA_DATA_PATH", "/app/data")
+DB_PATH = os.path.join(INSTA_DATA_PATH, "insta.db")
+CARDS_DIR = os.path.join(INSTA_DATA_PATH, "insta_cards")
+CARD_TEMPLATE_DIR = os.getenv("CARD_TEMPLATE_DIR", "/app/app/templates")
+
+CORS_ALLOW_ORIGINS = os.getenv(
+    "CORS_ALLOW_ORIGINS", "http://localhost:3007,http://localhost:8080"
+)
+
+NEWS_PER_CATEGORY = int(os.getenv("NEWS_PER_CATEGORY", "30"))
+KEYWORDS_PER_CATEGORY = int(os.getenv("KEYWORDS_PER_CATEGORY", "5"))
+
+DEFAULT_CATEGORY_SEEDS = {
+    "economy": ["금리", "인플레이션", "환율", "주식", "부동산"],
+    "psychology": ["심리학", "스트레스", "우울증", "관계", "자존감"],
+    "celebrity": ["연예인", "드라마", "예능", "K-POP", "영화"],
+}

insta-lab/app/db.py

@@ -0,0 +1,352 @@
+import os
+import sqlite3
+import json
+import uuid
+from typing import Any, Dict, List, Optional
+
+from .config import DB_PATH
+
+
+def _conn() -> sqlite3.Connection:
+    os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
+    conn = sqlite3.connect(DB_PATH, timeout=120.0)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=120000")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def init_db() -> None:
+    with _conn() as conn:
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS news_articles (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                category    TEXT NOT NULL,
+                title       TEXT NOT NULL,
+                link        TEXT NOT NULL UNIQUE,
+                summary     TEXT NOT NULL DEFAULT '',
+                pub_date    TEXT,
+                fetched_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_na_category_fetched ON news_articles(category, fetched_at DESC)")
+
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS trending_keywords (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                keyword         TEXT NOT NULL,
+                category        TEXT NOT NULL,
+                score           REAL NOT NULL DEFAULT 0,
+                articles_count  INTEGER NOT NULL DEFAULT 0,
+                suggested_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                used            INTEGER NOT NULL DEFAULT 0
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_tk_score ON trending_keywords(category, score DESC)")
+
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS card_slates (
+                id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+                keyword            TEXT NOT NULL,
+                category           TEXT NOT NULL,
+                status             TEXT NOT NULL DEFAULT 'draft',
+                cover_copy         TEXT NOT NULL DEFAULT '{}',
+                body_copies        TEXT NOT NULL DEFAULT '[]',
+                cta_copy           TEXT NOT NULL DEFAULT '{}',
+                suggested_caption  TEXT NOT NULL DEFAULT '',
+                hashtags           TEXT NOT NULL DEFAULT '[]',
+                created_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                updated_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_cs_created ON card_slates(created_at DESC)")
+
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS card_assets (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                slate_id    INTEGER NOT NULL REFERENCES card_slates(id) ON DELETE CASCADE,
+                page_index  INTEGER NOT NULL,
+                file_path   TEXT NOT NULL,
+                file_hash   TEXT NOT NULL DEFAULT '',
+                created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                UNIQUE (slate_id, page_index)
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_ca_slate ON card_assets(slate_id, page_index)")
+
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS generation_tasks (
+                id          TEXT PRIMARY KEY,
+                type        TEXT NOT NULL,
+                status      TEXT NOT NULL DEFAULT 'queued',
+                progress    INTEGER NOT NULL DEFAULT 0,
+                message     TEXT NOT NULL DEFAULT '',
+                result_id   INTEGER,
+                error       TEXT,
+                params      TEXT NOT NULL DEFAULT '{}',
+                created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_gt_created ON generation_tasks(created_at DESC)")
+
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS prompt_templates (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                name         TEXT NOT NULL UNIQUE,
+                description  TEXT NOT NULL DEFAULT '',
+                template     TEXT NOT NULL DEFAULT '',
+                updated_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+
+        # source column for trending_keywords (idempotent ALTER)
+        cols = [r[1] for r in conn.execute("PRAGMA table_info(trending_keywords)").fetchall()]
+        if "source" not in cols:
+            conn.execute("ALTER TABLE trending_keywords ADD COLUMN source TEXT NOT NULL DEFAULT 'manual'")
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_tk_source ON trending_keywords(source, suggested_at DESC)")
+
+        # account_preferences — 카테고리 가중치
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS account_preferences (
+                category    TEXT PRIMARY KEY,
+                weight      REAL NOT NULL DEFAULT 1.0,
+                updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+        # seed defaults if table empty
+        existing = conn.execute("SELECT COUNT(*) FROM account_preferences").fetchone()[0]
+        if existing == 0:
+            for cat in ("economy", "psychology", "celebrity"):
+                conn.execute(
+                    "INSERT INTO account_preferences(category, weight) VALUES(?,?)",
+                    (cat, 1.0),
+                )
+
+
+# ── news_articles ────────────────────────────────────────────────
+def add_news_article(row: Dict[str, Any]) -> int:
+    with _conn() as conn:
+        try:
+            cur = conn.execute(
+                "INSERT INTO news_articles(category, title, link, summary, pub_date) VALUES(?,?,?,?,?)",
+                (row["category"], row["title"], row["link"], row.get("summary", ""), row.get("pub_date")),
+            )
+            return cur.lastrowid
+        except sqlite3.IntegrityError:
+            existing = conn.execute("SELECT id FROM news_articles WHERE link=?", (row["link"],)).fetchone()
+            return existing["id"] if existing else 0
+
+
+def list_news_articles(category: Optional[str] = None, days: int = 1) -> List[Dict[str, Any]]:
+    sql = "SELECT * FROM news_articles WHERE fetched_at >= datetime('now', ?)"
+    params: List[Any] = [f"-{int(days)} days"]
+    if category:
+        sql += " AND category=?"
+        params.append(category)
+    sql += " ORDER BY fetched_at DESC"
+    with _conn() as conn:
+        rows = conn.execute(sql, params).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── trending_keywords ───────────────────────────────────────────
+def add_trending_keyword(row: Dict[str, Any]) -> int:
+    with _conn() as conn:
+        cur = conn.execute(
+            "INSERT INTO trending_keywords(keyword, category, score, articles_count, source) VALUES(?,?,?,?,?)",
+            (
+                row["keyword"], row["category"],
+                float(row.get("score", 0.0)), int(row.get("articles_count", 0)),
+                row.get("source", "manual"),
+            ),
+        )
+        return cur.lastrowid
+
+
+def list_trending_keywords(category: Optional[str] = None, used: Optional[bool] = None) -> List[Dict[str, Any]]:
+    sql = "SELECT * FROM trending_keywords WHERE 1=1"
+    params: List[Any] = []
+    if category:
+        sql += " AND category=?"
+        params.append(category)
+    if used is not None:
+        sql += " AND used=?"
+        params.append(1 if used else 0)
+    sql += " ORDER BY score DESC, suggested_at DESC"
+    with _conn() as conn:
+        rows = conn.execute(sql, params).fetchall()
+    return [dict(r) for r in rows]
+
+
+def mark_keyword_used(keyword_id: int) -> None:
+    with _conn() as conn:
+        conn.execute("UPDATE trending_keywords SET used=1 WHERE id=?", (keyword_id,))
+
+
+def get_trending_keyword(keyword_id: int) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        row = conn.execute("SELECT * FROM trending_keywords WHERE id=?", (keyword_id,)).fetchone()
+    return dict(row) if row else None
+
+
+# ── card_slates ─────────────────────────────────────────────────
+def add_card_slate(row: Dict[str, Any]) -> int:
+    with _conn() as conn:
+        cur = conn.execute("""
+            INSERT INTO card_slates(keyword, category, status, cover_copy, body_copies, cta_copy,
+                                    suggested_caption, hashtags)
+            VALUES(?,?,?,?,?,?,?,?)
+        """, (
+            row["keyword"], row["category"], row.get("status", "draft"),
+            json.dumps(row.get("cover_copy", {}), ensure_ascii=False),
+            json.dumps(row.get("body_copies", []), ensure_ascii=False),
+            json.dumps(row.get("cta_copy", {}), ensure_ascii=False),
+            row.get("suggested_caption", ""),
+            json.dumps(row.get("hashtags", []), ensure_ascii=False),
+        ))
+        return cur.lastrowid
+
+
+def update_slate_status(slate_id: int, status: str) -> None:
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE card_slates SET status=?, updated_at=strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id=?",
+            (status, slate_id),
+        )
+
+
+def get_card_slate(slate_id: int) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        row = conn.execute("SELECT * FROM card_slates WHERE id=?", (slate_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def list_card_slates(limit: int = 50) -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT * FROM card_slates ORDER BY created_at DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def delete_card_slate(slate_id: int) -> None:
+    with _conn() as conn:
+        conn.execute("DELETE FROM card_slates WHERE id=?", (slate_id,))
+
+
+# ── card_assets ─────────────────────────────────────────────────
+def add_card_asset(slate_id: int, page_index: int, file_path: str, file_hash: str = "") -> int:
+    with _conn() as conn:
+        cur = conn.execute("""
+            INSERT INTO card_assets(slate_id, page_index, file_path, file_hash)
+            VALUES(?,?,?,?)
+            ON CONFLICT(slate_id, page_index) DO UPDATE SET
+                file_path=excluded.file_path, file_hash=excluded.file_hash
+        """, (slate_id, page_index, file_path, file_hash))
+        return cur.lastrowid
+
+
+def list_card_assets(slate_id: int) -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT * FROM card_assets WHERE slate_id=? ORDER BY page_index ASC",
+            (slate_id,),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── generation_tasks ────────────────────────────────────────────
+def create_task(task_type: str, params: Dict[str, Any]) -> str:
+    tid = uuid.uuid4().hex
+    with _conn() as conn:
+        conn.execute(
+            "INSERT INTO generation_tasks(id, type, params) VALUES(?,?,?)",
+            (tid, task_type, json.dumps(params, ensure_ascii=False)),
+        )
+    return tid
+
+
+def update_task(task_id: str, status: str, progress: int = 0, message: str = "",
+                result_id: Optional[int] = None, error: Optional[str] = None) -> None:
+    with _conn() as conn:
+        conn.execute("""
+            UPDATE generation_tasks
+               SET status=?, progress=?, message=?, result_id=?, error=?,
+                   updated_at=strftime('%Y-%m-%dT%H:%M:%fZ','now')
+             WHERE id=?
+        """, (status, progress, message, result_id, error, task_id))
+
+
+def get_task(task_id: str) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        row = conn.execute("SELECT * FROM generation_tasks WHERE id=?", (task_id,)).fetchone()
+    return dict(row) if row else None
+
+
+# ── prompt_templates ────────────────────────────────────────────
+def upsert_prompt_template(name: str, template: str, description: str = "") -> None:
+    with _conn() as conn:
+        conn.execute("""
+            INSERT INTO prompt_templates(name, description, template)
+                 VALUES(?,?,?)
+            ON CONFLICT(name) DO UPDATE SET
+                template=excluded.template,
+                description=excluded.description,
+                updated_at=strftime('%Y-%m-%dT%H:%M:%fZ','now')
+        """, (name, description, template))
+
+
+def get_prompt_template(name: str) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        row = conn.execute("SELECT * FROM prompt_templates WHERE name=?", (name,)).fetchone()
+    return dict(row) if row else None
+
+
+# ── external trends ─────────────────────────────────────────────
+def add_external_trend(row: Dict[str, Any]) -> int:
+    """`source` 필수 — naver_popular | google_trends. trending_keywords에 인서트."""
+    if "source" not in row:
+        raise ValueError("add_external_trend requires 'source' field")
+    return add_trending_keyword(row)
+
+
+def list_trends(source: Optional[str] = None, category: Optional[str] = None,
+                days: int = 1) -> List[Dict[str, Any]]:
+    sql = "SELECT * FROM trending_keywords WHERE suggested_at >= datetime('now', ?)"
+    params: List[Any] = [f"-{int(days)} days"]
+    if source and source != "all":
+        sql += " AND source=?"
+        params.append(source)
+    if category:
+        sql += " AND category=?"
+        params.append(category)
+    sql += " ORDER BY suggested_at DESC, score DESC"
+    with _conn() as conn:
+        rows = conn.execute(sql, params).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ── account_preferences ─────────────────────────────────────────
+def get_preferences() -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT category, weight, updated_at FROM account_preferences ORDER BY category ASC"
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def upsert_preferences(weights: Dict[str, float]) -> None:
+    """전체 upsert. 기존에 있던 카테고리는 weight 갱신, 신규는 INSERT.
+    명시되지 않은 기존 카테고리는 그대로 둔다 (삭제 X). 삭제 필요 시 별도 API로."""
+    with _conn() as conn:
+        for cat, w in weights.items():
+            conn.execute("""
+                INSERT INTO account_preferences(category, weight)
+                     VALUES(?,?)
+                ON CONFLICT(category) DO UPDATE SET
+                    weight=excluded.weight,
+                    updated_at=strftime('%Y-%m-%dT%H:%M:%fZ','now')
+            """, (cat, float(w)))

insta-lab/app/keyword_extractor.py

@@ -0,0 +1,102 @@
+"""키워드 추출 — 한글 명사 빈도 + Claude Haiku 정제."""
+
+import json
+import logging
+import re
+from collections import Counter
+from typing import Any, Dict, List
+
+from anthropic import Anthropic
+
+from .config import ANTHROPIC_API_KEY, ANTHROPIC_MODEL_HAIKU, KEYWORDS_PER_CATEGORY
+from . import db
+
+logger = logging.getLogger(__name__)
+
+_NOUN_RE = re.compile(r"[가-힣]{2,6}")
+_STOPWORDS = {
+    "있다", "없다", "이다", "되다", "그리고", "하지만", "통해", "위해", "오늘", "이번",
+    "지난", "관련", "대해", "또한", "다만", "한편", "최근", "앞서", "현재", "진행",
+    "발생", "결과", "이상", "이하", "여러", "다양", "방법", "경우", "이유", "필요",
+}
+
+
+def _count_nouns(text: str) -> Dict[str, int]:
+    tokens = _NOUN_RE.findall(text or "")
+    return Counter(tokens)
+
+
+def _top_candidates(counts: Dict[str, int], n: int = 20) -> List[tuple]:
+    filtered = [(k, c) for k, c in counts.items() if k not in _STOPWORDS]
+    return sorted(filtered, key=lambda x: x[1], reverse=True)[:n]
+
+
+def _refine_with_llm(category: str, candidates: List[tuple], articles: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Claude Haiku로 후보 정제. JSON 리스트 [{keyword, score(0~1), reason}] 반환."""
+    if not ANTHROPIC_API_KEY:
+        return [{"keyword": k, "score": min(1.0, c / 10), "reason": "freq"} for k, c in candidates[:KEYWORDS_PER_CATEGORY]]
+
+    client = Anthropic(api_key=ANTHROPIC_API_KEY)
+    titles = [a["title"] for a in articles[:15]]
+    prompt = f"""너는 인스타그램 카드 뉴스 큐레이터다.
+카테고리: {category}
+빈도 상위 후보: {[k for k, _ in candidates]}
+관련 기사 제목 일부:
+{chr(10).join('- ' + t for t in titles)}
+
+이 후보 중에서 인스타 카드 콘텐츠로 적합한 키워드를 score 내림차순으로 최대 {KEYWORDS_PER_CATEGORY}개 골라.
+출력 형식 (JSON 배열만):
+[{{"keyword": "...", "score": 0.0~1.0, "reason": "..."}}]
+"""
+    msg = client.messages.create(
+        model=ANTHROPIC_MODEL_HAIKU,
+        max_tokens=600,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    text = msg.content[0].text.strip()
+    if text.startswith("```"):
+        text = re.sub(r"^```(?:json)?\s*|\s*```$", "", text).strip()
+    try:
+        return json.loads(text)
+    except Exception:
+        logger.warning("LLM refine JSON parse failed, falling back to freq")
+        return [{"keyword": k, "score": min(1.0, c / 10), "reason": "freq-fallback"} for k, c in candidates[:KEYWORDS_PER_CATEGORY]]
+
+
+def extract_for_category(category: str, limit: int = KEYWORDS_PER_CATEGORY) -> List[Dict[str, Any]]:
+    """카테고리 기사들에서 키워드를 뽑아 DB에 저장하고 결과 반환."""
+    articles = db.list_news_articles(category=category, days=2)
+    text_blob = "\n".join((a["title"] + " " + a.get("summary", "")) for a in articles)
+    counts = _count_nouns(text_blob)
+    candidates = _top_candidates(counts, n=20)
+    refined = _refine_with_llm(category, candidates, articles)[:limit]
+
+    saved: List[Dict[str, Any]] = []
+    for kw in refined:
+        kid = db.add_trending_keyword({
+            "keyword": kw["keyword"],
+            "category": category,
+            "score": float(kw.get("score", 0.0)),
+            "articles_count": sum(1 for a in articles if kw["keyword"] in a["title"]),
+        })
+        saved.append({"id": kid, **kw, "category": category})
+    return saved
+
+
+def extract_with_weights(weights: Dict[str, float], total_limit: int) -> List[Dict[str, Any]]:
+    """카테고리 가중치 비율대로 키워드를 분배 추출."""
+    from .config import DEFAULT_CATEGORY_SEEDS
+    if not weights or sum(weights.values()) == 0:
+        cats = list(DEFAULT_CATEGORY_SEEDS.keys())
+        weights = {c: 1.0 for c in cats}
+
+    total_weight = sum(weights.values())
+    out: List[Dict[str, Any]] = []
+    for category, w in weights.items():
+        if w <= 0:
+            continue
+        per_cat = round(total_limit * w / total_weight)
+        if per_cat <= 0:
+            continue
+        out.extend(extract_for_category(category, limit=per_cat))
+    return out

insta-lab/app/main.py

@@ -0,0 +1,305 @@
+"""FastAPI entrypoint for insta-lab."""
+
+import asyncio
+import json
+import logging
+import os
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, BackgroundTasks, Body, Query
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+from .config import (
+    CORS_ALLOW_ORIGINS, NAVER_CLIENT_ID, ANTHROPIC_API_KEY,
+    INSTA_DATA_PATH, DB_PATH, DEFAULT_CATEGORY_SEEDS, KEYWORDS_PER_CATEGORY,
+)
+from . import db, news_collector, keyword_extractor, card_writer, card_renderer, trend_collector
+
+logger = logging.getLogger(__name__)
+app = FastAPI()
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[o.strip() for o in CORS_ALLOW_ORIGINS.split(",")],
+    allow_credentials=False,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"],
+    allow_headers=["Content-Type"],
+)
+
+
+@app.on_event("startup")
+def on_startup():
+    os.makedirs(INSTA_DATA_PATH, exist_ok=True)
+    db.init_db()
+
+
+@app.get("/health")
+def health():
+    return {"ok": True}
+
+
+@app.get("/api/insta/status")
+def status():
+    return {
+        "ok": True,
+        "naver_api": bool(NAVER_CLIENT_ID),
+        "anthropic_api": bool(ANTHROPIC_API_KEY),
+    }
+
+
+# ── News ─────────────────────────────────────────────────────────
+class CollectRequest(BaseModel):
+    categories: Optional[list[str]] = None
+
+
+def _seeds_for(category: str) -> list[str]:
+    pt = db.get_prompt_template("category_seeds")
+    if pt and pt.get("template"):
+        try:
+            data = json.loads(pt["template"])
+            if category in data:
+                return list(data[category])
+        except Exception:
+            pass
+    return list(DEFAULT_CATEGORY_SEEDS.get(category, []))
+
+
+async def _bg_collect(task_id: str, categories: list[str]):
+    try:
+        db.update_task(task_id, "processing", 10, "수집 중")
+        total = 0
+        for cat in categories:
+            seeds = _seeds_for(cat)
+            if not seeds:
+                continue
+            total += news_collector.collect_for_category(cat, seeds)
+        db.update_task(task_id, "succeeded", 100, f"{total}건 수집", result_id=total)
+    except Exception as e:
+        logger.exception("collect failed")
+        db.update_task(task_id, "failed", 0, "", error=str(e))
+
+
+@app.post("/api/insta/news/collect")
+def collect_news(req: CollectRequest, bg: BackgroundTasks):
+    cats = req.categories or list(DEFAULT_CATEGORY_SEEDS.keys())
+    tid = db.create_task("news_collect", {"categories": cats})
+    bg.add_task(_bg_collect, tid, cats)
+    return {"task_id": tid, "categories": cats}
+
+
+@app.get("/api/insta/news/articles")
+def list_articles(category: Optional[str] = None, days: int = Query(7, ge=1, le=90)):
+    return {"items": db.list_news_articles(category=category, days=days)}
+
+
+# ── Keywords ─────────────────────────────────────────────────────
+class ExtractRequest(BaseModel):
+    categories: Optional[list[str]] = None
+
+
+async def _bg_extract(task_id: str, categories: Optional[list[str]] = None):
+    try:
+        db.update_task(task_id, "processing", 10, "추출 중")
+        prefs_rows = db.get_preferences()
+        weights = {p["category"]: p["weight"] for p in prefs_rows}
+        if categories:
+            # 사용자가 카테고리 명시한 경우만 그 서브셋으로 균등 가중치 (override)
+            weights = {c: 1.0 for c in categories}
+        total = KEYWORDS_PER_CATEGORY * max(1, len([w for w in weights.values() if w > 0]))
+        keyword_extractor.extract_with_weights(weights, total_limit=total)
+        db.update_task(task_id, "succeeded", 100, "완료", result_id=0)
+    except Exception as e:
+        logger.exception("extract failed")
+        db.update_task(task_id, "failed", 0, "", error=str(e))
+
+
+@app.post("/api/insta/keywords/extract")
+def extract_keywords(req: ExtractRequest, bg: BackgroundTasks):
+    cats = req.categories or list(DEFAULT_CATEGORY_SEEDS.keys())
+    tid = db.create_task("keyword_extract", {"categories": cats})
+    bg.add_task(_bg_extract, tid, cats)
+    return {"task_id": tid, "categories": cats}
+
+
+@app.get("/api/insta/keywords")
+def list_keywords(
+    category: Optional[str] = None,
+    used: Optional[bool] = None,
+    source: Optional[str] = None,
+):
+    if source:
+        return {"items": db.list_trends(source=source, category=category, days=30)}
+    return {"items": db.list_trending_keywords(category=category, used=used)}
+
+
+# ── Slates ───────────────────────────────────────────────────────
+class SlateRequest(BaseModel):
+    keyword: str
+    category: str
+    keyword_id: Optional[int] = None
+
+
+async def _bg_create_slate(task_id: str, keyword: str, category: str, keyword_id: Optional[int]):
+    try:
+        db.update_task(task_id, "processing", 30, "카피 생성 중")
+        sid = card_writer.write_slate(keyword=keyword, category=category)
+        db.update_task(task_id, "processing", 70, "카드 렌더 중")
+        await card_renderer.render_slate(sid)
+        db.update_slate_status(sid, "rendered")
+        if keyword_id:
+            db.mark_keyword_used(keyword_id)
+        db.update_task(task_id, "succeeded", 100, "완료", result_id=sid)
+    except Exception as e:
+        logger.exception("create slate failed")
+        db.update_task(task_id, "failed", 0, "", error=str(e))
+
+
+@app.post("/api/insta/slates")
+def create_slate(req: SlateRequest, bg: BackgroundTasks):
+    tid = db.create_task("slate_create", req.dict())
+    bg.add_task(_bg_create_slate, tid, req.keyword, req.category, req.keyword_id)
+    return {"task_id": tid}
+
+
+@app.get("/api/insta/slates")
+def list_slates(limit: int = Query(50, ge=1, le=500)):
+    return {"items": db.list_card_slates(limit=limit)}
+
+
+@app.get("/api/insta/slates/{slate_id}")
+def get_slate(slate_id: int):
+    s = db.get_card_slate(slate_id)
+    if not s:
+        raise HTTPException(404, "slate not found")
+    s["assets"] = db.list_card_assets(slate_id)
+    for k in ("cover_copy", "body_copies", "cta_copy", "hashtags"):
+        if isinstance(s.get(k), str):
+            try:
+                s[k] = json.loads(s[k])
+            except Exception:
+                pass
+    return s
+
+
+async def _bg_render(task_id: str, slate_id: int):
+    try:
+        db.update_task(task_id, "processing", 30, "재렌더 중")
+        await card_renderer.render_slate(slate_id)
+        db.update_slate_status(slate_id, "rendered")
+        db.update_task(task_id, "succeeded", 100, "완료", result_id=slate_id)
+    except Exception as e:
+        logger.exception("render failed")
+        db.update_task(task_id, "failed", 0, "", error=str(e))
+
+
+@app.post("/api/insta/slates/{slate_id}/render")
+def render_slate_endpoint(slate_id: int, bg: BackgroundTasks):
+    if not db.get_card_slate(slate_id):
+        raise HTTPException(404, "slate not found")
+    tid = db.create_task("slate_render", {"slate_id": slate_id})
+    bg.add_task(_bg_render, tid, slate_id)
+    return {"task_id": tid}
+
+
+@app.get("/api/insta/slates/{slate_id}/assets/{page}")
+def get_asset(slate_id: int, page: int):
+    if not (1 <= page <= 10):
+        raise HTTPException(400, "page must be 1..10")
+    assets = db.list_card_assets(slate_id)
+    match = next((a for a in assets if a["page_index"] == page), None)
+    if not match:
+        raise HTTPException(404, "asset not found")
+    return FileResponse(match["file_path"], media_type="image/png")
+
+
+@app.delete("/api/insta/slates/{slate_id}")
+def delete_slate(slate_id: int):
+    if not db.get_card_slate(slate_id):
+        raise HTTPException(404)
+    for a in db.list_card_assets(slate_id):
+        try:
+            os.unlink(a["file_path"])
+        except OSError:
+            pass
+    db.delete_card_slate(slate_id)
+    return {"ok": True}
+
+
+# ── Tasks ────────────────────────────────────────────────────────
+@app.get("/api/insta/tasks/{task_id}")
+def get_task_status(task_id: str):
+    t = db.get_task(task_id)
+    if not t:
+        raise HTTPException(404)
+    return t
+
+
+# ── Prompt Templates ─────────────────────────────────────────────
+class TemplateBody(BaseModel):
+    template: str
+    description: str = ""
+
+
+@app.get("/api/insta/templates/prompts/{name}")
+def get_prompt(name: str):
+    pt = db.get_prompt_template(name)
+    if not pt:
+        raise HTTPException(404)
+    return pt
+
+
+@app.put("/api/insta/templates/prompts/{name}")
+def upsert_prompt(name: str, body: TemplateBody):
+    db.upsert_prompt_template(name, body.template, body.description)
+    return db.get_prompt_template(name)
+
+
+# ── Trends ───────────────────────────────────────────────────────
+class TrendsCollectRequest(BaseModel):
+    categories: Optional[list[str]] = None
+
+
+async def _bg_collect_trends(task_id: str, categories: list[str]):
+    try:
+        db.update_task(task_id, "processing", 10, "외부 트렌드 수집 중")
+        result = trend_collector.collect_all(categories)
+        msg = f"naver:{result['naver_popular']}, youtube:{result['youtube_trending']}"
+        db.update_task(task_id, "succeeded", 100, msg, result_id=sum(result.values()))
+    except Exception as e:
+        logger.exception("trends collect failed")
+        db.update_task(task_id, "failed", 0, "", error=str(e))
+
+
+@app.post("/api/insta/trends/collect")
+def collect_trends(req: TrendsCollectRequest, bg: BackgroundTasks):
+    cats = req.categories or list(DEFAULT_CATEGORY_SEEDS.keys())
+    tid = db.create_task("trends_collect", {"categories": cats})
+    bg.add_task(_bg_collect_trends, tid, cats)
+    return {"task_id": tid, "categories": cats}
+
+
+@app.get("/api/insta/trends")
+def list_trends_endpoint(
+    source: Optional[str] = None,
+    category: Optional[str] = None,
+    days: int = Query(1, ge=1, le=90),
+):
+    return {"items": db.list_trends(source=source, category=category, days=days)}
+
+
+# ── Preferences ──────────────────────────────────────────────────
+class PreferencesBody(BaseModel):
+    categories: dict[str, float]
+
+
+@app.get("/api/insta/preferences")
+def get_preferences_endpoint():
+    return {"categories": db.get_preferences()}
+
+
+@app.put("/api/insta/preferences")
+def put_preferences_endpoint(body: PreferencesBody):
+    db.upsert_preferences(body.categories)
+    return {"categories": db.get_preferences()}

insta-lab/app/news_collector.py

@@ -0,0 +1,82 @@
+"""NAVER 뉴스 검색 API 연동 — 카테고리별 시드 키워드로 일일 수집."""
+
+import html
+import logging
+import re
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .config import NAVER_CLIENT_ID, NAVER_CLIENT_SECRET, NEWS_PER_CATEGORY
+from . import db
+
+logger = logging.getLogger(__name__)
+
+NEWS_URL = "https://openapi.naver.com/v1/search/news.json"
+_HEADERS = {
+    "X-Naver-Client-Id": NAVER_CLIENT_ID,
+    "X-Naver-Client-Secret": NAVER_CLIENT_SECRET,
+}
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _clean(text: str) -> str:
+    if not text:
+        return ""
+    no_tag = _TAG_RE.sub("", text)
+    return html.unescape(no_tag).strip()
+
+
+def search_news(keyword: str, display: int = 30, sort: str = "date") -> List[Dict[str, Any]]:
+    """NAVER news.json 단일 호출.
+
+    Returns: list of {title, link, summary, pub_date}
+    """
+    resp = requests.get(
+        NEWS_URL,
+        headers=_HEADERS,
+        params={"query": keyword, "display": display, "sort": sort},
+        timeout=10,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return [
+        {
+            "title": _clean(item.get("title", "")),
+            "link": item.get("link") or item.get("originallink", ""),
+            "summary": _clean(item.get("description", "")),
+            "pub_date": item.get("pubDate", ""),
+        }
+        for item in data.get("items", [])
+    ]
+
+
+def collect_for_category(category: str,
+                         seed_keywords: List[str],
+                         per_keyword: Optional[int] = None) -> int:
+    """카테고리에 대해 시드 키워드 각각으로 검색 후 DB에 삽입.
+    UNIQUE(link)가 중복 삽입을 막음. 시도된 기사 수(중복 포함) 반환.
+    """
+    per_kw = per_keyword if per_keyword is not None else max(1, NEWS_PER_CATEGORY // max(1, len(seed_keywords)))
+    seen_links = set()
+    attempted = 0
+    for kw in seed_keywords:
+        try:
+            items = search_news(kw, display=per_kw)
+        except Exception as e:
+            logger.warning("search_news failed kw=%s err=%s", kw, e)
+            continue
+        for item in items:
+            link = item["link"]
+            if not link or link in seen_links:
+                continue
+            seen_links.add(link)
+            db.add_news_article({
+                "category": category,
+                "title": item["title"],
+                "link": link,
+                "summary": item["summary"],
+                "pub_date": item["pub_date"],
+            })
+            attempted += 1
+    return attempted

insta-lab/app/templates/default/card.html.j2

@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="UTF-8">
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;700;900&display=swap');
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body {
+    width: 1080px; height: 1350px;
+    font-family: 'Noto Sans KR', sans-serif;
+    background: #F7F7FA; color: #14171A;
+  }
+  .card {
+    width: 1080px; height: 1350px;
+    padding: 80px 72px;
+    display: flex; flex-direction: column; justify-content: space-between;
+    background: linear-gradient(180deg, #FFFFFF 0%, #F7F7FA 100%);
+    border-top: 16px solid {{ accent_color }};
+  }
+  .badge {
+    display: inline-block; padding: 8px 20px; border-radius: 999px;
+    background: {{ accent_color }}; color: #fff;
+    font-size: 28px; font-weight: 700; letter-spacing: -0.02em;
+  }
+  .headline {
+    font-size: {{ 96 if page_type == 'cover' else 72 }}px;
+    font-weight: 900; line-height: 1.15; letter-spacing: -0.04em;
+    margin-top: 32px;
+  }
+  .body {
+    font-size: 40px; font-weight: 400; line-height: 1.55;
+    margin-top: 40px; color: #2A2F35;
+    white-space: pre-wrap;
+  }
+  .footer {
+    display: flex; justify-content: space-between; align-items: center;
+    font-size: 28px; color: #6B7280; font-weight: 500;
+  }
+  .cta { font-weight: 700; color: {{ accent_color }}; }
+</style>
+</head>
+<body>
+<div class="card">
+  <div>
+    <span class="badge">{{ page_type|upper }}</span>
+    <h1 class="headline">{{ headline }}</h1>
+    <p class="body">{{ body }}</p>
+  </div>
+  <div class="footer">
+    <span>{{ page_no }} / {{ total_pages }}</span>
+    {% if cta %}<span class="cta">{{ cta }}</span>{% endif %}
+  </div>
+</div>
+</body>
+</html>

insta-lab/app/trend_collector.py

@@ -0,0 +1,250 @@
+"""외부 트렌드 수집 — NAVER 인기 + YouTube 인기 영상 + LLM 카테고리 분류.
+
+NAVER: 카테고리별 시드 키워드로 인기 검색 → 빈도 상위 추출.
+YouTube: Google Trends 비공식 endpoint(RSS / dailytrends JSON)가 모두 404 폐기되어
+대체로 YouTube Data API v3 (`videos.list?chart=mostPopular&regionCode=KR`) 사용.
+무료 일일 quota 10000, 한국 region 지원, 인기 영상 50개 제목에서 트렌드 추출.
+LLM 분류 결과는 24h in-memory 캐시.
+"""
+
+import json
+import logging
+import re
+import time
+from typing import Any, Dict, List, Optional
+
+import requests
+from anthropic import Anthropic
+
+from .config import (
+    NAVER_CLIENT_ID, NAVER_CLIENT_SECRET, DEFAULT_CATEGORY_SEEDS,
+    ANTHROPIC_API_KEY, ANTHROPIC_MODEL_HAIKU, YOUTUBE_DATA_API_KEY,
+)
+from . import db
+from .news_collector import _clean
+from .keyword_extractor import _count_nouns, _top_candidates
+
+logger = logging.getLogger(__name__)
+
+NEWS_URL = "https://openapi.naver.com/v1/search/news.json"
+_NAVER_HEADERS = {
+    "X-Naver-Client-Id": NAVER_CLIENT_ID,
+    "X-Naver-Client-Secret": NAVER_CLIENT_SECRET,
+}
+
+YOUTUBE_TRENDING_URL = "https://www.googleapis.com/youtube/v3/videos"
+# YouTube 제목 정제: 대괄호·이모지·과도한 길이 제거 후 카드 주제로 적합한 키워드 형태
+_TITLE_BRACKET_RE = re.compile(r"[\[【「『\(][^\]】」』\)]{0,30}[\]】」』\)]")
+_EMOJI_RE = re.compile(
+    r"["
+    r"\U0001F300-\U0001FAFF"   # symbols & pictographs, etc.
+    r"\U00002600-\U000027BF"   # misc symbols, dingbats
+    r"\U0001F1E6-\U0001F1FF"   # regional indicator
+    r"]"
+)
+_TITLE_MAX_LEN = 60
+
+_PLACEHOLDER_SEEDS = {"...", "…", "tbd", "todo", "placeholder", "example"}
+
+
+def _is_valid_seed(s: str) -> bool:
+    """프롬프트 템플릿에 placeholder/빈 값이 들어가 NAVER에 400을 유발하는 일을 막는 가드."""
+    if not s:
+        return False
+    s = s.strip()
+    if len(s) < 2:
+        return False
+    if s.lower() in _PLACEHOLDER_SEEDS:
+        return False
+    return True
+
+
+def _seeds_for(category: str) -> List[str]:
+    """category_seeds 프롬프트 템플릿이 있으면 사용, 없거나 모두 invalid면 config DEFAULT 폴백."""
+    pt = db.get_prompt_template("category_seeds")
+    if pt and pt.get("template"):
+        try:
+            data = json.loads(pt["template"])
+            if category in data:
+                filtered = [s for s in (data[category] or []) if _is_valid_seed(s)]
+                if filtered:
+                    return filtered
+                logger.warning("category_seeds[%s]에 유효한 시드 없음 → DEFAULT 폴백", category)
+        except Exception as e:
+            logger.warning("category_seeds JSON 파싱 실패 → DEFAULT 폴백: %s", e)
+    return list(DEFAULT_CATEGORY_SEEDS.get(category, []))
+
+
+def fetch_naver_popular(category: str, per_seed: int = 30, top_n: int = 10) -> List[Dict[str, Any]]:
+    """카테고리 시드 키워드들로 NAVER news.json `sort=sim` 호출,
+    응답 기사 묶음에서 빈도어 추출 후 상위 N개 반환."""
+    seeds = _seeds_for(category)
+    if not seeds:
+        return []
+    blob_parts: List[str] = []
+    for seed in seeds:
+        try:
+            resp = requests.get(
+                NEWS_URL,
+                headers=_NAVER_HEADERS,
+                params={"query": seed, "display": per_seed, "sort": "sim"},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            for item in resp.json().get("items", []):
+                blob_parts.append(_clean(item.get("title", "")))
+                blob_parts.append(_clean(item.get("description", "")))
+        except Exception as e:
+            logger.warning("fetch_naver_popular seed=%s err=%s", seed, e)
+            continue
+    text = "\n".join(blob_parts)
+    counts = _count_nouns(text)
+    candidates = _top_candidates(counts, n=top_n)
+    if not candidates:
+        return []
+    max_count = candidates[0][1] or 1
+    return [
+        {
+            "keyword": k,
+            "category": category,
+            "source": "naver_popular",
+            "score": round(min(1.0, c / max_count), 4),
+            "articles_count": c,
+        }
+        for k, c in candidates
+    ]
+
+
+def collect_naver_popular_for(categories: List[str]) -> int:
+    total = 0
+    for cat in categories:
+        trends = fetch_naver_popular(cat)
+        for t in trends:
+            db.add_external_trend(t)
+            total += 1
+    return total
+
+
+# ── LLM 분류 캐시 ────────────────────────────────────────────────────────────
+
+_CACHE_TTL_SEC = 24 * 3600
+_category_cache: Dict[str, tuple] = {}  # keyword -> (category, expires_ts)
+
+
+def _llm_classify_one(keyword: str) -> str:
+    """Claude Haiku 1회 호출로 단일 키워드 분류."""
+    if not ANTHROPIC_API_KEY:
+        return "uncategorized"
+    seeds_template = db.get_prompt_template("category_seeds")
+    if seeds_template and seeds_template.get("template"):
+        try:
+            allowed = sorted(json.loads(seeds_template["template"]).keys())
+        except Exception:
+            allowed = sorted(DEFAULT_CATEGORY_SEEDS.keys())
+    else:
+        allowed = sorted(DEFAULT_CATEGORY_SEEDS.keys())
+    allowed.append("uncategorized")
+
+    client = Anthropic(api_key=ANTHROPIC_API_KEY)
+    msg = client.messages.create(
+        model=ANTHROPIC_MODEL_HAIKU,
+        max_tokens=20,
+        messages=[{
+            "role": "user",
+            "content": (
+                f"다음 한국어 트렌딩 키워드를 카테고리 중 하나로 분류해라. "
+                f"카테고리: {allowed}. 키워드: '{keyword}'. "
+                f"카테고리명 한 단어만 출력. 다른 텍스트 금지."
+            ),
+        }],
+    )
+    raw = msg.content[0].text.strip().lower()
+    for cat in allowed:
+        if cat.lower() in raw:
+            return cat
+    return "uncategorized"
+
+
+def classify_keyword(keyword: str) -> str:
+    now = time.time()
+    cached = _category_cache.get(keyword)
+    if cached and cached[1] > now:
+        return cached[0]
+    cat = _llm_classify_one(keyword)
+    _category_cache[keyword] = (cat, now + _CACHE_TTL_SEC)
+    return cat
+
+
+# ── YouTube Trending ──────────────────────────────────────────────────────────
+# YouTube Data API v3 videos.list?chart=mostPopular&regionCode=KR
+# 한국 인기 영상 50개 제목에서 카드 주제로 적합한 키워드 추출.
+
+def _clean_yt_title(title: str) -> str:
+    """[공식]·【속보】·🔥 등 제거 후 60자 이내로 자른다."""
+    if not title:
+        return ""
+    cleaned = _TITLE_BRACKET_RE.sub("", title)
+    cleaned = _EMOJI_RE.sub("", cleaned)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    return cleaned[:_TITLE_MAX_LEN]
+
+
+def fetch_youtube_trending() -> List[Dict[str, Any]]:
+    """YouTube Data API v3 mostPopular (한국, 50개). API 키 없거나 호출 실패 시 빈 리스트."""
+    if not YOUTUBE_DATA_API_KEY:
+        logger.info("YOUTUBE_DATA_API_KEY 미설정 — youtube_trending skip")
+        return []
+    try:
+        resp = requests.get(
+            YOUTUBE_TRENDING_URL,
+            params={
+                "part": "snippet",
+                "chart": "mostPopular",
+                "regionCode": "KR",
+                "maxResults": 50,
+                "key": YOUTUBE_DATA_API_KEY,
+            },
+            timeout=15,
+        )
+        resp.raise_for_status()
+        videos = resp.json().get("items", []) or []
+    except Exception as e:
+        logger.warning("YouTube trending fetch failed: %s", e)
+        return []
+
+    items: List[Dict[str, Any]] = []
+    seen = set()
+    total = max(1, len(videos))
+    for idx, v in enumerate(videos):
+        title = (v.get("snippet") or {}).get("title", "")
+        kw = _clean_yt_title(title)
+        if not kw or kw in seen:
+            continue
+        seen.add(kw)
+        try:
+            cat = classify_keyword(kw)
+        except Exception as e:
+            logger.warning("classify_keyword(%s) 실패: %s", kw, e)
+            cat = "uncategorized"
+        rank_score = round(max(0.0, 1.0 - (idx / total)), 4)
+        items.append({
+            "keyword": kw,
+            "category": cat,
+            "source": "youtube_trending",
+            "score": rank_score,
+            "articles_count": 0,
+        })
+    return items
+
+
+def collect_youtube_trending() -> int:
+    items = fetch_youtube_trending()
+    for it in items:
+        db.add_external_trend(it)
+    return len(items)
+
+
+def collect_all(categories: List[str]) -> Dict[str, int]:
+    naver_n = collect_naver_popular_for(categories)
+    yt_n = collect_youtube_trending()
+    return {"naver_popular": naver_n, "youtube_trending": yt_n}

insta-lab/requirements.txt

@@ -1,6 +1,9 @@
 fastapi==0.115.6
 uvicorn[standard]==0.34.0
 requests==2.32.3
-anthropic==0.52.0
-beautifulsoup4>=4.12
 httpx>=0.27
+anthropic==0.52.0
+jinja2>=3.1.4
+playwright==1.48.0
+pytest>=8.0
+pytest-asyncio>=0.24

insta-lab/tests/test_card_renderer.py

@@ -0,0 +1,48 @@
+import os
+import tempfile
+
+import pytest
+
+from app import db as db_module
+from app import card_renderer
+
+
+@pytest.fixture
+def tmp_db_and_dirs(monkeypatch, tmp_path):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    monkeypatch.setattr(card_renderer, "CARDS_DIR", str(tmp_path / "cards"))
+    db_module.init_db()
+    yield path
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def _seed_slate() -> int:
+    return db_module.add_card_slate({
+        "keyword": "테스트",
+        "category": "economy",
+        "status": "draft",
+        "cover_copy": {"headline": "커버 헤드라인", "body": "서브카피", "accent_color": "#0F62FE"},
+        "body_copies": [{"headline": f"본문 {i+1}", "body": f"내용 {i+1}"} for i in range(8)],
+        "cta_copy": {"headline": "마무리", "body": "감사합니다", "cta": "팔로우"},
+    })
+
+
+@pytest.mark.asyncio
+async def test_render_slate_produces_ten_pngs(tmp_db_and_dirs):
+    sid = _seed_slate()
+    paths = await card_renderer.render_slate(sid)
+    assert len(paths) == 10
+    for p in paths:
+        assert os.path.exists(p)
+        assert os.path.getsize(p) > 1000  # > 1 KB sanity
+    db_module.update_slate_status(sid, "rendered")
+    assets = db_module.list_card_assets(sid)
+    assert {a["page_index"] for a in assets} == set(range(1, 11))

insta-lab/tests/test_card_writer.py

@@ -0,0 +1,75 @@
+import json
+import os
+import tempfile
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from app import db as db_module
+from app import card_writer
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+SAMPLE_LLM_JSON = {
+    "cover_copy": {"headline": "금리 인상 단행", "body": "왜 지금?", "accent_color": "#0F62FE"},
+    "body_copies": [
+        {"headline": f"포인트 {i+1}", "body": f"본문 {i+1}"} for i in range(8)
+    ],
+    "cta_copy": {"headline": "정리", "body": "바로 확인", "cta": "팔로우"},
+    "suggested_caption": "금리에 대해 알아보자",
+    "hashtags": ["#금리", "#경제"],
+}
+
+
+def _fake_messages_create(*_args, **_kwargs):
+    msg = MagicMock()
+    block = MagicMock()
+    block.text = json.dumps(SAMPLE_LLM_JSON, ensure_ascii=False)
+    msg.content = [block]
+    return msg
+
+
+def test_write_slate_persists_full_payload(tmp_db, monkeypatch):
+    db_module.add_news_article({
+        "category": "economy", "title": "기준금리 인상 단행",
+        "link": "https://example.com/1", "summary": "한국은행 발표",
+    })
+    fake_client = MagicMock()
+    fake_client.messages.create = _fake_messages_create
+    monkeypatch.setattr(card_writer, "_client", lambda: fake_client)
+
+    sid = card_writer.write_slate(keyword="기준금리", category="economy")
+    slate = db_module.get_card_slate(sid)
+    assert slate["status"] == "draft"
+    body_copies = json.loads(slate["body_copies"])
+    assert len(body_copies) == 8
+    assert body_copies[0]["headline"] == "포인트 1"
+    assert json.loads(slate["cover_copy"])["accent_color"] == "#0F62FE"
+
+
+def test_write_slate_raises_on_invalid_json(tmp_db, monkeypatch):
+    fake_client = MagicMock()
+    bad_msg = MagicMock()
+    bad_block = MagicMock()
+    bad_block.text = "not json"
+    bad_msg.content = [bad_block]
+    fake_client.messages.create.return_value = bad_msg
+    monkeypatch.setattr(card_writer, "_client", lambda: fake_client)
+
+    with pytest.raises(ValueError):
+        card_writer.write_slate(keyword="x", category="economy")

insta-lab/tests/test_db.py

@@ -0,0 +1,97 @@
+import os
+import json
+import tempfile
+
+import pytest
+
+from app import db as db_module
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    # Close all SQLite WAL files before removal (needed on Windows)
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except FileNotFoundError:
+            pass
+
+
+def test_init_db_creates_seven_tables(tmp_db):
+    with db_module._conn() as conn:
+        rows = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+        ).fetchall()
+    names = sorted(r[0] for r in rows if not r[0].startswith("sqlite_"))
+    assert names == sorted([
+        "news_articles", "trending_keywords", "card_slates",
+        "card_assets", "generation_tasks", "prompt_templates",
+        "account_preferences",
+    ])
+
+
+def test_news_article_roundtrip(tmp_db):
+    aid = db_module.add_news_article({
+        "category": "economy",
+        "title": "금리 인상 발표",
+        "link": "https://example.com/1",
+        "summary": "한국은행이 기준금리를 인상했다.",
+        "pub_date": "2026-05-15T08:00:00",
+    })
+    assert isinstance(aid, int)
+    rows = db_module.list_news_articles(category="economy", days=7)
+    assert len(rows) == 1
+    assert rows[0]["title"] == "금리 인상 발표"
+
+
+def test_trending_keyword_roundtrip(tmp_db):
+    kid = db_module.add_trending_keyword({
+        "keyword": "기준금리",
+        "category": "economy",
+        "score": 0.87,
+        "articles_count": 12,
+    })
+    assert isinstance(kid, int)
+    items = db_module.list_trending_keywords(category="economy", used=False)
+    assert items[0]["score"] == pytest.approx(0.87)
+
+
+def test_card_slate_with_assets(tmp_db):
+    sid = db_module.add_card_slate({
+        "keyword": "기준금리",
+        "category": "economy",
+        "cover_copy": {"headline": "금리 인상", "body": "왜?", "accent_color": "#0F62FE"},
+        "body_copies": [{"headline": f"H{i}", "body": f"B{i}"} for i in range(8)],
+        "cta_copy": {"headline": "정리", "body": "바로 확인", "cta": "팔로우"},
+        "suggested_caption": "금리에 대해 알아보자",
+        "hashtags": ["#금리", "#경제"],
+    })
+    db_module.add_card_asset(sid, page_index=1, file_path="/tmp/01.png", file_hash="abc")
+    slate = db_module.get_card_slate(sid)
+    assert slate["status"] == "draft"
+    assert json.loads(slate["body_copies"])[0]["headline"] == "H0"
+    assets = db_module.list_card_assets(sid)
+    assert assets[0]["page_index"] == 1
+
+
+def test_generation_task_lifecycle(tmp_db):
+    tid = db_module.create_task("collect", {"category": "economy"})
+    db_module.update_task(tid, status="processing", progress=50, message="..")
+    db_module.update_task(tid, status="succeeded", progress=100, message="ok", result_id=123)
+    t = db_module.get_task(tid)
+    assert t["status"] == "succeeded"
+    assert t["result_id"] == 123
+
+
+def test_prompt_template_upsert(tmp_db):
+    db_module.upsert_prompt_template("slate_writer", "v1 template", "writer")
+    db_module.upsert_prompt_template("slate_writer", "v2 template", "writer")
+    pt = db_module.get_prompt_template("slate_writer")
+    assert pt["template"] == "v2 template"

insta-lab/tests/test_extract_with_weights.py

@@ -0,0 +1,71 @@
+import os
+import gc
+import tempfile
+from unittest.mock import patch
+
+import pytest
+
+from app import db as db_module
+from app import keyword_extractor
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def test_extract_with_weights_proportional(tmp_db, monkeypatch):
+    calls = []
+
+    def fake_extract(category, limit):
+        calls.append((category, limit))
+        return [{"id": i, "keyword": f"{category}{i}", "category": category, "score": 0.5}
+                for i in range(limit)]
+
+    monkeypatch.setattr(keyword_extractor, "extract_for_category", fake_extract)
+    out = keyword_extractor.extract_with_weights(
+        {"economy": 0.6, "psychology": 0.3, "celebrity": 0.1}, total_limit=10,
+    )
+    by_cat = {c: l for c, l in calls}
+    assert by_cat == {"economy": 6, "psychology": 3, "celebrity": 1}
+    assert len(out) == 10
+
+
+def test_extract_with_weights_skips_zero(tmp_db, monkeypatch):
+    calls = []
+
+    def fake_extract(category, limit):
+        calls.append((category, limit))
+        return []
+
+    monkeypatch.setattr(keyword_extractor, "extract_for_category", fake_extract)
+    keyword_extractor.extract_with_weights(
+        {"economy": 1.0, "celebrity": 0.0}, total_limit=10,
+    )
+    cats_called = [c for c, _ in calls]
+    assert "celebrity" not in cats_called
+    assert "economy" in cats_called
+
+
+def test_extract_with_weights_fallback_to_equal(tmp_db, monkeypatch):
+    calls = []
+
+    def fake_extract(category, limit):
+        calls.append((category, limit))
+        return []
+
+    monkeypatch.setattr(keyword_extractor, "extract_for_category", fake_extract)
+    keyword_extractor.extract_with_weights({}, total_limit=9)
+    by_cat = {c: l for c, l in calls}
+    assert set(by_cat.keys()) == {"economy", "psychology", "celebrity"}
+    assert all(l == 3 for l in by_cat.values())

insta-lab/tests/test_keyword_extractor.py

@@ -0,0 +1,65 @@
+import os
+import tempfile
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from app import db as db_module
+from app import keyword_extractor
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    # Windows-safe cleanup: close handles + remove sidecars
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def test_count_nouns_extracts_korean_nouns():
+    text = "기준금리 인상으로 환율 급등. 기준금리 추가 인상 가능성"
+    counts = keyword_extractor._count_nouns(text)
+    assert counts["기준금리"] == 2
+    assert counts["환율"] == 1
+
+
+def test_top_candidates_filters_stopwords():
+    counts = {"기준금리": 5, "있다": 7, "환율": 3, "그리고": 4}
+    top = keyword_extractor._top_candidates(counts, n=10)
+    keywords = [k for k, _ in top]
+    assert "있다" not in keywords
+    assert "그리고" not in keywords
+    assert "기준금리" in keywords
+
+
+def test_extract_for_category_persists(tmp_db):
+    # seed articles
+    for i in range(3):
+        db_module.add_news_article({
+            "category": "economy",
+            "title": f"기준금리 인상 {i}",
+            "link": f"https://example.com/{i}",
+            "summary": "환율도 영향",
+        })
+
+    # mock LLM refinement
+    fake_refined = [
+        {"keyword": "기준금리", "score": 0.92, "reason": "핵심 금융 이슈"},
+        {"keyword": "환율", "score": 0.71, "reason": "시장 영향"},
+    ]
+    with patch.object(keyword_extractor, "_refine_with_llm", return_value=fake_refined):
+        kws = keyword_extractor.extract_for_category("economy", limit=2)
+
+    assert len(kws) == 2
+    assert kws[0]["keyword"] == "기준금리"
+    persisted = db_module.list_trending_keywords(category="economy")
+    assert {p["keyword"] for p in persisted} == {"기준금리", "환율"}

insta-lab/tests/test_main.py

@@ -0,0 +1,91 @@
+import os
+import tempfile
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app import db as db_module
+
+
+@pytest.fixture
+def client(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    from app import main
+    monkeypatch.setattr(main, "DB_PATH", path)
+    with TestClient(main.app) as c:
+        yield c
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def test_health(client):
+    resp = client.get("/health")
+    assert resp.status_code == 200
+    assert resp.json()["ok"] is True
+
+
+def test_status_endpoint(client):
+    resp = client.get("/api/insta/status")
+    assert resp.status_code == 200
+    j = resp.json()
+    assert "naver_api" in j and "anthropic_api" in j
+
+
+def test_news_articles_listing(client):
+    db_module.add_news_article({
+        "category": "economy", "title": "T1", "link": "https://x/1", "summary": "S",
+    })
+    resp = client.get("/api/insta/news/articles?category=economy&days=7")
+    assert resp.status_code == 200
+    assert len(resp.json()["items"]) == 1
+
+
+def test_keywords_listing(client):
+    db_module.add_trending_keyword({
+        "keyword": "K", "category": "economy", "score": 0.5, "articles_count": 3,
+    })
+    resp = client.get("/api/insta/keywords?category=economy")
+    assert resp.status_code == 200
+    assert resp.json()["items"][0]["keyword"] == "K"
+
+
+def test_create_slate_kicks_background_task(client, monkeypatch):
+    from app import main, card_writer, card_renderer
+
+    def fake_write(keyword, category, articles=None):
+        return db_module.add_card_slate({
+            "keyword": keyword, "category": category, "status": "draft",
+            "cover_copy": {"headline": "H", "body": "B", "accent_color": "#000"},
+            "body_copies": [{"headline": f"h{i}", "body": f"b{i}"} for i in range(8)],
+            "cta_copy": {"headline": "C", "body": "B", "cta": "F"},
+        })
+
+    async def fake_render(slate_id, template="default/card.html.j2"):
+        for i in range(1, 11):
+            db_module.add_card_asset(slate_id, i, f"/tmp/{slate_id}_{i}.png", "h")
+        return [f"/tmp/{slate_id}_{i}.png" for i in range(1, 11)]
+
+    monkeypatch.setattr(card_writer, "write_slate", fake_write)
+    monkeypatch.setattr(card_renderer, "render_slate", fake_render)
+
+    resp = client.post("/api/insta/slates", json={"keyword": "K", "category": "economy"})
+    assert resp.status_code == 200
+    task_id = resp.json()["task_id"]
+    # poll task
+    for _ in range(20):
+        st = client.get(f"/api/insta/tasks/{task_id}").json()
+        if st["status"] in ("succeeded", "failed"):
+            break
+    assert st["status"] == "succeeded"
+    slate_id = st["result_id"]
+    detail = client.get(f"/api/insta/slates/{slate_id}").json()
+    assert detail["status"] == "rendered"
+    assert len(detail["assets"]) == 10

insta-lab/tests/test_main_trends.py

@@ -0,0 +1,83 @@
+import os
+import gc
+import tempfile
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app import db as db_module
+
+
+@pytest.fixture
+def client(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    from app import main
+    monkeypatch.setattr(main, "DB_PATH", path)
+    with TestClient(main.app) as c:
+        yield c
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def test_get_preferences_returns_defaults(client):
+    resp = client.get("/api/insta/preferences")
+    assert resp.status_code == 200
+    cats = {p["category"]: p["weight"] for p in resp.json()["categories"]}
+    assert cats == {"economy": 1.0, "psychology": 1.0, "celebrity": 1.0}
+
+
+def test_put_preferences_upsert(client):
+    resp = client.put("/api/insta/preferences",
+                      json={"categories": {"economy": 0.7, "psychology": 0.2, "tech": 0.5}})
+    assert resp.status_code == 200
+    cats = {p["category"]: p["weight"] for p in resp.json()["categories"]}
+    assert cats["economy"] == 0.7
+    assert cats["tech"] == 0.5
+
+
+def test_list_trends_filter(client):
+    db_module.add_external_trend({"keyword": "A", "category": "economy",
+                                  "source": "naver_popular", "score": 1.0})
+    db_module.add_external_trend({"keyword": "B", "category": "celebrity",
+                                  "source": "google_trends", "score": 0.8})
+    resp = client.get("/api/insta/trends?source=naver_popular")
+    items = resp.json()["items"]
+    assert {it["keyword"] for it in items} == {"A"}
+
+
+def test_collect_trends_kicks_background(client, monkeypatch):
+    from app import main, trend_collector
+
+    captured = {"called": False}
+
+    def fake_collect_all(cats):
+        captured["called"] = True
+        return {"naver_popular": 3, "youtube_trending": 2}
+
+    monkeypatch.setattr(trend_collector, "collect_all", fake_collect_all)
+    resp = client.post("/api/insta/trends/collect", json={})
+    assert resp.status_code == 200
+    task_id = resp.json()["task_id"]
+    for _ in range(20):
+        st = client.get(f"/api/insta/tasks/{task_id}").json()
+        if st["status"] in ("succeeded", "failed"):
+            break
+    assert st["status"] == "succeeded"
+    assert captured["called"] is True
+
+
+def test_list_keywords_filters_by_source(client):
+    db_module.add_trending_keyword({"keyword": "M", "category": "economy",
+                                    "score": 0.4, "articles_count": 1, "source": "manual"})
+    db_module.add_external_trend({"keyword": "N", "category": "economy",
+                                  "source": "naver_popular", "score": 0.9})
+    resp = client.get("/api/insta/keywords?source=manual")
+    items = resp.json()["items"]
+    assert {it["keyword"] for it in items} == {"M"}

insta-lab/tests/test_news_collector.py

@@ -0,0 +1,89 @@
+from unittest.mock import patch, MagicMock
+import os
+import tempfile
+
+import pytest
+
+from app import db as db_module
+from app import news_collector
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    # Close all SQLite WAL files before removal (needed on Windows)
+    import gc
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except FileNotFoundError:
+            pass
+
+
+SAMPLE_RESPONSE = {
+    "items": [
+        {
+            "title": "<b>금리</b> 인상 단행",
+            "originallink": "https://news.example.com/1",
+            "link": "https://n.news.naver.com/article/1",
+            "description": "한국은행이 <b>기준금리</b>를 25bp 올렸다.",
+            "pubDate": "Fri, 15 May 2026 08:00:00 +0900",
+        },
+        {
+            "title": "환율 급등",
+            "originallink": "https://news.example.com/2",
+            "link": "https://n.news.naver.com/article/2",
+            "description": "원달러 환율이 1400원을 돌파했다.",
+            "pubDate": "Fri, 15 May 2026 09:00:00 +0900",
+        },
+    ],
+}
+
+
+def test_strip_html_and_decode_entities():
+    out = news_collector._clean(' <b>"테스트"</b> &amp; 아이템 ')
+    assert out == '"테스트" & 아이템'
+
+
+def test_search_news_parses_items(tmp_db):
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = SAMPLE_RESPONSE
+    fake_resp.raise_for_status.return_value = None
+    with patch.object(news_collector.requests, "get", return_value=fake_resp):
+        items = news_collector.search_news("금리", display=10)
+    assert len(items) == 2
+    assert items[0]["title"] == "금리 인상 단행"
+    assert items[0]["summary"].startswith("한국은행")
+
+
+def test_collect_for_category_inserts(tmp_db):
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = SAMPLE_RESPONSE
+    fake_resp.raise_for_status.return_value = None
+    with patch.object(news_collector.requests, "get", return_value=fake_resp):
+        news_collector.collect_for_category("economy", seed_keywords=["금리"], per_keyword=10)
+    rows = db_module.list_news_articles(category="economy", days=7)
+    assert {r["link"] for r in rows} == {
+        "https://n.news.naver.com/article/1",
+        "https://n.news.naver.com/article/2",
+    }
+
+
+def test_collect_dedupes_existing(tmp_db):
+    db_module.add_news_article({
+        "category": "economy", "title": "기존",
+        "link": "https://n.news.naver.com/article/1", "summary": ""
+    })
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = SAMPLE_RESPONSE
+    fake_resp.raise_for_status.return_value = None
+    with patch.object(news_collector.requests, "get", return_value=fake_resp):
+        news_collector.collect_for_category("economy", seed_keywords=["금리"])
+    rows = db_module.list_news_articles(category="economy", days=7)
+    # 1 pre-existing + 1 newly added (the other link); UNIQUE link blocks duplicate insert
+    assert len(rows) == 2

insta-lab/tests/test_preferences_crud.py

@@ -0,0 +1,77 @@
+import os
+import gc
+import tempfile
+
+import pytest
+
+from app import db as db_module
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+def test_init_db_creates_account_preferences(tmp_db):
+    with db_module._conn() as conn:
+        rows = conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+    names = {r[0] for r in rows}
+    assert "account_preferences" in names
+
+
+def test_init_db_seeds_default_weights(tmp_db):
+    prefs = db_module.get_preferences()
+    cats = {p["category"]: p["weight"] for p in prefs}
+    assert cats["economy"] == pytest.approx(1.0)
+    assert cats["psychology"] == pytest.approx(1.0)
+    assert cats["celebrity"] == pytest.approx(1.0)
+
+
+def test_upsert_preferences_replaces_weights(tmp_db):
+    db_module.upsert_preferences({"economy": 0.6, "psychology": 0.3, "celebrity": 0.1, "tech": 0.5})
+    prefs = {p["category"]: p["weight"] for p in db_module.get_preferences()}
+    assert prefs["economy"] == pytest.approx(0.6)
+    assert prefs["tech"] == pytest.approx(0.5)
+    assert "celebrity" in prefs and prefs["celebrity"] == pytest.approx(0.1)
+
+
+def test_trending_keywords_source_column_exists(tmp_db):
+    with db_module._conn() as conn:
+        cols = [r[1] for r in conn.execute("PRAGMA table_info(trending_keywords)").fetchall()]
+    assert "source" in cols
+
+
+def test_add_trending_keyword_default_source(tmp_db):
+    kid = db_module.add_trending_keyword({
+        "keyword": "K", "category": "economy", "score": 0.5, "articles_count": 3,
+    })
+    with db_module._conn() as conn:
+        row = conn.execute("SELECT source FROM trending_keywords WHERE id=?", (kid,)).fetchone()
+    assert row[0] == "manual"
+
+
+def test_add_external_trend_stores_source(tmp_db):
+    tid = db_module.add_external_trend({
+        "keyword": "급등주", "category": "economy", "source": "naver_popular", "score": 0.9,
+    })
+    rows = db_module.list_trends(source="naver_popular")
+    assert any(r["id"] == tid and r["keyword"] == "급등주" for r in rows)
+
+
+def test_list_trends_filters_by_source_and_category(tmp_db):
+    db_module.add_external_trend({"keyword": "A", "category": "economy", "source": "naver_popular", "score": 1.0})
+    db_module.add_external_trend({"keyword": "B", "category": "celebrity", "source": "google_trends", "score": 1.0})
+    only_naver = db_module.list_trends(source="naver_popular")
+    assert {r["keyword"] for r in only_naver} == {"A"}
+    only_celeb_google = db_module.list_trends(source="google_trends", category="celebrity")
+    assert {r["keyword"] for r in only_celeb_google} == {"B"}

insta-lab/tests/test_trend_collector.py

@@ -0,0 +1,160 @@
+import os
+import gc
+import tempfile
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from app import db as db_module
+from app import trend_collector
+
+
+@pytest.fixture
+def tmp_db(monkeypatch):
+    fd, path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    monkeypatch.setattr(db_module, "DB_PATH", path)
+    db_module.init_db()
+    yield path
+    gc.collect()
+    for ext in ("", "-wal", "-shm"):
+        try:
+            os.remove(path + ext)
+        except OSError:
+            pass
+
+
+NAVER_RESPONSE = {
+    "items": [
+        {"title": "<b>기준금리</b> 인상", "link": "https://n.news.naver.com/a/1", "description": "한국은행 발표"},
+        {"title": "환율 급등", "link": "https://n.news.naver.com/a/2", "description": "달러 강세"},
+        {"title": "기준금리 추가 인상", "link": "https://n.news.naver.com/a/3", "description": "추가 발표"},
+    ],
+}
+
+
+def test_fetch_naver_popular_extracts_top_terms(tmp_db, monkeypatch):
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = NAVER_RESPONSE
+    fake_resp.raise_for_status.return_value = None
+
+    with patch.object(trend_collector.requests, "get", return_value=fake_resp):
+        trends = trend_collector.fetch_naver_popular("economy", per_seed=10, top_n=5)
+
+    keywords = [t["keyword"] for t in trends]
+    assert "기준금리" in keywords
+    for t in trends:
+        assert t["category"] == "economy"
+        assert t["source"] == "naver_popular"
+        assert 0.0 <= t["score"] <= 1.0
+
+
+def test_collect_naver_writes_to_db(tmp_db, monkeypatch):
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = NAVER_RESPONSE
+    fake_resp.raise_for_status.return_value = None
+    with patch.object(trend_collector.requests, "get", return_value=fake_resp):
+        n = trend_collector.collect_naver_popular_for(["economy"])
+    assert n > 0
+    rows = db_module.list_trends(source="naver_popular")
+    assert len(rows) > 0
+    assert all(r["source"] == "naver_popular" for r in rows)
+
+
+def test_classify_keyword_with_cache(monkeypatch):
+    calls = {"n": 0}
+
+    def fake_claude(keyword: str) -> str:
+        calls["n"] += 1
+        return "economy"
+
+    monkeypatch.setattr(trend_collector, "_llm_classify_one", fake_claude)
+    trend_collector._category_cache.clear()
+
+    c1 = trend_collector.classify_keyword("기준금리")
+    c2 = trend_collector.classify_keyword("기준금리")
+    assert c1 == c2 == "economy"
+    assert calls["n"] == 1
+
+
+def test_fetch_youtube_trending_parses_and_cleans_titles(tmp_db, monkeypatch):
+    """YouTube Data API mostPopular 응답 → 제목 정제 + 분류."""
+    monkeypatch.setattr(trend_collector, "YOUTUBE_DATA_API_KEY", "fake_key")
+    payload = {
+        "items": [
+            {"snippet": {"title": "[속보] 기준금리 인상 단행 🔥"}},
+            {"snippet": {"title": "(공식) BTS 컴백 무대 🎤"}},
+            {"snippet": {"title": "스트레스 관리 5가지 방법"}},
+            # 중복 제목 — 중복 제거 확인
+            {"snippet": {"title": "[속보] 기준금리 인상 단행 🔥"}},
+        ]
+    }
+    fake_resp = MagicMock()
+    fake_resp.json.return_value = payload
+    fake_resp.raise_for_status.return_value = None
+    monkeypatch.setattr(trend_collector.requests, "get", lambda *a, **kw: fake_resp)
+    monkeypatch.setattr(
+        trend_collector, "classify_keyword",
+        lambda kw: ("economy" if "금리" in kw else
+                    "celebrity" if "BTS" in kw else
+                    "psychology" if "스트레스" in kw else "uncategorized"),
+    )
+
+    trends = trend_collector.fetch_youtube_trending()
+    keywords = [t["keyword"] for t in trends]
+    assert "기준금리 인상 단행" in keywords  # 대괄호·이모지 제거
+    assert "BTS 컴백 무대" in keywords  # 괄호 제거
+    assert "스트레스 관리 5가지 방법" in keywords  # 그대로
+    assert len(trends) == 3  # 중복 제거됨
+    assert all(t["source"] == "youtube_trending" for t in trends)
+
+
+def test_fetch_youtube_trending_no_api_key_returns_empty(monkeypatch):
+    monkeypatch.setattr(trend_collector, "YOUTUBE_DATA_API_KEY", "")
+    out = trend_collector.fetch_youtube_trending()
+    assert out == []
+
+
+def test_fetch_youtube_trending_graceful_on_api_failure(monkeypatch):
+    monkeypatch.setattr(trend_collector, "YOUTUBE_DATA_API_KEY", "fake_key")
+    fake_resp = MagicMock()
+    fake_resp.raise_for_status.side_effect = RuntimeError("quota exceeded")
+    monkeypatch.setattr(trend_collector.requests, "get", lambda *a, **kw: fake_resp)
+    out = trend_collector.fetch_youtube_trending()
+    assert out == []
+
+
+def test_collect_all_invokes_both_sources(tmp_db, monkeypatch):
+    monkeypatch.setattr(trend_collector, "collect_naver_popular_for",
+                        lambda cats: 5)
+    monkeypatch.setattr(trend_collector, "collect_youtube_trending",
+                        lambda: 3)
+    out = trend_collector.collect_all(["economy"])
+    assert out == {"naver_popular": 5, "youtube_trending": 3}
+
+
+def test_seeds_for_filters_placeholder(tmp_db, monkeypatch):
+    """category_seeds 템플릿에 placeholder '...'가 들어가도 DEFAULT 폴백."""
+    from app import db as db_module
+    db_module.upsert_prompt_template(
+        "category_seeds",
+        '{"economy": ["...", "…", "a", "real_keyword"]}',
+        "test",
+    )
+    out = trend_collector._seeds_for("economy")
+    # '...', '…', 'a'(2자 미만)는 필터링되고 'real_keyword'만 남음
+    assert out == ["real_keyword"]
+
+
+def test_seeds_for_falls_back_when_all_invalid(tmp_db, monkeypatch):
+    """모든 시드가 invalid면 DEFAULT_CATEGORY_SEEDS 폴백."""
+    from app import db as db_module
+    db_module.upsert_prompt_template(
+        "category_seeds",
+        '{"economy": ["...", "TBD", ""]}',
+        "test",
+    )
+    out = trend_collector._seeds_for("economy")
+    # DEFAULT_CATEGORY_SEEDS["economy"] 가 반환되어야 함
+    from app.config import DEFAULT_CATEGORY_SEEDS
+    assert out == list(DEFAULT_CATEGORY_SEEDS["economy"])

lotto/app/db.py

@@ -9,8 +9,10 @@ DB_PATH = "/app/data/lotto.db"
 
 def _conn() -> sqlite3.Connection:
     os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
-    conn = sqlite3.connect(DB_PATH)
+    conn = sqlite3.connect(DB_PATH, timeout=120.0)
     conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=120000")
     return conn
 
 def _ensure_column(conn: sqlite3.Connection, table: str, col: str, ddl: str) -> None:
@@ -259,6 +261,45 @@ def init_db() -> None:
         """)
         conn.execute("CREATE INDEX IF NOT EXISTS idx_briefings_draw ON lotto_briefings(draw_no DESC)")
 
+        # ── weekly_review 테이블 (큐레이터 자기 평가 + 사용자 패턴 갭) ────────
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS weekly_review (
+                id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+                draw_no               INTEGER UNIQUE NOT NULL,
+                curator_avg_match     REAL,
+                curator_best_tier     TEXT,
+                curator_best_match    INTEGER,
+                curator_5plus_prizes  INTEGER,
+                user_avg_match        REAL,
+                user_best_match       INTEGER,
+                user_5plus_prizes     INTEGER,
+                user_pattern_summary  TEXT,
+                draw_pattern_summary  TEXT,
+                pattern_delta         TEXT,
+                created_at            TEXT NOT NULL DEFAULT (datetime('now','localtime'))
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_review_draw ON weekly_review(draw_no DESC)")
+
+        # ── lotto_briefings.picks 4계층 마이그레이션 (1회 변환) ───────────────
+        # 기존: picks가 JSON 리스트 [{numbers,risk_tag,reason}]
+        # 신규: picks가 JSON 객체 {core:[...], bonus:[], extended:[], pool:[]}
+        rows = conn.execute("SELECT id, picks FROM lotto_briefings").fetchall()
+        for r in rows:
+            try:
+                p = json.loads(r["picks"])
+                if isinstance(p, list):
+                    new_picks = {"core": p, "bonus": [], "extended": [], "pool": []}
+                    conn.execute(
+                        "UPDATE lotto_briefings SET picks=? WHERE id=?",
+                        (json.dumps(new_picks, ensure_ascii=False), r["id"]),
+                    )
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+        _ensure_column(conn, "lotto_briefings", "tier_rationale",
+                       "ALTER TABLE lotto_briefings ADD COLUMN tier_rationale TEXT NOT NULL DEFAULT '{}'")
+
 
 
 
@@ -952,39 +993,88 @@ def update_purchase_results(purchase_id: int, results: list, total_prize: int) -
         )
 
 
+def bulk_insert_purchases_from_briefing(draw_no: int, tier_mode: str, amount: int) -> Dict[str, Any]:
+    """tier_mode 에 해당하는 큐레이터 picks 를 purchase_history 에 일괄 INSERT.
+
+    tier_mode: "core" | "core_bonus" | "core_bonus_extended" | "full"
+    """
+    briefing = get_briefing(draw_no)
+    if not briefing:
+        return {"ok": False, "reason": "briefing not found"}
+
+    picks = briefing.get("picks") or {}
+    if isinstance(picks, list):
+        # 마이그레이션 이전 형태
+        picks = {"core": picks, "bonus": [], "extended": [], "pool": []}
+
+    tier_chain = {
+        "core": ["core"],
+        "core_bonus": ["core", "bonus"],
+        "core_bonus_extended": ["core", "bonus", "extended"],
+        "full": ["core", "bonus", "extended", "pool"],
+    }.get(tier_mode)
+    if not tier_chain:
+        return {"ok": False, "reason": f"unknown tier_mode: {tier_mode}"}
+
+    inserted_ids = []
+    with _conn() as conn:
+        for tier in tier_chain:
+            for idx, pick in enumerate(picks.get(tier) or []):
+                source_strategy = f"curator_{tier}"
+                source_detail = json.dumps({
+                    "tier": tier,
+                    "role": pick.get("risk_tag"),
+                    "set_index": idx,
+                    "draw_no": draw_no,
+                }, ensure_ascii=False)
+                numbers_json = json.dumps([pick.get("numbers")], ensure_ascii=False)
+                cur = conn.execute(
+                    """INSERT INTO purchase_history
+                       (draw_no, amount, sets, prize, note, numbers, is_real, source_strategy, source_detail)
+                       VALUES (?, ?, 1, 0, '', ?, 1, ?, ?)""",
+                    (draw_no, 1000, numbers_json, source_strategy, source_detail),
+                )
+                inserted_ids.append(cur.lastrowid)
+    return {"ok": True, "inserted_ids": inserted_ids, "sets": len(inserted_ids)}
+
+
 # --- Lotto Briefings ---
 
 def save_briefing(data: Dict[str, Any]) -> int:
+    picks_json = json.dumps(data["picks"], ensure_ascii=False)
+    narrative_json = json.dumps(data["narrative"], ensure_ascii=False)
+    tier_rationale_json = json.dumps(data.get("tier_rationale") or {}, ensure_ascii=False)
     with _conn() as conn:
-        cur = conn.execute("""
+        cur = conn.execute(
+            """
             INSERT INTO lotto_briefings
                 (draw_no, picks, narrative, confidence, model,
                  tokens_input, tokens_output, cache_read, cache_write,
-                 latency_ms, source)
-            VALUES (?,?,?,?,?,?,?,?,?,?,?)
+                 latency_ms, source, tier_rationale)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             ON CONFLICT(draw_no) DO UPDATE SET
-                picks=excluded.picks, narrative=excluded.narrative,
-                confidence=excluded.confidence, model=excluded.model,
+                picks=excluded.picks,
+                narrative=excluded.narrative,
+                confidence=excluded.confidence,
+                model=excluded.model,
                 tokens_input=excluded.tokens_input,
                 tokens_output=excluded.tokens_output,
                 cache_read=excluded.cache_read,
                 cache_write=excluded.cache_write,
                 latency_ms=excluded.latency_ms,
                 source=excluded.source,
+                tier_rationale=excluded.tier_rationale,
                 generated_at=datetime('now','localtime')
-        """, (
-            data["draw_no"],
-            json.dumps(data["picks"], ensure_ascii=False),
-            json.dumps(data["narrative"], ensure_ascii=False),
-            int(data["confidence"]),
-            data["model"],
-            int(data.get("tokens_input", 0)),
-            int(data.get("tokens_output", 0)),
-            int(data.get("cache_read", 0)),
-            int(data.get("cache_write", 0)),
-            int(data.get("latency_ms", 0)),
-            data.get("source", "auto"),
-        ))
+            """,
+            (
+                data["draw_no"], picks_json, narrative_json,
+                data["confidence"], data["model"],
+                data.get("tokens_input", 0), data.get("tokens_output", 0),
+                data.get("cache_read", 0), data.get("cache_write", 0),
+                data.get("latency_ms", 0), data.get("source", "auto"),
+                tier_rationale_json,
+            ),
+        )
         return cur.lastrowid
 
 
@@ -994,6 +1084,7 @@ def _briefing_row(r) -> Dict[str, Any]:
         "draw_no": r["draw_no"],
         "picks": json.loads(r["picks"]),
         "narrative": json.loads(r["narrative"]),
+        "tier_rationale": json.loads(r["tier_rationale"]) if r["tier_rationale"] else {},
         "confidence": r["confidence"],
         "model": r["model"],
         "tokens_input": r["tokens_input"],
@@ -1052,3 +1143,88 @@ def get_curator_usage(days: int = 30) -> Dict[str, Any]:
         "avg_latency_ms": round(float(r["avg_latency"] or 0), 1),
     }
 
+
+def save_review(data: Dict[str, Any]) -> int:
+    with _conn() as conn:
+        cur = conn.execute(
+            """
+            INSERT INTO weekly_review (
+                draw_no,
+                curator_avg_match, curator_best_tier, curator_best_match, curator_5plus_prizes,
+                user_avg_match, user_best_match, user_5plus_prizes,
+                user_pattern_summary, draw_pattern_summary, pattern_delta
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(draw_no) DO UPDATE SET
+                curator_avg_match=excluded.curator_avg_match,
+                curator_best_tier=excluded.curator_best_tier,
+                curator_best_match=excluded.curator_best_match,
+                curator_5plus_prizes=excluded.curator_5plus_prizes,
+                user_avg_match=excluded.user_avg_match,
+                user_best_match=excluded.user_best_match,
+                user_5plus_prizes=excluded.user_5plus_prizes,
+                user_pattern_summary=excluded.user_pattern_summary,
+                draw_pattern_summary=excluded.draw_pattern_summary,
+                pattern_delta=excluded.pattern_delta
+            """,
+            (
+                data["draw_no"],
+                data.get("curator_avg_match"), data.get("curator_best_tier"),
+                data.get("curator_best_match"), data.get("curator_5plus_prizes"),
+                data.get("user_avg_match"), data.get("user_best_match"),
+                data.get("user_5plus_prizes"),
+                data.get("user_pattern_summary"), data.get("draw_pattern_summary"),
+                data.get("pattern_delta"),
+            ),
+        )
+        return cur.lastrowid
+
+
+def _review_row(r) -> Optional[Dict[str, Any]]:
+    if not r:
+        return None
+    return {
+        "id": r["id"],
+        "draw_no": r["draw_no"],
+        "curator_avg_match": r["curator_avg_match"],
+        "curator_best_tier": r["curator_best_tier"],
+        "curator_best_match": r["curator_best_match"],
+        "curator_5plus_prizes": r["curator_5plus_prizes"],
+        "user_avg_match": r["user_avg_match"],
+        "user_best_match": r["user_best_match"],
+        "user_5plus_prizes": r["user_5plus_prizes"],
+        "user_pattern_summary": r["user_pattern_summary"],
+        "draw_pattern_summary": r["draw_pattern_summary"],
+        "pattern_delta": r["pattern_delta"],
+        "created_at": r["created_at"],
+    }
+
+
+def get_review(draw_no: int) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        r = conn.execute("SELECT * FROM weekly_review WHERE draw_no=?", (draw_no,)).fetchone()
+    return _review_row(r)
+
+
+def get_latest_review() -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        r = conn.execute("SELECT * FROM weekly_review ORDER BY draw_no DESC LIMIT 1").fetchone()
+    return _review_row(r)
+
+
+def get_reviews_range(start_drw: int, end_drw: int) -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT * FROM weekly_review WHERE draw_no BETWEEN ? AND ? ORDER BY draw_no ASC",
+            (start_drw, end_drw),
+        ).fetchall()
+    return [_review_row(r) for r in rows]
+
+
+def list_reviews(limit: int = 10) -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT * FROM weekly_review ORDER BY draw_no DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+    return [_review_row(r) for r in rows]
+

lotto/app/jobs/grade_weekly_review.py

@@ -0,0 +1,154 @@
+"""주간 회고 채점 통합 잡 — 일요일 03:00 KST 실행.
+
+1) 기존 purchase_manager.check_purchases_for_draw() 로 사용자 구매 자동 채점
+2) 큐레이터 4계층 picks vs 추첨 결과 비교
+3) 패턴 요약·갭 계산
+4) weekly_review UPSERT
+5) 4등 이상 발견 시 agent-office webhook 호출
+"""
+import json
+import logging
+import os
+from typing import Optional
+
+import httpx
+
+from .. import db
+from ..purchase_manager import check_purchases_for_draw
+from .grading_helpers import (
+    score_picks_against_draw,
+    summarize_pattern,
+    aggregate_pattern_summaries,
+    compute_pattern_delta,
+)
+
+logger = logging.getLogger("lotto-backend")
+
+AGENT_OFFICE_URL = os.environ.get("AGENT_OFFICE_URL", "http://agent-office:8000")
+
+
+def _flatten_curator_picks(briefing: dict) -> list:
+    """4계층 picks 를 모두 합쳐 단일 리스트(score 계산용)."""
+    picks = briefing.get("picks") or {}
+    if isinstance(picks, list):
+        return picks
+    out = []
+    for tier in ("core", "bonus", "extended", "pool"):
+        out.extend(picks.get(tier) or [])
+    return out
+
+
+def _curator_score(briefing: dict, win_nums: list, bonus: int) -> dict:
+    if not briefing:
+        return {}
+    flat = _flatten_curator_picks(briefing)
+    if not flat:
+        return {}
+    return score_picks_against_draw(flat, win_nums, bonus)
+
+
+def _user_score(drw_no: int, win_nums: list) -> dict:
+    purchases = db.get_purchases(draw_no=drw_no)
+    if not purchases:
+        return {}
+    matches = []
+    win_set = set(win_nums)
+    pattern_summaries = []
+    for p in purchases:
+        for nums in (p.get("numbers") or []):
+            if not nums:
+                continue
+            m = len(set(nums) & win_set)
+            matches.append(m)
+            pattern_summaries.append(summarize_pattern(nums))
+    if not matches:
+        return {}
+    return {
+        "avg_match": round(sum(matches) / len(matches), 2),
+        "best_match": max(matches),
+        "five_plus_prizes": sum(1 for m in matches if m >= 3),
+        "pattern_avg": aggregate_pattern_summaries(pattern_summaries),
+    }
+
+
+def _trigger_prize_alert(drw_no: int, match_count: int, numbers: list, purchase_id: int) -> None:
+    try:
+        with httpx.Client(timeout=10) as client:
+            client.post(
+                f"{AGENT_OFFICE_URL}/api/agent-office/notify/lotto-prize",
+                json={
+                    "draw_no": drw_no,
+                    "match_count": match_count,
+                    "numbers": numbers,
+                    "purchase_id": purchase_id,
+                },
+            )
+    except Exception as e:
+        logger.warning(f"[grade_weekly_review] prize alert webhook failed: {e}")
+
+
+def run_weekly_grading(drw_no: int) -> dict:
+    """주어진 회차에 대해 채점 잡 1회 실행. 멱등."""
+    draw = db.get_draw(drw_no)
+    if not draw:
+        logger.warning(f"[grade_weekly_review] draw {drw_no} not found, skip")
+        return {"ok": False, "reason": "no draw"}
+
+    win_nums = [draw["n1"], draw["n2"], draw["n3"], draw["n4"], draw["n5"], draw["n6"]]
+    bonus = draw["bonus"]
+
+    # 1) 사용자 구매 자동 채점 (기존 인프라)
+    try:
+        check_purchases_for_draw(drw_no)
+    except Exception as e:
+        logger.warning(f"[grade_weekly_review] check_purchases_for_draw failed: {e}")
+
+    # 2) 4등 이상 발견 시 webhook
+    purchases = db.get_purchases(draw_no=drw_no, checked=True)
+    for p in purchases:
+        for r in (p.get("results") or []):
+            if r.get("correct", 0) >= 4:
+                _trigger_prize_alert(drw_no, r["correct"], r["numbers"], p["id"])
+
+    # 3) 큐레이터 자기 평가
+    briefing = db.get_briefing(drw_no)
+    cur = _curator_score(briefing, win_nums, bonus)
+
+    # 4) 사용자 평가 (재로드, 구매가 다 채점된 후 패턴 계산)
+    usr = _user_score(drw_no, win_nums)
+
+    # 5) 추첨 패턴 요약 + 델타
+    draw_summary = summarize_pattern(win_nums)
+    draw_pattern = {
+        "low_avg": draw_summary["low_count"],
+        "odd_avg": draw_summary["odd_count"],
+        "sum_avg": draw_summary["sum"],
+    }
+    user_pattern = usr.get("pattern_avg", {})
+    delta = compute_pattern_delta(user_pattern, draw_pattern) if user_pattern else ""
+
+    # 6) UPSERT
+    payload = {
+        "draw_no": drw_no,
+        "curator_avg_match": cur.get("avg_match"),
+        "curator_best_tier": cur.get("best_tier"),
+        "curator_best_match": cur.get("best_match"),
+        "curator_5plus_prizes": cur.get("five_plus_prizes"),
+        "user_avg_match": usr.get("avg_match"),
+        "user_best_match": usr.get("best_match"),
+        "user_5plus_prizes": usr.get("five_plus_prizes"),
+        "user_pattern_summary": json.dumps(user_pattern, ensure_ascii=False) if user_pattern else None,
+        "draw_pattern_summary": json.dumps(draw_pattern, ensure_ascii=False),
+        "pattern_delta": delta,
+    }
+    rid = db.save_review(payload)
+    logger.info(f"[grade_weekly_review] saved review id={rid} for draw {drw_no}")
+    return {"ok": True, "review_id": rid}
+
+
+def run_for_latest() -> dict:
+    """가장 최근 sync된 추첨 회차로 채점 — cron 진입점."""
+    latest = db.get_latest_draw()
+    if not latest:
+        return {"ok": False, "reason": "no draws"}
+    return run_weekly_grading(latest["drw_no"])

lotto/app/jobs/grading_helpers.py

@@ -0,0 +1,93 @@
+"""채점 보조 — 일치 수 계산, 패턴 요약, 패턴 갭."""
+from typing import List, Dict, Any
+
+LOW_HIGH_CUT = 22  # curator_helpers.py 와 동일
+
+
+def score_picks_against_draw(picks: List[Dict[str, Any]],
+                              win_nums: List[int],
+                              bonus: int) -> Dict[str, Any]:
+    """4계층 중 한 그룹(예: core_picks 5세트) vs 추첨 결과 채점.
+
+    picks 는 [{numbers, risk_tag, reason}] 리스트.
+    """
+    if not picks:
+        return {"avg_match": None, "best_match": 0, "five_plus_prizes": 0, "best_tier": None}
+
+    win_set = set(win_nums)
+    matches = []
+    for p in picks:
+        nums = p.get("numbers") or []
+        m = len(set(nums) & win_set)
+        matches.append((m, p.get("risk_tag")))
+
+    avg = sum(m for m, _ in matches) / len(matches)
+    best_match, best_tier = max(matches, key=lambda x: x[0])
+    five_plus = sum(1 for m, _ in matches if m >= 3)  # 5등 이상
+
+    # tier별 평균 → 가장 잘 맞은 risk_tag
+    tier_scores: Dict[str, List[int]] = {}
+    for m, t in matches:
+        if t:
+            tier_scores.setdefault(t, []).append(m)
+    if tier_scores:
+        best_tier = max(tier_scores.items(),
+                        key=lambda kv: sum(kv[1]) / len(kv[1]))[0]
+
+    return {
+        "avg_match": round(avg, 2),
+        "best_match": best_match,
+        "five_plus_prizes": five_plus,
+        "best_tier": best_tier,
+    }
+
+
+def summarize_pattern(nums: List[int]) -> Dict[str, int]:
+    """한 세트의 패턴 요약 — 저/고, 홀/짝, 합계."""
+    nums = sorted(nums)
+    odd = sum(1 for n in nums if n % 2 == 1)
+    low = sum(1 for n in nums if n <= LOW_HIGH_CUT)
+    return {
+        "odd_count": odd,
+        "even_count": 6 - odd,
+        "low_count": low,
+        "high_count": 6 - low,
+        "sum": sum(nums),
+    }
+
+
+def aggregate_pattern_summaries(summaries: List[Dict[str, int]]) -> Dict[str, float]:
+    """여러 세트의 패턴 요약 → 평균(low_avg, odd_avg, sum_avg)."""
+    if not summaries:
+        return {"low_avg": None, "odd_avg": None, "sum_avg": None}
+    n = len(summaries)
+    return {
+        "low_avg": round(sum(s["low_count"] for s in summaries) / n, 2),
+        "odd_avg": round(sum(s["odd_count"] for s in summaries) / n, 2),
+        "sum_avg": round(sum(s["sum"] for s in summaries) / n, 1),
+    }
+
+
+def compute_pattern_delta(user_summary: Dict[str, float],
+                          draw_summary: Dict[str, float]) -> str:
+    """사용자 평균 vs 추첨 패턴의 가장 큰 격차 1~2개를 한 줄로."""
+    if not user_summary or user_summary.get("low_avg") is None:
+        return ""
+    deltas = []
+    if user_summary.get("low_avg") is not None and draw_summary.get("low_avg") is not None:
+        d = round(user_summary["low_avg"] - draw_summary["low_avg"], 2)
+        if abs(d) >= 0.5:
+            sign = "+" if d > 0 else ""
+            deltas.append(("저번호", d, f"저번호 편향 {sign}{d}"))
+    if user_summary.get("sum_avg") is not None and draw_summary.get("sum_avg") is not None:
+        d = round(user_summary["sum_avg"] - draw_summary["sum_avg"], 1)
+        if abs(d) >= 10:
+            sign = "+" if d > 0 else ""
+            deltas.append(("합계", d, f"합계 {sign}{d}"))
+    if user_summary.get("odd_avg") is not None and draw_summary.get("odd_avg") is not None:
+        d = round(user_summary["odd_avg"] - draw_summary["odd_avg"], 2)
+        if abs(d) >= 0.5:
+            sign = "+" if d > 0 else ""
+            deltas.append(("홀짝", d, f"홀짝 {sign}{d}"))
+    deltas.sort(key=lambda x: -abs(x[1]))
+    return " / ".join(d[2] for d in deltas[:2])

lotto/app/main.py

@@ -19,6 +19,7 @@ from .db import (
     get_recommendation_performance,
     # Phase 2: 구매 이력
     add_purchase, get_purchases, update_purchase, delete_purchase, get_purchase_stats,
+    bulk_insert_purchases_from_briefing,
     # Phase 2: 주간 리포트 캐시
     save_weekly_report, get_weekly_report_list, get_weekly_report,
     # Phase 2: 개인 패턴 분석
@@ -39,10 +40,13 @@ from .strategy_evolver import (
 )
 from .routers import curator as curator_router
 from .routers import briefing as briefing_router
+from .routers import review as review_router
+from .jobs.grade_weekly_review import run_for_latest as grade_run_for_latest
 
 app = FastAPI()
 app.include_router(curator_router.router)
 app.include_router(briefing_router.router)
+app.include_router(review_router.router)
 scheduler = BackgroundScheduler(timezone=os.getenv("TZ", "Asia/Seoul"))
 
 ALL_URL = os.getenv("LOTTO_ALL_URL", "https://smok95.github.io/lotto/results/all.json")
@@ -95,6 +99,17 @@ def on_startup():
 
     scheduler.add_job(_save_weekly_report_job, "cron", day_of_week="sat", hour=9, minute=0)
 
+    # 4. 주간 채점 (매주 일요일 03:00 KST — 토요일 추첨 다음날 새벽)
+    #    당첨번호 sync 이후 추천 vs 실제 결과 비교 → reviews 테이블 저장
+    scheduler.add_job(
+        grade_run_for_latest,
+        "cron",
+        day_of_week="sun",
+        hour=3,
+        minute=0,
+        id="grade_weekly_review",
+    )
+
     scheduler.start()
 
 
@@ -329,6 +344,22 @@ def api_purchase_delete(purchase_id: int):
     return {"ok": True}
 
 
+class BulkPurchaseRequest(BaseModel):
+    draw_no: int
+    tier_mode: str  # core | core_bonus | core_bonus_extended | full
+    sets: int       # 검증용 — 실제 INSERT는 briefing 기준
+    amount: int     # 검증용
+
+
+@app.post("/api/lotto/purchase/bulk", status_code=201)
+def api_purchase_bulk(body: BulkPurchaseRequest):
+    """결정카드 원클릭 기록 — 큐레이터 브리핑 picks 를 tier_mode 기준으로 일괄 기록."""
+    result = bulk_insert_purchases_from_briefing(body.draw_no, body.tier_mode, body.amount)
+    if not result["ok"]:
+        raise HTTPException(status_code=400, detail=result["reason"])
+    return result
+
+
 # ── 전략 진화 API ──────────────────────────────────────────────────────────
 
 @app.get("/api/lotto/strategy/weights")

lotto/app/requirements.txt

@@ -1,5 +1,6 @@
 fastapi==0.115.6
 uvicorn[standard]==0.30.6
 requests==2.32.3
+httpx==0.27.2
 beautifulsoup4==4.12.3
 APScheduler==3.10.4

lotto/app/routers/briefing.py

@@ -7,10 +7,24 @@ from .. import db
 router = APIRouter(prefix="/api/lotto")
 
 
+class TierRationale(BaseModel):
+    bonus: str = ""
+    extended: str = ""
+    pool: str = ""
+
+
+class BriefingPicks(BaseModel):
+    core: List[Dict[str, Any]] = Field(default_factory=list)
+    bonus: List[Dict[str, Any]] = Field(default_factory=list)
+    extended: List[Dict[str, Any]] = Field(default_factory=list)
+    pool: List[Dict[str, Any]] = Field(default_factory=list)
+
+
 class BriefingRequest(BaseModel):
     draw_no: int
-    picks: List[Dict[str, Any]]
+    picks: BriefingPicks
     narrative: Dict[str, Any]
+    tier_rationale: TierRationale = Field(default_factory=TierRationale)
     confidence: int = Field(ge=0, le=100)
     model: str
     tokens_input: int = 0

lotto/app/routers/review.py

@@ -0,0 +1,26 @@
+"""주간 회고(weekly_review) 조회 엔드포인트."""
+from fastapi import APIRouter, HTTPException
+from .. import db
+
+router = APIRouter(prefix="/api/lotto/review")
+
+
+@router.get("/latest")
+def latest():
+    r = db.get_latest_review()
+    if not r:
+        raise HTTPException(404, "no review yet")
+    return r
+
+
+@router.get("/history")
+def history(limit: int = 10):
+    return {"reviews": db.list_reviews(limit)}
+
+
+@router.get("/{draw_no}")
+def get_one(draw_no: int):
+    r = db.get_review(draw_no)
+    if not r:
+        raise HTTPException(404, f"no review for draw {draw_no}")
+    return r

lotto/docs/operations-week1.md

@@ -0,0 +1,28 @@
+# Lotto Curator Evolution — 1주차 운영 점검
+
+## 일요일 (추첨 다음날)
+- [ ] 03:05 KST: lotto-backend 로그에 `[grade_weekly_review] saved review id=N` 출력 확인
+- [ ] `curl http://localhost:18000/api/lotto/review/latest` → JSON 정상
+- [ ] purchase_history 의 직전 회차 행이 `checked=1`, `total_prize` 채워졌는지
+
+## 월요일
+- [ ] 09:05 KST: agent-office 로그에 `큐레이션 완료: #NNNN` + `[telegram_lotto] briefing` 출력
+- [ ] 텔레그램 봇 채팅에 헤드라인 알림 도착 (회고 단락 포함/생략 정확)
+- [ ] `curl http://localhost:18000/api/lotto/briefing/latest` → 4계층 picks(core/bonus/extended/pool 각 5세트) + tier_rationale + narrative.retrospective
+
+## 사이트 확인
+- [ ] http://localhost:3007/lotto 브리핑 탭 결정 카드 정상 렌더
+- [ ] 모드 토글 4단계 동작 (5/10/15/20 펼침/접힘)
+- [ ] localStorage `lotto.tier_mode` 마지막 선택 기억 (새로고침 후 유지)
+- [ ] "이대로 N세트 구매" 클릭 → 토스트 + 구매탭 갱신
+- [ ] 자료실 탭 첫 진입 시 모든 패널 접힘
+- [ ] 구매탭 추세 차트 1주차에는 점 1개, 2주차부터 라인 형성
+
+## 실패 케이스
+- [ ] 큐레이션 실패(Anthropic API 다운): agent-office 로그 + lotto_agent state=idle, 에러 텔레그램
+- [ ] 4등 이상 발견: 별도 텔레그램 푸시 도착 (3개 이하만 있으면 미발송)
+- [ ] briefing 없는 회차에 bulk purchase 시도: 400 응답, 토스트 표시
+
+## cron 시간 조정 (필요 시)
+- 채점 잡: `lotto/app/main.py` 의 `scheduler.add_job(grade_run_for_latest, "cron", day_of_week="sun", hour=3, minute=0)`
+- 큐레이션: `agent-office/app/scheduler.py` `add_job(_run_lotto_schedule, ..., hour=9, minute=0)`

lotto/tests/test_briefing_4tier.py

@@ -0,0 +1,52 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import pytest
+from app import db
+
+
+@pytest.fixture(autouse=True)
+def setup_db(tmp_path, monkeypatch):
+    test_db = tmp_path / "test.db"
+    monkeypatch.setattr(db, "DB_PATH", str(test_db))
+    db.init_db()
+    yield
+
+
+def test_save_briefing_4tier_roundtrip():
+    payload = {
+        "draw_no": 9999,
+        "picks": {"core":[{"numbers":[1,2,3,4,5,6],"risk_tag":"안정","reason":"x"}],
+                  "bonus":[], "extended":[], "pool":[]},
+        "narrative": {"headline":"H","summary_3lines":["a","b","c"],"retrospective":"r"},
+        "tier_rationale": {"bonus":"b1","extended":"e1","pool":"p1"},
+        "confidence": 70,
+        "model": "test",
+    }
+    bid = db.save_briefing(payload)
+    assert bid > 0
+    got = db.get_briefing(9999)
+    assert got["picks"]["core"][0]["numbers"] == [1,2,3,4,5,6]
+    assert got["tier_rationale"]["bonus"] == "b1"
+    assert got["narrative"]["retrospective"] == "r"
+
+
+def test_save_briefing_upsert_overwrites():
+    db.save_briefing({
+        "draw_no": 8888,
+        "picks": {"core":[], "bonus":[], "extended":[], "pool":[]},
+        "narrative": {"headline":"old","summary_3lines":["a","b","c"]},
+        "confidence": 50, "model": "v1",
+    })
+    db.save_briefing({
+        "draw_no": 8888,
+        "picks": {"core":[{"numbers":[10,20,30,40,41,42],"risk_tag":"공격","reason":"y"}],
+                  "bonus":[], "extended":[], "pool":[]},
+        "narrative": {"headline":"new","summary_3lines":["x","y","z"]},
+        "tier_rationale": {"bonus":"","extended":"","pool":""},
+        "confidence": 90, "model": "v2",
+    })
+    got = db.get_briefing(8888)
+    assert got["narrative"]["headline"] == "new"
+    assert got["confidence"] == 90
+    assert got["picks"]["core"][0]["risk_tag"] == "공격"