fromis_9/CLAUDE.md

# fromis_9 프로젝트

K-pop 그룹 프로미스나인 팬사이트

## 기술 스택

- **Frontend**: React 18, Vite, Tailwind CSS, React Query, Zustand
- **Backend**: Fastify, MySQL2, Meilisearch, Redis, AWS S3
- **Infrastructure**: Docker, Caddy

## 개발 환경

```bash
docker compose up -d --build
docker compose logs -f fromis9-frontend
```

## 환경 변수

DB 및 외부 서비스 접근 정보는 `.env` 파일 참조:
- DB_HOST, DB_USER, DB_PASSWORD, DB_NAME (MariaDB)
- RUSTFS_* (S3 호환 스토리지)
- YOUTUBE_API_KEY
- MEILI_MASTER_KEY (Meilisearch)
- KAKAO_REST_KEY (카카오맵 장소 검색)
- GEMINI_API_KEY (대학 축제 크롤러 봇)

## 문서

- [docs/architecture.md](docs/architecture.md) - 프로젝트 구조
- [docs/api.md](docs/api.md) - API 명세
- [docs/development.md](docs/development.md) - 개발/배포 가이드
- [docs/logs.md](docs/logs.md) - 활동 로그 시스템

## 작업 시 주의사항

- **문서 업데이트 필수**: 작업이 완료되면 항상 `docs/` 폴더의 관련 문서를 업데이트할 것
- **활동 로그 필수**: 새로운 관리자 라우트나 봇 기능을 추가할 때 `logActivity` 호출을 포함할 것 (자세한 사용법은 `docs/development.md` 참조)
docs: 프로젝트 개발환경 문서 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-01-18 18:54:27 +09:00			`# fromis_9 프로젝트`

			`K-pop 그룹 프로미스나인 팬사이트`

			`## 기술 스택`

			`- Frontend: React 18, Vite, Tailwind CSS, React Query, Zustand`
			`- Backend: Fastify, MySQL2, Meilisearch, Redis, AWS S3`
			`- Infrastructure: Docker, Caddy`

			`## 개발 환경`

			```bash
			`docker compose up -d --build`
			`docker compose logs -f fromis9-frontend`
			```

refactor: 일정 API source 객체 구조 변경 - source_name, source_url → source: { name, url } 형태로 변경 - YouTube: schedule_youtube에서 video_id로 URL 생성 - X: schedule_x에서 post_id로 URL 생성 - 프론트엔드 전체 파일 source 객체 형태로 수정 - 문서 업데이트 (api.md, architecture.md, migration.md 등) - tracks → album_tracks 테이블명 변경 반영 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-01-18 21:50:04 +09:00			`## 환경 변수`

			DB 및 외부 서비스 접근 정보는 `.env` 파일 참조:
			`- DB_HOST, DB_USER, DB_PASSWORD, DB_NAME (MariaDB)`
			`- RUSTFS_* (S3 호환 스토리지)`
			`- YOUTUBE_API_KEY`
			`- MEILI_MASTER_KEY (Meilisearch)`
feat(festival-bot): 대학 축제 크롤러 봇 구현 (3단계) 검색 페이지(memogipost)를 크롤링하여 프로미스나인 출연 대학 축제를 Gemini url_context로 추출, 행사 일정을 자동 생성하는 봇. 백엔드: - services/event.js: 이벤트 생성 로직 공유화 (upsertVenue, createEventSchedule, 카카오 검색) - services/festival/: scraper(검색 페이지 크롤) + gemini(추출) + index(봇 플러그인) - routes/admin/festival-bots.js: 축제 봇 CRUD API - scheduler.js: festival 타입 지원, 시간 단위 cron(0 /H * *) 변환 - 처리한 글 URL은 festival_crawl_log에 기록, 새 글 없으면 Gemini 미호출 - 학교명 부분일치 중복 감지, 활동 멤버 전체 자동 등록 - Gemini 503/500/429 재시도 로직 기타 수정: - 행사 상세 페이지 관련 링크 줄바꿈 (truncate → break-all) - 대학 축제 아이콘 변경 (GraduationCap → PartyPopper) - docs/api.md, CLAUDE.md 환경변수 문서화 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> 2026-05-20 22:28:24 +09:00			`- KAKAO_REST_KEY (카카오맵 장소 검색)`
			`- GEMINI_API_KEY (대학 축제 크롤러 봇)`
refactor: 일정 API source 객체 구조 변경 - source_name, source_url → source: { name, url } 형태로 변경 - YouTube: schedule_youtube에서 video_id로 URL 생성 - X: schedule_x에서 post_id로 URL 생성 - 프론트엔드 전체 파일 source 객체 형태로 수정 - 문서 업데이트 (api.md, architecture.md, migration.md 등) - tracks → album_tracks 테이블명 변경 반영 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-01-18 21:50:04 +09:00
docs: 프로젝트 개발환경 문서 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-01-18 18:54:27 +09:00			`## 문서`

			`- [docs/architecture.md](docs/architecture.md) - 프로젝트 구조`
			`- [docs/api.md](docs/api.md) - API 명세`
			`- [docs/development.md](docs/development.md) - 개발/배포 가이드`
feat(festival-bot): 대학 축제 크롤러 봇 구현 (3단계) 검색 페이지(memogipost)를 크롤링하여 프로미스나인 출연 대학 축제를 Gemini url_context로 추출, 행사 일정을 자동 생성하는 봇. 백엔드: - services/event.js: 이벤트 생성 로직 공유화 (upsertVenue, createEventSchedule, 카카오 검색) - services/festival/: scraper(검색 페이지 크롤) + gemini(추출) + index(봇 플러그인) - routes/admin/festival-bots.js: 축제 봇 CRUD API - scheduler.js: festival 타입 지원, 시간 단위 cron(0 /H * *) 변환 - 처리한 글 URL은 festival_crawl_log에 기록, 새 글 없으면 Gemini 미호출 - 학교명 부분일치 중복 감지, 활동 멤버 전체 자동 등록 - Gemini 503/500/429 재시도 로직 기타 수정: - 행사 상세 페이지 관련 링크 줄바꿈 (truncate → break-all) - 대학 축제 아이콘 변경 (GraduationCap → PartyPopper) - docs/api.md, CLAUDE.md 환경변수 문서화 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> 2026-05-20 22:28:24 +09:00			`- [docs/logs.md](docs/logs.md) - 활동 로그 시스템`
feat: YouTube API 할당량 절감을 위한 playlist ID 캐싱 - uploads playlist ID를 Redis에 영구 캐싱 (불변값) - 일일 API 사용량 6,480 → 4,320 units (33% 절감) - 문서 업데이트 (컨테이너 분리 구조, X source.name 빈 문자열) - CLAUDE.md에 문서 업데이트 필수 안내 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-01-19 12:32:04 +09:00
			`## 작업 시 주의사항`

			- 문서 업데이트 필수: 작업이 완료되면 항상 `docs/` 폴더의 관련 문서를 업데이트할 것
docs: 새 기능 추가 시 logActivity 호출 필수 안내 추가 development.md에 로그가 자동 수집이 아님을 명시하고, CLAUDE.md 작업 주의사항에 활동 로그 필수 항목 추가. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-03-02 17:23:00 +09:00			- 활동 로그 필수: 새로운 관리자 라우트나 봇 기능을 추가할 때 `logActivity` 호출을 포함할 것 (자세한 사용법은 `docs/development.md` 참조)