music-lab 신규 서비스 추가 (AI 음악 생성 + 라이브러리 관리)

- music-lab/ 신규 서비스 (포트 18600) - POST /api/music/generate 비동기 음악 생성 (task_id 반환) - GET /api/music/status/:id 폴링 (queued→processing→succeeded/failed) - GET /api/music/library 라이브러리 조회 - POST /api/music/library 트랙 수동 추가 - DELETE /api/music/library/:id 트랙 삭제 (파일 포함) - SQLite: music_tasks + music_library 테이블 - 생성 완료 시 라이브러리 자동 등록 - AI 서버 응답: binary audio / JSON audio_url 모두 지원 - nginx: /api/music/ 프록시 + /media/music/ 오디오 파일 직접 서빙 - docker-compose: music-lab 서비스 + frontend 볼륨 마운트 추가 - CLAUDE.md 업데이트 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-21 09:32:26 +09:00
parent f1eab292a2
commit 868020f7ed
8 changed files with 723 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,287 @@
+# CLAUDE.md — web-backend 프로젝트 가이드
+
+> Claude Code가 이 프로젝트를 작업할 때 참조하는 설정 및 구조 문서.
+
+---
+
+## 1. 프로젝트 개요
+
+Synology NAS 기반의 개인 웹 플랫폼 백엔드 모노레포.
+- **서비스**: lotto-lab, stock-lab, travel-album, music-lab, deployer
+- **프론트엔드**: 별도 레포 (React + Vite SPA), 빌드 산출물만 NAS에 배포
+- **인프라**: Docker Compose + Nginx(리버스 프록시) + Gitea Webhook 자동 배포
+
+---
+
+## 2. NAS 환경
+
+| 항목 | 값 |
+|------|----|
+| 장비 | Synology NAS |
+| CPU | Intel Celeron J4025 (2 Core, 2.0 GHz) |
+| 메모리 | 18 GB |
+| Docker | Synology Container Manager |
+| Git 서버 | Gitea (self-hosted, NAS 내부) |
+| AI 서버 | Windows PC (192.168.45.59:8000) — NVIDIA 3070 Ti + Ollama |
+
+---
+
+## 3. NAS 디렉토리 구조
+
+```
+/volume1
+├── docker/webpage/          # 운영 런타임 (Docker Compose 실행 위치)
+│   ├── backend/             # lotto-backend 소스 (rsync 동기화)
+│   ├── stock-lab/           # stock-lab 소스 (rsync 동기화)
+│   ├── travel-proxy/        # travel-proxy 소스 (rsync 동기화)
+│   ├── deployer/            # deployer 소스 (rsync 동기화)
+│   ├── nginx/default.conf   # Nginx 설정
+│   ├── scripts/deploy.sh    # Webhook 트리거 배포 스크립트
+│   ├── docker-compose.yml
+│   ├── .env                 # 운영 환경변수
+│   ├── data/lotto.db        # SQLite DB
+│   └── data/music/          # 생성된 오디오 파일 (music-lab)
+│
+├── workspace/web-page-backend/  # Git 레포 클론 위치 (REPO_PATH)
+│
+└── web/images/webPage/travel/   # 원본 여행 사진 (RO 마운트)
+```
+
+---
+
+## 4. Docker 서비스 & 포트
+
+| 컨테이너 | 포트 | 역할 |
+|---------|------|------|
+| `lotto-backend` | 18000 | 로또 데이터 수집·분석·추천 API |
+| `stock-lab` | 18500 | 주식 뉴스·AI 분석·KIS API 연동 |
+| `music-lab` | 18600 | AI 음악 생성·라이브러리 관리 API |
+| `travel-proxy` | 19000 | 여행 사진 API + 썸네일 생성 |
+| `lotto-frontend` (nginx) | 8080 | 정적 SPA 서빙 + API 리버스 프록시 |
+| `webpage-deployer` | 19010 | Gitea Webhook 수신 → 자동 배포 |
+
+---
+
+## 5. Nginx 라우팅 규칙
+
+| 경로 | 프록시 대상 | 비고 |
+|------|------------|------|
+| `/api/` | `lotto-backend: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/music/` | `music-lab:8000` | AI 음악 생성·라이브러리 API |
+| `/webhook`, `/webhook/` | `deployer:9000` | Gitea Webhook |
+| `/media/music/` | `/data/music/` (파일 직접 서빙) | 생성된 오디오 파일 |
+| `/media/travel/.thumb/` | `/data/thumbs/` (파일 직접 서빙) | 썸네일 캐시 |
+| `/media/travel/` | `/data/travel/` (파일 직접 서빙) | 원본 사진 |
+| `/assets/` | 정적 파일 (장기 캐시) | Vite 해시 파일 |
+| `/` | SPA fallback (`try_files → index.html`) | |
+
+---
+
+## 6. 기술 스택
+
+| 레이어 | 기술 |
+|--------|------|
+| Backend 언어 | Python 3.12 |
+| API 프레임워크 | FastAPI |
+| DB | SQLite (`/app/data/*.db`) |
+| 스케줄러 | APScheduler |
+| 컨테이너 | Docker (`python:3.12-slim` 기반) |
+| AI 연동 | Ollama (Llama 3.1) — Windows PC (192.168.45.59) |
+| 주식 API | KIS (한국투자증권) Open API |
+
+---
+
+## 7. 자동 배포 흐름
+
+```
+개발자 git push → Gitea → Webhook (HMAC SHA256 검증)
+  → deployer 컨테이너 → /scripts/deploy.sh
+  → rsync(REPO→RUNTIME) → docker compose up -d --build
+```
+
+- **배포 스크립트 위치**: `scripts/deploy-nas.sh` (레포) / `scripts/deploy.sh` (런타임)
+- **환경변수 파일**: `.env` (RUNTIME_PATH, REPO_PATH, PHOTO_PATH, PUID, PGID 등)
+- **백업**: `.releases/` 디렉토리에 자동 백업
+
+---
+
+## 8. 로컬 개발 환경
+
+```bash
+# .env 기본값으로 즉시 실행 가능 (RUNTIME_PATH=., PHOTO_PATH=./mock_data/photos)
+docker compose up -d
+```
+
+| 서비스 | 로컬 URL |
+|--------|----------|
+| Frontend + API | http://localhost:8080 |
+| Lotto Backend | http://localhost:18000 |
+| Travel API | http://localhost:19000 |
+| Stock Lab | http://localhost:18500 |
+
+---
+
+## 9. 서비스별 핵심 정보
+
+### lotto-lab (backend/)
+- DB: `/app/data/lotto.db`
+- 데이터 소스: `smok95.github.io/lotto/results/`
+- 파일 구조: `main.py`, `db.py`, `recommender.py`, `collector.py`, `checker.py`, `generator.py`, `analyzer.py`, `utils.py`
+
+**lotto.db 테이블**
+
+| 테이블 | 설명 |
+|--------|------|
+| `draws` | 로또 당첨번호 |
+| `recommendations` | 추천 이력 (즐겨찾기·태그·채점 포함) |
+| `simulation_runs` | 시뮬레이션 실행 기록 |
+| `simulation_candidates` | 시뮬레이션 후보 (점수 5종) |
+| `best_picks` | 현재 활성 최적 번호 20개 (`is_active` 플래그로 교체) |
+| `todos` | 투두리스트 (UUID PK) |
+| `blog_posts` | 블로그 글 (tags: JSON 배열) |
+
+**스케줄러 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개 교체)
+
+**lotto-lab API 목록**
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/lotto/latest` | 최신 당첨번호 |
+| GET | `/api/lotto/{drw_no}` | 특정 회차 |
+| GET | `/api/lotto/stats` | 번호 빈도 통계 |
+| GET | `/api/lotto/analysis` | 5가지 통계 분석 리포트 |
+| GET | `/api/lotto/best` | 시뮬레이션 최적 번호 (기본 20쌍) |
+| GET | `/api/lotto/simulation` | 시뮬레이션 상세 결과 |
+| GET | `/api/lotto/recommend` | 통계 기반 추천 |
+| GET | `/api/lotto/recommend/heatmap` | 히트맵 기반 추천 |
+| GET | `/api/lotto/recommend/batch` | 배치 추천 |
+| POST | `/api/lotto/recommend/batch` | 배치 추천 저장 |
+| POST | `/api/admin/simulate` | 시뮬레이션 수동 실행 |
+| POST | `/api/admin/sync_latest` | 당첨번호 수동 동기화 |
+| GET | `/api/history` | 추천 이력 (limit, offset, favorite, tag, sort) |
+| PATCH | `/api/history/{id}` | 즐겨찾기·메모·태그 수정 |
+| DELETE | `/api/history/{id}` | 삭제 |
+| GET | `/api/todos` | 투두 전체 목록 |
+| POST | `/api/todos` | 투두 생성 (status: todo\|in_progress\|done) |
+| PUT | `/api/todos/{id}` | 투두 수정 |
+| DELETE | `/api/todos/done` | 완료 항목 일괄 삭제 |
+| DELETE | `/api/todos/{id}` | 투두 개별 삭제 |
+| GET | `/api/blog/posts` | 블로그 글 목록 (`{"posts": [...]}`, date DESC) |
+| POST | `/api/blog/posts` | 블로그 글 생성 (date 미입력 시 오늘) |
+| PUT | `/api/blog/posts/{id}` | 블로그 글 수정 |
+| DELETE | `/api/blog/posts/{id}` | 블로그 글 삭제 |
+
+### stock-lab (stock-lab/)
+- 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 목록**
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/stock/news` | 뉴스 조회 (`limit`, `category` 파라미터) |
+| GET | `/api/stock/indices` | 주요 지표 실시간 조회 |
+| POST | `/api/stock/scrap` | 수동 뉴스 스크랩 트리거 |
+| GET | `/api/trade/balance` | 실계좌 잔고 조회 (Windows AI 서버 프록시) |
+| POST | `/api/trade/order` | 주식 주문 (Windows AI 서버 프록시) |
+| GET | `/api/portfolio` | 포트폴리오 전체 조회 (현재가·손익·예수금 포함) |
+| POST | `/api/portfolio` | 종목 추가 |
+| PUT | `/api/portfolio/{id}` | 종목 수정 |
+| DELETE | `/api/portfolio/{id}` | 종목 삭제 |
+| GET | `/api/portfolio/cash` | 예수금 전체 조회 |
+| PUT | `/api/portfolio/cash` | 예수금 등록·수정 (upsert) |
+| DELETE | `/api/portfolio/cash/{broker}` | 예수금 삭제 |
+| POST | `/api/portfolio/snapshot` | 총 자산 스냅샷 수동 저장 |
+| GET | `/api/portfolio/snapshot/history` | 스냅샷 이력 조회 (`days=0`: 전체, `days=N`: 최근 N건) |
+| GET | `/api/portfolio/sell-history` | 매도 내역 조회 (`broker`, `days` 필터 선택) |
+| POST | `/api/portfolio/sell-history` | 매도 기록 저장 (id 포함 레코드 반환) |
+| PUT | `/api/portfolio/sell-history/{id}` | 매도 기록 수정 (수정된 레코드 반환) |
+| DELETE | `/api/portfolio/sell-history/{id}` | 매도 기록 삭제 |
+
+**매도 히스토리 (`sell_history`)**
+- 독립 테이블 — `portfolio` 테이블과 별개로 관리
+- `sold_at`: UTC ISO8601 형식 (`new Date().toISOString()`)
+- `realized_profit` / `realized_rate`: 프론트 계산값 저장 (백엔드 재계산 무방)
+- 응답 정렬: `sold_at DESC` (최신순)
+
+**총 자산 스냅샷 (`asset_snapshots`)**
+- 평일 15:40 APScheduler 자동 실행 (`save_daily_snapshot`)
+- 공휴일 판별: `holidays.json` (매년 수동 갱신, KRX 기준) → `is_market_open()` 함수
+- 같은 날 중복 저장 시 upsert (date UNIQUE 제약)
+- 수동 저장: `POST /api/portfolio/snapshot`
+- 이력 조회: `GET /api/portfolio/snapshot/history?days=30` (ASC 정렬, 차트용)
+
+**스케줄러 job**
+- 08:00 매일 — 뉴스 스크랩 (`run_scraping_job`)
+- 15:40 평일 — 총 자산 스냅샷 저장 (`save_daily_snapshot`)
+
+### music-lab (music-lab/)
+- AI 음악 생성 서비스. Windows AI 서버(`MUSIC_AI_SERVER_URL`)에 생성 요청 프록시
+- 생성된 오디오 파일: `/app/data/music/` (Nginx가 `/media/music/`로 직접 서빙)
+- DB: `/app/data/music.db` (music_tasks, music_library 테이블)
+- 파일 구조: `main.py`, `db.py`
+- 생성 흐름: POST generate → task_id 반환 → BackgroundTask가 AI 서버 호출 → 파일 저장 → 라이브러리 자동 등록
+
+**music-lab API 목록**
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| POST | `/api/music/generate` | 음악 생성 시작 (task_id 반환, 비동기) |
+| GET | `/api/music/status/{task_id}` | 생성 상태 폴링 (queued→processing→succeeded/failed) |
+| GET | `/api/music/library` | 라이브러리 전체 조회 |
+| POST | `/api/music/library` | 트랙 수동 추가 (201) |
+| DELETE | `/api/music/library/{id}` | 트랙 삭제 (로컬 파일 포함) |
+
+**환경변수**
+- `MUSIC_AI_SERVER_URL`: AI 음악 생성 서버 URL (미설정 시 생성 요청 실패)
+- `MUSIC_MEDIA_BASE`: 오디오 파일 공개 URL prefix (기본 `/media/music`)
+- `MUSIC_DATA_PATH`: NAS 오디오 파일 저장 경로 (기본 `./data/music`)
+
+**AI 서버 응답 형식 (2가지 모두 지원)**
+- binary audio (Content-Type: audio/*) → 직접 저장
+- JSON `{"audio_url": "..."}` → 해당 URL에서 다운로드 후 저장
+
+### travel-proxy (travel-proxy/)
+- 원본 사진: `/data/travel/` (RO)
+- 썸네일 캐시: `/data/thumbs/` (RW)
+- 메타: `/data/travel/_meta/region_map.json`, `regions.geojson`
+- 썸네일: 480×480 리사이징 (Pillow), 온디맨드 생성 후 영구 캐시
+- 메모리 캐시: TTL 300초 (앨범 스캔 결과)
+
+**travel-proxy API 목록**
+
+| 메서드 | 경로 | 설명 |
+|--------|------|------|
+| GET | `/api/travel/regions` | 지역 GeoJSON |
+| GET | `/api/travel/photos` | 사진 목록 (region, page=1, size=20) |
+| POST | `/api/travel/reload` | 메모리 캐시 초기화 |
+
+### deployer (deployer/)
+- Webhook 검증: `X-Gitea-Signature` (HMAC SHA256, `compare_digest` 사용)
+- `WEBHOOK_SECRET` 환경변수로 시크릿 관리
+- Webhook 수신 즉시 `{"ok": True}` 응답 후 BackgroundTask로 배포 실행
+- 배포 타임아웃: 10분 (`scripts/deploy.sh`)
+
+---
+
+## 10. 주의사항
+
+- **Nginx trailing slash**: `/api/portfolio`는 trailing slash 없이도 매칭되도록 두 location 블록으로 처리
+- **라우트 순서**: `DELETE /api/todos/done`은 `DELETE /api/todos/{id}` 보다 **반드시 먼저** 등록 (FastAPI prefix 매칭 순서)
+- **PUID/PGID**: travel-proxy는 NAS 파일 권한을 위해 PUID/PGID를 환경변수로 주입
+- **캐시 전략**: `index.html`은 `no-store`, `assets/`는 1년 장기 캐시(immutable)
+- **Frontend 배포**: git push로 자동 배포되지 않음. 로컬 빌드 후 NAS에 수동 업로드
+- **.env 파일**: 절대 커밋 금지. `.env.example`만 레포에 포함
+- **공휴일 목록**: `stock-lab/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`으로 비활성화 후 신규 입력