fromis_9/docs/youtube-bots-plan.md

YouTube 봇 동적 관리 기능 구현 계획

개요

현재 config/bots.js에 하드코딩된 YouTube 봇 설정을 DB 기반으로 변경하여, 관리 페이지에서 채널을 추가/수정/삭제할 수 있도록 함.

주요 기능

1. YouTube 핸들(@username) 입력 → 채널 정보 자동 조회
2. 동기화 간격 설정 (분 단위)
3. 다음 주 예정 일정 자동 생성 옵션 (요일, 시간, 제목 템플릿)
4. 봇 활성화/비활성화
5. 봇 삭제

---

1. DB 스키마

youtube_bots 테이블 생성

CREATE TABLE youtube_bots (
  id VARCHAR(50) PRIMARY KEY,           -- 봇 ID (youtube-{handle})
  channel_id VARCHAR(30) NOT NULL,      -- UC...
  channel_handle VARCHAR(50) NOT NULL,  -- @username
  channel_name VARCHAR(100) NOT NULL,   -- 채널 이름
  uploads_playlist_id VARCHAR(50),      -- UU... (캐싱용)
  cron_interval INT DEFAULT 2,          -- 분 단위 (2 = */2 * * * *)
  enabled TINYINT(1) DEFAULT 1,

  -- 제목 필터 (선택)
  title_filter VARCHAR(100),

  -- 멤버 설정 (선택)
  default_member_id INT,
  extract_members_from_desc TINYINT(1) DEFAULT 0,

  -- 다음 주 예정 일정 설정 (JSON)
  auto_schedule_config JSON,
  -- 예: {"dayOfWeek": 4, "time": "18:00:00", "titleTemplate": "{channelName} {episode}화", "deadlineDayOfWeek": 5}

  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

  UNIQUE KEY uk_channel_id (channel_id)
);

파일: backend/sql/youtube_bots.sql

---

2. 백엔드 API

2.1 채널 정보 조회 API (신규)

POST /api/admin/youtube-bots/lookup

YouTube API forHandle 파라미터로 채널 정보 조회.

// 요청
{ "handle": "@studiofromis_9" }

// 응답
{
  "channelId": "UCeUJ8B3krxw8zuDi19AlhaA",
  "handle": "studiofromis_9",
  "title": "스프 : 스튜디오 프로미스나인",
  "thumbnailUrl": "...",
  "uploadsPlaylistId": "UUeUJ8B3krxw8zuDi19AlhaA"
}

파일: backend/src/services/youtube/api.js - getChannelByHandle() 추가

2.2 봇 CRUD API (신규)

파일: backend/src/routes/admin/youtube-bots.js

메서드	경로	설명
GET	/api/admin/youtube-bots	봇 목록 조회
POST	/api/admin/youtube-bots	봇 추가
PUT	/api/admin/youtube-bots/:id	봇 수정
DELETE	/api/admin/youtube-bots/:id	봇 삭제

2.3 기존 봇 API 수정

파일: backend/src/routes/admin/bots.js

• GET /api/admin/bots: DB에서 YouTube 봇 목록 조회하도록 수정
• 기존 bots.js의 meilisearch-sync, x-fromis9는 유지 (YouTube 봇만 DB로 이동)

---

3. 스케줄러 수정

파일: backend/src/plugins/scheduler.js

변경 사항

1. 시작 시 DB에서 YouTube 봇 목록 로드
2. bots.js의 meilisearch-sync, x-fromis9는 기존대로 사용
3. 봇 추가/수정/삭제 시 스케줄 동적 업데이트

// getBots() 함수를 async로 변경하여 DB에서 조회
async getBots() {
  const staticBots = bots.filter(b => b.type !== 'youtube');
  const [youtubeBots] = await fastify.db.query('SELECT * FROM youtube_bots WHERE enabled = 1');
  return [...staticBots, ...youtubeBots.map(convertDbBotToConfig)];
}

// 봇 추가/삭제 시 스케줄러 동적 업데이트 메서드 추가
async addBot(bot) { ... }
async removeBot(botId) { ... }
async updateBot(botId, config) { ... }

---

4. YouTube 서비스 수정

파일: backend/src/services/youtube/index.js

변경 사항

• getManagedChannelIds(): DB에서 조회하도록 수정

---

5. 프론트엔드 UI

5.1 봇 추가/수정 모달

파일: frontend/src/components/pc/admin/YouTubeBotModal.jsx

입력 필드:

