# Database INSERT 코드 위치 정리

이 문서는 O2O Castad Backend 프로젝트에서 실제 동작하는 모든 DB INSERT 코드의 위치를 정리합니다.

---

## 1. User 모듈 (`app/user`)

### 1.1 User 모델 INSERT
- **파일**: `app/user/services/auth.py`
- **라인**: 278
- **메서드**: `_get_or_create_user()`
- **API 엔드포인트**:
  - `GET /auth/kakao/callback` - 카카오 로그인 콜백
  - `POST /auth/kakao/verify` - 카카오 인가 코드 검증
- **설명**: 카카오 로그인 시 신규 사용자 생성
- **저장 필드**: `kakao_id`, `email`, `nickname`, `profile_image_url`, `thumbnail_image_url`

### 1.2 RefreshToken 모델 INSERT
- **파일**: `app/user/services/auth.py`
- **라인**: 315
- **메서드**: `_save_refresh_token()`
- **API 엔드포인트**:
  - `GET /auth/kakao/callback` - 카카오 로그인 콜백
  - `POST /auth/kakao/verify` - 카카오 인가 코드 검증
- **설명**: 로그인 시 리프레시 토큰 저장
- **저장 필드**: `user_id`, `token_hash`, `expires_at`, `user_agent`, `ip_address`

---

## 2. Lyric 모듈 (`app/lyric`)

### 2.1 Project 모델 INSERT
- **파일**: `app/lyric/api/routers/v1/lyric.py`
- **라인**: 297
- **API 엔드포인트**: `POST /lyric/generate` - 가사 생성
- **설명**: 가사 생성 요청 시 프로젝트 레코드 생성
- **저장 필드**: `store_name`, `region`, `task_id`, `detail_region_info`, `language`

### 2.2 Lyric 모델 INSERT
- **파일**: `app/lyric/api/routers/v1/lyric.py`
- **라인**: 317
- **API 엔드포인트**: `POST /lyric/generate` - 가사 생성
- **설명**: 가사 생성 요청 시 가사 레코드 생성 (초기 status: `processing`)
- **저장 필드**: `project_id`, `task_id`, `status`, `lyric_prompt`, `lyric_result`, `language`

---

## 3. Song 모듈 (`app/song`)

### 3.1 Song 모델 INSERT
- **파일**: `app/song/api/routers/v1/song.py`
- **라인**: 178
- **API 엔드포인트**: `POST /song/generate/{task_id}` - 노래 생성
- **설명**: 노래 생성 요청 시 노래 레코드 생성 (초기 status: `processing`)
- **저장 필드**: `project_id`, `lyric_id`, `task_id`, `suno_task_id`, `status`, `song_prompt`, `language`

### 3.2 SongTimestamp 모델 INSERT
- **파일**: `app/song/api/routers/v1/song.py`
- **라인**: 459
- **API 엔드포인트**: `GET /song/status/{song_id}` - 노래 생성 상태 조회
- **설명**: Suno API에서 노래 생성 완료(SUCCESS) 시 가사 타임스탬프 저장 (반복문으로 다건 INSERT)
- **저장 필드**: `suno_audio_id`, `order_idx`, `lyric_line`, `start_time`, `end_time`

---

## 4. Video 모듈 (`app/video`)

### 4.1 Video 모델 INSERT
- **파일**: `app/video/api/routers/v1/video.py`
- **라인**: 247
- **API 엔드포인트**: `GET /video/generate/{task_id}` - 영상 생성
- **설명**: 영상 생성 요청 시 영상 레코드 생성 (초기 status: `processing`)
- **저장 필드**: `project_id`, `lyric_id`, `song_id`, `task_id`, `creatomate_render_id`, `status`

---

## 5. Home 모듈 (`app/home`) - 이미지 업로드

### 5.1 Image 모델 INSERT (URL 이미지 - 서버 저장)
- **파일**: `app/home/api/routers/v1/home.py`
- **라인**: 486
- **API 엔드포인트**: `POST /image/upload` (tags: Image-Server)
- **설명**: 외부 URL 이미지를 Image 테이블에 저장
- **저장 필드**: `task_id`, `img_name`, `img_url`, `img_order`

### 5.2 Image 모델 INSERT (바이너리 파일 - 서버 저장)
- **파일**: `app/home/api/routers/v1/home.py`
- **라인**: 535
- **API 엔드포인트**: `POST /image/upload` (tags: Image-Server)
- **설명**: 업로드된 바이너리 파일을 media 폴더에 저장 후 Image 테이블에 저장
- **저장 필드**: `task_id`, `img_name`, `img_url`, `img_order`

### 5.3 Image 모델 INSERT (URL 이미지 - Blob)
- **파일**: `app/home/api/routers/v1/home.py`
- **라인**: 782
- **API 엔드포인트**: `POST /image/upload/blob` (tags: Image-Blob)
- **설명**: 외부 URL 이미지를 Image 테이블에 저장 (Azure Blob 엔드포인트)
- **저장 필드**: `task_id`, `img_name`, `img_url`, `img_order`

### 5.4 Image 모델 INSERT (Blob 업로드 결과)
- **파일**: `app/home/api/routers/v1/home.py`
- **라인**: 804
- **API 엔드포인트**: `POST /image/upload/blob` (tags: Image-Blob)
- **설명**: 바이너리 파일을 Azure Blob Storage에 업로드 후 Image 테이블에 저장
- **저장 필드**: `task_id`, `img_name`, `img_url`, `img_order`

---

## 6. Base Services (미사용)

아래 파일들은 공통 `_add()` 메서드를 정의하고 있으나, 현재 실제 API에서 직접 호출되지 않습니다.

| 파일 | 라인 | 비고 |
|------|------|------|
| `app/lyric/services/base.py` | 15 | `_update()`에서만 내부 호출 |
| `app/home/services/base.py` | 15 | `_update()`에서만 내부 호출 |
| `app/song/services/base.py` | 15 | `_update()`에서만 내부 호출 |

---

## 요약 테이블

| 모듈 | 모델 | 파일:라인 | API 엔드포인트 |
|------|------|-----------|----------------|
| User | User | `auth.py:278` | `GET /auth/kakao/callback`, `POST /auth/kakao/verify` |
| User | RefreshToken | `auth.py:315` | `GET /auth/kakao/callback`, `POST /auth/kakao/verify` |
| Lyric | Project | `lyric.py:297` | `POST /lyric/generate` |
| Lyric | Lyric | `lyric.py:317` | `POST /lyric/generate` |
| Song | Song | `song.py:178` | `POST /song/generate/{task_id}` |
| Song | SongTimestamp | `song.py:459` | `GET /song/status/{song_id}` |
| Video | Video | `video.py:247` | `GET /video/generate/{task_id}` |
| Home | Image | `home.py:486` | `POST /image/upload` |
| Home | Image | `home.py:535` | `POST /image/upload` |
| Home | Image | `home.py:782` | `POST /image/upload/blob` |
| Home | Image | `home.py:804` | `POST /image/upload/blob` |

---

*생성일: 2026-01-23*