From 9335720fa85f7e9f1507a47daf53f9b4e6ad05e6 Mon Sep 17 00:00:00 2001
From: caadiq <caadiq@gmail.com>
Date: Mon, 2 Mar 2026 15:55:50 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20YouTube=20=EB=B4=87=20API=20=EC=B5=9C?=
 =?UTF-8?q?=EC=A0=81=ED=99=94=20=EA=B4=80=EB=A0=A8=20=EB=AC=B8=EC=84=9C=20?=
 =?UTF-8?q?=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- architecture.md: YouTube 서비스 파일 구조 추가
- development.md: 동기화 흐름, API 할당량, 주요 함수 목록 추가

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/architecture.md |  4 +++-
 docs/development.md  | 25 +++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 81e4b00..6ecb5e9 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -37,6 +37,8 @@ fromis_9/
 │   │   │   └── index.js        # 라우트 등록
 │   │   ├── services/           # 비즈니스 로직
 │   │   │   ├── youtube/        # YouTube 봇
+│   │   │   │   ├── api.js      # YouTube Data API 호출
+│   │   │   │   └── index.js    # 봇 로직 (동기화, 저장)
 │   │   │   ├── x/              # X(Twitter) 봇
 │   │   │   ├── meilisearch/    # 검색 서비스
 │   │   │   └── suggestions/    # 추천 검색어
@@ -317,7 +319,7 @@ fromis_9/
 - `concert_setlist_members` - 셋리스트-멤버 연결
 
 #### 봇
-- `bot_youtube` - YouTube 봇 설정 (채널 정보, 동기화 간격, 필터 등)
+- `bot_youtube` - YouTube 봇 설정 (채널 정보, 동기화 간격, 필터 등, video_id UNIQUE)
 - `bot_x` - X 봇 설정 (username, 프로필, 동기화 간격, 텍스트 필터, 리트윗 포함, YouTube 추출)
 
 #### 이미지
diff --git a/docs/development.md b/docs/development.md
index c3be8bd..f11b60e 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -258,6 +258,31 @@ queryClient.invalidateQueries();
 
 ---
 
+## YouTube 봇 동기화
+
+### 동기화 흐름 (syncNewVideos)
+1. `fetchRecentVideoIds()` — Activities API로 최근 영상 ID 목록만 조회 (1 unit)
+2. DB에서 이미 존재하는 video_id 필터링
+3. 새 영상만 `fetchVideoInfo()` — Videos API로 상세 정보 조회 (새 영상당 1 unit)
+4. `saveVideo()` — DB 저장 + Meilisearch 동기화
+
+### API 할당량
+- 일일 할당량: 10,000 units
+- 새 영상 없을 때: activities.list 1 unit만 소비
+- 새 영상 있을 때: 1 + 새 영상 수 units
+- 1분 간격, 3채널 기준: ~4,320 units/일 (43%)
+
+### 주요 API 함수 (services/youtube/api.js)
+| 함수 | YouTube API | 용도 |
+|------|-----------|------|
+| `fetchRecentVideoIds()` | activities.list (1 unit) | 최근 영상 ID 목록 조회 |
+| `fetchVideoInfo()` | videos.list (1 unit) | 단일 영상 상세 정보 |
+| `fetchAllVideos()` | playlistItems.list + videos.list | 전체 영상 초기 동기화 |
+| `getChannelByHandle()` | channels.list (1 unit) | 핸들로 채널 조회 |
+| `getChannelInfo()` | channels.list (1 unit) | 채널 정보 (배너 등) |
+
+---
+
 ## 유용한 명령어
 
 ```bash