merge: 인스타 카드뉴스 품질 고도화 + zip 패키지 (Phase 1-5)

모던 미니멀 디자인 시스템 템플릿 + 카피 글자수 가이드 + zip 패키지 다운로드 API.
(렌더 견고화·템플릿 authoritative는 web-ai repo)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.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
@@ -119,5 +124,6 @@ PACK_DATA_PATH=./data/packs
 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
+# 운영 NAS는 반드시 /volume1/docker/webpage/media/packs 같은 절대경로 설정.
+# 미설정 시 PACK_DATA_PATH로 fallback (로컬 개발용).
+PACK_HOST_DIR=/docker/webpage/media/packs

.gitignore

@@ -66,3 +66,11 @@ temp/
 
 # Git worktrees
 .worktrees/
+
+################################
+# Local working files
+################################
+# Superpowers 스킬 캐시·세션 메타
+.superpowers/
+# 임시 코드 리뷰 노트 (작업 끝나면 폐기 또는 docs/로 이동)
+CODE_REVIEW.md

CHECK_POINT.md

@@ -0,0 +1,209 @@
+# web-backend CHECK_POINT
+
+> NAS Docker 11 컨테이너(9 백엔드 + frontend + deployer). Synology Celeron J4025 (2C 2.0GHz) 18GB.
+> 2026-05-18 작성 — uvicorn CPU 폭주 진단 결과 정리.
+
+## 🔴 즉시 (오늘, 총 1시간 5분)
+
+### 1. 09:00 cron 5분 스태거링 ⭐ 가장 큰 효과
+
+**파일**: `agent-office/app/scheduler.py:72-76`
+```python
+# 변경 전 — 09:00 동시 실행 (CPU 폭주 원인 #1)
+scheduler.add_job(_run_insta_trends_collect, "cron", hour=9, minute=0)
+scheduler.add_job(_run_lotto_schedule, "cron", day_of_week="mon", hour=9, minute=0)
+scheduler.add_job(_run_youtube_research, "cron", hour=9, minute=0)
+
+# 변경 후 — 5분 스태거링
+scheduler.add_job(_run_insta_trends_collect, "cron", hour=9, minute=0,  id="insta_trends")
+scheduler.add_job(_run_lotto_schedule,       "cron", day_of_week="mon", hour=9, minute=5, id="lotto_curate")
+scheduler.add_job(_run_youtube_research,     "cron", hour=9, minute=10, id="youtube_research")
+```
+
+**파일**: `realestate-lab/app/main.py:51`
+```python
+# 변경 전
+scheduler.add_job(scheduled_collect, "cron", hour=9, minute=0, id="collect")
+
+# 변경 후
+scheduler.add_job(scheduled_collect, "cron", hour=9, minute=15, id="collect")
+```
+
+- [x] agent-office scheduler.py 수정 (2026-05-18)
+- [x] realestate-lab main.py 수정 (2026-05-18)
+- [ ] git commit + push (Gitea Webhook 자동 빌드)
+
+---
+
+### 2. insta-lab Playwright Semaphore(1) ⭐
+
+**파일**: `insta-lab/app/main.py` (모듈 레벨 추가)
+```python
+import asyncio
+
+# 모듈 레벨에 한 번만 선언
+RENDER_SEMAPHORE = asyncio.Semaphore(1)  # Chromium 동시 실행 1개로 제한
+
+# 카드 렌더 백그라운드 함수에 감싸기
+async def _bg_render(task_id: str, slate_id: int):
+    async with RENDER_SEMAPHORE:
+        await card_renderer.render_slate(slate_id, ...)
+```
+
+- [x] card_renderer.render_slate를 Semaphore(1)로 감쌈 (2026-05-18, lazy init)
+- [ ] 동시 2개 요청 테스트 (curl 동시 2회 → 순차 처리되는지 확인)
+
+---
+
+### 3. healthcheck interval 60s
+
+**파일**: `docker-compose.yml` (모든 9 컨테이너)
+```yaml
+# 변경 전
+healthcheck:
+  interval: 30s
+
+# 변경 후
+healthcheck:
+  interval: 60s
+```
+
+- [x] docker-compose.yml 10개 healthcheck 일괄 변경 (9 백엔드 + frontend, 2026-05-18)
+- [ ] `docker compose up -d` 재기동
+- [ ] `docker stats` 로 CPU 5% 정도 감소 확인
+
+---
+
+### 4. uvicorn --workers 1 명시
+
+**모든 Dockerfile CMD**:
+```dockerfile
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
+```
+
+영향 9 파일 (모두 2026-05-18 적용):
+- [x] lotto/Dockerfile
+- [x] stock/Dockerfile
+- [x] music-lab/Dockerfile
+- [x] insta-lab/Dockerfile
+- [x] realestate-lab/Dockerfile
+- [x] agent-office/Dockerfile
+- [x] personal/Dockerfile
+- [x] packs-lab/Dockerfile
+- [x] travel-proxy/Dockerfile
+
+→ `docker compose build --no-cache` 후 재기동.
+
+---
+
+### 5. lotto Monte Carlo 08:05 → 08:30
+
+**파일**: `lotto/app/main.py:86`
+```python
+# 변경 전 — stock 08:00과 5분 차이로 겹침
+scheduler.add_job(_run_simulation_job, "cron", hour="0,4,8,12,16,20", minute=5)
+
+# 변경 후 — 25분 분리
+scheduler.add_job(_run_simulation_job, "cron", hour="0,4,8,12,16,20", minute=30)
+```
+
+- [x] lotto/app/main.py 수정 (2026-05-18)
+
+---
+
+## 🟡 중기 (1~2주)
+
+### 6. Chromium Browser Pool 재설계 (insta-lab) ✅ 2026-05-18
+- 매번 launch X → 1개 인스턴스 재사용
+- 카드 10장 렌더 시간 30% 단축 기대
+- [x] `card_renderer.py` 내부에 모듈 레벨 `_PLAYWRIGHT`/`_BROWSER` + `init_browser`/`shutdown_browser` 함수 (별도 모듈 분리 안 함, 같은 파일에 인접 배치)
+- [x] `_render_slate_locked` 본체에서 `_get_browser()` 재사용 (crashed 시 lazy 재초기화)
+- [x] `main.py` startup hook에서 `init_browser()`, shutdown hook에서 `shutdown_browser()`
+
+### 7. stock 뉴스 스크랩 비동기화 — ⚠️ 보류 2026-05-18
+- **재진단**: stock은 `BackgroundScheduler` 사용 중 → main loop 블로킹 없음 (이미 별도 thread)
+- `fetch_market_news`의 4개 동기 `requests.get`은 network I/O wait라 CPU 거의 사용 안 함
+- `to_thread`로 wrap해도 BackgroundScheduler 환경에서 사실상 의미 없음
+- 진짜 효과를 보려면 AsyncIOScheduler 전환 + scraper.py 4개 fetch를 `aiohttp` 병렬로 — **큰 리팩토링 vs 효과 불명확**
+- [ ] 박재오 판단: 큰 리팩토링 진행 여부
+
+### 8. realestate 수집 병렬화 ✅ 2026-05-18
+- **파일**: `realestate-lab/app/main.py:scheduled_collect`
+- `collect_all()` + `delete_old_completed_announcements()` 병렬
+- BackgroundScheduler 환경이라 `asyncio.gather` 대신 `ThreadPoolExecutor(max_workers=2)` 사용 (효과 동일)
+- 매칭은 순차 유지 (DB 일관성)
+- [x] ThreadPoolExecutor 적용
+
+### 9. lotto Monte Carlo 시뮬레이션 빈도 검토
+- 현재 6회/일 (00·04·08·12·16·20)
+- 실제 필요 빈도 박재오 결정 — 3회/일(아침·점심·저녁)로 줄이면 CPU 50% 감소
+- [ ] 박재오 의사결정 후 cron 변경
+
+---
+
+## 🟢 장기 (1개월+)
+
+### 10. 무거운 작업 Windows AI 서버로 이전 ✅ 이미 적용 상태 (2026-05-18 확인)
+- **확인 결과**: NAS `.env`가 이미 `LLM_PROVIDER=claude` + `OLLAMA_URL=http://192.168.45.59:11435`로 설정됨
+- 실 운영은 Anthropic Claude (원격 API) — NAS Celeron에서 LLM 추론 안 함
+- Ollama fallback 사용 시에도 Windows AI 서버로 통일
+- stock 외 다른 컨테이너에 ollama/qwen 호출 코드 없음
+- 결론: 코드/설정 변경 불필요
+
+### 11. 컨테이너 리소스 제한 — ❌ 진행 금지 (박재오 명시 2026-05-18)
+- J4025 2C 환경에서 cpus 0.5 제한은 오히려 throughput 손해
+- 향후 작업자 무심코 도입하지 말 것
+
+### 12. NAS 업그레이드 검토 — ⏸️ 보류 (박재오 명시 2026-05-18)
+- 현재: Celeron J4025 (2C 2.0GHz)
+- 대안: Ryzen N5105 (4C 2.0GHz) NAS — 4코어로 병렬성 2배
+- 자금·우선순위 결정 대기
+
+---
+
+## ✅ 최근 완료 (참고)
+
+- 2026-05-15: insta-lab 신설 (포트 18700, Jinja2 + Playwright + Claude Sonnet)
+- 2026-05-16: insta-lab Playwright 1080×1350 PNG 렌더 완성
+- 2026-05-17: agent-office random idle 제거, ADMIN_API_KEY 강화 (stock)
+- 2026-05-17: insta-lab minimal theme + design_importer 추가
+- 2026-05-17: blog-lab 트랙 완전 폐기 (docker-compose에 없음, 위키 정정 완료)
+- 2026-05-18: 🔴 즉시 5건 일괄 적용 — 09:00 cron 스태거링(insta/lotto/youtube/realestate), lotto Monte Carlo 08:30, insta-lab Semaphore(1), healthcheck 60s, uvicorn --workers 1 명시 (사용자 push + NAS deployer 재기동 대기)
+- 2026-05-18: 🟡 중기 2건 적용 — #6 insta-lab Chromium Browser Pool (lifecycle hook), #8 realestate ThreadPoolExecutor 병렬 (collect/delete). #7 stock async는 BackgroundScheduler 사용 중이라 재진단 후 보류 (효과 미미). #9 Monte Carlo 빈도는 박재오 결정 대기.
+- 2026-05-18: 🟢 장기 진단·결정 — #10은 이미 적용 상태 확인 (LLM_PROVIDER=claude, OLLAMA_URL=Windows AI). #11 컨테이너 리소스 제한 박재오 진행 금지. #12 NAS 업그레이드 보류. web-ai V1(:8000)+V2(:8001) 4개 process 종료 — NAS API polling 부담 즉시 감소.
+
+---
+
+## 🔧 진단 커맨드 (NAS bash)
+
+```bash
+# 실시간 CPU 사용 (상위 15)
+top -b -n 1 | head -25
+
+# 프로세스별 CPU 정렬
+ps aux --sort=-%cpu | head -15
+
+# uvicorn·chromium·python 프로세스만
+ps aux | grep -E "uvicorn|chromium|python" | grep -v grep
+
+# 스케줄러 실행 로그 (최근 50)
+docker logs agent-office 2>&1 | grep -E "APScheduler|executing" | tail -50
+
+# insta-lab Chromium 프로세스 개수
+docker exec insta-lab ps aux | grep chromium | wc -l
+
+# 컨테이너별 CPU/메모리 실시간
+docker stats --no-stream
+```
+
+---
+
+## 📚 참고
+
+- 진단 풀 보고서: `C:\Users\jaeoh\Documents\Obsidian Vault\raw\2026-05-18-NAS-uvicorn-CPU-진단-개선안.md`
+- 위키 페이지: [[사업-개인-웹-플랫폼]] (CPU 부하 진단 섹션 + 컨테이너 표)
+- docker-compose.yml: 본 디렉토리 루트
+
+## 변경 이력
+
+- 2026-05-18: 페이지 신설. 즉시 5건 + 중기 4건 + 장기 3건. 진단 커맨드.

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 |
 
@@ -164,10 +164,16 @@ docker compose up -d
 | `lotto_briefings` | AI 큐레이터 주간 브리핑 (5세트 + 내러티브 + 토큰·비용 집계) |
 | `todos` | 투두리스트 (UUID PK) — personal 서비스로 이전됨, 레거시 테이블 유지 |
 | `blog_posts` | 블로그 글 (tags: JSON 배열) — personal 서비스로 이전됨, 레거시 테이블 유지 |
+| `weight_trials` | 주별 6일치 후보 가중치 (4 perturb + 2 dirichlet) |
+| `auto_picks` | 매일 N=5 시도 번호 + 채점 결과 |
+| `weight_base_history` | base 갱신 이력 (winner_4plus / ema_blend / unchanged / cold_start) |
 
 **스케줄러 job**
 - 09:10 / 21:10 매일 — 당첨번호 동기화 + 채점 (`sync_latest` → `check_results_for_draw`)
 - 00:05, 04:05, 08:05, 12:05, 16:05, 20:05 — 몬테카를로 시뮬레이션 (20,000후보 → 상위100 → best_picks 20개 교체)
+- 월요일 09:00 — weight_evolver_weekly (6개 후보 생성 + 그날 N=5 추출)
+- 매일 09:00 — weight_evolver_daily (월요일 제외, 오늘 W로 N=5 추출)
+- 토요일 22:00 — weight_evolver_eval (회고 + 다음주 base 갱신)
 
 **lotto-lab API 목록**
 
@@ -204,15 +210,20 @@ docker compose up -d
 | GET | `/api/lotto/briefing/latest` | 최신 브리핑 |
 | GET | `/api/lotto/briefing/{draw_no}` | 특정 회차 브리핑 |
 | GET | `/api/lotto/briefing` | 브리핑 이력 |
+| GET | `/api/lotto/evolver/status` | weight_evolver 이번주 trials + current_base + 진행 상황 |
+| GET | `/api/lotto/evolver/history?weeks=12` | base 변경 이력 |
+| GET | `/api/lotto/evolver/trials/{week_start}` | 특정 주 6 trials + 채점 결과 |
+| POST | `/api/lotto/evolver/generate-now` | 수동 트리거 — 이번주 후보 생성 |
+| POST | `/api/lotto/evolver/evaluate-now` | 수동 회고 + 다음주 base 갱신 |
 
-### 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 +465,81 @@ 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`)
+- `INSTA_DEFAULT_THEME`: 카드 렌더에 사용할 theme 디렉토리명 (기본 `default`). `templates/<theme>/card.html.j2`가 없으면 자동으로 default 폴백
+- `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위 키워드 자동 슬레이트 생성·발송
+
+**디자인 import (사용자 디자인 PNG → Claude Vision → Jinja HTML 자동 생성)**
+- `insta-lab/app/templates/<theme>/pages/*.png` (10장, 4:5 비율 권장 1080×1350, placeholder 텍스트 박혀있는 형태) → Claude Sonnet Vision → `templates/<theme>/card.html.j2` 자동 생성
+- 파일명 자동 매핑: `cover`/`start`/`intro` → page 1, `cta`/`outro`/`finish`/`end` → page 10, 나머지 알파벳 순 → page 2~9
+- 매핑 override: `pages/_order.json`에 `{filename: page_no}` 명시 (10장 + page 1~10 완전 매핑일 때만 적용)
+- Vision prompt에 placeholder 마스킹 요구 포함 (2-layer: 마스킹 박스 + 동적 텍스트 layer)
+- 기존 HTML 자동 백업 (`card.html.j2.bak.YYYYMMDD-HHMMSS`)
+- Jinja 문법 깨진 응답은 `card.html.j2.error.txt`로 보존 + ValueError
+- 활성화: `.env`에 `INSTA_DEFAULT_THEME=<theme>` 추가 + `docker compose restart insta-lab` (테마 디렉토리에 `card.html.j2` 없으면 렌더러가 default로 폴백)
+- 토큰 비용: 1회당 ~15K tokens (~$0.05 Sonnet 기준)
+
+**⚠️ 실행 위치 — 로컬 권장, NAS docker exec 금지**
+- docker-compose의 insta-lab volume은 `/app/data`만 마운트. **`/app/app/templates`는 컨테이너 ephemeral state**.
+- NAS에서 `docker exec insta-lab python -m app.design_importer <theme>`로 돌리면 `card.html.j2`가 컨테이너 안에만 생성되고 다음 image rebuild(다른 push의 webhook이라도) 때 사라짐 → 렌더러가 default로 폴백.
+- **로컬 실행** (host repo working tree에 영속화 → git push → 자동 배포):
+  ```bash
+  cd insta-lab
+  pip install anthropic Pillow jinja2  # 이미 있으면 skip
+  export ANTHROPIC_API_KEY=sk-ant-...
+  python -m app.design_importer <theme> --templates-dir ./app/templates
+  git add app/templates/<theme>/card.html.j2
+  git commit -m "feat(insta-lab): <theme> 디자인 import"
+  git push  # → Gitea webhook → NAS rebuild → 영구 활성화
+  ```
+- 응급 hotfix로 NAS에서 돌렸다면 `docker cp insta-lab:/app/app/templates/<theme>/card.html.j2 ./` 후 즉시 host repo에 commit + push 필요
+
+**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 +549,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`)
@@ -537,6 +564,11 @@ docker compose up -d
 - `LOTTO_BACKEND_URL`: 기본 `http://lotto:8000`
 - `LOTTO_CURATOR_MODEL`: 기본 `claude-sonnet-4-5`
 - `YOUTUBE_DATA_API_KEY`: YouTube Data API v3 키 (미설정 시 YouTube trending 수집 skip)
+- `LOTTO_SIGNAL_WINDOW`: baseline 윈도우 크기 (기본 8)
+- `LOTTO_Z_NORMAL`: normal fire 임계치 (기본 1.5)
+- `LOTTO_Z_URGENT`: urgent fire 임계치 (기본 2.5)
+- `LOTTO_THROTTLE_HOURS`: 같은 메트릭 재발화 throttle (기본 6시간)
+- `LOTTO_URGENT_DAILY_MAX`: urgent 하루 cap (기본 3통)
 
 **YouTubeResearchAgent (`agents/youtube.py`)**
 - `agent_id = "youtube"` — AGENT_REGISTRY에 등록
@@ -561,6 +593,11 @@ docker compose up -d
 - ~~09:15 매일 — 청약 매칭 데일리 리포트~~ (Task 2026-04-28에서 폐기. realestate-lab의 push 트리거로 전환)
 - 09:00 매일 — YouTube 트렌드 수집 (`youtube_research`) → music-lab `/api/music/market/ingest` push
 - 매주 월요일 08:00 — YouTube 주간 리포트 텔레그램 발송 (`youtube_weekly_report`)
+- 09:15 매일 — 로또 light_check (시뮬·전략 가중치 평가)
+- 매 4시간 :15 — 로또 sim_check (00/04/08/12/16/20시)
+- 일/수 21:15 — 로또 deep_check (큐레이션 후 confidence 포함 평가)
+- 09:25 매일 — 로또 daily_digest (지난 24h 발화 텔레그램 1통)
+- 토요일 22:15 — 로또 weight_evolver 주간 텔레그램 리포트
 
 **RealestateAgent (`agents/realestate.py`)**
 - 진입점: `on_new_matches(matches: list[dict]) -> {sent, sent_ids, message_id}`
@@ -592,6 +629,9 @@ docker compose up -d
 | GET | `/api/agent-office/conversation/stats` | 텔레그램 자연어 대화 토큰·캐시 통계 (`days` 필터) |
 | POST | `/api/agent-office/youtube/research` | YouTube 트렌드 수집 수동 트리거 (body: `{countries: []}`) |
 | GET | `/api/agent-office/youtube/research/status` | 마지막 수집 작업 상태 |
+| GET | `/api/agent-office/lotto/signals?days=7` | 로또 능동 시그널 이력 (모든 fire_level) |
+| GET | `/api/agent-office/lotto/baselines` | 로또 메트릭별 baseline μ/σ + 윈도우 상태 |
+| POST | `/api/agent-office/lotto/signal-check?source=light` | 로또 시그널 평가 수동 트리거 (light/sim/deep) |
 
 ### personal (personal/)
 - 개인 서비스 (포트폴리오 + 블로그 + 투두 통합)
@@ -697,7 +737,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

@@ -1,7 +1,7 @@
 # web-backend
 
 Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
-로또 분석, 주식 포트폴리오, AI 음악 생성, 블로그 마케팅, 부동산 청약, AI 에이전트 오피스, 여행 앨범을 하나의 Docker Compose 스택으로 운영한다.
+로또 분석, 주식 포트폴리오, AI 음악 생성, 인스타 카드 피드, 부동산 청약, AI 에이전트 오피스, 여행 앨범, 개인 서비스(포트폴리오·블로그·투두), NAS 자료 다운로드 자동화를 하나의 Docker Compose 스택으로 운영한다.
 
 ---
 
@@ -9,33 +9,37 @@ Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
-│  lotto-frontend (Nginx:8080)                                          │
+│  frontend (Nginx:8080)                                                │
 │  ├── 정적 SPA 서빙 (React + Vite)                                     │
 │  └── API 리버스 프록시                                                 │
-│       ├── /api/                  → lotto-backend:8000  (로또·블로그·투두)│
-│       ├── /api/stock/, /trade/   → stock-lab:8000                     │
-│       ├── /api/portfolio         → stock-lab:8000                     │
-│       ├── /api/music/            → music-lab:8000                     │
-│       ├── /api/blog-marketing/   → blog-lab:8000                      │
-│       ├── /api/realestate/       → realestate-lab:8000                │
-│       ├── /api/agent-office/     → agent-office:8000 (+ WebSocket)    │
-│       ├── /api/travel/           → travel-proxy:8000                  │
-│       ├── /media/music/…          (nginx 직접 서빙, 생성 오디오)        │
+│       ├── /api/                  → lotto:8000        (로또)             │
+│       ├── /api/stock/, /trade/   → stock:8000                          │
+│       ├── /api/portfolio         → stock:8000                          │
+│       ├── /api/music/            → music-lab:8000                      │
+│       ├── /api/insta/            → insta-lab:8000                      │
+│       ├── /api/realestate/       → realestate-lab:8000                 │
+│       ├── /api/agent-office/     → agent-office:8000 (+ WebSocket)     │
+│       ├── /api/profile/, /todos, /blog/ → personal:8000                │
+│       ├── /api/packs/            → packs-lab:8000 (HMAC + 5GB upload)  │
+│       ├── /api/travel/           → travel-proxy:8000                   │
+│       ├── /media/music/, /media/videos/  (nginx 직접 서빙, 미디어)     │
 │       ├── /media/travel/…         (nginx 직접 서빙, 사진/썸네일)        │
-│       └── /webhook               → deployer:9000                      │
+│       └── /webhook               → deployer:9000                       │
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
 | 컨테이너 | 포트 | 역할 |
 |---------|------|------|
-| `lotto-backend` | 18000 | 로또 데이터 수집·분석·추천 + 블로그·투두 API |
-| `stock-lab` | 18500 | 주식 뉴스·AI 요약·KIS 실계좌·포트폴리오·자산 추적 |
-| `music-lab` | 18600 | AI 음악 생성 (Suno + 로컬 MusicGen 듀얼 프로바이더) |
-| `blog-lab` | 18700 | 블로그 마케팅 수익화 (키워드→글 생성→리뷰→발행) |
-| `realestate-lab` | 18800 | 청약 공고 자동 수집·프로필 매칭 |
+| `lotto` | 18000 | 로또 데이터 수집·분석·추천 API |
+| `stock` | 18500 | 주식 뉴스·AI 요약·KIS 실계좌·포트폴리오·자산 추적 |
+| `music-lab` | 18600 | AI 음악 생성 (Suno + 로컬 MusicGen 듀얼 프로바이더) + YouTube 수익화 |
+| `insta-lab` | 18700 | 인스타 카드 피드 자동 생성 (뉴스→키워드→10페이지 카드, Playwright) |
+| `realestate-lab` | 18800 | 청약 공고 자동 수집·5티어 매칭·신규 매칭 push |
 | `agent-office` | 18900 | AI 에이전트 가상 오피스 (WebSocket + 텔레그램 봇) |
+| `personal` | 18850 | 개인 서비스 — 포트폴리오·블로그·투두 통합 |
+| `packs-lab` | 18950 | NAS 자료 다운로드 자동화 (DSM 공유 링크 + 5GB 청크 업로드) |
 | `travel-proxy` | 19000 | 여행 사진 API + 온디맨드 썸네일 |
-| `lotto-frontend` | 8080 | SPA 서빙 + 리버스 프록시 |
+| `frontend` | 8080 | SPA 서빙 + 리버스 프록시 |
 | `webpage-deployer` | 19010 | Gitea Webhook → 자동 배포 |
 
 ---
@@ -44,12 +48,14 @@ Synology NAS 기반 개인 웹 플랫폼 백엔드 모노레포.
 
 ```
 web-backend/
-├── backend/              # lotto-backend (로또·블로그·투두)
-├── stock-lab/            # 주식·포트폴리오
-├── music-lab/            # AI 음악 생성
-├── blog-lab/             # 블로그 마케팅 파이프라인
-├── realestate-lab/       # 청약 자동 수집·매칭
+├── lotto/                # 로또 추천·통계·시뮬레이션
+├── stock/                # 주식·포트폴리오·KIS 연동
+├── music-lab/            # AI 음악 생성 + YouTube 수익화
+├── insta-lab/            # 인스타 카드 피드 자동 생성 (Playwright)
+├── realestate-lab/       # 청약 자동 수집·5티어 매칭
 ├── agent-office/         # AI 에이전트 오피스 (WS + 텔레그램)
+├── personal/             # 포트폴리오·블로그·투두 통합
+├── packs-lab/            # NAS 자료 다운로드 자동화 (HMAC + Supabase)
 ├── travel-proxy/         # 여행 사진 + 썸네일
 ├── deployer/             # Gitea Webhook 수신 → 자동 배포
 ├── nginx/default.conf    # 리버스 프록시 + SPA + 캐시
@@ -74,12 +80,14 @@ curl http://localhost:18500/health
 | 서비스 | 로컬 URL |
 |--------|----------|
 | Frontend + API | http://localhost:8080 |
-| lotto-backend | http://localhost:18000 |
-| stock-lab | http://localhost:18500 |
+| lotto | http://localhost:18000 |
+| stock | http://localhost:18500 |
 | music-lab | http://localhost:18600 |
-| blog-lab | http://localhost:18700 |
+| insta-lab | http://localhost:18700 |
 | realestate-lab | http://localhost:18800 |
+| personal | http://localhost:18850 |
 | agent-office | http://localhost:18900 |
+| packs-lab | http://localhost:18950 |
 | travel-proxy | http://localhost:19000 |
 
 ---
@@ -99,7 +107,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 실계좌 연동 + 포트폴리오·자산 스냅샷.
 
@@ -123,20 +131,23 @@ curl http://localhost:18500/health
 - **라이브러리**: 생성 파일은 `/app/data/music/`에 저장되고 Nginx가 `/media/music/`으로 직접 서빙
 - **가사 도구**: 저장·편집·타임스탬프 기반 가라오케 동기
 
-### 4. blog-lab (`/api/blog-marketing/`)
+### 4. insta-lab (`/api/insta/`)
 
-블로그 마케팅 수익화 4단계 파이프라인 (`draft → marketed → reviewed → published`).
+인스타그램 카드 피드 자동 생성 — 뉴스 모니터링 → 키워드 추출 → 10페이지 카드 카피·PNG 렌더 → 텔레그램 푸시 → 사용자 수동 업로드.
 
 ```
-리서치(Naver Search + 상위 블로그 본문 크롤링)
-  → 작가(AI 초안 생성)
-    → 마케터(전환율 강화 + 브랜드 링크 삽입)
-      → 평가자(6기준×10점, 42/60 통과 시 published)
+NAVER 뉴스 + YouTube 인기 (외부 트렌드)
+  → 카테고리별 빈도 + Claude Haiku 정제 → 트렌딩 키워드
+    → 사용자가 키워드 선택
+      → Claude Sonnet으로 10페이지 카피 추론 (커버 1 + 본문 8 + CTA 1)
+        → Jinja2 + Playwright 1080×1350 PNG 10장 렌더
+          → 텔레그램 미디어 그룹 + 추천 캡션·해시태그
 ```
 
-- **AI 엔진**: Claude API (`claude-sonnet-4-20250514`)
-- **키워드 분석**: 네이버 검색(블로그+쇼핑) API + 경쟁도/기회 점수
-- **수익 추적**: 포스트별 월간 클릭/구매/수익 기록
+- **AI 엔진**: Claude Sonnet (카피) + Claude Haiku (키워드 분류)
+- **데이터 소스**: NAVER 뉴스 검색 + YouTube Data API v3 mostPopular(KR)
+- **카테고리 가중치**: 사용자가 economy/psychology/celebrity 등 카테고리별 가중치 설정 → 자동 추출 비율에 반영
+- **카드 디자인**: `insta-lab/app/templates/default/card.html.j2` — 사용자가 자유 수정 (Tailwind 등)
 - **프롬프트 템플릿**: DB에 저장 → 코드 배포 없이 수정 가능
 
 ### 5. realestate-lab (`/api/realestate/`)
@@ -152,7 +163,7 @@ curl http://localhost:18500/health
 
 AI 에이전트 가상 오피스 — 2D 픽셀아트 사무실에서 4명의 에이전트가 실제 작업을 수행한다.
 
-- **아키텍처**: stock-lab / music-lab / blog-lab / realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
+- **아키텍처**: stock / music-lab / insta-lab / realestate-lab 기존 API를 서비스 프록시로 호출 (직접 DB 접근 없음)
 - **FSM 상태**: `idle → working → waiting(승인 대기) → reporting → break`
 - **실시간 동기화**: WebSocket `/api/agent-office/ws` (init, agent_state, task_complete, command_result)
 - **텔레그램 연동**: 양방향 알림 + 인라인 키보드 승인
@@ -165,22 +176,28 @@ AI 에이전트 가상 오피스 — 2D 픽셀아트 사무실에서 4명의 에
 |---------|--------|-----|----------|
 | 📈 **주식 트레이더** (`stock`) | 08:00 매일 | — | 뉴스 요약 (LLM) → 텔레그램 아침 브리핑, 종목 알람 등록 |
 | 🎵 **음악 프로듀서** (`music`) | 수동 트리거 | ✅ 작곡 | 프롬프트 수신 → 승인 → Suno API 작곡 → 트랙 푸시 |
-| ✍️ **블로그 마케터** (`blog`) | 10:00 매일 | ✅ 발행 | 트렌드 키워드 1개 선택 → 리서치→작가→마케터→평가 자동 실행 → 점수·본문을 텔레그램 승인 요청 → 승인 시 `published` 전환, 거절 시 재생성 |
-| 🏢 **청약 애널리스트** (`realestate`) | 09:15 매일 | — | realestate-lab 수집 트리거 → 신규 매칭 상위 5건 + 대시보드 요약을 텔레그램 리포트 (읽음 처리 자동) |
+| 🎴 **인스타 큐레이터** (`insta`) | 09:00 / 09:30 매일 | — | 09:00 외부 트렌드(NAVER + YouTube) 수집 → 09:30 가중치 기반 키워드 추출 → 텔레그램 후보 5개씩 카테고리당 인라인 버튼 푸시 → 사용자 선택 시 카드 10장 미디어 그룹 |
+| 🏢 **청약 애널리스트** (`realestate`) | realestate-lab push trigger | — | realestate-lab이 신규 매칭 발견 시 push → 인라인 [북마크] 버튼 포함 텔레그램 알림 |
+| 🎬 **YouTube 리서처** (`youtube`) | 09:00 매일 | — | 한국 YouTube 트렌딩 + Google Trends + Billboard → music-lab market_trends push |
 
 #### 에이전트별 명령
 
 **Stock** — `fetch_news`, `list_alerts`, `add_alert`, `test_telegram`
 **Music** — `compose` (승인 필요), `credits`
-**Blog** — `research {keyword}`, `add_trend_keyword`, `list_trend_keywords`
+**Insta** — `extract`, `render <keyword_id>`, `collect_trends`
 **Realestate** — `fetch_matches`, `dashboard`
+**YouTube** — `research {countries: [...]}`
 
 #### 스케줄러 잡
 
 - 07:00 월요일 — Lotto: AI 큐레이터 브리핑 (5세트 + 내러티브)
 - 07:30 — Stock: 뉴스 요약
-- 09:15 — Realestate: 매칭 리포트
-- 10:00 — Blog: 자동 파이프라인 (리서치→생성→리뷰→승인 대기)
+- 08:00 평일 — Stock: AI 뉴스 sentiment 분석
+- 09:00 — YouTube: 한국 트렌딩 수집
+- 09:00 — Insta: 외부 트렌드 수집 (NAVER 인기 + YouTube mostPopular)
+- 09:30 — Insta: 키워드 추출 (가중치 적용) + 텔레그램 후보 푸시
+- 15:40 평일 — Stock: 총 자산 스냅샷
+- 16:30 평일 — Stock: 스크리너 실행
 - 60초 interval — 유휴 에이전트 휴식 체크
 
 ### 7. travel-proxy (`/api/travel/`)
@@ -224,7 +241,7 @@ Gitea Webhook 수신 → NAS 자동 배포.
 | 공동 출현 | 15% | 번호 쌍 동시 출현 빈도 |
 | 다양성 | 10% | 연속번호·범위·구간 커버리지 |
 
-### LLM 요약 provider 추상화 (stock-lab)
+### LLM 요약 provider 추상화 (stock)
 
 `ai_summarizer.py`는 provider 분리 구조. `summarize_news(articles)` 시그니처는 provider와 무관하게 고정.
 
@@ -232,7 +249,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).
 
@@ -265,13 +282,15 @@ 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 |
-| `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 |
+| `lotto.db` | lotto | draws, recommendations, simulation_runs/candidates, best_picks, purchase_history, strategy_performance/weights, weekly_reports, lotto_briefings |
+| `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), video_projects, revenue_records, market_trends, trend_reports |
+| `insta.db` | insta-lab | news_articles, trending_keywords (source 컬럼), card_slates, card_assets, generation_tasks, prompt_templates, account_preferences |
 | `realestate.db` | realestate-lab | announcements, announcement_models, user_profile, match_results, collect_log |
 | `agent_office.db` | agent-office | agent_config, agent_tasks, agent_logs, telegram_state, conversation_messages |
+| `personal.db` | personal | profile, careers, projects, skills, introductions, todos, blog_posts |
 | `travel.db` | travel-proxy | photos (album, filename, mtime, has_thumb), album_covers |
+| `pack_files` (외부 Supabase) | packs-lab | filename, host_path, mime, byte_size, sha256, deleted_at |
 
 ---
 
@@ -292,33 +311,50 @@ 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, insta-lab, agent-office 공통)
 ANTHROPIC_API_KEY=sk-ant-...
 ANTHROPIC_MODEL=claude-haiku-4-5-20251001
 LLM_PROVIDER=claude              # claude | ollama
 OLLAMA_URL=http://192.168.45.59:11435
 OLLAMA_MODEL=qwen3:14b
 
+# stock admin protection (CODE_REVIEW F2)
+ADMIN_API_KEY=
+ALLOW_UNAUTHENTICATED_ADMIN=false
+
 # music-lab
 SUNO_API_KEY=
 MUSIC_AI_SERVER_URL=
 MUSIC_MEDIA_BASE=/media/music
 
-# blog-lab
+# insta-lab + agent-office (NAVER 검색 + YouTube Data API 공유)
 NAVER_CLIENT_ID=
 NAVER_CLIENT_SECRET=
+YOUTUBE_DATA_API_KEY=
 
 # realestate-lab
 DATA_GO_KR_API_KEY=
 
+# packs-lab (DSM + Supabase)
+DSM_HOST=
+DSM_USER=
+DSM_PASS=
+BACKEND_HMAC_SECRET=
+SUPABASE_URL=
+SUPABASE_SERVICE_KEY=
+PACK_HOST_DIR=/docker/webpage/media/packs  # shared folder 시점 (CLAUDE.md F5)
+
 # agent-office
 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
+INSTA_LAB_URL=http://insta-lab:8000
 REALESTATE_LAB_URL=http://realestate-lab:8000
+
+# personal (포트폴리오 편집 인증)
+PORTFOLIO_EDIT_PASSWORD=
 ```
 
 ---
@@ -343,7 +379,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

@@ -1,40 +1,42 @@
 # web-backend — 구현 현황 & 로드맵
 
-> 최종 갱신: 2026-05-07
+> 최종 갱신: 2026-05-17
 > 자세한 서비스·환경변수·DB 표는 [CLAUDE.md](./CLAUDE.md), 설계는 `docs/superpowers/specs/`, 실행 계획은 `docs/superpowers/plans/` 참조.
 
 ---
 
 ## 1. 서비스 구현 현황
 
-### 1-1. 운영 중인 컨테이너 (10개)
+### 1-1. 운영 중인 컨테이너 (11개)
 
 | 서비스 | 포트 | 상태 | 핵심 기능 |
 |--------|------|------|-----------|
-| `lotto-backend` | 18000 | ✅ | 로또 추천·통계·리포트·구매내역 + 블로그·투두 |
-| `stock-lab` | 18500 | ✅ | 주식 뉴스·지수·트레이딩·포트폴리오·자산 스냅샷 |
+| `lotto` | 18000 | ✅ | 로또 추천·통계·리포트·구매내역·AI 큐레이터 |
+| `stock` | 18500 | ✅ | 주식 뉴스·지수·트레이딩·포트폴리오·자산 스냅샷·스크리너 |
 | `music-lab` | 18600 | ✅ | Suno + MusicGen + YouTube 수익화 + 컴파일 |
-| `blog-lab` | 18700 | ✅ | 블로그 마케팅 수익화 파이프라인 |
-| `realestate-lab` | 18800 | ✅ | 청약 수집·5티어 매칭·매칭 알림 |
-| `agent-office` | 18900 | ✅ | AI 에이전트 (WebSocket + 텔레그램 + YouTubeResearcher) |
-| `packs-lab` | 18950 | ✅ | NAS 자료 다운로드 자동화 (HMAC + Supabase) — 2026-05-05 |
+| `insta-lab` | 18700 | ✅ | 인스타 카드 피드 자동 생성 (NAVER + YouTube 트렌드 → 10페이지 카드, Playwright) |
+| `realestate-lab` | 18800 | ✅ | 청약 수집·5티어 매칭·매칭 알림 push |
+| `personal` | 18850 | ✅ | 포트폴리오·블로그·투두 통합 (개인 서비스) |
+| `agent-office` | 18900 | ✅ | AI 에이전트 (WebSocket + 텔레그램 + InstaAgent + YouTubeResearcher) |
+| `packs-lab` | 18950 | ✅ | NAS 자료 다운로드 자동화 (HMAC + Supabase + 5GB chunked upload) |
 | `travel-proxy` | 19000 | ✅ | 여행 사진 API + 썸네일 + 지역 관리 |
-| `nginx` | 8080 | ✅ | SPA + 리버스 프록시 (5GB body limit) |
-| `webpage-deployer` | 19010 | ✅ | Gitea Webhook 자동 배포 |
+| `frontend` (nginx) | 8080 | ✅ | SPA + 리버스 프록시 (5GB body limit, 인스타 라우팅 포함) |
+| `webpage-deployer` | 19010 | ✅ | Gitea Webhook 자동 배포 (BUILDKIT timeout 600s, healthcheck via docker inspect) |
 
-### 1-2. 최근 큰 작업 (2026-04 ~ 05)
+### 1-2. 최근 큰 작업 (2026-05)
 
 | 시기 | 영역 | 핵심 |
 |------|------|------|
+| 2026-05-17 | 보안 / 정합성 | CODE_REVIEW F1 (packs-lab path traversal `startswith→relative_to`) + F2 (stock admin auth 503 거부) + F4 (portfolio total_buy 수량 곱산) |
+| 2026-05-17 | insta-lab | Google Trends API 폐기 대응 → YouTube Data API v3로 source 교체. trend_collector 재작성 |
+| 2026-05-16 | insta-lab | Trends 탭 추가 — 외부 트렌드 수집 (NAVER 인기 + YouTube) + 카테고리 가중치 (`account_preferences`) + 가중치 기반 키워드 추출 |
+| 2026-05-15 | insta-lab | blog-lab 폐기 → insta-lab 신설. 뉴스 모니터링 → 키워드 추출 → 10페이지 카드 카피·PNG → 텔레그램 푸시 → 수동 인스타 업로드 파이프라인 |
 | 2026-05-05 | packs-lab | sign-link / upload / list / delete + admin mint-token + 5GB nginx body limit + Supabase DDL |
 | 2026-05-01~06 | music-lab | YouTube 수익화 백엔드 (market_trends·trend_reports DB + 5개 API) + 다중 트랙 FFmpeg concat MP4 |
-| 2026-04-28 | realestate-lab | targeting enhancement (5티어 매칭·5축 점수·알림 대상 카운트) |
+| 2026-04-28 | realestate-lab | targeting enhancement (5티어 매칭·5축 점수·알림 대상 카운트, realestate-lab push → agent-office RealestateAgent) |
 | 2026-04-27 | personal | personal 서비스 분리 마이그레이션 (블로그·투두·포트폴리오 인증) |
 | 2026-04-27 | agent-office | v2 — youtube_researcher (YouTube API + pytrends + Billboard) + 알림 |
-| 2026-04-24 | travel-proxy | 갤러리 리디자인 + 성능 개선 (썸네일/페이지네이션) |
-| 2026-04-15 | lotto-backend | AI 큐레이터 (Claude 기반 주간 브리핑 자동 생성) |
-| 2026-04-08 | music-lab | Suno enhancement + MusicGen 통합 |
-| 2026-04-06 | blog-lab | 마케팅 파이프라인 (research → generate → market → review) |
+| 2026-04-15 | lotto | AI 큐레이터 (Claude 기반 주간 브리핑 자동 생성) |
 
 ### 1-3. 인프라 / DX
 

_shared/__init__.py

@@ -0,0 +1 @@
+# empty

_shared/access_log.py

@@ -0,0 +1,112 @@
+"""각 lab 컨테이너에서 import 하는 공용 액세스/이벤트 로그 모듈.
+
+사용법:
+    from _shared.access_log import install as install_access_log
+    install_access_log(app)
+"""
+from collections import deque
+from datetime import datetime
+from typing import Optional
+import logging
+import time
+
+from fastapi import APIRouter, Request
+from fastapi.applications import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware
+
+# 컨테이너당 최근 500개를 in-memory 로 유지. 재시작 시 휘발.
+_BUFFER: deque = deque(maxlen=500)
+
+EXCLUDED_PATHS = {
+    "/health", "/healthz", "/ping", "/favicon.ico",
+    "/docs", "/redoc", "/openapi.json", "/logs/recent",
+}
+EXCLUDED_PREFIXES = ("/static/",)
+EXCLUDED_METHODS = {"OPTIONS", "HEAD"}
+
+
+def _should_log(request: Request) -> bool:
+    if request.method in EXCLUDED_METHODS:
+        return False
+    path = request.url.path
+    if path in EXCLUDED_PATHS:
+        return False
+    if any(path.startswith(p) for p in EXCLUDED_PREFIXES):
+        return False
+    return True
+
+
+class AccessLogMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        start = time.time()
+        response = await call_next(request)
+        if not _should_log(request):
+            return response
+        elapsed_ms = int((time.time() - start) * 1000)
+        status = response.status_code
+        if status < 400:
+            level = "info"
+        elif status < 500:
+            level = "warning"
+        else:
+            level = "error"
+        _BUFFER.append({
+            "ts": datetime.utcnow().isoformat() + "Z",
+            "level": level,
+            "source": "access",
+            "method": request.method,
+            "path": request.url.path,
+            "status": status,
+            "ms": elapsed_ms,
+            "message": f"{request.method} {request.url.path} → {status} ({elapsed_ms}ms)",
+        })
+        return response
+
+
+class BufferLogHandler(logging.Handler):
+    """root logger 에 부착하면 모든 logger.info/warning/error 가 buffer 에 흐름."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            _BUFFER.append({
+                "ts": datetime.utcfromtimestamp(record.created).isoformat() + "Z",
+                "level": record.levelname.lower(),
+                "source": "log",
+                "logger": record.name,
+                "message": record.getMessage(),
+            })
+        except Exception:
+            # buffer 에 못 넣는다고 서비스가 죽으면 안 됨
+            pass
+
+
+router = APIRouter()
+
+
+@router.get("/logs/recent")
+def logs_recent(limit: int = 200, since: Optional[str] = None,
+                path_prefix: Optional[str] = None):
+    items = list(_BUFFER)
+    if since:
+        items = [x for x in items if x["ts"] > since]
+    if path_prefix:
+        items = [
+            x for x in items
+            if x["source"] == "log"
+            or x.get("path", "").startswith(path_prefix)
+        ]
+    return {"logs": items[-limit:]}
+
+
+def install(app: FastAPI, logger_root: str = "") -> None:
+    """서비스 main.py 에서 호출하는 단일 설치 함수.
+
+    - AccessLogMiddleware 등록
+    - /logs/recent 라우터 등록
+    - root logger 에 BufferLogHandler 부착 (모든 child logger 자동 전파)
+    """
+    app.add_middleware(AccessLogMiddleware)
+    app.include_router(router)
+    root = logging.getLogger(logger_root)
+    if not any(isinstance(h, BufferLogHandler) for h in root.handlers):
+        root.addHandler(BufferLogHandler())

_shared/tests/test_access_log.py

@@ -0,0 +1,129 @@
+import logging
+import time
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from _shared.access_log import (
+    AccessLogMiddleware,
+    BufferLogHandler,
+    router as logs_router,
+    install,
+    _BUFFER,
+)
+
+
+def _reset_buffer():
+    _BUFFER.clear()
+
+
+def test_access_middleware_records_request():
+    _reset_buffer()
+    app = FastAPI()
+    app.add_middleware(AccessLogMiddleware)
+
+    @app.get("/api/lotto/recommend")
+    def recommend():
+        return {"ok": True}
+
+    client = TestClient(app)
+    client.get("/api/lotto/recommend")
+
+    items = [x for x in _BUFFER if x["source"] == "access"]
+    assert len(items) == 1
+    assert items[0]["method"] == "GET"
+    assert items[0]["path"] == "/api/lotto/recommend"
+    assert items[0]["status"] == 200
+    assert items[0]["ms"] >= 0
+
+
+def test_access_middleware_skips_health():
+    _reset_buffer()
+    app = FastAPI()
+    app.add_middleware(AccessLogMiddleware)
+
+    @app.get("/health")
+    def health():
+        return {"ok": True}
+
+    client = TestClient(app)
+    client.get("/health")
+
+    items = [x for x in _BUFFER if x["source"] == "access"]
+    assert items == []
+
+
+def test_access_middleware_skips_options():
+    _reset_buffer()
+    app = FastAPI()
+    app.add_middleware(AccessLogMiddleware)
+
+    @app.get("/api/lotto/recommend")
+    def recommend():
+        return {"ok": True}
+
+    client = TestClient(app)
+    client.options("/api/lotto/recommend")
+
+    items = [x for x in _BUFFER if x["source"] == "access"]
+    assert items == []
+
+
+def test_buffer_log_handler_captures_logger_info():
+    _reset_buffer()
+    root = logging.getLogger("")
+    handler = BufferLogHandler()
+    root.addHandler(handler)
+    try:
+        lg = logging.getLogger("lotto.test")
+        lg.setLevel(logging.INFO)
+        lg.info("뉴스 스크래핑 완료: 국내 12건")
+    finally:
+        root.removeHandler(handler)
+
+    items = [x for x in _BUFFER if x["source"] == "log"]
+    assert len(items) == 1
+    assert items[0]["message"] == "뉴스 스크래핑 완료: 국내 12건"
+    assert items[0]["level"] == "info"
+    assert items[0]["logger"] == "lotto.test"
+
+
+def test_logs_recent_endpoint_returns_recent_items():
+    _reset_buffer()
+    app = FastAPI()
+    install(app)
+
+    @app.get("/api/lotto/recommend")
+    def recommend():
+        return {"ok": True}
+
+    client = TestClient(app)
+    client.get("/api/lotto/recommend")
+    client.get("/api/lotto/recommend")
+    client.get("/health")  # 제외되어야 함
+
+    resp = client.get("/logs/recent")
+    assert resp.status_code == 200
+    logs = resp.json()["logs"]
+    access_items = [x for x in logs if x["source"] == "access"]
+    assert len(access_items) == 2
+
+
+def test_logs_recent_with_since_filter():
+    _reset_buffer()
+    app = FastAPI()
+    install(app)
+
+    @app.get("/api/lotto/recommend")
+    def recommend():
+        return {"ok": True}
+
+    client = TestClient(app)
+    client.get("/api/lotto/recommend")
+    time.sleep(0.01)
+    cursor_resp = client.get("/logs/recent")
+    cursor_ts = cursor_resp.json()["logs"][-1]["ts"]
+    client.get("/api/lotto/recommend")
+
+    resp = client.get(f"/logs/recent?since={cursor_ts}")
+    items = [x for x in resp.json()["logs"] if x["source"] == "access"]
+    assert len(items) == 1

agent-office/Dockerfile

@@ -7,4 +7,4 @@ RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . .
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

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/base.py

@@ -1,12 +1,7 @@
-import asyncio
-import random
 import time
 from typing import Optional
 
-from ..config import IDLE_BREAK_THRESHOLD, BREAK_DURATION_MIN, BREAK_DURATION_MAX
-from ..db import add_log
-
-VALID_STATES = ("idle", "working", "waiting", "reporting", "break")
+VALID_STATES = ("idle", "working", "waiting", "reporting")
 
 class BaseAgent:
     agent_id: str = ""
@@ -14,7 +9,6 @@ class BaseAgent:
     state: str = "idle"
     state_detail: str = ""
     _idle_since: float = 0.0
-    _break_until: float = 0.0
     _ws_manager = None
 
     def __init__(self):
@@ -32,11 +26,6 @@ class BaseAgent:
 
         if new_state == "idle":
             self._idle_since = time.time()
-        elif new_state == "break":
-            duration = random.randint(BREAK_DURATION_MIN, BREAK_DURATION_MAX)
-            self._break_until = time.time() + duration
-
-        add_log(self.agent_id, f"State: {old} -> {new_state} ({detail})")
 
         if self._ws_manager:
             await self._ws_manager.send_agent_state(self.agent_id, new_state, detail, task_id)
@@ -48,19 +37,6 @@ class BaseAgent:
                 await self._ws_manager.send_notification(
                     self.agent_id, "task_completed", task_id, detail or "작업 완료"
                 )
-            if new_state == "break":
-                await self._ws_manager.send_agent_move(self.agent_id, "break_room")
-            elif old == "break" and new_state == "idle":
-                await self._ws_manager.send_agent_move(self.agent_id, "desk")
-
-    async def check_idle_break(self) -> None:
-        now = time.time()
-        if self.state == "idle" and (now - self._idle_since) > IDLE_BREAK_THRESHOLD:
-            if random.random() < 0.5:
-                break_type = random.choice(["커피 타임", "잠깐 산책", "졸고 있음"])
-                await self.transition("break", break_type)
-        elif self.state == "break" and now > self._break_until:
-            await self.transition("idle", "휴식 완료")
 
     async def on_schedule(self) -> None:
         raise NotImplementedError

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,194 @@
+"""인스타 카드 에이전트 — 매일 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__)
+
+# 텔레그램 후보 푸시 시 "확실한 것만" 보내기 위한 최소 신뢰도 (키워드 score 0~1)
+KEYWORD_MIN_SCORE = 0.7
+
+
+def _dedup_and_filter_keywords(
+    keywords: List[Dict[str, Any]], min_score: float = KEYWORD_MIN_SCORE,
+) -> List[Dict[str, Any]]:
+    """score >= min_score 인 키워드만 남기고, 동일 keyword 중복 제거(최고 score 유지).
+    결과는 score 내림차순. 텔레그램 후보 푸시 전 정리용."""
+    best: Dict[str, Dict[str, Any]] = {}
+    for k in keywords:
+        if float(k.get("score", 0)) < min_score:
+            continue
+        name = str(k.get("keyword", "")).strip()
+        if not name:
+            continue
+        if name not in best or k["score"] > best[name]["score"]:
+            best[name] = k
+    return sorted(best.values(), key=lambda k: -k["score"])
+
+
+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 != "idle":
+            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:
+        # 중복 제거 + 신뢰도(score) 임계값 이상만 — "확실한 것만" 정리해서 전송
+        filtered = _dedup_and_filter_keywords(keywords)
+        if not filtered:
+            await messaging.send_raw(
+                f"📰 [인스타 큐레이터] 오늘은 확실한 추천 키워드가 없습니다 (신뢰도 {KEYWORD_MIN_SCORE:.1f}+ 기준)."
+            )
+            return
+        by_cat: Dict[str, List[Dict[str, Any]]] = {}
+        for k in filtered:
+            by_cat.setdefault(k["category"], []).append(k)
+        rows: List[List[Dict[str, Any]]] = []
+        text_lines = [f"📰 <b>[인스타 큐레이터]</b> 오늘의 키워드 후보 (신뢰도 {KEYWORD_MIN_SCORE:.1f}+)"]
+        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

@@ -8,7 +8,7 @@ class LottoAgent(BaseAgent):
     display_name = "로또 큐레이터"
 
     async def on_schedule(self) -> None:
-        if self.state not in ("idle", "break"):
+        if self.state != "idle":
             return
         await self._run(source="auto")
 
@@ -17,11 +17,249 @@ class LottoAgent(BaseAgent):
             return await self._run(source="manual")
         if action == "status":
             return {"ok": True, "message": f"{self.state}: {self.state_detail}"}
+        if action in ("signal_check", "light_check", "sim_check", "deep_check"):
+            source = action.replace("_check", "") if action != "signal_check" else "light"
+            return await self.run_signal_check(source=source)
+        if action == "daily_digest":
+            return await self.run_daily_digest()
+        if action == "sunday_review":
+            return await self.run_sunday_review()
         return {"ok": False, "message": f"unknown action: {action}"}
 
     async def on_approval(self, task_id: str, approved: bool, feedback: str = "") -> None:
         pass
 
+    async def run_signal_check(self, source: str = "light") -> dict:
+        """비-LLM 시그널 평가. task_id wrap 적용."""
+        from ..curator.signal_runner import run_signal_check
+        from ..config import (
+            LOTTO_Z_NORMAL, LOTTO_Z_URGENT,
+            LOTTO_THROTTLE_HOURS, LOTTO_URGENT_DAILY_MAX,
+        )
+        from ..db import (
+            create_task, update_task_status, add_log,
+            get_last_signal_notification, get_recent_urgent_count,
+            mark_signal_notified,
+        )
+        from ..notifiers.telegram_lotto import send_urgent_signal
+        from ..service_proxy import lotto_latest_draw
+
+        if self.state not in ("idle", "reporting"):
+            return {"ok": False, "message": f"busy ({self.state})"}
+
+        task_id = create_task("lotto", "signal_check", {"source": source})
+        try:
+            curate_result = None
+            current_draw_no = await lotto_latest_draw()
+
+            if source == "deep":
+                from ..curator.pipeline import curate_weekly
+                cw = await curate_weekly(source="signal_deep")
+                curate_result = {"confidence": cw.get("confidence")}
+                if cw.get("draw_no"):
+                    current_draw_no = cw.get("draw_no")
+
+            outcome = await run_signal_check(
+                source=source,
+                z_normal=LOTTO_Z_NORMAL,
+                z_urgent=LOTTO_Z_URGENT,
+                curate_result=curate_result,
+                current_draw_no=current_draw_no,
+            )
+
+            # urgent 텔레그램 + throttle (기존 동작 유지)
+            if outcome["overall_fire"] == "urgent":
+                if get_recent_urgent_count(hours=24) >= LOTTO_URGENT_DAILY_MAX:
+                    add_log("lotto", "urgent daily cap 도달 → normal로 강등", level="warning", task_id=task_id)
+                else:
+                    blocked = False
+                    for r in outcome["results"]:
+                        if r["fire_level"] in ("normal", "urgent"):
+                            if get_last_signal_notification(
+                                metric=r["metric"], fire_level=r["fire_level"],
+                                hours=LOTTO_THROTTLE_HOURS,
+                            ):
+                                blocked = True
+                                break
+                    if not blocked:
+                        from datetime import datetime, timezone
+                        event = {
+                            "fire_level": "urgent",
+                            "triggered_at": datetime.now(timezone.utc).isoformat(),
+                            "results": outcome["results"],
+                        }
+                        await send_urgent_signal(event)
+                        for r in outcome["results"]:
+                            if r["fire_level"] in ("normal", "urgent"):
+                                mark_signal_notified(r["signal_id"])
+                        add_log("lotto", f"urgent 텔레그램 발송 ({len(outcome['results'])}개 시그널)", task_id=task_id)
+
+            fired_metrics = [
+                r["metric"] for r in outcome["results"]
+                if r["fire_level"] not in ("noop", "warmup")
+            ]
+            update_task_status(task_id, "succeeded", result_data={
+                "source": source,
+                "overall_fire": outcome["overall_fire"],
+                "n_results": len(outcome["results"]),
+                "fired_metrics": fired_metrics,
+            })
+            add_log("lotto", f"signal_check({source}) → {outcome['overall_fire']} results={len(outcome['results'])}", task_id=task_id)
+            return {"ok": True, **outcome}
+        except Exception as e:
+            update_task_status(task_id, "failed", result_data={"error": str(e)})
+            add_log("lotto", f"signal_check 예외: {e}", level="error", task_id=task_id)
+            return {"ok": False, "message": f"{type(e).__name__}: {e}"}
+
+    async def run_daily_digest(self) -> dict:
+        """일일 요약 — 지난 24h normal/urgent 발화 텔레그램 1통. task_id wrap."""
+        from ..db import (
+            create_task, update_task_status, add_log,
+            get_recent_lotto_signals, get_signals_history, get_baseline,
+        )
+        from ..notifiers.telegram_lotto import send_signal_summary
+
+        task_id = create_task("lotto", "daily_digest", {})
+        try:
+            sigs = get_recent_lotto_signals(hours=24, min_fire="normal")
+            total_24h = get_signals_history(days=1)
+            evaluated = len(total_24h)
+
+            trend = {}
+            try:
+                cache = get_baseline("drift_weights_cache")
+                if cache and isinstance(cache["window_values"], list) and len(cache["window_values"]) >= 2:
+                    prev_w = cache["window_values"][-2]
+                    curr_w = cache["window_values"][-1]
+                    trend = {
+                        k: curr_w.get(k, 0.0) - prev_w.get(k, 0.0)
+                        for k in (set(prev_w) | set(curr_w))
+                    }
+            except Exception as e:
+                add_log("lotto", f"weights_trend 계산 실패: {e}", level="warning", task_id=task_id)
+
+            digest = {
+                "evaluated": evaluated,
+                "fired": len(sigs),
+                "signals": sigs,
+                "weights_trend": trend,
+            }
+            await send_signal_summary(digest)
+            update_task_status(task_id, "succeeded", result_data={
+                "evaluated": evaluated,
+                "fired": len(sigs),
+                "signals_count": len(sigs),
+            })
+            add_log("lotto", f"daily_digest 발송: 평가 {evaluated} / 발화 {len(sigs)}", task_id=task_id)
+            return {"ok": True, **digest}
+        except Exception as e:
+            update_task_status(task_id, "failed", result_data={"error": str(e)})
+            add_log("lotto", f"daily_digest 예외: {e}", level="error", task_id=task_id)
+            return {"ok": False, "message": f"{type(e).__name__}: {e}"}
+
+    async def run_sunday_review(self) -> dict:
+        """일 09:00 — 최신 회차 forward+calibration 보장 후 회고 텔레그램."""
+        from ..service_proxy import lotto_latest_draw, lotto_backtest_review
+        from ..notifiers.telegram_lotto import send_sunday_review
+        from ..db import create_task, update_task_status, add_log
+
+        task_id = create_task("lotto", "sunday_review", {})
+        try:
+            draw_no = await lotto_latest_draw()
+            if not draw_no:
+                update_task_status(task_id, "failed", result_data={"reason": "no_draw"})
+                return {"ok": False, "message": "no latest draw"}
+            # forward는 lotto cron이 이미 돌렸을 수 있으나 멱등이라 안전 — review만 호출
+            payload = await lotto_backtest_review(draw_no)
+            await send_sunday_review(payload)
+            update_task_status(task_id, "succeeded", result_data={"draw_no": draw_no})
+            add_log("lotto", f"sunday_review 발송: #{draw_no}", task_id=task_id)
+            return {"ok": True, "draw_no": draw_no}
+        except Exception as e:
+            update_task_status(task_id, "failed", result_data={"error": str(e)})
+            add_log("lotto", f"sunday_review 예외: {e}", level="error", task_id=task_id)
+            return {"ok": False, "message": f"{type(e).__name__}: {e}"}
+
+    async def run_weekly_evolution_report(self) -> dict:
+        """토 22:15 — lotto-lab evaluate-now 트리거 후 텔레그램 리포트. task_id wrap."""
+        from ..service_proxy import lotto_evolver_evaluate, lotto_evolver_status
+        from ..notifiers.telegram_lotto import send_evolution_report
+        from ..db import create_task, update_task_status, add_log
+
+        task_id = create_task("lotto", "weekly_evolution_report", {})
+        try:
+            eval_result = await lotto_evolver_evaluate()
+            status = await lotto_evolver_status()
+            current_base = status.get("current_base") or [0.2] * 5
+            await send_evolution_report(eval_result, current_base)
+
+            winner = eval_result.get("winner") or {}
+            update_task_status(task_id, "succeeded", result_data={
+                "draw_no": eval_result.get("draw_no"),
+                "update_reason": eval_result.get("update_reason"),
+                "winner_day_of_week": winner.get("day_of_week"),
+                "winner_max_correct": winner.get("max_correct"),
+            })
+            add_log("lotto", f"weekly_evolution_report 발송: draw={eval_result.get('draw_no')} reason={eval_result.get('update_reason')}", task_id=task_id)
+            return {"ok": True, **eval_result}
+        except Exception as e:
+            update_task_status(task_id, "failed", result_data={"error": str(e)})
+            add_log("lotto", f"weekly_evolution_report 예외: {e}", level="error", task_id=task_id)
+            return {"ok": False, "message": f"{type(e).__name__}: {e}"}
+
+    async def sync_evolver_activity(self) -> dict:
+        """매일 09:30 — lotto-lab evolver 상태 polling → agent_office.db에 task+log 거울. 멱등."""
+        from datetime import datetime, timezone, timedelta
+        from ..service_proxy import lotto_evolver_status
+        from ..db import (
+            create_task, update_task_status, add_log,
+            get_tasks_by_agent_date_kind,
+        )
+
+        KST = timezone(timedelta(hours=9))
+        today_kst = datetime.now(KST).date()
+        # created_at은 UTC로 저장되므로 idempotency guard는 UTC 날짜 기준
+        today_utc_iso = datetime.now(timezone.utc).date().isoformat()
+        dow = today_kst.weekday()
+        if dow == 6:
+            dow = 5
+
+        try:
+            status = await lotto_evolver_status()
+        except Exception as e:
+            add_log("lotto", f"sync_evolver_activity: lotto-lab status fetch 실패: {e}", level="warning")
+            return {"ok": False, "reason": "status_fetch_failed", "error": str(e)}
+
+        results = {"created": []}
+
+        today_trial = next((t for t in status.get("trials", []) if t.get("day_of_week") == dow), None)
+        if today_trial and today_trial.get("picks"):
+            if not get_tasks_by_agent_date_kind("lotto", today_utc_iso, "evolver_apply"):
+                tid = create_task("lotto", "evolver_apply", {
+                    "date": today_utc_iso,
+                    "trial_id": today_trial["id"],
+                    "day_of_week": dow,
+                    "weight": today_trial["weight"],
+                })
+                update_task_status(tid, "succeeded", result_data={
+                    "n_picks": len(today_trial["picks"]),
+                    "meta_scores": [p.get("meta_score") for p in today_trial["picks"]],
+                })
+                add_log("lotto", f"evolver_apply: 오늘({dow}) W로 {len(today_trial['picks'])}세트 추출", task_id=tid)
+                results["created"].append("evolver_apply")
+
+        if today_kst.weekday() == 0 and len(status.get("trials", [])) == 6:
+            if not get_tasks_by_agent_date_kind("lotto", today_utc_iso, "evolver_generate"):
+                tid = create_task("lotto", "evolver_generate", {"week_start": status.get("week_start")})
+                update_task_status(tid, "succeeded", result_data={
+                    "trials_count": 6,
+                    "candidates_per_source": {"perturb": 4, "dirichlet": 2},
+                })
+                add_log("lotto", f"evolver_generate: {status.get('week_start')} 주의 6 trials 생성", task_id=tid)
+                results["created"].append("evolver_generate")
+
+        return {"ok": True, **results}
+
     async def _run(self, source: str) -> dict:
         task_id = create_task(self.agent_id, "curate_weekly", {"source": source})
         await self.transition("working", "후보 수집 및 AI 큐레이션 중...", task_id)

agent-office/app/agents/stock.py

@@ -44,14 +44,14 @@ class StockAgent(BaseAgent):
     display_name = "주식 트레이더"
 
     async def on_schedule(self) -> None:
-        if self.state not in ("idle", "break"):
+        if self.state != "idle":
             return
 
         task_id = create_task(self.agent_id, "news_summary", {"limit": 15})
         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,273 @@ 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 != "idle":
+            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 != "idle":
+            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 run_holdings_eod(self) -> dict:
+        """평일 16:50 — 보유종목 시그널 계산·저장."""
+        # idle 가드 없음(의도적): 스크리너 진행 중에도 EOD/브리핑은 독립적으로 실행되어야 함
+        from ..service_proxy import stock_holdings_run
+        from ..db import create_task, update_task_status, add_log
+        task_id = create_task(self.agent_id, "holdings_eod", {})
+        try:
+            res = await stock_holdings_run()
+            update_task_status(task_id, "succeeded", res)
+            add_log(self.agent_id, f"holdings_eod: {res}", "info", task_id)
+            return {"ok": True, **res}
+        except Exception as e:
+            update_task_status(task_id, "failed", {"error": str(e)})
+            add_log(self.agent_id, f"holdings_eod 실패: {e}", "error", task_id)
+            return {"ok": False, "message": str(e)}
+
+    async def run_holdings_brief(self) -> dict:
+        """평일 08:30 — 저장된 시그널 브리핑 텔레그램."""
+        # idle 가드 없음(의도적): 스크리너 진행 중에도 EOD/브리핑은 독립적으로 실행되어야 함
+        from ..service_proxy import stock_holdings_brief
+        from ..notifiers.telegram_stock import send_holdings_brief
+        from ..db import create_task, update_task_status, add_log
+        task_id = create_task(self.agent_id, "holdings_brief", {})
+        try:
+            payload = await stock_holdings_brief()
+            await send_holdings_brief(payload)
+            update_task_status(task_id, "succeeded", {"date": payload.get("date"),
+                                                      "count": len(payload.get("holdings", []))})
+            add_log(self.agent_id, f"holdings_brief 발송: {payload.get('date')}", "info", task_id)
+            return {"ok": True}
+        except Exception as e:
+            update_task_status(task_id, "failed", {"error": str(e)})
+            add_log(self.agent_id, f"holdings_brief 실패: {e}", "error", task_id)
+            return {"ok": False, "message": str(e)}
+
     async def on_command(self, command: str, params: dict) -> dict:
+        if command == "holdings_eod":
+            return await self.run_holdings_eod()
+
+        if command == "holdings_brief":
+            return await self.run_holdings_brief()
+
+        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/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
@@ -26,11 +26,28 @@ CORS_ALLOW_ORIGINS = os.getenv(
     "CORS_ALLOW_ORIGINS", "http://localhost:3007,http://localhost:8080"
 )
 
-# Idle break threshold (seconds)
-IDLE_BREAK_THRESHOLD = int(os.getenv("IDLE_BREAK_THRESHOLD", "300"))  # 5 min
-BREAK_DURATION_MIN = int(os.getenv("BREAK_DURATION_MIN", "60"))       # 1 min
-BREAK_DURATION_MAX = int(os.getenv("BREAK_DURATION_MAX", "180"))      # 3 min
-
 # Lotto Curator
 LOTTO_BACKEND_URL = os.getenv("LOTTO_BACKEND_URL", "http://lotto:8000")
 LOTTO_CURATOR_MODEL = os.getenv("LOTTO_CURATOR_MODEL", "claude-sonnet-4-5")
+
+# Lotto Active Signals
+LOTTO_SIGNAL_WINDOW = int(os.getenv("LOTTO_SIGNAL_WINDOW", "8"))
+LOTTO_Z_NORMAL = float(os.getenv("LOTTO_Z_NORMAL", "1.5"))
+LOTTO_Z_URGENT = float(os.getenv("LOTTO_Z_URGENT", "2.5"))
+LOTTO_DIGEST_HOUR = int(os.getenv("LOTTO_DIGEST_HOUR", "9"))
+LOTTO_DIGEST_MIN = int(os.getenv("LOTTO_DIGEST_MIN", "25"))
+LOTTO_THROTTLE_HOURS = int(os.getenv("LOTTO_THROTTLE_HOURS", "6"))
+LOTTO_URGENT_DAILY_MAX = int(os.getenv("LOTTO_URGENT_DAILY_MAX", "3"))
+
+import re as _re
+
+# 에이전트 → (container_host, port, path_prefix_regex)
+# path_prefix_regex: lotto 컨테이너에 personal/blog/todo 도 같이 있어
+# /api/lotto 만 골라내기 위한 정규식. business log (source='log') 는 모두 통과.
+AGENT_CONTAINER_MAP: dict[str, tuple[str, int, _re.Pattern]] = {
+    "lotto":      ("lotto",          8000, _re.compile(r"^/api/lotto")),
+    "stock":      ("stock",          8000, _re.compile(r"^/api/(stock|trade|portfolio)")),
+    "music":      ("music-lab",      8000, _re.compile(r"^/api/music")),
+    "insta":      ("insta-lab",      8000, _re.compile(r"^/api/insta")),
+    "realestate": ("realestate-lab", 8000, _re.compile(r"^/api/realestate")),
+}

agent-office/app/curator/signal_runner.py

@@ -0,0 +1,185 @@
+"""LottoAgent 능동 시그널 — DB I/O + cron 진입점 + 평가 orchestration."""
+from __future__ import annotations
+import logging
+from typing import Any, Dict, List, Optional
+
+from .. import db
+from .. import service_proxy
+from . import signals
+
+logger = logging.getLogger("agent-office.lotto-signals")
+
+# 회차 단위 메트릭 (window push 시 last_pushed_draw_no 비교)
+DRAW_SCOPED_METRICS = {"drift", "confidence"}
+
+
+def _load_baseline(metric: str) -> signals.AdaptiveBaseline:
+    row = db.get_baseline(metric)
+    if row is None:
+        return signals.AdaptiveBaseline(window=[], window_max=8)
+    return signals.AdaptiveBaseline(
+        window=list(row["window_values"]),
+        window_max=8,
+        last_pushed_draw_no=row.get("last_pushed_draw_no"),
+    )
+
+
+def _save_baseline(metric: str, bl: signals.AdaptiveBaseline) -> None:
+    db.upsert_baseline(
+        metric=metric,
+        window_values=bl.window,
+        mu=bl.mu,
+        sigma=bl.sigma,
+        last_pushed_draw_no=bl.last_pushed_draw_no,
+    )
+
+
+def evaluate_metric_and_persist(
+    source: str,
+    metric: str,
+    value: float,
+    draw_no: Optional[int],
+    z_normal: float,
+    z_urgent: float,
+    push_to_window: bool,
+    payload: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """단일 메트릭 평가 → lotto_signals INSERT → baseline 갱신.
+
+    회차 단위 메트릭(drift, confidence)은 같은 draw_no에서 window push 생략.
+    """
+    bl = _load_baseline(metric)
+
+    # 회차 가드
+    do_push = push_to_window
+    if metric in DRAW_SCOPED_METRICS and draw_no is not None:
+        if bl.last_pushed_draw_no == draw_no:
+            do_push = False
+
+    # 평가는 push 전 baseline 기준
+    z, fire = bl.evaluate(value=value, z_normal=z_normal, z_urgent=z_urgent)
+
+    if do_push:
+        bl.push(value=value, draw_no=draw_no)
+        _save_baseline(metric, bl)
+    else:
+        # cold start에서도 baseline row를 만들어 두려면 upsert 필요
+        _save_baseline(metric, bl)
+
+    sid = db.insert_lotto_signal(
+        source=source,
+        metric=metric,
+        value=value,
+        baseline_mu=bl.mu if bl.size > 0 else None,
+        baseline_sigma=bl.sigma if bl.size >= 2 else None,
+        z_score=z,
+        fire_level=fire,
+        payload=payload,
+    )
+    return {
+        "signal_id": sid,
+        "metric": metric,
+        "value": value,
+        "baseline_mu": bl.mu if bl.size > 0 else None,
+        "baseline_sigma": bl.sigma if bl.size >= 2 else None,
+        "z_score": z,
+        "fire_level": fire,
+        "payload": payload or {},
+    }
+
+
+# ---------- Service proxy thin wrappers (monkeypatch 대상) ----------
+
+async def _fetch_best_picks() -> List[Dict[str, Any]]:
+    return await service_proxy.lotto_best()
+
+
+async def _fetch_strategy_weights() -> Dict[str, float]:
+    return await service_proxy.lotto_strategy_weights()
+
+
+# ---------- Orchestrator ----------
+
+async def run_signal_check(
+    source: str,
+    z_normal: float = 1.5,
+    z_urgent: float = 2.5,
+    curate_result: Optional[Dict[str, Any]] = None,
+    current_draw_no: Optional[int] = None,
+) -> Dict[str, Any]:
+    """cron 진입점. source ∈ {'light', 'sim', 'deep'}.
+
+    light/sim: Sim Consensus + Strategy Drift 평가
+    deep: 위 2종 + Confidence (curate_result 필요)
+    """
+    results: List[Dict[str, Any]] = []
+
+    # --- Sim Consensus ---
+    try:
+        best = await _fetch_best_picks()
+        v = signals.sim_consensus_score(best)
+        results.append(
+            evaluate_metric_and_persist(
+                source=source, metric="sim_signal",
+                value=v, draw_no=None,
+                z_normal=z_normal, z_urgent=z_urgent,
+                push_to_window=True,
+                payload={"top_count": min(len(best), 10)},
+            )
+        )
+    except Exception as e:
+        logger.warning(f"sim_consensus 평가 실패: {e}")
+
+    # --- Strategy Drift (회차 단위) ---
+    try:
+        w_curr = await _fetch_strategy_weights()
+        # weights 캐시: lotto_baselines의 별도 metric 'drift_weights_cache'에 prev/curr 2개 보관
+        prev_payload_row = db.get_baseline("drift_weights_cache")
+        w_prev = prev_payload_row["window_values"] if prev_payload_row else None
+
+        if w_prev and isinstance(w_prev, list) and len(w_prev) > 0 and isinstance(w_prev[0], dict):
+            prev_dict = w_prev[-1]
+            drift_value = signals.strategy_drift_score(prev_dict, w_curr)
+            results.append(
+                evaluate_metric_and_persist(
+                    source=source, metric="drift",
+                    value=drift_value, draw_no=current_draw_no,
+                    z_normal=z_normal, z_urgent=z_urgent,
+                    push_to_window=True,
+                    payload={"weights_now": w_curr, "weights_prev": prev_dict},
+                )
+            )
+        # weights 캐시 갱신 (최대 2개 FIFO)
+        cache_window = (w_prev or []) + [w_curr]
+        if len(cache_window) > 2:
+            cache_window = cache_window[-2:]
+        db.upsert_baseline(
+            metric="drift_weights_cache",
+            window_values=cache_window,
+            mu=0.0, sigma=0.0,
+            last_pushed_draw_no=current_draw_no,
+        )
+    except Exception as e:
+        logger.warning(f"strategy_drift 평가 실패: {e}")
+
+    # --- Confidence (deep_check + curate_result 필수) ---
+    if source == "deep" and curate_result is not None:
+        try:
+            cv = signals.confidence_score(curate_result)
+            if cv is not None:
+                results.append(
+                    evaluate_metric_and_persist(
+                        source=source, metric="confidence",
+                        value=cv, draw_no=current_draw_no,
+                        z_normal=z_normal, z_urgent=z_urgent,
+                        push_to_window=True,
+                        payload={"draw_no": current_draw_no},
+                    )
+                )
+        except Exception as e:
+            logger.warning(f"confidence 평가 실패: {e}")
+
+    overall = signals.decide_overall_fire(
+        [{"metric": r["metric"], "z": r["z_score"], "fire": r["fire_level"]} for r in results]
+    )
+    return {"overall_fire": overall, "results": results}

agent-office/app/curator/signals.py

@@ -0,0 +1,150 @@
+# agent-office/app/curator/signals.py
+"""LottoAgent 능동 모니터링 — 시그널 평가 & adaptive baseline (순수 함수).
+
+DB I/O 없음. 입력은 모두 dict/list, 출력도 dict/list.
+signal_runner.py에서 DB 연동 + cron 진입점 담당.
+"""
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from statistics import mean, stdev
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------- Metric: Sim Consensus ----------
+
+def _normalize_columns(picks: List[Dict[str, Any]]) -> List[List[float]]:
+    """20개 후보의 5종 점수 컬럼별 min-max normalize → 후보별 5종 정규화 점수."""
+    if not picks:
+        return []
+    n_metrics = len(picks[0]["scores"])
+    columns = [[p["scores"][k] for p in picks] for k in range(n_metrics)]
+    norms_per_col = []
+    for col in columns:
+        lo, hi = min(col), max(col)
+        rng = hi - lo
+        if rng == 0:
+            # 모두 0이면 0.0(기하평균 페널티), 모두 동일한 양수면 0.5(타이 처리)
+            fallback = 0.0 if lo == 0 else 0.5
+            norms_per_col.append([fallback] * len(col))
+        else:
+            norms_per_col.append([(v - lo) / rng for v in col])
+    return [
+        [norms_per_col[k][i] for k in range(n_metrics)]
+        for i in range(len(picks))
+    ]
+
+
+def _geomean(values: List[float]) -> float:
+    """기하평균. 0이 하나라도 있으면 0 (한 차원이 0인 후보 강하게 페널티)."""
+    if not values:
+        return 0.0
+    if any(v <= 0 for v in values):
+        return 0.0
+    log_sum = sum(math.log(v) for v in values)
+    return math.exp(log_sum / len(values))
+
+
+def sim_consensus_score(best_picks: List[Dict[str, Any]]) -> float:
+    """top-10 후보의 기하평균 consensus 평균."""
+    if not best_picks:
+        return 0.0
+    normalized = _normalize_columns(best_picks)
+    consensus = [_geomean(scores) for scores in normalized]
+    consensus.sort(reverse=True)
+    top = consensus[:10] if len(consensus) >= 10 else consensus
+    return mean(top) if top else 0.0
+
+
+# ---------- Metric: Strategy Drift ----------
+
+def strategy_drift_score(prev: Dict[str, float], curr: Dict[str, float]) -> float:
+    """가중치 변화 절댓값 합. 신규/소멸 전략도 가산."""
+    keys = set(prev) | set(curr)
+    return sum(abs(curr.get(k, 0.0) - prev.get(k, 0.0)) for k in keys)
+
+
+# ---------- Metric: Confidence ----------
+
+def confidence_score(curate_result: Dict[str, Any]) -> Optional[float]:
+    """큐레이션 결과의 confidence를 0~1로 clamp. 없으면 None."""
+    if "confidence" not in curate_result:
+        return None
+    v = float(curate_result["confidence"])
+    return max(0.0, min(1.0, v))
+
+
+# ---------- Adaptive Baseline ----------
+
+@dataclass
+class AdaptiveBaseline:
+    window: List[float] = field(default_factory=list)
+    window_max: int = 8
+    last_pushed_draw_no: Optional[int] = None
+
+    @property
+    def size(self) -> int:
+        return len(self.window)
+
+    @property
+    def mu(self) -> float:
+        return mean(self.window) if self.window else 0.0
+
+    @property
+    def sigma(self) -> float:
+        return stdev(self.window) if len(self.window) >= 2 else 0.0
+
+    def push(self, value: float, draw_no: Optional[int] = None) -> None:
+        """FIFO push. window_max 초과 시 가장 오래된 값 제거."""
+        self.window.append(float(value))
+        if len(self.window) > self.window_max:
+            self.window = self.window[-self.window_max:]
+        if draw_no is not None:
+            self.last_pushed_draw_no = draw_no
+
+    def evaluate(self, value: float, z_normal: float, z_urgent: float) -> Tuple[Optional[float], str]:
+        """z-score 계산 + fire_level 판정.
+
+        Returns:
+            (z_score, fire_level) — z_score는 cold start/warmup이면 None.
+            fire_level ∈ {'warmup', 'noop', 'normal', 'urgent'}
+
+        NOTE: z_score is None when sigma==0 (degenerate window) or warmup.
+        Callers must treat None as "signal present but unquantified" — do not
+        compare None with thresholds directly.
+        """
+        if self.size < 4:
+            return None, "warmup"
+
+        z_normal_eff = 2.0 if self.size < self.window_max else z_normal
+        z_urgent_eff = z_urgent
+
+        if self.sigma == 0:
+            return (None, "urgent") if value > self.mu else (None, "noop")
+
+        z = (value - self.mu) / self.sigma
+        if z >= z_urgent_eff:
+            return z, "urgent"
+        if z >= z_normal_eff:
+            return z, "normal"
+        return z, "noop"
+
+
+# ---------- Combined fire decision ----------
+
+def decide_overall_fire(signal_results: List[Dict[str, Any]]) -> str:
+    """3종 시그널을 종합해 전체 fire_level 결정.
+
+    Args:
+        signal_results: [{"metric": str, "z": float|None, "fire": str}, ...]
+    Returns:
+        'noop' | 'normal' | 'urgent'
+    """
+    fires = [s for s in signal_results if s["fire"] in ("normal", "urgent")]
+    if any(s["fire"] == "urgent" for s in fires):
+        return "urgent"
+    if len(fires) >= 2:
+        return "urgent"
+    if len(fires) == 1:
+        return "normal"
+    return "noop"

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
 
 
@@ -97,6 +98,66 @@ def init_db() -> None:
                 completed_at     TEXT
             )
         """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS lotto_signals (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                triggered_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                source          TEXT NOT NULL,
+                metric          TEXT NOT NULL,
+                value           REAL NOT NULL,
+                baseline_mu     REAL,
+                baseline_sigma  REAL,
+                z_score         REAL,
+                fire_level      TEXT NOT NULL,
+                notified_at     TEXT,
+                payload         TEXT
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ls_triggered
+            ON lotto_signals(triggered_at DESC)
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_ls_fire
+            ON lotto_signals(fire_level, notified_at)
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS lotto_baselines (
+                metric              TEXT PRIMARY KEY,
+                window_values       TEXT NOT NULL DEFAULT '[]',
+                mu                  REAL NOT NULL DEFAULT 0.0,
+                sigma               REAL NOT NULL DEFAULT 0.0,
+                last_pushed_draw_no INTEGER,
+                updated_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            )
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS tarot_readings (
+                id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+                created_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+                spread_type         TEXT NOT NULL,
+                category            TEXT,
+                question            TEXT,
+                cards               TEXT NOT NULL,
+                interpretation_json TEXT,
+                summary             TEXT,
+                model               TEXT,
+                tokens_in           INTEGER,
+                tokens_out          INTEGER,
+                cost_usd            REAL,
+                confidence          TEXT,
+                favorite            INTEGER NOT NULL DEFAULT 0,
+                note                TEXT
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_tarot_created
+            ON tarot_readings(created_at DESC)
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_tarot_favorite
+            ON tarot_readings(favorite, created_at DESC)
+        """)
         # Seed default agent configs
         for agent_id, name in [
             ("stock", "주식 트레이더"),
@@ -202,12 +263,24 @@ def get_task(task_id: str) -> Optional[Dict[str, Any]]:
     return _task_to_dict(r) if r else None
 
 
-def get_agent_tasks(agent_id: str, limit: int = 20) -> List[Dict[str, Any]]:
+def get_agent_tasks(
+    agent_id: str,
+    limit: int = 20,
+    task_type: Optional[str] = None,
+    days: Optional[int] = None,
+) -> List[Dict[str, Any]]:
+    sql = "SELECT * FROM agent_tasks WHERE agent_id=?"
+    params: List[Any] = [agent_id]
+    if task_type is not None:
+        sql += " AND task_type=?"
+        params.append(task_type)
+    if days is not None and days > 0:
+        sql += " AND created_at >= datetime('now', ?)"
+        params.append(f"-{int(days)} days")
+    sql += " ORDER BY created_at DESC LIMIT ?"
+    params.append(limit)
     with _conn() as conn:
-        rows = conn.execute(
-            "SELECT * FROM agent_tasks WHERE agent_id=? ORDER BY created_at DESC LIMIT ?",
-            (agent_id, limit),
-        ).fetchall()
+        rows = conn.execute(sql, params).fetchall()
     return [_task_to_dict(r) for r in rows]
 
 
@@ -248,7 +321,13 @@ def add_log(agent_id: str, message: str, level: str = "info", task_id: str = Non
 def get_logs(agent_id: str, limit: int = 50) -> List[Dict[str, Any]]:
     with _conn() as conn:
         rows = conn.execute(
-            "SELECT * FROM agent_logs WHERE agent_id=? ORDER BY created_at DESC LIMIT ?",
+            """
+            SELECT * FROM agent_logs
+            WHERE agent_id = ?
+              AND message NOT LIKE 'State: %'
+            ORDER BY created_at DESC
+            LIMIT ?
+            """,
             (agent_id, limit),
         ).fetchall()
     return [
@@ -259,6 +338,7 @@ def get_logs(agent_id: str, limit: int = 50) -> List[Dict[str, Any]]:
             "level": r["level"],
             "message": r["message"],
             "created_at": r["created_at"],
+            "source": "agent",
         }
         for r in rows
     ]
@@ -515,6 +595,20 @@ def get_activity_feed(limit: int = 50, offset: int = 0) -> dict:
     return {"items": items, "total": total}
 
 
+import datetime as _dt
+
+
+def delete_old_logs(days: int = 90) -> int:
+    """retention 정책: N일 이전 agent_logs 삭제. 매일 03:00 스케줄러가 호출."""
+    cutoff = (_dt.datetime.utcnow() - _dt.timedelta(days=days)).isoformat()
+    with _conn() as conn:
+        c = conn.execute(
+            "DELETE FROM agent_logs WHERE created_at < ?",
+            (cutoff,),
+        )
+        return c.rowcount
+
+
 # ── youtube_research_jobs CRUD ────────────────────────────────────────────────
 
 def add_youtube_research_job(countries: list) -> int:
@@ -555,3 +649,170 @@ def get_latest_youtube_research_job() -> Optional[Dict[str, Any]]:
         "started_at":       row["started_at"],
         "completed_at":     row["completed_at"],
     }
+
+
+# --- lotto_signals / lotto_baselines CRUD ---
+
+def insert_lotto_signal(
+    source: str,
+    metric: str,
+    value: float,
+    baseline_mu: Optional[float],
+    baseline_sigma: Optional[float],
+    z_score: Optional[float],
+    fire_level: str,
+    payload: Optional[Dict[str, Any]] = None,
+) -> int:
+    with _conn() as conn:
+        cur = conn.execute(
+            """
+            INSERT INTO lotto_signals
+              (source, metric, value, baseline_mu, baseline_sigma, z_score, fire_level, payload)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                source, metric, value,
+                baseline_mu, baseline_sigma, z_score, fire_level,
+                json.dumps(payload or {}, ensure_ascii=False),
+            ),
+        )
+        return cur.lastrowid
+
+
+def mark_signal_notified(signal_id: int) -> None:
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE lotto_signals SET notified_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
+            (signal_id,),
+        )
+
+
+def get_recent_lotto_signals(hours: int = 24, min_fire: str = "normal") -> List[Dict[str, Any]]:
+    """지난 N시간 발화 시그널. min_fire='normal'이면 normal+urgent."""
+    levels = ("urgent",) if min_fire == "urgent" else ("normal", "urgent")
+    placeholders = ",".join("?" * len(levels))
+    with _conn() as conn:
+        rows = conn.execute(
+            f"""
+            SELECT * FROM lotto_signals
+            WHERE triggered_at >= datetime('now', ?)
+              AND fire_level IN ({placeholders})
+            ORDER BY triggered_at DESC
+            """,
+            (f"-{int(hours)} hours", *levels),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_signals_history(days: int = 7) -> List[Dict[str, Any]]:
+    """차트/이력 페이지용 — 모든 fire_level 포함."""
+    with _conn() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM lotto_signals
+            WHERE triggered_at >= datetime('now', ?)
+            ORDER BY triggered_at DESC
+            """,
+            (f"-{int(days)} days",),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_recent_urgent_count(hours: int = 24) -> int:
+    with _conn() as conn:
+        row = conn.execute(
+            """
+            SELECT COUNT(*) AS c FROM lotto_signals
+            WHERE triggered_at >= datetime('now', ?)
+              AND fire_level = 'urgent'
+              AND notified_at IS NOT NULL
+            """,
+            (f"-{int(hours)} hours",),
+        ).fetchone()
+    return int(row["c"]) if row else 0
+
+
+def get_last_signal_notification(metric: str, fire_level: str, hours: int) -> Optional[str]:
+    """같은 metric+fire_level이 hours 내에 알림 발송된 마지막 시각. throttle용."""
+    with _conn() as conn:
+        row = conn.execute(
+            """
+            SELECT notified_at FROM lotto_signals
+            WHERE metric = ?
+              AND fire_level = ?
+              AND notified_at IS NOT NULL
+              AND notified_at >= datetime('now', ?)
+            ORDER BY notified_at DESC LIMIT 1
+            """,
+            (metric, fire_level, f"-{int(hours)} hours"),
+        ).fetchone()
+    return row["notified_at"] if row else None
+
+
+def get_baseline(metric: str) -> Optional[Dict[str, Any]]:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM lotto_baselines WHERE metric = ?",
+            (metric,),
+        ).fetchone()
+    if not row:
+        return None
+    d = dict(row)
+    d["window_values"] = json.loads(d["window_values"])
+    return d
+
+
+def upsert_baseline(
+    metric: str,
+    window_values: List[float],
+    mu: float,
+    sigma: float,
+    last_pushed_draw_no: Optional[int],
+) -> None:
+    with _conn() as conn:
+        conn.execute(
+            """
+            INSERT INTO lotto_baselines
+              (metric, window_values, mu, sigma, last_pushed_draw_no, updated_at)
+            VALUES (?, ?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+            ON CONFLICT(metric) DO UPDATE SET
+              window_values = excluded.window_values,
+              mu = excluded.mu,
+              sigma = excluded.sigma,
+              last_pushed_draw_no = excluded.last_pushed_draw_no,
+              updated_at = excluded.updated_at
+            """,
+            (
+                metric,
+                json.dumps(window_values),
+                mu, sigma, last_pushed_draw_no,
+            ),
+        )
+
+
+def get_all_baselines() -> List[Dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute("SELECT * FROM lotto_baselines ORDER BY metric").fetchall()
+    out = []
+    for r in rows:
+        d = dict(r)
+        d["window_values"] = json.loads(d["window_values"])
+        out.append(d)
+    return out
+
+
+def get_tasks_by_agent_date_kind(agent_id: str, date_iso: str, task_type: str) -> List[Dict[str, Any]]:
+    """같은 (agent, date, task_type)으로 이미 생성된 task 조회. 멱등 guard."""
+    with _conn() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM agent_tasks
+            WHERE agent_id = ? AND task_type = ?
+              AND substr(created_at, 1, 10) = ?
+            ORDER BY created_at DESC
+            """,
+            (agent_id, task_type, date_iso),
+        ).fetchall()
+    return [_task_to_dict(r) for r in rows]
+
+

agent-office/app/main.py

@@ -1,5 +1,6 @@
 import os
 import json
+from typing import Optional
 from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
 from fastapi.middleware.cors import CORSMiddleware
 
@@ -104,12 +105,29 @@ def update_agent(agent_id: str, body: AgentConfigUpdate):
     return {"ok": True}
 
 @app.get("/api/agent-office/agents/{agent_id}/tasks")
-def agent_tasks(agent_id: str, limit: int = 20):
-    return {"tasks": get_agent_tasks(agent_id, limit)}
+def agent_tasks(
+    agent_id: str,
+    limit: int = 20,
+    task_type: Optional[str] = None,
+    days: Optional[int] = None,
+):
+    tasks_list = get_agent_tasks(agent_id, limit=limit, task_type=task_type, days=days)
+    # Backward compat: 기존 client는 'tasks', 신규 client는 'items' 사용
+    return {"tasks": tasks_list, "items": tasks_list}
 
 @app.get("/api/agent-office/agents/{agent_id}/logs")
-def agent_logs(agent_id: str, limit: int = 50):
-    return {"logs": get_logs(agent_id, limit)}
+async def agent_logs(agent_id: str, limit: int = 50):
+    from .service_proxy import fetch_service_logs
+
+    agent_items = get_logs(agent_id, limit=limit)
+    service_items = await fetch_service_logs(agent_id, limit=limit)
+
+    def _sort_key(x):
+        # agent_logs: created_at, service: ts
+        return x.get("ts") or x.get("created_at") or ""
+
+    merged = sorted(agent_items + service_items, key=_sort_key, reverse=True)
+    return {"logs": merged[:limit]}
 
 @app.get("/api/agent-office/tasks/pending")
 def pending_tasks():
@@ -227,3 +245,30 @@ def youtube_research_status():
     if not job:
         return {"status": "never_run"}
     return job
+
+
+# --- Lotto Signal Endpoints ---
+
+@app.get("/api/agent-office/lotto/signals")
+async def list_lotto_signals(days: int = 7):
+    """시그널 이력 (모든 fire_level)."""
+    from .db import get_signals_history
+    return {"items": get_signals_history(days=days)}
+
+
+@app.get("/api/agent-office/lotto/baselines")
+async def list_lotto_baselines():
+    """현재 baseline μ/σ + window 상태."""
+    from .db import get_all_baselines
+    return {"items": get_all_baselines()}
+
+
+@app.post("/api/agent-office/lotto/signal-check")
+async def trigger_signal_check(source: str = "light"):
+    """수동 트리거 (디버그·테스트용). source ∈ {light, sim, deep}."""
+    if source not in ("light", "sim", "deep"):
+        raise HTTPException(status_code=400, detail="source must be light/sim/deep")
+    agent = AGENT_REGISTRY.get("lotto")
+    if not agent:
+        raise HTTPException(status_code=503, detail="lotto agent not registered")
+    return await agent.run_signal_check(source=source)

agent-office/app/models.py

@@ -1,5 +1,5 @@
-from pydantic import BaseModel
-from typing import Optional
+from pydantic import BaseModel, Field
+from typing import Optional, List, Literal
 
 
 class CommandRequest(BaseModel):

agent-office/app/notifiers/telegram_lotto.py

@@ -1,6 +1,6 @@
 """로또 큐레이션·당첨 알림 — 텔레그램 푸시."""
 import logging
-from typing import Dict, Any
+from typing import Dict, Any, List
 
 # 기존 에이전트들과 동일한 패턴: send_raw(text, reply_markup=None, chat_id=None)
 # chat_id 생략 시 기본 TELEGRAM_CHAT_ID로 자동 발송.
@@ -59,3 +59,208 @@ async def send_prize_alert(event: Dict[str, Any]) -> None:
         await send_raw(text)
     except Exception as e:
         logger.warning(f"[telegram_lotto] prize alert send failed: {e}")
+
+
+# ---------- 능동 시그널 알림 (urgent + digest) ----------
+
+_METRIC_LABEL = {
+    "sim_signal": "Sim Consensus",
+    "drift": "Strategy Drift",
+    "confidence": "Confidence",
+}
+
+
+def _format_urgent_signal(event: Dict[str, Any]) -> str:
+    """긴급 시그널 텔레그램 메시지 포맷."""
+    triggered = event.get("triggered_at", "")[:19].replace("T", " ")
+    results = event.get("results", [])
+    fired = [r for r in results if r.get("fire_level") in ("normal", "urgent")]
+
+    lines = [
+        "🚨 로또 능동 신호",
+        "",
+        f"[{triggered}]",
+        f"강한 시그널 {len(fired)}종 발화:",
+    ]
+    for r in fired:
+        label = _METRIC_LABEL.get(r["metric"], r["metric"])
+        v = r.get("value")
+        mu = r.get("baseline_mu")
+        sigma = r.get("baseline_sigma")
+        z = r.get("z_score")
+        v_text = f"{v:.2f}" if v is not None else "N/A"
+        if mu is not None and sigma is not None and z is not None:
+            lines.append(f"• {label} {v_text} (μ={mu:.2f}, σ={sigma:.2f}) z={z:.1f}")
+        else:
+            lines.append(f"• {label} {v_text}")
+
+    # drift 페이로드 — 어떤 전략이 변동했는지 한 줄
+    for r in fired:
+        if r["metric"] == "drift":
+            wn = (r.get("payload") or {}).get("weights_now") or {}
+            wp = (r.get("payload") or {}).get("weights_prev") or {}
+            if wn and wp:
+                diffs = {k: wn.get(k, 0) - wp.get(k, 0) for k in (set(wn) | set(wp))}
+                top = sorted(diffs.items(), key=lambda kv: abs(kv[1]), reverse=True)[:2]
+                detail = ", ".join(f"{k} {'+' if d>=0 else ''}{d*100:.0f}%p" for k, d in top)
+                lines.append("")
+                lines.append(f"요인: {detail}")
+            break
+
+    lines.append("")
+    lines.append(f"[자세히 보기] ({LOTTO_URL}/agent)")
+    return "\n".join(lines)
+
+
+def _format_signal_digest(digest: Dict[str, Any]) -> str:
+    """일일 요약 메시지. 발화 0건이면 빈 문자열 (발송 skip 신호)."""
+    fired = int(digest.get("fired", 0))
+    if fired == 0:
+        return ""
+
+    signals_list = digest.get("signals", [])
+    evaluated = digest.get("evaluated", 0)
+
+    lines = [
+        "📊 로또 일일 요약 (지난 24h)",
+        "",
+        f"평가 {evaluated}회 / 발화 {fired}회",
+    ]
+    for s in signals_list:
+        label = _METRIC_LABEL.get(s["metric"], s["metric"])
+        z = s.get("z_score")
+        when = (s.get("triggered_at") or "")[11:16]  # HH:MM
+        z_text = f"z={z:.1f}" if z is not None else "z=-"
+        lines.append(f"• {label:14s} {s['fire_level']:6s} {z_text}  ({when})")
+
+    weights_trend = digest.get("weights_trend") or {}
+    if weights_trend:
+        lines += ["", "전략 가중치 추세 (최근 8회 baseline):"]
+        for strategy, delta in sorted(weights_trend.items(), key=lambda kv: -abs(kv[1])):
+            arrow = "↑" if delta > 0.01 else ("↓" if delta < -0.01 else "→")
+            lines.append(f"  {strategy:12s} {arrow} {delta*100:+.0f}%")
+
+    return "\n".join(lines)
+
+
+async def send_urgent_signal(event: Dict[str, Any]) -> None:
+    text = _format_urgent_signal(event)
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] urgent signal send failed: {e}")
+
+
+async def send_signal_summary(digest: Dict[str, Any]) -> None:
+    text = _format_signal_digest(digest)
+    if not text:
+        return  # 발화 0건이면 발송 skip
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] digest send failed: {e}")
+
+
+# ---------- Weight Evolver 주간 리포트 ----------
+
+_DAY_NAMES = ["월", "화", "수", "목", "금", "토"]
+_METRIC_NAMES = ["freq", "finger", "gap", "cooccur", "divers"]
+_REASON_LABEL = {
+    "winner_4plus": "4개 이상 일치 → base 교체",
+    "ema_blend": "3개 일치 → EMA blend (0.3)",
+    "unchanged": "유효 성과 없음 → base 유지",
+    "cold_start": "초기 균등 적용",
+}
+
+
+def _format_evolution_report(eval_result: Dict[str, Any], current_base: List[float]) -> str:
+    """주간 weight evolution 텔레그램 메시지. ok=False 또는 winner 없으면 빈 문자열."""
+    if not eval_result or "winner" not in eval_result:
+        return ""
+
+    draw_no = eval_result.get("draw_no", "?")
+    winner = eval_result["winner"]
+    new_base = eval_result.get("new_base") or [0.0] * 5
+    reason = eval_result.get("update_reason", "")
+    dow = winner.get("day_of_week", 0)
+    day_name = _DAY_NAMES[dow] if 0 <= dow < len(_DAY_NAMES) else "?"
+
+    lines = [
+        f"🧬 로또 학습 주간 리포트 ({draw_no}회차)",
+        "",
+        f"이번주 시도: 6일 × {winner.get('n_picks', 5)}세트",
+        "",
+        f"🏆 Winner: {day_name}요일",
+        f"  W = [" + ", ".join(
+            f"{name} {w:.2f}" for name, w in zip(_METRIC_NAMES, winner["weight"])
+        ) + "]",
+        f"  최고 적중: {winner.get('max_correct', 0)}개 일치 (max={winner.get('max_correct', 0)})",
+        f"  평균 점수: {winner.get('avg_score', 0):.2f}",
+        "",
+        f"📊 다음주 base 변경 ({reason}):",
+    ]
+    # 우선순위: eval_result.previous_base > current_base (eval 직후 stale) > 균등 fallback
+    base_now = eval_result.get("previous_base") or current_base or [0.2] * 5
+    for i, (cur, new) in enumerate(zip(base_now, new_base)):
+        diff = new - cur
+        if abs(diff) < 0.005:
+            marker = "="
+        elif diff > 0:
+            marker = "+" if diff < 0.05 else "++"
+        else:
+            marker = "-" if diff > -0.05 else "--"
+        lines.append(f"  {_METRIC_NAMES[i]:8s} {cur:.2f} → {new:.2f}  ({marker})")
+    lines.append("")
+    lines.append(f"  → {_REASON_LABEL.get(reason, reason)}")
+    lines.append("")
+    lines.append(f"[웹에서 차트 보기] ({LOTTO_URL}/evolver)")
+    return "\n".join(lines)
+
+
+async def send_evolution_report(eval_result: Dict[str, Any], current_base: List[float]) -> None:
+    text = _format_evolution_report(eval_result, current_base)
+    if not text:
+        return
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] evolution report send failed: {e}")
+
+
+# ---------- 일요 회고 브리핑 ----------
+
+def format_sunday_review(payload: Dict[str, Any]) -> str:
+    """일요 회고 브리핑 텍스트 (HTML parse_mode)."""
+    wa = payload.get("winner_analysis") or {}
+    draw_no = payload.get("draw_no") or "?"
+    pct = wa.get("percentile")
+    pct_txt = f"{pct*100:.0f}%" if pct is not None else "—"
+    lines = [f"🔍 <b>로또 #{draw_no} 일요 회고</b>", ""]
+    if wa:
+        lines.append(f"이번 당첨조합 분석치: <b>{wa.get('score_total',0):.2f}</b> "
+                     f"(무작위 분포 상위 {pct_txt})")
+        lines.append(f"  빈도 {wa.get('score_frequency',0):.2f} · 지문 {wa.get('score_fingerprint',0):.2f} "
+                     f"· 갭 {wa.get('score_gap',0):.2f} · 공동출현 {wa.get('score_cooccur',0):.2f} "
+                     f"· 다양성 {wa.get('score_diversity',0):.2f}")
+        lines.append("")
+    if payload.get("forward"):
+        lines.append("📊 <b>이번 회차 가상구매 성적</b>")
+        for f in payload.get("forward", []):
+            p = f.get("prizes") or {}
+            name = {"engine_w": f"엔진({f.get('label','')})", "random_null": "무작위", "coverage": "커버리지"}.get(
+                f.get("strategy", ""), f.get("strategy", "?"))
+            lines.append(f"  {name}: 최고 {f.get('best_match','?')}일치 / "
+                         f"4등 {p.get('4th', 0)} · 5등 {p.get('5th', 0)}")
+    else:
+        lines.append("📊 <b>이번 회차 가상구매 성적</b>: 데이터 없음 (아직 집계 전)")
+    lines.append("")
+    lines.append("ℹ️ 무작위 대비 우위가 통계적으로 의미있을 때만 가중치가 진화합니다.")
+    return "\n".join(lines)
+
+
+async def send_sunday_review(payload: Dict[str, Any]) -> None:
+    text = format_sunday_review(payload)
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_lotto] sunday review send failed: {e}")

agent-office/app/notifiers/telegram_stock.py

@@ -0,0 +1,42 @@
+"""보유종목 인텔리전스 텔레그램 포매터 (advisory)."""
+import logging
+from typing import Any, Dict
+
+from ..telegram.messaging import send_raw
+
+logger = logging.getLogger("agent-office")
+
+_ACTION_KR = {"add": "🟢 추가매수", "hold": "⚪ 보유", "trim": "🟡 축소", "sell": "🔴 매도"}
+_SEV = {"high": "🔴", "med": "🟠", "low": "🟡"}
+
+
+def format_holdings_brief(payload: Dict[str, Any]) -> str:
+    date = payload.get("date") or "?"
+    lines = [f"📊 <b>보유종목 인텔리전스</b> ({date})", ""]
+    ph = payload.get("portfolio_health") or {}
+    if ph:
+        lines.append(f"포트 손익 {ph.get('total_pnl_rate',0):+.1f}% · "
+                     f"종목 {ph.get('positions',0)} · 최대비중 {ph.get('max_weight',0)*100:.0f}% · "
+                     f"현금 {ph.get('cash_ratio',0)*100:.0f}%")
+        lines.append("")
+    for h in payload.get("holdings", []):
+        act = _ACTION_KR.get(h.get("action"), h.get("action", "?"))
+        pnl = h.get("pnl_rate")
+        pnl_txt = f"{pnl:+.1f}%" if pnl is not None else "—"
+        line = f"{act} <b>{h.get('name') or h.get('ticker')}</b> ({pnl_txt})"
+        if h.get("reasons"):
+            line += f" — {h['reasons']}"
+        lines.append(line)
+        for iss in (h.get("issues") or [])[:3]:
+            lines.append(f"   {_SEV.get(iss.get('severity'),'•')} {iss.get('summary','')}")
+    lines.append("")
+    lines.append("ℹ️ 투자 판단 보조용 제안입니다(자동매매 아님).")
+    return "\n".join(lines)
+
+
+async def send_holdings_brief(payload: Dict[str, Any]) -> None:
+    text = format_holdings_brief(payload)
+    try:
+        await send_raw(text)
+    except Exception as e:
+        logger.warning(f"[telegram_stock] holdings brief send failed: {e}")

agent-office/app/scheduler.py

@@ -1,29 +1,88 @@
 import asyncio
+import logging
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
 
 from .agents import AGENT_REGISTRY
+from .db import delete_old_logs
 
 scheduler = AsyncIOScheduler(timezone="Asia/Seoul")
 
-async def _check_idle_breaks():
-    for agent in AGENT_REGISTRY.values():
-        await agent.check_idle_break()
-
 async def _run_stock_schedule():
     agent = AGENT_REGISTRY.get("stock")
     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_stock_holdings_eod():
+    agent = AGENT_REGISTRY.get("stock")
+    if agent:
+        await agent.run_holdings_eod()
+
+async def _run_stock_holdings_brief():
+    agent = AGENT_REGISTRY.get("stock")
+    if agent:
+        await agent.run_holdings_brief()
+
+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:
         await agent.on_schedule()
 
+async def _run_lotto_light_check():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_signal_check(source="light")
+
+async def _run_lotto_sim_check():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_signal_check(source="sim")
+
+async def _run_lotto_deep_check():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_signal_check(source="deep")
+
+async def _run_lotto_daily_digest():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_daily_digest()
+
+async def _run_lotto_weekly_evolution_report():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_weekly_evolution_report()
+
+async def _run_lotto_sync_evolver_activity():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.sync_evolver_activity()
+
+async def _run_lotto_sunday_review():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.run_sunday_review()
+
 async def _run_youtube_research():
     agent = AGENT_REGISTRY.get("youtube")
     if agent:
@@ -39,12 +98,49 @@ async def _poll_pipelines():
     if agent:
         await agent.poll_state_changes()
 
+def _cleanup_old_logs():
+    n = delete_old_logs(days=90)
+    if n:
+        logging.getLogger(__name__).info("delete_old_logs: %d rows removed", n)
+
 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=9, minute=0, id="lotto_curate")
-    scheduler.add_job(_run_youtube_research, "cron", hour=9, minute=0, id="youtube_research")
+    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_stock_holdings_eod,   "cron", day_of_week="mon-fri", hour=16, minute=50, id="stock_holdings_eod")  # 16:50: 스크리너 snapshot(16:30) 완료 후 — 부분 일봉 읽기 방지
+    scheduler.add_job(_run_stock_holdings_brief, "cron", day_of_week="mon-fri", hour=8,  minute=30, id="stock_holdings_brief")
+    scheduler.add_job(_run_insta_schedule, "cron", hour=9, minute=30, id="insta_pipeline")
+    # 외부 트렌드 수집은 장 마감 후 16:40 — 9시 주식 활발 시간대 NAS 자원 회피.
+    # screener(16:30)와 10분 스태거: Celeron 2C/2.0GHz 동시 실행 시 CPU 폭주 방지 (CHECK_POINT FU-A)
+    scheduler.add_job(_run_insta_trends_collect, "cron", hour=16, minute=40, id="insta_trends_collect")
+    scheduler.add_job(_run_lotto_schedule,       "cron", day_of_week="mon", hour=9, minute=5, id="lotto_curate")
+    scheduler.add_job(_run_lotto_light_check,   "cron", hour=9, minute=15, id="lotto_light_check")
+    scheduler.add_job(_run_lotto_sim_check,     "cron", minute=15, hour="0,4,8,12,16,20", id="lotto_sim_check")
+    scheduler.add_job(_run_lotto_deep_check,    "cron", day_of_week="sun,wed", hour=21, minute=15, id="lotto_deep_check")
+    scheduler.add_job(_run_lotto_daily_digest,  "cron", hour=9, minute=25, id="lotto_digest")
+    scheduler.add_job(_run_lotto_weekly_evolution_report, "cron", day_of_week="sat", hour=22, minute=15, id="lotto_evolution_weekly")
+    scheduler.add_job(_run_lotto_sunday_review, "cron", day_of_week="sun", hour=9, minute=0, id="lotto_sunday_review")
+    scheduler.add_job(
+        _run_lotto_sync_evolver_activity,
+        "cron", hour=9, minute=30,
+        id="lotto_evolver_activity_sync",
+    )
+    scheduler.add_job(_run_youtube_research,     "cron", hour=9, minute=10, 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")
     scheduler.add_job(_poll_pipelines, "interval", seconds=30, id="pipeline_poll")
+    scheduler.add_job(_cleanup_old_logs, "cron", hour=3, minute=0, id="cleanup_old_logs", replace_existing=True)
     scheduler.start()

agent-office/app/service_proxy.py

@@ -1,7 +1,10 @@
 import httpx
+import logging
 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
+
+logger = logging.getLogger(__name__)
 
 _client = httpx.AsyncClient(timeout=30.0)
 
@@ -9,40 +12,105 @@ 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()
 
+
+async def stock_holdings_run() -> Dict[str, Any]:
+    """보유종목 시그널 계산 트리거 (EOD, use_llm=True).
+
+    stock BackgroundTask 등록 후 즉시 {ok, queued} 반환.
+    실제 계산은 stock 컨테이너 백그라운드에서 진행 — 여유있게 120s.
+    """
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        resp = await client.post(
+            f"{STOCK_URL}/api/stock/holdings/intel/run",
+            params={"use_llm": True},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def stock_holdings_brief() -> Dict[str, Any]:
+    """보유종목 최신 브리핑 payload 조회 (GET, 모듈 레벨 _client 사용)."""
+    resp = await _client.get(f"{STOCK_URL}/api/stock/holdings/intel")
+    resp.raise_for_status()
+    return resp.json()
+
+
 async def generate_music(payload: dict) -> Dict[str, Any]:
     resp = await _client.post(f"{MUSIC_LAB_URL}/api/music/generate", json=payload)
     resp.raise_for_status()
@@ -59,60 +127,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]:
@@ -249,3 +364,102 @@ async def lookup_pipeline_by_msg(msg_id: int) -> Optional[dict]:
         if resp.status_code == 200:
             return resp.json()
         return None
+
+
+async def lotto_best() -> List[Dict[str, Any]]:
+    """GET /api/lotto/best — best_picks 20개 (numbers + scores 5종)."""
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/best")
+    resp.raise_for_status()
+    data = resp.json()
+    items = data.get("items") if isinstance(data, dict) else data
+    return items or []
+
+
+async def lotto_strategy_weights() -> Dict[str, float]:
+    """GET /api/lotto/strategy/weights — 전략별 가중치 dict."""
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/strategy/weights")
+    resp.raise_for_status()
+    data = resp.json()
+    weights = data.get("weights") if isinstance(data, dict) else data
+    if isinstance(weights, list):
+        return {item["strategy"]: float(item["weight"]) for item in weights}
+    return {k: float(v) for k, v in (weights or {}).items()}
+
+
+async def lotto_latest_draw() -> Optional[int]:
+    """GET /api/lotto/latest — 최신 회차 번호만 반환."""
+    from .config import LOTTO_BACKEND_URL
+    try:
+        resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/latest")
+        resp.raise_for_status()
+        data = resp.json()
+        # /api/lotto/latest 응답 키: {"drawNo": N, ...}
+        # 하위 호환을 위해 drawNo, draw_no, drwNo, draw 순서로 시도
+        for key in ("drawNo", "draw_no", "drwNo", "draw"):
+            if isinstance(data, dict) and data.get(key):
+                return int(data[key])
+        return None
+    except Exception:
+        return None
+
+
+async def lotto_evolver_status() -> Dict[str, Any]:
+    """GET /api/lotto/evolver/status — 이번주 trials + 다음주 base 정보."""
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/evolver/status")
+    resp.raise_for_status()
+    return resp.json()
+
+
+async def lotto_evolver_evaluate() -> Dict[str, Any]:
+    """POST /api/lotto/evolver/evaluate-now — 회고 트리거 (텔레그램 리포트용)."""
+    from .config import LOTTO_BACKEND_URL
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        resp = await client.post(f"{LOTTO_BACKEND_URL}/api/lotto/evolver/evaluate-now")
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def lotto_backtest_review(draw_no: int) -> Dict[str, Any]:
+    from .config import LOTTO_BACKEND_URL
+    resp = await _client.get(f"{LOTTO_BACKEND_URL}/api/lotto/backtest/review/{draw_no}")
+    resp.raise_for_status()
+    return resp.json()
+
+
+
+from .config import AGENT_CONTAINER_MAP
+
+
+async def fetch_service_logs(
+    agent_id: str,
+    since: Optional[str] = None,
+    limit: int = 200,
+) -> List[Dict[str, Any]]:
+    """해당 에이전트가 가리키는 컨테이너의 /logs/recent 를 호출해서
+    path_prefix 정규식으로 필터한 결과를 반환.
+
+    네트워크 실패 시 빈 리스트를 반환하고 warning 만 남김 (LogTab 이 죽지 않게).
+    """
+    mapping = AGENT_CONTAINER_MAP.get(agent_id)
+    if not mapping:
+        return []
+    host, port, path_re = mapping
+    url = f"http://{host}:{port}/logs/recent"
+    params: Dict[str, Any] = {"limit": limit}
+    if since:
+        params["since"] = since
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as client:
+            resp = await client.get(url, params=params)
+            data = resp.json().get("logs", [])
+    except Exception as e:
+        logger.warning("fetch_service_logs(%s) 실패: %s", agent_id, e)
+        return []
+    return [
+        x for x in data
+        if x.get("source") == "log"
+        or path_re.match(x.get("path", "") or "")
+    ]

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/app/test_db.py

@@ -93,6 +93,41 @@ def test_telegram_state():
     print("  [PASS] test_telegram_state")
 
 
+def test_get_logs_excludes_state_messages():
+    init_db()
+    add_log("stock", "State: idle -> working (큐레이션 시작)")
+    add_log("stock", "뉴스 12건 스크랩 완료")
+    add_log("stock", "State: working -> idle ()")
+
+    logs = get_logs("stock", limit=10)
+    messages = [x["message"] for x in logs]
+    assert "뉴스 12건 스크랩 완료" in messages
+    assert not any(m.startswith("State: ") for m in messages)
+
+
+def test_delete_old_logs_removes_beyond_retention():
+    import datetime as _dt
+    from app.db import delete_old_logs, _conn
+
+    init_db()
+    add_log("stock", "오래된 로그")
+    # 강제로 200일 전으로 옮김
+    cutoff = (_dt.datetime.utcnow() - _dt.timedelta(days=200)).isoformat()
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE agent_logs SET created_at = ? WHERE message = '오래된 로그'",
+            (cutoff,),
+        )
+
+    add_log("stock", "최근 로그")
+    deleted = delete_old_logs(days=90)
+    assert deleted >= 1
+
+    msgs = [x["message"] for x in get_logs("stock", limit=20)]
+    assert "최근 로그" in msgs
+    assert "오래된 로그" not in msgs
+
+
 if __name__ == "__main__":
     test_init_and_seed()
     test_agent_config_update()

agent-office/requirements.txt

@@ -4,5 +4,6 @@ apscheduler==3.10.4
 websockets>=12.0
 httpx>=0.27
 respx>=0.21
+pytest-asyncio>=0.23
 google-api-python-client>=2.100.0
 pytrends>=4.9.2

agent-office/scripts/migrate_tarot_to_lab.py

@@ -0,0 +1,81 @@
+"""1회성 마이그레이션 — agent_office.db.tarot_readings → tarot.db.tarot_readings.
+
+멱등성: 이미 존재하는 id는 SKIP.
+
+실행:
+    docker exec agent-office python /app/scripts/migrate_tarot_to_lab.py
+
+또는 호스트에서 직접:
+    AGENT_OFFICE_DB=/path/to/agent_office.db TAROT_DB=/path/to/tarot.db \\
+        python scripts/migrate_tarot_to_lab.py
+"""
+import os
+import sqlite3
+import sys
+
+
+SRC = os.getenv("AGENT_OFFICE_DB", "/app/data/agent_office.db")
+DST = os.getenv("TAROT_DB", "/app/data/tarot.db")
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS tarot_readings (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    spread_type         TEXT NOT NULL,
+    category            TEXT,
+    question            TEXT,
+    cards               TEXT NOT NULL,
+    interpretation_json TEXT,
+    summary             TEXT,
+    model               TEXT,
+    tokens_in           INTEGER,
+    tokens_out          INTEGER,
+    cost_usd            REAL,
+    confidence          TEXT,
+    favorite            INTEGER NOT NULL DEFAULT 0,
+    note                TEXT
+);
+"""
+
+
+def migrate() -> int:
+    """이관된 row 수 반환."""
+    src = sqlite3.connect(SRC)
+    src.row_factory = sqlite3.Row
+    dst = sqlite3.connect(DST)
+    dst.execute("PRAGMA journal_mode=WAL")
+    dst.executescript(SCHEMA)
+
+    rows = src.execute("SELECT * FROM tarot_readings").fetchall()
+    if not rows:
+        src.close(); dst.close()
+        return 0
+
+    all_cols = list(rows[0].keys())
+
+    moved = 0
+    for r in rows:
+        exists = dst.execute("SELECT 1 FROM tarot_readings WHERE id=?", (r["id"],)).fetchone()
+        if exists:
+            continue
+        # NULL 값은 INSERT에서 제외 → 목적지 스키마의 DEFAULT가 적용되도록 함
+        # (예: created_at이 NULL이면 strftime() 기본값 사용)
+        cols = [c for c in all_cols if r[c] is not None]
+        placeholders = ",".join("?" * len(cols))
+        cols_str = ",".join(cols)
+        dst.execute(
+            f"INSERT INTO tarot_readings ({cols_str}) VALUES ({placeholders})",
+            tuple(r[c] for c in cols),
+        )
+        moved += 1
+    dst.commit()
+    src.close(); dst.close()
+    return moved
+
+
+if __name__ == "__main__":
+    moved = migrate()
+    total = sqlite3.connect(SRC).execute("SELECT COUNT(*) FROM tarot_readings").fetchone()[0]
+    print(f"migrated {moved} / {total} rows from {SRC} to {DST}")
+    sys.exit(0)

agent-office/tests/test_holdings_brief_format.py

@@ -0,0 +1,82 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from app.notifiers import telegram_stock as ts
+
+
+def test_format_holdings_brief():
+    payload = {
+        "date": "2026-05-29",
+        "holdings": [
+            {"ticker": "005930", "name": "삼성전자", "action": "trim", "tech_score": 60.0,
+             "exit_flags": {"ma50_break": True}, "issues": [{"type":"news","severity":"high","summary":"악재"}],
+             "pnl_rate": 5.2, "reasons": "MA50 이탈"},
+            {"ticker": "000660", "name": "SK하이닉스", "action": "hold", "tech_score": 75.0,
+             "exit_flags": {}, "issues": [], "pnl_rate": -2.0, "reasons": "특이 신호 없음"},
+        ],
+        "portfolio_health": {"positions": 2, "total_pnl_rate": 3.1, "max_weight": 0.6, "cash_ratio": 0.2},
+    }
+    txt = ts.format_holdings_brief(payload)
+    assert "삼성전자" in txt
+    assert "축소" in txt or "trim" in txt
+    assert "%" in txt
+
+
+def test_format_holdings_brief_empty_holdings():
+    """빈 holdings + None portfolio_health에도 크래시 없음."""
+    payload = {"date": "2026-05-29", "holdings": [], "portfolio_health": None}
+    txt = ts.format_holdings_brief(payload)
+    assert "보유종목 인텔리전스" in txt
+    assert "자동매매" in txt
+
+
+def test_format_holdings_brief_missing_fields():
+    """pnl_rate None·name None·issues None 방어적 처리."""
+    payload = {
+        "date": None,
+        "holdings": [
+            {"ticker": "005930", "name": None, "action": "sell",
+             "pnl_rate": None, "reasons": None, "issues": None},
+        ],
+        "portfolio_health": {},
+    }
+    txt = ts.format_holdings_brief(payload)
+    assert "005930" in txt          # ticker fallback
+    assert "🔴 매도" in txt
+
+
+def test_format_holdings_brief_sell_action():
+    """sell 액션은 🔴 매도로 표시."""
+    payload = {
+        "date": "2026-05-29",
+        "holdings": [
+            {"ticker": "000660", "name": "SK하이닉스", "action": "sell",
+             "pnl_rate": -12.5, "reasons": "손절선 이탈", "issues": []},
+        ],
+        "portfolio_health": {"positions": 1, "total_pnl_rate": -12.5,
+                             "max_weight": 1.0, "cash_ratio": 0.0},
+    }
+    txt = ts.format_holdings_brief(payload)
+    assert "🔴 매도" in txt
+    assert "-12.5%" in txt
+
+
+def test_format_holdings_brief_issue_severity_icons():
+    """이슈 심각도별 이모지 매핑 확인."""
+    payload = {
+        "date": "2026-05-29",
+        "holdings": [
+            {"ticker": "005930", "name": "삼성전자", "action": "hold", "pnl_rate": 2.0,
+             "reasons": "특이 신호 없음",
+             "issues": [
+                 {"type": "news", "severity": "high", "summary": "심각 악재"},
+                 {"type": "volume_surge", "severity": "med", "summary": "거래량 급증"},
+                 {"type": "price_move", "severity": "low", "summary": "소폭 변동"},
+             ]},
+        ],
+        "portfolio_health": {},
+    }
+    txt = ts.format_holdings_brief(payload)
+    assert "🔴" in txt   # high severity
+    assert "🟠" in txt   # med severity
+    assert "🟡" in txt   # low severity

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_insta_keyword_filter.py

@@ -0,0 +1,55 @@
+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 app.agents.insta import _dedup_and_filter_keywords, KEYWORD_MIN_SCORE
+
+
+def test_filters_below_threshold():
+    """score < 임계값(0.7) 키워드는 제외."""
+    kws = [
+        {"id": 1, "keyword": "금리인하", "category": "경제", "score": 0.9},
+        {"id": 2, "keyword": "환율", "category": "경제", "score": 0.6},  # 컷
+        {"id": 3, "keyword": "반도체", "category": "경제", "score": 0.71},
+    ]
+    out = _dedup_and_filter_keywords(kws, min_score=0.7)
+    kept = {k["keyword"] for k in out}
+    assert kept == {"금리인하", "반도체"}
+
+
+def test_dedup_keeps_highest_score():
+    """동일 keyword 중복 시 최고 score 1개만 유지."""
+    kws = [
+        {"id": 1, "keyword": "AI", "category": "경제", "score": 0.75},
+        {"id": 2, "keyword": "AI", "category": "기술", "score": 0.92},  # 같은 키워드, 더 높음
+    ]
+    out = _dedup_and_filter_keywords(kws, min_score=0.7)
+    assert len(out) == 1
+    assert out[0]["id"] == 2
+    assert out[0]["score"] == 0.92
+
+
+def test_sorted_by_score_desc():
+    kws = [
+        {"id": 1, "keyword": "a", "category": "c", "score": 0.72},
+        {"id": 2, "keyword": "b", "category": "c", "score": 0.95},
+        {"id": 3, "keyword": "c", "category": "c", "score": 0.80},
+    ]
+    out = _dedup_and_filter_keywords(kws, min_score=0.7)
+    assert [k["keyword"] for k in out] == ["b", "c", "a"]
+
+
+def test_empty_when_all_below_threshold():
+    kws = [{"id": 1, "keyword": "x", "category": "c", "score": 0.4}]
+    assert _dedup_and_filter_keywords(kws, min_score=0.7) == []
+
+
+def test_default_threshold_is_0_7():
+    assert KEYWORD_MIN_SCORE == 0.7

agent-office/tests/test_log_merge.py

@@ -0,0 +1,47 @@
+import pytest
+import respx
+import httpx
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.db import add_log, _conn
+
+
+@pytest.fixture(autouse=True)
+def _clean_logs():
+    with _conn() as conn:
+        conn.execute("DELETE FROM agent_logs WHERE agent_id = 'lotto'")
+    yield
+
+
+@respx.mock
+def test_agent_logs_endpoint_merges_db_and_service_logs():
+    add_log("lotto", "큐레이션 완료: #1234 conf=0.78")
+    respx.get("http://lotto:8000/logs/recent").mock(
+        return_value=httpx.Response(200, json={
+            "logs": [
+                {"ts": "2026-05-28T10:00:00Z", "source": "access",
+                 "method": "GET", "path": "/api/lotto/latest",
+                 "status": 200, "ms": 8,
+                 "message": "GET /api/lotto/latest → 200 (8ms)"},
+                {"ts": "2026-05-28T10:00:02Z", "source": "log",
+                 "logger": "lotto", "level": "info",
+                 "message": "성과 통계 캐시 갱신"},
+            ]
+        })
+    )
+
+    client = TestClient(app)
+    resp = client.get("/api/agent-office/agents/lotto/logs?limit=20")
+    assert resp.status_code == 200
+    logs = resp.json()["logs"]
+
+    sources = {x["source"] for x in logs}
+    assert "agent" in sources
+    assert "access" in sources
+    assert "log" in sources
+
+    messages = [x["message"] for x in logs]
+    assert any("큐레이션 완료" in m for m in messages)
+    assert any("성과 통계 캐시 갱신" in m for m in messages)
+    assert any("/api/lotto/latest" in m for m in messages)

agent-office/tests/test_lotto_evolution_format.py

@@ -0,0 +1,87 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from app.notifiers.telegram_lotto import _format_evolution_report
+
+
+def test_evolution_report_winner_4plus():
+    eval_result = {
+        "ok": True,
+        "draw_no": 1225,
+        "week_start": "2026-05-18",
+        "winner": {
+            "day_of_week": 3,
+            "weight": [0.18, 0.32, 0.20, 0.22, 0.08],
+            "avg_score": 0.42,
+            "max_correct": 4,
+            "n_picks": 5,
+        },
+        "new_base": [0.18, 0.32, 0.20, 0.22, 0.08],
+        "previous_base": [0.20, 0.20, 0.20, 0.20, 0.20],
+        "update_reason": "winner_4plus",
+        "per_day": [
+            {"day_of_week": 0, "avg_score": 0.20, "max_correct": 2},
+            {"day_of_week": 3, "avg_score": 0.42, "max_correct": 4},
+        ],
+    }
+    current_base = [0.20, 0.20, 0.20, 0.20, 0.20]
+    text = _format_evolution_report(eval_result, current_base)
+    assert "🧬" in text
+    assert "1225" in text
+    assert "목요일" in text or "Winner" in text
+    assert "4개 일치" in text or "max=4" in text
+    assert "winner_4plus" in text
+
+
+def test_evolution_report_unchanged():
+    eval_result = {
+        "ok": True,
+        "draw_no": 1226,
+        "week_start": "2026-05-25",
+        "winner": {
+            "day_of_week": 1,
+            "weight": [0.21, 0.19, 0.20, 0.20, 0.20],
+            "avg_score": 0.10,
+            "max_correct": 2,
+            "n_picks": 5,
+        },
+        "new_base": [0.20, 0.20, 0.20, 0.20, 0.20],
+        "update_reason": "unchanged",
+        "per_day": [],
+    }
+    current_base = [0.20, 0.20, 0.20, 0.20, 0.20]
+    text = _format_evolution_report(eval_result, current_base)
+    assert "unchanged" in text or "유지" in text
+    assert "2개 일치" in text or "max=2" in text
+
+
+def test_evolution_report_empty_returns_empty():
+    """evaluate가 ok=False면 빈 문자열 (발송 skip)."""
+    text = _format_evolution_report({"ok": False, "reason": "no_trials"}, [0.2]*5)
+    assert text == ""
+
+
+def test_evolution_report_uses_previous_base_for_diff():
+    """previous_base와 new_base 차이가 메시지 diff에 정확히 반영됨."""
+    eval_result = {
+        "ok": True,
+        "draw_no": 1227,
+        "winner": {
+            "day_of_week": 0,
+            "weight": [0.30, 0.20, 0.20, 0.20, 0.10],
+            "avg_score": 0.50,
+            "max_correct": 4,
+            "n_picks": 5,
+        },
+        "new_base": [0.30, 0.20, 0.20, 0.20, 0.10],
+        "previous_base": [0.20, 0.20, 0.20, 0.20, 0.20],
+        "update_reason": "winner_4plus",
+    }
+    # current_base는 stale (post-update 값) — previous_base가 우선 적용되어야 함
+    text = _format_evolution_report(eval_result, [0.30, 0.20, 0.20, 0.20, 0.10])
+    # freq: 0.20 → 0.30 (+0.10 = "++")
+    # divers: 0.20 → 0.10 (-0.10 = "--")
+    assert "0.20 → 0.30" in text   # freq 증가
+    assert "0.20 → 0.10" in text   # divers 감소
+    assert "(++)" in text or "(+)" in text   # freq marker
+    assert "(--)" in text or "(-)" in text   # divers marker

agent-office/tests/test_lotto_signal_runner.py

@@ -0,0 +1,116 @@
+import gc
+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 pytest
+
+from app.curator import signal_runner
+from app import db
+
+db.DB_PATH = _TMP  # patch frozen module-level DB_PATH (import order safety)
+
+
+@pytest.fixture(autouse=True)
+def fresh_db():
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    db.init_db()
+    yield
+    gc.collect()
+    if os.path.exists(_TMP):
+        try:
+            os.remove(_TMP)
+        except PermissionError:
+            pass  # Windows: WAL-mode file locked; DB is ephemeral anyway
+
+
+def test_evaluate_and_persist_cold_start():
+    """첫 호출은 warmup으로 기록되고 baseline에 값이 들어간다."""
+    result = signal_runner.evaluate_metric_and_persist(
+        source="light",
+        metric="sim_signal",
+        value=1.5,
+        draw_no=None,
+        z_normal=1.5,
+        z_urgent=2.5,
+        push_to_window=True,
+    )
+    assert result["fire_level"] == "warmup"
+    assert result["z_score"] is None
+
+    bl = db.get_baseline("sim_signal")
+    assert bl is not None
+    assert bl["window_values"] == [1.5]
+
+
+def test_evaluate_after_window_filled_normal_fire():
+    """8회 push 후 정상 운영, 평균 대비 z≥1.5면 normal."""
+    for v in [1.0, 1.1, 0.9, 1.0, 1.0, 1.1, 0.9, 1.0]:
+        signal_runner.evaluate_metric_and_persist(
+            source="sim",
+            metric="sim_signal",
+            value=v,
+            draw_no=None,
+            z_normal=1.5,
+            z_urgent=2.5,
+            push_to_window=True,
+        )
+
+    result = signal_runner.evaluate_metric_and_persist(
+        source="sim",
+        metric="sim_signal",
+        value=1.12,
+        draw_no=None,
+        z_normal=1.5,
+        z_urgent=2.5,
+        push_to_window=True,
+    )
+    assert result["fire_level"] in ("normal", "urgent")
+    assert result["z_score"] is not None and result["z_score"] >= 1.5
+
+
+def test_evaluate_drift_skips_same_draw_push():
+    """drift는 회차 단위. 같은 회차에서 두 번 호출하면 두 번째는 window push X."""
+    signal_runner.evaluate_metric_and_persist(
+        source="sim", metric="drift", value=0.05, draw_no=1100,
+        z_normal=1.5, z_urgent=2.5, push_to_window=True,
+    )
+    bl_before = db.get_baseline("drift")
+    assert bl_before["window_values"] == [0.05]
+    assert bl_before["last_pushed_draw_no"] == 1100
+
+    signal_runner.evaluate_metric_and_persist(
+        source="sim", metric="drift", value=0.08, draw_no=1100,
+        z_normal=1.5, z_urgent=2.5, push_to_window=True,
+    )
+    bl_after = db.get_baseline("drift")
+    assert bl_after["window_values"] == [0.05]
+
+
+@pytest.mark.asyncio
+async def test_run_signal_check_aggregates_three_metrics(monkeypatch):
+    """run_signal_check이 3종 메트릭 모두 평가하고 overall fire를 반환."""
+    async def fake_lotto_best():
+        return [{"numbers": [1,2,3,4,5,6], "scores": [10,10,10,10,10]}] * 20
+
+    async def fake_lotto_strategy_weights():
+        return {"gap_focus": 0.4, "hot_focus": 0.3, "pair_bias": 0.3}
+
+    monkeypatch.setattr(signal_runner, "_fetch_best_picks", fake_lotto_best)
+    monkeypatch.setattr(signal_runner, "_fetch_strategy_weights", fake_lotto_strategy_weights)
+
+    out = await signal_runner.run_signal_check(source="light", curate_result=None, current_draw_no=1101)
+    assert "overall_fire" in out
+    assert "results" in out
+    assert any(r["metric"] == "sim_signal" for r in out["results"])
+    # light_check는 confidence 평가 안 함
+    assert not any(r["metric"] == "confidence" for r in out["results"])

agent-office/tests/test_lotto_signals.py

@@ -0,0 +1,130 @@
+# agent-office/tests/test_lotto_signals.py
+import pytest
+
+from app.curator import signals
+
+
+def test_sim_consensus_top10_geomean():
+    """top-10 consensus 평균이 기하평균 기반인지."""
+    best_picks = [
+        {"scores": [10, 10, 10, 10, 10]},  # high & uniform
+        {"scores": [9,  9,  9,  9,  9]},
+        {"scores": [8,  8,  8,  8,  8]},
+        {"scores": [7,  7,  7,  7,  7]},
+        {"scores": [6,  6,  6,  6,  6]},
+        {"scores": [5,  5,  5,  5,  5]},
+        {"scores": [4,  4,  4,  4,  4]},
+        {"scores": [3,  3,  3,  3,  3]},
+        {"scores": [2,  2,  2,  2,  2]},
+        {"scores": [1,  1,  1,  1,  1]},  # top 10
+        {"scores": [0,  0,  0,  0,  0]},  # bottom 10
+    ] * 1 + [{"scores": [0, 0, 0, 0, 0]}] * 10
+    result = signals.sim_consensus_score(best_picks)
+    assert 0.0 <= result <= 1.0
+    assert result > 0.4
+
+
+def test_sim_consensus_geomean_penalizes_imbalance():
+    """5종 중 한 종만 폭주하는 outlier 후보는 균형 후보보다 작아야 한다."""
+    balanced = [{"scores": [5, 5, 5, 5, 5]}] * 20
+    imbalanced = [{"scores": [25, 0, 0, 0, 0]}] * 20
+    s_balanced = signals.sim_consensus_score(balanced)
+    s_imbalanced = signals.sim_consensus_score(imbalanced)
+    assert s_imbalanced < s_balanced
+
+
+def test_strategy_drift_score():
+    """drift = 전략별 가중치 변화 절댓값 합."""
+    w_prev = {"gap_focus": 0.30, "hot_focus": 0.25, "pair_bias": 0.45}
+    w_curr = {"gap_focus": 0.40, "hot_focus": 0.20, "pair_bias": 0.40}
+    result = signals.strategy_drift_score(w_prev, w_curr)
+    assert abs(result - 0.20) < 1e-9
+
+
+def test_strategy_drift_new_strategy_appears():
+    """이전에 없던 전략이 등장하면 그 가중치 전체가 drift에 가산."""
+    w_prev = {"gap_focus": 0.5, "hot_focus": 0.5}
+    w_curr = {"gap_focus": 0.4, "hot_focus": 0.4, "newbie": 0.2}
+    result = signals.strategy_drift_score(w_prev, w_curr)
+    assert abs(result - 0.4) < 1e-9
+
+
+def test_confidence_score_passthrough():
+    """confidence는 큐레이션 결과의 값 그대로 (0~1 clamp 확인)."""
+    assert signals.confidence_score({"confidence": 0.85}) == 0.85
+    assert signals.confidence_score({"confidence": 1.2}) == 1.0
+    assert signals.confidence_score({"confidence": -0.1}) == 0.0
+    assert signals.confidence_score({}) is None
+
+
+def test_adaptive_baseline_cold_start():
+    """window 크기 < 4 → warmup, z=None."""
+    bl = signals.AdaptiveBaseline(window=[1.0, 1.1, 0.9], window_max=8)
+    z, fire = bl.evaluate(value=1.5, z_normal=1.5, z_urgent=2.5)
+    assert fire == "warmup"
+    assert z is None
+
+
+def test_adaptive_baseline_preparing():
+    """window 4~7 → 보수적 임계치 z=2.0."""
+    bl = signals.AdaptiveBaseline(window=[1.0, 1.0, 1.0, 1.0], window_max=8)
+    z, fire = bl.evaluate(value=3.0, z_normal=1.5, z_urgent=2.5)
+    assert fire in ("normal", "urgent")
+
+
+def test_adaptive_baseline_normal_window_full():
+    """window 8 풀, value가 평균보다 1.5σ 이상이면 normal."""
+    bl = signals.AdaptiveBaseline(
+        window=[1.0, 1.1, 0.9, 1.0, 1.0, 1.1, 0.9, 1.0],
+        window_max=8,
+    )
+    z, fire = bl.evaluate(value=1.12, z_normal=1.5, z_urgent=2.5)
+    assert fire == "normal"
+    assert z is not None and z >= 1.5
+
+
+def test_adaptive_baseline_urgent():
+    """z >= 2.5 → urgent."""
+    bl = signals.AdaptiveBaseline(
+        window=[1.0, 1.1, 0.9, 1.0, 1.0, 1.1, 0.9, 1.0],
+        window_max=8,
+    )
+    z, fire = bl.evaluate(value=2.0, z_normal=1.5, z_urgent=2.5)
+    assert fire == "urgent"
+
+
+def test_adaptive_baseline_push_updates_window():
+    """push 시 FIFO 동작."""
+    bl = signals.AdaptiveBaseline(window=[1, 2, 3, 4, 5, 6, 7, 8], window_max=8)
+    bl.push(9.0)
+    assert bl.window == [2, 3, 4, 5, 6, 7, 8, 9.0]
+
+
+def test_decide_fire_level_two_normals_escalate():
+    sigs = [
+        {"metric": "sim", "z": 1.6, "fire": "normal"},
+        {"metric": "drift", "z": 1.7, "fire": "normal"},
+        {"metric": "conf", "z": 0.5, "fire": "noop"},
+    ]
+    assert signals.decide_overall_fire(sigs) == "urgent"
+
+
+def test_decide_fire_level_single_normal():
+    sigs = [
+        {"metric": "sim", "z": 1.6, "fire": "normal"},
+        {"metric": "drift", "z": 0.3, "fire": "noop"},
+    ]
+    assert signals.decide_overall_fire(sigs) == "normal"
+
+
+def test_decide_fire_level_single_urgent():
+    sigs = [
+        {"metric": "sim", "z": 3.0, "fire": "urgent"},
+        {"metric": "drift", "z": 0.2, "fire": "noop"},
+    ]
+    assert signals.decide_overall_fire(sigs) == "urgent"
+
+
+def test_decide_fire_level_all_noop():
+    sigs = [{"metric": "sim", "z": 0.5, "fire": "noop"}]
+    assert signals.decide_overall_fire(sigs) == "noop"

agent-office/tests/test_lotto_task_wrap.py

@@ -0,0 +1,154 @@
+# agent-office/tests/test_lotto_task_wrap.py
+import os
+import sys
+import tempfile
+import gc
+
+_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 pytest
+from app import db
+db.DB_PATH = _TMP
+
+
+@pytest.fixture(autouse=True)
+def fresh_db():
+    # Re-patch DB_PATH at the start of every test (cross-file isolation)
+    db.DB_PATH = _TMP
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    db.init_db()
+    yield
+    gc.collect()
+    if os.path.exists(_TMP):
+        try:
+            os.remove(_TMP)
+        except PermissionError:
+            pass
+
+
+@pytest.mark.asyncio
+async def test_run_signal_check_creates_task_row(monkeypatch):
+    """run_signal_check이 agent_tasks에 row를 만들고 result_data를 저장."""
+    from app.agents.lotto import LottoAgent
+    from app.curator import signal_runner
+
+    async def fake_run_signal_check(**kwargs):
+        return {
+            "overall_fire": "normal",
+            "results": [
+                {"signal_id": 1, "metric": "sim_signal",
+                 "value": 0.6, "z_score": 1.7, "fire_level": "normal",
+                 "baseline_mu": 0.5, "baseline_sigma": 0.05, "payload": {}},
+            ],
+        }
+    monkeypatch.setattr(signal_runner, "run_signal_check", fake_run_signal_check)
+
+    from app import service_proxy
+    async def fake_latest():
+        return 1226
+    monkeypatch.setattr(service_proxy, "lotto_latest_draw", fake_latest)
+
+    from app.notifiers import telegram_lotto
+    async def fake_send(_event): pass
+    monkeypatch.setattr(telegram_lotto, "send_urgent_signal", fake_send)
+
+    agent = LottoAgent()
+    result = await agent.run_signal_check(source="light")
+    assert result["ok"] is True
+
+    tasks = db.get_agent_tasks("lotto", task_type="signal_check", days=1)
+    assert len(tasks) == 1
+    t = tasks[0]
+    assert t["status"] == "succeeded"
+    assert t["result_data"]["source"] == "light"
+    assert t["result_data"]["overall_fire"] == "normal"
+    assert "sim_signal" in t["result_data"]["fired_metrics"]
+
+
+@pytest.mark.asyncio
+async def test_run_signal_check_failure_marks_task_failed(monkeypatch):
+    from app.agents.lotto import LottoAgent
+    from app.curator import signal_runner
+    from app import service_proxy
+
+    async def boom(**kwargs):
+        raise RuntimeError("boom")
+    monkeypatch.setattr(signal_runner, "run_signal_check", boom)
+
+    async def fake_latest():
+        return 1226
+    monkeypatch.setattr(service_proxy, "lotto_latest_draw", fake_latest)
+
+    agent = LottoAgent()
+    result = await agent.run_signal_check(source="sim")
+    assert result["ok"] is False
+
+    tasks = db.get_agent_tasks("lotto", task_type="signal_check", days=1)
+    assert len(tasks) == 1
+    assert tasks[0]["status"] == "failed"
+    assert "boom" in tasks[0]["result_data"]["error"]
+
+
+@pytest.mark.asyncio
+async def test_run_daily_digest_creates_task(monkeypatch):
+    """run_daily_digest이 agent_tasks에 task 생성 + result_data 저장."""
+    from app.agents.lotto import LottoAgent
+    from app.notifiers import telegram_lotto
+
+    async def fake_send(_d): pass
+    monkeypatch.setattr(telegram_lotto, "send_signal_summary", fake_send)
+
+    agent = LottoAgent()
+    result = await agent.run_daily_digest()
+    assert result["ok"] is True
+
+    tasks = db.get_agent_tasks("lotto", task_type="daily_digest", days=1)
+    assert len(tasks) == 1
+    assert tasks[0]["status"] == "succeeded"
+    assert "fired" in tasks[0]["result_data"]
+    assert "evaluated" in tasks[0]["result_data"]
+
+
+@pytest.mark.asyncio
+async def test_run_weekly_evolution_report_creates_task(monkeypatch):
+    """run_weekly_evolution_report이 task 생성 + result_data 저장."""
+    from app.agents.lotto import LottoAgent
+    from app import service_proxy
+    from app.notifiers import telegram_lotto
+
+    async def fake_eval():
+        return {
+            "ok": True, "draw_no": 1225,
+            "winner": {"day_of_week": 3, "weight": [0.18, 0.32, 0.20, 0.22, 0.08],
+                       "avg_score": 0.42, "max_correct": 4, "n_picks": 5},
+            "new_base": [0.18, 0.32, 0.20, 0.22, 0.08],
+            "previous_base": [0.2] * 5,
+            "update_reason": "winner_4plus",
+        }
+    async def fake_status():
+        return {"current_base": [0.2] * 5}
+    async def fake_send(_e, _b): pass
+
+    monkeypatch.setattr(service_proxy, "lotto_evolver_evaluate", fake_eval)
+    monkeypatch.setattr(service_proxy, "lotto_evolver_status", fake_status)
+    monkeypatch.setattr(telegram_lotto, "send_evolution_report", fake_send)
+
+    agent = LottoAgent()
+    result = await agent.run_weekly_evolution_report()
+    assert result["ok"] is True
+
+    tasks = db.get_agent_tasks("lotto", task_type="weekly_evolution_report", days=1)
+    assert len(tasks) == 1
+    r = tasks[0]["result_data"]
+    assert tasks[0]["status"] == "succeeded"
+    assert r["draw_no"] == 1225
+    assert r["update_reason"] == "winner_4plus"
+    assert r["winner_day_of_week"] == 3
+    assert r["winner_max_correct"] == 4

agent-office/tests/test_lotto_telegram_signal.py

@@ -0,0 +1,49 @@
+from app.notifiers.telegram_lotto import (
+    _format_urgent_signal,
+    _format_signal_digest,
+)
+
+
+def test_urgent_signal_format_basic():
+    event = {
+        "fire_level": "urgent",
+        "triggered_at": "2026-05-20T07:18:00.000Z",
+        "results": [
+            {"metric": "sim_signal", "value": 1.84, "z_score": 3.9,
+             "baseline_mu": 1.02, "baseline_sigma": 0.21, "payload": {},
+             "fire_level": "urgent"},
+            {"metric": "drift", "value": 0.18, "z_score": 3.0,
+             "baseline_mu": 0.06, "baseline_sigma": 0.04, "fire_level": "normal",
+             "payload": {"weights_now": {"gap_focus": 0.5, "hot_focus": 0.5},
+                         "weights_prev": {"gap_focus": 0.3, "hot_focus": 0.7}}},
+        ],
+    }
+    text = _format_urgent_signal(event)
+    assert "🚨" in text
+    assert "Sim Consensus" in text
+    assert "z=3.9" in text
+    assert "Strategy Drift" in text
+
+
+def test_signal_digest_format_with_signals():
+    digest = {
+        "evaluated": 6,
+        "fired": 2,
+        "signals": [
+            {"metric": "sim_signal", "fire_level": "normal", "z_score": 1.7,
+             "triggered_at": "2026-05-20T16:18:00Z", "payload": {}},
+            {"metric": "confidence", "fire_level": "normal", "z_score": 1.6,
+             "triggered_at": "2026-05-20T09:05:00Z", "payload": {}},
+        ],
+        "weights_trend": {"gap_focus": +0.12, "hot_focus": -0.02, "pair_bias": -0.08},
+    }
+    text = _format_signal_digest(digest)
+    assert "📊" in text
+    assert "지난 24h" in text
+    assert "z=1.7" in text
+
+
+def test_signal_digest_empty_returns_empty_string():
+    """발화 0건이면 빈 문자열 → 발송 자체 skip 가능."""
+    text = _format_signal_digest({"evaluated": 6, "fired": 0, "signals": [], "weights_trend": {}})
+    assert text == ""

agent-office/tests/test_migrate_tarot.py

@@ -0,0 +1,72 @@
+"""migrate_tarot_to_lab.py 단위 테스트 — 멱등성 + 데이터 보존."""
+import sqlite3
+import sys
+import os
+import pytest
+
+
+@pytest.fixture
+def src_db(tmp_path):
+    p = tmp_path / "agent_office.db"
+    conn = sqlite3.connect(str(p))
+    conn.execute("""
+        CREATE TABLE tarot_readings (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            created_at TEXT, spread_type TEXT, category TEXT, question TEXT,
+            cards TEXT, interpretation_json TEXT, summary TEXT, model TEXT,
+            tokens_in INTEGER, tokens_out INTEGER, cost_usd REAL,
+            confidence TEXT, favorite INTEGER, note TEXT
+        )
+    """)
+    conn.execute("""
+        INSERT INTO tarot_readings (id, spread_type, category, cards, model, favorite)
+        VALUES (1, 'three_card', '연애', '[]', 'm', 0),
+               (2, 'one_card', '재물', '[]', 'm', 1)
+    """)
+    conn.commit()
+    conn.close()
+    return str(p)
+
+
+@pytest.fixture
+def dst_db(tmp_path):
+    return str(tmp_path / "tarot.db")
+
+
+def _import_migrate(src, dst, monkeypatch):
+    monkeypatch.setenv("AGENT_OFFICE_DB", src)
+    monkeypatch.setenv("TAROT_DB", dst)
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))
+    import migrate_tarot_to_lab as m
+    import importlib
+    importlib.reload(m)
+    return m
+
+
+def test_first_run_copies_all_rows(src_db, dst_db, monkeypatch):
+    m = _import_migrate(src_db, dst_db, monkeypatch)
+    moved = m.migrate()
+    assert moved == 2
+    conn = sqlite3.connect(dst_db)
+    rows = conn.execute("SELECT id, spread_type, category FROM tarot_readings ORDER BY id").fetchall()
+    conn.close()
+    assert rows == [(1, "three_card", "연애"), (2, "one_card", "재물")]
+
+
+def test_idempotent_second_run(src_db, dst_db, monkeypatch):
+    m = _import_migrate(src_db, dst_db, monkeypatch)
+    m.migrate()
+    moved2 = m.migrate()
+    assert moved2 == 0
+
+
+def test_partial_migration(src_db, dst_db, monkeypatch):
+    """dst에 id=1만 있는 상태에서 다시 돌리면 id=2만 옮김."""
+    m = _import_migrate(src_db, dst_db, monkeypatch)
+    m.migrate()
+    conn = sqlite3.connect(dst_db)
+    conn.execute("DELETE FROM tarot_readings WHERE id=2")
+    conn.commit()
+    conn.close()
+    moved = m.migrate()
+    assert moved == 1

agent-office/tests/test_service_proxy_logs.py

@@ -0,0 +1,53 @@
+import pytest
+import respx
+import httpx
+
+from app.service_proxy import fetch_service_logs
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_fetch_service_logs_filters_by_path_prefix():
+    # lotto 컨테이너 응답: lotto + personal 섞임
+    respx.get("http://lotto:8000/logs/recent").mock(
+        return_value=httpx.Response(200, json={
+            "logs": [
+                {"ts": "2026-05-28T10:00:00Z", "source": "access",
+                 "method": "GET", "path": "/api/lotto/recommend",
+                 "status": 200, "ms": 12,
+                 "message": "GET /api/lotto/recommend → 200 (12ms)"},
+                {"ts": "2026-05-28T10:00:01Z", "source": "access",
+                 "method": "GET", "path": "/api/blog/posts",
+                 "status": 200, "ms": 5,
+                 "message": "GET /api/blog/posts → 200 (5ms)"},
+                {"ts": "2026-05-28T10:00:02Z", "source": "log",
+                 "logger": "lotto", "level": "info",
+                 "message": "성과 통계 캐시 갱신"},
+            ]
+        })
+    )
+
+    result = await fetch_service_logs("lotto", limit=50)
+    # lotto path 와 모든 log 이벤트만 통과
+    paths = [x.get("path") for x in result]
+    assert "/api/lotto/recommend" in paths
+    assert "/api/blog/posts" not in paths
+    # 비즈니스 로그도 포함
+    assert any(x["source"] == "log" and x["message"] == "성과 통계 캐시 갱신"
+               for x in result)
+
+
+@pytest.mark.asyncio
+async def test_fetch_service_logs_unknown_agent_returns_empty():
+    result = await fetch_service_logs("nonexistent", limit=50)
+    assert result == []
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_fetch_service_logs_handles_connection_error():
+    respx.get("http://lotto:8000/logs/recent").mock(
+        side_effect=httpx.ConnectError("connection refused")
+    )
+    result = await fetch_service_logs("lotto", limit=50)
+    assert result == []

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_sunday_review.py

@@ -0,0 +1,38 @@
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from app.notifiers import telegram_lotto as tl
+
+
+def test_format_sunday_review_text():
+    payload = {
+        "draw_no": 1170,
+        "winner_analysis": {"score_total": 0.41, "percentile": 0.33,
+            "score_frequency": 0.4, "score_fingerprint": 0.5, "score_gap": 0.3,
+            "score_cooccur": 0.45, "score_diversity": 0.6},
+        "forward": [
+            {"strategy": "engine_w", "label": "w1", "prizes": {"1st":0,"2nd":0,"3rd":0,"4th":1,"5th":12}, "best_match": 4, "avg_meta_score": 0.55},
+            {"strategy": "random_null", "label": "-", "prizes": {"1st":0,"2nd":0,"3rd":0,"4th":0,"5th":10}, "best_match": 3, "avg_meta_score": 0.33},
+        ],
+        "track_record": {},
+        "calibration_trend": [{"draw_no":1170,"score_total":0.41,"percentile":0.33}],
+    }
+    txt = tl.format_sunday_review(payload)
+    assert "1170" in txt
+    assert "%" in txt        # percentile 표기
+    assert "engine" in txt.lower() or "엔진" in txt
+
+
+def test_format_sunday_review_no_calibration():
+    payload = {"draw_no": 1171, "winner_analysis": None, "forward": []}
+    txt = tl.format_sunday_review(payload)
+    assert "1171" in txt
+    assert "%" not in txt  # no percentile section when calibration absent
+    assert "데이터 없음" in txt
+
+
+def test_format_sunday_review_missing_prizes_no_crash():
+    payload = {"draw_no": 1171, "winner_analysis": None,
+               "forward": [{"strategy": "engine_w", "label": "w1", "best_match": 3}]}  # no 'prizes'
+    txt = tl.format_sunday_review(payload)   # must NOT raise
+    assert "1171" in txt

agent-office/tests/test_sync_evolver_activity.py

@@ -0,0 +1,123 @@
+# agent-office/tests/test_sync_evolver_activity.py
+import os
+import sys
+import tempfile
+import gc
+from datetime import datetime, timezone, timedelta
+
+_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 pytest
+from app import db
+db.DB_PATH = _TMP
+
+
+@pytest.fixture(autouse=True)
+def fresh_db():
+    # Re-patch DB_PATH at the start of every test (cross-file isolation)
+    db.DB_PATH = _TMP
+    gc.collect()
+    if os.path.exists(_TMP):
+        os.remove(_TMP)
+    db.init_db()
+    yield
+    gc.collect()
+    if os.path.exists(_TMP):
+        try:
+            os.remove(_TMP)
+        except PermissionError:
+            pass
+
+
+def _today_dow_clamped():
+    """오늘의 weekday() (일요일=6은 5로 clamp)."""
+    KST = timezone(timedelta(hours=9))
+    dow = datetime.now(KST).weekday()
+    return 5 if dow == 6 else dow
+
+
+def _fake_status_with_picks(dow_with_picks):
+    async def fake():
+        return {
+            "week_start": "2026-05-18",
+            "current_base": [0.2] * 5,
+            "trials": [
+                {
+                    "id": 100 + i,
+                    "day_of_week": i,
+                    "weight": [0.2] * 5,
+                    "source": "perturb",
+                    "picks": ([
+                        {"id": j, "numbers": [1,2,3,4,5,6], "meta_score": 0.5}
+                        for j in range(5)
+                    ] if i == dow_with_picks else []),
+                }
+                for i in range(6)
+            ],
+        }
+    return fake
+
+
+@pytest.mark.asyncio
+async def test_sync_evolver_activity_creates_apply_task(monkeypatch):
+    """오늘 trial에 picks가 있으면 evolver_apply task 1개 생성."""
+    from app.agents.lotto import LottoAgent
+    from app import service_proxy
+
+    dow = _today_dow_clamped()
+    monkeypatch.setattr(service_proxy, "lotto_evolver_status", _fake_status_with_picks(dow))
+
+    agent = LottoAgent()
+    await agent.sync_evolver_activity()
+
+    apply_tasks = db.get_agent_tasks("lotto", task_type="evolver_apply", days=1)
+    assert len(apply_tasks) == 1
+    assert apply_tasks[0]["result_data"]["n_picks"] == 5
+    assert apply_tasks[0]["input_data"]["day_of_week"] == dow
+
+
+@pytest.mark.asyncio
+async def test_sync_evolver_activity_idempotent(monkeypatch):
+    """같은 날 두 번 호출해도 task는 1개만 (멱등)."""
+    from app.agents.lotto import LottoAgent
+    from app import service_proxy
+
+    dow = _today_dow_clamped()
+    monkeypatch.setattr(service_proxy, "lotto_evolver_status", _fake_status_with_picks(dow))
+
+    agent = LottoAgent()
+    await agent.sync_evolver_activity()
+    await agent.sync_evolver_activity()
+
+    apply_tasks = db.get_agent_tasks("lotto", task_type="evolver_apply", days=1)
+    assert len(apply_tasks) == 1
+
+
+@pytest.mark.asyncio
+async def test_sync_evolver_activity_no_picks_no_task(monkeypatch):
+    """오늘 trial에 picks가 없으면 task 생성하지 않음."""
+    from app.agents.lotto import LottoAgent
+    from app import service_proxy
+
+    async def fake_status():
+        return {
+            "week_start": "2026-05-18",
+            "current_base": [0.2] * 5,
+            "trials": [
+                {"id": 100 + i, "day_of_week": i, "weight": [0.2]*5,
+                 "source": "perturb", "picks": []}
+                for i in range(6)
+            ],
+        }
+    monkeypatch.setattr(service_proxy, "lotto_evolver_status", fake_status)
+
+    agent = LottoAgent()
+    await agent.sync_evolver_activity()
+
+    apply_tasks = db.get_agent_tasks("lotto", task_type="evolver_apply", days=1)
+    assert len(apply_tasks) == 0

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

@@ -14,20 +14,27 @@ services:
       - TZ=${TZ:-Asia/Seoul}
       - LOTTO_ALL_URL=${LOTTO_ALL_URL:-https://smok95.github.io/lotto/results/all.json}
       - LOTTO_LATEST_URL=${LOTTO_LATEST_URL:-https://smok95.github.io/lotto/results/latest.json}
+      - PYTHONPATH=/app:/shared
     volumes:
       - ${RUNTIME_PATH}/data:/app/data
+      - ${RUNTIME_PATH}/_shared:/shared/_shared:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       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,11 +50,19 @@ 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:-}
+      - PYTHONPATH=/app:/shared
     volumes:
       - ${RUNTIME_PATH}/data/stock:/app/data
+      - ${RUNTIME_PATH}/_shared:/shared/_shared:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -61,7 +76,6 @@ services:
     environment:
       - TZ=${TZ:-Asia/Seoul}
       - MUSIC_AI_SERVER_URL=${MUSIC_AI_SERVER_URL:-}
-      - SUNO_API_KEY=${SUNO_API_KEY:-}
       - MUSIC_MEDIA_BASE=${MUSIC_MEDIA_BASE:-/media/music}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
       - PEXELS_API_KEY=${PEXELS_API_KEY:-}
@@ -76,33 +90,107 @@ services:
       - 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}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - INTERNAL_API_KEY=${INTERNAL_API_KEY:-}
+      - MUSIC_RENDER_URL=${MUSIC_RENDER_URL:-http://192.168.45.59:18711}
+      - PYTHONPATH=/app:/shared
     volumes:
       - ${RUNTIME_PATH}/data/music:/app/data
       - ${RUNTIME_PATH:-.}/data/videos:/app/data/videos
+      - ${RUNTIME_PATH}/_shared:/shared/_shared:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+    depends_on:
+      - redis
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
-  blog-lab:
+  video-lab:
     build:
-      context: ./blog-lab
-    container_name: blog-lab
+      context: ./video-lab
+    container_name: video-lab
+    restart: unless-stopped
+    ports:
+      - "18801:8000"
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - INTERNAL_API_KEY=${INTERNAL_API_KEY:-}
+      - VIDEO_DATA_DIR=/app/data
+      - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+    volumes:
+      - ${RUNTIME_PATH}/data/video:/app/data
+    depends_on:
+      - redis
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+
+  image-lab:
+    build: ./image-lab
+    container_name: image-lab
+    restart: unless-stopped
+    ports:
+      - "18802:8000"
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - INTERNAL_API_KEY=${INTERNAL_API_KEY:-}
+      - IMAGE_DATA_DIR=/app/data
+      - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+    volumes:
+      - ${RUNTIME_PATH}/data/image:/app/data
+    depends_on:
+      - redis
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+
+  insta-lab:
+    build:
+      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
+      - INSTA_DEFAULT_THEME=${INSTA_DEFAULT_THEME:-default}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - INTERNAL_API_KEY=${INTERNAL_API_KEY:-}
+      - PYTHONPATH=/app:/shared
     volumes:
-      - ${RUNTIME_PATH}/data/blog:/app/data
+      - ${RUNTIME_PATH}/data/insta:/app/data
+      - ${RUNTIME_PATH}/_shared:/shared/_shared:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+    depends_on:
+      - redis
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -118,11 +206,18 @@ services:
       - DATA_GO_KR_API_KEY=${DATA_GO_KR_API_KEY:-}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
       - AGENT_OFFICE_URL=${AGENT_OFFICE_URL:-http://agent-office:8000}
+      - PYTHONPATH=/app:/shared
     volumes:
       - ${RUNTIME_PATH}/data/realestate:/app/data
+      - ${RUNTIME_PATH}/_shared:/shared/_shared:ro
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -136,9 +231,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:-}
@@ -157,13 +252,61 @@ 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')"]
-      interval: 30s
+      interval: 60s
+      timeout: 5s
+      retries: 3
+
+  tarot-lab:
+    build:
+      context: ./tarot-lab
+    container_name: tarot-lab
+    restart: unless-stopped
+    ports:
+      - "18250:8000"
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - TAROT_MODEL=${TAROT_MODEL:-claude-sonnet-4-6}
+      - TAROT_COST_INPUT_PER_M=${TAROT_COST_INPUT_PER_M:-3.0}
+      - TAROT_COST_OUTPUT_PER_M=${TAROT_COST_OUTPUT_PER_M:-15.0}
+      - TAROT_TIMEOUT_SEC=${TAROT_TIMEOUT_SEC:-180}
+      - TAROT_DATA_PATH=/app/data
+      - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+    volumes:
+      - ${RUNTIME_PATH:-.}/data/tarot:/app/data
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+
+  saju-lab:
+    build:
+      context: ./saju-lab
+    container_name: saju-lab
+    restart: unless-stopped
+    ports:
+      - "18300:8000"
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - SAJU_MODEL=${SAJU_MODEL:-claude-sonnet-4-6}
+      - SAJU_COST_INPUT_PER_M=${SAJU_COST_INPUT_PER_M:-3.0}
+      - SAJU_COST_OUTPUT_PER_M=${SAJU_COST_OUTPUT_PER_M:-15.0}
+      - SAJU_TIMEOUT_SEC=${SAJU_TIMEOUT_SEC:-240}
+      - SAJU_DATA_PATH=/app/data
+      - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-http://localhost:3007,http://localhost:8080}
+    volumes:
+      - ${RUNTIME_PATH:-.}/data/saju:/app/data
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -182,7 +325,7 @@ services:
       - ${RUNTIME_PATH:-.}/data/personal:/app/data
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -209,7 +352,7 @@ services:
       - ${PACK_DATA_PATH:-./data/packs}:${PACK_BASE_DIR:-/app/data/packs}
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -232,18 +375,30 @@ services:
       - ${RUNTIME_PATH}/travel-thumbs:/data/thumbs:rw
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
   frontend:
-    image: nginx:alpine
+    # ngx_http_rewrite_module 힙 오버플로우 2건 대응 (미고정 nginx:alpine → 패치 stable 고정)
+    #  - CVE-2026-42945 (NGINX Rift, CVSS 9.2): fixed in 1.30.1+ / 1.31.0+
+    #  - CVE-2026-9256  (nginx-poolslip, 영향 ~1.31.0): fixed in 1.30.2+ / 1.31.1+
+    # → 둘 다 커버하는 최소 stable = 1.30.2
+    image: nginx:1.30.2-alpine
     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
+      - video-lab
+      - image-lab
     ports:
       - "8080:80"
     volumes:
@@ -253,11 +408,13 @@ services:
       - ${RUNTIME_PATH}/travel-thumbs:/data/thumbs:ro
       - ${RUNTIME_PATH}/data/music:/data/music:ro
       - ${RUNTIME_PATH}/data/videos:/data/videos:ro
+      - ${RUNTIME_PATH}/data/video:/data/video:ro
+      - ${RUNTIME_PATH}/data/insta/insta_cards:/data/insta_cards:ro
     extra_hosts:
       - "host.docker.internal:host-gateway"
     healthcheck:
       test: ["CMD", "wget", "-q", "--spider", "http://localhost:80/"]
-      interval: 30s
+      interval: 60s
       timeout: 5s
       retries: 3
 
@@ -277,3 +434,18 @@ services:
       - ${RUNTIME_PATH}:/runtime:rw
       - ${RUNTIME_PATH}/scripts:/scripts:ro
       - /var/run/docker.sock:/var/run/docker.sock
+
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    volumes:
+      - ${RUNTIME_PATH}/redis-data:/data
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 60s
+      timeout: 5s
+      retries: 3

docs/superpowers/plans/2026-05-18-plan-b-base-redis-wsl2.md

@@ -0,0 +1,635 @@
+# Plan-B-Base — NAS Redis 컨테이너 + Windows WSL2/Docker/Tailscale/SMB 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:** 분산 아키텍처 base 인프라 셋업 — NAS에 24/7 Redis 컨테이너 신설 + Windows AI 머신에 WSL2 + Docker Engine + Tailscale + NAS SMB 마운트 구성. 후속 Plan-B-Insta/Music/Video/Infra 트랙의 prerequisite.
+
+**Architecture:** SP-1 (NAS Redis) = docker-compose service 추가 + deployer auto-rebuild. SP-2 (Windows) = 박재오 머신 192.168.45.59에서 직접 셋업 (WSL2 Ubuntu 22.04 + Docker Engine + Tailscale + cifs-utils로 NAS SMB 마운트). 두 SP가 모두 끝나야 후속 트랙의 worker가 NAS ↔ Windows 양방향 통신 가능.
+
+**Tech Stack:** Redis 7-alpine, WSL2, Ubuntu 22.04, Docker Engine 24+, Tailscale, cifs-utils (SMB 3.0). PowerShell (관리자) + bash (WSL2 내부).
+
+**Spec:** `web-backend/docs/superpowers/specs/2026-05-18-nas-windows-distributed-architecture-design.md` §4 SP-1·SP-2, §10 SP-1·SP-2 상세
+
+---
+
+## 사전 확인 사항
+
+- **박재오 자격증명 필요**: NAS SMB 마운트용 user/password (Synology DSM 사용자, SMB 권한 보유)
+- **Windows AI 머신 직접 접근 필요**: WSL2 설치는 관리자 PowerShell + 재부팅 1회. Claude는 별도 머신이라 명령 직접 실행 불가 — **Task 4~7은 박재오가 콘솔에서 직접 수행**. 명령어와 검증 방법 명시.
+- **NAS deployer 사용자**: Gitea webhook으로 docker compose up -d 자동 실행. 새 redis 서비스도 추가 시 자동 startup.
+
+## File Structure
+
+### SP-1 — NAS 측 (Modify)
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-backend/docker-compose.yml` | `redis:` 서비스 블록 추가 | 컨테이너 정의 (image, volume, healthcheck) |
+
+### SP-2 — Windows 측 (Create, 박재오 머신 로컬)
+
+| 파일/위치 | 변경 | 책임 |
+|----------|------|------|
+| (Windows AI) WSL2 Ubuntu-22.04 | install | Linux 런타임 |
+| WSL2 `/etc/apt/keyrings/docker.gpg` | install | Docker Engine apt key |
+| WSL2 `/etc/apt/sources.list.d/docker.list` | install | Docker Engine apt source |
+| (Windows AI) Tailscale | install + auth | 사설망 100.x.x.x |
+| WSL2 `/etc/nas-smb-credentials` (신규) | NAS user/password | SMB 자격증명 (chmod 600) |
+| WSL2 `/etc/fstab` (수정) | SMB 마운트 항목 추가 | 부팅 시 자동 마운트 |
+| WSL2 `/mnt/nas` | mkdir | 마운트 포인트 |
+
+---
+
+## Task 1: NAS docker-compose.yml에 redis 서비스 추가
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/docker-compose.yml`
+
+- [ ] **Step 1: 현재 docker-compose.yml 끝부분 확인 (deployer 위치)**
+
+Run: `tail -20 C:/Users/jaeoh/Desktop/workspace/web-backend/docker-compose.yml`
+Expected: `deployer` 서비스가 마지막. line ~277-293 영역.
+
+- [ ] **Step 2: redis 서비스 블록 추가**
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/docker-compose.yml` 파일 **끝**에 (deployer 서비스 다음, volumes 블록 있다면 그 전에) 다음 블록 추가. 들여쓰기는 다른 서비스(`lotto:`, `stock:` 등)와 동일하게 services 아래 2칸 들여쓰기:
+
+```yaml
+
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    volumes:
+      - ${RUNTIME_PATH}/redis-data:/data
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+    networks:
+      - default
+```
+
+**주의:**
+- 파일 끝에 추가하되, 만약 `networks:` / `volumes:` top-level 블록이 services 다음에 있다면 그 블록들 **앞에** 삽입
+- 첫 줄에 빈 줄 1개 두기 (deployer와 분리)
+- `${RUNTIME_PATH}` 환경변수는 다른 서비스에서도 사용 중. 자동 적용됨
+
+- [ ] **Step 3: yaml 문법 검증**
+
+Run:
+```bash
+python -c "import yaml; yaml.safe_load(open('C:/Users/jaeoh/Desktop/workspace/web-backend/docker-compose.yml'))" && echo "yaml OK"
+```
+Expected: `yaml OK`
+
+만약 실패하면 indent 또는 trailing space 확인.
+
+- [ ] **Step 4: redis 서비스가 services dict에 들어갔는지 확인**
+
+Run:
+```bash
+python -c "import yaml; d=yaml.safe_load(open('C:/Users/jaeoh/Desktop/workspace/web-backend/docker-compose.yml')); print(sorted(d['services'].keys()))"
+```
+Expected: 리스트에 `'redis'` 포함. 다른 서비스(`lotto`, `stock`, `music-lab`, `insta-lab`, `realestate-lab`, `agent-office`, `personal`, `packs-lab`, `travel-proxy`, `frontend`, `deployer`)도 모두 그대로.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git add docker-compose.yml
+git commit -m "$(cat <<'EOF'
+feat(infra): add redis container as 24/7 queue + cache base (SP-1)
+
+redis:7-alpine, 256MB maxmemory, AOF appendonly ON, allkeys-lru.
+docker volume ${RUNTIME_PATH}/redis-data로 영속화.
+Plan-B 후속 트랙(insta-render/music-render/video-render Windows
+워커)의 BLPOP 큐 + NAS↔Windows pub/sub의 base.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+- [ ] **Step 6: push (Gitea webhook → NAS deployer 자동 적용)**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git push origin main
+```
+
+자격증명 prompt 시 입력. 1회 실패 시 1회 재시도 패턴.
+
+Expected: push 성공. NAS deployer가 webhook 수신 → `git pull` → `docker compose up -d redis` 자동 실행.
+
+---
+
+## Task 2: NAS Redis 컨테이너 헬스 확인
+
+**Files:** 없음 (NAS 검증)
+
+- [ ] **Step 1: deployer 완료까지 대기 (통상 30초~2분)**
+
+Run (Windows 로컬에서):
+```bash
+for i in 1 2 3 4 5 6 7 8 9 10; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" https://gahusb.synology.me/api/stock/news -m 5)
+  echo "[try $i] HTTP $code"
+  if [ "$code" = "200" ]; then break; fi
+  sleep 15
+done
+```
+
+Expected: HTTP 200 응답 — NAS 컨테이너 안정 상태. redis 컨테이너는 별도 endpoint 없으나 deployer가 build 완료했음을 시사.
+
+- [ ] **Step 2: NAS에서 redis 컨테이너 확인 (박재오 SSH)**
+
+NAS bash:
+```bash
+ssh -p 22 박재오@gahusb.synology.me
+cd /volume1/docker/webpage
+docker compose ps redis
+```
+
+또는 한 번에:
+```bash
+ssh -p 22 박재오@gahusb.synology.me "cd /volume1/docker/webpage && docker compose ps redis && docker exec redis redis-cli PING"
+```
+
+Expected:
+- `docker compose ps redis` → `redis ... healthy` 또는 `Up X seconds (health: starting)` 후 곧 healthy
+- `redis-cli PING` → `PONG`
+
+만약 `docker compose ps`에 redis가 안 보이면:
+```bash
+cd /volume1/docker/webpage && docker compose up -d redis
+```
+
+수동 실행해서 startup 확인.
+
+- [ ] **Step 3: redis-data 볼륨 생성 확인 (Z: drive로)**
+
+Run (Windows):
+```powershell
+Test-Path "Z:\webpage\redis-data"
+```
+
+또는 NAS bash:
+```bash
+ls -la /volume1/docker/webpage/redis-data/
+```
+
+Expected: 디렉토리 존재. 그 안에 `appendonlydir/` 또는 `dump.rdb` 등의 redis 데이터 파일.
+
+- [ ] **Step 4: AOF append-only 작동 확인 (선택, 데이터 영속성 검증)**
+
+```bash
+ssh -p 22 박재오@gahusb.synology.me 'docker exec redis redis-cli SET test_key "hello"'
+ssh -p 22 박재오@gahusb.synology.me 'docker exec redis redis-cli RESTART'  # 또는 docker restart
+# 잠시 대기
+ssh -p 22 박재오@gahusb.synology.me 'docker exec redis redis-cli GET test_key'
+```
+
+Expected: `"hello"` — 재시작 후에도 값 유지 (AOF 영속화 작동).
+
+테스트 후 정리: `docker exec redis redis-cli DEL test_key`
+
+---
+
+## Task 3: Windows AI에 WSL2 + Ubuntu 22.04 설치
+
+**Files:** 없음 (Windows AI 머신 192.168.45.59에서 박재오 직접 실행)
+
+**전제:** Windows 10 build 19041+ 또는 Windows 11. 박재오 9800X3D 머신 충족.
+
+- [ ] **Step 1: 관리자 PowerShell 실행**
+
+박재오 Windows AI 머신에서 시작 메뉴 → "PowerShell" 우클릭 → "관리자 권한으로 실행".
+
+- [ ] **Step 2: WSL2 + Ubuntu 22.04 설치**
+
+```powershell
+wsl --install -d Ubuntu-22.04
+```
+
+Expected: 다운로드 progress + "Ubuntu-22.04 has been installed". **재부팅 필요할 수 있음.**
+
+- [ ] **Step 3: 재부팅 (필요 시)**
+
+설치 완료 메시지에 "재시작이 필요합니다"가 보이면 재부팅. 자동 재부팅 안 됨.
+
+- [ ] **Step 4: Ubuntu 초기 설정 (재부팅 후 자동 실행 또는 시작 메뉴에서 "Ubuntu" 클릭)**
+
+새 콘솔이 열리고 다음 입력 요청됨:
+- 새 UNIX username: `jaeoh` 또는 박재오 선호 username (이후 모든 sudo에 사용)
+- 비밀번호: 박재오가 정하는 값. 잘 기억할 것.
+
+Expected: `jaeoh@<hostname>:~$` 프롬프트 표시 → WSL2 진입 성공.
+
+- [ ] **Step 5: WSL 버전 확인**
+
+WSL2 내부에서 PowerShell로 잠시 돌아와서:
+```powershell
+wsl -l -v
+```
+
+Expected:
+```
+  NAME            STATE           VERSION
+* Ubuntu-22.04    Running         2
+```
+
+VERSION=2 확인. 만약 1이면:
+```powershell
+wsl --set-version Ubuntu-22.04 2
+```
+
+- [ ] **Step 6: WSL2 안 진입 (이후 작업)**
+
+```powershell
+wsl -d Ubuntu-22.04
+```
+
+이후 Task 4~7은 모두 WSL2 안 bash에서 실행.
+
+---
+
+## Task 4: WSL2 안 Docker Engine 설치 (Docker Desktop 사용 X)
+
+**Files:** (WSL2 내부) `/etc/apt/keyrings/docker.gpg`, `/etc/apt/sources.list.d/docker.list`
+
+**위치:** WSL2 Ubuntu-22.04 bash 프롬프트.
+
+- [ ] **Step 1: 패키지 인덱스 + 기본 의존성 설치**
+
+```bash
+sudo apt update
+sudo apt install -y ca-certificates curl gnupg lsb-release
+```
+
+Expected: 에러 없이 완료.
+
+- [ ] **Step 2: Docker apt key 등록**
+
+```bash
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+```
+
+Expected: 에러 없이 완료. `/etc/apt/keyrings/docker.gpg` 파일 생성.
+
+- [ ] **Step 3: Docker repository 추가**
+
+```bash
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
+  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+sudo apt update
+```
+
+Expected: `Hit:N https://download.docker.com/linux/ubuntu jammy InRelease` 라인 보임.
+
+- [ ] **Step 4: Docker Engine + Compose 설치**
+
+```bash
+sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+Expected: 설치 완료. 용량 ~400MB.
+
+- [ ] **Step 5: 현재 사용자를 docker 그룹에 추가**
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+Expected: 출력 없음 (정상). **새 셸 열어야 적용됨.**
+
+- [ ] **Step 6: Docker 서비스 시작 + 자동 시작 설정**
+
+```bash
+sudo systemctl enable docker
+sudo systemctl start docker
+sudo systemctl status docker | head -5
+```
+
+Expected: `Active: active (running)`.
+
+만약 `systemctl: command not found` 또는 systemd 미지원 시:
+```bash
+sudo service docker start
+```
+
+WSL2 systemd 활성화는 `/etc/wsl.conf`에 `[boot]\nsystemd=true` 추가 후 PowerShell에서 `wsl --shutdown` 후 재진입. (Ubuntu-22.04는 보통 기본 활성)
+
+- [ ] **Step 7: docker 명령 동작 확인**
+
+새 셸로 (PowerShell에서 다시 `wsl -d Ubuntu-22.04` 또는 현재 셸 종료 후 재진입):
+
+```bash
+docker version
+docker run --rm hello-world
+```
+
+Expected:
+- `docker version`: Client + Server 둘 다 표시 (Server에 Engine version)
+- `hello-world`: "Hello from Docker!" 출력
+
+---
+
+## Task 5: WSL2 안 Tailscale 설치 + 가입
+
+**Files:** Tailscale은 systemd service 등록 (별도 path 신경 안 써도 됨)
+
+- [ ] **Step 1: Tailscale 설치**
+
+WSL2 bash:
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+```
+
+Expected: 패키지 install 후 "Installation complete!" 출력.
+
+- [ ] **Step 2: Tailscale 가입 (브라우저 OAuth)**
+
+```bash
+sudo tailscale up
+```
+
+Expected: `To authenticate, visit: https://login.tailscale.com/a/...` URL 표시.
+
+브라우저에서 그 URL 열기 → Google/Microsoft/GitHub 등으로 로그인 → 박재오 Tailscale 네트워크에 가입 (기존 계정 없으면 생성).
+
+- [ ] **Step 3: 가입 완료 확인**
+
+```bash
+tailscale status
+```
+
+Expected:
+- 첫 줄에 Windows AI 머신의 100.x.x.x IP 표시
+- (이미 가입된) NAS도 같은 네트워크에 있다면 NAS의 100.x.x.x IP도 표시
+
+- [ ] **Step 4: NAS와 Tailscale ping (양방향 사설망 확인)**
+
+NAS의 Tailscale IP를 `tailscale status` 출력에서 찾아 (예: `100.64.0.10`):
+```bash
+tailscale ping 100.64.0.10
+```
+
+Expected: `pong from <NAS hostname>` (직접 LAN 또는 DERP 중계). 만약 NAS가 Tailscale 미가입이면 별도로 NAS DSM Tailscale 패키지 셋업 필요 — 이는 박재오 결정 사항이라 plan 외.
+
+> **참고:** Tailscale은 spec §3 sense의 사설망 layer 보조. LAN(192.168.45.0/24) 안에서만 작업한다면 Tailscale 없이도 작동. 외부 출장 등에서 NAS↔Windows 통신을 위해 권장.
+
+---
+
+## Task 6: WSL2 안 NAS SMB 자격증명 파일 + 마운트 포인트 준비
+
+**Files:** `/etc/nas-smb-credentials`, `/mnt/nas`
+
+- [ ] **Step 1: cifs-utils 설치 (SMB 마운트 패키지)**
+
+```bash
+sudo apt install -y cifs-utils
+```
+
+Expected: 설치 완료.
+
+- [ ] **Step 2: SMB 자격증명 파일 생성**
+
+박재오 NAS 계정의 username과 password를 사용. 파일 위치는 system-wide `/etc/`.
+
+```bash
+sudo bash -c 'cat > /etc/nas-smb-credentials <<EOF
+username=박재오NAS사용자명
+password=박재오NAS비밀번호
+domain=
+EOF'
+```
+
+**위 명령 실행 전 `박재오NAS사용자명` / `박재오NAS비밀번호`를 실제 값으로 교체.** Synology DSM Control Panel → User & Group 에서 SMB 접근 권한 있는 계정 사용. 비밀번호에 특수문자 있을 시 escape 필요 (특히 `!`, `$`, `\`).
+
+- [ ] **Step 3: 자격증명 파일 권한 보호**
+
+```bash
+sudo chmod 600 /etc/nas-smb-credentials
+sudo chown root:root /etc/nas-smb-credentials
+```
+
+Expected: 출력 없음.
+
+```bash
+ls -la /etc/nas-smb-credentials
+```
+
+Expected: `-rw------- 1 root root ... /etc/nas-smb-credentials`
+
+- [ ] **Step 4: 마운트 포인트 생성**
+
+```bash
+sudo mkdir -p /mnt/nas
+```
+
+---
+
+## Task 7: NAS SMB 마운트 (수동 마운트 + fstab 자동화)
+
+**Files:** `/etc/fstab` (수정)
+
+- [ ] **Step 1: 수동 마운트 시도 (자격증명·경로 검증)**
+
+```bash
+sudo mount -t cifs //gahusb.synology.me/docker /mnt/nas \
+  -o credentials=/etc/nas-smb-credentials,vers=3.0,uid=1000,gid=1000,_netdev
+```
+
+Expected: 출력 없음 (성공). 만약 `mount error(13)` (permission) → 자격증명 오류. `mount error(2)` (no such file) → share name `docker` 확인.
+
+> **share name 변형:** 박재오 NAS는 메모리(`feedback_nas_deploy_paths.md`)에 따르면 SMB 매핑이 `/volume1/docker/`를 share `docker`로 노출. 만약 다른 share name(예: `webpage`)이라면 그것으로 교체.
+
+- [ ] **Step 2: 마운트 결과 확인**
+
+```bash
+ls /mnt/nas/
+```
+
+Expected: `webpage/` 디렉토리 + 다른 share 내 디렉토리 보임.
+
+```bash
+ls /mnt/nas/webpage/data/
+```
+
+Expected: `insta/`, `music/` 등 후속 트랙에서 사용할 디렉토리. 없으면 후속 트랙에서 생성됨.
+
+- [ ] **Step 3: 마운트 해제 후 fstab으로 자동화**
+
+```bash
+sudo umount /mnt/nas
+```
+
+Expected: 출력 없음.
+
+`/etc/fstab` 끝에 다음 라인 추가:
+```bash
+sudo bash -c 'cat >> /etc/fstab <<EOF
+
+# NAS Synology SMB mount for web-ai-services workers (2026-05-18)
+//gahusb.synology.me/docker /mnt/nas cifs credentials=/etc/nas-smb-credentials,vers=3.0,uid=1000,gid=1000,_netdev,nofail 0 0
+EOF'
+```
+
+`nofail` 옵션은 부팅 시 NAS 미접속이어도 boot 진행 (production 안전).
+
+- [ ] **Step 4: fstab 적용 + 검증**
+
+```bash
+sudo mount -a
+ls /mnt/nas/webpage/data/ 2>&1 | head -5
+mount | grep cifs
+```
+
+Expected:
+- `mount -a` 출력 없음 (성공)
+- `ls /mnt/nas/webpage/data/` 디렉토리 내용 표시
+- `mount | grep cifs` 라인에 마운트 정보 보임
+
+- [ ] **Step 5: WSL2 재시작 시 자동 마운트 확인**
+
+PowerShell에서 (관리자 권한 불필요):
+```powershell
+wsl --shutdown
+wsl -d Ubuntu-22.04
+```
+
+WSL2 다시 진입 후:
+```bash
+ls /mnt/nas/webpage/data/
+```
+
+Expected: 정상 디렉토리 목록. 자동 마운트 성공.
+
+만약 마운트 안 됨:
+- `dmesg | grep cifs` 확인
+- `nofail` 때문에 boot은 통과했으나 마운트 실패 가능. 수동 `sudo mount -a` 후 동작 확인 → fstab syntax 재검토
+
+---
+
+## Task 8: 통합 검증 — base 인프라 동작 확인
+
+**Files:** 없음 (검증)
+
+- [ ] **Step 1: NAS Redis 외부 ping (Windows 로컬에서)**
+
+```powershell
+# Windows AI 또는 박재오 PC에서
+Test-NetConnection -ComputerName 192.168.45.54 -Port 6379
+```
+
+Expected: `TcpTestSucceeded : True`
+
+> 외부 6379 노출은 LAN 한정. 가능하면 NAS firewall (DSM Control Panel)에서 6379 LAN-only allowed로 한정 권장. (이번 plan에 포함 안 됨, 별도 사용자 작업)
+
+- [ ] **Step 2: WSL2에서 NAS Redis 접속**
+
+WSL2 bash:
+```bash
+docker run --rm redis:7-alpine redis-cli -h 192.168.45.54 PING
+```
+
+또는 Tailscale 사용 시:
+```bash
+docker run --rm redis:7-alpine redis-cli -h <NAS_TAILSCALE_IP> PING
+```
+
+Expected: `PONG`
+
+- [ ] **Step 3: NAS volume 쓰기 테스트 (Windows→NAS 양방향)**
+
+WSL2 bash:
+```bash
+echo "Plan-B-Base test $(date)" | sudo tee /mnt/nas/webpage/data/.plan-b-test.txt
+cat /mnt/nas/webpage/data/.plan-b-test.txt
+sudo rm /mnt/nas/webpage/data/.plan-b-test.txt
+```
+
+Expected:
+- `tee` 출력에 같은 내용 + 파일 생성됨
+- `cat` 으로 확인 성공
+- 파일 삭제 성공
+
+`sudo` 필요 시 chmod로 uid 1000 쓰기 권한 확인. 또는 mount option `uid=1000,gid=1000` 적용 후 일반 사용자도 쓰기 가능. 만약 안 되면 NAS DSM에서 SMB user의 write 권한 확인.
+
+- [ ] **Step 4: WSL2 Docker로 hello-world 한 번 더 (재진입 후 상태 확인)**
+
+```bash
+docker run --rm hello-world
+```
+
+Expected: "Hello from Docker!"
+
+- [ ] **Step 5: 모든 검증 완료 후 보고 — 후속 트랙으로 진입 가능 상태**
+
+다음 plan(Plan-B-Insta 등)이 가정하는 상태:
+- ✅ NAS `redis:6379` PING/PONG 성공
+- ✅ Windows WSL2 Ubuntu-22.04 작동 + Docker Engine 실행
+- ✅ `/mnt/nas/webpage/data/` 양방향 read·write 성공
+- ✅ Tailscale 가입 (선택, 외부 출장 시 필요)
+
+---
+
+## Self-Review
+
+### Spec 커버리지
+
+| Spec 요구사항 | 구현 Task |
+|---------------|-----------|
+| §4 SP-1: NAS Redis 컨테이너 | Task 1 (compose 추가) + Task 2 (헬스 검증) |
+| §10 SP-1: redis:7-alpine + 256MB + AOF + healthcheck | Task 1 Step 2 |
+| §4 SP-2: Windows WSL2 + Docker Engine | Task 3 (WSL2) + Task 4 (Docker) |
+| §10 SP-2: Tailscale | Task 5 |
+| §10 SP-2: NAS SMB mount `/mnt/nas` | Task 6 (자격증명·포인트) + Task 7 (마운트+fstab) |
+| §10 SP-2: 검증 (docker ps, tailscale status, ls /mnt/nas) | Task 8 |
+| §6 Redis 키 컨벤션 사용 가능 | Task 2 Step 2 (PING) — 컨벤션 자체는 후속 트랙에서 RPUSH로 시작 |
+
+### Placeholder 스캔
+
+- TBD/TODO 없음 ✓
+- 모든 명령어가 그대로 실행 가능한 형태 ✓
+- 한 가지 예외: Task 6 Step 2 — `박재오NAS사용자명/박재오NAS비밀번호`는 사용자 자격증명이라 placeholder가 의도된 것. 실행 전 교체 명시 ✓
+- Task 5 Step 4 — `<NAS 의 Tailscale IP>`는 `tailscale status` 출력에서 박재오가 보고 입력. 사용자 환경에서만 결정 가능, plan에 명시 ✓
+
+### Type/이름 consistency
+
+- `redis` 서비스명 (Task 1, 2, 8 모두 동일) ✓
+- `/mnt/nas` 마운트 포인트 (Task 6, 7, 8 모두 동일) ✓
+- `/etc/nas-smb-credentials` 자격증명 파일 (Task 6, 7 동일) ✓
+- share name `docker` (Task 7 Step 1, fstab 동일) ✓
+- Ubuntu-22.04 (Task 3, 4 동일) ✓
+
+### 위험·주의
+
+| 위험 | 완화 |
+|------|------|
+| Windows 재부팅 시 WSL2 자동 시작 안 함 | 향후 Plan-B-Infra(SP-9)에서 NSSM으로 자동 시작 |
+| WSL2 systemd 미지원 시 docker service 자동 시작 안 함 | Task 4 Step 6의 fallback `sudo service docker start` 또는 `/etc/wsl.conf` 수정 |
+| SMB 마운트 자격증명 노출 | `/etc/nas-smb-credentials` chmod 600 + root:root |
+| NAS firewall에서 6379 외부 노출 | 권장: LAN(192.168.45.0/24) only allow. 본 plan 외 (DSM 수동) |
+| Tailscale 미가입 시 NAS↔Windows 외부 통신 불가 | LAN 내에선 작동. 외부 출장 시 필요할 때만 가입 |
+| /mnt/nas 쓰기 권한 부족 | uid=1000 mount option + NAS DSM에서 SMB user의 share write 권한 확인 |
+
+---
+
+## 완료 후 다음 단계
+
+Plan-B-Base 완료 후 spec §14 권장 순서대로:
+
+1. **Plan-B-Insta** — SP-3 (insta-render Windows worker) + SP-4 (NAS insta-lab 분할)
+2. **Plan-B-Music** — SP-5 + SP-6
+3. **Plan-B-Video** — SP-7 + SP-8
+4. **Plan-B-Infra** — SP-9 (NSSM 자동 시작) + SP-10 (task-watcher)
+
+각 후속 plan은 본 plan이 제공한 base 인프라(Redis + WSL2/Docker + /mnt/nas)에 의존.

docs/superpowers/plans/2026-05-18-track-a-cache-hardening.md

@@ -0,0 +1,656 @@
+# Track A — NAS↔Windows API 부하 캐시 강화 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:** web-ai → NAS stock 호출량을 분당 12회 → 분당 3~4회로 축소하여, V2 재시작 시점부터 즉시 NAS CPU 부담 70% 감소.
+
+**Architecture:** 2-layer cache. (1) web-ai client side: 3개 endpoint TTL 60/300/60 → 180/600/300으로 증가. (2) NAS stock server side: 동일 endpoint에 in-memory TTLCache 추가하여 web-ai 캐시 miss 시에도 KIS·LLM 재호출 차단. 두 layer가 cumulative하게 작동.
+
+**Tech Stack:** Python 3.12 / FastAPI / pytest / `cachetools.TTLCache`. **two repos**: `web-ai` (signal_v2/) + `web-backend` (stock/).
+
+**Spec:** `web-backend/docs/superpowers/specs/2026-05-18-nas-windows-distributed-architecture-design.md` §4 SP-A1·A2, §10 상세
+
+---
+
+## File Structure
+
+### SP-A1 — web-ai 캐시 TTL (Modify)
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-ai/signal_v2/stock_client.py:13-17` | `_TTL` dict 3개 값 변경 | endpoint별 client-side cache TTL |
+| `web-ai/signal_v2/tests/test_stock_client_ttl.py` (Create) | TTL 값 회귀 테스트 | 미래 변경 시 의도하지 않은 회귀 방지 |
+
+### SP-A2 — NAS stock TTLCache (Modify + Create)
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-backend/stock/requirements.txt` | `cachetools>=5.3` 추가 | 의존성 |
+| `web-backend/stock/app/webai_cache.py` (Create) | 3개 TTLCache + helper 함수 | server-side cache 중앙화 |
+| `web-backend/stock/app/main.py:419-422` | `get_webai_portfolio()` cache 적용 | NAS portfolio 캐시 |
+| `web-backend/stock/app/main.py:467-470` | `get_webai_news_sentiment(date)` cache 적용 | date별 캐시 |
+| `web-backend/stock/app/screener/router.py:173` | `post_run()` cache 적용 (mode=preview만) | screener preview 캐시 |
+| `web-backend/stock/app/test_webai_cache.py` (Create) | cache 동작 + TTL + key 분기 | 캐시 hit/miss 검증 |
+
+---
+
+## Task 1: web-ai SP-A1 — `_TTL` dict 회귀 테스트 작성
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/signal_v2/tests/test_stock_client_ttl.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+```python
+# tests/test_stock_client_ttl.py
+"""SP-A1 회귀 — _TTL이 NAS 부담 완화를 위한 값으로 설정되어 있어야 함."""
+from signal_v2.stock_client import _TTL
+
+
+def test_portfolio_ttl_is_180s():
+    """portfolio TTL은 180초 이상 (3분 폴링에서 1회 fetch가 3 폴링 커버)."""
+    assert _TTL["portfolio"] >= 180.0
+
+
+def test_news_sentiment_ttl_is_600s():
+    """news-sentiment TTL은 600초 이상 (10분, 뉴스 sentiment는 자주 안 바뀜)."""
+    assert _TTL["news-sentiment"] >= 600.0
+
+
+def test_screener_preview_ttl_is_300s():
+    """screener-preview TTL은 300초 이상 (5분, Top-20은 분 단위로 거의 안 바뀜)."""
+    assert _TTL["screener-preview"] >= 300.0
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai && python -m pytest signal_v2/tests/test_stock_client_ttl.py -v`
+Expected: FAIL — 현재 _TTL 값은 60/300/60. portfolio·screener-preview 모두 < 180/300.
+
+- [ ] **Step 3: `_TTL` 값 변경**
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/signal_v2/stock_client.py` line 13-17:
+
+변경 전:
+```python
+_TTL = {
+    "portfolio": 60.0,
+    "news-sentiment": 300.0,
+    "screener-preview": 60.0,
+}
+```
+
+변경 후:
+```python
+# Cache TTL by endpoint (seconds).
+# 2026-05-18 — NAS 인바운드 호출 부담 완화 (Plan-A SP-A1).
+_TTL = {
+    "portfolio": 180.0,        # 3분 (1분 폴링 시 3 폴링당 1회 실제 fetch)
+    "news-sentiment": 600.0,   # 10분 (뉴스 sentiment는 자주 안 바뀜)
+    "screener-preview": 300.0, # 5분 (Top-20은 분 단위로 거의 안 바뀜)
+}
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai && python -m pytest signal_v2/tests/test_stock_client_ttl.py -v`
+Expected: PASS — 3개 모두 통과.
+
+- [ ] **Step 5: 전체 회귀 확인 (기존 56 tests + 신규 3 tests)**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai && python -m pytest signal_v2/tests/ -v 2>&1 | tail -5`
+Expected: 59 tests 모두 PASS (기존 56 + 신규 3).
+
+- [ ] **Step 6: 커밋**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add signal_v2/stock_client.py signal_v2/tests/test_stock_client_ttl.py
+git commit -m "$(cat <<'EOF'
+perf(signal_v2): raise stock_client TTL for NAS load relief (SP-A1)
+
+portfolio  60s → 180s (3분 폴링 → 3회당 1회 fetch)
+news-sent 300s → 600s (sentiment는 자주 안 바뀜)
+screener   60s → 300s (Top-20 분 단위 변화 미미)
+
+V2 재시작 시점부터 NAS stock에 대한 인바운드 호출이
+분당 12 → 분당 3~4 로 감소 예상. 캐시 hit ratio 0~50% → 66~80%.
+회귀 테스트 3건 추가로 미래 의도치 않은 TTL 변경 차단.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 2: NAS SP-A2 — `cachetools` 의존성 추가
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/requirements.txt`
+
+- [ ] **Step 1: 현재 requirements.txt 확인**
+
+Run: `cat C:/Users/jaeoh/Desktop/workspace/web-backend/stock/requirements.txt`
+파일 끝 확인 — 마지막 줄 newline 여부 확인 (sed/append 안전).
+
+- [ ] **Step 2: cachetools 추가**
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/stock/requirements.txt` 끝에 한 줄 추가:
+
+```
+cachetools>=5.3
+```
+
+(파일 마지막에 newline 없으면 newline 먼저, 그 다음 cachetools 줄.)
+
+- [ ] **Step 3: 로컬 import 가능 여부 확인 (선택, NAS rebuild가 정본)**
+
+Run (Windows 로컬에서 docker 외부 검증용, 선택):
+```bash
+python -c "import cachetools; print(cachetools.__version__)" 2>&1
+```
+
+로컬 미설치라면 skip — NAS deployer가 rebuild 시 install. 이 plan은 코드 정합성만 보장.
+
+- [ ] **Step 4: 커밋 (단독 커밋, deps만)**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git add stock/requirements.txt
+git commit -m "$(cat <<'EOF'
+chore(stock): add cachetools for server-side TTLCache (SP-A2 prep)
+
+다음 커밋에서 /api/webai/portfolio·news-sentiment·screener/run에
+in-memory TTLCache 적용 예정.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: NAS SP-A2 — `webai_cache.py` 모듈 + 단위 테스트
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/webai_cache.py`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/test_webai_cache.py`
+
+- [ ] **Step 1: 실패하는 테스트 작성**
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/test_webai_cache.py`:
+
+```python
+"""SP-A2 — webai_cache module의 cache hit/miss + key 분기 검증."""
+import time
+import pytest
+from app.webai_cache import (
+    PORTFOLIO_CACHE, NEWS_CACHE, SCREENER_CACHE,
+    cache_get_portfolio, cache_set_portfolio,
+    cache_get_news, cache_set_news,
+    cache_get_screener, cache_set_screener,
+    _screener_key,
+)
+
+
+def _clear_all():
+    PORTFOLIO_CACHE.clear()
+    NEWS_CACHE.clear()
+    SCREENER_CACHE.clear()
+
+
+def test_portfolio_cache_miss_then_hit():
+    _clear_all()
+    assert cache_get_portfolio() is None
+    cache_set_portfolio({"holdings": [], "cash": 0})
+    assert cache_get_portfolio() == {"holdings": [], "cash": 0}
+
+
+def test_news_cache_key_by_date():
+    """date가 다르면 별도 캐시 슬롯."""
+    _clear_all()
+    cache_set_news("2026-05-18", {"count": 5})
+    cache_set_news("2026-05-17", {"count": 3})
+    assert cache_get_news("2026-05-18") == {"count": 5}
+    assert cache_get_news("2026-05-17") == {"count": 3}
+    assert cache_get_news("2026-05-16") is None  # not cached
+
+
+def test_news_cache_latest_key_normalized():
+    """date=None은 'latest' 키로 정규화되어 동일 슬롯."""
+    _clear_all()
+    cache_set_news(None, {"count": 9})
+    assert cache_get_news(None) == {"count": 9}
+
+
+def test_screener_key_includes_mode_and_top_n():
+    """screener key는 mode + top_n + weights hash로 분기."""
+    k_preview = _screener_key("preview", 20, None)
+    k_preview_w = _screener_key("preview", 20, {"news": 0.3})
+    k_auto = _screener_key("auto", 20, None)
+    assert k_preview != k_preview_w
+    assert k_preview != k_auto
+
+
+def test_screener_cache_roundtrip():
+    _clear_all()
+    payload = {"asof": "2026-05-18", "survivors_count": 17}
+    cache_set_screener("preview", 20, None, payload)
+    assert cache_get_screener("preview", 20, None) == payload
+    assert cache_get_screener("preview", 20, {"news": 0.3}) is None
+
+
+def test_ttl_expiry_portfolio():
+    """짧은 ttl로 만료 확인 — 직접 시간 조작 대신 TTLCache 내부 동작 신뢰."""
+    from cachetools import TTLCache
+    short = TTLCache(maxsize=1, ttl=0.1)  # 0.1초
+    short["result"] = "x"
+    assert short.get("result") == "x"
+    time.sleep(0.2)
+    assert short.get("result") is None
+```
+
+- [ ] **Step 2: 테스트 실패 확인**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -m pytest app/test_webai_cache.py -v`
+Expected: FAIL — `app.webai_cache` 모듈 존재 안 함.
+
+- [ ] **Step 3: `webai_cache.py` 작성**
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/webai_cache.py`:
+
+```python
+"""SP-A2 — NAS stock의 /api/webai/* 엔드포인트 in-memory TTLCache.
+
+web-ai 측 캐시(stock_client._TTL)가 miss됐을 때도 NAS에서 같은 데이터를
+KIS·LLM 재호출 없이 즉시 반환하기 위한 2-layer 캐시의 server 측.
+V1+V2가 동시 호출해도 NAS는 1회만 계산.
+
+TTL 정책 (spec §10 SP-A2):
+- portfolio:  120s (web-ai TTL 180s 보다 짧게 — 변경 감지 가능)
+- news:       600s (sentiment는 일 단위)
+- screener:   180s
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Optional
+
+from cachetools import TTLCache
+
+
+PORTFOLIO_CACHE: TTLCache = TTLCache(maxsize=1, ttl=120.0)
+NEWS_CACHE: TTLCache = TTLCache(maxsize=10, ttl=600.0)
+SCREENER_CACHE: TTLCache = TTLCache(maxsize=10, ttl=180.0)
+
+
+# ----- portfolio -----
+
+def cache_get_portfolio() -> Optional[Any]:
+    return PORTFOLIO_CACHE.get("result")
+
+
+def cache_set_portfolio(value: Any) -> None:
+    PORTFOLIO_CACHE["result"] = value
+
+
+# ----- news-sentiment -----
+
+def _news_key(date: Optional[str]) -> str:
+    return date if date else "latest"
+
+
+def cache_get_news(date: Optional[str]) -> Optional[Any]:
+    return NEWS_CACHE.get(_news_key(date))
+
+
+def cache_set_news(date: Optional[str], value: Any) -> None:
+    NEWS_CACHE[_news_key(date)] = value
+
+
+# ----- screener -----
+
+def _screener_key(mode: str, top_n: int, weights: Optional[dict]) -> str:
+    """mode + top_n + weights canonical hash. weights 객체 동등성을 키로."""
+    if weights is None:
+        w_repr = "none"
+    else:
+        # canonical: sorted keys → md5 hex (긴 weights도 짧은 키로)
+        canon = json.dumps(weights, sort_keys=True, ensure_ascii=False)
+        w_repr = hashlib.md5(canon.encode("utf-8")).hexdigest()[:12]
+    return f"{mode}:{top_n}:{w_repr}"
+
+
+def cache_get_screener(mode: str, top_n: int, weights: Optional[dict]) -> Optional[Any]:
+    return SCREENER_CACHE.get(_screener_key(mode, top_n, weights))
+
+
+def cache_set_screener(mode: str, top_n: int, weights: Optional[dict], value: Any) -> None:
+    SCREENER_CACHE[_screener_key(mode, top_n, weights)] = value
+```
+
+- [ ] **Step 4: 테스트 통과 확인**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -m pytest app/test_webai_cache.py -v`
+Expected: PASS — 6개 모두 통과.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git add stock/app/webai_cache.py stock/app/test_webai_cache.py
+git commit -m "$(cat <<'EOF'
+feat(stock): webai_cache module (TTLCache for SP-A2)
+
+3개의 TTLCache (portfolio 120s · news 600s · screener 180s) +
+헬퍼 함수. screener key는 mode + top_n + weights canonical hash로
+분기. 다음 커밋에서 /api/webai/portfolio·news-sentiment·screener/run
+3 endpoint에 적용.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: NAS SP-A2 — `/api/webai/portfolio` 캐시 적용
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/main.py:419-422`
+
+- [ ] **Step 1: 현재 endpoint 코드 확인**
+
+`web-backend/stock/app/main.py` 419-422 line은 spec §10 SP-A2와 일치:
+```python
+@app.get("/api/webai/portfolio", dependencies=[Depends(verify_webai_key)])
+def get_webai_portfolio():
+    """web-ai 전용 portfolio (인증 필수, pnl_pct 비율 필드 추가)."""
+    return _augment_portfolio_with_pnl_pct(get_portfolio())
+```
+
+- [ ] **Step 2: 캐시 적용으로 교체**
+
+`web-backend/stock/app/main.py` 419-422 line을 다음으로 교체:
+
+```python
+@app.get("/api/webai/portfolio", dependencies=[Depends(verify_webai_key)])
+def get_webai_portfolio():
+    """web-ai 전용 portfolio (인증 필수, pnl_pct 비율 필드 추가).
+
+    SP-A2 server-side TTLCache 적용. V1+V2 동시 호출도 NAS에서 1회 계산.
+    """
+    cached = webai_cache.cache_get_portfolio()
+    if cached is not None:
+        return cached
+    result = _augment_portfolio_with_pnl_pct(get_portfolio())
+    webai_cache.cache_set_portfolio(result)
+    return result
+```
+
+- [ ] **Step 3: import 추가 (파일 상단)**
+
+`web-backend/stock/app/main.py` 파일 상단 import 블록 (다른 `from .xxx import` 들과 같은 위치)에 추가:
+
+```python
+from . import webai_cache
+```
+
+- [ ] **Step 4: 빠른 import sanity 체크**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -c "from app import main; print('OK')"` 2>&1 | tail -3
+
+(`cachetools` 미설치 환경에선 ImportError 가능 → 그 경우 `pip install cachetools` 후 재시도. 실제 검증은 NAS rebuild 후.)
+Expected: `OK` 또는 cachetools 누락 메시지 (의도된 상태).
+
+---
+
+## Task 5: NAS SP-A2 — `/api/webai/news-sentiment` 캐시 적용
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/main.py:467-470`
+
+- [ ] **Step 1: 캐시 적용**
+
+`web-backend/stock/app/main.py` 467-470 line을 다음으로 교체:
+
+```python
+@app.get("/api/webai/news-sentiment", dependencies=[Depends(verify_webai_key)])
+def get_webai_news_sentiment(date: str | None = None):
+    """web-ai 전용 news sentiment 일별 dump.
+
+    SP-A2 server-side TTLCache 적용. date 파라미터별로 별도 슬롯.
+    """
+    cached = webai_cache.cache_get_news(date)
+    if cached is not None:
+        return cached
+    result = _fetch_news_sentiment_dump(date)
+    webai_cache.cache_set_news(date, result)
+    return result
+```
+
+- [ ] **Step 2: import sanity 체크**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -c "from app import main; print('OK')" 2>&1 | tail -3`
+Expected: `OK`
+
+---
+
+## Task 6: NAS SP-A2 — `/api/stock/screener/run` 캐시 적용 (preview 모드만)
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/screener/router.py:173-...`
+
+- [ ] **Step 1: 현재 함수 확인 (참고)**
+
+`web-backend/stock/app/screener/router.py:173` 시작 `def post_run(body: schemas.RunRequest):` — 함수 본체는 mode 분기 후 _conn() + KIS 호출 등. 단, `mode == "auto"` 는 휴장일/실 운영 트리거이므로 캐시하지 않음 (매 호출이 다른 의미). `mode == "preview"` 는 frontend·web-ai 폴링용 → 캐시 적용.
+
+- [ ] **Step 2: 함수 진입부에 cache 분기 추가**
+
+`web-backend/stock/app/screener/router.py:173` `@router.post("/run", ...)` 의 `def post_run(...)` 본체 **첫 줄들에** 다음 캐시 분기 추가:
+
+변경 전 (line 173-179 근처):
+```python
+@router.post("/run", response_model=schemas.RunResponse)
+def post_run(body: schemas.RunRequest):
+    from .registry import NODE_REGISTRY as _NR, GATE_REGISTRY as _GR
+    started_at = dt.datetime.utcnow().isoformat()
+    with _conn() as c:
+        asof = _resolve_asof(body.asof, c)
+```
+
+변경 후:
+```python
+@router.post("/run", response_model=schemas.RunResponse)
+def post_run(body: schemas.RunRequest):
+    from .registry import NODE_REGISTRY as _NR, GATE_REGISTRY as _GR
+    # SP-A2 — preview 모드는 web-ai/frontend 폴링이라 캐시 적용.
+    # auto 모드는 실제 운영 트리거(휴장일 게이트 등)라 캐시 미적용.
+    if body.mode == "preview":
+        cached = webai_cache.cache_get_screener(body.mode, body.top_n, body.weights)
+        if cached is not None:
+            return cached
+    started_at = dt.datetime.utcnow().isoformat()
+    with _conn() as c:
+        asof = _resolve_asof(body.asof, c)
+```
+
+- [ ] **Step 3: 함수 끝 부분 — preview 결과를 캐시에 저장**
+
+`post_run`의 반환부 직전에 (preview 모드일 때만) 캐시 저장. `post_run` 함수는 결과를 `schemas.RunResponse(...)` 로 만들어 return하는 구조일 것. 정확한 return 위치 확인 후, return 직전에:
+
+`web-backend/stock/app/screener/router.py` `post_run` 함수의 마지막 return 직전에:
+
+```python
+    # SP-A2 — preview 모드 결과 캐시 저장.
+    if body.mode == "preview":
+        webai_cache.cache_set_screener(body.mode, body.top_n, body.weights, response)
+    return response
+```
+
+(`response` 라는 변수가 없으면, 기존 return 표현식을 `response = ...` 로 binding 후 위 코드 추가.)
+
+> **주의:** post_run의 정확한 return 라인을 먼저 확인. `grep -n "return " app/screener/router.py | head` 로 위치 파악 후 적용.
+
+- [ ] **Step 4: import 추가 (router.py 상단)**
+
+`web-backend/stock/app/screener/router.py` 상단 import 블록에 추가:
+
+```python
+from .. import webai_cache
+```
+
+- [ ] **Step 5: 빠른 import sanity 체크**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -c "from app.screener import router; print('OK')" 2>&1 | tail -3`
+Expected: `OK`
+
+---
+
+## Task 7: 통합 검증 — 기존 테스트 회귀 + SP-A2 신규 테스트
+
+**Files:** (조회만)
+
+- [ ] **Step 1: stock 전체 pytest 실행**
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -m pytest -v 2>&1 | tail -30`
+Expected: 기존 모든 테스트 + SP-A2 신규 6 tests 모두 PASS. **0 failed**.
+
+- [ ] **Step 2: 회귀 발견 시 처리**
+
+회귀가 발견되면:
+- import 누락 → `from . import webai_cache` 또는 `from .. import webai_cache` 위치 재확인
+- screener test가 cache hit으로 fail → test가 `_clear_all()` 또는 cache fixture 통해 격리되어 있는지 확인. 필요 시 conftest에 `autouse=True` cache reset fixture 추가:
+
+```python
+# conftest.py에 추가 (선택)
+import pytest
+from app import webai_cache
+
+@pytest.fixture(autouse=True)
+def _reset_webai_cache():
+    webai_cache.PORTFOLIO_CACHE.clear()
+    webai_cache.NEWS_CACHE.clear()
+    webai_cache.SCREENER_CACHE.clear()
+    yield
+```
+
+- [ ] **Step 3: 커밋 (SP-A2 endpoint 통합 + 회귀 확인)**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git add stock/app/main.py stock/app/screener/router.py
+# (필요 시) git add stock/app/conftest.py
+git commit -m "$(cat <<'EOF'
+feat(stock): apply webai_cache to portfolio/news/screener-preview (SP-A2)
+
+3 endpoint cache 적용 — /api/webai/portfolio, /api/webai/news-sentiment,
+/api/stock/screener/run (preview 모드만, auto는 캐시 미적용).
+V1+V2 동시 호출도 NAS에서 1회 계산. web-ai 측 SP-A1 캐시와 2-layer로
+작동하여 NAS 인바운드 부담 70% 감소 예상.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 8: 양쪽 push + NAS deploy 트리거
+
+**Files:** 없음 (git 작업)
+
+- [ ] **Step 1: web-ai push**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git push origin main
+```
+
+Expected: success. 인증 prompt 뜨면 자격증명 입력. 1회 실패 시 1회 재시도 (캐시 패턴).
+
+> **참고:** web-ai는 NAS deployer가 별도 webhook 없음 (Windows 머신 코드). push는 백업/이력 동기화 목적. 실제 적용은 V2 재시작 시점.
+
+- [ ] **Step 2: web-backend push (NAS deployer 트리거)**
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git push origin main
+```
+
+Expected: success. NAS deployer가 webhook 수신 → `git pull` → `docker compose build stock --no-cache` (cachetools 신규 설치) → `docker compose up -d stock`. 통상 2~3분 소요.
+
+- [ ] **Step 3: NAS stock 컨테이너 헬스 확인**
+
+```bash
+curl -s -o /dev/null -w "HTTP %{http_code}\n" https://gahusb.synology.me/api/stock/news -m 10
+```
+
+Expected: `HTTP 200`. (NAS deploy 완료 후 통상 30초 ~ 2분 대기 필요.)
+
+- [ ] **Step 4: webai 캐시 효과 확인 (선택)**
+
+연속 2회 호출 시 두 번째가 즉시 응답하는지 (cached):
+
+```bash
+# 인증키 필요. .env의 WEBAI_API_KEY 사용 또는 NAS에서 직접 호출.
+# Windows 로컬에서:
+# 첫 호출
+time curl -s -H "X-WebAI-Key: $WEBAI_API_KEY" https://gahusb.synology.me/api/webai/portfolio -o /dev/null
+# 즉시 두번째 (캐시 hit 기대, 첫 호출 < 1s + DB / 두번째 < 100ms)
+time curl -s -H "X-WebAI-Key: $WEBAI_API_KEY" https://gahusb.synology.me/api/webai/portfolio -o /dev/null
+```
+
+Expected: 두 번째 호출이 첫 번째보다 명확히 빠름 (DB·계산 skip).
+
+---
+
+## Self-Review
+
+### Spec 커버리지
+
+| Spec 요구사항 | 구현 Task |
+|---------------|-----------|
+| §4 SP-A1: web-ai 캐시 TTL 증가 (180/600/300) | Task 1 |
+| §4 SP-A2: NAS stock TTLCache | Task 2~7 |
+| §10 SP-A2: 3 endpoint (portfolio/news/screener) 적용 | Task 4 (portfolio), Task 5 (news), Task 6 (screener preview) |
+| §10 SP-A2: cachetools 의존성 | Task 2 |
+| §8: X-WebAI-Key 인증 (기존 verify_webai_key 유지) | 기존 dependency 그대로, 변경 없음 |
+| §6: server cache 별개 (Redis 캐시 옵션) | in-memory TTLCache 선택 (Redis는 SP-1 이후 도입 검토) |
+
+§4의 SP-A2는 `/api/webai/portfolio`, `/api/webai/news-sentiment`, `/api/stock/screener/run` 3건만 명시. 추가 endpoint 캐시는 out of scope (별도 plan에서).
+
+### Placeholder 스캔
+
+- TBD/TODO/"implement later" 패턴 없음 ✓
+- 모든 code step에 완전 코드 포함 ✓
+- Task 6에 한 가지 conditional ("`post_run`의 정확한 return 라인을 먼저 확인") — 이건 plan 실행 시 grep 명령으로 즉시 해결 가능한 단순 lookup이라 placeholder가 아님. 그러나 안전성 위해 helper note 그대로 유지.
+
+### Type consistency
+
+- `webai_cache.cache_get_portfolio()` / `cache_set_portfolio(value)` — Task 3에서 정의, Task 4에서 사용. 시그니처 일치 ✓
+- `cache_get_news(date)` — Task 3·5 일치 ✓
+- `cache_get_screener(mode, top_n, weights)` / `cache_set_screener(mode, top_n, weights, value)` — Task 3·6 일치 ✓
+- 변수명 `cached`, `result`, `payload` — 각 함수 안에서만 사용, 충돌 없음 ✓
+
+### 위험·주의
+
+- **NAS deployer rebuild**: `requirements.txt` 변경은 docker image rebuild 필요. deployer가 변경 감지 시 rebuild 트리거. 만약 deployer가 변경 미감지(예: requirements.txt만 변경 시 rebuild 안 함)라면 NAS에서 `docker compose build stock --no-cache && docker compose up -d stock` 수동 실행 필요.
+- **Cache stale**: TTL이 충분히 짧아 stale 문제 미미. portfolio 120s = web-ai 폴링 주기(1분) 2배. 변경 감지에 최대 2분 지연.
+- **Cache miss thunder herd**: V1+V2가 정확히 동시에 캐시 miss 시 KIS 동시 호출 가능. 현재 V1/V2 둘 다 정지 상태라 risk 0. 향후 재시작 시 KIS rate limit 모니터링 필요 (별도 plan 항목).
+
+---
+
+## 완료 후 다음 단계
+
+Plan-A 완료 후 spec §14 "차후 plan 작성 순서 권장"대로:
+
+1. **Plan-B-Base** — SP-1 (Redis) + SP-2 (WSL2)
+2. **Plan-B-Insta** — SP-3 + SP-4
+3. **Plan-B-Music** — SP-5 + SP-6
+4. **Plan-B-Video** — SP-7 + SP-8
+5. **Plan-B-Infra** — SP-9 + SP-10
+
+각각은 별도 brainstorm 없이 spec §10에서 직접 plan 작성 가능 (이미 명세 충분).

docs/superpowers/plans/2026-05-22-plan-b-infra.md

@@ -0,0 +1,929 @@
+# Plan-B-Infra — NSSM 자동 시작 + task-watcher (시간대 큐 토글) 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:** Windows AI 머신의 서비스(ai_trade + WSL2 Docker)를 NSSM으로 부팅 시 자동 시작 + 우선순위 설정(SP-9), 그리고 시간대 기반으로 `queue:paused`를 토글하는 task-watcher 컨테이너 신설(SP-10). 트레이딩 시간대(비휴장 평일 07:00–16:30)에 무거운 render 작업을 일시정지하여 KIS 트레이딩 우선순위 보장.
+
+**Architecture:** task-watcher는 WSL2 Docker 컨테이너로 30초마다 `current_mode()` 판정(KST 시각 + NAS `/api/stock/holidays` 조회) → 트레이딩 시간대면 `SET queue:paused 1 EX 600`, 그 외엔 `DEL queue:paused`. 모든 render worker(insta/music/video)가 BLPOP 전 `queue:paused`를 확인하므로 단일 키로 전체 일시정지. NSSM(SP-9)은 박재오 Windows 머신에서 수동 설치 — plan은 정확한 명령 + 안내 문서 제공.
+
+**Tech Stack:** Python 3.12 / `redis>=5.0` / `httpx` (holidays fetch) / `zoneinfo` (KST) / Docker Engine in WSL2 / NSSM (Windows service manager) / FastAPI (NAS stock holidays endpoint)
+
+**Spec:** `web-backend/docs/superpowers/specs/2026-05-18-nas-windows-distributed-architecture-design.md` §3 시간대별 우선순위 모드, §10 SP-9·SP-10. **박재오 결정 (2026-05-22): idle/게임 감지 생략 — 시간대만으로 토글** (spec §3의 "박재오 활동 감지 시 SET" → "트레이딩 시간대면 무조건 SET"). idle 감지가 없으므로 WSL2 컨테이너로 구현 가능 (Win32 input API 불필요).
+
+**Spec 갱신 사항 (현 상태 반영):**
+- `signal_v2` → **`ai_trade`** (rename 완료, web-ai/ai_trade/)
+- `Ubuntu-22.04` → **`Ubuntu-24.04`** (Plan-B-Base에서 변경)
+- `web-ai-services` → **`web-ai/services`** (실제 경로)
+- `/api/stock/holidays` endpoint **미존재 → 신설** (Task 1)
+
+**Prerequisites (✅ 모두 완료):**
+- Plan-A / Plan-B-Base / Plan-B-Insta / Plan-B-Music / Plan-B-Video 모두 완료
+- WSL2 mirror mode + Redis chown 999:999 영구 적용
+- services/.env 분기 패턴 정착 (NAS_BASE_URL service-local default)
+
+---
+
+## Phase 구조
+
+| Phase | 내용 | Task |
+|-------|------|------|
+| **1. NAS stock holidays endpoint** | `/api/stock/holidays` GET 신설 (task-watcher가 조회) | 1 |
+| **2. Windows task-watcher** | mode 판정 + Redis 토글 loop + Dockerfile + compose | 2~6 |
+| **3. NSSM 안내 + 검증** | SP-9 NSSM 안내 문서 + 박재오 빌드 + end-to-end | 7~8 |
+
+---
+
+## File Structure
+
+### Phase 1 — NAS web-backend
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-backend/stock/app/main.py` | `GET /api/stock/holidays` endpoint 추가 | holidays.json + 주말 노출 |
+| `web-backend/stock/app/test_holidays_endpoint.py` (Create) | 2 tests | TDD |
+
+### Phase 2 — Windows web-ai/services/task-watcher
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-ai/services/task-watcher/mode.py` (Create) | `current_mode(now, holidays)` 순수 함수 + `fetch_holidays()` | 시간대 판정 |
+| `web-ai/services/task-watcher/watcher.py` (Create) | 30초 loop + Redis 토글 | dispatcher |
+| `web-ai/services/task-watcher/main.py` (Create) | FastAPI + lifespan(watcher spawn) + /health | entry |
+| `web-ai/services/task-watcher/Dockerfile` (Create) | python:3.12-slim | image |
+| `web-ai/services/task-watcher/requirements.txt` (Create) | fastapi, redis, httpx, pytest | deps |
+| `web-ai/services/task-watcher/.env.example` (Create) | REDIS_URL, STOCK_BASE_URL, TRADING_START, TRADING_END | secrets |
+| `web-ai/services/task-watcher/tests/test_mode.py` (Create) | current_mode 6 cases | TDD |
+| `web-ai/services/task-watcher/tests/__init__.py` (Create) | 빈 marker | pkg |
+| `web-ai/services/docker-compose.yml` | task-watcher service 추가 (port 18713) | compose |
+
+### Phase 3 — 안내 문서
+
+| 파일 | 변경 | 책임 |
+|------|------|------|
+| `web-ai/services/task-watcher/NSSM_SETUP.md` (Create) | SP-9 NSSM 설치 안내 (ai_trade + wsl_docker + task-watcher) | 박재오 수동 가이드 |
+
+---
+
+## Task 1: NAS stock — `/api/stock/holidays` endpoint + tests
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/main.py`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/test_holidays_endpoint.py`
+
+### Step 1: 실패 테스트 작성
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/test_holidays_endpoint.py`:
+
+```python
+"""GET /api/stock/holidays — task-watcher 휴장일 조회용."""
+from fastapi.testclient import TestClient
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_holidays_returns_list():
+    r = client.get("/api/stock/holidays")
+    assert r.status_code == 200
+    data = r.json()
+    assert "holidays" in data
+    assert isinstance(data["holidays"], list)
+
+
+def test_holidays_entries_are_iso_dates():
+    r = client.get("/api/stock/holidays")
+    holidays = r.json()["holidays"]
+    # 비어 있지 않다면 ISO date 형식 (YYYY-MM-DD)
+    if holidays:
+        import datetime as dt
+        for h in holidays[:5]:
+            dt.date.fromisoformat(h)   # raise 안 하면 통과
+```
+
+### Step 2: 테스트 실패 확인
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-backend/stock && python -m pytest app/test_holidays_endpoint.py -v`
+Expected: FAIL — endpoint 404.
+
+### Step 3: `main.py`에 endpoint 추가
+
+`C:/Users/jaeoh/Desktop/workspace/web-backend/stock/app/main.py`에서 `_HOLIDAYS_PATH` (현재 line 82 부근) 정의를 활용. 적절한 위치(다른 `@app.get` 근처)에 추가:
+
+```python
+@app.get("/api/stock/holidays")
+def get_holidays():
+    """task-watcher가 조회하는 휴장일 목록. holidays.json 그대로 노출 (인증 불필요)."""
+    import json
+    try:
+        with open(_HOLIDAYS_PATH, encoding="utf-8") as f:
+            data = json.load(f)
+        # holidays.json 구조가 list이거나 {"holidays": [...]} 또는 {year: [...]} 형태일 수 있음
+        if isinstance(data, list):
+            holidays = data
+        elif isinstance(data, dict) and "holidays" in data:
+            holidays = data["holidays"]
+        elif isinstance(data, dict):
+            # {year: [dates]} → flatten
+            holidays = [d for v in data.values() if isinstance(v, list) for d in v]
+        else:
+            holidays = []
+    except (OSError, ValueError):
+        holidays = []
+    return {"holidays": holidays}
+```
+
+**주의:** 작성 전 `holidays.json` 실제 구조를 확인할 것 (`Read web-backend/stock/app/holidays.json`). 위 코드는 list / `{"holidays":[]}` / `{year:[]}` 3가지 형태를 모두 처리하지만, 실제 구조에 맞게 단순화 가능.
+
+### Step 4: 테스트 통과
+
+Run: `python -m pytest app/test_holidays_endpoint.py -v`
+Expected: 2 PASS.
+
+### Step 5: 회귀 확인
+
+Run: `python -m pytest app/ -v 2>&1 | tail -5`
+Expected: 기존 stock 테스트 모두 통과 + 새 2개.
+
+### Step 6: 커밋
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend
+git add stock/app/main.py stock/app/test_holidays_endpoint.py
+git commit -m "$(cat <<'EOF'
+feat(stock): GET /api/stock/holidays endpoint (SP-10 task-watcher용)
+
+holidays.json 노출. task-watcher가 휴장일 판정에 조회.
+인증 불필요 (민감 정보 아님). 주말은 task-watcher가 weekday로 별도 판정.
+Plan-B-Infra Phase 1.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Context
+
+- spec §3: "휴장일 단일 소스 — web-backend/stock/app/holidays.json 정본. NAS stock이 GET /api/stock/holidays로 노출."
+- 현재 holidays.json은 `_is_holiday()` 내부 함수에서만 사용, HTTP endpoint 없음 → 신설.
+- stock 컨테이너는 이미 deploy.sh BUILD_TARGETS에 등재됨 (신규 lab 아님 — deploy scripts 추가 불필요).
+- 작업 디렉토리: `C:/Users/jaeoh/Desktop/workspace/web-backend`
+
+## Report
+
+- Status: DONE | DONE_WITH_CONCERNS | BLOCKED
+- holidays.json 실제 구조 (확인 결과)
+- 2 PASS + 회귀
+- 커밋 SHA
+
+---
+
+## Task 2: Windows task-watcher — mode.py (current_mode + fetch_holidays) + tests
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/mode.py`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/tests/__init__.py`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/tests/test_mode.py`
+
+### Step 1: 실패 테스트 작성
+
+`tests/__init__.py`: (빈 파일)
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/tests/test_mode.py`:
+
+```python
+"""current_mode — 시간대 + 휴장일 판정 (순수 함수)."""
+import datetime as dt
+from zoneinfo import ZoneInfo
+
+from mode import current_mode
+
+KST = ZoneInfo("Asia/Seoul")
+HOLIDAYS = {"2026-05-25"}  # 가상 휴장일 (월요일)
+
+
+def _kst(y, m, d, hh, mm):
+    return dt.datetime(y, m, d, hh, mm, tzinfo=KST)
+
+
+def test_weekday_trading_hours_is_trading():
+    # 2026-05-22 금요일 10:00 — 트레이딩 시간대
+    assert current_mode(_kst(2026, 5, 22, 10, 0), HOLIDAYS) == "trading"
+
+
+def test_weekday_before_open_is_free():
+    # 평일 06:00 — 장 전
+    assert current_mode(_kst(2026, 5, 22, 6, 0), HOLIDAYS) == "free"
+
+
+def test_weekday_after_close_is_free():
+    # 평일 17:00 — 장 마감 후
+    assert current_mode(_kst(2026, 5, 22, 17, 0), HOLIDAYS) == "free"
+
+
+def test_weekend_is_free():
+    # 2026-05-23 토요일 10:00
+    assert current_mode(_kst(2026, 5, 23, 10, 0), HOLIDAYS) == "free"
+
+
+def test_holiday_weekday_is_free():
+    # 2026-05-25 월요일이지만 휴장일 → 트레이딩 시간대라도 free
+    assert current_mode(_kst(2026, 5, 25, 10, 0), HOLIDAYS) == "free"
+
+
+def test_trading_boundary_inclusive_start_exclusive_end():
+    # 07:00 정각 = 트레이딩 시작, 16:30 정각 = 마감 (16:30은 free)
+    assert current_mode(_kst(2026, 5, 22, 7, 0), HOLIDAYS) == "trading"
+    assert current_mode(_kst(2026, 5, 22, 16, 29), HOLIDAYS) == "trading"
+    assert current_mode(_kst(2026, 5, 22, 16, 30), HOLIDAYS) == "free"
+```
+
+### Step 2: 테스트 실패 확인
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher && python -m pytest tests/test_mode.py -v`
+Expected: FAIL — `mode` 모듈 미존재.
+
+### Step 3: `mode.py` 작성
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/mode.py`:
+
+```python
+"""시간대 + 휴장일 기반 모드 판정 (idle 감지 생략 — 박재오 결정 2026-05-22).
+
+trading: 비휴장 평일 07:00–16:30 (장중) → queue:paused SET
+free:    그 외 (장 전/후, 주말, 휴장) → queue:paused DEL
+"""
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import os
+from typing import Set
+from zoneinfo import ZoneInfo
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+KST = ZoneInfo("Asia/Seoul")
+STOCK_BASE_URL = os.getenv("STOCK_BASE_URL", "http://192.168.45.54:18500")
+
+# 트레이딩 윈도우 (HH:MM, KST). .env로 조정 가능.
+TRADING_START = os.getenv("TRADING_START", "07:00")
+TRADING_END = os.getenv("TRADING_END", "16:30")
+
+
+def _parse_hhmm(s: str) -> dt.time:
+    hh, mm = s.split(":")
+    return dt.time(int(hh), int(mm))
+
+
+def current_mode(now: dt.datetime, holidays: Set[str]) -> str:
+    """now(KST aware) + holidays(ISO date set) → 'trading' | 'free'."""
+    # 주말 (토=5, 일=6)
+    if now.weekday() >= 5:
+        return "free"
+    # 휴장일
+    if now.date().isoformat() in holidays:
+        return "free"
+    # 트레이딩 윈도우 [start, end)
+    start = _parse_hhmm(TRADING_START)
+    end = _parse_hhmm(TRADING_END)
+    t = now.timetz().replace(tzinfo=None)
+    if start <= t < end:
+        return "trading"
+    return "free"
+
+
+def fetch_holidays() -> Set[str]:
+    """NAS stock /api/stock/holidays 조회. 실패 시 빈 set (안전 — free로 판정)."""
+    try:
+        r = httpx.get(f"{STOCK_BASE_URL}/api/stock/holidays", timeout=10.0)
+        if r.status_code == 200:
+            return set(r.json().get("holidays", []))
+        logger.warning("holidays fetch returned %d", r.status_code)
+    except Exception:
+        logger.exception("holidays fetch 실패")
+    return set()
+```
+
+### Step 4: 테스트 통과
+
+Run: `python -m pytest tests/test_mode.py -v`
+Expected: 6 PASS.
+
+### Step 5: 커밋
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add services/task-watcher/mode.py services/task-watcher/tests/__init__.py services/task-watcher/tests/test_mode.py
+git commit -m "$(cat <<'EOF'
+feat(task-watcher): mode.py — 시간대+휴장일 판정 (SP-10)
+
+current_mode(now, holidays): 비휴장 평일 07:00–16:30 → trading, 그 외 free.
+fetch_holidays(): NAS /api/stock/holidays 조회 (실패 시 빈 set = free 안전).
+TRADING_START/END env로 윈도우 조정. idle 감지 생략 (박재오 결정).
+6 tests (평일 장중/장전/장후, 주말, 휴장, 경계).
+Plan-B-Infra Phase 2.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Context
+
+- KST 시각 + holidays set → trading/free 순수 함수. 테스트 용이 (now를 인자로).
+- holidays는 fetch_holidays()로 NAS 조회. 매 loop마다 호출하면 부하 — watcher.py에서 캐싱 (Task 3).
+- 작업 디렉토리: `C:/Users/jaeoh/Desktop/workspace/web-ai`
+
+## Report
+- Status / 6 PASS / 커밋 SHA
+
+---
+
+## Task 3: Windows task-watcher — watcher.py (Redis 토글 loop)
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/watcher.py`
+
+### Step 1: `watcher.py` 작성
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/watcher.py`:
+
+```python
+"""30초마다 current_mode 판정 → queue:paused 토글.
+
+trading → SET queue:paused 1 EX 600 (10분 TTL — watcher 죽어도 자동 해제)
+free    → DEL queue:paused
+holidays는 1시간마다 refresh (매 loop fetch 부하 회피).
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import logging
+import os
+from zoneinfo import ZoneInfo
+
+import redis.asyncio as aioredis
+
+from mode import current_mode, fetch_holidays, KST
+
+logger = logging.getLogger(__name__)
+
+REDIS_URL = os.getenv("REDIS_URL", "redis://192.168.45.54:6379")
+PAUSED_KEY = "queue:paused"
+LOOP_INTERVAL = 30          # 초
+HOLIDAYS_REFRESH = 3600     # 1시간
+PAUSED_TTL = 600            # 10분 (watcher 죽어도 자동 해제)
+
+
+async def watcher_loop():
+    redis = aioredis.from_url(REDIS_URL, decode_responses=False)
+    holidays = fetch_holidays()
+    last_holiday_refresh = dt.datetime.now(KST)
+    last_mode = None
+    logger.info("task-watcher started (trading window 토글)")
+
+    while True:
+        try:
+            now = dt.datetime.now(KST)
+            # holidays 주기적 refresh
+            if (now - last_holiday_refresh).total_seconds() >= HOLIDAYS_REFRESH:
+                holidays = fetch_holidays()
+                last_holiday_refresh = now
+
+            mode = current_mode(now, holidays)
+            if mode == "trading":
+                await redis.set(PAUSED_KEY, b"1", ex=PAUSED_TTL)
+            else:
+                await redis.delete(PAUSED_KEY)
+
+            if mode != last_mode:
+                logger.info("mode 전환: %s → %s (paused=%s)", last_mode, mode, mode == "trading")
+                last_mode = mode
+
+            await asyncio.sleep(LOOP_INTERVAL)
+        except asyncio.CancelledError:
+            logger.info("watcher_loop cancelled")
+            raise
+        except Exception:
+            logger.exception("watcher_loop iteration 실패, 30초 후 재시도")
+            await asyncio.sleep(LOOP_INTERVAL)
+```
+
+### Step 2: 임포트 smoke
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher && python -c "from watcher import watcher_loop; print('OK')"`
+Expected: `OK`.
+
+### Step 3: 커밋
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add services/task-watcher/watcher.py
+git commit -m "$(cat <<'EOF'
+feat(task-watcher): watcher.py — 30초 loop + queue:paused 토글 (SP-10)
+
+trading → SET queue:paused 1 EX 600 / free → DEL.
+holidays 1시간마다 refresh. PAUSED_TTL 600s (watcher 죽어도 자동 해제 — 안전).
+mode 전환 시에만 로그.
+Plan-B-Infra Phase 2.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Context
+
+- `PAUSED_TTL=600`이 핵심 안전장치: task-watcher가 죽어도 10분 후 자동으로 paused 해제 → 큐 영구 정지 방지.
+- holidays는 1시간 캐싱 (매 30초 fetch 안 함).
+- render worker들(insta/music/video)이 이미 `queue:paused` 체크 로직 보유 (Plan-B-Insta/Music/Video).
+
+## Report
+- Status / smoke 결과 / 커밋 SHA
+
+---
+
+## Task 4: Windows task-watcher — main.py + Dockerfile + requirements + .env.example
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/main.py`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/Dockerfile`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/requirements.txt`
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/.env.example`
+
+### Step 1: `requirements.txt`
+
+```
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+redis>=5.0
+httpx>=0.27
+pytest>=8.0
+```
+
+### Step 2: `Dockerfile`
+
+```dockerfile
+FROM python:3.12-slim-bookworm
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates tzdata \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --timeout 600 --retries 5 -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
+```
+
+(tzdata 추가 — zoneinfo Asia/Seoul 사용.)
+
+### Step 3: `.env.example`
+
+```
+# Plan-B-Infra — task-watcher
+
+# NAS Redis
+REDIS_URL=redis://192.168.45.54:6379
+
+# NAS stock holidays endpoint
+STOCK_BASE_URL=http://192.168.45.54:18500
+
+# 트레이딩 윈도우 (KST, HH:MM) — 이 시간대에만 queue:paused
+TRADING_START=07:00
+TRADING_END=16:30
+```
+
+### Step 4: `main.py`
+
+```python
+"""task-watcher FastAPI entry — health + lifespan (watcher loop spawn)."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+import watcher
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    watcher_task = asyncio.create_task(watcher.watcher_loop())
+    logger.info("task-watcher lifespan 시작")
+    try:
+        yield
+    finally:
+        watcher_task.cancel()
+        try:
+            await watcher_task
+        except asyncio.CancelledError:
+            pass
+        logger.info("task-watcher lifespan 종료")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/health")
+def health():
+    return {"ok": True, "service": "task-watcher"}
+```
+
+### Step 5: smoke + 회귀
+
+Run:
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher
+python -c "from main import app; print(len(app.routes))"
+python -m pytest tests/ -v 2>&1 | tail -5
+```
+Expected: 숫자 출력 + 6 PASS (test_mode).
+
+### Step 6: 커밋
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add services/task-watcher/main.py services/task-watcher/Dockerfile services/task-watcher/requirements.txt services/task-watcher/.env.example
+git commit -m "$(cat <<'EOF'
+feat(task-watcher): main.py + Dockerfile + requirements + env (SP-10)
+
+FastAPI lifespan에서 watcher_loop 스폰. /health. tzdata(zoneinfo Asia/Seoul).
+.env: REDIS_URL, STOCK_BASE_URL, TRADING_START/END.
+Plan-B-Infra Phase 2.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Report
+- Status / routes 개수 / 6 PASS / 커밋 SHA
+
+---
+
+## Task 5: Windows services/docker-compose — task-watcher entry
+
+**Files:**
+- Modify: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/docker-compose.yml`
+
+### Step 1: video-render service 다음에 task-watcher 추가
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/services/docker-compose.yml`에 추가:
+
+```yaml
+
+  task-watcher:
+    build:
+      context: ./task-watcher
+    container_name: task-watcher
+    restart: unless-stopped
+    ports:
+      - "18713:8000"
+    environment:
+      - TZ=Asia/Seoul
+      - REDIS_URL=${REDIS_URL:-redis://192.168.45.54:6379}
+      - STOCK_BASE_URL=${STOCK_BASE_URL:-http://192.168.45.54:18500}
+      - TRADING_START=${TRADING_START:-07:00}
+      - TRADING_END=${TRADING_END:-16:30}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+```
+
+### Step 2: YAML 검증
+
+Run: `cd C:/Users/jaeoh/Desktop/workspace/web-ai/services && python -c "import yaml; yaml.safe_load(open('docker-compose.yml')); print('valid YAML')"`
+Expected: `valid YAML`.
+
+### Step 3: 커밋 + push
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add services/docker-compose.yml
+git commit -m "$(cat <<'EOF'
+feat(task-watcher): services/docker-compose entry (SP-10)
+
+port 18713, REDIS_URL/STOCK_BASE_URL/TRADING_START/END env.
+insta/music/video-render와 같은 services 묶음. outbound only.
+Plan-B-Infra Phase 2 완료 — 박재오 빌드 대기.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+git push 2>&1   # 자격증명 실패 시 박재오 수동 push
+```
+
+## Report
+- Status / YAML 검증 / 커밋 SHA / push 결과
+
+---
+
+## Task 6: NSSM 안내 문서 (SP-9)
+
+**Files:**
+- Create: `C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/NSSM_SETUP.md`
+
+SP-9는 박재오 Windows 머신에서 NSSM 수동 설치. controller는 정확한 명령 + 안내 문서 작성. (코드 아님 — 안내 문서.)
+
+### Step 1: `NSSM_SETUP.md` 작성
+
+`C:/Users/jaeoh/Desktop/workspace/web-ai/services/task-watcher/NSSM_SETUP.md`:
+
+```markdown
+# NSSM 자동 시작 설정 (SP-9)
+
+Windows AI 머신 부팅 시 ai_trade(트레이딩) + WSL2 Docker(render workers + task-watcher) 자동 시작.
+
+## 1. NSSM 다운로드
+
+https://nssm.cc/download → nssm-2.24.zip → `C:\nssm\nssm.exe` 배치 (또는 PATH 등록).
+
+## 2. ai_trade (Native Python, HIGH priority)
+
+⚠️ spec의 signal_v2는 ai_trade로 rename됨. 경로/포트 확인.
+
+```powershell
+# 관리자 PowerShell
+C:\nssm\nssm.exe install ai_trade "C:\Python312\python.exe" "-m uvicorn main:app --host 0.0.0.0 --port 8001"
+C:\nssm\nssm.exe set ai_trade AppDirectory "C:\Users\jaeoh\Desktop\workspace\web-ai\ai_trade"
+C:\nssm\nssm.exe set ai_trade Priority HIGH_PRIORITY_CLASS
+C:\nssm\nssm.exe set ai_trade Start SERVICE_AUTO_START
+C:\nssm\nssm.exe set ai_trade AppStdout "C:\Users\jaeoh\nssm-logs\ai_trade.log"
+C:\nssm\nssm.exe set ai_trade AppStderr "C:\Users\jaeoh\nssm-logs\ai_trade.log"
+```
+
+(ai_trade의 실제 진입점이 main:app + port 8001인지 확인. 다르면 조정.)
+
+## 3. WSL2 Docker (NORMAL priority — render workers + task-watcher)
+
+```powershell
+C:\nssm\nssm.exe install wsl_docker "C:\Windows\System32\wsl.exe" "-d Ubuntu-24.04 -- sh -c 'sudo service docker start && cd /workspace/web-ai/services && docker compose up -d'"
+C:\nssm\nssm.exe set wsl_docker Priority NORMAL_PRIORITY_CLASS
+C:\nssm\nssm.exe set wsl_docker Start SERVICE_AUTO_START
+C:\nssm\nssm.exe set wsl_docker AppStdout "C:\Users\jaeoh\nssm-logs\wsl_docker.log"
+```
+
+⚠️ 변경점: Ubuntu-22.04 → **Ubuntu-24.04**, web-ai-services → **web-ai/services**. WSL 경로는 `/mnt/c/...` 또는 박재오 WSL 마운트 기준 (`/workspace`가 web-ai에 매핑되어 있으면 그대로).
+
+`sudo service docker start`가 비밀번호 요구하면 sudoers에 NOPASSWD 추가:
+```bash
+# WSL2 안
+echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/service docker start" | sudo tee /etc/sudoers.d/docker-start
+```
+
+## 4. 서비스 시작 + 확인
+
+```powershell
+C:\nssm\nssm.exe start ai_trade
+C:\nssm\nssm.exe start wsl_docker
+
+# 상태 확인
+C:\nssm\nssm.exe status ai_trade
+C:\nssm\nssm.exe status wsl_docker
+sc query ai_trade
+```
+
+## 5. 검증
+
+```powershell
+# ai_trade
+curl http://localhost:8001/health   # 또는 ai_trade의 실제 health endpoint
+
+# WSL2 docker 컨테이너 (재부팅 후 자동 시작 확인)
+wsl -d Ubuntu-24.04 -- docker ps
+# insta-render, music-render, video-render, task-watcher 4개 Up 확인
+```
+
+## 6. 재부팅 테스트
+
+Windows 재부팅 → 로그인 → 수동 조작 없이:
+- ai_trade 서비스 자동 시작 (HIGH priority)
+- WSL2 + Docker + 4 컨테이너 자동 시작 (NORMAL priority)
+- task-watcher가 trading window에 queue:paused 토글 시작
+
+## task-watcher 동작 확인
+
+```bash
+# WSL2
+docker logs task-watcher --tail 20
+# 기대: "task-watcher started" + mode 전환 로그 (trading/free)
+
+# Redis 큐 상태 (NAS 또는 LAN)
+docker exec redis redis-cli GET queue:paused
+# 트레이딩 시간대(평일 07:00-16:30): "1"
+# 그 외: (nil)
+```
+```
+
+### Step 2: 커밋 + push
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-ai
+git add services/task-watcher/NSSM_SETUP.md
+git commit -m "$(cat <<'EOF'
+docs(task-watcher): NSSM_SETUP.md — SP-9 자동 시작 안내
+
+ai_trade(HIGH, native python :8001) + wsl_docker(NORMAL, WSL2 Ubuntu-24.04
+docker compose up). spec의 signal_v2→ai_trade, 22.04→24.04, web-ai-services
+→web-ai/services 정정. sudoers NOPASSWD + 재부팅 검증 절차.
+Plan-B-Infra Phase 3.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+git push 2>&1
+```
+
+## Report
+- Status / 커밋 SHA / push 결과
+
+---
+
+## Task 7: 박재오 빌드 + task-watcher 검증
+
+**Files:** (변경 없음 — 박재오 측 작업 + 검증)
+
+### Step 1: web-backend push (Task 1 holidays endpoint)
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend && git push
+```
+→ NAS deployer가 stock 컨테이너 rebuild. `/api/stock/holidays` 활성화.
+
+### Step 2: 박재오 NAS 측 holidays endpoint 확인
+
+```bash
+curl https://gahusb.synology.me/api/stock/holidays
+# → {"holidays": ["2026-01-01", ...]}
+```
+
+### Step 3: 박재오 Windows 측 task-watcher 빌드
+
+```bash
+cd /workspace/web-ai && git pull
+cd /workspace/web-ai/services
+docker compose build task-watcher
+docker compose up -d task-watcher
+docker logs task-watcher --tail 20
+# 기대: "task-watcher lifespan 시작" + "task-watcher started" + mode 로그
+curl -m 3 http://localhost:18713/health
+```
+
+### Step 4: 시간대 토글 검증
+
+현재 KST 시각 기준:
+```bash
+# 트레이딩 시간대(평일 07:00-16:30)면 paused=1, 아니면 nil
+docker exec task-watcher python -c "import datetime as dt; from zoneinfo import ZoneInfo; from mode import current_mode, fetch_holidays; print('now mode:', current_mode(dt.datetime.now(ZoneInfo('Asia/Seoul')), fetch_holidays()))"
+
+# Redis 확인 (NAS 또는 LAN)
+ssh nas
+docker exec redis redis-cli GET queue:paused
+```
+
+기대:
+- 평일 07:00-16:30 (비휴장): `current_mode` = "trading", `queue:paused` = "1"
+- 그 외: "free", (nil)
+
+### Step 5: render worker가 paused 존중하는지 (선택)
+
+트레이딩 시간대에 video 생성 요청 → worker가 BLPOP 전 paused 확인 → 10초 대기 반복 (처리 보류). free 시간대 되면 자동 처리. (이미 Plan-B-Insta/Music/Video worker에 `queue:paused` 체크 로직 있음.)
+
+### Step 6: 메모리 기록
+
+`reference_plan_b_infra_complete.md` 작성 + MEMORY.md 인덱스 추가 (Task 8에서).
+
+## Report
+- holidays endpoint 응답
+- task-watcher health + mode
+- queue:paused 토글 확인
+
+---
+
+## Task 8: 메모리 기록 + 최종 정리
+
+**Files:**
+- Create: `C:/Users/jaeoh/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ui/memory/reference_plan_b_infra_complete.md`
+- Modify: `C:/Users/jaeoh/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ui/memory/MEMORY.md`
+
+### Step 1: `reference_plan_b_infra_complete.md`
+
+```markdown
+---
+name: plan-b-infra-complete
+description: 2026-05-22 Plan-B-Infra — NSSM 자동 시작(SP-9) + task-watcher 시간대 큐 토글(SP-10). spec 12 SP 전부 완료
+metadata:
+  type: reference
+---
+
+Plan-B-Infra 2026-05-22 완료. spec §10 SP-9 + SP-10. 이로써 NAS↔Windows 분산 아키텍처 spec의 12 SP 전부 완료.
+
+## SP-10 task-watcher (구현)
+- web-ai/services/task-watcher/ WSL2 컨테이너 (port 18713)
+- 30초 loop: current_mode(KST + holidays) → queue:paused 토글
+- trading(비휴장 평일 07:00-16:30) → SET queue:paused 1 EX 600 / free → DEL
+- **idle/게임 감지 생략** (박재오 결정 2026-05-22) — WSL2 컨테이너는 Win32 input API 접근 불가. 시간대만으로 판정.
+- PAUSED_TTL 600s = watcher 죽어도 10분 후 자동 해제 (큐 영구정지 방지 안전장치)
+- holidays는 NAS GET /api/stock/holidays (신설) 1시간 캐싱
+- TRADING_START/END env로 윈도우 조정
+
+## SP-9 NSSM (박재오 수동)
+- NSSM_SETUP.md 안내 문서. ai_trade(HIGH, native :8001) + wsl_docker(NORMAL, WSL2 docker compose up)
+- spec 정정: signal_v2→ai_trade, Ubuntu-22.04→24.04, web-ai-services→web-ai/services
+
+## NAS holidays endpoint (신설)
+- GET /api/stock/holidays — holidays.json 노출. 기존엔 _is_holiday() 내부 함수만 있었음.
+
+## 다음
+- frontend video/music/insta UI (backend gateway만 완료, UI 별도)
+- FOLLOW-UP B: -lab suffix 제거
+```
+
+### Step 2: MEMORY.md 인덱스 추가
+
+`reference_plan_b_video_complete.md` 항목 뒤:
+```markdown
+- [Plan-B-Infra 완료](reference_plan_b_infra_complete.md) — 2026-05-22 NSSM 자동 시작(SP-9) + task-watcher 시간대 큐 토글(SP-10). idle 감지 생략. spec 12 SP 전부 완료
+```
+
+### Step 3: 양쪽 push 확인
+
+```bash
+cd C:/Users/jaeoh/Desktop/workspace/web-backend && git status && git log --oneline -3
+cd C:/Users/jaeoh/Desktop/workspace/web-ai && git status && git log --oneline -5
+```
+
+### Step 4: 박재오 보고
+- spec 12 SP 전부 완료
+- task-watcher 시간대 토글 동작
+- NSSM은 박재오 수동 (NSSM_SETUP.md 참고)
+
+## Report
+- 메모리 파일 생성
+- push 상태
+- 최종 보고
+
+---
+
+## Self-Review
+
+**1. Spec coverage**
+
+| Spec 요구사항 | 구현 위치 | 상태 |
+|--------------|-----------|------|
+| SP-9 §10: NSSM ai_trade(HIGH) + wsl_docker(NORMAL) 자동 시작 | Task 6 NSSM_SETUP.md | ✓ (박재오 수동 + 안내) |
+| SP-10 §10: task-watcher 컨테이너 30초 loop | Task 3 watcher.py | ✓ |
+| SP-10 §10: current_mode (시간대 + holidays + KST) | Task 2 mode.py | ✓ |
+| SP-10 §10: queue:paused 토글 (free→DEL, trading→SET) | Task 3 | ✓ |
+| §3 휴장일 단일 소스 GET /api/stock/holidays | Task 1 | ✓ (신설) |
+| 박재오 결정: idle 감지 생략 — 시간대만 | Task 2 (is_user_active 제거) | ✓ |
+| §3 트레이딩 모드 = 평일 비휴장 07:00-16:30 | Task 2 TRADING_START/END | ✓ |
+
+**spec 대비 의도적 변경 (박재오 승인):**
+- idle/게임 감지 생략 — spec §10 SP-10의 `is_user_active()` 제거. trading 시간대면 무조건 paused.
+- spec §3의 🟡 일반(16:30-23:30) 모드 → free로 통합 (트레이딩 시간대만 paused).
+
+**2. Placeholder scan:** 통과. NSSM_SETUP.md의 "(확인)" 표기는 박재오 환경 검증 안내 (placeholder 아님).
+
+**3. Type consistency:**
+- `current_mode(now: dt.datetime, holidays: Set[str]) -> str` — Task 2 정의, Task 3 watcher_loop + Task 7 검증 호출 일관
+- `fetch_holidays() -> Set[str]` — Task 2 정의, Task 3 호출
+- mode 값 `"trading"` | `"free"` 2개 — Task 2/3/7 일관
+- `PAUSED_KEY = "queue:paused"` — Task 3, render workers의 PAUSED_KEY와 동일 문자열 (Plan-B-Insta/Music/Video)
+
+**4. 함정 사전 인지:**
+- task-watcher는 services/ 컨테이너 (NAS lab 아님) → deploy.sh 6위치 등재 불필요
+- holidays endpoint(stock)는 기존 컨테이너 수정 → deploy.sh 등재 이미 됨
+- services/.env: TRADING_START/END는 task-watcher 전용 → 다른 서비스와 충돌 없음 (compose default로 분기)
+- PAUSED_TTL로 watcher 장애 시 큐 영구정지 방지
+
+플랜 완성. 모든 검토 통과.
+
+---
+
+## 부록 — 알려진 결정 + follow-up
+
+**박재오 결정 (2026-05-22):** idle/게임 감지 생략. 시간대만으로 큐 토글. 박재오 7결정 #1의 "Windows 작업 감지 큐 정지"는 부분 포기 (시간대 기반만). 향후 idle 감지 필요 시 Windows native idle-reporter(GetLastInputInfo) → Redis user:last_input_ts 기록 → task-watcher가 읽는 hybrid로 확장 가능.
+
+**spec 12 SP 완료 후 follow-up:**
+- frontend `/video` `/music` UI (backend gateway만 완료)
+- FOLLOW-UP B: `-lab` suffix 일괄 제거
+- GCS lifecycle (Veo Vertex 미사용으로 무관 — Gemini API는 GCS 안 씀)
+- Sora 2 alternative (2026-09-24 deprecated 대비)

docs/superpowers/plans/2026-06-02-insta-cardnews-upgrade.md

@@ -0,0 +1,408 @@
+# 인스타 카드뉴스 품질 고도화 + 업로드 친화 패키지 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:** 인스타 카드를 모던 미니멀 디자인 시스템으로 격상하고(렌더 견고화로 known-issue 해결), 완성 패키지를 zip으로 받아 인스타에 쉽게 업로드(반자동)할 수 있게 한다.
+
+**Architecture:** 디자인 시스템 Jinja 템플릿(페이지 타입별 레이아웃)을 web-ai insta-render 워커(authoritative)와 insta-lab(참조 복사본)에 작성. 워커 `card_renderer.py`에 `document.fonts.ready` 대기 + PNG 검증 추가. card_writer 프롬프트에 글자수 가이드. insta-lab에 zip 패키지 API + web-ui 다운로드 버튼. Graph API 미사용(반자동).
+
+**Tech Stack:** Jinja2 + HTML/CSS, Playwright(Chromium), FastAPI, pytest / React+Vite(web-ui).
+
+**Spec:** `docs/superpowers/specs/2026-06-02-insta-cardnews-upgrade-design.md`
+
+**⚠️ 3 repo 작업** (커밋·배포 경로 다름):
+- `web-backend/insta-lab` — git push → Gitea webhook 자동배포 (NAS)
+- `web-ai/services/insta-render` — **별도 repo(ai-trade.git), Windows 머신 구동** — 워커가 실제 렌더하는 authoritative 템플릿 위치
+- `web-ui` — **별도 repo**, `npm run release:nas` 수동 배포
+
+---
+
+## 검증된 컨텍스트
+- 워커 렌더: `web-ai/services/insta-render/card_renderer.py` — `_build_pages(slate)`가 10 spec 생성(cover page_no=1 / body page_no=2~9 / cta page_no=10, 각 `page_type`/`headline`/`body`/`accent_color`/`cta`/`page_no`/`total_pages`). `CARD_TEMPLATE_DIR`(기본 `/app/templates`)에서 `{theme}/card.html.j2` 로드 → `page.goto(file://, networkidle)` → `screenshot(full_page=False)` @viewport 1080×1350.
+- 워커 템플릿 실제 위치: `web-ai/services/insta-render/templates/default/card.html.j2` (현재 insta-lab과 동일한 55줄 기본형). **이게 렌더에 쓰이는 authoritative 파일.**
+- 카피: `insta-lab/app/card_writer.py` `DEFAULT_PROMPT`(DB `slate_writer` 오버라이드 가능). 산출: cover_copy{headline,body,accent_color}/body_copies[8]{headline,body}/cta_copy{headline,body,cta}/suggested_caption/hashtags[].
+- 슬레이트 PNG: 워커가 `INSTA_MEDIA_ROOT/{slate_id}/{page_no:02d}.png` 저장. NAS에서 `card_assets` 테이블 + `db.list_card_assets(slate_id)`(page_index + 파일경로)로 추적. `GET /api/insta/slates/{id}/assets/{page}`가 단일 PNG 서빙(파일경로 읽어 반환).
+- 슬레이트 데이터: `db.get_card_slate(slate_id)` + `db.list_card_assets(slate_id)`. `GET /api/insta/slates/{id}`가 slate + assets 반환.
+
+---
+
+# Phase 1 — 모던 미니멀 디자인 시스템 템플릿 (web-ai authoritative + insta-lab 복사본)
+
+## Task 1.1: 디자인 시스템 card.html.j2 작성
+
+**Files:**
+- Modify: `web-ai/services/insta-render/templates/default/card.html.j2` (**렌더 authoritative**)
+- Modify: `web-backend/insta-lab/app/templates/default/card.html.j2` (참조 복사본 — 동일 내용 유지)
+
+> 두 파일을 **동일 내용**으로 작성한다. 워커가 web-ai 쪽을 렌더하지만 insta-lab 복사본도 일관성 위해 갱신.
+
+- [ ] **Step 1: 디자인 시스템 템플릿 작성** — 아래 전체 내용으로 두 파일을 교체:
+
+```html
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+<meta charset="UTF-8">
+<style>
+  @import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.css');
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { width: 1080px; height: 1350px; }
+  body {
+    font-family: 'Pretendard', 'Noto Sans KR', sans-serif;
+    background: #F7F7FA; color: #14171A;
+    -webkit-font-smoothing: antialiased;
+  }
+  .card {
+    position: relative; width: 1080px; height: 1350px; overflow: hidden;
+    padding: 96px 84px 72px;
+    display: flex; flex-direction: column;
+    background: #FFFFFF;
+  }
+  .accent-bar { position: absolute; top: 0; left: 0; width: 100%; height: 14px; background: {{ accent_color }}; }
+  .badge {
+    align-self: flex-start; padding: 10px 24px; border-radius: 999px;
+    background: {{ accent_color }}; color: #fff;
+    font-size: 30px; font-weight: 700; letter-spacing: -0.02em;
+  }
+  .idx { font-size: 120px; font-weight: 800; line-height: 1; color: {{ accent_color }}; letter-spacing: -0.04em; }
+  .content { flex: 1; display: flex; flex-direction: column; justify-content: center; gap: 36px; }
+  .headline {
+    font-weight: 800; line-height: 1.18; letter-spacing: -0.04em; color: #14171A;
+    display: -webkit-box; -webkit-box-orient: vertical; overflow: hidden;
+  }
+  .cover .headline { font-size: 104px; -webkit-line-clamp: 4; }
+  .body-page .headline { font-size: 76px; -webkit-line-clamp: 3; }
+  .cta .headline { font-size: 88px; -webkit-line-clamp: 3; }
+  .sub {
+    font-size: 42px; font-weight: 400; line-height: 1.5; color: #3A4047;
+    display: -webkit-box; -webkit-box-orient: vertical; overflow: hidden; -webkit-line-clamp: 8;
+    white-space: pre-wrap;
+  }
+  .footer {
+    display: flex; justify-content: space-between; align-items: center;
+    font-size: 28px; color: #8A9099; font-weight: 600; margin-top: 40px;
+  }
+  .cta-pill {
+    align-self: flex-start; margin-top: 8px; padding: 18px 40px; border-radius: 16px;
+    background: {{ accent_color }}; color: #fff; font-size: 40px; font-weight: 700;
+  }
+  .progress { display: flex; gap: 10px; }
+  .progress i { width: 14px; height: 14px; border-radius: 50%; background: #D8DCE0; display: inline-block; }
+  .progress i.on { background: {{ accent_color }}; }
+</style>
+</head>
+<body>
+<div class="card {{ 'cover' if page_type=='cover' else ('cta' if page_type=='cta' else 'body-page') }}">
+  <div class="accent-bar"></div>
+
+  {% if page_type == 'cover' %}
+    <span class="badge">{{ category_label|default(headline[:0]) }}{{ '오늘의 이슈' if not category_label }}</span>
+    <div class="content">
+      <h1 class="headline">{{ headline }}</h1>
+      <p class="sub">{{ body }}</p>
+    </div>
+  {% elif page_type == 'cta' %}
+    <div class="content">
+      <h1 class="headline">{{ headline }}</h1>
+      <p class="sub">{{ body }}</p>
+      {% if cta %}<div class="cta-pill">{{ cta }}</div>{% endif %}
+    </div>
+  {% else %}
+    <span class="idx">{{ '%02d'|format(page_no - 1) }}</span>
+    <div class="content">
+      <h1 class="headline">{{ headline }}</h1>
+      <p class="sub">{{ body }}</p>
+    </div>
+  {% endif %}
+
+  <div class="footer">
+    {% if page_type == 'cover' or page_type == 'cta' %}
+      <span>{{ brand_handle|default('') }}</span><span>{{ page_no }} / {{ total_pages }}</span>
+    {% else %}
+      <div class="progress">{% for n in range(2, total_pages) %}<i class="{{ 'on' if n <= page_no }}"></i>{% endfor %}</div>
+      <span>{{ page_no }} / {{ total_pages }}</span>
+    {% endif %}
+  </div>
+</div>
+</body>
+</html>
+```
+> 디자인 노트: 페이지 타입별 분기(cover 대형 헤드라인+서브+배지 / body 좌상단 인덱스 `01~08`(page_no-1)+헤드라인+본문+진행 점 / cta 요약+CTA pill). `-webkit-line-clamp`로 오버플로우 2차 방어(글자수 가이드가 1차). `accent_color`는 기존 데이터. `brand_handle`은 미설정 시 빈칸(추후 핸들 주입 가능). Pretendard CDN(@import) — Phase 2의 fonts.ready 대기와 짝.
+
+- [ ] **Step 2: 렌더 스모크 확인 (web-ai)** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ai/services/insta-render && python -c "from jinja2 import Environment, FileSystemLoader; e=Environment(loader=FileSystemLoader('templates')); t=e.get_template('default/card.html.j2'); [print(pt, len(t.render(page_type=pt, page_no=n, total_pages=10, headline='테스트 헤드라인', body='본문 테스트입니다.', accent_color='#0F62FE', cta='팔로우')) > 0) for pt,n in [('cover',1),('body',3),('cta',10)]]"`
+  Expected: `True` 3줄 (3 페이지 타입 모두 렌더 예외 없음).
+
+- [ ] **Step 3: Commit (2 repo 각각)**
+```bash
+# web-ai repo
+cd /c/Users/jaeoh/Desktop/workspace/web-ai && git add services/insta-render/templates/default/card.html.j2 && git commit -m "feat(insta-render): 모던 미니멀 디자인 시스템 템플릿"
+# insta-lab repo (참조 복사본)
+cd /c/Users/jaeoh/Desktop/workspace/web-backend && git add insta-lab/app/templates/default/card.html.j2 && git commit -m "feat(insta-lab): default 템플릿 디자인 시스템 동기화(참조용)"
+```
+> 커밋 메시지 trailer 각각에 `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>` 추가.
+
+---
+
+# Phase 2 — 렌더 견고화 (web-ai 워커, known-issue 해결)
+
+## Task 2.1: fonts.ready 대기 + PNG 비어있음 검증
+
+**Files:**
+- Modify: `web-ai/services/insta-render/card_renderer.py` (`_render_slate_locked`)
+- Test: `web-ai/services/insta-render/tests/test_worker.py` (또는 기존 테스트 파일에 추가)
+
+- [ ] **Step 1: 실패 테스트** — `tests/test_worker.py`에 추가 (실제 Chromium 렌더 + 검증). 워커 테스트 관례 확인 후 맞출 것; pytest-asyncio 사용 가정:
+```python
+import os
+import pytest
+from card_renderer import render_slate, init_browser, shutdown_browser
+
+@pytest.mark.asyncio
+async def test_render_produces_nonempty_1080x1350(tmp_path, monkeypatch):
+    monkeypatch.setattr("card_renderer.INSTA_MEDIA_ROOT", str(tmp_path))
+    await init_browser()
+    try:
+        slate = {
+            "cover_copy": {"headline": "헤드라인", "body": "서브", "accent_color": "#0F62FE"},
+            "body_copies": [{"headline": f"포인트{i}", "body": "본문"} for i in range(8)],
+            "cta_copy": {"headline": "요약", "body": "마무리", "cta": "팔로우"},
+        }
+        paths = await render_slate(slate, slate_id=99999)
+        assert len(paths) == 10
+        for p in paths:
+            assert os.path.getsize(p) > 1000          # 비어있지 않음
+    finally:
+        await shutdown_browser()
+```
+
+- [ ] **Step 2: 실패/현황 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ai/services/insta-render && python -m pytest tests/test_worker.py::test_render_produces_nonempty_1080x1350 -v`
+  Expected: 현재 코드로도 통과할 수 있으나(렌더 자체는 동작), 폰트/검증 보강 전이므로 FAIL이 아니면 다음 Step에서 검증 로직 추가가 의미를 갖도록 진행. (Playwright/Chromium 미설치 환경이면 `playwright install chromium` 필요 — 안 되면 DONE_WITH_CONCERNS로 보고)
+
+- [ ] **Step 3: card_renderer 보강** — `_render_slate_locked`의 페이지 루프에서 `page.goto` 직후·`screenshot` 직전에 폰트 대기 추가, screenshot 후 비어있음 검증:
+```python
+            try:
+                await page.goto(f"file://{html_path}", wait_until="networkidle")
+                await page.evaluate("document.fonts.ready")   # 웹폰트 로딩 완료까지 대기
+                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)
+                if os.path.getsize(out_path) < 1000:          # 빈/깨진 PNG 방어
+                    raise RuntimeError(f"rendered PNG too small: {out_path}")
+                paths.append(out_path)
+            finally:
+                ...
+```
+
+- [ ] **Step 4: 통과 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ai/services/insta-render && python -m pytest tests/test_worker.py -v` Expected: PASS
+
+- [ ] **Step 5: Commit (web-ai repo)**
+```bash
+cd /c/Users/jaeoh/Desktop/workspace/web-ai && git add services/insta-render/card_renderer.py services/insta-render/tests/test_worker.py && git commit -m "fix(insta-render): fonts.ready 대기 + PNG 비어있음 검증 (렌더 known-issue 해결)"
+```
+
+---
+
+# Phase 3 — 카피 글자수 가이드 (insta-lab)
+
+## Task 3.1: card_writer 프롬프트에 글자수 상한 추가
+
+**Files:**
+- Modify: `web-backend/insta-lab/app/card_writer.py` (`DEFAULT_PROMPT`)
+- Test: `web-backend/insta-lab/app/test_card_writer_prompt.py` (NEW)
+
+- [ ] **Step 1: 실패 테스트**
+
+`insta-lab/app/test_card_writer_prompt.py`:
+```python
+from app import card_writer
+
+def test_default_prompt_has_length_guidance():
+    p = card_writer.DEFAULT_PROMPT
+    # 글자수 가이드가 프롬프트에 포함됐는지
+    assert "22자" in p and "120자" in p
+    # 포맷 placeholder는 유지
+    assert "{category}" in p and "{keyword}" in p and "{articles}" in p
+```
+
+- [ ] **Step 2: 실패 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-backend/insta-lab && python -m pytest app/test_card_writer_prompt.py -v` Expected: FAIL
+
+- [ ] **Step 3: DEFAULT_PROMPT에 가이드 추가** — `DEFAULT_PROMPT` 문자열의 JSON 스키마 안내 뒤(닫는 `}}` 다음)에 글자수 가이드 문단 추가:
+```python
+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", ...]
+}}
+
+[글자수 제약 — 카드 디자인 박스에 맞게 반드시 준수]
+- cover_copy.headline: 22자 이내
+- body_copies[].headline: 26자 이내
+- body_copies[].body: 120자 이내 (2~4문장)
+- cta_copy.headline: 22자 이내
+초과하면 잘리므로 간결하고 임팩트 있게 작성한다.
+"""
+```
+
+- [ ] **Step 4: 통과 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-backend/insta-lab && python -m pytest app/test_card_writer_prompt.py -v` Expected: PASS
+
+- [ ] **Step 5: Commit (insta-lab)**
+```bash
+cd /c/Users/jaeoh/Desktop/workspace/web-backend && git add insta-lab/app/card_writer.py insta-lab/app/test_card_writer_prompt.py && git commit -m "feat(insta-lab): card_writer 프롬프트에 글자수 가이드(오버플로우 예방)"
+```
+> 주의: 운영 DB에 `slate_writer` prompt_template 오버라이드가 있으면 DEFAULT_PROMPT 대신 그게 쓰임 → 배포 후 필요 시 `PUT /api/insta/templates/prompts/slate_writer`로 동일 가이드 반영(plan §검증에서 안내).
+
+---
+
+# Phase 4 — zip 패키지 다운로드 API (insta-lab)
+
+## Task 4.1: GET /api/insta/slates/{id}/package
+
+**Files:**
+- Modify: `web-backend/insta-lab/app/main.py` (엔드포인트 추가)
+- Test: `web-backend/insta-lab/app/test_package_api.py` (NEW)
+
+- [ ] **Step 1: (확인됨) asset 스키마** — `card_assets(slate_id, page_index, file_path, file_hash)`. `db.list_card_assets(slate_id)` → 각 row에 `file_path`·`page_index`. `db.add_card_asset(slate_id, page_index, file_path, file_hash="")`. `db.add_card_slate(row: dict)`. 기존 `/assets/{page}`는 `FileResponse(match["file_path"], media_type="image/png")`. zip 엔드포인트는 동일하게 `a["file_path"]`를 읽는다.
+
+- [ ] **Step 2: 실패 테스트**
+
+`insta-lab/app/test_package_api.py`:
+```python
+import io, os, tempfile, zipfile, sys
+from fastapi.testclient import TestClient
+
+def _client(monkeypatch):
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+    from app import config, db
+    tmp = tempfile.mkdtemp()
+    monkeypatch.setattr(config, "INSTA_DATA_PATH", tmp, raising=False)
+    monkeypatch.setattr(db, "DB_PATH", os.path.join(tmp, "insta.db"), raising=False)
+    db.init_db()
+    from app.main import app
+    return TestClient(app), db, tmp
+
+def test_package_zip_contains_pngs_and_caption(monkeypatch):
+    client, db, tmp = _client(monkeypatch)
+    # 슬레이트 + 2개 asset(실제 PNG 파일) 시드
+    sid = db.add_card_slate({"keyword":"k","category":"economy","status":"rendered",
+        "cover_copy":{"headline":"h"}, "body_copies":[{"headline":"b","body":"x"}]*8,
+        "cta_copy":{}, "suggested_caption":"캡션입니다", "hashtags":["#a","#b"]})
+    cards_dir = os.path.join(tmp, "insta_cards", str(sid)); os.makedirs(cards_dir, exist_ok=True)
+    for pg in (1,2):
+        fp = os.path.join(cards_dir, f"{pg:02d}.png")
+        with open(fp, "wb") as f: f.write(b"\x89PNG\r\n" + b"0"*2000)
+        db.add_card_asset(slate_id=sid, page_index=pg, file_path=fp)
+    r = client.get(f"/api/insta/slates/{sid}/package")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "application/zip"
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    names = z.namelist()
+    assert any(n.endswith(".png") for n in names)
+    assert "caption.txt" in names
+    cap = z.read("caption.txt").decode("utf-8")
+    assert "캡션입니다" in cap and "#a" in cap
+```
+> `db.add_card_slate`/`add_card_asset`/`list_card_assets`의 실제 시그니처·컬럼명은 db.py 확인 후 맞출 것. asset 경로 컬럼이 `path`가 아니면 테스트·구현 모두 조정.
+
+- [ ] **Step 3: 실패 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-backend/insta-lab && python -m pytest app/test_package_api.py -v` Expected: FAIL (404)
+
+- [ ] **Step 4: 엔드포인트 구현** — `insta-lab/app/main.py`에 추가 (`/assets/{page}` 엔드포인트 근처, 동일한 asset 파일경로 접근 방식 사용. `import io, zipfile`은 상단에 추가):
+```python
+@app.get("/api/insta/slates/{slate_id}/package")
+def download_package(slate_id: int):
+    slate = db.get_card_slate(slate_id)
+    if not slate:
+        raise HTTPException(404, "slate not found")
+    assets = sorted(db.list_card_assets(slate_id), key=lambda a: a["page_index"])
+    if not assets:
+        raise HTTPException(409, "아직 렌더된 카드가 없습니다")
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        for a in assets:
+            fp = a["file_path"]
+            if os.path.exists(fp):
+                z.write(fp, arcname=f"{a['page_index']:02d}.png")
+        caption = (slate.get("suggested_caption") or "").strip()
+        tags = slate.get("hashtags") or []
+        if isinstance(tags, str):
+            import json as _json
+            try: tags = _json.loads(tags)
+            except Exception: tags = []
+        caption_full = caption + ("\n\n" + " ".join(tags) if tags else "")
+        z.writestr("caption.txt", caption_full)
+    buf.seek(0)
+    from fastapi.responses import StreamingResponse
+    return StreamingResponse(buf, media_type="application/zip", headers={
+        "Content-Disposition": f'attachment; filename="insta_slate_{slate_id}.zip"'})
+```
+> `HTTPException`/`os`는 main.py에 이미 import됨. `slate.get("hashtags")`가 JSON 문자열일 수 있어 방어 파싱.
+
+- [ ] **Step 5: 통과 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-backend/insta-lab && python -m pytest app/test_package_api.py -v` Expected: PASS
+
+- [ ] **Step 6: Commit (insta-lab)**
+```bash
+cd /c/Users/jaeoh/Desktop/workspace/web-backend && git add insta-lab/app/main.py insta-lab/app/test_package_api.py && git commit -m "feat(insta-lab): 슬레이트 zip 패키지 다운로드 API (10 PNG + caption.txt)"
+```
+
+---
+
+# Phase 5 — web-ui 패키지 다운로드 버튼 (별도 repo: web-ui)
+
+## Task 5.1: 슬레이트 상세에 다운로드 버튼
+
+**Files:**
+- Modify: `web-ui/src/api.js` (헬퍼)
+- Modify: insta 카드 페이지 (`web-ui/src/pages/insta/InstaCards.jsx` 또는 슬레이트 상세 컴포넌트)
+
+- [ ] **Step 1: 구조 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ui && git checkout -b feat/insta-package-download && grep -rln "insta\|슬레이트\|slate" src/pages/insta/ src/api.js 2>/dev/null | head` 로 슬레이트 상세 UI + apiGet 패턴 확인.
+
+- [ ] **Step 2: api.js 헬퍼 + 다운로드** — `src/api.js`에 패키지 URL 헬퍼 추가(파일 다운로드는 새 탭/anchor로):
+```javascript
+export const instaPackageUrl = (slateId) => `/api/insta/slates/${slateId}/package`;
+```
+슬레이트 상세 컴포넌트에 버튼 추가 (기존 버튼 스타일 맞춤):
+```jsx
+<a className="insta-pkg-btn" href={instaPackageUrl(slate.id)} download>
+  📦 패키지 다운로드 (10장 + 캡션)
+</a>
+```
+> import에 `instaPackageUrl` 추가. 실제 슬레이트 객체의 id 필드명·버튼 클래스는 Step 1 확인 결과에 맞출 것.
+
+- [ ] **Step 3: 빌드 확인** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ui && npm run build` Expected: exit 0
+
+- [ ] **Step 4: Commit (web-ui repo)**
+```bash
+cd /c/Users/jaeoh/Desktop/workspace/web-ui && git add src/ && git commit -m "feat: 인스타 슬레이트 패키지 다운로드 버튼"
+```
+
+---
+
+# Phase 6 — 통합 검증
+
+## Task 6.1: 회귀 + 배포 안내
+
+- [ ] **Step 1: insta-lab 테스트** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-backend/insta-lab && python -m pytest app/ -q` (Playwright 의존 테스트는 web-ai에만 있음). 신규 통과 + 회귀 없음. (`_shared` import로 main 로드 시 PYTHONPATH 필요하면 test에 sys.path.insert 적용 — Phase 4 test가 이미 처리)
+- [ ] **Step 2: web-ai 테스트** — Run: `cd /c/Users/jaeoh/Desktop/workspace/web-ai/services/insta-render && python -m pytest -q` (Chromium 필요; 미설치 시 `playwright install chromium`).
+- [ ] **Step 3: 배포 안내** — 3 repo 각각 push/배포:
+  - insta-lab: `git push origin main` → webhook 자동배포(NAS).
+  - web-ai: Windows 머신에서 워커 repo pull + 재시작 (insta-render 서비스). **신규 템플릿이 워커 CARD_TEMPLATE_DIR에 반영돼야 효과 발생.**
+  - web-ui: `npm run release:nas`.
+  - 배포 후 슬레이트 1건 생성 → 카드 PNG 육안 확인(디자인 시스템 적용·폰트 정상) → `/package` zip 다운로드 확인. DB `slate_writer` 오버라이드 존재 시 글자수 가이드 반영.
+
+---
+
+## Self-Review 체크리스트 결과
+- **Spec 커버리지**: 디자인 시스템 템플릿(Task 1.1) / 렌더 견고화 fonts.ready+검증(2.1) / 카피 글자수 가이드(3.1) / zip 패키지(4.1) / web-ui 버튼(5.1) / 검증(6.1). known-issue(폰트·오버플로우)=2.1+템플릿 clamp. 모두 매핑.
+- **Placeholder**: 모든 코드 step에 실제 코드. db asset 컬럼명·web-ui 슬레이트 필드·워커 테스트 관례는 "Step에서 확인 후 맞춤" 명시(코드베이스 의존, 합리적). brand_handle 기본 빈칸(미설정 허용).
+- **타입 일관성**: 템플릿이 쓰는 spec 키(page_type/page_no/total_pages/headline/body/accent_color/cta)가 워커 `_build_pages` 산출과 일치. zip 엔드포인트가 쓰는 `list_card_assets`/`get_card_slate`/`suggested_caption`/`hashtags`는 기존 db/슬레이트 스키마와 일치(Step 1에서 asset 경로 컬럼명만 확인).
+- **3 repo 경로**: 각 Task에 repo별 cd + 커밋 분리 명시.

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,251 @@
+# insta-lab Trends 탭 설계 — 외부 트렌드 수집 + 카테고리 가중치
+
+작성일: 2026-05-16
+상태: 사용자 승인 대기 → writing-plans 진입 예정
+연관 문서: `2026-05-15-insta-agent-design.md` (insta-lab 기본 설계)
+
+## ⚠️ 변경 이력
+
+- **2026-05-17**: 본문에 `google_trends` source로 기재된 모든 항목은 **실제 구현에서 `youtube_trending`으로 교체됨**. Google Trends 비공식 endpoint 두 가지(`trendingsearches/daily/rss?geo=KR`, `/trends/api/dailytrends?...`)가 모두 404로 폐기되어 운영 호출이 빈 결과로 끝나는 문제 확인 → YouTube Data API v3 `videos.list?chart=mostPopular&regionCode=KR`로 source 대체. 이후 spec 본문을 읽을 때는 `google_trends` → `youtube_trending`, "Google Trends" → "YouTube 인기"로 치환 해석. 사유와 source 교체 시 동시 갱신 체크리스트: `feedback_external_data_sources.md`.
+
+---
+
+## 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 전체 통과

docs/superpowers/specs/2026-05-17-insta-design-importer-design.md

@@ -0,0 +1,294 @@
+# insta-lab Design Importer — Claude Vision으로 이미지 디자인 → Jinja HTML 자동 생성
+
+작성일: 2026-05-17
+상태: 사용자 승인 대기 → writing-plans 진입 예정
+연관 문서: `2026-05-15-insta-agent-design.md`, `2026-05-16-insta-trends-design.md`, `feedback_external_data_sources.md`
+
+---
+
+## 1. 목적·배경
+
+insta-lab의 카드 렌더는 현재 `templates/default/card.html.j2` 한 골격만 사용 (단순 그라데이션 + Noto Sans KR). 사용자가 직접 디자인한 10장 카드 이미지(`templates/minimal/pages/insta_card_*.png`)를 이미 NAS에 배포한 상태인데, 이 이미지들이 카드 렌더에 반영되지 않음.
+
+이 spec은 사용자가 만든 디자인 이미지를 **카드 렌더 파이프라인에 통합**하는 메커니즘을 정의한다. 핵심은 Claude Vision으로 10장 PNG를 분석해 페이지별 텍스트 영역·색·폰트·레이아웃을 도출하고, 이를 그대로 모방한 단일 Jinja2 HTML 파일을 자동 생성하는 것이다. 생성된 HTML은 동적 카피(headline, body, cta)를 사용자 디자인 위에 layer로 얹어 일관된 시각 + 동적 텍스트를 동시에 확보한다.
+
+---
+
+## 2. 스코프
+
+### 포함
+
+- 신규 백엔드 모듈 `insta-lab/app/design_importer.py` — 10장 PNG → Claude Sonnet Vision → `card.html.j2` 생성
+- CLI 진입점 `python -m app.design_importer <theme_name>` (운영자가 한 번씩 실행)
+- 환경변수 `INSTA_DEFAULT_THEME` 신규 (default="default") — 모든 슬레이트가 이 theme 사용
+- `card_renderer.render_slate`에 theme 전달 (기존 `template` 인자 활용, 호출자만 변경)
+- pytest: Vision 호출 mock + 출력 HTML 파싱 검증
+
+### 제외 (후속)
+
+- API endpoint `POST /api/insta/templates/import` — UI에서 트리거 가능
+- `card_slates.theme` 컬럼 — 슬레이트별 다른 theme 선택
+- 다중 theme 비교/A·B 테스트 UI
+- 자동 theme 추천 (트렌드 카테고리별 다른 theme)
+
+---
+
+## 3. 데이터·디렉토리 구조
+
+```
+insta-lab/app/templates/
+├── default/                          # 기존 — 폴백 / 초기 골격
+│   ├── card.html.j2
+│   └── .gitkeep
+└── <theme_name>/                     # 사용자 디자인 1세트 (반복 가능)
+    ├── pages/                        # 사용자가 git commit으로 업로드
+    │   ├── insta_card_start.png      # 의미 있는 이름 권장 (Claude가 페이지 의도 파악에 활용)
+    │   ├── insta_card_keyword.png
+    │   ├── ... (총 10장)
+    │   └── README.md (선택, 디자인 의도 메모)
+    └── card.html.j2                  # design_importer가 자동 생성
+```
+
+**파일명 컨벤션**:
+- 페이지 번호 매핑은 사용자가 제공하지 않음. design_importer가 다음 순서로 자동 매핑:
+  1. 파일명에 `cover` > `start` > `intro` 키워드 포함 (우선순위 순서) → page 1 (커버). 여러 파일이 매치되면 가장 앞 키워드를 가진 파일만 선택, 나머지는 본문 풀로
+  2. 파일명에 `cta` > `outro` > `finish` > `end` 키워드 포함 (우선순위 순서) → page 10. 동일하게 첫 매치만 page 10, 나머지는 본문 풀로
+  3. 남은 8장은 알파벳 정렬 순으로 page 2~9 (본문)
+- **현재 운영 케이스**: `insta_card_start.png`(start=1순위) → page 1, `insta_card_cta.png`(cta=1순위) → page 10, `insta_card_finish.png`는 finish=3순위인데 cta가 이미 page 10이므로 본문 풀로 떨어져 알파벳 순에 따라 page 2~9 어딘가 배치됨
+- 사용자가 매핑을 override하려면 `pages/_order.json` 파일에 `{"insta_card_start.png": 1, "insta_card_finish.png": 10, ...}` 명시 가능 (충돌·의도 명시 시 강력 권장)
+- 매핑이 의도와 어긋나면 importer 실행 결과 dict의 `page_mapping` 필드로 확인 후 `_order.json` 추가하고 재실행
+
+---
+
+## 4. 핵심 모듈 `design_importer.py`
+
+### 4-1. Public API
+
+```python
+def import_design_theme(theme_name: str) -> dict:
+    """templates/<theme>/pages/*.png 10장 → Claude Sonnet Vision → card.html.j2 생성.
+
+    Returns:
+        {
+            "theme_name": str,
+            "html_path": str,
+            "page_mapping": {filename: page_no, ...},
+            "analysis_summary": str,  # Claude가 도출한 디자인 분석 짧은 요약
+            "tokens_used": int,
+        }
+
+    Raises:
+        ValueError: pages/ 폴더에 PNG 10장 미만이거나 매핑 실패
+        anthropic.APIError: Vision 호출 실패 (retry 1회 후)
+    """
+```
+
+### 4-2. 처리 흐름
+
+1. `templates/<theme>/pages/` 폴더 스캔 → PNG 10장 검증 (10장 정확히)
+2. 파일명 → 페이지 매핑 결정 (3장 규칙 + 선택적 `_order.json` override)
+3. 각 PNG base64 인코딩
+4. Claude Sonnet(`claude-sonnet-4-6`) Vision 호출 1회:
+   - 시스템 프롬프트: 디자이너 역할 + 출력 형식 명세
+   - 사용자 메시지: 10장 이미지 + 페이지 매핑 정보 + 변수 명세 (`page_no`, `headline`, `body`, `cta`)
+   - 출력 요청: 단일 Jinja2 HTML 파일 (page_no 분기 + 텍스트 영역 절대 위치 CSS + `background-image: url('pages/{{filename}}')`)
+5. 응답 HTML 파싱 + Jinja Environment로 sanity render 1회 (분기·문법 검증)
+6. `templates/<theme>/card.html.j2`에 저장
+7. dict 반환
+
+### 4-3. Vision 프롬프트 스킴 (placeholder 텍스트 마스킹 포함)
+
+**중요 제약**: 사용자 PNG에는 **placeholder 텍스트가 이미 박혀있다**. 동적 카피(headline, body, cta)로 교체해야 하며 원본 placeholder 텍스트는 보이면 안 된다. 따라서 단순히 텍스트 layer를 얹는 것만으로는 부족하고, 원본 텍스트가 있던 영역을 그 영역의 **배경색으로 덮은 후** 그 위에 새 텍스트를 그려야 한다.
+
+시스템 프롬프트 (요약):
+```
+너는 인스타그램 카드 뉴스 디자인을 모방하는 프론트엔드 디자이너다.
+입력: 10장의 카드 디자인 이미지 (각 1080×1350, placeholder 텍스트 포함) + 페이지 번호 매핑.
+출력: 단일 Jinja2 HTML 파일.
+
+요구사항:
+- 컨테이너 width 1080px, height 1350px
+- background-image로 해당 페이지 PNG를 url('pages/{{filename}}')로 로드
+- 각 페이지에서 placeholder 텍스트가 있는 영역을 식별하고, 다음 두 layer를 그 위에 그린다:
+  (a) 마스킹 박스: position: absolute로 텍스트 영역과 같은 좌표·크기.
+      background는 PNG의 그 영역 주변 픽셀 색 (보통 카드 배경색)에서 추출.
+      placeholder가 완전히 가려지도록 padding 8px 정도 여유.
+  (b) 동적 텍스트 layer: 마스킹 박스와 동일 좌표.
+      font-size·font-weight·color는 원본 placeholder 폰트 스타일을 그대로 모방.
+      `{{ headline }}`, `{{ body }}`, `{{ cta }}` (page_no=10에서만) Jinja 변수 사용.
+- 페이지 종류별 영역 추정:
+  · page 1 (cover): 메인 헤드라인 1개 영역. 보통 화면 상단 1/3 또는 중앙
+  · page 2~9 (body): 헤드라인 1개 + 본문 1개 영역 (보통 헤드라인 상단, 본문 그 아래)
+  · page 10 (cta): 헤드라인 1개 + 본문 1개 + CTA 강조 텍스트 1개 영역
+- page_no 1~10 분기: {% if page_no == N %}...{% endif %} 구조
+- 폰트는 Noto Sans KR (Google Fonts CDN), letter-spacing -0.02em
+- 텍스트 영역은 word-wrap: break-word + overflow: hidden으로 길이 초과 시도 마스킹 박스 밖으로 새지 않게
+- 출력은 <!DOCTYPE html>로 시작하는 완전한 HTML 본문만 (```html 코드펜스·설명 텍스트 금지)
+```
+
+사용자 메시지에 각 이미지 + filename + page_no 매핑 포함.
+
+**시각 품질 보장 절차** (importer 운영 후 사용자 검증):
+1. 첫 import 후 1개 슬레이트 생성해서 PNG 10장 육안 확인
+2. placeholder 텍스트가 비치거나 마스킹 박스가 어색하면 — `card.html.j2`를 직접 수정해서 영역 좌표·색 fine-tune (백업 자동 보존)
+3. 새 디자인을 import할 일 있을 때까지는 수동 수정본 그대로 사용
+
+### 4-4. 캐시 / 재실행 정책
+
+- 이미 `card.html.j2`가 존재하면 덮어쓰기 (사용자 명시적 재import 의도)
+- 백업: 기존 HTML이 있으면 `card.html.j2.bak.YYYYMMDD-HHMMSS`로 rename 후 새 파일 작성
+- 분석 결과 캐시 X (재실행할 때마다 최신 결과)
+
+---
+
+## 5. CLI 진입점
+
+```bash
+# 컨테이너 내부에서 실행
+docker exec insta-lab python -m app.design_importer <theme_name>
+
+# 결과 stdout (예시)
+{
+  "theme_name": "minimal",
+  "html_path": "/app/app/templates/minimal/card.html.j2",
+  "page_mapping": {
+    "insta_card_start.png": 1,
+    "insta_card_keyword.png": 2,
+    ...
+    "insta_card_cta.png": 10
+  },
+  "analysis_summary": "미니멀 카드 — 흰 배경 + 검정 헤드라인 + 회색 본문...",
+  "tokens_used": 15234
+}
+```
+
+`__main__` 가드: argparse로 `theme_name` 위치 인자 + `--force` (기존 HTML 백업 없이 덮어쓰기) 옵션. 실패 시 exit 1.
+
+---
+
+## 6. 카드 렌더 통합
+
+### 6-1. 환경변수 추가 (`config.py`)
+
+```python
+INSTA_DEFAULT_THEME = os.getenv("INSTA_DEFAULT_THEME", "default")
+```
+
+### 6-2. `main.py:_bg_create_slate` 호출 변경
+
+기존:
+```python
+await card_renderer.render_slate(sid)
+```
+
+신규:
+```python
+template_path = f"{INSTA_DEFAULT_THEME}/card.html.j2"
+await card_renderer.render_slate(sid, template=template_path)
+```
+
+`card_renderer.render_slate`는 이미 `template` 인자를 받으며 default 값이 `"default/card.html.j2"`. 변경 없음.
+
+### 6-3. `card_renderer` 폴백 가드
+
+`render_slate` 시작부에 template 파일 존재 확인 추가:
+```python
+template_full = Path(_resolve_template_dir()) / template
+if not template_full.exists():
+    logger.warning("Template %s 없음, default로 폴백", template)
+    template = "default/card.html.j2"
+```
+
+→ env에 `INSTA_DEFAULT_THEME=minimal` 설정했는데 `minimal/card.html.j2`가 아직 import 안 됐으면 자동 default 폴백.
+
+### 6-4. 운영 활성화 절차
+
+```bash
+# 1. 이미지 commit + push (이미 완료 — minimal/pages/ 10장)
+# 2. NAS 머지 후 design_importer 실행
+docker exec insta-lab python -m app.design_importer minimal
+
+# 3. NAS .env에 추가
+echo "INSTA_DEFAULT_THEME=minimal" >> /volume1/docker/webpage/.env
+
+# 4. 컨테이너 재시작 (env 재로드)
+docker compose restart insta-lab
+```
+
+---
+
+## 7. 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| `pages/` 폴더 없음 또는 PNG 10장 미만 | ValueError + 어떤 파일이 빠졌는지 명시. 모든 이미지가 1080×1350인지도 검증 (Pillow로 size 체크) |
+| Vision 호출 실패 (network, rate limit) | retry 1회 (5초 대기), 그래도 실패 시 anthropic.APIError 전파 |
+| Vision 응답이 HTML이 아님 / Jinja 문법 깨짐 | Jinja Environment로 sanity render 시도 → 실패 시 raw 응답을 `card.html.j2.error.txt`에 저장 + ValueError 전파 (운영자가 수동 수정 가능) |
+| Vision 응답이 max_tokens(16K) 초과 → 잘림 | 응답 끝이 닫힌 `</html>` 없으면 잘렸다고 판단, max_tokens 24K로 retry 1회 |
+| 이미지 base64 인코딩 실패 (파일 깨짐) | 어느 파일이 문제인지 로그 + ValueError |
+| `_order.json` 형식 깨짐 | log warning + 자동 매핑 규칙으로 폴백 |
+
+---
+
+## 8. 테스트
+
+### `insta-lab/tests/test_design_importer.py` (~6 케이스)
+
+1. `test_auto_page_mapping_with_cover_and_cta`: 의미 이름 파일 10개 → cover→1, cta→10, 나머지 알파벳 순
+2. `test_explicit_order_json_overrides`: `_order.json` 있으면 그것 우선
+3. `test_validates_exactly_ten_pngs`: 9장 또는 11장이면 ValueError
+4. `test_validates_image_dimensions`: 1080×1350 아닌 이미지 있으면 ValueError + 어떤 파일인지
+5. `test_import_generates_html_via_mocked_claude`: Anthropic Vision mock, 응답 HTML이 Jinja 렌더 가능한 형식인지 검증
+6. `test_import_falls_back_on_jinja_parse_failure`: mock이 깨진 HTML 반환 시 ValueError + `.error.txt` 저장
+
+### `insta-lab/tests/test_card_renderer.py` (기존, 보강 1개)
+
+7. `test_render_falls_back_to_default_when_theme_html_missing`: `template="ghost/card.html.j2"` 지정 시 파일 없어도 default로 폴백 + 정상 PNG 생성
+
+---
+
+## 9. 운영 영향
+
+| 항목 | 영향 |
+|------|------|
+| Anthropic 토큰 비용 | +1회당 ~15K 토큰 (이미지 10장 × ~1K + 프롬프트 + HTML 출력). Claude Sonnet 단가 기준 ~$0.05/import. 자주 실행 X |
+| 빌드 시간 | 영향 없음 (코드 변경만, 의존성 추가 없음) |
+| 카드 렌더 시간 | 영향 없음 (Playwright는 background-image까지 wait_until="networkidle"로 처리) |
+| 디스크 | 사용자 디자인 PNG 12MB (이미 push됨) + 자동 생성 HTML ~10KB |
+| 운영 중 카드 품질 | env `INSTA_DEFAULT_THEME=minimal` 설정 후 다음 슬레이트부터 사용자 디자인 적용. 기존 슬레이트는 default 그대로 |
+
+---
+
+## 10. 마이그레이션 절차
+
+배포 후 사용자가 운영 NAS에서 수동 실행:
+
+1. PR 머지 → webhook으로 `design_importer.py` 코드 배포 + minimal/ 디렉토리는 이미 배포됨
+2. SSH NAS:
+   ```bash
+   docker exec insta-lab python -m app.design_importer minimal
+   ```
+3. 결과 JSON에서 `html_path`와 `page_mapping` 확인. 매핑이 의도와 다르면 `pages/_order.json`로 override 후 재실행
+4. `.env`에 `INSTA_DEFAULT_THEME=minimal` 추가
+5. `docker compose restart insta-lab` (env 재로드)
+6. 새 슬레이트 1개 만들어서 시각 검증 (Insta 페이지 Trends 탭 또는 수동 트리거)
+
+생성된 `card.html.j2`가 마음에 안 들면:
+- `pages/_order.json`으로 페이지 순서 조정 후 importer 재실행
+- 또는 자동 생성 HTML을 사용자가 직접 수정 (importer 재실행 안 함)
+- 백업본 `card.html.j2.bak.YYYYMMDD-HHMMSS`로 롤백 가능
+
+---
+
+## 11. 완료 정의
+
+- [ ] `insta-lab/app/design_importer.py` 작성, CLI `python -m app.design_importer` 작동
+- [ ] `_resolve_page_mapping` + 의미 이름 기반 자동 매핑 + `_order.json` override
+- [ ] Vision 호출 mock 기반 pytest 6 케이스 PASS
+- [ ] `card_renderer.render_slate`에 theme 폴백 가드 추가, 테스트 1 케이스 PASS
+- [ ] `insta-lab/app/config.py`에 `INSTA_DEFAULT_THEME` 추가
+- [ ] `insta-lab/app/main.py:_bg_create_slate`가 `INSTA_DEFAULT_THEME` 사용
+- [ ] `docker-compose.yml` insta-lab 환경변수에 `INSTA_DEFAULT_THEME=${INSTA_DEFAULT_THEME:-default}` 추가
+- [ ] CLAUDE.md 9.x insta-lab 섹션에 design_importer + INSTA_DEFAULT_THEME 항목 추가
+- [ ] 운영 NAS에서 `docker exec insta-lab python -m app.design_importer minimal` 실행 → `card.html.j2` 생성 확인
+- [ ] `.env` 설정 + 새 슬레이트 1개 생성 → 시각적으로 minimal 디자인 반영 확인

docs/superpowers/specs/2026-05-18-nas-windows-distributed-architecture-design.md

@@ -0,0 +1,584 @@
+# NAS ↔ Windows 분산 아키텍처 — Design Spec
+
+**Date:** 2026-05-18
+**Author:** CEO (with Claude)
+**Scope:** `web-backend` + `web-ai` + 신규 `web-ai-services` (Windows WSL2 컨테이너 모음)
+
+---
+
+## 1. 배경 & 목적
+
+NAS Synology J4025 (Celeron 2C/2.0GHz, 18GB)에서 11개 docker 컨테이너가 CPU를 과점유. 진단 결과 가장 큰 원인은 **외부 인바운드 API 호출 빈도** (web-ai signal_v1/v2가 분당 12회 NAS stock 호출) + **insta-lab Playwright Chromium의 동시 launch 비용**이었다.
+
+박재오 통찰: *"NAS = 24/7 표출·게이트웨이 / Windows = 트레이딩 메인 + 트리거 기반 컴퓨팅"*. 박재오가 이미 7건의 의사결정을 마쳤고 1주 셋업 가이드도 정리되어 있다 (`Obsidian Vault/raw/2026-05-18-Windows-NAS-아키텍처-7결정-통합.md`).
+
+본 spec은 그 위에 **실행 단위 분할(SP) + 의존성 그래프 + 통합 패턴 + 데이터 플로우**를 정리해서 실제 구현 plan으로 진입 가능한 형태로 만든다.
+
+### 박재오 7결정 (수용된 결정 사항)
+
+1. **d+b 조합** — Windows 작업 감지 큐 정지 + 트레이딩 우선순위 High
+2. **insta-lab Playwright 1순위** 이전 (NAS → Windows)
+3. **트리거 B(비동기) + C(예약)** — 즉시 응답 X, task_id 발급 + 폴링
+4. **외부 영상 생성 도구** (Runway·Sora·Veo·Pika·Kling·Luma)
+5. **Redis NAS 컨테이너** — 24/7 안정 큐
+6. **옵션 4 하이브리드** — 트레이딩 Native Python / 신규 WSL2 Docker Engine
+7. **NSSM** — Windows Service 도구 (자동 시작·우선순위)
+
+---
+
+## 2. 전체 아키텍처
+
+```
+[사용자 브라우저]
+   ↓ HTTPS
+[NAS Synology J4025] ─── 24/7 안정 · 표출 · 게이트웨이 · 상태(state)
+  ├─ frontend (nginx :8080)            React SPA
+  ├─ redis (:6379)            ⭐ NEW    24/7 큐 + 캐시
+  ├─ stock (:18500)            +TTLCache  메타 + KIS data + WebAI gateway
+  ├─ insta-lab (:18700)        분할 후   카피 생성 + DB + Redis push
+  ├─ music-lab (:18600)        분할 후   메타 + Redis push (Suno/MusicGen 미실행)
+  ├─ video-lab (:18XXX)       ⭐ NEW    영상 게이트웨이 + Redis push
+  ├─ agent-office (:18900)              텔레그램 라우팅 + scheduler
+  ├─ lotto / realestate-lab / personal / packs-lab / travel-proxy
+  └─ deployer (:19010)
+                              ↓ Redis BLPOP / 직접 HTTP webhook
+[Windows AI Server 192.168.45.59] ─── 트레이딩 최우선 · 트리거 컴퓨팅
+  ├─ 🔵 Native Python (NSSM HIGH priority)
+  │   ├─ signal_v2 (:8001)    ⭐ 트레이딩 절대 우선
+  │   ├─ Ollama qwen3:14b (:11435)
+  │   └─ MusicGen (:8765)
+  └─ 🟢 WSL2 + Docker Engine (NORMAL priority)
+      ├─ insta-render (:18710)  ⭐ NEW   Playwright Chromium pool
+      ├─ music-render (:18711)  ⭐ NEW   Suno API + MusicGen orchestration
+      ├─ video-render (:18712)  ⭐ NEW   외부 영상 API gateway (6 provider)
+      └─ task-watcher                   박재오 작업 감지 + 시간대 분기
+```
+
+### 핵심 원칙
+
+1. **NAS = state(DB) + view(nginx 미디어 서빙)**, **Windows = stateless compute**
+2. **트레이딩 절대 우선** — 시간대 조건부 (아래 §3 참조)
+3. **무거운 작업 시간대 분리** — 데드존 23:30–04:30 + 주말·휴장일 = 골든타임
+
+---
+
+## 3. 시간대별 우선순위 모드
+
+| 모드 | 조건 | signal_v2 | task-watcher 정책 |
+|------|------|-----------|------------------|
+| 🔴 트레이딩 | 평일 비휴장일 07:00–16:30 | NSSM HIGH, polling 활성 | 박재오 활동 감지 시 `queue:paused` SET |
+| 🟡 일반 | 평일 16:30–23:30 (NXT) | NSSM HIGH 유지 (5분 폴링 가벼움) | 박재오 활동 감지 시 SET |
+| 🟢 자유 | 주말·휴장일 + 평일 23:30–04:30 | 자동 idle (휴장일 polling 미실행) | `queue:paused` DEL 유지 — 큐 항상 활성 |
+
+### 구현 위치
+- **signal_v2의 휴장일 인식**: `web-ai` CHECK_POINT #7 `holidays.json` 자동 동기화 항목. 휴장일·주말에 polling 자체 미실행.
+- **휴장일 단일 소스**: `web-backend/stock/app/holidays.json` 정본. NAS stock이 `GET /api/stock/holidays`로 노출. signal_v2 + task-watcher가 매일 00:00 갱신.
+- **task-watcher 시간대 분기**: `current_mode()` 함수가 30초 폴링마다 모드 판정 → `queue:paused` 토글.
+
+---
+
+## 4. Sub-project 카탈로그 (12개)
+
+| SP | 명칭 | 트랙 | 위치 | 소요 |
+|----|------|------|------|------|
+| **SP-A1** | web-ai 캐시 TTL 증가 | A | `web-ai/signal_v2/stock_client.py` | 10분 |
+| **SP-A2** | NAS stock TTLCache | A | `web-backend/stock/app/*` | 30분 |
+| **SP-1** | NAS Redis 컨테이너 | B (Base) | `web-backend/docker-compose.yml` | 30분 |
+| **SP-2** | Windows WSL2 + Docker Engine | B (Base) | (Windows AI) | 2h |
+| **SP-3** | insta-render Windows 서비스 | B | `web-ai-services/insta-render/` (신규) | 4h |
+| **SP-4** | NAS insta-lab 분할 | B | `web-backend/insta-lab` | 2h |
+| **SP-5** | music-render Windows 서비스 | B | `web-ai-services/music-render/` (신규) | 3h |
+| **SP-6** | NAS music-lab 분할 | B | `web-backend/music-lab` | 2h |
+| **SP-7** | video-render Windows 서비스 | B | `web-ai-services/video-render/` (신규) | 3h |
+| **SP-8** | NAS video-lab 신설 | B | `web-backend/video-lab/` (신규 컨테이너) | 2h |
+| **SP-9** | NSSM 자동 시작 + 우선순위 | B | (Windows) | 1h |
+| **SP-10** | task-watcher (시간대 + 활동 감지) | B | `web-ai-services/task-watcher/` (신규) | 2h |
+
+**총 작업시간**: ~22.5h (1주 일정에 부합)
+
+### 의존성 그래프
+
+```
+A 트랙 (병행, ~40분)
+  SP-A1 ─╮
+         ├── V2 재시작 시 효과
+  SP-A2 ─╯
+
+B 트랙 Base (Day 1~2)
+  SP-1 (Redis) ─┐
+                ├── 인스타·음악·영상 3 트랙 모두 의존
+  SP-2 (WSL2) ──┘
+
+인스타 트랙 (Day 3~4)
+  SP-3 (insta-render) ──→ SP-4 (NAS insta-lab 분할)
+
+음악 트랙 (Day 4~5)
+  SP-5 (music-render) ──→ SP-6 (NAS music-lab 분할)
+
+영상 트랙 (Day 5~6)
+  SP-7 (video-render) ──→ SP-8 (NAS video-lab 신설)
+
+인프라 마무리 (Day 6~7)
+  SP-9 (NSSM) ──→ SP-10 (task-watcher)
+```
+
+### Critical Path
+`SP-1 ∥ SP-2` → `SP-3` → `SP-4` → `SP-9` → `SP-10` (최단 약 11.5h)
+
+병렬화: SP-1(NAS)·SP-2(Windows)는 다른 머신이라 동시 진행. 인스타·음악·영상 트랙은 패턴이 같아 한 번 정착 후 빠르게 복제.
+
+---
+
+## 5. 통합 패턴 — "Windows Render Worker"
+
+인스타·음악·영상 3 트랙이 **완전히 같은 패턴**. 한 번만 정의하고 3번 재사용한다.
+
+### 시퀀스
+
+```
+사용자 ─POST /api/{kind}/generate ...──→ NAS {kind}-lab
+                                            │
+                                            ├─ DB.create_task() → task_id
+                                            ├─ Redis RPUSH queue:{kind}-render {task_id, params, ...}
+                                            └─ 200 {task_id}                          ─→ 사용자
+                                            
+                                        [Windows {kind}-render]
+                                            │ (queue:paused 체크 후 BLPOP queue:{kind}-render)
+                                            │
+                                            ├─ POST /api/internal/{kind}/update
+                                            │  {status: "processing", progress: 30}    ─→ NAS DB update
+                                            │
+                                            ├─ 무거운 작업 (Playwright / Suno / Runway 등)
+                                            │   결과 파일 → /mnt/nas/data/{kind}/{id}/{file}  (SMB direct write)
+                                            │
+                                            └─ POST /api/internal/{kind}/update
+                                               {status: "succeeded", progress: 100,
+                                                result_path: "/media/{kind}/{id}/{file}"} ─→ NAS DB update
+
+사용자 ─GET /api/{kind}/tasks/{task_id}──→ NAS {kind}-lab
+                                            └─ DB.get_task() → {status, progress, result_path}
+                                                                                       ─→ 사용자 (폴링)
+```
+
+### 4가지 미세 개선 (반영됨)
+
+1. **결과물 저장**: SMB direct write (`/mnt/nas/data/`) — 별도 HTTP upload 단계 제거
+2. **NAS 알림**: Windows → NAS internal webhook (`POST /api/internal/{kind}/update`) — NAS polling 부담 0
+3. **사용자 응답**: 폴링 유지 (YAGNI, 미래 SSE 검토)
+4. **인증 키 분리**: `X-WebAI-Key`(read, web-ai→NAS) vs `X-Internal-Key`(write, Windows→NAS)
+
+---
+
+## 6. Redis 키 컨벤션
+
+| 키 | 종류 | TTL | 용도 |
+|----|------|-----|------|
+| `queue:insta-render` | list | (없음) | 인스타 카드 렌더 작업 큐 |
+| `queue:music-render` | list | (없음) | 음악 생성 작업 큐 |
+| `queue:video-render` | list | (없음) | 영상 생성 작업 큐 |
+| `queue:paused` | string `"1"` | 600s | task-watcher가 set/del. worker가 BLPOP 전 확인 |
+| (옵션) `cache:stock:*` | string (json) | 120~600s | NAS stock Redis 캐시 (SP-A2와 별개 옵션) |
+
+### 큐 payload 표준 (JSON)
+
+```json
+{
+  "task_id": "uuid-...",
+  "kind": "insta|music|video",
+  "params": { ... },
+  "submitted_at": "2026-05-18T08:30:00+09:00"
+}
+```
+
+Worker는 `BLPOP queue:{kind}-render` (1초 timeout) → `queue:paused` 체크 → 처리.
+
+---
+
+## 7. NAS 볼륨 레이아웃 + nginx 서빙
+
+### 실 파일 시스템
+```
+/volume1/docker/webpage/data/
+├── insta/{slate_id}/01.png ~ 10.png
+├── music/{track_id}/{file}.mp3
+└── video/{video_id}/{file}.mp4
+```
+
+### WSL2 마운트
+```bash
+# WSL2 /etc/fstab
+//gahusb.synology.me/docker/webpage/data /mnt/nas cifs username=...,vers=3.0,uid=1000,_netdev 0 0
+```
+
+### nginx 서빙
+```
+https://gahusb.synology.me/media/insta/{id}/01.png
+                          /music/{id}/...
+                          /video/{id}/...
+```
+
+→ nginx `location /media/` 블록은 `/volume1/docker/webpage/data/`를 alias로 서빙 (기존 패턴).
+
+---
+
+## 8. NAS internal webhook 명세
+
+### Endpoint
+`POST /api/internal/{kind}/update` (kind ∈ `insta`|`music`|`video`)
+
+### 인증 — 3-layer 차단
+1. **nginx IP 화이트리스트** (Layer 1·2):
+   ```nginx
+   location /api/internal/ {
+       allow 192.168.45.0/24;     # LAN 화이트리스트
+       allow 100.64.0.0/10;       # Tailscale CGNAT 대역
+       deny all;
+       ...
+   }
+   ```
+2. **`X-Internal-Key` 헤더 검증** (Layer 3): `verify_internal_key` dependency
+
+### Payload
+```json
+{
+  "task_id": "uuid-...",
+  "status": "processing|succeeded|failed",
+  "progress": 0-100,
+  "result_path": "/media/insta/123/01.png",     // succeeded일 때만, nginx 경로
+  "error": "exception message"                    // failed일 때만
+}
+```
+
+### NAS 측 처리
+1. `tasks` 테이블 row update (status, progress, result_path, error)
+2. (옵션) Redis PUBLISH `task:{id}` — 미래 SSE 통합 시 활용
+3. 200 응답 (또는 401 if invalid key)
+
+### 인증 키 정책
+
+| 키 | 방향 | 권한 | 위치 |
+|----|------|------|------|
+| `X-WebAI-Key` | web-ai → NAS | read-only (`GET /api/webai/*`) | NAS `.env` + web-ai `.env` |
+| `X-Internal-Key` | Windows worker → NAS | write-only (`POST /api/internal/*`) | NAS `.env` + Windows `.env` |
+
+분리 사유: Principle of Least Privilege, 독립 로테이션, 감사 로그 명확성.
+
+### 인증 helper (NAS 공통 모듈, `web-backend/_shared/auth.py` 또는 각 컨테이너 복제)
+
+```python
+from fastapi import Header, HTTPException
+import os
+
+async def verify_internal_key(x_internal_key: str = Header(...)):
+    expected = os.getenv("INTERNAL_API_KEY")
+    if not expected or x_internal_key != expected:
+        raise HTTPException(401, "Invalid X-Internal-Key")
+
+# 라우터 사용
+@app.post("/api/internal/insta/update", dependencies=[Depends(verify_internal_key)])
+async def insta_update(payload: InternalUpdate): ...
+```
+
+기존 `verify_webai_key` 패턴(메모리 `reference_webai_auth_pattern.md`)을 복제.
+
+---
+
+## 9. Suno + 외부 영상 API 키 이전
+
+NAS `.env`에서 다음 키들을 **제거** → Windows `.env`로 이전:
+
+| 키 | NAS 이전 | Windows 이후 |
+|-----|---------|-------------|
+| `SUNO_API_KEY` | music-lab | music-render |
+| `RUNWAY_API_KEY` | (없음) | video-render |
+| `OPENAI_API_KEY` (Sora) | (있을 수도) | video-render |
+| `GEMINI_API_KEY` (Veo) | (없음) | video-render |
+| `PIKA_API_KEY` / `KLING_API_KEY` / `LUMA_API_KEY` | (없음) | video-render |
+
+→ NAS music-lab + video-lab은 외부 API 호출 코드를 가지지 않음. Redis push만.
+
+---
+
+## 10. SP 상세 명세
+
+### SP-A1 — web-ai 캐시 TTL 증가 (10분)
+
+**파일**: `web-ai/signal_v2/stock_client.py`
+
+변경:
+```python
+# 변경 전
+PORTFOLIO_TTL = 60
+NEWS_TTL      = 300
+SCREENER_TTL  = 60
+
+# 변경 후
+PORTFOLIO_TTL = 180   # 3분
+NEWS_TTL      = 600   # 10분
+SCREENER_TTL  = 300   # 5분
+```
+
+**효과**: 분당 12 → 3~4 호출 (~70% 감소), 캐시 hit ratio 0~50% → 66~80%
+
+### SP-A2 — NAS stock TTLCache (30분)
+
+**파일**: `web-backend/stock/app/*` (webai endpoint 위치 확인 후)
+
+```python
+from cachetools import TTLCache
+
+_PORTFOLIO_CACHE = TTLCache(maxsize=1, ttl=120)
+_NEWS_CACHE      = TTLCache(maxsize=10, ttl=600)
+_SCREENER_CACHE  = TTLCache(maxsize=10, ttl=180)
+
+@app.get("/api/webai/portfolio", dependencies=[Depends(verify_webai_key)])
+async def portfolio():
+    if "result" in _PORTFOLIO_CACHE:
+        return _PORTFOLIO_CACHE["result"]
+    result = await compute_portfolio()
+    _PORTFOLIO_CACHE["result"] = result
+    return result
+```
+
+3 endpoint 적용: `/api/webai/portfolio` · `/api/webai/news-sentiment` · `/api/stock/screener/run`. `cachetools` 의존성 requirements.txt 확인.
+
+**효과**: V1+V2 동시 호출도 NAS에서 1회 계산. KIS·LLM 재호출 방지.
+
+### SP-1 — NAS Redis 컨테이너 (30분)
+
+**파일**: `web-backend/docker-compose.yml`에 추가
+
+```yaml
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    volumes:
+      - ${RUNTIME_PATH}/redis-data:/data
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+```
+
+검증: `docker exec redis redis-cli PING` → `PONG`
+
+### SP-2 — Windows WSL2 + Docker Engine + Tailscale (2h)
+
+박재오 Windows AI Server에서 (관리자 PowerShell):
+
+```powershell
+wsl --install -d Ubuntu-22.04
+# 재부팅 후
+wsl -d Ubuntu-22.04
+```
+
+WSL2 안:
+```bash
+# Docker Engine
+sudo apt update && sudo apt install -y ca-certificates curl gnupg
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
+  sudo tee /etc/apt/sources.list.d/docker.list
+sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+sudo usermod -aG docker $USER
+
+# Tailscale
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+
+# NAS SMB mount
+sudo mkdir -p /mnt/nas
+echo "//gahusb.synology.me/docker/webpage/data /mnt/nas cifs username=...,vers=3.0,uid=1000,_netdev 0 0" | sudo tee -a /etc/fstab
+sudo mount -a
+```
+
+검증: `docker ps`, `tailscale status`, `ls /mnt/nas`
+
+### SP-3 — insta-render Windows 서비스 (4h)
+
+**디렉토리**: `C:\Users\jaeoh\Desktop\workspace\web-ai-services\insta-render\`
+
+```
+insta-render/
+├── Dockerfile
+├── docker-compose.yml
+├── requirements.txt
+├── .env
+├── main.py
+├── worker.py
+└── card_renderer.py    # 기존 NAS insta-lab/app/card_renderer.py 이식
+```
+
+핵심 로직:
+- `worker.py`: Redis BLPOP `queue:insta-render` (paused 체크)
+- `card_renderer.py`: Browser pool (`init_browser`/`shutdown_browser`) + `render_slate`
+- `main.py`: 시작 시 browser init + worker async task spawn
+- 완료 시 `/mnt/nas/data/insta/{slate_id}/` 저장 + NAS webhook `POST /api/internal/insta/update`
+
+### SP-4 — NAS insta-lab 분할 (2h)
+
+**파일**: `web-backend/insta-lab/app/main.py` + `app/card_renderer.py`
+
+변경:
+```python
+# 변경 전 — NAS에서 직접 렌더
+async def _bg_render(task_id: str, slate_id: int):
+    async with RENDER_SEMAPHORE:
+        await card_renderer.render_slate(slate_id, ...)
+
+# 변경 후 — Redis 큐에 push만
+import redis.asyncio as aioredis
+redis_client = aioredis.from_url(os.getenv("REDIS_URL", "redis://redis:6379"))
+
+async def _bg_render(task_id: str, slate_id: int):
+    payload = {"task_id": task_id, "kind": "insta",
+               "params": {"slate_id": slate_id, "theme": "hedgy75"},
+               "submitted_at": datetime.now(KST).isoformat()}
+    await redis_client.rpush("queue:insta-render", json.dumps(payload))
+```
+
+추가: `POST /api/internal/insta/update` endpoint (Windows webhook 수신).
+삭제: `card_renderer.py` Playwright 코드 (Browser pool, Semaphore 등), `requirements.txt`에서 `playwright` 제거, Dockerfile에서 Chromium install 제거.
+
+### SP-5 — music-render Windows 서비스 (3h)
+
+**디렉토리**: `web-ai-services/music-render/`
+
+- Suno API client (외부 SaaS, polling 1~5분)
+- MusicGen local call (Windows localhost:8765)
+- Redis BLPOP `queue:music-render`
+- 결과 mp3 → `/mnt/nas/data/music/{track_id}/{file}.mp3`
+- NAS webhook `POST /api/internal/music/update`
+
+`SUNO_API_KEY` Windows `.env`에 단독 보관.
+
+### SP-6 — NAS music-lab 분할 (2h)
+
+Suno 호출 코드 + MusicGen 호출 코드 삭제. `_bg_generate` 함수를 Redis push로 변경. `POST /api/internal/music/update` endpoint 추가.
+
+### SP-7 — video-render Windows 서비스 (3h)
+
+**디렉토리**: `web-ai-services/video-render/`
+
+6 provider gateway (Runway·Sora·Veo·Pika·Kling·Luma) — provider 선택은 payload에서. 각 외부 API 호출 + 결과 mp4 다운로드 → `/mnt/nas/data/video/{id}/`. NAS webhook.
+
+### SP-8 — NAS video-lab 신설 (2h)
+
+새 docker 컨테이너. `web-backend/video-lab/`:
+- `app/main.py`: 2 endpoint
+  - `POST /api/video/generate` → Redis push `queue:video-render` + task_id 반환
+  - `GET /api/video/tasks/{id}` → DB 조회
+- `app/db.py`: video_tasks 테이블 (sqlite)
+- `POST /api/internal/video/update` (Windows webhook)
+- Dockerfile, requirements, docker-compose.yml entry
+
+매우 가벼움 (NAS CPU 부담 미미).
+
+### SP-9 — NSSM 자동 시작 + 우선순위 (1h)
+
+Windows AI에서 NSSM 다운로드 후:
+
+```powershell
+# 트레이딩 (Native, HIGH)
+nssm install signal_v2 "C:\Python312\python.exe" "-m uvicorn main:app --host 0.0.0.0 --port 8001"
+nssm set signal_v2 AppDirectory "C:\Users\jaeoh\Desktop\workspace\web-ai\signal_v2"
+nssm set signal_v2 Priority HIGH_PRIORITY_CLASS
+nssm set signal_v2 AppStartup AUTO
+
+# WSL2 Docker (NORMAL)
+nssm install wsl_docker "wsl" "-d Ubuntu-22.04 -- sudo service docker start && cd /workspace/web-ai-services && docker compose up -d"
+nssm set wsl_docker Priority NORMAL_PRIORITY_CLASS
+nssm set wsl_docker AppStartup AUTO
+
+nssm start signal_v2
+nssm start wsl_docker
+```
+
+### SP-10 — task-watcher (2h)
+
+**디렉토리**: `web-ai-services/task-watcher/`
+
+WSL2 Docker 컨테이너. 30초마다:
+1. `current_mode()` 판정 (시간대 + holidays.json 체크 + KST 시각)
+2. `is_user_active()` 판정 (마우스/키보드 idle < 5분 또는 게임 process 감지)
+3. 모드 + 활동 → `queue:paused` 토글
+   - `mode == "free"` → `DEL queue:paused`
+   - `mode != "free" and active` → `SET queue:paused 1 EX 600`
+   - `mode != "free" and idle` → `DEL queue:paused`
+
+---
+
+## 11. 데이터 플로우 검증 — 인스타 사례 end-to-end
+
+```
+1. 사용자 클릭 "카드 생성"
+   POST /api/insta/slates/123/render
+       ↓ NAS insta-lab
+2. NAS insta-lab
+   - db.create_task("slate_render", {slate_id: 123}) → task_id="t-abc"
+   - redis.rpush("queue:insta-render", {task_id: "t-abc", kind: "insta", params: {slate_id: 123, theme: "hedgy75"}})
+   - 응답 {task_id: "t-abc"}
+       ↓ 즉시 사용자
+3. Windows insta-render worker
+   - redis.blpop("queue:insta-render", 1)
+   - paused 체크 → 통과
+   - webhook(processing, 10%) → NAS DB update
+   - Playwright 카드 10장 렌더 → /mnt/nas/data/insta/123/01.png..10.png
+   - webhook(processing, 90%) 진행률 보고
+   - webhook(succeeded, 100, result_path="/media/insta/123/01.png") → NAS DB update
+4. 사용자 폴링
+   GET /api/insta/tasks/t-abc → {status: "succeeded", result_path: "/media/insta/123/01.png"}
+   브라우저에서 <img src="/media/insta/123/01.png" /> 렌더
+```
+
+---
+
+## 12. Out of Scope
+
+- V1/V2 재시작 결정 (사용자 보류, 두 process 정지 유지)
+- NAS 하드웨어 업그레이드 (#12 보류)
+- 컨테이너 리소스 제한 cpus 0.5 (#11 박재오 진행 금지)
+- SSE/WS push 모델 (YAGNI, 폴링 유지)
+- Grafana 모니터링 (NAS 자산 활용 옵션, 향후)
+
+## 13. 위험 요소
+
+| 위험 | 완화 |
+|------|------|
+| Windows 재부팅 시 worker 중단 | NSSM AppStartup AUTO + WSL2 자동 시작 (SP-9) |
+| Windows ↔ NAS 네트워크 단절 | task가 큐에 남음, NAS 측 timeout 처리 (예: 30분 timeout → failed) |
+| 박재오 게임·작업 중 worker 충돌 | task-watcher queue:paused (SP-10) + NORMAL priority |
+| Suno API rate limit | music-render 내부에서 retry + 큐 직렬 처리 |
+| SMB 마운트 실패 | WSL2 부팅 시 `mount -a`, 실패 시 alarm (로그) |
+| Redis 다운 | docker restart unless-stopped + healthcheck. 다운 시 모든 worker idle (NAS는 응답 계속) |
+| 키 노출 | 3-layer 차단 (IP 화이트리스트 + nginx + X-Internal-Key) |
+
+## 14. 첫 plan 작성 대상
+
+**옵션 A — Track A만 (사용자 선택 확정)**:
+- SP-A1: web-ai 캐시 TTL 증가 (10분)
+- SP-A2: NAS stock TTLCache (30분)
+
+이 plan은 즉시 NAS CPU 70% 감소 효과 (V2 재시작 시). Track B는 별도 spec/plan으로 차후 진행.
+
+차후 plan 작성 순서 권장:
+1. **Plan-A (이번)** — SP-A1 + SP-A2
+2. **Plan-B-Base** — SP-1 + SP-2
+3. **Plan-B-Insta** — SP-3 + SP-4 (1순위 패턴 정착)
+4. **Plan-B-Music** — SP-5 + SP-6
+5. **Plan-B-Video** — SP-7 + SP-8
+6. **Plan-B-Infra** — SP-9 + SP-10
+
+## 15. 참고
+
+- 박재오 7결정 통합: `Obsidian Vault/raw/2026-05-18-Windows-NAS-아키텍처-7결정-통합.md`
+- API 부하 해결: `Obsidian Vault/raw/2026-05-18-NAS-Window-AI-API-부하-해결방안.md`
+- 역할 분담 최적화: `Obsidian Vault/raw/2026-05-18-NAS-Windows-역할-분담-최적화.md`
+- web-backend CHECK_POINT.md (즉시·중기·장기 + 7결정 매핑)
+- web-ai CHECK_POINT.md (Phase 진행도)
+- 기존 인증 패턴: 메모리 `reference_webai_auth_pattern.md`

docs/superpowers/specs/2026-05-20-lotto-active-agent-design.md

@@ -0,0 +1,301 @@
+# LottoAgent 능동성 확장 설계
+
+- **상태**: Draft (사용자 리뷰 대기)
+- **작성일**: 2026-05-20
+- **대상 컨테이너**: agent-office
+- **영향 외부 도메인**: lotto-lab (read-only API 소비만)
+
+---
+
+## 1. 문제 정의
+
+현재 LottoAgent는 매주 월요일 09:05 cron으로 무조건 큐레이션을 1회 실행하고 헤드라인을 텔레그램으로 푸시한다. "결과가 좋지 않은 회차"도 동일하게 발화되며, **정량적 시그널이 평소보다 강할 때 별도로 알리는 능동성**이 없다.
+
+사용자 의도: 통계·시뮬레이션·전략 가중치를 에이전트가 스스로 모니터링하다가 "좋은 수치"가 나오면 능동적으로 보고하는 패턴.
+
+## 2. 의사결정 요약
+
+| 결정 사항 | 선택 | 비고 |
+|---|---|---|
+| 분석 주기 | 다중 트리거 혼합 | 매일 정기 + 시뮬레이션 후 + 회차 후 |
+| 시그널 종류 | 3종 — Sim Consensus / Strategy Drift / Confidence | Hot/Cold 변화는 제외 (노이즈) |
+| 알림 정책 | 일일 요약 + 긴급 즉시 | 2개 동시 발화 OR 단일 z≥2.5 → 긴급 |
+| 임계치 전략 | 적응형 (최근 8회 μ + σ) | warmup·보수적 단계 포함 |
+| 시뮬 강도 조절 (Layer B) | v1 미포함 | 운영 검증 후 v2에서 도입 검토 |
+
+## 3. 아키텍처
+
+### 3.1 컴포넌트 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  agent-office                                                │
+│                                                             │
+│  cron (scheduler.py)                                        │
+│  ├─ lotto_light_check    매일 09:15                          │
+│  ├─ lotto_sim_check      4시간마다 :15                       │
+│  ├─ lotto_deep_check     일/수 21:15                         │
+│  ├─ lotto_daily_digest   매일 09:25                          │
+│  └─ lotto_curate         월요일 09:05 (기존 유지)            │
+│                            ↓                                │
+│  curator/signals.py (신규)                                  │
+│  ├─ evaluate_sim_consensus()   ← lotto_best API             │
+│  ├─ evaluate_strategy_drift()  ← strategy/weights API       │
+│  ├─ evaluate_confidence()      ← deep_check 시 큐레이션 결과 │
+│  └─ adaptive_baseline()        ← μ, σ 갱신                  │
+│                            ↓                                │
+│  agent_office.db                                            │
+│  ├─ lotto_signals (이벤트 이력)                              │
+│  └─ lotto_baselines (롤링 8회 윈도우)                        │
+│                            ↓                                │
+│  notifiers/telegram_lotto.py                                │
+│  ├─ send_urgent_signal()       ← 긴급                       │
+│  └─ send_signal_summary()      ← 일일 요약                   │
+└─────────────────────────────────────────────────────────────┘
+              ↑ (HTTP GET, 기존 lotto-lab API 재사용, 변경 없음)
+              │
+        lotto:8000
+        ├─ /api/lotto/best
+        ├─ /api/lotto/strategy/weights
+        └─ /api/lotto/curator/*
+```
+
+### 3.2 책임 경계
+
+- **lotto-lab**: 변경 없음. 기존 GET API만 소비.
+- **agent-office**: 능동 모니터링 layer 전부 담당. DB도 `agent_office.db` 안에 분리해서 lotto.db와 결합 없음.
+- **프론트엔드**: Phase 4 별도 (web-ui repo). 본 spec 범위 밖.
+
+## 4. 시그널 평가 로직
+
+### 4.1 Sim Consensus Score
+
+```
+best_picks 20개의 점수 5종 (s1..s5) 사용
+
+normalize(s_k) = (s_k - min_k) / (max_k - min_k)  per metric across 20 picks
+consensus_i    = geomean( normalize(s1_i), ..., normalize(s5_i) )
+sim_signal     = mean( sorted(consensus_i, desc)[:10] )
+```
+
+- 기하평균: 5종 점수가 **동시에** 높을 때만 강한 시그널. 단일 폭주는 감쇠.
+- top-10 평균: 전체 20개 분포에서 강한 후보군의 농도 측정.
+
+### 4.2 Strategy Drift Score
+
+```
+drift_t = Σ | w_strategy_t - w_strategy_{t-1} |  for each strategy in strategy_weights
+```
+
+- 회차 단위로 비교. 한 전략이 EMA로 큰 폭 이동했을 때 누적값이 큼.
+- 시스템이 "지난 회차에서 의미 있게 학습한" 시그널.
+
+### 4.3 Confidence Score
+
+`curator.pipeline.curate_weekly()` 반환의 `validated.confidence` (0~1) 그대로.
+- light_check / sim_check: N/A (LLM 호출 없음)
+- deep_check: 직전 큐레이션 confidence를 baseline 윈도우에 push
+
+### 4.4 Adaptive Baseline
+
+```
+lotto_baselines.window_values = [v_{t-7}, v_{t-6}, ..., v_t]   (FIFO 8)
+mu     = mean(window_values)
+sigma  = stddev(window_values, ddof=1)
+z_now  = (v_now - mu) / sigma
+```
+
+- **Cold start**: window 크기 < 4 → fire_level='warmup', 발화 X
+- **준비 단계**: window 4~7 → 임계치 z=2.0 (false positive 줄임)
+- **정상 운영**: window 8 풀 → z_normal=1.5, z_urgent=2.5
+
+### 4.5 Trigger × Metric 매트릭스
+
+| Trigger | Sim Consensus | Strategy Drift | Confidence |
+|---|---|---|---|
+| `light_check` (매일 09:15) | ✓ 평가 | ✓ 회차 변경 시만 | — |
+| `sim_check` (4h마다) | ✓ 평가 | ✓ 회차 변경 시만 | — |
+| `deep_check` (일/수 21:15) | ✓ 평가 | ✓ 회차 변경 시만 | ✓ (큐레이션 후) |
+| `lotto_curate` (월 09:05) | — | — | ✓ 큐레이션 결과 직접 push |
+
+**회차 변경 가드**: Strategy Drift / Confidence는 **회차 단위 메트릭**. baseline 윈도우에 push할 때 `last_pushed_draw_no`를 비교, 동일 회차면 skip. 같은 회차 내에서 값 비교는 가능하지만 baseline 갱신은 회차당 1회만.
+
+```
+if metric in ('drift', 'confidence'):
+    if current_draw_no == baselines[metric].last_pushed_draw_no:
+        # baseline 윈도우는 그대로, z-score만 현재값으로 비교
+        skip_window_update = True
+```
+
+Sim Consensus는 회차 무관 (4시간마다 시뮬 자체가 갱신) → 매 평가 시 window push.
+
+### 4.6 Fire 결정
+
+```
+fires = [m for m in [sim, drift, conf] if m.z >= LOTTO_Z_NORMAL]
+if len(fires) >= 2 or any(m.z >= LOTTO_Z_URGENT for m in fires):
+    fire_level = 'urgent'
+elif len(fires) == 1:
+    fire_level = 'normal'
+else:
+    fire_level = 'noop'
+```
+
+## 5. 알림 흐름
+
+### 5.1 트리거→발송 다이어그램
+
+```
+cron / signal_check
+  ↓
+signals.evaluate_all()
+  ↓
+lotto_signals INSERT (all results)
+  ↓
+fire_level == 'urgent'  →  send_urgent_signal()  →  텔레그램 즉시
+fire_level == 'normal'  →  09:25 digest 합류
+fire_level == 'noop'    →  기록만
+```
+
+### 5.2 텔레그램 메시지 폼
+
+**Urgent**:
+```
+🚨 로또 능동 신호
+
+[2026-05-20 16:18]
+강한 시그널 2종 동시 발화:
+• Sim Consensus 1.84 (μ=1.02, σ=0.21) z=3.9
+• Strategy Drift 0.18 (μ=0.06, σ=0.04) z=3.0
+
+요인: gap_focus 전략이 지난 3회차 EMA +22%p
+다음 시뮬: 20:05
+
+[자세히 보기] (→ /lotto/agent)
+```
+
+**Daily digest** (09:25):
+```
+📊 로또 일일 요약 (지난 24h)
+
+평가 6회 / 발화 2회
+• Sim Consensus  normal  z=1.7  (16:18)
+• Confidence     normal  z=1.6  (월 09:05)
+
+전략 가중치 추세 (최근 8회 baseline):
+  gap_focus   ↑ +12%
+  hot_focus   →  -2%
+  pair_bias   ↓ -8%
+```
+
+- 24h 내 발화 0건이면 digest 자체 skip (조용한 날 강제 알림 없음).
+
+### 5.3 Throttle 규칙
+
+| 규칙 | 동작 |
+|---|---|
+| 같은 metric + 같은 fire_level이 6시간 이내 재발화 | 두 번째는 DB 기록만, 텔레그램 skip |
+| urgent 누적 ≥ 3통/day | 4번째부터 normal로 강등 → digest 합류 |
+| digest 24h 발화 0건 | digest skip |
+| Anthropic / 텔레그램 실패 | 평가는 success로 기록, 메시지만 60초 후 1회 retry |
+
+## 6. 데이터 모델
+
+### 6.1 lotto_signals
+
+```sql
+CREATE TABLE IF NOT EXISTS lotto_signals (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  triggered_at TEXT NOT NULL,        -- ISO8601 UTC
+  source TEXT NOT NULL,              -- 'light' | 'sim' | 'deep'
+  metric TEXT NOT NULL,              -- 'sim_signal' | 'drift' | 'confidence'
+  value REAL NOT NULL,
+  baseline_mu REAL,
+  baseline_sigma REAL,
+  z_score REAL,
+  fire_level TEXT NOT NULL,          -- 'noop' | 'warmup' | 'normal' | 'urgent'
+  notified_at TEXT,                  -- 텔레그램 발송 시각 (NULL=미발송)
+  payload TEXT                       -- JSON 부가 정보
+);
+CREATE INDEX idx_ls_triggered ON lotto_signals(triggered_at DESC);
+CREATE INDEX idx_ls_fire ON lotto_signals(fire_level, notified_at);
+```
+
+### 6.2 lotto_baselines
+
+```sql
+CREATE TABLE IF NOT EXISTS lotto_baselines (
+  metric TEXT PRIMARY KEY,
+  window_values TEXT NOT NULL,       -- JSON: [v1..v8]
+  mu REAL NOT NULL,
+  sigma REAL NOT NULL,
+  last_pushed_draw_no INTEGER,       -- 회차 단위 메트릭의 중복 push 방지 (drift, confidence)
+  updated_at TEXT NOT NULL
+);
+```
+
+마이그레이션: `agent-office/app/db.py`의 `init_db()`에 `CREATE TABLE IF NOT EXISTS` 추가만으로 idempotent. 기존 테이블 영향 없음.
+
+## 7. API 추가
+
+| 메서드 | 경로 | 설명 |
+|---|---|---|
+| GET | `/api/agent-office/lotto/signals?days=7` | 시그널 이력 (timeline, 차트용) |
+| GET | `/api/agent-office/lotto/baselines` | 현재 baseline μ/σ 조회 |
+| POST | `/api/agent-office/lotto/signal-check` | 수동 트리거 (디버깅·테스트용) |
+
+## 8. 환경 변수
+
+```bash
+LOTTO_SIGNAL_WINDOW=8        # baseline 윈도우 크기
+LOTTO_Z_NORMAL=1.5           # normal fire 임계치
+LOTTO_Z_URGENT=2.5           # urgent fire 임계치
+LOTTO_DIGEST_HOUR=9          # digest cron hour (KST)
+LOTTO_DIGEST_MIN=25
+LOTTO_THROTTLE_HOURS=6       # 같은 메트릭 재발화 throttle
+LOTTO_URGENT_DAILY_MAX=3     # urgent 하루 cap
+```
+
+모두 default 있음. `.env` 미설정 시 default로 동작.
+
+## 9. 스케줄러 cron
+
+```python
+scheduler.add_job(lotto_light_check,  "cron", hour=9, minute=15, id="lotto_light_check")
+scheduler.add_job(lotto_sim_check,    "cron", minute=15, hour="0,4,8,12,16,20", id="lotto_sim_check")
+scheduler.add_job(lotto_deep_check,   "cron", day_of_week="sun,wed", hour=21, minute=15, id="lotto_deep_check")
+scheduler.add_job(lotto_daily_digest, "cron", hour=9, minute=25, id="lotto_digest")
+# 기존: lotto_curate (월 09:05) 유지
+```
+
+## 10. 구현 Phase
+
+| Phase | 범위 | 검증 |
+|---|---|---|
+| 1 | DB 마이그레이션 + `signals.py` (순수 함수, LLM X) | `POST /lotto/signal-check`로 수동 호출 → z-score 계산 확인 |
+| 2 | cron 4개 + `lotto_signals` INSERT (텔레그램 X) | 24h 가동 → DB에 시그널 누적 |
+| 3 | 텔레그램 urgent / digest + throttle | dry-run env로 메시지 검증 후 실제 발송 |
+| 4 | 프론트 (web-ui) — `/lotto/agent` 시그널 timeline UI | 별도 PR (본 spec 범위 외) |
+
+Phase 1~3이 백엔드 능동성 완성. 각 Phase 끝에 commit + 자동 배포.
+
+## 11. 비기능 요구
+
+- **백워드 호환**: 기존 월요일 큐레이션 cron 변경 없음
+- **장애 격리**: signals 평가 실패해도 LottoAgent.state는 idle 유지 (try/except + add_log warning)
+- **테스트**: `signals.py`의 메트릭 함수는 input/output 순수형 → 단위 테스트 작성 가능
+- **관측**: `agent_logs` 테이블 그대로 활용 (별도 로깅 추가 없음)
+
+## 12. 비목표 (Out of scope)
+
+- 자동 구매·자동 픽 갱신 (보고만)
+- 시뮬레이션 강도 자동 조절 (Layer B는 v2)
+- 텔레그램 인라인 키보드 (v2에서 자동 액션 도입 시 함께)
+- 핫넘버/콜드넘버 시그널 (노이즈 위험, v1 제외)
+- 프론트 UI (별도 PR)
+
+## 13. v2 후속 검토
+
+- Layer B 시뮬 강도 조절 (모호 시그널 시 deep_simulate)
+- 사용자 피드백 루프 (텔레그램 [좋아요/별로] 버튼 → 임계치 가중 조정)
+- 회차 retrospective 자동 분석 (당첨번호 vs 추천번호 패턴 학습)

docs/superpowers/specs/2026-05-22-lotto-weight-evolver-design.md

@@ -0,0 +1,419 @@
+# Lotto Weight Evolver — 자율 학습 루프 설계 (v2)
+
+- **상태**: Draft (사용자 리뷰 대기)
+- **작성일**: 2026-05-22
+- **대상 컨테이너**: lotto (lotto-lab) + agent-office (텔레그램 보고)
+- **선행 작업**: v1 LottoAgent 능동성 확장 (2026-05-20 배포)
+- **목표**: 5종 시뮬 점수 가중치를 매주 6가지로 변형 시도 → 토요일 회고 → winner 가중치를 다음 주 base로 적용 → 무한 반복 자가 학습 루프
+
+---
+
+## 1. 문제 정의
+
+현재 `analyzer.score_combination()`은 5종 점수(`score_frequency`, `score_fingerprint`, `score_gap`, `score_cooccur`, `score_diversity`)를 **균등 합산**으로 `score_total`을 계산한다. 어떤 메트릭이 실제 추첨 결과와 더 잘 상관되는지에 대한 학습 없이 가중치가 고정.
+
+또한 `purchase_history` 기반 `strategy_evolver`는 **사용자가 실제 구매한 번호만** 학습 시그널로 사용. 사람이 안 사면 학습 안 됨.
+
+사용자 요구: 에이전트가 사람 없이도 **매일 다른 가중치로 시뮬레이션 → 번호 시도 → 토요일 추첨 후 best 가중치 식별 → 다음주 base 갱신**의 무한 학습 루프.
+
+## 2. 의사결정 요약
+
+| 결정 사항 | 선택 | 비고 |
+|---|---|---|
+| 학습 대상 | 시뮬 점수 5종 가중치 (`W = [w_freq, w_finger, w_gap, w_cooccur, w_diversity]`) | 메타 전략 가중치는 strategy_evolver가 별도 학습 (v2에서 손대지 않음) |
+| 탐험 전략 | 현재 base 주변 4개 perturbation + Dirichlet 무작위 2개 | 매주 월요일 6개 후보 |
+| 일일 시도량 | N = 5 세트/일 × 6일 = 30 세트/주 | 통계적 의미 + 비용 균형 |
+| 평가 시그널 | strategy_evolver의 `RANK_BONUS` + `correct/6` | 기존 패턴 재사용으로 일관성 |
+| Base 적용 강도 | Hybrid — winner_max_correct ≥ 4면 교체, =3이면 EMA blend (0.3), ≤2면 유지 | 노이즈에 base가 헤매지 않도록 보호 |
+| v1과의 결합 | W가 `analyzer.score_combination`에 반영 → best_picks 점수 자동 영향 → v1 시그널 자동 cascade | 별도 통합 코드 없음 |
+| strategy_evolver와의 상호작용 | strategy_evolver는 `score_total`을 그대로 입력으로 사용 → W 변경 시 입력 분포가 함께 변함. **의도된 간접 영향** | v3에서 메타 가중치도 함께 학습할 때 명시적으로 분리 검토 |
+| 자동 구매 | v2 비포함 | 사람 결정 영역 — purchase_history는 사람이 등록 |
+
+## 3. 아키텍처
+
+### 3.1 컴포넌트 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  lotto-lab (자율 학습 루프 추가)                              │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ weight_evolver.py (신규)                            │    │
+│  │ • generate_weekly_candidates()  ← 월 09:00          │    │
+│  │ • apply_today_weight()          ← 매일 09:00        │    │
+│  │ • evaluate_weekly()             ← 토 22:00          │    │
+│  │ • update_base()                 ← evaluate 안에서   │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                            ↓                                │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │ analyzer.score_combination(numbers, cache,           │    │
+│  │                            weights=None) 확장        │    │
+│  │ • weights=None → 균등 합산 (기존 호환)               │    │
+│  │ • weights=[..] → 가중 합산                           │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                            ↓                                │
+│  lotto.db 신규 테이블 3개                                    │
+│  • weight_trials       (주별 6일치 후보 가중치)              │
+│  • auto_picks          (매일 N=5 시도 번호 + 채점 결과)      │
+│  • weight_base_history (base 변경 이력)                      │
+│                                                             │
+│  기존 시뮬 cron (00/04/08/12/16/20:05) — 변경 없음.         │
+│  단 best_picks 재계산 시 활성 W를 읽어 적용.                 │
+└─────────────────────────────────────────────────────────────┘
+              ↓ (HTTP)
+┌─────────────────────────────────────────────────────────────┐
+│  agent-office                                                │
+│                                                             │
+│  cron 신규 1종: lotto_evolution_weekly (토 22:15)            │
+│  LottoAgent.run_weekly_evolution_report() (신규)             │
+│  notifiers/telegram_lotto.send_evolution_report() (신규)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 책임 경계
+
+- **lotto-lab**: 가중치 생성·적용·평가·base 갱신 + DB CRUD + API. 시그널/알림 책임 없음.
+- **agent-office**: 토요일 22:15 lotto-lab API 폴링 → 텔레그램 보고 1통.
+- **v1 (signals layer)**: 변경 없음. W 변경의 효과는 best_picks 분포 변화로 자동 흡수.
+- **strategy_evolver (메타 가중치 5종)**: 그대로 둠.
+
+## 4. 가중치 진화 알고리즘
+
+### 4.1 Weight Vector
+
+```
+W = [w_freq, w_finger, w_gap, w_cooccur, w_diversity]
+제약: w_i ≥ 0.05, sum(W) = 1.0
+```
+
+(MIN_WEIGHT=0.05는 한 메트릭이 죽지 않도록 보호. strategy_evolver의 MIN_WEIGHT 패턴.)
+
+### 4.2 주간 6개 후보 생성
+
+`generate_weekly_candidates()` — 매주 월요일 09:00 KST.
+
+```python
+W_base = get_current_base()   # weight_base_history 최신 row, 없으면 [0.2]*5
+
+# 4개 Local Perturbation
+for i in range(4):
+    noise = np.random.normal(0, 0.05, size=5)
+    W_i = W_base + noise
+    W_i = clamp(W_i, min=0.05)
+    W_i = W_i / W_i.sum()
+    save_trial(week_start, day=i, W_i, source='perturb', base=W_base)
+
+# 2개 Dirichlet 탐험
+for i in range(4, 6):
+    W_i = np.random.dirichlet([2.0]*5)
+    W_i = clamp(W_i, min=0.05)
+    W_i = W_i / W_i.sum()
+    save_trial(week_start, day=i, W_i, source='dirichlet', base=W_base)
+```
+
+- `σ=0.05` 정규분포: 각 메트릭 ±10%p 안쪽 변동
+- `α=2.0` Dirichlet: 균등 분포에 약간 치우치게, 극단 가중치도 포함
+
+### 4.3 일일 W 적용
+
+`apply_today_weight()` — 매일 09:00 KST.
+
+```python
+W_today = get_trial(week_start, day_of_week=today)
+set_active_weight(W_today)              # 메모리 캐시 or DB row (W_active 테이블 또는 file)
+generate_n_picks(N=5, weight=W_today)   # auto_picks에 5세트 저장
+```
+
+같은 W로 그날 기존 시뮬 cron (4시간마다 6회) best_picks 재계산.
+
+### 4.4 토요일 회고
+
+`evaluate_weekly()` — 매주 토요일 22:00 KST (추첨 20:35 KST + sync 21:10 → 22:00 안전).
+
+```python
+winning_numbers = get_latest_draw().numbers   # 1224, 1225, ...
+trials = get_trials(week_start)               # 6 trials
+
+scores_per_day = []
+for trial in trials:
+    picks = get_auto_picks(trial.id)          # N=5
+    day_score = mean(
+        calc_pick_score(p.numbers, winning_numbers) for p in picks
+    )
+    max_correct = max(
+        count_match(p.numbers, winning_numbers) for p in picks
+    )
+    update_pick_grades(picks, winning_numbers)   # auto_picks 채점 결과 저장
+    scores_per_day.append({
+        "trial_id": trial.id,
+        "day": trial.day_of_week,
+        "weight": trial.weight,
+        "score": day_score,
+        "max_correct": max_correct,
+    })
+
+winner = max(scores_per_day, key=lambda s: s.score)
+update_base(winner)
+```
+
+**점수 함수** (strategy_evolver `calc_draw_score` 패턴, 단순화):
+
+v2에서는 보너스 번호를 평가에 포함하지 않음 → 5개 일치를 2등/3등으로 구분 불가. 따라서 보너스 무시한 단순 매핑:
+
+```python
+# correct → rank 매핑 (보너스 제외)
+RANK_BY_CORRECT = {
+    6: 1,   # 1등
+    5: 3,   # 3등 (보너스 평가 안 함 → 2등 표시 X)
+    4: 4,
+    3: 5,
+}
+RANK_BONUS = {1: 1.0, 2: 0.8, 3: 0.6, 4: 0.3, 5: 0.1}
+
+def calc_pick_score(pick_numbers, winning_numbers):
+    correct = count_match(pick_numbers, winning_numbers[:6])
+    base = correct / 6.0
+    rank = RANK_BY_CORRECT.get(correct)
+    bonus = RANK_BONUS.get(rank, 0)
+    return base + bonus
+```
+
+(rank=2의 보너스 0.8은 매핑되지 않으므로 v2 점수에 등장하지 않음. v3에서 보너스 번호 평가 도입 시 활성화.)
+
+### 4.5 Base 갱신 규칙 (Hybrid)
+
+```python
+if winner.max_correct >= 4:
+    W_base_next = winner.weight
+    reason = "winner_4plus"
+elif winner.max_correct == 3:
+    W_base_next = 0.3 * winner.weight + 0.7 * W_base_current
+    reason = "ema_blend"
+else:
+    W_base_next = W_base_current
+    reason = "unchanged"
+
+save_to_weight_base_history(W_base_next, reason, winner)
+```
+
+성과가 약할 때 base를 그대로 두는 게 핵심 — base가 노이즈에 따라 헤매지 않음.
+
+### 4.6 Cold start (첫 주)
+
+`weight_base_history`가 비어있으면 `W_base = [0.2]*5` (균등) 가정. 첫 주는 4 perturbation이 모두 균등 주변, 2 Dirichlet 탐험.
+
+## 5. 데이터 모델
+
+### 5.1 weight_trials
+
+```sql
+CREATE TABLE IF NOT EXISTS weight_trials (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  week_start    TEXT NOT NULL,          -- 'YYYY-MM-DD' (해당 주 월요일)
+  day_of_week   INTEGER NOT NULL,       -- 0=월 .. 5=토
+  weight_json   TEXT NOT NULL,          -- '[0.18, 0.22, ...]'
+  source        TEXT NOT NULL,          -- 'perturb' | 'dirichlet'
+  base_at_gen   TEXT,                   -- 생성 시점 W_base (참조용)
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+  UNIQUE(week_start, day_of_week)
+);
+CREATE INDEX idx_wt_week ON weight_trials(week_start, day_of_week);
+```
+
+### 5.2 auto_picks
+
+```sql
+CREATE TABLE IF NOT EXISTS auto_picks (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  trial_id      INTEGER NOT NULL REFERENCES weight_trials(id) ON DELETE CASCADE,
+  pick_no       INTEGER NOT NULL,       -- 1..5
+  numbers       TEXT NOT NULL,          -- JSON 정렬 6개
+  meta_score    REAL,                   -- 활성 W로 계산한 score_total
+  correct       INTEGER,                -- 채점 후 채워짐
+  rank          INTEGER,                -- 1..5 또는 NULL
+  graded_at     TEXT,
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+  UNIQUE(trial_id, pick_no)
+);
+CREATE INDEX idx_ap_trial ON auto_picks(trial_id);
+CREATE INDEX idx_ap_graded ON auto_picks(graded_at);
+```
+
+### 5.3 weight_base_history
+
+```sql
+CREATE TABLE IF NOT EXISTS weight_base_history (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  effective_from  TEXT NOT NULL,        -- 'YYYY-MM-DD' (적용 시작 월요일)
+  weight_json     TEXT NOT NULL,
+  source_trial_id INTEGER REFERENCES weight_trials(id),  -- NULL=cold start
+  update_reason   TEXT,                 -- 'winner_4plus' | 'ema_blend' | 'unchanged' | 'cold_start'
+  winner_score    REAL,
+  winner_max_correct INTEGER,
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+```
+
+마이그레이션: `lotto/app/db.py`의 `init_db()`에 `CREATE TABLE IF NOT EXISTS` 추가만으로 idempotent. 기존 테이블 영향 없음.
+
+## 6. analyzer.score_combination 시그니처 확장
+
+```python
+# 기존
+def score_combination(numbers, cache) -> Dict[str, float]:
+    ...
+    return {
+        "score_frequency": ...,
+        "score_fingerprint": ...,
+        "score_gap": ...,
+        "score_cooccur": ...,
+        "score_diversity": ...,
+        "score_total": sum(5 scores)   # 균등 합산
+    }
+
+# 변경
+def score_combination(numbers, cache, weights: Optional[List[float]] = None) -> Dict[str, float]:
+    ...
+    scores = [s_freq, s_finger, s_gap, s_cooccur, s_diversity]
+    if weights is None:
+        total = sum(scores)
+    else:
+        total = sum(s * w for s, w in zip(scores, weights))
+    return {
+        "score_frequency": ...,
+        ...
+        "score_total": total
+    }
+```
+
+- 기본값 None → 기존 호출 호환 (변경 없는 효과)
+- 시뮬 cron / smart_recommendation 등은 `get_active_weight()` 결과 전달
+- 활성 W가 없으면 (cold start 이전) None 그대로 → 균등 합산 폴백
+
+### 6.1 활성 W 조회 (`get_active_weight()`)
+
+별도 캐시 테이블 없이 `weight_trials`에서 오늘 요일 row 직접 조회:
+
+```python
+def get_active_weight() -> Optional[List[float]]:
+    today = datetime.now(KST).date()
+    week_start = today - timedelta(days=today.weekday())  # 이번주 월요일
+    day_of_week = today.weekday()  # 0=월, 6=일
+    if day_of_week == 6:           # 일요일은 trial 없음 → 직전 토요일 W 유지
+        day_of_week = 5
+    row = db.get_weight_trial(week_start.isoformat(), day_of_week)
+    return json.loads(row["weight_json"]) if row else None
+```
+
+- 컨테이너 재시작·timezone 변화에 영향 없음 (DB 진실 기준)
+- 일요일(6)은 토요일 W를 그대로 사용 (회고 cron 22:00 전까지)
+- 첫 주 월요일 generate가 안 끝났을 때만 None 반환 → 균등 폴백
+
+## 7. API 추가 (lotto-lab)
+
+| 메서드 | 경로 | 설명 |
+|---|---|---|
+| GET | `/api/lotto/evolver/status` | 현재 base + 이번주 6 trials + 진행 상황 |
+| GET | `/api/lotto/evolver/history?weeks=12` | 주별 winner + base 변경 이력 |
+| GET | `/api/lotto/evolver/trials/{week_start}` | 특정 주 trials + 채점 결과 |
+| POST | `/api/lotto/evolver/generate-now` | 수동 트리거 (다음 월요일 후보 생성) |
+| POST | `/api/lotto/evolver/evaluate-now` | 수동 채점 (디버그) |
+
+## 8. 스케줄러 cron (lotto-lab)
+
+```python
+scheduler.add_job(generate_weekly_candidates, "cron", day_of_week="mon", hour=9,  minute=0,  id="weight_evolver_weekly")
+scheduler.add_job(apply_today_weight,         "cron", hour=9, minute=0,                       id="weight_evolver_daily")
+scheduler.add_job(evaluate_weekly,            "cron", day_of_week="sat", hour=22, minute=0,  id="weight_evolver_eval")
+```
+
+순서 보장: 월요일 09:00에 generate가 먼저 row 저장 후 commit, 그 다음 같은 시각 apply가 그 row 읽음. APScheduler가 동일 시간 job 직렬 실행 보장하지 않으므로 **월요일에 generate 함수 마지막에 inline으로 apply_today_weight 호출** — race 제거.
+
+## 9. agent-office 통합 (텔레그램 주간 보고)
+
+### 9.1 cron 추가
+
+```python
+scheduler.add_job(_run_lotto_weekly_evolution_report, "cron", day_of_week="sat", hour=22, minute=15, id="lotto_evolution_weekly")
+```
+
+### 9.2 LottoAgent.run_weekly_evolution_report (신규)
+
+```python
+async def run_weekly_evolution_report(self) -> dict:
+    from ..service_proxy import lotto_evolver_status
+    from ..notifiers.telegram_lotto import send_evolution_report
+    status = await lotto_evolver_status()
+    await send_evolution_report(status)
+    return {"ok": True, **status}
+```
+
+### 9.3 텔레그램 메시지 폼
+
+```
+🧬 로또 학습 주간 리포트 (1225회차)
+
+이번주 시도: 6일 × 5세트 = 30번
+
+🏆 Winner: 목요일 (W_4)
+  W = [freq 0.18, finger 0.32, gap 0.20, cooccur 0.22, divers 0.08]
+  최고 적중: 4개 일치 (1세트)
+  평균 점수: 0.42 (vs 다른 요일 0.18~0.30)
+
+📊 다음주 base 변경:
+  freq    0.20 → 0.18  (-)
+  finger  0.20 → 0.32  (+)
+  gap     0.20 → 0.20  (=)
+  cooccur 0.20 → 0.22  (+)
+  divers  0.20 → 0.08  (--)
+  reason: winner_4plus (4개 이상 일치 → base 교체)
+
+[웹에서 차트 보기] (/lotto/evolver)
+```
+
+## 10. v1 시그널과의 연동 (자동 cascade)
+
+별도 코드 추가 없음. 활성 W가 `analyzer.score_combination`에 반영되면:
+1. 매 4시간 시뮬 cron이 새 W로 best_picks 갱신
+2. score 분포 자체가 변하므로 v1의 `sim_consensus_score`가 자동으로 새 분포 평가
+3. W 변경 직후 outlier 패턴이 나오면 자연스럽게 sim_signal urgent fire
+
+→ 사용자는 두 종류 텔레그램 받음:
+- **🧬 토 22:15 weekly evolution report** (정해진 리듬)
+- **🚨 평시 v1 urgent / 📊 v1 digest** (시그널 기반)
+
+## 11. 구현 Phase
+
+| Phase | 범위 | 검증 |
+|---|---|---|
+| 1 | DB 마이그레이션 + `weight_evolver.py` (순수 함수: generate/evaluate + 점수 함수) + 단위 테스트 | pytest로 perturbation·Dirichlet·점수·base 갱신 룰 검증 |
+| 2 | analyzer.score_combination 시그니처 확장 + active weight 캐시 | 기존 시뮬 cron이 새 시그니처로 정상 동작 (regression X) |
+| 3 | cron 3종 등록 + API 5종 | 수동 트리거로 generate→apply→evaluate 전체 흐름 확인 |
+| 4 | agent-office 통합 (cron + 텔레그램 폼 + 테스트) | 토요일 22:15 자동 발송 확인 |
+
+각 Phase 끝 commit + 자동 배포.
+
+## 12. 비기능 요구
+
+- **백워드 호환**: `analyzer.score_combination` 기본값 None → 기존 호출 그대로 작동
+- **장애 격리**: 가중치 적용 실패 시 균등 합산 폴백, evaluate 실패해도 다음 주 base는 직전 값 유지
+- **테스트**:
+  - `weight_evolver` 순수 함수 (clamp, normalize, perturbation, base update rule) — 단위 테스트
+  - `analyzer.score_combination(weights=...)` — 가중 합산 정확성 테스트
+  - `evaluate_weekly` mock 추첨번호 시나리오 — base 갱신 분기 3가지 (winner_4plus / ema_blend / unchanged)
+- **관측**: `weight_base_history` 테이블로 모든 base 변경 추적 가능 (rollback도 가능)
+
+## 13. 비목표 (Out of scope)
+
+- 메타 전략(combined/simulation/heatmap/manual/custom) 가중치 학습 — strategy_evolver 영역, v3 후속
+- 6일 trials의 day-transition에서 이전 W로 계산된 best_picks를 새 W로 재계산하는 처리 — 다음 시뮬 cron에서 자동 덮어씀
+- Multi-objective 학습 (적중 + 분포 균등 등 복합 점수)
+- 자동 구매 (purchase_history 자동 채움)
+- 프론트 `/lotto/evolver` UI — v2 백엔드 완성 후 별도 PR (web-ui repo)
+
+## 14. v3 후속 검토
+
+- Multi-armed bandit (UCB1) — 탐험·활용 균형 더 정교
+- 메타 전략 가중치도 함께 학습 (2-layer Bayesian Optimization)
+- 가중치 공간을 RL agent로 학습 (policy gradient)
+- 자동 구매 후보 픽 (winner W로 1주 N장 자동 발주, 사람 승인 후)

docs/superpowers/specs/2026-05-23-lotto-evolver-ui-design.md

@@ -0,0 +1,368 @@
+# Lotto Evolver UI + 에이전트 활동 가시화 설계 (v2.1)
+
+- **상태**: Draft (사용자 리뷰 대기)
+- **작성일**: 2026-05-23
+- **대상 저장소**:
+  - `web-ui` (프론트엔드) — `/lotto/evolver` 페이지 신설 + 공용 활동 컴포넌트
+  - `web-backend` agent-office — LottoAgent task_id 도입 + sync_evolver_activity cron
+- **선행 작업**: v2 Lotto Weight Evolver (2026-05-22 배포, 운영 중)
+- **목표**: 토요일 22:15 텔레그램 리포트의 "[웹에서 차트 보기]" 링크가 가리키는 페이지 구축 + 로또 에이전트의 모든 활동(시그널·digest·큐레이션·evolver)을 한 곳에서 추적 가능하게.
+
+---
+
+## 1. 문제 정의
+
+v2 텔레그램 메시지가 `https://gahusb.synology.me/lotto/evolver` 링크를 포함하지만 web-ui repo에 해당 라우트가 없음 → React Router catch-all 404. spec section 13에서 "프론트 UI는 별도 PR"로 명시했지만 링크는 미리 박혀있음 → UX 깨짐.
+
+또한 LottoAgent의 활동(signals / digest / weekly_evolution_report / curate)이 agent_office.db의 `agent_logs`에는 기록되지만 `agent_tasks` 테이블에는 **`curate_weekly`만** 들어감 → agent-office UI에서 "Tasks" 섹션 봤을 때 활동 이력이 누락. lotto-lab의 weight_evolver cron(매일 apply / 월 generate / 토 evaluate)은 lotto.db에만 기록 → agent_office에서 완전히 안 보임.
+
+사용자 의도: "로또 에이전트가 무엇을 했는지" 한 곳에서 확인 가능하게.
+
+## 2. 의사결정 요약
+
+| 결정 사항 | 선택 | 비고 |
+|---|---|---|
+| 라우트 위치 | 별도 `/lotto/evolver` (텔레그램 링크와 일치) | `/stock/trade`, `/stock/screener` 패턴 따름 |
+| 사용 시나리오 | 토 22:15 텔레그램 직후 주간 요약 대시보드 | 평일 운영·장기 분석은 부차 |
+| 페이지 구조 | 단일 스크롤, 5개 카드 (Header / Winner / TrialsGrid / BaseDiff / BaseHistory / Actions) | sub-tab 불필요 |
+| 차트 | Recharts (이미 dep) — Radar / Bar / Line + 인라인 metric-card | small multiples 대신 텍스트 강조 |
+| 활동 노출 위치 | `/lotto/evolver` + `/agent-office` 양쪽 (공용 컴포넌트) | DRY |
+| 백엔드 보강 | 기존 add_log만 있던 LottoAgent 메서드에 task_id 도입 + 신규 sync_evolver_activity cron | 멱등 guard 포함 |
+
+## 3. 아키텍처
+
+### 3.1 컴포넌트 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ web-ui (신규 컴포넌트)                                       │
+│                                                             │
+│ src/pages/lotto/                                            │
+│   Evolver.jsx                  ← /lotto/evolver 진입점       │
+│   Evolver.css                                               │
+│   evolver/                                                  │
+│     WinnerCard.jsx             ← Radar (5축) + 메타          │
+│     TrialsGrid.jsx             ← 6일 Bar 비교 + 펼치기       │
+│     BaseDiff.jsx               ← 5 metric-card (텍스트+arrow)│
+│     BaseHistory.jsx            ← LineChart 12주 시계열       │
+│     EvolverActions.jsx         ← 수동 트리거 (dev)           │
+│     useEvolverApi.js           ← status+history+activity hook│
+│                                                             │
+│ src/components/lotto/                                       │
+│   LottoActivityTimeline.jsx    ← 공용 활동 timeline          │
+│                                  /lotto/evolver + /agent-office│
+└─────────────────────────────────────────────────────────────┘
+              ↓ (HTTP)
+┌─────────────────────────────────────────────────────────────┐
+│ web-backend (보강)                                           │
+│                                                             │
+│ agent-office/app/agents/lotto.py                            │
+│   • run_signal_check       → task_id 도입 (신규)             │
+│   • run_daily_digest       → task_id 도입 (신규)             │
+│   • run_weekly_evolution_report → task_id 도입 (신규)        │
+│   • sync_evolver_activity  → 신규 메서드                     │
+│                                                             │
+│ agent-office/app/scheduler.py                               │
+│   • lotto_evolver_activity_sync — 매일 09:30 cron 신규       │
+│                                                             │
+│ agent-office/app/db.py                                      │
+│   • get_tasks_by_agent_date_kind — 멱등 guard helper 신규    │
+│                                                             │
+│ agent-office/app/main.py                                    │
+│   • GET /agents/{id}/tasks에 task_type 필터 추가 (확장)      │
+│                                                             │
+│ lotto-lab: 변경 없음 (web-ui가 evolver API 직접 소비)        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 책임 경계
+
+- **web-ui Evolver 페이지**: 데이터 시각화 전담. 비즈니스 로직 없음. fetch는 useEvolverApi에 집중.
+- **LottoActivityTimeline**: 시간순 timeline 표현만. logs/tasks/evolverEvents 3종 입력 받아 merge sort + 렌더.
+- **LottoAgent**: 모든 자율 작업 시 task row 생성 (다른 에이전트와 동일 패턴).
+- **sync_evolver_activity**: lotto-lab의 결과를 agent_office.db에 거울 비추기. 백엔드 polling 패턴. 멱등.
+- **lotto-lab**: 변경 없음. 모든 evolver API는 web-ui가 직접 호출.
+
+## 4. 페이지 정보 layout
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ HEADER                                                      │
+│   Lotto · Weight Evolver                                    │
+│   "스스로 가중치를 조절하는 자율 학습 루프"                  │
+│   마지막 회고: 1225회 (2026-05-21 22:00)                    │
+├─────────────────────────────────────────────────────────────┤
+│ ① WinnerCard (대형, 메인)                                    │
+│   🏆 목요일 · W_4 · max=4개 일치                             │
+│   ┌─ Radar Chart (5축) ──┐                                  │
+│   │ freq, finger, gap,    │                                 │
+│   │ cooccur, divers       │                                 │
+│   └──────────────────────┘                                  │
+│   avg_score · n_picks graded · update reason                │
+├─────────────────────────────────────────────────────────────┤
+│ ② TrialsGrid                                                 │
+│   월 화 수 목⭐ 금 토 (가로 6개 Bar)                          │
+│   ░░ ▓▓ ░░ ██ ▒▒ ░░                                          │
+│   max=2 1  3  4  2  1                                        │
+│   클릭 → 그날 5세트 numbers + scores 펼침                    │
+├─────────────────────────────────────────────────────────────┤
+│ ③ BaseDiff                                                   │
+│   5개 metric-card 가로 정렬                                  │
+│   freq    0.20 → 0.18  ↓ -10%                                │
+│   finger  0.20 → 0.32  ↑↑ +60%                               │
+│   gap     0.20 → 0.20  = (변화 없음)                         │
+│   cooccur 0.20 → 0.22  ↑ +10%                                │
+│   divers  0.20 → 0.08  ↓↓ -60%                               │
+│   → reason: winner_4plus                                     │
+├─────────────────────────────────────────────────────────────┤
+│ ④ BaseHistory (12주)                                         │
+│   LineChart 5 라인 (freq/finger/gap/cooccur/divers)          │
+│   X축: effective_from, Y축: weight 0~1                       │
+│   dot click → reason tooltip + 회차 표시                     │
+├─────────────────────────────────────────────────────────────┤
+│ ⑤ LottoActivityTimeline (compact=false)                      │
+│   최근 7일 — task + log + lotto-lab evolver 이벤트 merge     │
+│   2026-05-23 22:15  🧬  weekly_evolution_report  succeeded   │
+│   2026-05-23 22:00  ⚖️  weight_evolver_eval (lotto-lab)       │
+│   2026-05-23 21:15  🔍  deep_check  succeeded                │
+│   ...                                                        │
+├─────────────────────────────────────────────────────────────┤
+│ ⑥ EvolverActions (개발자 모드)                                │
+│   [수동 generate-now]  [수동 evaluate-now]                   │
+│   응답 JSON 콘솔에 표시                                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 4.1 모바일 반응형
+
+- ≤640px: 1 컬럼, 차트는 가로폭 100%
+- 641-1024px: WinnerCard·TrialsGrid 가로 분할 (50/50)
+- ≥1025px: 위 layout 그대로
+
+## 5. 데이터 흐름
+
+### 5.1 useEvolverApi hook
+
+```js
+function useEvolverApi({ days = 7, weeks = 12 } = {}) {
+  // 4개 fetch 동시 — Promise.all
+  // 1. GET /api/lotto/evolver/status        → status
+  // 2. GET /api/lotto/evolver/history?weeks=12 → history
+  // 3. GET /api/agent-office/agents/lotto/logs?days=7 → logs
+  // 4. GET /api/agent-office/agents/lotto/tasks?days=7 → tasks
+  //
+  // activity = merge(logs, tasks, evolverEventsFromHistory) sorted by timestamp DESC
+  return { status, history, activity, loading, error, refetch };
+}
+```
+
+`activity` 합성 규칙:
+- agent_logs의 created_at + level + message + task_id
+- agent_tasks의 created_at + task_type + status + result_data
+- history.items의 created_at + update_reason + weight (evolver eval 자체 이벤트로 별도 표시)
+- 클라이언트에서 timestamp DESC sort → React에서 렌더링
+
+### 5.2 Recharts 매핑
+
+| 컴포넌트 | 차트 | data prop |
+|---|---|---|
+| WinnerCard | `RadarChart` | `[{metric, value, previous}]` 5점 (overlay: previous_base) |
+| TrialsGrid | `BarChart` 수평 6개 | `[{day_name, avg_score, max_correct, is_winner}]` |
+| BaseHistory | `LineChart` | `[{effective_from, freq, finger, gap, cooccur, divers}, ...]` |
+
+### 5.3 LottoActivityTimeline
+
+```jsx
+<LottoActivityTimeline
+  logs={agentLogs}
+  tasks={agentTasks}
+  evolverEvents={evolverEventsFromHistory}
+  days={7}
+  compact={false}
+/>
+```
+
+merge & sort:
+```js
+const stream = [
+  ...logs.map(l => ({ ts: l.created_at, kind: 'log', payload: l })),
+  ...tasks.map(t => ({ ts: t.created_at, kind: 'task', payload: t })),
+  ...evolverEvents.map(e => ({ ts: e.created_at, kind: 'evolver', payload: e })),
+].sort((a, b) => b.ts.localeCompare(a.ts));
+```
+
+각 stream item:
+- kind='task': 아이콘 + task_type label + status badge + (completed_at - created_at) 소요시간
+- kind='log': 아이콘(level) + message
+- kind='evolver': ⚖️ + update_reason + winner_score
+
+icon · color mapping (task_type 기준):
+```
+curate_weekly             📋  blue
+signal_check              🔍  green / fired면 amber
+daily_digest              📊  cyan
+weekly_evolution_report   🧬  purple
+evolver_generate          🌱  teal
+evolver_apply             🎲  gray
+```
+
+### 5.4 cold start / empty state
+
+- `weight_base_history` empty → 큰 빈 카드: "아직 학습 시작 전. 다음 월요일 09:00 자동 시작" + `[수동 generate-now 트리거]` 버튼
+- `trials` empty (월 09:00 전) → 안내 카드
+- `activity` empty → 회색 "최근 활동 없음"
+
+## 6. 백엔드 보강
+
+### 6.1 LottoAgent 메서드 — task_id 도입
+
+3개 메서드에 `_run` 패턴(`create_task` + try/except + `update_task_status` + `add_log(..., task_id=...)`) 적용:
+
+| 메서드 | 새 task_type | result_data 핵심 |
+|---|---|---|
+| `run_signal_check(source)` | `signal_check` | source, overall_fire, n_results, fired_metrics |
+| `run_daily_digest()` | `daily_digest` | evaluated, fired, signals_count |
+| `run_weekly_evolution_report()` | `weekly_evolution_report` | draw_no, update_reason, winner_day |
+
+기존 `_run`(`curate_weekly`)은 그대로.
+
+### 6.2 sync_evolver_activity — 신규 메서드
+
+매일 09:30 cron. lotto-lab의 today_trial 가져와 agent_office.db에 task+log 기록. 멱등 guard.
+
+```python
+async def sync_evolver_activity(self):
+    """lotto-lab evolver 상태 polling → agent_office.db에 거울. 멱등."""
+    today_iso = _today_kst_iso()
+    dow = _today_dow()
+
+    status = await service_proxy.lotto_evolver_status()
+
+    # 오늘 trial + picks → evolver_apply task
+    today_trial = next((t for t in status["trials"] if t["day_of_week"] == dow), None)
+    if today_trial and today_trial.get("picks") and not db.get_tasks_by_agent_date_kind("lotto", today_iso, "evolver_apply"):
+        tid = db.create_task("lotto", "evolver_apply", {
+            "date": today_iso, "trial_id": today_trial["id"],
+            "day_of_week": dow, "weight": today_trial["weight"],
+        })
+        db.update_task_status(tid, "succeeded", result_data={
+            "n_picks": len(today_trial["picks"]),
+            "meta_scores": [p["meta_score"] for p in today_trial["picks"]],
+        })
+        db.add_log("lotto", f"evolver_apply: 오늘 W로 {len(today_trial['picks'])}세트 추출", task_id=tid)
+
+    # 월요일 + 6 trials 완성 → evolver_generate task
+    if dow == 0 and len(status["trials"]) == 6 and not db.get_tasks_by_agent_date_kind("lotto", today_iso, "evolver_generate"):
+        tid = db.create_task("lotto", "evolver_generate", {"week_start": status["week_start"]})
+        db.update_task_status(tid, "succeeded", result_data={"trials_count": 6})
+        db.add_log("lotto", f"evolver_generate: {status['week_start']} 주의 6 trials 생성", task_id=tid)
+```
+
+토요일 22:15 evaluate는 `run_weekly_evolution_report`가 이미 task 기록 → sync 불필요.
+
+### 6.3 db.py — 신규 helper
+
+```python
+def get_tasks_by_agent_date_kind(agent_id: str, date_iso: str, task_type: str) -> List[Dict[str, Any]]:
+    """같은 (agent, date, task_type)으로 이미 생성된 task 조회 — 멱등 guard."""
+    with _conn() as conn:
+        rows = conn.execute(
+            """
+            SELECT * FROM agent_tasks
+            WHERE agent_id = ? AND task_type = ?
+              AND substr(created_at, 1, 10) = ?
+            ORDER BY created_at DESC
+            """,
+            (agent_id, task_type, date_iso),
+        ).fetchall()
+    return [dict(r) for r in rows]
+```
+
+### 6.4 scheduler.py — cron 추가
+
+```python
+async def _run_lotto_sync_evolver_activity():
+    agent = AGENT_REGISTRY.get("lotto")
+    if agent:
+        await agent.sync_evolver_activity()
+
+scheduler.add_job(
+    _run_lotto_sync_evolver_activity,
+    "cron", hour=9, minute=30,
+    id="lotto_evolver_activity_sync",
+)
+```
+
+### 6.5 main.py — API 확장
+
+`GET /api/agent-office/agents/{id}/tasks`에 query param 추가:
+```python
+@app.get("/api/agent-office/agents/{agent_id}/tasks")
+async def get_agent_tasks(agent_id: str, days: int = 7, task_type: Optional[str] = None):
+    return {"items": db.get_agent_tasks(agent_id, days=days, task_type=task_type)}
+```
+
+`db.get_agent_tasks`도 task_type 필터 추가 (기존 함수 보강).
+
+### 6.6 task_type 명세 (참조)
+
+| task_type | 트리거 | 어디서 생성 |
+|---|---|---|
+| `curate_weekly` | 월 09:05 또는 deep_check | LottoAgent._run (기존) |
+| `signal_check` | light / sim / deep cron | LottoAgent.run_signal_check (신규 wrap) |
+| `daily_digest` | 매일 09:25 | LottoAgent.run_daily_digest (신규 wrap) |
+| `weekly_evolution_report` | 토 22:15 | LottoAgent.run_weekly_evolution_report (신규 wrap) |
+| `evolver_generate` | 월 09:30 sync | LottoAgent.sync_evolver_activity (신규) |
+| `evolver_apply` | 매일 09:30 sync | LottoAgent.sync_evolver_activity (신규) |
+
+## 7. 라우터 등록
+
+`web-ui/src/routes.jsx`에 추가:
+
+```jsx
+const Evolver = lazy(() => import('./pages/lotto/Evolver'));
+
+// appRoutes 배열에 추가:
+{
+    path: 'lotto/evolver',
+    element: <Evolver />,
+},
+```
+
+## 8. 구현 Phase
+
+| Phase | 범위 | 검증 |
+|---|---|---|
+| 1 | agent-office 백엔드 보강 (LottoAgent task_id wrap + sync cron + db helper) + 단위 테스트 | task row 생성 확인, 멱등 가드 동작 |
+| 2 | agent-office API 확장 (task_type 필터) | curl로 필터링 동작 확인 |
+| 3 | web-ui Evolver 페이지 — useEvolverApi + WinnerCard + TrialsGrid + BaseDiff + BaseHistory + EvolverActions | 로컬 dev 브라우저에서 모든 카드 정상 렌더, 모바일 반응형 |
+| 4 | LottoActivityTimeline 공용 컴포넌트 — /lotto/evolver에 통합 + /agent-office LottoAgent 카드에 compact 모드 통합 | 두 페이지에서 동일 데이터 보임 |
+| 5 | 라우터 등록 + 텔레그램 링크 404 해결 확인 | `release:nas` → 텔레그램 [차트 보기] 클릭 → 정상 페이지 |
+
+Phase 1-2: web-backend repo, Phase 3-5: web-ui repo. 각 repo는 별도 git, 별도 배포 (web-backend git push → Gitea webhook auto, web-ui `npm run release:nas`).
+
+## 9. 비기능 요구
+
+- **백워드 호환**: 기존 LottoAgent 호출자 (cron 등) 시그니처 변경 없음. 내부 task_id wrap만 추가.
+- **장애 격리**: sync_evolver_activity 실패해도 lotto-lab 영향 없음. task_id wrap 실패 시 try/except로 메서드 자체는 계속 동작.
+- **멱등성**: sync_evolver_activity는 멱등 guard로 cron 재실행·재시작 안전.
+- **테스트**:
+  - LottoAgent task_id wrap — mock task_id 받아 update 호출 확인
+  - sync_evolver_activity 멱등 — 같은 날 2번 호출 시 1 row만
+  - LottoActivityTimeline merge sort — unit test로 stream 순서·아이콘 매핑
+- **관측**: 모든 LottoAgent 메서드의 result_data 표준화 (Section 6.1 표 참조)
+
+## 10. 비목표 (Out of scope)
+
+- TrialsGrid에서 과거 주 deep dive 조회 (`GET /trials/{week_start}` 사용) — v2.2 후속, 별도 UI
+- 차트 export / CSV 다운로드
+- 가중치 수동 편집 UI — v3에서 사용자 개입 모드 도입 검토
+- 다른 에이전트(stock / music / realestate)의 활동 통합 timeline — 현재 spec은 lotto만
+- 실시간 WebSocket 푸시 (agent-office에 ws 있지만 evolver 활동은 polling으로 충분)
+
+## 11. v3 후속 검토
+
+- 다른 에이전트 활동도 같은 패턴(LottoActivityTimeline 제너릭화 → AgentActivityTimeline)으로 노출
+- /lotto/evolver 페이지에 사용자 의견 입력 (이번 winner가 마음에 듦/싫음) → 학습 시그널로 활용
+- BaseHistory에 brush 도입 (긴 history 시계열 zoom)
+- TrialsGrid에 picks 채점 결과 통계 (몇 개 trial에서 4개 일치 났는지 등)

docs/superpowers/specs/2026-05-23-tarot-lab-design.md

@@ -0,0 +1,559 @@
+# Tarot Lab v1 — Design Spec
+
+**작성일:** 2026-05-23
+**상태:** 디자인 승인 완료, 구현 계획 작성 대기
+**관련 자산:**
+- `source/images/tarot_page/tarot_main_landing_page.png` (랜딩 시안)
+- `source/images/tarot_page/tarot_card_select_page.png` (카드 선택 시안)
+- `source/images/tarot_page/tarot_background.png` (정적 배경 폴백)
+- `source/images/tarot_page/tarot_cards.png` (카드 콜라주 참고)
+- `source/videos/tarot_main_background.mp4` (히어로 영상)
+
+---
+
+## 1. 목표와 배경
+
+개인 웹 플랫폼에 라이더-웨이트(RWS) 기반 타로 리딩 기능을 추가한다. v1은 **오늘의 카드 / 3장 스프레드 / 리딩 히스토리·마이페이지** 3개 핵심 흐름을 한 번에 배포하고, AI 해석은 Claude Sonnet 4.6을 통해 **근거 기반(evidence)** 으로 생성한다. 켈틱 크로스 10장 스프레드와 카드 78장 정식 이미지 자산은 v2 분리.
+
+### 비목표 (v2 이후)
+- 켈틱 크로스 10장 스프레드
+- 사용자가 제공할 카드 78장 정식 이미지 자산의 정식 매핑 (v1은 placeholder/CSS)
+- 78장 의미 텍스트 완성본 (v1은 메이저 22 + 마이너 키워드만)
+- 텔레그램 자동 push ("매일 오늘의 카드")
+- 카드 78장 도감 화면
+- 즐겨찾기 메모 편집 UI (백엔드 endpoint는 v1에 포함, UI는 v2)
+- **카드 시각 효과 보강** — 카드 이미지 자산 도착 이후 보강:
+  - 카드 hover·focus 시 보더 주변 황금 글로우·sparkle particles
+  - 카드 뒤집기 애니메이션 (3D rotateY transform, 0.6~0.8s ease-out, 뒷면→앞면 전환)
+  - 우주 입자 floating · 별 깜빡임 등 분위기 효과
+  - v1은 hover lift + 단순 fade-in 정도의 미니멀 모션만
+
+---
+
+## 2. 아키텍처
+
+```
+web-ui (React + Vite)
+  /tarot           랜딩 (히어로 영상 + 3-tier)
+  /tarot/today     오늘의 카드 (원카드)
+  /tarot/reading   3장 스프레드 (메인 인터랙션)
+  /tarot/history   마이페이지 (리딩 이력)
+        │
+        │ /api/agent-office/tarot/*
+        ▼
+agent-office (FastAPI 확장)
+  app/routes/tarot.py        4 endpoint
+  app/agents/tarot.py        TarotAgent (Claude Sonnet 호출 + 응답 검증)
+  app/db.py                  tarot_readings 테이블 추가
+        │
+        ▼ Anthropic API
+   Claude Sonnet 4.6
+```
+
+### 경계 결정 이유
+- **카드 78장 메타데이터는 프론트 정적 JSON** — 자주 안 변하고 셔플·선택에 백엔드 호출 불필요. 라운드트립 절약.
+- **AI 해석만 백엔드** — API key 보호 + 호출 로깅·검증·reroll 가능.
+- **히스토리도 백엔드** — localStorage는 기기 의존, 사용자가 영속화 요구.
+- **신규 컨테이너 없음** — agent-office 확장. nginx·docker-compose 변경 0건.
+
+### Why agent-office인가
+1. `ANTHROPIC_API_KEY` 이미 환경변수로 연결됨
+2. Claude SDK + httpx 클라이언트 set up 완료
+3. Agent FSM 패턴(idle→working→reporting)에 자연스럽게 맞음 — TarotAgent도 "리딩 수행" 작업으로 모델링
+4. 텔레그램 봇 연결되어 있어 v2에서 "매일 오늘의 카드" push 확장 여지
+
+---
+
+## 3. 프론트 데이터 모델
+
+### 정적 카드 데이터 (`web-ui/src/pages/tarot/data/cards.js`)
+
+```js
+export const TAROT_DECK = [
+  // Major Arcana 22장
+  {
+    id: 0,
+    slug: "the-fool",
+    name: "바보",
+    nameEn: "The Fool",
+    arcana: "major",
+    element: "air",
+    keywords: ["새로운 시작", "도약", "순수", "자유"],
+    reversedKeywords: ["무모함", "경솔함", "위험", "방향 상실"],
+    meaningUpright: "미지의 세계로 내딛는 첫걸음. 계산보다 직관과 신뢰로 시작하는 시기.",
+    meaningReversed: "준비 없이 뛰어들어 위험을 자초하거나, 두려움으로 첫걸음을 미루는 상태.",
+    image: null,  // 사용자가 /images/tarot/cards/the-fool.png 추가 시 자동 매핑
+  },
+  // ... Major 21장 더
+
+  // Minor Arcana 56장
+  {
+    id: 22,
+    slug: "ace-of-wands",
+    name: "지팡이 에이스",
+    arcana: "minor",
+    suit: "wands",
+    rank: 1,
+    element: "fire",
+    keywords: ["창조의 불씨", "영감", "새로운 시작"],
+    reversedKeywords: ["지연", "동기 부족", "방향 상실"],
+    meaningUpright: "...",
+    meaningReversed: "...",
+    image: null,
+  },
+  // ... Minor 55장 더
+];
+
+export const SPREADS = {
+  one_card: {
+    id: "one_card",
+    name: "오늘의 카드",
+    positions: [{ idx: 0, label: "오늘" }],
+  },
+  three_card: {
+    id: "three_card",
+    name: "3장 스프레드",
+    positions: [
+      { idx: 0, label: "과거" },
+      { idx: 1, label: "현재" },
+      { idx: 2, label: "미래" },
+    ],
+  },
+};
+
+export const CATEGORIES = ["연애", "일·커리어", "관계", "재물", "건강", "일반"];
+```
+
+**v1 시드 데이터 작업량:**
+- 메이저 22장: 정·역 키워드 + 정·역 의미 텍스트 완성 (필수)
+- 마이너 56장: 정·역 키워드만 (필수) + 의미 텍스트는 짧은 요약 1문장씩 (v2에서 보강)
+
+### 카드 이미지 자동 매핑 규칙
+- 사용자가 `web-ui/public/images/tarot/cards/<slug>.png` 추가 시 자동 표시
+- `cards.js`에서 `image: \`/images/tarot/cards/${slug}.png\`` 일관 패턴
+- `onError` → CSS 카드 디자인 폴백 (그라데이션 보더 + 카드명 + 심볼)
+
+---
+
+## 4. 백엔드 데이터 모델
+
+### tarot_readings 테이블 (`agent_office.db`)
+
+```sql
+CREATE TABLE IF NOT EXISTS tarot_readings (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at   TEXT NOT NULL,            -- UTC ISO8601
+    spread_type  TEXT NOT NULL,            -- 'one_card' | 'three_card'
+    category     TEXT,                     -- '연애' | '일·커리어' | …
+    question     TEXT,                     -- 사용자 입력 (NULL 가능)
+    cards        TEXT NOT NULL,            -- JSON: [{position, card_id, reversed}]
+    interpretation_json TEXT,              -- Claude 응답 파싱 결과 전체
+    summary      TEXT,                     -- interpretation_json.summary 빠른 조회용
+    model        TEXT,                     -- 'claude-sonnet-4-6'
+    tokens_in    INTEGER,
+    tokens_out   INTEGER,
+    cost_usd     REAL,
+    confidence   TEXT,                     -- 'high' | 'medium' | 'low'
+    favorite     INTEGER DEFAULT 0,
+    note         TEXT
+);
+CREATE INDEX idx_tarot_created  ON tarot_readings(created_at DESC);
+CREATE INDEX idx_tarot_favorite ON tarot_readings(favorite, created_at DESC);
+```
+
+**저장 정책:**
+- 모든 리딩은 자동 저장 (사용자가 "저장" 누르지 않아도). 사용자가 별도 액션 없이도 히스토리에서 확인 가능.
+- `favorite` 토글 + `note` 편집은 별도 PATCH 호출
+- 카드는 `card_id`(slug)만 저장 — 실제 이름·의미는 항상 프론트 데이터에서 조회 → 카드 데이터 수정이 과거 이력에 자동 반영
+
+### interpretation_json 구조
+
+```json
+{
+  "summary": "전체 흐름 한 단락 (3~4문장)",
+  "cards": [
+    {
+      "position": "과거",
+      "card": "the-fool",
+      "reversed": false,
+      "interpretation": "이 위치에서 이 카드가 의미하는 바 (3~4문장)",
+      "evidence": {
+        "card_meaning_used": "참고 카드 정보에서 인용한 키워드·상징",
+        "position_logic": "왜 이 의미가 이 위치에 그렇게 적용되는지 (1~2문장)",
+        "category_lens": "카테고리 관점에서 부각되는 면 (1문장)"
+      },
+      "advice": "이 카드가 주는 짧고 구체적인 조언 (1문장)"
+    }
+  ],
+  "interactions": [
+    {
+      "type": "synergy" | "conflict" | "transition",
+      "between": ["the-fool", "the-lovers"],
+      "explanation": "두 카드의 슈트·원소·정역방향 흐름 근거 (1~2문장)"
+    }
+  ],
+  "advice": "3장(또는 1장) 종합 조언 (2문장)",
+  "warning": null,
+  "confidence": "high" | "medium" | "low"
+}
+```
+
+---
+
+## 5. API 명세
+
+### 5.1 `POST /api/agent-office/tarot/interpret`
+AI 해석만 수행 (저장과 분리). 응답 받은 후 사용자가 별도 액션 없으면 자동 저장 호출.
+
+**Request:**
+```json
+{
+  "spread_type": "three_card",
+  "category": "연애",
+  "question": "다음 달 그 사람과의 관계는?",
+  "cards": [
+    { "position": "과거", "card_id": "the-fool", "reversed": false },
+    { "position": "현재", "card_id": "the-lovers", "reversed": true },
+    { "position": "미래", "card_id": "ten-of-cups", "reversed": false }
+  ],
+  "cards_reference": "## 1. 위치: 과거 | 카드: The Fool ...",
+  "context_meta": {
+    "major_minor_ratio": "2:1",
+    "element_distribution": { "air": 2, "water": 1, "fire": 0, "earth": 0 },
+    "orientation_flow": "upright→reversed→upright"
+  }
+}
+```
+
+`cards_reference`와 `context_meta`는 프론트가 `cards.js`를 기반으로 빌드해서 전송. 백엔드가 카드 데이터를 따로 가지고 있을 필요 없음 (DRY).
+
+**Response:** `interpretation_json` 구조 + 호출 메타.
+```json
+{
+  "interpretation_json": { /* 위 4절 구조 */ },
+  "model": "claude-sonnet-4-6",
+  "tokens_in": 712,
+  "tokens_out": 942,
+  "cost_usd": 0.0163,
+  "latency_ms": 5240,
+  "reroll_count": 0
+}
+```
+
+**에러:**
+- 400 — spread_type 미지원 / cards 길이 불일치 / cards_reference 빈 문자열
+- 429 — Anthropic API rate limit
+- 500 — Claude 호출 실패 (Retry-After 헤더 포함) 또는 reroll 2회 모두 실패
+
+### 5.2 `POST /api/agent-office/tarot/readings`
+리딩 저장. interpret 결과를 그대로 + 사용자 컨텍스트.
+
+**Request:**
+```json
+{
+  "spread_type": "three_card",
+  "category": "연애",
+  "question": "...",
+  "cards": [...],
+  "interpretation_json": { ... },
+  "model": "claude-sonnet-4-6",
+  "tokens_in": 712, "tokens_out": 942, "cost_usd": 0.0163,
+  "confidence": "medium"
+}
+```
+
+**Response:** `{ "id": 123, "created_at": "2026-05-23T07:42:11Z" }`
+
+### 5.3 `GET /api/agent-office/tarot/readings`
+페이지네이션 + 필터.
+
+**Query:** `?page=1&size=20&favorite=true&spread_type=three_card&category=연애`
+
+**Response:**
+```json
+{
+  "items": [
+    { "id": 123, "created_at": "...", "spread_type": "three_card",
+      "category": "연애", "question": "...", "cards": [...],
+      "summary": "한 줄 요약", "confidence": "medium", "favorite": 1 }
+  ],
+  "page": 1, "size": 20, "total": 47
+}
+```
+
+### 5.4 `PATCH /api/agent-office/tarot/readings/{id}`
+즐겨찾기 토글·메모.
+
+**Request:** `{ "favorite": true }` 또는 `{ "note": "메모" }`
+
+### 5.5 `DELETE /api/agent-office/tarot/readings/{id}`
+이력 삭제.
+
+### Nginx 라우팅
+변경 없음. 기존 `/api/agent-office/` 매칭에 흡수됨.
+
+---
+
+## 6. AI 프롬프트 설계
+
+### SYSTEM_PROMPT
+
+```text
+당신은 라이더-웨이트(RWS) 타로 덱의 전통 상징체계에 정통한 타로 리더입니다.
+사용자의 질문, 카테고리, 뽑힌 카드 각각의 정·역방향과 위치를 받아 근거 기반으로 해석합니다.
+
+# 해석 원칙
+1. 데이터 우선: "참고 카드 정보" 블록의 키워드·기본의미·상징만을 1차 근거로 사용.
+   외부 변형 의미·다른 덱 해석은 사용하지 않음.
+2. 위치 의미 결합: 카드의 의미와 위치(과거/현재/미래 또는 오늘)를 명시적으로 결합해서 해석. evidence에 근거 기록.
+3. 카드 간 상호작용 분석 (3장 스프레드):
+   - 시너지: 같은 슈트, 같은 원소, 메이저 비율, 정·역 흐름
+   - 충돌·전환: 슈트 충돌(컵-소드, 완드-펜타클), 정→역 전환, 메이저↔마이너 전환
+4. 자기 성찰 톤: 운명론 단정 금지. "…할 가능성이 있어 보입니다" 같은 표현.
+5. 카테고리 컨텍스트: 동일 카드라도 카테고리에 따라 강조점이 달라야 함.
+6. 질문 직접 응답: 사용자 질문을 evidence·advice에서 인용·반영.
+
+# 응답 형식 (strict JSON only — 코드블록 없이 raw JSON)
+{
+  "summary": "전체 흐름 한 단락 (3~4문장)",
+  "cards": [
+    {
+      "position": "<위치 라벨>",
+      "card": "<card_id>",
+      "reversed": <bool>,
+      "interpretation": "3~4문장",
+      "evidence": {
+        "card_meaning_used": "참고 카드 정보에서 인용한 키워드·상징",
+        "position_logic": "왜 이 위치에 이렇게 적용되는지 (1~2문장)",
+        "category_lens": "카테고리 관점에서 부각되는 면 (1문장)"
+      },
+      "advice": "1문장"
+    }
+  ],
+  "interactions": [
+    { "type": "synergy"|"conflict"|"transition",
+      "between": ["<card_id>", "<card_id>"],
+      "explanation": "1~2문장" }
+  ],
+  "advice": "2문장. interactions를 1개 이상 참조할 것.",
+  "warning": "역방향·충돌 경계 (없으면 null)",
+  "confidence": "high"|"medium"|"low"
+}
+
+# confidence 판정 기준
+- high: 3장 모두 한 방향 서사 또는 명확한 전환
+- medium: 2장 일관, 1장 별도 신호
+- low: 카드 간 의미 충돌이 커서 명확한 흐름 잡기 어려움
+
+# 금지사항
+- 참고 카드 정보에 없는 상징 도입 금지
+- 역방향 카드를 정방향처럼 다루지 말 것
+- "신비롭게 들리는" 문구로 채우지 말 것 — evidence에 인용·근거 명시
+- JSON 외 텍스트 금지
+```
+
+### USER_PROMPT_TEMPLATE
+
+```text
+# 질문
+{question}
+
+# 카테고리
+{category}
+
+# 스프레드
+{spread_name} ({spread_count}장)
+
+# 뽑힌 카드와 참고 카드 정보
+{cards_with_reference_block}
+
+# 작업
+위 정보만을 근거로 사용해, 시스템 지침의 JSON 형식으로 응답하세요.
+- 각 카드의 evidence.card_meaning_used에는 위 "참고 카드 정보"에서 발췌한 키워드·의미를 그대로 인용.
+- interactions는 3장 간 슈트·원소·정역방향 패턴을 분석해 최소 1개 이상 도출.
+- confidence는 카드 흐름의 일관성에 따라 정직하게 판정.
+```
+
+### cards_with_reference_block 예시
+
+```
+## 1. 위치: 과거 | 카드: The Fool (정방향)
+- 아르카나: Major (0)
+- 원소: 공기 (Air)
+- 정방향 키워드: 새로운 시작, 도약, 순수, 자유
+- 정방향 의미: 미지의 세계로 내딛는 첫걸음. 계산보다 직관과 신뢰로 시작하는 시기.
+
+## 2. 위치: 현재 | 카드: The Lovers (역방향)
+- 아르카나: Major (6)
+- 원소: 공기 (Air)
+- 역방향 키워드: 관계 갈등, 선택의 어려움
+- 역방향 의미: 두 길 사이에서 머뭇거리거나, 이미 내린 선택의 의구심이 커지는 시기.
+
+## 3. 위치: 미래 | 카드: Ten of Cups (정방향)
+- 아르카나: Minor (Cups, 10)
+- 원소: 물 (Water)
+- 정방향 키워드: 정서적 충만, 가족·공동체의 행복
+- 정방향 의미: 컵 슈트의 완성 단계. 감정적 만족이 안정된 형태로 자리잡는 시기.
+
+## 추가 컨텍스트
+- 메이저:마이너 비율: 2:1 (메이저 우세 → 큰 인생 주제)
+- 원소 분포: 공기 2, 물 1
+- 정역 흐름: 정→역→정 (일시적 정체 후 회복 가능성)
+```
+
+### 응답 검증 (백엔드)
+- `cards[].evidence.card_meaning_used`가 비어있으면 → reroll 1회 (max 1 retry, 총 2회 호출)
+- `interactions`가 비어있고 spread_type == "three_card"이면 → reroll 1회
+- reroll 2회 모두 실패 → 받은 응답 그대로 저장 + log warning + 500 응답
+- JSON 파싱 실패 → codeblock 추출 시도 → raw 추출 시도 → 텍스트 그대로 summary에 박고 cards=[]
+
+### 비용
+- Sonnet 4.6 입력 $3/1M, 출력 $15/1M
+- 회당 입력 ~700, 출력 ~900 토큰
+- 회당 비용 ~$0.015~0.022
+- 환경변수로 가격 오버라이드: `TAROT_COST_INPUT_PER_M`, `TAROT_COST_OUTPUT_PER_M`
+
+---
+
+## 7. UI 흐름
+
+### 7.1 Route 구조
+| Path | 화면 | 컴포넌트 |
+|---|---|---|
+| `/tarot` | 랜딩 | `Tarot.jsx` |
+| `/tarot/today` | 오늘의 카드 | `TodayCard.jsx` |
+| `/tarot/reading` | 3장 스프레드 메인 | `Reading.jsx` |
+| `/tarot/history` | 마이페이지 | `History.jsx` |
+
+### 7.2 랜딩 (`/tarot`)
+- 영상 배경 (`tarot_main_background.mp4` autoplay muted loop, `prefers-reduced-motion` 시 정지 이미지)
+- Overlay: `linear-gradient(rgba(15,4,40,.5) → rgba(15,4,40,.85))`
+- 헤더 sticky nav: 오늘의 카드 / 타로 리딩 / 가이드 / 히스토리
+- Hero: h1 "당신의 오늘을 비추는 타로" + sub + 2 CTA (지금 시작하기 / 오늘의 카드)
+- 3-tier 카드: 🌙 오늘의 운세 / 🃏 3장 스프레드 / ✨ AI 해석 (hover lift)
+
+### 7.3 3장 스프레드 (`/tarot/reading`)
+3-step 진행, 한 화면 안에서 step 전환.
+
+**Step 1 — 질문 입력 (좌측 panel)**
+- 질문 textarea
+- 카테고리 chip 선택 (`CATEGORIES` 중 1개)
+- 스프레드 라디오 (3장 / 1장)
+- [⊃ 카드 셔플하기] 버튼
+
+**Step 2 — 카드 선택 (중앙)**
+- 셔플된 카드 16장 그리드 (4×4, 카드 뒷면)
+- 카드 hover 시 lift + glow
+- 카드 click 시 자리(과거→현재→미래)로 날아가며 flip + 위치 라벨 표시
+- 3장 모두 채워지면 [AI 해석 시작] 버튼 활성
+
+**Step 3 — AI 해석 (우측 panel)**
+- 좌측: 3장 카드 자리 (카드 click으로 우측 panel 전환)
+- 우측 panel: 선택된 카드명 + 키워드 chip + 기본 의미 + AI interpretation + AI evidence(접을 수 있음) + advice
+- 하단: 종합 summary + advice + warning(있을 때) + confidence 배지
+- 액션: [⭐ 즐겨찾기 토글] / [다시 뽑기]
+
+### 7.4 오늘의 카드 (`/tarot/today`)
+- 단일 큰 카드 슬롯 + "운명을 묻다" 버튼
+- 카테고리·질문 옵션 (default = "일반 / 없음")
+- 클릭 → 1장 추출 + flip 애니메이션 + Claude 호출 → 우측 텍스트로 해석 표시
+- 하루 1회 제한은 v1에 없음 (소비 자유)
+
+### 7.5 히스토리 (`/tarot/history`)
+- 카드 리스트형: 날짜 · 스프레드 종류 · 질문 · 카드 미니 · 요약 한 줄 · confidence 배지 · ⭐ 토글
+- 클릭 → 디테일 모달 (원본 해석 전체)
+- 필터: 즐겨찾기만 / 스프레드 종류 / 카테고리
+- 페이지네이션 20개씩
+
+### 7.6 공용 컴포넌트
+- `TarotCard.jsx` — 단일 카드 (앞·뒷면 토글, props: cardId / reversed / size / clickable)
+- `CardGrid.jsx` — 셔플 16장 그리드 (props: deckSlice / onPick)
+- `SpreadSlots.jsx` — 위치별 슬롯 (props: spread / cards)
+- `InterpretationPanel.jsx` — 우측 패널 (카드 의미 + AI 텍스트 + evidence 접기)
+- `useTarotShuffle.js` — Fisher–Yates + 16장 슬라이스 hook
+- `useTarotReading.js` — 카드 선택 상태 + reference 블록 빌더 + AI 호출 + 저장 hook
+
+### 7.7 디자인 토큰
+- 배경 그라데이션: `#0a0420 → #1a0d2e → #2a1648`
+- 금색 액센트: `#d4af37`
+- 카드 보더 글로우: `0 0 24px rgba(212, 175, 55, .35)`
+- 폰트: 본문 기존 / 타이틀 세리프 (Cormorant Garamond + Noto Serif KR 폴백)
+- 네임스페이스: `.tarot-*`
+
+### 7.8 navLinks 추가
+- id: `tarot`, label: `Tarot`, path: `/tarot`, subtitle: `ARCANA`,
+  description: "라이더-웨이트 카드로 오늘과 내일을 비추는 리딩 랩",
+  icon: sparkle 아이콘, accent: `#a78bfa`
+
+---
+
+## 8. 미디어 자산
+
+### 히어로 영상
+- 원본: `source/videos/tarot_main_background.mp4`
+- 배포 위치: `web-ui/public/videos/tarot_hero.mp4` (Vite public/ 직접 서빙)
+- 권장 압축: 1920×1080 H.264 ≤4Mbps, ≤15초 loop
+- 폴백: `prefers-reduced-motion` 또는 `navigator.connection.saveData` 시 `tarot_background.png` 정지 이미지
+
+### 배경 이미지
+- 원본: `source/images/tarot_page/tarot_background.png`
+- 배포 위치: `web-ui/public/images/tarot_background.png`
+- 사용: 영상 fallback + 카드 선택 페이지 배경 layer
+
+### 카드 자산
+- v1: `web-ui/public/images/tarot/card_back.svg` — 단일 카드 뒷면 SVG (보라+금 + ARCANA TAROT 모노그램)
+- v1 카드 앞면: 78장 모두 CSS 카드 디자인 (그라데이션 보더 + 카드명 세리프 + 심볼 이모지)
+- 사용자 자산 추가 시: `web-ui/public/images/tarot/cards/<slug>.png` 자동 매핑, 누락 시 `onError` → CSS 폴백
+- 정적 파일이므로 이미지 추가 후 별도 빌드 불필요. NAS의 `frontend/images/tarot/cards/`에 robocopy 또는 직접 업로드 → 페이지 reload만으로 즉시 반영
+- 사용자가 78장을 한 번에 추가하지 않아도 됨 — 매핑된 것은 이미지로, 안 된 것은 CSS 폴백으로 자연스럽게 혼용
+
+---
+
+## 9. 테스트 전략
+
+### 프론트 (Vitest)
+- `data/cards.js` 검증: 78장 총수, slug 중복 없음, 메이저 22 + 마이너 56, 모든 카드 keywords·meaningUpright·meaningReversed 존재
+- `useTarotShuffle.js`: Fisher–Yates 정확성 (중복 없음, 분포)
+- `useTarotReading.js`: 카드 선택 상태 전환, reference 블록 빌더 단위 테스트
+- `TarotCard.jsx`: 정·역 토글, flip 상태, 이미지 onError 폴백
+- `Reading.jsx`: step 1→2→3 전환
+
+### 백엔드 (pytest)
+- `tarot.py::interpret`: 응답 파싱 (raw JSON / codeblock 감싸진 JSON / 깨진 JSON 폴백)
+- `tarot.py::interpret`: evidence·interactions 누락 시 reroll 1회 → 실패 시 그대로 저장
+- `db.py`: tarot_readings CRUD 정확성, favorite 필터, 페이지네이션
+- Anthropic 호출은 mock — 실제 호출은 통합 테스트 1건만
+
+### 제외
+- AI 응답 품질 자체는 자동 테스트 불가 — manual QA로 검수
+
+---
+
+## 10. 배포
+
+1. **백엔드 (agent-office 수정만)**: `git push` → Gitea Webhook → agent-office 재빌드 + 자동 마이그레이션 (`CREATE TABLE IF NOT EXISTS`)
+2. **프론트**: 로컬 빌드 → `npm run release:nas` → robocopy (영상·이미지 포함)
+3. **docker-compose 변경 없음**
+4. **nginx 변경 없음**
+5. **`scripts/deploy*.sh` 변경 없음** — 컨테이너 리스트 그대로
+
+---
+
+## 11. 위험·완화
+
+| 위험 | 완화 |
+|---|---|
+| Claude 응답 JSON 깨짐 | 파싱 폴백 3단(codeblock→raw→텍스트) + reroll 1회 |
+| 영상 파일 NAS 트래픽↑ | 압축 후 사이즈 체크 — 5MB 초과 시 사용자 노티 |
+| 카드 이미지 미준비로 임팩트↓ | CSS 카드 디자인을 시안 톤(보라+금)에 맞춰 정교화 |
+| AI 비용 폭주 | 회당 ~$0.02, 일 50회 가정 시 월 ~$30 — 개인 사용 OK |
+| 78장 의미 텍스트 작성 부담 | v1 plan에 별도 "데이터 시드 task" 분리, 메이저 22 우선 + 마이너 키워드만 |
+| reference 블록을 프론트가 빌드 → 백엔드 검증 누락 | reference 블록 빈 문자열·길이 단순 검증만 추가 (carot 검증은 v2) |
+
+---
+
+## 12. v1 작업량 추산
+- 백엔드: agent-office 추가 ~300 LOC (`agents/tarot.py` + `routes/tarot.py` + `db.py` 마이그레이션 + 테스트)
+- 프론트: ~1500~2000 LOC (4 페이지 + 5~7 컴포넌트 + 데이터 + CSS)
+- 카드 시드 데이터: 메이저 22장 완성 + 마이너 56장 키워드만 + 짧은 의미 1문장
+- 예상 plan task: 15~18개

docs/superpowers/specs/2026-05-25-saju-tarot-lab-migration-design.md

@@ -0,0 +1,670 @@
+# saju-lab 신설 + tarot-lab 분리 — 마이그레이션 설계
+
+**작성일**: 2026-05-25
+**상태**: Spec (구현 plan 작성 전)
+
+---
+
+## 1. 목표
+
+1. **saju-lab 신설**: 별도 디렉토리에 있던 `saju-web` (Next.js + Supabase + OpenAI) 프로젝트를 web-backend 모노레포의 한 lab 서비스로 마이그레이션. Python FastAPI + Claude + SQLite 패턴으로 단순화.
+2. **tarot-lab 분리**: 현재 `agent-office` 컨테이너 내부 모듈로 들어 있는 tarot 기능을 독립 컨테이너로 분리. agent-office가 가벼워지고 tarot은 자체 라이프사이클을 가짐.
+
+두 작업이 같은 패턴(독립 lab 컨테이너 신설)을 공유하므로 하나의 spec에 담아 순차 구현.
+
+---
+
+## 2. 배경
+
+### 2-1. saju-web 현황
+- 위치: `C:\Users\jaeoh\Desktop\workspace\saju-web`
+- 스택: Next.js 16, TypeScript, Supabase(OAuth+DB), OpenAI gpt-4o, PortOne 결제, Kakao 공유
+- 기능 4종: 사주분석(10토큰), 궁합(15토큰), 토정비결(5토큰), 오늘의 운세
+- 핵심 자산: `lib/saju-calculator.ts`, `lib/ai-interpretation.ts`, `lib/daeun-calculator.ts`, `lib/solar-terms.ts` (계산 엔진 ~1500줄)
+- 현재 사용 중이 아님. 자산 보존 + 패턴 일치화를 위한 마이그레이션
+
+### 2-2. tarot-lab 현황
+- 위치: `agent-office/app/tarot/` (모듈), `agent-office/app/routers/tarot.py`
+- DB: `agent_office.db`의 `tarot_readings` 테이블
+- API: `/api/agent-office/tarot/*` 6개 endpoint (interpret, save, list, get, patch, delete)
+- 21개 단위 테스트 존재
+- 문제: agent-office가 점점 비대해짐 (텔레그램·로또·주식·청약·유튜브·타로 모두 한 컨테이너에). tarot은 독립 도메인이라 분리가 자연스러움
+
+### 2-3. 다른 lab 패턴 (참조 기준)
+`insta-lab`, `music-lab`, `realestate-lab`은 모두 동일 패턴:
+```
+<lab>/
+├── Dockerfile (python:3.12-slim)
+├── requirements.txt
+├── pytest.ini
+├── tests/
+└── app/
+    ├── main.py (FastAPI)
+    ├── config.py
+    ├── db.py (SQLite)
+    └── <도메인 모듈들>
+```
+- 인증 없음 (개인 NAS 서비스)
+- nginx가 `/api/<name>/`로 라우팅
+- docker-compose의 한 항목으로 등록
+- Gitea Webhook → deployer가 rsync + docker compose up -d --build
+
+---
+
+## 3. 핵심 결정 사항
+
+| 항목 | 결정 |
+|------|------|
+| 백엔드 언어 | Python FastAPI (saju 계산 엔진은 TypeScript → Python 포팅) |
+| AI 모델 | Claude Sonnet 4.6 (`claude-sonnet-4-6`) + prompt-caching beta. tarot과 일관 |
+| DB | SQLite 로컬 (saju-lab은 `saju.db`, tarot-lab은 `tarot.db`) |
+| 인증 | 없음 (다른 lab 패턴 일치). saju-web의 Supabase/PortOne/Kakao 제거 |
+| saju-lab v1 기능 | 사주 분석 + 궁합 + 사주 결과 내 세운(歲運) (오늘의 운세는 세운으로 통합). 토정비결은 v2 |
+| tarot DB 마이그레이션 | 1회성 복사 스크립트 (agent_office.db → tarot.db), cutover 후 agent-office tarot 모듈 완전 제거 |
+| saju-lab UI | 시안 기반 신규 (시안 추후 제공, Phase 2 마지막 단계) |
+| API prefix | `/api/saju/*`, `/api/tarot/*` (완전 이전) — `/api/agent-office/tarot/*`는 제거 |
+| 포트 (내부) | tarot-lab 18250, saju-lab 18300 |
+| 진행 순서 | Phase 1 tarot 분리 → Phase 2 saju 신설 |
+
+---
+
+## 4. 디렉토리 구조
+
+```
+web-backend/
+├── tarot-lab/                      # [신설]
+│   ├── Dockerfile
+│   ├── requirements.txt
+│   ├── pytest.ini
+│   ├── tests/
+│   │   ├── test_db.py              # agent-office/tests/test_tarot_db.py 이관
+│   │   ├── test_schema.py
+│   │   ├── test_pipeline.py
+│   │   └── test_routes.py          # 6 endpoint (interpret + readings CRUD 5)
+│   └── app/
+│       ├── __init__.py
+│       ├── main.py                 # FastAPI app + /api/tarot/* 라우터 6개
+│       ├── config.py               # TAROT_MODEL, TAROT_COST_*, ANTHROPIC_API_KEY, TAROT_TIMEOUT_SEC
+│       ├── db.py                   # tarot.db: 5 CRUD + _tarot_row_to_dict
+│       ├── models.py               # Pydantic 모델 5개 (TarotCardDraw, TarotInterpretRequest, TarotInterpretResponse, TarotSaveRequest, TarotPatchRequest)
+│       ├── pipeline.py             # Claude 호출 + reroll 1회
+│       ├── prompt.py               # SYSTEM_PROMPT + build_user_message
+│       └── schema.py               # validate_interpretation
+│
+├── saju-lab/                       # [신설]
+│   ├── Dockerfile
+│   ├── requirements.txt            # fastapi, httpx, anthropic, pydantic, sxtwl(절기/음력)
+│   ├── pytest.ini
+│   ├── tests/
+│   │   ├── fixtures/
+│   │   │   └── reference_saju.json # Node.js 원본에서 추출한 입력→출력 쌍
+│   │   ├── test_core.py            # 천간/지지/십성/십이운성/calculate_saju
+│   │   ├── test_solar_terms.py     # 24절기
+│   │   ├── test_lunar.py           # 음력 변환
+│   │   ├── test_analysis.py        # 오행/신강신약/용신/세운
+│   │   ├── test_daeun.py
+│   │   ├── test_shinsal.py         # 신살/공망/지장간
+│   │   ├── test_compatibility.py   # 궁합 점수
+│   │   ├── test_pipeline.py        # Claude mock + reroll
+│   │   ├── test_compat_pipeline.py
+│   │   ├── test_schema.py
+│   │   ├── test_db.py
+│   │   └── test_routes.py
+│   └── app/
+│       ├── __init__.py
+│       ├── main.py                 # FastAPI app
+│       ├── config.py               # SAJU_MODEL, SAJU_COST_*, ANTHROPIC_API_KEY, SAJU_TIMEOUT_SEC
+│       ├── db.py                   # saju.db: saju_records, compat_records 테이블 + CRUD
+│       ├── models.py               # SajuRequest, CompatRequest, etc.
+│       ├── calculator/
+│       │   ├── __init__.py
+│       │   ├── constants.py        # HEAVENLY_STEMS, EARTHLY_BRANCHES, FIVE_ELEMENTS, HIDDEN_STEMS, TEN_GODS, TWELVE_FORTUNES
+│       │   ├── core.py             # get_year_ganzi, get_month_ganzi, get_day_ganzi, get_hour_ganzi, get_ten_god, get_twelve_fortune, calculate_saju
+│       │   ├── solar_terms.py      # get_solar_term_date, get_current_solar_term, get_solar_term_month_branch, get_days_to_next_solar_term — sxtwl 사용
+│       │   ├── lunar.py            # solar_to_lunar, lunar_to_solar
+│       │   ├── shinsal.py          # get_hidden_stems, get_all_hidden_stems, analyze_branch_interactions, calculate_shinsal, calculate_gongmang
+│       │   ├── analysis.py         # calculate_detailed_element_balance, calculate_element_score, analyze_day_master_strength, estimate_yongshin, calculate_seun, perform_full_analysis
+│       │   ├── daeun.py            # calculate_daeun, get_current_daeun, get_daeun_description
+│       │   └── compatibility.py    # calculate_compatibility (오행 상생/상극 + 지지 합/충 점수화)
+│       ├── interpret/
+│       │   ├── __init__.py
+│       │   ├── pipeline.py         # Claude 호출 + reroll (tarot 패턴)
+│       │   ├── compat_pipeline.py
+│       │   ├── prompt.py           # 사주 12항목 SYSTEM_PROMPT (Claude용 재작성, evidence-based)
+│       │   ├── compat_prompt.py    # 궁합 SYSTEM_PROMPT
+│       │   └── schema.py           # validate_saju_interpretation, validate_compat_interpretation
+│       └── routers/
+│           ├── __init__.py
+│           ├── saju.py             # POST /api/saju/interpret, /readings CRUD, /current-fortune
+│           └── compat.py           # POST /api/saju/compat/interpret, /readings CRUD
+│
+├── agent-office/                   # [수정]
+│   ├── app/
+│   │   ├── tarot/                  # [제거]
+│   │   ├── routers/tarot.py        # [제거]
+│   │   ├── models.py               # Tarot* 5개 제거
+│   │   ├── db.py                   # tarot_readings 관련 CRUD 5개 + _tarot_row_to_dict + CREATE TABLE 제거
+│   │   └── main.py                 # include_router(tarot_router.router) 줄 제거
+│   ├── tests/                      # test_tarot_*.py 4개 제거
+│   └── scripts/
+│       └── migrate_tarot_to_lab.py # [신설] 1회성 마이그레이션
+│
+├── docker-compose.yml              # [수정] tarot-lab, saju-lab 추가
+├── nginx/default.conf              # [수정] /api/tarot/ → tarot-lab, /api/saju/ → saju-lab, /api/agent-office/tarot/ 제거
+├── scripts/
+│   ├── deploy-nas.sh               # [수정] CONTAINERS 배열에 saju-lab, tarot-lab 추가
+│   └── deploy.sh                   # [수정] 5위치 (CLAUDE.md memory의 "배포 스크립트 동기화" 항목 참조)
+└── docs/superpowers/specs/
+    └── 2026-05-25-saju-tarot-lab-migration-design.md  # 본 문서
+```
+
+**프론트엔드 (`web-ui/`)** — Phase 1·2 양쪽 변경:
+```
+web-ui/
+├── src/
+│   ├── api.js                      # [Phase 1 수정] tarot helpers 6개 URL prefix 변경 + [Phase 2 추가] saju/compat helpers
+│   ├── routes.jsx                  # [Phase 2 수정] /saju, /saju/result, /saju/compatibility, /saju/compatibility/result 라우트
+│   ├── components/Icons.jsx        # [Phase 2 수정] IconSaju 추가
+│   └── pages/
+│       ├── tarot/                  # [Phase 1] URL prefix만 변경, 그 외 변경 없음
+│       └── saju/                   # [Phase 2 신설, 시안 받은 후]
+│           ├── Saju.jsx
+│           ├── SajuForm.jsx
+│           ├── SajuResult.jsx
+│           ├── Compatibility.jsx
+│           ├── CompatibilityForm.jsx
+│           ├── CompatibilityResult.jsx
+│           ├── data/
+│           │   ├── constants.js    # 천간/지지/오행 상수 (UI 표시용)
+│           │   └── interpretations.js
+│           ├── hooks/
+│           │   ├── useSajuForm.js
+│           │   └── useSajuInterpretation.js
+│           └── components/
+│               ├── SajuBoard.jsx   # 4기둥 시각화
+│               ├── ElementChart.jsx# 오행 차트
+│               ├── DaeunTimeline.jsx
+│               └── InterpretationPanel.jsx
+```
+
+---
+
+## 5. Phase 1: tarot-lab 분리
+
+### 5-1. 신규 tarot-lab 컨테이너 생성
+
+**파일 단순 복사 + 모듈 평탄화:**
+- `agent-office/app/tarot/__init__.py` → `tarot-lab/app/__init__.py` (간단화)
+- `agent-office/app/tarot/prompt.py` → `tarot-lab/app/prompt.py`
+- `agent-office/app/tarot/pipeline.py` → `tarot-lab/app/pipeline.py` (import 경로 수정: `..config` → `.config`, `..models` → `.models`)
+- `agent-office/app/tarot/schema.py` → `tarot-lab/app/schema.py`
+
+**추출 파일:**
+- `tarot-lab/app/config.py`: agent-office의 config.py에서 TAROT_* 환경변수만 추출
+  ```python
+  import os
+  ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "")
+  TAROT_MODEL = os.getenv("TAROT_MODEL", "claude-sonnet-4-6")
+  TAROT_COST_INPUT_PER_M = float(os.getenv("TAROT_COST_INPUT_PER_M", "3.0"))
+  TAROT_COST_OUTPUT_PER_M = float(os.getenv("TAROT_COST_OUTPUT_PER_M", "15.0"))
+  TAROT_TIMEOUT_SEC = int(os.getenv("TAROT_TIMEOUT_SEC", "180"))
+  TAROT_DATA_PATH = os.getenv("TAROT_DATA_PATH", "/app/data")
+  TAROT_DB_PATH = os.path.join(TAROT_DATA_PATH, "tarot.db")
+  ```
+- `tarot-lab/app/models.py`: agent-office models.py에서 Tarot* 5개만 추출
+- `tarot-lab/app/db.py`: 
+  - tarot_readings CREATE TABLE + WAL 활성화
+  - 5 CRUD (save/get/list/update/delete) + `_tarot_row_to_dict`
+  - DB 경로는 `TAROT_DB_PATH` (volume mount된 `/app/data/tarot.db`)
+- `tarot-lab/app/main.py`:
+  ```python
+  from fastapi import FastAPI, HTTPException
+  from .models import (...)
+  from . import pipeline, db as db_module
+
+  app = FastAPI(title="tarot-lab")
+
+  @app.on_event("startup")
+  def _init_db():
+      db_module.init_db()
+
+  # /api/tarot/* 5 endpoints (routers/tarot.py 코드 그대로)
+  ```
+
+**Dockerfile (insta-lab 패턴):**
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY app/ ./app/
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+**requirements.txt:**
+```
+fastapi==0.115.0
+uvicorn[standard]==0.32.0
+httpx==0.27.2
+pydantic==2.9.2
+```
+
+### 5-2. 테스트 이관
+- `agent-office/tests/test_tarot_*.py` 4개 파일 → `tarot-lab/tests/test_*.py`
+- import 경로 수정 (`from app.tarot.pipeline` → `from app.pipeline`)
+- pytest.ini 추가 (`testpaths = tests`, `pythonpath = .`)
+- 모두 통과 확인 (21 tests)
+
+### 5-3. DB 마이그레이션 스크립트
+
+`agent-office/scripts/migrate_tarot_to_lab.py`:
+```python
+"""1회성 — agent_office.db의 tarot_readings를 tarot.db로 복사.
+멱등성: 이미 존재하는 id는 SKIP.
+실행: docker exec agent-office python /app/scripts/migrate_tarot_to_lab.py
+"""
+import sqlite3
+import os
+
+SRC = os.getenv("AGENT_OFFICE_DB", "/app/data/agent_office.db")
+DST = os.getenv("TAROT_DB", "/app/data/tarot.db")
+
+def migrate():
+    src = sqlite3.connect(SRC)
+    dst = sqlite3.connect(DST)
+    dst.execute("""
+      CREATE TABLE IF NOT EXISTS tarot_readings (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ... (agent-office 스키마 그대로)
+      )
+    """)
+    rows = src.execute("SELECT * FROM tarot_readings").fetchall()
+    cols = [c[0] for c in src.execute("SELECT * FROM tarot_readings LIMIT 1").description]
+    placeholders = ",".join("?" * len(cols))
+    cols_str = ",".join(cols)
+    moved = 0
+    for r in rows:
+        cur = dst.execute(f"SELECT 1 FROM tarot_readings WHERE id = ?", (r[0],))
+        if cur.fetchone() is None:
+            dst.execute(f"INSERT INTO tarot_readings ({cols_str}) VALUES ({placeholders})", r)
+            moved += 1
+    dst.commit()
+    print(f"migrated {moved} / {len(rows)} rows")
+
+if __name__ == "__main__":
+    migrate()
+```
+
+**볼륨 공유 전략**: tarot-lab의 `/app/data`를 agent-office의 `/app/data`와 같은 NAS 호스트 디렉토리에 마운트. tarot.db는 신규 파일이라 별도 마운트 가능.
+
+### 5-4. docker-compose / nginx / deploy 갱신
+
+**docker-compose.yml**에 추가:
+```yaml
+tarot-lab:
+  build: ./tarot-lab
+  container_name: tarot-lab
+  restart: unless-stopped
+  ports:
+    - "18250:8000"
+  environment:
+    - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    - TAROT_MODEL=${TAROT_MODEL:-claude-sonnet-4-6}
+    - TAROT_DATA_PATH=/app/data
+  volumes:
+    - ${RUNTIME_PATH:-.}/data:/app/data
+```
+
+**nginx/default.conf**에 추가, 기존 `/api/agent-office/tarot/`은 제거:
+```nginx
+location /api/tarot/ {
+    proxy_pass http://tarot-lab:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+    proxy_connect_timeout 60s;
+}
+```
+
+**deploy 스크립트 5위치** (memory의 "배포 스크립트 동기화" 참조):
+- `scripts/deploy-nas.sh`의 CONTAINERS 배열
+- `scripts/deploy.sh`의 SERVICES, DIRS 배열
+- 컨테이너 목록 하드코딩된 모든 위치에 `tarot-lab` 추가 (Phase 1) / `saju-lab` 추가 (Phase 2)
+
+### 5-5. agent-office cutover
+
+마이그레이션 + 데이터 검증 후:
+- `agent-office/app/tarot/` 디렉토리 통째로 제거
+- `agent-office/app/routers/tarot.py` 제거
+- `agent-office/app/main.py`에서 tarot router import + include_router 줄 제거
+- `agent-office/app/models.py`에서 `TarotCardDraw`, `TarotInterpretRequest`, `TarotInterpretResponse`, `TarotSaveRequest`, `TarotPatchRequest` 제거
+- `agent-office/app/db.py`에서 `save_tarot_reading`, `get_tarot_reading`, `list_tarot_readings`, `update_tarot_reading`, `delete_tarot_reading`, `_tarot_row_to_dict` 제거
+- `agent-office/app/db.py`의 CREATE TABLE에서 `tarot_readings` 줄 제거 (또는 idempotent 유지: 기존 DB 호환 위해 CREATE IF NOT EXISTS는 유지하되 코드 경로 제거)
+- `agent-office/tests/test_tarot_*.py` 4개 제거
+- agent-office pytest 통과 확인
+
+### 5-6. web-ui api.js URL 변경
+
+`web-ui/src/api.js`의 tarot helpers 6개:
+- `tarotInterpret`: `/api/agent-office/tarot/interpret` → `/api/tarot/interpret`
+- `tarotSaveReading`: `/api/agent-office/tarot/readings` → `/api/tarot/readings`
+- `tarotListReadings`: 동일 변환
+- `tarotGetReading`: 동일 변환
+- `tarotPatchReading`: 동일 변환
+- `tarotDeleteReading`: 동일 변환
+
+Phase 1 검증: `npm run dev` → http://127.0.0.1:3007/tarot → 3장 리딩 1회 e2e 동작 확인.
+
+---
+
+## 6. Phase 2: saju-lab 신설
+
+### 6-1. 계산 엔진 포팅 (TypeScript → Python)
+
+**핵심 위험**: 계산 엔진은 ~1500줄 TypeScript로 매년 검증된 코드. Python으로 옮기면서 미세한 버그가 들어가면 모든 사주 해석이 잘못됨.
+
+**대응 전략 — Reference Output 비교 테스트**:
+1. saju-web의 `lib/saju-calculator.ts` 코드를 Node.js로 직접 실행 (`node -e "..."`)
+2. 알려진 입력 30~50쌍에 대해 `calculateSaju(year, month, day, hour, gender)` + `performFullAnalysis(saju, currentYear)` + `calculateDaeun(...)` 호출 결과를 JSON 파일로 저장
+3. `tests/fixtures/reference_saju.json` 형식:
+   ```json
+   [
+     {
+       "input": {"year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "male"},
+       "expected": {
+         "saju": {...},
+         "analysis": {...},
+         "daeun": [...]
+       }
+     },
+     ... (50개)
+   ]
+   ```
+4. Python 포팅 후 pytest로 매 입력 → expected와 1:1 비교 (`assert deep_equal(actual, expected)`)
+
+**포팅 순서** (의존성 그래프):
+1. `calculator/constants.py` — 모든 상수 (천간 10·지지 12·오행 5·십성·십이운성·지장간·신살)
+2. `calculator/solar_terms.py` — `sxtwl` Python 라이브러리 사용 (24절기 + 음력)
+3. `calculator/lunar.py` — `sxtwl` 음력↔양력 변환
+4. `calculator/core.py` — `get_year_ganzi`, `get_month_ganzi` (절기 기반), `get_day_ganzi`, `get_hour_ganzi`, `get_ten_god`, `get_twelve_fortune`, `calculate_saju`
+5. `calculator/shinsal.py` — 지장간(`get_hidden_stems`, `get_all_hidden_stems`), 지지 상호작용(`analyze_branch_interactions`), 신살(`calculate_shinsal`), 공망(`calculate_gongmang`)
+6. `calculator/analysis.py` — 오행 점수(`calculate_detailed_element_balance`, `calculate_element_score`), 신강신약(`analyze_day_master_strength`), 용신(`estimate_yongshin`), 세운(`calculate_seun`), 종합(`perform_full_analysis`)
+7. `calculator/daeun.py` — `calculate_daeun`, `get_current_daeun`, `get_daeun_description`
+8. `calculator/compatibility.py` — 두 사주의 오행 매칭 + 지지 합/충 점수화 → 0~100 점수
+
+각 단계마다 reference test 통과를 게이트로.
+
+### 6-2. Claude 프롬프트 (tarot 패턴 재활용)
+
+**`interpret/prompt.py`** — 사주 12항목 해석:
+- 시스템 프롬프트: "당신은 한국 전통 사주명리학 전문가다. 다음 사주 + 분석 결과를 보고, JSON 스키마로 12항목 해석을 작성하라. 각 항목은 evidence 필드를 포함해 어떤 사주 요소에서 결론을 도출했는지 명시하라."
+- 12항목: 타고난 기질 / 오행 밸런스 / 지지 상호작용 / 신살 영향 / 재물운 / 직업 적성 / 애정운 / 건강운 / 현재 대운 / 올해 세운 / 인생 황금기 / 종합 조언
+- JSON 응답 스키마:
+  ```json
+  {
+    "items": [
+      { "key": "기질", "title": "...", "content": "...", "evidence": {"saju_element": "...", "reasoning": "..."} },
+      ...
+    ],
+    "summary": "...",
+    "advice": "...",
+    "warning": "...",
+    "confidence": "high|medium|low"
+  }
+  ```
+- `cache_control: ephemeral`을 system 블록에 적용
+
+**`interpret/compat_prompt.py`** — 궁합 해석:
+- 두 사주 + 궁합 점수 + 오행 상생/상극 분석 → JSON 응답
+- evidence: 어떤 지지 합/충에서 점수가 나왔는지 명시
+
+**`interpret/schema.py`** — validate 함수:
+- `validate_saju_interpretation(parsed)`: items 12개 존재 / 각 evidence 채워졌는지 / confidence 값 검증
+- `validate_compat_interpretation(parsed)`: 마찬가지
+
+**`interpret/pipeline.py`** — Claude 호출 (tarot pipeline.py 거의 그대로 복사 + 사주용 prompt/schema 사용):
+- max_tokens 2400 (12항목 + 종합이라 더 길음)
+- reroll 1회
+- latency_ms / tokens 로깅
+
+### 6-3. DB 스키마
+
+`saju-lab/app/db.py`:
+```python
+SAJU_DB_SCHEMA = """
+CREATE TABLE IF NOT EXISTS saju_records (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  birth_year INTEGER NOT NULL,
+  birth_month INTEGER NOT NULL,
+  birth_day INTEGER NOT NULL,
+  birth_hour INTEGER,
+  gender TEXT NOT NULL,
+  calendar_type TEXT DEFAULT 'solar',
+  saju_data JSON NOT NULL,
+  analysis_data JSON NOT NULL,
+  daeun_data JSON NOT NULL,
+  interpretation_json JSON,
+  model TEXT,
+  tokens_in INTEGER DEFAULT 0,
+  tokens_out INTEGER DEFAULT 0,
+  cost_usd REAL DEFAULT 0,
+  latency_ms INTEGER DEFAULT 0,
+  reroll_count INTEGER DEFAULT 0,
+  favorite INTEGER DEFAULT 0,
+  memo TEXT,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS compat_records (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  person_a JSON NOT NULL,
+  person_b JSON NOT NULL,
+  score INTEGER NOT NULL,
+  breakdown JSON NOT NULL,
+  interpretation_json JSON,
+  model TEXT,
+  tokens_in INTEGER DEFAULT 0,
+  tokens_out INTEGER DEFAULT 0,
+  cost_usd REAL DEFAULT 0,
+  favorite INTEGER DEFAULT 0,
+  memo TEXT,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+"""
+```
+
+CRUD 함수: `save_saju_record`, `get_saju_record`, `list_saju_records`, `update_saju_record`, `delete_saju_record` + compat 5개.
+
+### 6-4. API 엔드포인트
+
+**`routers/saju.py`**:
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| POST | `/api/saju/interpret` | 입력 → 계산 + AI 해석 + DB 저장. 응답에 saju/analysis/daeun/interpretation/reading_id 포함 |
+| GET | `/api/saju/readings` | 페이지네이션 목록 (page, size, favorite) |
+| GET | `/api/saju/readings/{id}` | 상세 조회 |
+| PATCH | `/api/saju/readings/{id}` | favorite, memo 수정 |
+| DELETE | `/api/saju/readings/{id}` | 삭제 |
+| GET | `/api/saju/current-fortune?reading_id={id}` | 저장된 사주 기반 오늘의 세운 (실시간 계산, AI 호출 없음) |
+
+**`routers/compat.py`**:
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| POST | `/api/saju/compat/interpret` | 두 사람 입력 → 두 사주 계산 + 궁합 점수 + AI 해석 + DB 저장 |
+| GET | `/api/saju/compat/readings` | 목록 |
+| GET | `/api/saju/compat/readings/{id}` | 상세 |
+| PATCH | `/api/saju/compat/readings/{id}` | favorite, memo |
+| DELETE | `/api/saju/compat/readings/{id}` | 삭제 |
+
+### 6-5. docker-compose / nginx 등록
+
+**docker-compose.yml**에 saju-lab 항목 추가 (tarot-lab과 동일 패턴, 포트 18300).
+
+**nginx/default.conf**에 추가:
+```nginx
+location /api/saju/ {
+    proxy_pass http://saju-lab:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+    proxy_connect_timeout 60s;
+}
+```
+
+deploy 스크립트 5위치에 `saju-lab` 추가.
+
+### 6-6. web-ui /saju 페이지
+
+**시안 추후 제공** (사용자 확인). 시안 받은 후 tarot 페이지 패턴 따라 구현:
+- 입력 폼: 생년월일 + 시간 + 성별 + 양력/음력 (양력 default)
+- 결과 페이지: 사주판 시각화 + 오행 차트 + 대운 타임라인 + AI 12항목 아코디언
+- 궁합: 두 사람 입력 폼 + 결과 카드
+- 인사이트 패널 (tarot의 InterpretationPanel.jsx 패턴 차용)
+
+`api.js`에 helpers 추가:
+- `sajuInterpret`, `sajuListReadings`, `sajuGetReading`, `sajuPatchReading`, `sajuDeleteReading`, `sajuCurrentFortune`
+- `compatInterpret`, `compatListReadings`, `compatGetReading`, `compatPatchReading`, `compatDeleteReading`
+
+`routes.jsx`에 라우트 추가:
+- `/saju` (입력), `/saju/result` (사주 결과), `/saju/compatibility` (입력), `/saju/compatibility/result` (궁합 결과)
+
+`components/Icons.jsx`에 `IconSaju` 추가.
+
+---
+
+## 7. 데이터 흐름
+
+### tarot-lab (Phase 1)
+```
+[web-ui /tarot/reading]
+  ↓ POST /api/tarot/interpret { cards, question, category, spread_type }
+[nginx /api/tarot/ → tarot-lab:8000]
+  ↓ pipeline.interpret() → Claude API
+  ↓ validate + reroll
+[tarot-lab]
+  ↓ POST /api/tarot/readings { ... save body }
+  ↓ db.save_tarot_reading() → tarot.db INSERT
+  ← { id, created_at }
+```
+
+### saju-lab (Phase 2)
+```
+[web-ui /saju/result]
+  ↓ POST /api/saju/interpret { year, month, day, hour, gender, calendarType }
+[nginx /api/saju/ → saju-lab:8000]
+  ↓ calculator.calculate_saju() → SajuData
+  ↓ calculator.perform_full_analysis() → SajuAnalysis
+  ↓ calculator.calculate_daeun() → DaeunPillar[]
+  ↓ interpret.pipeline.interpret() → Claude API
+  ↓ validate + reroll
+  ↓ db.save_saju_record() → saju.db INSERT
+  ← { saju, analysis, daeun, interpretation, reading_id, cost_usd, latency_ms }
+[web-ui]
+```
+
+### saju-lab 궁합
+```
+[web-ui /saju/compatibility/result]
+  ↓ POST /api/saju/compat/interpret { person_a: {...}, person_b: {...} }
+[saju-lab]
+  ↓ calculate_saju(person_a) + calculate_saju(person_b)
+  ↓ compatibility.calculate_compatibility(saju_a, saju_b) → { score, breakdown }
+  ↓ interpret.compat_pipeline.interpret() → Claude API
+  ↓ db.save_compat_record()
+  ← { saju_a, saju_b, score, breakdown, interpretation, reading_id }
+```
+
+---
+
+## 8. 에러 처리
+
+| 시나리오 | 처리 |
+|---------|------|
+| Claude API HTTP error | `TarotError` / `SajuError` raise → FastAPI 500 |
+| Claude JSON 파싱 실패 | `_extract_json` codeblock 스트립 + 첫 `{` / 마지막 `}` 추출. 실패 시 reroll |
+| validate 실패 (필수 필드 누락) | reroll 1회. 그래도 실패 시 `_Error("검증 실패")` raise → 500 |
+| 계산 엔진 입력 오류 (잘못된 날짜 등) | Pydantic validation → 422 |
+| DB 락 | sqlite WAL 모드. 짧은 retry 없이 raise (드물게 발생) |
+| 마이그레이션 스크립트 중복 실행 | `INSERT OR IGNORE` 패턴 / 멱등 |
+
+---
+
+## 9. 테스트 전략
+
+### tarot-lab
+- 기존 21 tests 이관 + import 경로 수정 후 100% 통과
+
+### saju-lab — 계산 엔진
+- **Reference output 비교가 핵심**. 30~50개 입력 → JSON 저장 → Python 결과와 deep_equal 비교
+- 각 모듈 단위 테스트 (constants, solar_terms, lunar, core, shinsal, analysis, daeun, compatibility)
+- 회귀 방지: 추가 입력 케이스 발견 시 fixtures에 추가
+
+### saju-lab — Claude 파이프라인
+- httpx mock (respx 또는 monkeypatch) 사용 (tarot 패턴 그대로)
+- validate / reroll / JSON 파싱 폴백 / cost 계산 검증
+
+### saju-lab — 라우터
+- TestClient 기반 e2e (FastAPI 표준)
+- DB tmp_path fixture
+
+### 통합 검증 (Phase 1, Phase 2 끝)
+- `npm run dev` + http://127.0.0.1:3007/tarot에서 리딩 1회 (Phase 1)
+- 같은 곳에서 /saju에서 사주 + 궁합 1회씩 (Phase 2, 시안 적용 후)
+
+---
+
+## 10. 환경변수 정리
+
+**tarot-lab 신규 환경변수** (docker-compose env):
+- `ANTHROPIC_API_KEY` (필수)
+- `TAROT_MODEL` (기본 `claude-sonnet-4-6`)
+- `TAROT_COST_INPUT_PER_M` (기본 3.0)
+- `TAROT_COST_OUTPUT_PER_M` (기본 15.0)
+- `TAROT_TIMEOUT_SEC` (기본 180)
+- `TAROT_DATA_PATH` (기본 `/app/data`)
+
+**saju-lab 신규 환경변수**:
+- `ANTHROPIC_API_KEY` (필수)
+- `SAJU_MODEL` (기본 `claude-sonnet-4-6`)
+- `SAJU_COST_INPUT_PER_M`, `SAJU_COST_OUTPUT_PER_M`
+- `SAJU_TIMEOUT_SEC`
+- `SAJU_DATA_PATH`
+
+---
+
+## 11. 마이그레이션 위험 + 완화
+
+| 위험 | 영향 | 완화 |
+|------|------|------|
+| TS→Python 포팅 미세 차이 (예: 절기 일자 1일 차이) | 모든 사주 결과 변형 | Reference output 비교 테스트 50건 + sxtwl로 절기 동일 알고리즘 사용 |
+| tarot.db 마이그레이션 중 데이터 손실 | 사용자 리딩 이력 손실 | 멱등 스크립트 + 검증 후 cutover. agent-office의 원본 데이터는 cutover 후에도 30일 유지 (테이블만 DROP 안 함) |
+| 두 컨테이너 추가로 NAS 메모리 압박 | 다른 서비스 OOM | python:3.12-slim 기반 ~150MB. 18GB RAM 여유 충분 |
+| API prefix 변경 missed 위치 (web-ui에서 일부 호출만 변경) | 일부 페이지 404 | grep 검색 (`/api/agent-office/tarot`) 후 일괄 변경 |
+| nginx restart 누락 | 라우팅 안 됨 | docker compose up -d --build → nginx 컨테이너 재시작 자동 (deployer 패턴) |
+| saju-web 코드 사라짐 (참조 못 하게 됨) | 검증 어려움 | saju-web 디렉토리는 그대로 유지 (포팅 끝나도 archive로 보존) |
+
+---
+
+## 12. 향후 (v2, 본 spec 밖)
+
+- 토정비결 (12개월 운세) — saju-lab v2에서 추가
+- 정밀 음력 + 윤달 처리 검증
+- 자동 마이그레이션 스크립트의 ON DELETE CASCADE 검토 (이력 정합성)
+- agent-office의 tarot 관련 텔레그램 명령이 있다면 그것도 saju-lab에 추가할지 검토
+- saju-lab UI 디자인 시안 확정 후 별도 짧은 plan으로 진행
+
+---
+
+## 13. 참고 자료
+
+- saju-web/PROJECT_OVERVIEW.md — 마이그레이션 원본 명세
+- web-backend/CLAUDE.md — lab 서비스 패턴 참조
+- agent-office/app/tarot/, agent-office/app/routers/tarot.py — Phase 1 이관 원본
+- web-backend/insta-lab/, music-lab/, realestate-lab/ — Dockerfile + 디렉토리 구조 참조 패턴
+- sxtwl (Python 만세력 라이브러리) — solarlunar 대체
+- docs/superpowers/specs/2026-05-23-tarot-lab-design.md — 본 작업의 직전 spec (tarot-lab 원본 설계)

docs/superpowers/specs/2026-05-26-saju-ui-design.md

@@ -0,0 +1,387 @@
+# saju-lab UI v1 — 호령 사주 페이지 설계
+
+**작성일**: 2026-05-26
+**상태**: Spec (구현 plan 작성 전)
+**전제**: saju-lab 백엔드 완성 (474 tests, SHA 8123f75) + web-ui Task 28 (api helpers + placeholder pages)
+
+---
+
+## 1. 목표
+
+사용자 시안 4종(`source/images/saju_page/horyung_saju_main.png`, `_today.png`, `_gunghab.png`, `_saju.png`) + 캐릭터 시트(`source/characters/horyung.png`) + 컬러시트(`saju_color_sheet.png`) 기반으로 web-ui `/saju/*` 페이지를 호령 마스코트와 함께 구축한다.
+
+v1 범위: **메인 / 오늘의 운세 / 사주풀이** 3개 페이지. 궁합은 v2 placeholder.
+
+---
+
+## 2. 결정된 핵심 사항
+
+| 항목 | 결정 |
+|------|------|
+| 캐릭터 자산 | horyung.png + saju_color_sheet.png에서 PNG 6개 추출 |
+| 백엔드 확장 | saju-lab에 fortune_scores + lucky + monthly_flow 산출 추가 |
+| 입력 흐름 | 메인에서 사주 1회 입력 → reading_id를 다른 페이지 URL query로 공유 |
+| v1 페이지 | 메인 + 사주풀이 + 오늘운세 (궁합은 v2) |
+| 반응형 | 데스크탑(1280+) 우선 + 태블릿 그라데이션 |
+| 컬러 | 시안 추출 — 크림 베이스 + 다크 네이비 + 골드 + 살구 + 청록 |
+| 폰트 | Pretendard (본문) + Noto Serif KR (큰 제목, Google Fonts) |
+| CSS 격리 | `.saju-page` scope (다른 페이지에 새지 않음) |
+
+---
+
+## 3. 백엔드 확장 (saju-lab)
+
+### 3-1. 신설 모듈
+
+**`saju-lab/app/calculator/fortune_scores.py`** — 4 카테고리 점수:
+
+```
+calculate_fortune_scores(saju, analysis, current_year) → {
+  wealth:  0-100  (재물운)
+  romance: 0-100  (연애운)
+  social:  0-100  (인간관계)
+  career:  0-100  (직장운)
+  overall: 0-100  (가중평균: wealth*0.3 + career*0.3 + romance*0.2 + social*0.2)
+}
+```
+
+알고리즘 (각 base 60에서 가산/감산, clamp 0-100):
+
+- **wealth**: +정재 강도 / +편재 강도 / +식상→재 통로 / -비겁 강도 / +세운재성
+- **romance**: +일지 합 / +정관·정재 균형 / -일지 충 / +세운 도화살
+- **social**: +인성 / +비겁 적정 / +식상 / +격국 균형 / +천을귀인
+- **career**: +정관 강도 / +편관 제어 / +일간 신강 / +세운 관성
+
+**`saju-lab/app/calculator/lucky.py`** — 럭키 데이터:
+
+```
+calculate_lucky(saju, analysis, target_date) → {
+  color: [str, str]   # 용신 오행 컬러 1~2개 (예: ["청록", "녹색"])
+  number: int 1-9     # (일진 천간 idx + 시진 천간 idx) % 9 + 1
+  direction: str      # 용신 오행 방향 (동/남/중앙/서/북)
+  good_signs: [str]   # 세운 천간이 일간 재성 → "재물 기회" 등
+  warnings: [str]     # 세운 지지가 일지 충 → "대인 갈등 주의"
+}
+```
+
+오행→컬러/방향 매핑은 정적 dict. 럭키 숫자는 일진+시진(시간 미상 시 일진만)으로 산출.
+
+**`saju-lab/app/calculator/monthly_flow.py`** — 12개월 운세 흐름:
+
+```
+calculate_monthly_flow(saju, year) → [
+  {month: 1, stem: "壬", branch: "寅", score: 65, label: "변동"},
+  {month: 2, stem: "癸", branch: "卯", score: 70, label: "성장"},
+  ... 12 entries
+]
+```
+
+각 월: 해당 월의 60갑자(寅월부터 12월 사이클) → 일간 관계(상생/상극/충/합) → score 0-100 + label(`변동`/`성장`/`안정`/`도전`/`정체` 등).
+
+### 3-2. `routers/saju.py` 응답 확장
+
+`SajuInterpretResponse`에 3 필드 추가:
+
+```python
+fortune_scores: dict   # {wealth, romance, social, career, overall}
+lucky: dict            # {color, number, direction, good_signs, warnings}
+monthly_flow: list[dict]  # 12 entries
+```
+
+`interpret_saju_endpoint`에서 계산 + DB 저장 + 응답 포함.
+
+### 3-3. `db.py` 스키마 마이그레이션
+
+`saju_records` 테이블에 ALTER TABLE로 3 컬럼 추가 (idempotent):
+- `fortune_scores_json TEXT`
+- `lucky_json TEXT`
+- `monthly_flow_json TEXT`
+
+`init_db()`에 try/except OperationalError 패턴 (이미 존재하면 skip).
+
+`_saju_row_to_dict`에서 3 컬럼 JSON 파싱하여 응답에 포함.
+
+### 3-4. 테스트
+
+- `test_fortune_scores.py` — 5-8 case (정재 강함 → wealth 80+, 일지 충 → romance 50-, clamp 검증)
+- `test_lucky.py` — 5 case (오행→컬러/방향 매핑, 럭키 숫자 1-9 범위)
+- `test_monthly_flow.py` — 3 case (12 entries 정확, 일간 충 월 score 낮음)
+
+기존 30 reference fixture 비교는 영향 없음 (응답에 새 필드만 추가).
+
+---
+
+## 4. 프론트엔드 구조 (web-ui)
+
+### 4-1. 디렉토리
+
+```
+web-ui/
+├── public/images/saju/
+│   ├── horyung/
+│   │   ├── horyung-front.png        # 시안 main hero용 (정면, 큰 사이즈)
+│   │   ├── horyung-bust.png         # 작은 카드용 (가슴샷)
+│   │   ├── horyung-greeting.png     # 인사 표정 (메인 좌상단)
+│   │   ├── horyung-thinking.png     # 생각하는 표정 (사주풀이)
+│   │   ├── horyung-pointing.png     # 가르치는 표정 (오늘운세)
+│   │   └── horyung-happy.png        # 기쁜 표정 (점수 높을 때)
+│   ├── frame-cloud.png              # 시안의 한국화 산 배경 (hero용)
+│   ├── pattern-cloud.svg            # 한국 전통 구름 패턴
+│   └── icons/
+│       ├── icon-today.svg
+│       ├── icon-heart.svg
+│       └── icon-book.svg
+└── src/pages/saju/
+    ├── Saju.css                     # 모든 saju 페이지 공통 스타일 (격리)
+    ├── data/
+    │   └── constants.js             # 4 카테고리 메타, 컬러 토큰
+    ├── hooks/
+    │   ├── useSajuForm.js
+    │   └── useSajuReading.js        # reading_id → fetched data + 캐시
+    ├── components/
+    │   ├── HoryungMascot.jsx
+    │   ├── SajuNav.jsx              # 시안 상단 네비게이션 (호령사주 로고 + nav)
+    │   ├── SajuInputForm.jsx
+    │   ├── ActionCard.jsx           # 3 카드 (오늘운세/궁합/사주풀이)
+    │   ├── ScoreCard.jsx            # 카테고리 점수 카드
+    │   ├── FortuneRing.jsx          # 종합점 ring SVG
+    │   ├── LuckyBox.jsx             # 럭키 컬러/숫자/방향
+    │   ├── ElementBarChart.jsx      # 오행 5색 가로 바
+    │   ├── SajuPillars.jsx          # 4기둥 8자 표시
+    │   ├── MonthlyFlow.jsx          # 12개월 운세 흐름 차트
+    │   ├── InterpretAccordion.jsx   # AI 12항목 아코디언
+    │   └── HoryungQuote.jsx         # 호령 말풍선
+    ├── Saju.jsx                     # 메인 페이지
+    ├── SajuResult.jsx               # 사주풀이 결과
+    ├── Today.jsx                    # 오늘의 운세
+    └── Compatibility.jsx            # v2 placeholder
+```
+
+### 4-2. 라우팅 (변경 없음, Task 28에서 등록됨)
+
+| 경로 | 컴포넌트 | reading_id 필요 |
+|------|---------|----------------|
+| `/saju` | Saju.jsx (메인) | 아니오 |
+| `/saju/result?rid=N` | SajuResult.jsx | 예 |
+| `/saju/today?rid=N` | Today.jsx | 예 |
+| `/saju/compatibility` | Compatibility.jsx (placeholder) | — |
+
+기존 `/saju/result` 등은 Task 28에서 placeholder로 등록 — 본 task에서 실제 컴포넌트로 교체.
+
+### 4-3. 데이터 흐름
+
+```
+[사용자] → /saju (메인)
+   ↓ 사주 입력
+   ↓ sajuInterpret(form)
+   ↓ POST /api/saju/interpret
+[saju-lab] 계산 + Claude AI + fortune_scores + lucky + monthly_flow
+   ↓ 응답: { reading_id, ... 풍부한 데이터 }
+[프론트] navigate(`/saju/result?rid=${reading_id}`)
+
+[사주풀이 페이지] /saju/result?rid=N
+   ↓ useSajuReading(N) → sajuGetReading(N)
+   ↓ GET /api/saju/readings/N
+   ↓ saju_data + analysis_data + daeun_data + interpretation_json + fortune_scores + lucky + monthly_flow
+   ↓ 렌더
+
+[오늘운세] /saju/today?rid=N — 사용자가 메인 또는 사주풀이에서 클릭
+   ↓ useSajuReading(N) + sajuCurrentFortune(N)
+   ↓ 렌더: ring + 4 score + lucky + 오늘 세운
+```
+
+### 4-4. 호령 마스코트
+
+`HoryungMascot.jsx` — `pose` prop으로 6개 PNG 중 선택.
+
+```jsx
+<HoryungMascot pose="greeting" size="lg" />     // 메인 좌상단
+<HoryungMascot pose="thinking" size="md" />      // 사주풀이
+<HoryungMascot pose="pointing" size="md" />      // 오늘운세
+<HoryungMascot pose="happy" size="sm" />         // 점수 높을 때 (옵션)
+```
+
+`onError` 핸들러로 PNG 누락 시 silent (디자인 깨짐 방지).
+
+### 4-5. CSS 격리 + 컬러 시스템
+
+`Saju.css`:
+
+```css
+.saju-page {
+  /* 베이스 */
+  --saju-cream: #FAF6EE;
+  --saju-paper: #F2EAD8;
+  --saju-ink: #2E2D45;        /* 다크 네이비 (헤더, 본문) */
+  --saju-ink-deep: #1F1D38;
+  
+  /* 액센트 */
+  --saju-gold: #D4A574;
+  --saju-gold-deep: #B5874E;
+  --saju-apricot: #C58F76;
+  --saju-rose: #D9A2A6;
+  --saju-jade: #4B7065;
+  --saju-violet: #6A5285;
+  
+  /* 카테고리 (3 ActionCard) */
+  --saju-today-bg: #4B7065;      /* 청록 (오늘운세) */
+  --saju-gunghab-bg: #A8736E;    /* 살구 (궁합) */
+  --saju-saju-bg: #4F4A78;       /* 보라 (사주풀이) */
+  
+  /* 점수 카테고리 (4 ScoreCard) */
+  --saju-wealth: #D4A574;        /* 골드 (재물) */
+  --saju-romance: #D9A2A6;       /* 로즈 (연애) */
+  --saju-social: #4B7065;        /* 청록 (인간관계) */
+  --saju-career: #6A5285;        /* 보라 (직장) */
+  
+  min-height: 100vh;
+  background: var(--saju-cream);
+  color: var(--saju-ink);
+  font-family: 'Pretendard', sans-serif;
+}
+
+.saju-page .saju-h1,
+.saju-page .saju-h2 {
+  font-family: 'Noto Serif KR', serif;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+```
+
+모든 saju 컴포넌트의 클래스는 `saju-` prefix로 시작 (다른 페이지와 격리).
+
+### 4-6. 반응형
+
+- 기준: `1280px+` 데스크탑 (시안 그대로)
+- `768~1280px` 태블릿: hero 컬럼 → 세로 스택, action card 3 → 2x2 grid
+- `~768px` 모바일: 호령 작게 (size="sm"), action card 1열, 입력 폼 세로
+
+`@media` 쿼리로 `Saju.css` 안에서 처리.
+
+### 4-7. 폰트
+
+`index.html`에 Google Fonts preconnect + Noto Serif KR 추가:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+KR:wght@500;700&display=swap" rel="stylesheet">
+```
+
+큰 제목(h1/h2)만 Noto Serif KR, 본문은 기존 Pretendard.
+
+---
+
+## 5. 컴포넌트별 세부
+
+### 5-1. Saju.jsx (메인)
+
+레이아웃 (시안 horyung_saju_main.png):
+- 상단: SajuNav (호령사주 로고 + 4 nav + "사주풀이 시작하기" 버튼)
+- Hero: 좌측 호령(front + greeting 박스) / 우측 큰 h1 + 3 ActionCard
+- Bottom: 좌측 통계 미리보기 / 우측 SajuInputForm
+
+폴백: reading_id가 query에 있으면 (`/saju?rid=N`) 통계 영역에 미리보기 점수 + 마지막 분석 결과로.
+
+### 5-2. SajuResult.jsx (사주풀이)
+
+레이아웃 (시안 horyung_saju_saju.png):
+- 상단: SajuNav + "사주풀이" 큰 타이틀 + 기본 정보 (이름, 생년월일) + 호령(thinking)
+- 중단 좌: 사주 4기둥 표 (SajuPillars) + 오행 바 차트 (ElementBarChart)
+- 중단 우: 호령의 비전 박스 (HoryungQuote — interpretation의 summary 발췌)
+- 하단: 성격강점 / 직업운 / 재물운 / 연애운 4 카드 (12항목 중 추출) + 12개월 운세 흐름 (MonthlyFlow)
+- 우하단: 이번 달 핵심 결정 포인트 (interpretation_json.advice)
+
+데이터: `useSajuReading(rid)` → saju + analysis + daeun + interpretation_json + monthly_flow
+
+### 5-3. Today.jsx (오늘의 운세)
+
+레이아웃 (시안 horyung_saju_today.png):
+- 상단: SajuNav + "오늘의 운세" 큰 타이틀 + 호령(pointing) + 풍경 배경
+- 중단: FortuneRing(overall) + 4 ScoreCard(wealth/romance/social/career) + LuckyBox
+- 하단: 행운 알림 / 위험 알림 (lucky.good_signs, lucky.warnings)
+- 최하단: 다음 페이지 (사주풀이 / 궁합보기) 버튼
+
+데이터: `useSajuReading(rid)` → fortune_scores + lucky + `sajuCurrentFortune(rid)` → 오늘 세운
+
+### 5-4. Compatibility.jsx (v2 placeholder)
+
+```jsx
+export default function Compatibility() {
+  return (
+    <div className="saju-page saju-page--compat-stub">
+      <SajuNav />
+      <div className="saju-stub">
+        <HoryungMascot pose="thinking" />
+        <h2>궁합보기는 곧 만나요!</h2>
+        <p>두 사람의 사주를 함께 풀어보는 기능을 준비 중입니다.</p>
+        <Link to="/saju">메인으로 돌아가기</Link>
+      </div>
+    </div>
+  );
+}
+```
+
+백엔드 `/api/saju/compat/*`는 이미 동작하지만 UI는 v2에서 정식 구현.
+
+---
+
+## 6. 에러 처리
+
+| 시나리오 | 처리 |
+|---------|------|
+| 메인 입력 폼 — 잘못된 날짜 | Pydantic 422 → 폼에서 "올바른 날짜를 입력해주세요" |
+| Claude API 504/500 | "잠시 후 다시 시도해주세요" + 사용자 입력 보존 |
+| reading_id 무효(404) | "사주 결과를 찾을 수 없습니다" + 메인으로 돌아가기 버튼 |
+| 호령 PNG 누락 | onError로 silent hide (디자인은 살짝 빈 자리, 동작은 정상) |
+| fortune_scores 산출 실패 (예외) | 기본값 60/60/60/60으로 fallback + 콘솔 warn |
+
+---
+
+## 7. 테스트 전략
+
+### 백엔드
+- fortune_scores: 5-8 unit test (각 카테고리 high/low 케이스 + clamp)
+- lucky: 5 unit test (오행→컬러 매핑, 숫자 1-9 범위, 방향)
+- monthly_flow: 3 unit test (12 entries, 점수 범위, 충/합 영향)
+- 기존 30 reference fixture 비교: 영향 없음 (응답 추가 필드만)
+
+### 프론트
+- 컴포넌트 단위 테스트는 v1 범위 밖 (수동 e2e 검증)
+- 로컬 e2e: `npm run dev` + 입력 → 사주풀이/오늘운세 1회 정상 동작
+- 호령 6 PNG 모두 존재 확인 (수동)
+- 반응형 — Chrome DevTools 1280/1024/768 3가지 확인
+
+---
+
+## 8. 위험 + 완화
+
+| 위험 | 완화 |
+|------|------|
+| 호령 PNG crop 좌표가 부정확 | plan 단계에서 PIL로 trial-and-error + 사용자 검수. onError로 silent fallback |
+| fortune_scores 점수 산식이 명리학적 부정확 | v1은 plausible default + base 60으로 보수적. 실사용 피드백으로 튜닝 |
+| 시안 색상과 미세 차이 | 시안 PNG에서 color picker로 hex 추출 후 CSS variable로 명시 |
+| Noto Serif KR Google Fonts 로드 지연 | display=swap로 폰트 fallback (Pretendard) → 깜빡임 최소화 |
+| reading_id 만료(DB row 삭제) | 404 graceful fallback + 새 입력 유도 |
+| Claude 응답 시간 초과 | nginx timeout 300s + 폼에서 progress 표시 |
+
+---
+
+## 9. 향후 (v2, 본 spec 밖)
+
+- 궁합보기 페이지 정식 구현 (시안 horyung_saju_gunghab.png 기반)
+- 상담안내 페이지 (nav에 있는 메뉴)
+- 즐겨찾기/히스토리 페이지 (sajuListReadings 활용)
+- 사주풀이 PDF 내보내기
+- 호령 캐릭터 lottie 애니메이션 (정적 PNG → 동적)
+
+---
+
+## 10. 참고
+
+- 시안: `source/images/saju_page/horyung_saju_{main,today,gunghab,saju}.png`
+- 캐릭터: `source/characters/horyung.png`
+- 컬러시트: `source/images/saju_page/saju_color_sheet.png`
+- 백엔드: web-backend/saju-lab/ (SHA 8123f75)
+- 직전 spec: `docs/superpowers/specs/2026-05-25-saju-tarot-lab-migration-design.md` (saju-lab 백엔드 설계)
+- web-ui Task 28 commit: e634cde (api.js + routes + IconSaju + placeholder pages)

docs/superpowers/specs/2026-05-26-saju-ui-v2-redesign-design.md

@@ -0,0 +1,415 @@
+# 호령 사주 UI v2 리디자인 — 디자인 문서
+
+- **상태**: Spec 단계 (brainstorming 종료, plan 대기)
+- **작성일**: 2026-05-26
+- **대상 저장소**: `web-ui` (React + Vite, `/saju` 라우트 트리)
+- **참조 디자인 소스**: `C:\Users\jaeoh\Desktop\workspace\source\images\saju_page\사주풀이\` (백호 사주도사 프로토타입: babel/standalone JSX 11 파일 + styles.css)
+- **선행 시스템**: saju-lab UI v1 (`web-ui/src/pages/saju/`, 호령 캐릭터 7 PNG 자산 포함)
+- **백엔드 변경 없음**: saju-lab `/api/saju/*` API는 그대로 사용
+
+---
+
+## 1. 목적 & 성공 기준
+
+### 목적
+v1의 임시 구조(컴포넌트 12개 직렬 배치, 단일 SajuNav)를 한국 전통 명리학 미학에 충실한 **풀 디자인 시스템**으로 교체. 4 라우트(`/saju`, `/saju/result`, `/saju/today`, `/saju/compatibility`)를 동시 리디자인하고 신규 `/saju/me` placeholder 추가.
+
+### 성공 기준
+1. 4 라우트가 새 디자인 토큰/컴포넌트/네비로 일관되게 동작
+2. 1024px breakpoint에서 모바일(BottomNav) ↔ 데스크탑(헤더 nav) 자동 전환
+3. `useSajuReading` hook + 기존 API 호출 0개 변경, 응답 매핑만 추가
+4. 호령 PNG 7개 자산 100% 재사용 (variant API로 추상화)
+5. v1 컴포넌트 12개 + SajuNav 제거 — 두 디자인 시스템 동시 유지 X
+6. 시각 QA: 골든 패스(메인→입력→result→today→compatibility) + 1024px ± 경계 + me placeholder 모두 정상
+
+---
+
+## 2. 미학 방향 (Aesthetic Direction)
+
+**컨셉**: *한국 전통 명리학 + 차분한 호령 캐릭터*. 디자인 프로토타입이 이미 강하게 commit한 방향을 충실히 옮긴다.
+
+### 2.1 타이포
+- **Display**: Nanum Myeongjo (weight 800, `letter-spacing: -0.02em`) — 페이지 타이틀, h1, 큰 한자
+- **Body**: Nanum Gothic (weight 400/700, `letter-spacing: -0.01em`) — 본문, 버튼, 캡션
+- **Fallback serif**: Gowun Batang
+- Google Fonts CSS 로드는 `web-ui/index.html`에 link 추가 (페이지 import 대신 — preconnect로 LCP 개선)
+- Inter/Roboto/system-ui 같은 generic AI sans는 사용 금지
+
+### 2.2 컬러 시스템 (CSS 토큰)
+디자인 프로토타입 `styles.css`의 `:root` 변수를 그대로 도입:
+
+| 토큰 | 값 | 용도 |
+|---|---|---|
+| `--navy` | `#1F2A44` | dominant body color, dark surface |
+| `--navy-deep` | `#141B30` | night-bg gradient 하단 |
+| `--navy-soft` | `#2E3B5A` | 보조 dark |
+| `--ivory` | `#F7F2E8` | paper 배경, dark surface 위 텍스트 |
+| `--ivory-soft` | `#FBF7EF` | 카드 배경 |
+| `--ivory-warm` | `#F0E9D9` | 액센트 배경 |
+| `--gold` | `#D4AF37` | sharp accent, 보더, ornament |
+| `--gold-soft` | `#E8C76B` | 활성 상태 텍스트 |
+| `--gold-dim` | `#B89530` | 비활성 골드 |
+| `--green` / `--green-soft` / `--green-bg` | 한국 전통 녹색 | 궁합 화면 accent |
+| `--purple` / `--purple-soft` / `--purple-bg` | `#6A4C7C` 계열 | 사주풀이 accent |
+| `--pink` / `--pink-deep` / `--pink-bg` | `#F2C7CD` 계열 | 보조 |
+| `--gray` / `--gray-soft` | `#6B6B6B` / `#9A968D` | 메타 텍스트 |
+| `--gray-line` / `--gray-line-strong` | 보더 |
+| `--shadow-card` / `--shadow-pop` / `--shadow-dark` | 그림자 단계 |
+
+**화면별 accent 단일 색** (팔레트 골고루 분산 안티패턴 회피):
+- 홈 (`/saju`) — navy
+- 오늘 (`/saju/today`) — gold
+- 궁합 (`/saju/compatibility`) — green
+- 사주풀이 (`/saju/result`) — purple
+- 마이 (`/saju/me`) — gray
+
+### 2.3 배경 텍스처
+- `.paper-bg` — radial gold/purple wash + 페이퍼 노이즈 (사주풀이, 오늘, 궁합, 마이)
+- `.night-bg` — 밤하늘 gradient (홈 hero)
+- `.mt-wash` — 데스크탑 헤더 산수화 SVG decoration (좌하단 + 우하단 산 outline, opacity 0.35)
+- 단색 배경은 카드 내부에서만 (`--ivory-soft`)
+
+### 2.4 차별화 요소 (UNFORGETTABLE)
+1. **OrnateFrame** — 한국 전통 더블 보더 + 4 코너 꺽쇠 SVG (`<path d="M0 4 L0 0 L4 0" />`)
+2. **MascotBubble** — 호령 발자국이 매 말풍선마다 `paw-bob` 2.4s ease infinite로 미세 bobbing
+3. **OrnamentBloom** — 골드 꽃봉오리 SVG가 모든 섹션 타이틀 좌우 ornament
+4. **TopRibbon** — 구름 SVG ribbon이 페이지 상단에 은은히
+5. **CharBox** — 사주명식 천간/지지 한자 Nanum Myeongjo 800 + 원소별 색 (목=green, 화=red, 토=earth, 금=gold, 수=blue)
+
+### 2.5 모션
+- `screenIn` 0.3s `cubic-bezier(0.16,1,0.3,1)` translateY(6→0) — 라우트 진입 fade-up
+- `paw-bob` 2.4s ease infinite — 호령 발자국
+- BottomNav 활성 항목 배경 색 전환 0.2s
+- 과한 마이크로 인터랙션 X — "페이지당 1 hero 모션" 원칙
+
+---
+
+## 3. 아키텍처 & 라우팅
+
+### 3.1 라우트 매핑
+
+| 라우트 | 디자인 화면 | 파일 | 상태 |
+|---|---|---|---|
+| `/saju` | HomeScreen | `Saju.jsx` | **교체** (v1 메인) |
+| `/saju/result?rid=N` | SajuScreen (4탭) | `SajuResult.jsx` | **교체** (v1 결과) |
+| `/saju/today?rid=N` | TodayScreen | `Today.jsx` | **교체** (v1 오늘) |
+| `/saju/compatibility` | MatchScreen | `Compatibility.jsx` | **placeholder → 본격 구현** |
+| `/saju/compatibility/result?cid=N` | (디자인에 없음) | `CompatibilityResult.jsx` | 디자인 토큰만 라이트 리스타일 |
+| `/saju/me` | MeScreen placeholder | `Me.jsx` | **신규** |
+
+라우트 수: 5 신규 진입점 + 1 sub. `routes.jsx`에 `/saju/me` lazy import 추가.
+
+### 3.2 디렉토리 구조
+
+```
+web-ui/src/pages/saju/
+├── _shell/                        # v2 디자인 시스템 + 네비
+│   ├── tokens.css                 # CSS 변수 정의
+│   ├── shell.css                  # paper-bg, night-bg, mt-wash, OrnateFrame, screenIn
+│   ├── useViewportMode.js         # 1024px breakpoint hook
+│   ├── BottomNav.jsx              # 모바일 5항목 (home/today/match/saju/me)
+│   ├── DesktopHeader.jsx          # 데스크탑 horizontal nav + 로고
+│   ├── Mascot.jsx                 # variant API: full|head|upper|greeting|thinking|pointing|happy
+│   ├── MascotBubble.jsx           # tone: ivory|navy|purple|green
+│   ├── OrnateFrame.jsx
+│   ├── OrnamentBloom.jsx
+│   ├── TopRibbon.jsx
+│   ├── TitleBlock.jsx
+│   ├── PrimaryButton.jsx          # gold inset shadow
+│   ├── GhostButton.jsx
+│   ├── Icons.jsx                  # 5 nav icon + IconPaw/IconChevron/IconSparkle/IconYinYang
+│   └── helpers/
+│       ├── daeunLabel.js          # age → 성장기/학습기/...
+│       ├── deriveTraits.js        # elements + sipsin → 6 성향
+│       └── hexA.js                # hex → rgba(x,x,x,a)
+├── Saju.jsx                       # routes 진입, useViewportMode → 분기
+├── SajuResult.jsx
+├── Today.jsx
+├── Compatibility.jsx
+├── CompatibilityResult.jsx
+├── Me.jsx
+└── views/                         # mobile/desktop 컴포넌트 분리
+    ├── home.mobile.jsx
+    ├── home.desktop.jsx
+    ├── saju.mobile.jsx            # 4탭 (basic/chart/flow/traits)
+    ├── saju.desktop.jsx           # 데스크탑은 4탭 그대로 vs 2-column 변형 — plan에서 결정
+    ├── today.mobile.jsx
+    ├── today.desktop.jsx
+    ├── match.mobile.jsx
+    └── match.desktop.jsx
+```
+
+**Me 페이지는 mobile/desktop 분리 안 함** (placeholder라 단순 — `Me.jsx` 본문에 직접 구현).
+```
+
+기존 v1 파일들:
+- `components/` 디렉토리 **전체 삭제** (SajuNav, HoryungMascot, SajuInputForm, ActionCard, SajuPillars, ElementBarChart, FortuneRing, ScoreCard, LuckyBox, InterpretAccordion, MonthlyFlow, HoryungQuote)
+- `hooks/useSajuForm.js`, `hooks/useSajuReading.js` 유지 (데이터 흐름)
+- `Saju.css` 신규 `_shell/tokens.css` + `_shell/shell.css`로 교체
+
+---
+
+## 4. 컴포넌트 명세
+
+### 4.1 `useViewportMode()`
+```js
+function useViewportMode() {
+  const [mode, setMode] = useState(() =>
+    typeof window !== 'undefined' && window.innerWidth >= 1024 ? 'desktop' : 'mobile'
+  );
+  useEffect(() => {
+    const onResize = () => {
+      const next = window.innerWidth >= 1024 ? 'desktop' : 'mobile';
+      setMode(prev => (prev === next ? prev : next));
+    };
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+  }, []);
+  return mode;
+}
+```
+- 디자인 프로토타입의 동일 hook 그대로 포팅
+- SSR 안전 (typeof window 체크) — Vite 기본 CSR이라 항상 window 존재하지만 방어
+- debounce 없음 — resize 빈도가 낮고 setState가 동일 값일 때 reflow 없음 (Object.is 비교)
+
+### 4.2 `<Mascot variant="...">`
+| variant | 매핑 PNG (기존 v1 자산) |
+|---|---|
+| `full` | `/images/saju/horyung/horyung-main.png` |
+| `head` | `/images/saju/horyung/horyung-bust.png` (얼굴 중심 crop) |
+| `upper` | `/images/saju/horyung/horyung-front.png` |
+| `greeting` | `/images/saju/horyung/horyung-greeting.png` |
+| `thinking` | `/images/saju/horyung/horyung-thinking.png` |
+| `pointing` | `/images/saju/horyung/horyung-pointing.png` |
+| `happy` | `/images/saju/horyung/horyung-happy.png` |
+
+props: `variant`, `size` (px), `style` (override). `<img loading="lazy">`.
+
+### 4.3 `<BottomNav current onChange theme>`
+- `position: fixed; bottom: 0` — iPhone frame이 아닌 실제 모바일 뷰포트의 하단
+- 5 아이템: home/today/match/saju/me. NavLink 사용으로 라우트 매핑 (`useLocation`으로 current 결정)
+- theme: `'ivory'` (paper 배경) / `'navy'` (night 배경) — backdrop-filter blur 적용
+- 활성 항목: 화면별 accent 색 배경(opacity 0.10~0.18) + 라벨 weight 700
+
+### 4.4 `<DesktopHeader>`
+- `position: sticky; top: 0; z-index: 30` — 스크롤 시 상단 고정
+- 좌측: 로고 (`壽` 한자 + "호령사주" Nanum Myeongjo)
+- 중앙: nav 5 링크 (BottomNav와 동일 항목, horizontal 배치)
+- 우측: 미사용 (향후 me 메뉴)
+- 배경: `--ivory-soft` + 하단 `--gray-line` 1px
+
+### 4.5 `<OrnateFrame children color bg radius padding double>`
+- 디자인 프로토타입 `common.jsx`의 OrnateFrame 그대로 포팅
+- `double=true`면 inset 4px 위치에 추가 보더
+- 4 코너 꺽쇠 SVG (rotate 0/90/180/270)
+
+### 4.6 `<MascotBubble text align tone tail paw>`
+- tone 팔레트 (`ivory`/`navy`/`green`/`purple`) → bg/border/text 색
+- `paw=true`면 우하단 IconPaw + `paw-bob` 애니메이션
+- `tail=true`면 풍선 꼬리 (rotate 45deg 사각형)
+
+### 4.7 Buttons
+- `PrimaryButton`: gold inset shadow (`inset 0 1px 0 rgba(212,175,55,0.4)`) + 풀 너비 옵션
+- `GhostButton`: 투명 배경 + 보더만, 동일 폰트/spacing
+
+### 4.8 `Me.jsx` (placeholder, mobile/desktop 공통)
+- `paper-bg` + `<TopRibbon>` + `<Mascot variant="thinking">` + `<MascotBubble tone="purple">` "곧 만나요" + 비활성 카드 4개 (이력/북마크/설정/문의 — disabled)
+- 뷰포트 분리 없이 단일 컴포넌트 (placeholder라 단순)
+
+### 4.9 입력 폼 컴포넌트 (Home에서 사용)
+- `<InputRow label name type ...>` — 디자인 토큰 적용된 단일 행 (label 좌측 64px + input 우측)
+- `<DateSelect>`, `<TimeSelect>`, `<GenderToggle>`, `<CalendarToggle>` (양/음력) — `useSajuForm` state와 연결
+- Phase 2에서 신설. 기존 v1 `SajuInputForm.jsx`의 검증 로직만 이식, 시각 표현은 새 디자인
+
+---
+
+## 5. 데이터 흐름
+
+### 5.1 hook 재사용
+- `useSajuReading(rid)` — 그대로 유지. `api.js`의 `sajuGetReading(id)` 호출 → `reading` 객체 반환
+- `useSajuForm()` — 그대로 유지. 입력 검증 + `sajuInterpret(body)` 호출 + navigate
+
+### 5.2 매핑 헬퍼 (`_shell/helpers/`)
+
+#### `daeunLabel(age)` → string
+- `age < 10` → "성장기"
+- `age < 20` → "학습기"
+- `age < 30` → "도전기"
+- `age < 40` → "성장기"
+- `age < 50` → "전성기"
+- `age < 60` → "안정기"
+- `age < 70` → "정리기"
+- `age >= 70` → "여유기"
+
+#### `deriveTraits(elements, sipsin)` → `[{id, ko, icon, color}]` (최대 6개)
+- 강한 원소 1~2개 → 매칭 성향:
+  - `fire >= 30` → `{id:'challenge', ko:'도전정신', color:'#C04A4A'}`
+  - `metal >= 30` → `{id:'lead', ko:'리더십', color:'#D4AF37'}`
+  - `wood >= 30` → `{id:'adapt', ko:'적응력', color:'#4E6B5C'}`
+  - `water >= 30` → `{id:'wisdom', ko:'지혜', color:'#3A5A8C'}`
+  - `earth >= 30` → `{id:'wealth', ko:'풍부함', color:'#A67B3F'}`
+- 일간 강도 (신강/신약) → `will` (의지)
+- 결과 6개 미만이면 다음으로 강한 원소 추가
+- 순서: 강한 원소 점수 내림차순
+
+#### `hexA(hex, alpha)` → `rgba(...)` 문자열
+- 디자인 프로토타입 동일 헬퍼
+
+### 5.3 SAJU_DATA mock → 실제 API 매핑 표
+
+| 디자인 mock 필드 (screen-saju.jsx) | API 응답 경로 (saju-lab) | 비고 |
+|---|---|---|
+| `name`, `birth`, `gender`, `birthTime`, `birthPlace` | `reading.input.*` | 직접 매핑 |
+| `sajuLabel` | `reading.label` | "경오년 신사월 갑자일 OO시" |
+| `ilgan` | `reading.ilgan` | `{ko, ch, element, sound}` |
+| `pillars[]` | `reading.pillars` | year/month/day/hour 4기둥 |
+| `pillars[].cheongan.color` | 원소→색 매핑 (`elementColor()`) | wood=green, fire=red, earth=earth, metal=gold, water=blue |
+| `pillars[].sipsin`, `jijang` | `reading.pillars[i].sipsin`, `jijang` | |
+| `ohaeng[]` | `reading.analysis.elements` | `{wood, fire, earth, metal, water}` → `[{id, ko, ch, value, color}]` 변환 |
+| `daeun[]` | `reading.daeun` (8개) | `label`은 `daeunLabel(age)` 헬퍼, `current`는 현재 나이 기반 derive |
+| `traits[]` | `deriveTraits(elements, sipsin)` | 헬퍼로 derive (API 응답에 직접 없음) |
+| TraitsTab `title`, `desc` | 상위 3 성향 → 정적 desc 사전 매핑 | YAGNI: 백엔드에 trait description 추가는 향후 작업 |
+| Today: `fortune_scores`, `lucky`, `monthly_flow` | API 응답에 이미 존재 | 그대로 사용 |
+
+### 5.4 BottomNav active state
+```jsx
+const { pathname } = useLocation();
+const current =
+  pathname === '/saju' ? 'home'
+  : pathname.startsWith('/saju/today') ? 'today'
+  : pathname.startsWith('/saju/compatibility') ? 'match'
+  : pathname.startsWith('/saju/result') ? 'saju'
+  : pathname.startsWith('/saju/me') ? 'me'
+  : 'home';
+```
+
+---
+
+## 6. 반응형 & 네비게이션 전략
+
+### 6.1 1024px breakpoint
+- `< 1024px` → 모바일: 페이지 컴포넌트가 `<MobileXxx>` 렌더, `<BottomNav>` 표시
+- `>= 1024px` → 데스크탑: `<DesktopXxx>` 렌더, `<DesktopHeader>` 표시
+- 페이지 진입 시 `useViewportMode()`가 결정. resize 시 동적 전환
+
+### 6.2 iPhone frame 제거
+- 디자인 프로토타입은 모바일 미리보기용으로 iPhone 외곽선을 그렸으나 실제 모바일 디바이스는 OS frame이 있으므로 frame DOM 제거
+- StatusBar(`BrandStatusBar`)도 미사용 — 실제 디바이스 status bar 자연스럽게 사용
+
+### 6.3 컨테이너 max-width
+- 모바일: `100%` (BottomNav만 fixed)
+- 데스크탑: 콘텐츠 max-width 1200px, `margin: 0 auto`. mt-wash 배경은 viewport 풀
+
+### 6.4 transition between modes
+- 1024px 경계에서 mode 변경 시 컴포넌트가 unmount → 새 컴포넌트 mount → screenIn 0.3s 재생
+- 폼 입력 중 transition 발생 시: useSajuForm 상태는 hook이 보관하므로 데이터 유실 X
+
+---
+
+## 7. 점진적 구현 단계 (Phase Plan)
+
+각 Phase 끝에 `npm run dev`로 `http://localhost:3007/saju` 시각 확인 + git commit. PR은 Phase 1~3, 4~5, 6 (fixup) 3개로 분할 권장.
+
+| Phase | 산출물 | 검증 |
+|---|---|---|
+| **1. Shell + 토큰** | `_shell/` 전체 + `Me.jsx` + 라우트 `/saju/me` 추가 + Google Fonts link | `/saju/me` 진입 시 placeholder + BottomNav/Header 모두 정상. 기존 4 페이지 무손상 |
+| **2. Home** | `Saju.jsx` + `views/home.{mobile,desktop}.jsx` + 입력 폼 + 호령 hero | 모바일/데스크탑 모두 입력 → submit → `/saju/result?rid=N` 이동 |
+| **3. SajuResult** | `SajuResult.jsx` + `views/saju.{mobile,desktop}.jsx` 4탭 + 매핑 헬퍼 | 실제 reading 데이터로 4탭 모두 정상 표시. 일간 표시·오행 막대·대운 흐름·성향 derive 검증 |
+| **4. Today** | `Today.jsx` + `views/today.{mobile,desktop}.jsx` | fortune_scores·lucky·monthly_flow 표시. PrimaryButton "다른 운세 보기" → SajuResult 이동 |
+| **5. Compatibility** | `Compatibility.jsx` + `views/match.{mobile,desktop}.jsx` 본격 구현. `CompatibilityResult.jsx` 라이트 리스타일 | 두 사람 입력 폼 + compat API 호출 + 결과 화면 |
+| **6. QA + cleanup** | v1 `components/` 삭제, `Saju.css` 제거, 시각 QA, 1024px 경계 chrome devtools | 골든 패스 통과, dead code 없음 |
+
+---
+
+## 8. 에러 / 빈 상태
+
+| 상황 | UI |
+|---|---|
+| API 실패 (네트워크/500) | `<OrnateFrame color="--purple">` + `<MascotBubble tone="purple">` "아이고, 다시 시도해주세요" + `<GhostButton>` 새로고침 |
+| `?rid=` 없이 `/saju/result` 직접 진입 | `<MascotBubble tone="ivory">` "사주를 먼저 입력해주세요" + `<PrimaryButton color="--purple">` "사주 입력하러 가기" → `/saju` |
+| `?rid=` 없이 `/saju/today` 직접 진입 | 동일 패턴, accent gold |
+| `?cid=` 없이 `/saju/compatibility/result` 진입 | 동일 패턴, accent green |
+| `/saju/me` | `<MascotBubble tone="purple">` "곧 만나요" + 비활성 placeholder 카드 4개 |
+| 백엔드 timeout (사주 해석 30~60초) | 로딩 화면: `<Mascot variant="thinking">` + `<MascotBubble>` "호령이 풀이 중이에요..." + spinner |
+
+---
+
+## 9. 검증 전략
+
+### 9.1 자동 테스트
+- `useViewportMode.test.js` — `vi.mock` window.innerWidth + resize 이벤트 dispatch, 1023/1024 경계 변환 확인
+- `daeunLabel.test.js` — 8 구간 모두 정답 매핑
+- `deriveTraits.test.js` — 강한 원소 1~5개 입력에 대한 정렬·중복 제거 확인
+- `Mascot.test.jsx` — 7 variant 모두 올바른 src prop
+
+### 9.2 시각 검증 (Phase 마다 dev server)
+1. `npm run dev` → `http://localhost:3007/saju` 진입
+2. 모바일 chrome devtools (375×667 iPhone SE, 390×844 iPhone 12)
+3. 데스크탑 (1280×720 이상)
+4. 1024px 경계 ± 1px (1023↔1024)에서 mode 전환 확인
+5. 5 라우트 모두 BottomNav active 상태 + DesktopHeader active 상태 일치
+6. 호령 PNG 7 variant 모두 로드 확인 (Network 탭)
+7. 폰트 로드 (Nanum Myeongjo, Nanum Gothic, Gowun Batang)
+
+### 9.3 회귀
+- 기존 reading_id URL 호환 (`/saju/result?rid=N` 패턴 유지)
+- `useSajuReading` hook 응답 매핑이 v1과 동일 데이터 표시
+- saju-lab API 호출 0개 변경 (네트워크 탭 비교)
+
+---
+
+## 10. YAGNI 명시 제외
+
+다음은 이번 v2에서 의도적으로 **제외**:
+- i18n / 다국어
+- 다크모드 토글 (디자인 자체가 화면별 light/dark scope 고정)
+- 호령 마스코트 드래그·물리 모션 (paw-bob bobbing만)
+- BottomNav 햅틱·진동
+- 인증/로그인 (Me는 placeholder, 향후 별도 spec)
+- PWA / 오프라인 캐시
+- 백엔드 trait description API (`deriveTraits` 프론트 헬퍼로 충분)
+- 디자인 프로토타입의 desktop-shell.jsx full conversion — DesktopHeader만 차용, shell 전체는 v2 컨테이너에 흡수
+
+---
+
+## 11. 마이그레이션 노트
+
+### 11.1 삭제 대상 (Phase 6에서 일괄 정리)
+- `web-ui/src/pages/saju/components/` 전체 12 파일
+- `web-ui/src/pages/saju/Saju.css`
+- v1 `Compatibility.jsx`의 placeholder 본문 (본격 구현으로 교체)
+
+### 11.2 보존 대상
+- `web-ui/src/pages/saju/hooks/useSajuForm.js`, `useSajuReading.js` (데이터 흐름)
+- `web-ui/public/images/saju/horyung/` 7 PNG 자산 (Mascot variant API가 매핑)
+- `web-ui/src/api.js` saju 헬퍼 함수들
+
+### 11.3 routes.jsx 변경
+기존 import 라인 유지 + Me lazy import 추가:
+```diff
++ const SajuMe = lazy(() => import('./pages/saju/Me'));
+```
+`children` 배열에 me 라우트 추가:
+```diff
+  path: '/saju',
+  children: [
+    { index: true, element: <Saju /> },
+    { path: 'result', element: <SajuResult /> },
+    { path: 'today', element: <SajuToday /> },
+    { path: 'compatibility', element: <Compatibility /> },
+    { path: 'compatibility/result', element: <CompatibilityResult /> },
++   { path: 'me', element: <SajuMe /> },
+  ],
+```
+
+---
+
+## 12. Plan 단계로 넘길 결정 사항
+
+다음은 plan 작성 시 구체화:
+- 각 view 파일별 line budget (현실적 500~800 라인 예상, 더 크면 sub 컴포넌트 분할)
+- 색→원소 매핑 함수 (`elementColor(elementId)`) 위치 — `_shell/helpers/` vs view 안 인라인
+- 데스크탑 `saju.desktop.jsx`의 4탭 유지 vs 2-column 변형 (디자인 프로토타입의 `desktop-saju.jsx` 상세 검토 후 결정)
+- 데스크탑 헤더의 me 메뉴 (향후 인증 위치 — 현재는 nav 5번째 링크)
+- 시각 QA 시 사용자 직접 확인 단계 (Claude가 puppeteer로 자동화하지 않음 — 시각 판단은 사람)
+- `<InputRow>` 등 입력 컴포넌트의 상세 props 시그니처

docs/superpowers/specs/2026-05-28-agent-office-docker-logs-design.md

@@ -0,0 +1,362 @@
+# Agent Office — Docker 로그 기반 통합 타임라인 설계
+
+> 작성일: 2026-05-28
+> 대상: web-backend (5개 lab + agent-office) + web-ui (LogTab)
+
+## 배경
+
+`/agent-office` 의 각 에이전트 상세 패널에 노출되는 **로그 탭** 이 현재는 의미가 빈약하다.
+- 노출 소스는 `agent-office` 의 자체 SQLite `agent_logs` 테이블 한 곳뿐.
+- `base.py BaseAgent.transition()` 가 매번 `State: idle -> working ({detail})` 형식 자동 로그를 기록 — 사용자가 실제로 무슨 일이 일어났는지 파악하기 어려운 노이즈가 다수.
+- 각 에이전트가 실제로 호출하는 외부 서비스 컨테이너 (lotto / stock / music-lab / insta-lab / realestate-lab) 의 docker stdout 은 LogTab 에 한 줄도 흐르지 않는다.
+
+따라서 LogTab 에서는 “이 에이전트가 어떤 API 를 불러서 어떤 응답을 받았는지” “외부 서비스에서 어떤 비즈니스 이벤트가 발생했는지” 가 보이지 않는다.
+
+## 목표
+
+1. 각 에이전트 LogTab 에 **해당 서비스 컨테이너의 의미 있는 docker 로그** 를 흘려보낸다.
+2. healthcheck / static / OPTIONS 같은 노이즈 로그는 **서버 측에서 미리 차단** 한다.
+3. API 호출 한 줄 (`POST /api/lotto/recommend → 200 142ms`) 과 비즈니스 이벤트 (`수집 완료: new=12, total=340`) 양쪽 모두 표시한다.
+4. 에이전트 내부 동작 로그 (`agent_logs` DB) 와 서비스 로그를 **한 화면에 시간순으로 통합** 한다.
+5. `State: idle -> working` 형식 자동 transition 로그는 제거한다.
+
+## 비목표
+
+- 실시간 WebSocket push (지금은 5초 폴링이면 충분).
+- 컨테이너 외부 (NAS 호스트, Windows AI 서버) 로그 수집.
+- 로그 검색 / 필터 UI (당장은 단순 시간순 표시).
+- 다른 lab (image-lab / tarot-lab / saju-lab / packs-lab / video-lab) 은 1차 범위에서 제외 — 5개 활성 에이전트가 가리키는 5개 컨테이너만 다룬다.
+
+## 결정사항 요약
+
+| 항목 | 결정 |
+|---|---|
+| 수집 방식 | 각 서비스가 `/logs/recent` 엔드포인트 노출 + agent-office 가 polling |
+| 표시 방식 | 통합 타임라인 (agent 로그 + service 로그 시간순 merge) |
+| 로그 범위 | 액세스 로그 (healthcheck 제외) + 비즈니스 이벤트 (logger.info/warning/error) |
+| ring buffer 크기 | 컨테이너당 500개, in-memory deque |
+| docker logs retention | `max-size 10m × max-file 3` = 서비스당 30MB |
+| agent_logs DB retention | **90일** (매일 03:00 cleanup) |
+| state 자동 로그 | 제거 (`base.py BaseAgent.transition()` 의 `add_log("State: ...")`) |
+| 자동 수집 메커니즘 | Python `logging.Handler` 를 BufferLogHandler 로 등록 — 기존 logger.info/warning/error 호출이 자동으로 ring buffer 에 흐름 |
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  web-ui (LogTab)                                            │
+│   ─ GET /api/agent-office/agents/{id}/logs?limit=N         │
+│   ─ 5초 폴링 (기존 refreshTrigger 흐름 재활용)               │
+│   ─ source 뱃지 표시 (access | log | agent)                 │
+└─────────────────────────────────────────────────────────────┘
+                          ▲
+                          │ 통합 타임라인 (시간순 merge)
+                          │
+┌─────────────────────────────────────────────────────────────┐
+│  agent-office                                               │
+│   - get_merged_logs(agent_id, limit) =                      │
+│       agent_logs (state 로그 제외)                          │
+│       + service_proxy.fetch_logs(container, path_prefix)    │
+│       → ts 기준 정렬 → 최근 N개                              │
+│   - 매핑: AGENT_CONTAINER_MAP                                │
+│        stock      → ("stock",          "/api/(stock|trade|portfolio)") │
+│        music      → ("music-lab",      "/api/music")        │
+│        insta      → ("insta-lab",      "/api/insta")        │
+│        realestate → ("realestate-lab", "/api/realestate")   │
+│        lotto      → ("lotto-backend",  "/api/lotto")        │
+└─────────────────────────────────────────────────────────────┘
+                          ▲
+                          │ GET http://{container}:{port}/logs/recent
+                          │ ?since=ISO&limit=N&path_prefix=...
+                          │ (내부 docker 네트워크 only, nginx public 라우팅 X)
+                          │
+┌─────────────────────────────────────────────────────────────┐
+│  각 서비스 컨테이너 (5개)                                     │
+│  공용 모듈 _shared/access_log.py:                            │
+│   - LogBuffer: collections.deque(maxlen=500)                │
+│   - AccessLogMiddleware: 모든 요청 후 한 줄 기록              │
+│       제외: /health /healthz /ping /favicon /docs /redoc    │
+│              /openapi.json /logs/recent OPTIONS HEAD        │
+│   - BufferLogHandler: logger.info/warning/error 자동 캡처   │
+│   - /logs/recent 라우터                                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 공용 모듈 — `web-backend/_shared/access_log.py`
+
+```python
+from collections import deque
+from datetime import datetime
+from fastapi import APIRouter, Request
+from starlette.middleware.base import BaseHTTPMiddleware
+import logging
+import time
+
+_BUFFER = deque(maxlen=500)
+
+EXCLUDED_PATHS = {"/health", "/healthz", "/ping", "/favicon.ico",
+                  "/docs", "/redoc", "/openapi.json", "/logs/recent"}
+EXCLUDED_PREFIXES = ("/static/",)
+EXCLUDED_METHODS = {"OPTIONS", "HEAD"}
+
+
+def _should_log(request: Request) -> bool:
+    if request.method in EXCLUDED_METHODS:
+        return False
+    path = request.url.path
+    if path in EXCLUDED_PATHS:
+        return False
+    if any(path.startswith(p) for p in EXCLUDED_PREFIXES):
+        return False
+    return True
+
+
+class AccessLogMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        start = time.time()
+        response = await call_next(request)
+        if not _should_log(request):
+            return response
+        elapsed_ms = int((time.time() - start) * 1000)
+        status = response.status_code
+        _BUFFER.append({
+            "ts": datetime.utcnow().isoformat() + "Z",
+            "level": "info" if status < 400 else
+                     "warning" if status < 500 else "error",
+            "source": "access",
+            "method": request.method,
+            "path": request.url.path,
+            "status": status,
+            "ms": elapsed_ms,
+            "message": f"{request.method} {request.url.path} → {status} ({elapsed_ms}ms)",
+        })
+        return response
+
+
+class BufferLogHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            _BUFFER.append({
+                "ts": datetime.utcfromtimestamp(record.created).isoformat() + "Z",
+                "level": record.levelname.lower(),
+                "source": "log",
+                "logger": record.name,
+                "message": record.getMessage(),
+            })
+        except Exception:
+            pass
+
+
+router = APIRouter()
+
+
+@router.get("/logs/recent")
+def logs_recent(limit: int = 200, since: str | None = None,
+                path_prefix: str | None = None):
+    items = list(_BUFFER)
+    if since:
+        items = [x for x in items if x["ts"] > since]
+    if path_prefix:
+        items = [x for x in items
+                 if x["source"] == "log" or x.get("path", "").startswith(path_prefix)]
+    return {"logs": items[-limit:]}
+
+
+def install(app, logger_root: str = ""):
+    """서비스 main.py 가 호출하는 단일 설치 함수."""
+    app.add_middleware(AccessLogMiddleware)
+    app.include_router(router)
+    logging.getLogger(logger_root).addHandler(BufferLogHandler())
+```
+
+### 각 서비스 main.py 적용
+
+```python
+from _shared.access_log import install as install_access_log
+install_access_log(app)
+```
+
+## docker-compose 변경
+
+5개 서비스 (`lotto-backend`, `stock`, `music-lab`, `insta-lab`, `realestate-lab`) 에 동일 패턴 추가:
+
+```yaml
+environment:
+  - PYTHONPATH=/app:/shared
+volumes:
+  - ../_shared:/shared:ro
+logging:
+  driver: "json-file"
+  options:
+    max-size: "10m"
+    max-file: "3"
+```
+
+`/logs/recent` 는 **nginx default.conf 의 public location 블록에 추가하지 않는다**. 내부 docker 네트워크에서 `http://{container_name}:{port}/logs/recent` 로만 접근.
+
+## agent-office 측 변경
+
+### `app/constants.py`
+```python
+AGENT_CONTAINER_MAP = {
+    "stock":      ("stock",          8000, r"^/api/(stock|trade|portfolio)"),
+    "music":      ("music-lab",      8000, r"^/api/music"),
+    "insta":      ("insta-lab",      8000, r"^/api/insta"),
+    "realestate": ("realestate-lab", 8000, r"^/api/realestate"),
+    "lotto":      ("lotto-backend",  8000, r"^/api/lotto"),
+}
+```
+
+### `app/service_proxy.py`
+```python
+async def fetch_service_logs(agent_id: str, since: str | None = None,
+                             limit: int = 200) -> list[dict]:
+    mapping = AGENT_CONTAINER_MAP.get(agent_id)
+    if not mapping:
+        return []
+    host, port, path_re = mapping
+    url = f"http://{host}:{port}/logs/recent"
+    params = {"limit": limit}
+    if since:
+        params["since"] = since
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as client:
+            resp = await client.get(url, params=params)
+            data = resp.json().get("logs", [])
+    except Exception as e:
+        logger.warning("fetch_service_logs(%s) 실패: %s", agent_id, e)
+        return []
+    # path_prefix 필터: access 로그만 path_re 검증
+    return [x for x in data if x["source"] == "log"
+            or re.match(path_re, x.get("path", ""))]
+```
+
+### `app/db.py`
+```python
+def get_logs(agent_id: str, limit: int = 50) -> list[dict]:
+    # 'State: ...' 자동 로그 제외 (사용자 요청)
+    rows = conn.execute("""
+        SELECT * FROM agent_logs
+        WHERE agent_id=?
+          AND message NOT LIKE 'State: %'
+        ORDER BY created_at DESC LIMIT ?
+    """, (agent_id, limit)).fetchall()
+    return [...]
+
+def delete_old_logs(days: int = 90) -> int:
+    cutoff = (datetime.utcnow() - timedelta(days=days)).isoformat()
+    with _conn() as conn:
+        c = conn.execute("DELETE FROM agent_logs WHERE created_at < ?", (cutoff,))
+        return c.rowcount
+```
+
+### `app/main.py`
+```python
+@app.get("/api/agent-office/agents/{agent_id}/logs")
+async def agent_logs(agent_id: str, limit: int = 50):
+    agent_items = get_logs(agent_id, limit=limit)
+    service_items = await fetch_service_logs(agent_id, limit=limit)
+    merged = sorted(agent_items + service_items,
+                    key=lambda x: x.get("ts") or x.get("created_at"),
+                    reverse=True)[:limit]
+    return {"logs": merged}
+```
+
+### `app/agents/base.py`
+```python
+async def transition(self, new_state, detail="", task_id=None):
+    # add_log(... "State: ...") 호출 삭제 — 사용자 요청
+    ...
+    # ws_manager 알림은 유지
+```
+
+### `app/scheduler.py`
+```python
+scheduler.add_job(
+    lambda: delete_old_logs(days=90),
+    CronTrigger(hour=3, minute=0),
+    id="cleanup_old_logs",
+)
+```
+
+## web-ui 측 변경
+
+### `src/pages/agent-office/components/LogTab.jsx`
+- log row schema 가 두 가지로 늘어남: agent_logs `{level, message, created_at}` vs service `{ts, level, source, method, path, status, ms, message}`.
+- source 뱃지를 추가로 표시: `[ACCESS]` / `[LOG]` / `[AGENT]`.
+- access 로그는 method + path + status + ms 를 보조 라인으로 표시.
+
+색상 가이드:
+- `source=access` 청록 (#5eead4)
+- `source=log` 파랑 (#60a5fa)
+- `level=warning` 노랑 (#fbbf24)
+- `level=error` 빨강 (#ef4444)
+- `source=agent` (agent_logs) 회색 (#9ca3af)
+
+## Phase 분리
+
+대규모 변경이라 단일 PR 위험. 3단계로 나눠 진행.
+
+### Phase 1 — PoC (가장 우선)
+1. `web-backend/_shared/access_log.py` 신설.
+2. `web-backend/lotto/app/main.py` 한 곳에만 `install_access_log(app)` 추가.
+3. `web-backend/docker-compose.yml` 의 `lotto-backend` 서비스에 PYTHONPATH + volume + logging 추가.
+4. `agent-office` 측 `service_proxy.fetch_service_logs()` + `AGENT_CONTAINER_MAP` (lotto 만) + `get_logs(agent_id)` merge.
+5. `LogTab.jsx` 가 source 뱃지를 표시하도록 확장.
+6. base.py `State: ...` 자동 로그 제거 + `db.get_logs()` NOT LIKE 필터 추가.
+
+검증: `/agent-office` 에서 lotto 에이전트 선택 → LogTab 에 `POST /api/lotto/...` 한 줄과 기존 logger.info 출력이 같이 보이는지.
+
+### Phase 2 — 4개 서비스 확장
+1. stock / music-lab / insta-lab / realestate-lab 의 `main.py` 에 `install_access_log(app)` 추가.
+2. docker-compose 4개 서비스 동일 패턴 적용.
+3. `AGENT_CONTAINER_MAP` 에 4개 매핑 추가.
+4. `delete_old_logs` cleanup job 등록.
+
+검증: 5개 에이전트 모두 LogTab 에서 의미 있는 로그 노출.
+
+### Phase 3 — 비즈니스 이벤트 보강
+디자인 4/5 의 "추가 권장" 표 항목들을 `logger.info(...)` 한 줄씩 추가. 약 10–15줄.
+- stock: Order 응답, AI Coach 호출, 스크리너 결과
+- music-lab: 생성 시작/완료
+- insta-lab: 키워드 추출 완료, 슬레이트 생성 완료, 발행 결과
+- lotto-backend: AI 큐레이터 호출/응답, 점수 계산 완료
+
+## 알려진 위험과 완화
+
+| 위험 | 완화 |
+|---|---|
+| `/logs/recent` 가 외부로 노출되면 access pattern + 내부 동작 노출 | nginx public location 에 등재하지 않음 + 내부 docker 네트워크만 |
+| 각 서비스의 logger 가 propagate 설정이 달라 BufferLogHandler 에 안 흐를 가능성 | `install()` 에서 `logging.getLogger("")` (root) 에 핸들러 등록 — 모든 child logger 가 자동 전파 |
+| BufferLogHandler 의 `emit()` 가 다른 핸들러의 포맷팅에 영향 | `Handler.emit` 만 override, formatter 사용 안 함 |
+| ring buffer 가 0.5초당 수십 건 트래픽으로 가득 차서 30초 분량밖에 안 남음 | 500개는 평소 트래픽 기준 1시간 이상 보관. 모니터링하다 부족하면 1000 으로 상향 |
+| `lotto-backend` 컨테이너의 personal/blog/todo API 가 lotto 에이전트 로그에 섞임 | `AGENT_CONTAINER_MAP` 의 path_prefix 정규식으로 `/api/lotto` 만 매칭 — 다른 prefix 는 자연스럽게 필터 |
+| docker-compose volume `../_shared:/shared:ro` 가 NAS 운영 환경에서 경로 차이로 깨질 가능성 | repo 의 상대경로 (`../_shared`) 는 NAS 의 `/volume1/docker/webpage/backend/_shared` 와 동일 구조로 git pull 됨. Gitea webhook 으로 push 되는 경로에 `_shared/` 디렉토리도 함께 포함됨을 deployer rsync 시 검증 |
+
+## 변경 파일 요약
+
+```
+■ 신설
+  web-backend/_shared/__init__.py
+  web-backend/_shared/access_log.py
+
+■ web-backend
+  lotto/app/main.py                + install_access_log + 추가 logger.info 3–4개 (Phase 3)
+  stock/app/main.py                + install_access_log + 추가 logger.info 3개 (Phase 3)
+  music-lab/app/main.py            + install_access_log + 추가 logger.info 2개 (Phase 3)
+  insta-lab/app/main.py            + install_access_log + 추가 logger.info 3개 (Phase 3)
+  realestate-lab/app/main.py       + install_access_log (Phase 3 추가 없음)
+  docker-compose.yml               5개 서비스 PYTHONPATH/volume/logging 추가
+
+■ web-backend/agent-office
+  app/service_proxy.py             + fetch_service_logs(agent_id, ...)
+  app/main.py                      agent_logs 엔드포인트가 merge 사용
+  app/db.py                        + delete_old_logs + get_logs NOT LIKE 'State: %'
+  app/scheduler.py                 + 매일 03:00 cleanup job
+  app/agents/base.py               transition() 의 add_log('State: ...') 제거
+  app/constants.py                 + AGENT_CONTAINER_MAP
+
+■ web-ui
+  src/pages/agent-office/components/LogTab.jsx
+                                   source 뱃지 + access 로그 method/status/ms 표시
+```

docs/superpowers/specs/2026-05-31-lotto-self-learning-backtest-design.md

@@ -0,0 +1,191 @@
+# 로또 자가학습 백테스트 & 캘리브레이션 — 설계 Spec
+
+- **작성일**: 2026-05-31
+- **상태**: 설계 승인 (구현 plan 대기)
+- **대상 서비스**: `lotto` (lotto-lab) + `agent-office` (LottoAgent) + `web-ui` (/lotto 자율학습 탭)
+- **사이클**: 스마트 에이전트 고도화 3종(로또/주식/인스타) 중 **1번 로또**. 주식·인스타는 후속 사이클.
+
+---
+
+## 1. 배경 & 목표
+
+사용자(CEO)는 로또 에이전트를 "분석 번호를 계속 가상구매해 시도횟수를 늘리고, 실제 당첨조합을 역분석해 스스로 학습·디벨롭하며 일요일에 회고 브리핑하는 스마트 에이전트"로 고도화하길 원한다. 명시 목표는 "로또 1등".
+
+### ⚠️ 정직성 전제 (설계의 토대)
+로또는 매 회차 균등·독립 추첨이다. C(45,6)=8,145,060 조합이 전부 동일 확률이며 회차 간 독립이다. 따라서:
+- **과거 데이터(빈도·갭·공동출현)의 미래 예측력은 수학적으로 0.** 통계 분석으로 1등 확률을 올릴 수 없다.
+- 고정 예산 N장으로 1등 확률을 최대화하는 유일한 방법은 **서로 다른(distinct) 조합 N개**를 사는 것이다.
+
+이 사실을 부정하지 않고 **시스템에 내장**한다. 본 프로젝트의 가치는 "예측"이 아니라:
+1. **정직한 측정** — "내 분석 엔진이 무작위를 이기는가?"를 null-model 대조군으로 매번 엄밀히 검정.
+2. **자가학습 엔진 인프라** — 측정→학습→회고 루프 자체의 엔지니어링.
+3. **커버리지 최적화** — 1등이 목표라면 distinct 조합 커버리지 최대화가 수학적 최적.
+
+→ 사용자 결정(2026-05-31): **"정직한 측정 + 커버리지 최적"** 프레이밍 채택. 패턴 학습은 계속하되 모든 백테스트에 null-model 베이스라인을 내장한다.
+
+### 기존 자산 (100% 재활용, 신규 ML 없음)
+- `analyzer.build_analysis_cache(draws)` / `score_combination(numbers, cache, weights)` — 임의 조합의 5개 sub-score + 종합점수(0~1) = **"분석치"**.
+- `analyzer.build_number_weights` + `utils.weighted_sample_6` — 가중 후보 생성.
+- `generator.run_simulation` — 20k 후보를 `score_combination(·, active_weights)`로 랭킹→best_picks. **W가 선택을 바꾸는 경로가 이미 존재.**
+- `weight_evolver` — 토 22:00 주간 6 가중치 후보 채점→base 갱신.
+
+### 발견된 잠재 결함 (본 작업으로 수정)
+`weight_evolver.apply_today_and_pick`은 `recommend_numbers(draws)`(W 미사용)로 픽을 뽑은 뒤 W로 점수만 매긴다. 즉 **현재 daily 픽은 W와 무관**하고, evolver가 평가하는 매칭 결과도 W-독립이라 가중치 진화가 픽 품질에 연결돼 있지 않다. → forward 가상구매를 **시뮬레이션 선택 경로(풀 생성→W 랭킹→상위 K 구매)**로 구현하면 W가 결과를 실제로 바꿔 가중치 학습이 비로소 의미를 갖고 이 결함도 해소된다.
+
+---
+
+## 2. 핵심 개념 — Self-Learning Backtest Loop
+
+세 축으로 구성:
+
+### 축 A — Forward 가상구매 (매주, 회차당 수천 장)
+매 회차 추첨 후, 각 전략별로 대량 후보를 생성·랭킹해 상위 K장을 "구매"로 간주 → 실제 당첨번호로 채점 → **회차별 집계 1행만 영구 저장**. 개별 티켓 미저장.
+- 전략: `engine_w`(6개 trial 가중치 각각) / `random_null`(무작위 대조군) / `coverage`(distinct 최대화).
+- 이 매칭 결과가 evolver의 학습 신호가 된다.
+
+### 축 B — Winner 캘리브레이션 (역대 전체 백필 + 매주 증분)
+각 회차의 **실제 당첨조합을 그 시점 이전 데이터로 만든 캐시(point-in-time)에 넣어** 5개 분석치 + 종합점수 + percentile을 기록.
+- percentile = 당첨조합 score_total이 그 시점 무작위 M개 표본 분포에서 차지하는 위치.
+- "내 엔진이 실제 당첨번호에 높은 점수를 주는가?"의 가장 정직한 신호. 당첨조합이 일관되게 낮은 percentile이면 엔진은 헛다리.
+
+### 축 C — 일요일 회고 브리핑
+토 추첨(20:45)→동기화(21:10)→기존 evolver 리포트(토 22:15) 이후, **일 09:00**에 차분히 회고. 이번 회차 forward 성적 + 당첨조합 역분석 + 내 추천과 비교 + 캘리브레이션 추세 + 가중치 진화를 텔레그램 1통 + UI.
+
+---
+
+## 3. 데이터 모델 (lotto.db 신규)
+
+집계 전용 — row 수 ≈ 회차 × 전략 (수천 규모, 무시 가능).
+
+### `backtest_runs` — forward 가상구매 집계
+```
+id            INTEGER PK
+draw_no       INTEGER NOT NULL          -- 채점 대상(당첨 확정된) 회차
+strategy      TEXT NOT NULL             -- 'engine_w' | 'random_null' | 'coverage'
+weight_label  TEXT NOT NULL             -- engine_w는 trial day_of_week('w0'..'w5'), 그 외 '-'
+weight_json   TEXT                      -- 사용한 W (random/coverage는 NULL)
+trial_id      INTEGER                   -- FK weight_trials (engine_w만, nullable)
+n_tickets     INTEGER NOT NULL          -- 구매(채점) 장수
+m3            INTEGER NOT NULL DEFAULT 0 -- 3개 일치 장수
+m4            INTEGER NOT NULL DEFAULT 0
+m5            INTEGER NOT NULL DEFAULT 0
+m6            INTEGER NOT NULL DEFAULT 0
+bonus_hits    INTEGER NOT NULL DEFAULT 0 -- 5+보너스(2등) 장수
+best_match    INTEGER NOT NULL DEFAULT 0
+avg_meta_score REAL                     -- 구매 티켓 평균 분석치
+created_at    TEXT NOT NULL
+UNIQUE(draw_no, strategy, weight_label)  -- 멱등
+```
+- 등수 매핑: 1등=m6, 2등=bonus_hits, 3등=m5−bonus_hits, 4등=m4, 5등=m3.
+
+### `winner_calibration` — 회차별 당첨조합 역분석
+```
+draw_no          INTEGER PK             -- 멱등
+winning_json     TEXT NOT NULL          -- [n1..n6] (보너스 별도 보관 안 함)
+score_total      REAL NOT NULL
+score_frequency  REAL NOT NULL
+score_fingerprint REAL NOT NULL
+score_gap        REAL NOT NULL
+score_cooccur    REAL NOT NULL
+score_diversity  REAL NOT NULL
+percentile       REAL                   -- 0~1, 무작위 M표본 대비 당첨조합 점수 위치
+my_pick_avg      REAL                   -- 그 회차 engine 추천 평균 분석치(있으면)
+cache_draws      INTEGER NOT NULL        -- point-in-time 캐시에 쓰인 회차 수
+created_at       TEXT NOT NULL
+```
+
+> 누적 성적표(track record)는 `backtest_runs` SUM 집계로 on-the-fly 계산 — 별도 테이블 불필요.
+
+---
+
+## 4. 컴포넌트
+
+### 4.1 lotto-lab `app/backtest.py` (순수 연산 — FastAPI 의존성 0, Windows 이전 대비)
+- `generate_pool(cache, number_weights, n) -> list[tuple]` — `weighted_sample_6` 반복으로 distinct 후보 풀.
+- `purchase_tickets(pool, cache, W, k) -> list[dict]` — 풀을 `score_combination(·, W)`로 랭킹→상위 k장 distinct.
+- `coverage_select(pool, k) -> list` — distinct 보장 상위 커버리지(초기엔 단순 distinct, 휠링은 향후).
+- `grade_tickets(tickets, winning6, bonus) -> dict` — 매칭 히스토그램 + 등수 카운트 + best_match + avg_meta. `bonus`는 draws 레코드에서 가져옴(2등=5일치+보너스 판정용).
+- `run_forward_purchase(draw_no, k=5000, pool_n=20000) -> dict` — engine(6 W)+random_null+coverage 각각 **전략당 k=5000장(수천 장)** 구매·채점·`backtest_runs` 저장(멱등). 풀 pool_n=20000에서 랭킹.
+- `calibrate_winner(draw_no, sample_m=2000) -> dict` — `draws[:idx]`(대상 회차 제외) 캐시로 당첨조합 채점 + 무작위 sample_m 표본 percentile → `winner_calibration` 저장(멱등).
+- `backfill_calibration(batch=50) -> dict` — 미처리 회차만 청크 처리, 재개 가능.
+- `build_review_payload(draw_no) -> dict` — 회고 브리핑용 조립(당첨조합 분해 + 내 추천 비교 + forward 성적 + 캘리브레이션 추세 + 진화 결과).
+
+### 4.2 lotto-lab `app/routers/backtest.py`
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/lotto/backtest/track-record` | 누적 성적표(전략별 등수 카운트, engine vs random) |
+| GET | `/api/lotto/backtest/calibration?weeks=N` | 캘리브레이션 이력 + 추세 |
+| GET | `/api/lotto/backtest/review/{draw_no}` | 회고 payload |
+| POST | `/api/lotto/backtest/run-forward?draw_no=` | forward 수동 트리거 |
+| POST | `/api/lotto/backtest/backfill` | 캘리브레이션 백필(백그라운드) |
+
+### 4.3 weight_evolver 업그레이드
+- `evaluate_weekly`: 학습 신호를 N=5(W-무관)에서 **forward 가상구매(engine_w 6전략) + null-model 대비 lift**로 승격.
+  - lift = engine_w 등수 점수 − random_null 등수 점수(동일 회차).
+  - 승자 = lift 최대 trial. **모든 W의 lift가 노이즈 범위(±ε) 내면 base `unchanged`** → 노이즈 과적합 방지.
+- `decide_base_update` 규칙은 유지하되 입력(winner)을 backtest 기반으로 교체.
+- 기존 `auto_picks` 경로는 하위호환·일일 활동표시용으로 유지(evolver 결정에는 미사용).
+
+---
+
+## 5. 플로우
+
+1. **캘리브레이션 백필 (1회)**: `POST /backtest/backfill` → 백그라운드 청크(50회차/배치, 멱등 재개). 이후 회차마다 증분.
+2. **주간 forward**: 당첨번호 동기화 직후 `run_forward_purchase(latest)`. 참고: 6 W × 20k 풀은 기존 시뮬이 **하루 6회** 돌리는 부하보다 가벼움 → NAS 부담 작음.
+3. **일 09:00 회고 (agent-office 신규 cron)**: `LottoAgent.run_sunday_review()` → forward+calibration 보장 → `GET /backtest/review/{latest}` → 텔레그램 1통.
+4. **evolver (토 22:00, 기존 cron)**: backtest 집계를 학습 신호로 소비.
+
+### Windows 이전 경로 (NAS 부하 측정 후 필요시)
+`backtest.py`가 순수 함수라, lotto-lab은 system-of-record 유지 + 무거운 연산만 Windows WSL docker 워커에 위임(`/api/internal/lotto/*` webhook, 기존 music/video/image 워커 패턴 재활용) + agent 폴링. 코드 경계가 깨끗해 마이그레이션 비용 최소. **초기 구현은 NAS-first**, 측정 후 결정.
+
+---
+
+## 6. 출력
+
+### 6.1 텔레그램 (일 09:00, `notifiers/telegram_lotto.py` 신규 섹션)
+이번 당첨조합 5분석치 분해 + 내 추천 평균과 비교 + 이번주 forward 성적(등수 카운트, **무작위 대비 lift**) + 캘리브레이션 percentile 추세 + 가중치 진화 결과.
+
+### 6.2 web-ui `/lotto` "자율 학습" 탭 확장 (`.lotto-evolver-*` 다크 네임스페이스 재활용)
+- **TrackRecordCard**: 누적 "매주 전략당 5,000장 샀다면" 등수 — engine vs random_null 나란히 + 총지출 대비 당첨금(정직하게 적자 표시).
+- **CalibrationChart**: 당첨조합 score_total 추세 + 내 추천 평균 오버레이 + percentile 밴드 → "우위 없음"을 시각화.
+- **WinnerAnalysisCard**: 이번 회차 당첨조합 5분석치 레이더 + 내 추천 비교.
+
+---
+
+## 7. 에러·성능·멱등
+- **멱등성**: `winner_calibration` UNIQUE(draw_no), `backtest_runs` UNIQUE(draw_no,strategy,weight_label) → 재실행 skip.
+- **NAS 성능**: 주간 forward는 기존 시뮬보다 가벼움. 백필만 1회 무거움(≈1100 point-in-time 캐시 재구성) → 청크+백그라운드+멱등 재개. 야간/유휴 트리거 권장.
+- **텔레그램 실패**: 로그만 남기고 job은 성공 처리(기존 패턴). 회고 데이터는 이미 DB에 있어 UI는 영향 없음.
+
+## 8. 테스트 전략
+- 등수 매핑(m3~m6/bonus → 1~5등) 단위 테스트.
+- null-model 기대값 + lift 계산.
+- percentile 계산 정확성.
+- **point-in-time 캐시가 대상 회차를 제외하는지** (calibrate_winner 정직성 핵심).
+- 멱등 백필(재실행 시 중복 row 없음, 중단 후 재개).
+- evolver의 lift-over-random 승자 선택 + ε-게이팅(노이즈 시 unchanged).
+- 기존 `count_match`/`calc_pick_score` 테스트 유지.
+
+## 9. 리스크 & 완화
+| 리스크 | 완화 |
+|--------|------|
+| 무작위성 → 실제 우위 없음 | null-model 정직 프레이밍, 우위 없음을 데이터로 보고하는 게 목표 |
+| Celeron 백필 부하 | 청크+1회성+멱등 재개, 필요시 Windows 이전 |
+| evolver 노이즈 추종 | lift-over-random + ε-게이팅으로 unchanged 처리 |
+| DB 증가 | 집계 전용, row 수 무시 가능 |
+| forward 풀 중복으로 커버리지 손실 | distinct 강제 + coverage 전략 별도 측정 |
+
+## 10. 결정 로그 (2026-05-31 brainstorming)
+1. 3종 중 **로또 먼저**, 주식·인스타는 후속 사이클.
+2. 회고 브리핑 = **토 추첨 직후 일 09:00**.
+3. 시도 규모 = **수천 장/회차 + 집계만 저장**.
+4. 자율성 = **가중치 자동튜닝 강화**(산식 구조 고정).
+5. 백테스트 범위 = **캘리브레이션 전체 백필 + 가상구매 forward**.
+6. 출력 = **텔레그램 + 기존 자율학습 탭 확장**.
+7. 프레이밍 = **정직한 측정(null-model) + 커버리지 최적**.
+8. 연산 위치 = **NAS-first, 필요시 Windows WSL 이전**.
+
+## 11. 스코프 밖 / 향후
+- 주식 에이전트(보유종목 집중 분석+차트 매수/매도 시그널), 인스타 에이전트(자율 카드 발급) — 별도 사이클.
+- 휠링/커버링 디자인(하위 등수 최소 보장) — coverage 전략 고도화로 향후.
+- Windows WSL 워커 분리 — NAS 부하 측정 후.

docs/superpowers/specs/2026-05-31-stock-holdings-intelligence-design.md

@@ -0,0 +1,122 @@
+# 주식 보유종목 인텔리전스 — 설계 Spec
+
+- **작성일**: 2026-05-31
+- **상태**: 설계 승인 (구현 plan 대기)
+- **대상 서비스**: `stock` + `agent-office`(StockAgent) + `web-ui`(stock/포트폴리오 페이지)
+- **사이클**: 스마트 에이전트 고도화 3종 중 **2번 주식**. (1번 로또 완료, 3번 인스타 후속)
+
+---
+
+## 1. 배경 & 목표
+
+현재 StockAgent는 아침 뉴스 요약(07:30) · KRX 강세주 스크리너(16:30) · AI 뉴스 sentiment(08:00)를 브리핑한다. CEO는 여기서 더 나아가 **내 보유종목을 집중 분석**해 ①종목별 매수/매도 자세 ②이슈 정리 ③포트폴리오 건강을 매일 advisory로 브리핑받길 원한다.
+
+### 핵심 결정 (2026-05-31 brainstorming)
+1. **실행 수준 = 브리핑 전용(advisory)**. `/api/trade/order`(KIS 실주문) 미사용. 매수/매도는 "제안"만, 실제 주문은 사용자 수동. (로또와 동일한 정직·관찰 철학)
+2. **분석 주기 = 일봉 EOD + 장중 경량 가드**. 장마감 후 일봉으로 기술분석 → 다음날 아침 브리핑. 장중엔 현재가로 손절·급변(±N%)만 경도 알림. 인트라데이 분봉 파이프라인 신설 안 함.
+3. **브리핑 범위 = 보유종목 + 포트 레벨**. 종목별 액션 + 포트폴리오 건강(집중도·비중·현금·손익).
+4. **이슈 소스 = 기존 뉴스+감성+LLM 요약 + 급변·거래량·외인수급 이벤트**. 신규 스크래핑 0 (DART·실적 일정 제외).
+
+### 기존 자산 (100% 재활용, 신규 ML/데이터소스 없음)
+- `stock/app/screener/snapshot.py` → `krx_daily_prices`(일봉 OHLCV) + `krx_master`(listing) + naver 외인 flow. 스크리너 잡(평일 16:30)이 갱신.
+- `stock/app/screener/engine.py` + `nodes/`(ma_alignment·momentum·rs_rating·vcp_lite·volume_surge·foreign_buy·high52w·hygiene). **`ScreenContext.restrict(tickers)`** + `latest_close()`/`latest_high()`로 보유종목 한정 분석 가능.
+- `portfolio` 테이블(broker·ticker·name·quantity·avg_price·purchase_price) + `/api/portfolio`(현재가·손익 계산) + `broker_cash`(예수금).
+- `price_fetcher`(현재가 3분 TTL) · `news_sentiment` 테이블(종목별 감성) · `ai_summarizer`(Claude Haiku).
+
+### 알려진 제약 (설계 반영)
+- **섹터 필드 없음**: `portfolio`·`krx_master`에 sector 없음 → 섹터 편중은 best-effort(FDR `StockListing`의 Sector/Industry가 있으면 사용, 없으면 생략)이고, **시장(KOSPI/KOSDAQ)·종목 비중 집중도**를 기본 지표로 사용.
+- **KRX 외 종목**(미국주 등): krx_daily_prices 밖 → 기술분석 불가, **뉴스·현재가·손익만** graceful 처리.
+- **snapshot 히스토리 의존**: MA200·52주 고점 노드는 ~1년 일봉 필요. 스크리너가 이미 이 노드들을 쓰므로 윈도우는 충족 가정(plan에서 lookback 확인 단계 포함).
+
+---
+
+## 2. 데이터 모델 & 컴포넌트
+
+### 신규 테이블 `holdings_signals` (stock.db, 일별 종목 시그널 이력)
+```
+date        TEXT NOT NULL          -- KST 거래일
+ticker      TEXT NOT NULL
+name        TEXT
+action      TEXT NOT NULL          -- 'add' | 'hold' | 'trim' | 'sell'
+tech_score  REAL                   -- 매수강도(score 노드 가중합, 0~1 정규화)
+exit_flags  TEXT NOT NULL DEFAULT '{}'  -- JSON {stop_loss,ma50_break,ma200_break,momentum_loss,take_profit,climax}
+issues      TEXT NOT NULL DEFAULT '[]'  -- JSON [{type, severity, summary}]
+close       INTEGER
+pnl_rate    REAL                   -- 평단 대비 % (스냅샷 시점)
+reasons     TEXT                   -- 액션 근거 텍스트
+created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+PRIMARY KEY(date, ticker)          -- 멱등 upsert
+```
+> 추세/이력은 이 테이블에서 조회. 포트 레벨 요약은 on-the-fly 계산(별도 테이블 불필요).
+
+### 신규 `stock/app/holdings_intel.py` (순수연산 중심, FastAPI 의존성 최소)
+- `get_holdings() -> list[dict]` — `portfolio` 행 + 현재가(price_fetcher) + pnl_rate. KRX 여부 플래그(`is_krx`).
+- `technical_posture(ctx_restricted, tickers) -> dict[ticker, score]` — `ScreenContext.restrict(tickers)`에 score 노드 실행 → 매수강도.
+- `exit_rules(holding, prices_df, params) -> dict` — **신규**: 손절·MA이탈·모멘텀소멸·익절·클라이맥스 flag 산출 (§3).
+- `decide_action(tech_score, exit_flags, pnl) -> (action, reasons)` — **신규**: 매수강도+exit 조합 → add/hold/trim/sell + 근거.
+- `market_events(prices_df, flow, params) -> dict[ticker, list]` — 급변(±N%)·거래량 Z-score·외인 순매도.
+- `news_issues(tickers) -> dict[ticker, list]` — news+news_sentiment 필터 → Claude Haiku 악재·심각도 요약(악재 있는 종목만).
+- `portfolio_health(holdings, cash) -> dict` — 종목 비중 집중도(HHI/최대비중)·시장 mix·현금 비중·총 손익.
+- `compute_and_store(asof) -> dict` — 위를 조합해 holdings_signals upsert (멱등).
+- `build_holdings_brief(asof) -> dict` — 브리핑/UI payload 조립(종목별 action+issues + portfolio_health + 추세).
+
+### API (stock)
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/stock/holdings/intel` | 최신 브리핑 payload |
+| GET | `/api/stock/holdings/intel/history?ticker=&days=` | 종목 시그널 추세 |
+| POST | `/api/stock/holdings/intel/run` | 수동 계산 트리거(BackgroundTask) |
+
+---
+
+## 3. 매도/리스크 룰 & 이슈 (설정 가능 임계값 — 기본값 제시)
+
+### exit_flags (각 boolean + 값)
+- **stop_loss**: `current < avg_price × (1 − STOP_PCT)` (기본 STOP_PCT=0.08, Minervini식)
+- **ma50_break / ma200_break**: 종가 < MA50 / MA200
+- **momentum_loss**: momentum/RS 노드 점수가 직전 대비 임계 하락 (or 음전환)
+- **take_profit**: `pnl_rate ≥ TAKE_PCT` (기본 25%) — 부분 익절 후보
+- **climax**: 거래량 급증(vol > avg×CLIMAX_VOL_X) + 종가 상단 꼬리 (분산 의심)
+
+### decide_action 매트릭스
+- tech_score 高 + exit_flags 無 → **add**(추가매수 후보)
+- exit_flags 無 (강건) → **hold**
+- ma50_break 또는 momentum_loss 또는 take_profit → **trim**(일부 축소)
+- stop_loss 또는 ma200_break → **sell**(청산 후보)
+- 각 결정에 trigger된 flag를 근거 텍스트로 동봉. (advisory — "제안")
+
+### issues
+- **시장이벤트** (기존 데이터): 일봉 ±EVENT_PCT% 급변 / 거래량 Z-score>임계 / naver flow 외인 순매도 N일 연속.
+- **뉴스이슈**: 보유종목 최근 뉴스 + news_sentiment 음수 → Claude Haiku로 `{type, severity(low/med/high), summary}` 요약. 악재 있는 종목만 호출(비용 bounded).
+
+---
+
+## 4. 플로우 · 에이전트 · UI
+
+1. **EOD 계산 (평일 16:40)**: 기존 스크리너/뉴스 잡과 동일하게 **agent-office cron이 orchestrate** — `_run_stock_holdings_eod()` → `StockAgent.run_holdings_eod()` → stock `POST /api/stock/holdings/intel/run` → `holdings_intel.compute_and_store(today)` → holdings_signals upsert. 스크리너 snapshot 갱신(16:30) 직후라 일봉 준비됨.
+2. **아침 브리핑 (평일 08:30, agent-office StockAgent.run_holdings_brief)**: 저장된 최신 시그널 + 야간 갭(현재가) → 텔레그램 1통(종목별 액션 + 포트 건강 + 상위 이슈). AI 뉴스(08:00) 다음 슬롯.
+3. **장중 경량 가드 (평일 09:00~15:30, 30분 간격)**: 현재가로 손절선 이탈·급변(±N%)만 점검 → 발생 시 텔레그램 alert. throttle(종목·유형별 재발화 억제) + daily cap (로또 시그널 패턴 재활용).
+4. **agent-office**: `service_proxy`에 holdings intel 호출 추가 + StockAgent 메서드(run_holdings_brief / intraday_guard) + scheduler cron.
+5. **UI (web-ui)**: stock/포트폴리오 페이지에 **"보유종목 인텔리전스" 탭/섹션 통합** — 종목별 액션 카드(자세·exit flags·근거) + 포트 건강 위젯 + 이슈 피드 + 종목 시그널 추세(history).
+
+---
+
+## 5. 에러·성능·테스트·리스크
+
+- **멱등성**: holdings_signals PRIMARY KEY(date,ticker) upsert → 재계산 안전.
+- **성능 (NAS Celeron)**: 보유종목만 restrict(소수 종목)이라 전체 스크리너 대비 매우 가벼움. LLM 이슈 요약은 악재 종목만(bounded). EOD 1회 + 장중 가드는 현재가만(경량).
+- **graceful degrade**: price_fetcher/KIS/news 실패 시 부분 데이터로 진행 + 경고 로그. KRX 외 종목은 기술분석 skip(뉴스·손익만). 텔레그램 실패는 로그만(job 성공 유지).
+- **테스트**: exit_rules 각 flag, decide_action 매트릭스 전 분기, market_events 검출, portfolio_health 계산, holdings_signals 멱등, KRX 외 종목 graceful, 뉴스 0건 경로.
+- **리스크**: ①기술적 시그널은 휴리스틱이지 보장 아님 → advisory 프레이밍·자동매매 없음 ②섹터 데이터 갭 → 시장·비중 집중도로 대체 ③snapshot 히스토리 의존 → plan에 lookback 확인 ④보유종목 출처는 portfolio 테이블(사용자/KIS 동기화) — 누락 시 빈 브리핑 graceful.
+
+---
+
+## 6. 결정 로그 (2026-05-31)
+1. 실행 수준 = **advisory 전용** (KIS 실주문 미사용)
+2. 주기 = **일봉 EOD + 장중 경량 가드**
+3. 범위 = **보유종목 + 포트 레벨**
+4. 이슈 소스 = **기존 뉴스+감성+LLM + 급변·거래량·외인 이벤트**
+
+## 7. 스코프 밖 / 향후
+- 자동매매(승인후/완전자동), 인트라데이 분봉, DART 공시·실적 일정, 신규 매수후보 발굴(기존 16:30 스크리너가 담당), 교체(rotation) 제안 — 향후 사이클.
+- 인스타 에이전트(자율 카드 발급) — 다음 사이클.