• 채널 핸들 (@username) - 입력 후 "조회" 버튼 → 채널 정보 표시
• 동기화 간격 (분): 드롭다운 (1, 2, 5, 10, 30, 60)
• 다음 주 예정 일정 활성화 (토글)
  • 요일 선택 (일~토)
  • 시간 입력 (HH:MM)
  • 제목 템플릿 (예: {channelName} {episode}화)
  • 마감 요일 선택
• 고급 설정 (접기/펼치기)
  • 제목 필터 (특정 키워드 포함 영상만)
  • 기본 멤버 선택
  • description에서 멤버 추출 (토글)

5.2 봇 목록 페이지 수정

파일: frontend/src/pages/pc/admin/schedules/ScheduleBots.jsx

• 섹션별로 분리: Meilisearch, YouTube, X
• YouTube 섹션에만 "봇 추가" 버튼
• BotCard에 "수정", "삭제" 버튼 추가 (YouTube 봇만)
• meilisearch, x 봇은 수정/삭제 버튼 없이 읽기 전용

5.3 BotCard 컴포넌트 수정

파일: frontend/src/components/pc/admin/BotCard.jsx

• onEdit, onDelete props 추가
• YouTube 타입일 때만 수정/삭제 버튼 표시

5.4 API 클라이언트

파일: frontend/src/api/admin/bots.js

// 추가할 함수
export const lookupChannel = (handle) => fetch('/admin/youtube-bots/lookup', { method: 'POST', body: { handle } })
export const createYouTubeBot = (data) => fetch('/admin/youtube-bots', { method: 'POST', body: data })
export const updateYouTubeBot = (id, data) => fetch(`/admin/youtube-bots/${id}`, { method: 'PUT', body: data })
export const deleteYouTubeBot = (id) => fetch(`/admin/youtube-bots/${id}`, { method: 'DELETE' })

---

6. 마이그레이션

기존 bots.js의 YouTube 봇 3개를 DB로 이동:

INSERT INTO youtube_bots (id, channel_id, channel_handle, channel_name, cron_interval, enabled)
VALUES
  ('youtube-fromis9', 'UCXbRURMKT3H_w8dT-DWLIxA', 'fromis9', 'fromis_9', 2, 1),
  ('youtube-studio', 'UCeUJ8B3krxw8zuDi19AlhaA', 'studiofromis_9', '스프 : 스튜디오 프로미스나인', 2, 1),
  ('youtube-musinsa', 'UCtfyAiqf095_0_ux8ruwGfA', 'maboroshimusinsaTV', 'MUSINSA TV', 2, 1);

-- youtube-studio 예정 일정 설정
UPDATE youtube_bots SET auto_schedule_config = '{"dayOfWeek":4,"time":"18:00:00","titleTemplate":"{channelName} {episode}화","deadlineDayOfWeek":5}' WHERE id = 'youtube-studio';

-- youtube-musinsa 필터/멤버 설정
UPDATE youtube_bots SET title_filter = '성수기', default_member_id = 7, extract_members_from_desc = 1 WHERE id = 'youtube-musinsa';

파일: backend/sql/youtube_bots_seed.sql

---

파일 변경 목록

신규 파일

파일	설명
backend/sql/youtube_bots.sql	테이블 생성 SQL
backend/sql/youtube_bots_seed.sql	초기 데이터 SQL
backend/src/routes/admin/youtube-bots.js	YouTube 봇 CRUD API
frontend/src/components/pc/admin/YouTubeBotModal.jsx	봇 추가/수정 모달

수정 파일

파일	변경 내용
backend/src/services/youtube/api.js	getChannelByHandle() 추가
backend/src/services/youtube/index.js	DB 기반으로 변경
backend/src/plugins/scheduler.js	DB에서 봇 로드, 동적 업데이트
backend/src/routes/admin/bots.js	DB 통합 조회
backend/src/routes/index.js	youtube-bots 라우트 등록
backend/src/config/bots.js	YouTube 봇 제거
frontend/src/pages/pc/admin/schedules/ScheduleBots.jsx	섹션별 분리, 추가/수정/삭제 UI
frontend/src/components/pc/admin/BotCard.jsx	수정/삭제 버튼
frontend/src/api/admin/bots.js	API 함수 추가

---

검증 방법

1. DB 테이블 생성: docker compose exec fromis9-db mysql -u... -e "DESC youtube_bots"
2. 채널 조회 API: @studiofromis_9 입력 → 채널 정보 반환 확인
3. 봇 추가: 새 채널 추가 후 목록에 표시, 스케줄러 동작 확인
4. 봇 수정: 동기화 간격 변경 후 cron 재등록 확인
5. 봇 삭제: 삭제 후 목록에서 제거, 스케줄러 중지 확인
6. 예정 일정: 설정된 요일에 예정 일정 자동 생성 확인