From 742c0f1bcc8fd828886342d617b9d23c05c54ace Mon Sep 17 00:00:00 2001 From: Haewon Kam Date: Fri, 10 Apr 2026 13:41:53 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=EB=B0=B1=EC=97=94=EB=93=9C?= =?UTF-8?q?=20=ED=8C=8C=EC=9D=B4=ED=94=84=EB=9D=BC=EC=9D=B8=20=EC=8B=A4?= =?UTF-8?q?=EC=A0=9C=20=EA=B5=AC=ED=98=84=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mock 데이터 기반이라는 잘못된 설명을 제거하고 실제 구현 상태로 업데이트: - 4단계 Edge Functions 파이프라인 (discover→collect→generate-report→generate-content-plan) - 실제 연동 API 목록 (YouTube/Apify/Naver/Firecrawl/Perplexity) - DB 테이블 구조, _shared 유틸리티, 환경변수 정리 - 배포 방법 (Vercel 수동 + Supabase Functions) Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 60900b9..e2cdb47 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -INFINITH Demo — AI 마케팅 분석 플랫폼의 프론트엔드 데모. 성형외과(뷰성형외과)를 대상으로 YouTube/Instagram/Facebook/웹사이트를 분석하고, 변환 전략/로드맵/KPI를 제안하는 마케팅 리포트를 보여준다. 현재는 mock 데이터 기반이며 실제 API 연동은 미구현 상태. +INFINITH — AI 마케팅 분석 플랫폼. 성형외과를 대상으로 YouTube/Instagram/Facebook/네이버블로그/네이버플레이스/강남언니를 분석하고, 변환 전략/로드맵/KPI를 제안하는 마케팅 리포트를 생성한다. + +**프론트엔드(React) + 백엔드(Supabase Edge Functions) 모두 실제 구현 완료.** `src/data/` mock 데이터는 개발 fallback 용도로만 남아 있으며, 실제 파이프라인은 Supabase Edge Functions에서 실행된다. ## Commands @@ -27,12 +29,43 @@ INFINITH Demo — AI 마케팅 분석 플랫폼의 프론트엔드 데모. 성 - `/distribute` — 콘텐츠 배포 - `/performance` — 성과 분석 -**Data flow:** -1. Pages → custom hooks (`useReport`, `useMarketingPlan`) → mock data (`src/data/`) -2. Hooks return `{ data, isLoading, error }` 패턴 (100ms delay로 API 시뮬레이션) +**Frontend Data flow:** +1. Pages → custom hooks (`useReport`, `useMarketingPlan`) → Supabase DB (`marketing_reports` 테이블) +2. Hooks return `{ data, isLoading, error }` 패턴 3. `ScreenshotContext`로 리포트 스크린샷 데이터 공유 4. `useExportPDF` 훅으로 리포트 → PDF 변환 +**Backend Pipeline (Supabase Edge Functions):** + +| Phase | Function | 역할 | +|---|---|---| +| 1 | `discover-channels` | 병원 URL → SNS 채널 발견 (registry fast-path → clinics 캐시 → Firecrawl 스크래핑) | +| 2 | `collect-channel-data` | 채널별 실제 데이터 수집 (YouTube API, Apify, Naver API, Firecrawl) | +| 3 | `generate-report` | Perplexity AI로 리포트 생성 + groundTruth 주입으로 수치 보정 | +| 4 | `generate-content-plan` | 마케팅 플랜 생성 | + +**실제 연동된 API:** +- YouTube Data API v3 — 구독자/조회수/영상 수 +- Apify — Instagram/Facebook 스크래퍼 +- Naver Search API — 네이버플레이스 검색 +- Naver Blog RSS — 공식 블로그 포스트 +- Firecrawl — 홈페이지 footer SNS 링크 추출, 강남언니 스크래핑 +- Perplexity AI — 리포트 JSON 생성 +- Gemini 2.5 Flash — 콘텐츠 이미지 생성 (`src/services/geminiImageGen.ts`) + +**주요 DB 테이블 (Supabase):** +- `marketing_reports` — 리포트 결과 (`channel_data`, `report`, `analysis_data` JSONB) +- `clinic_registry` — 병원 SNS 채널 등록 (fast-path 캐시) +- `clinics` — 병원 기본 정보 + 14일 TTL 캐시 +- `channel_snapshots` — 채널별 수집 이력 +- `analysis_runs` — 파이프라인 실행 로그 + +**Shared utilities (`supabase/functions/_shared/`):** +- `extractSocialLinks.ts` — URL → SNS handle 결정론적 추출 (regex 기반) +- `verifyHandles.ts` — 핸들 실제 존재 여부 검증 +- `dataQuality.ts` — `isMissingValue()`, `validateReportQuality()` +- `retry.ts` — 자동 재시도/타임아웃/rate limit 내장 fetch wrapper + **Type definitions** in `src/types/`: - `report.ts` — `MarketingReport` 및 하위 타입 (YouTubeAudit, InstagramAudit, etc.) - `plan.ts` — 마케팅 플랜 타입 @@ -40,6 +73,18 @@ INFINITH Demo — AI 마케팅 분석 플랫폼의 프론트엔드 데모. 성 **AI Integration:** `src/services/geminiImageGen.ts` — Gemini 2.5 Flash로 이미지 생성. `GEMINI_API_KEY` 환경변수 필요. +## Environment Variables + +**Supabase Edge Functions (Supabase Dashboard → Settings → Secrets):** +- `YOUTUBE_API_KEY` — YouTube Data API v3 +- `APIFY_API_KEY` — Instagram/Facebook 스크래퍼 +- `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` — Naver Search API +- `FIRECRAWL_API_KEY` — Firecrawl 스크래핑 +- `PERPLEXITY_API_KEY` — 리포트 AI 생성 + +**Frontend (`.env.local`):** +- `GEMINI_API_KEY` — Gemini 이미지 생성 + ## Styling - Tailwind CSS 4 (`@theme` directive in `src/index.css`) @@ -55,4 +100,5 @@ INFINITH Demo — AI 마케팅 분석 플랫폼의 프론트엔드 데모. 성 ## Deployment -Vercel (SPA 모드 — 모든 경로 `/index.html`로 리라이트) +- **Frontend:** Vercel (SPA 모드 — 모든 경로 `/index.html`로 리라이트). `git push` 후 `vercel --prod` 수동 실행 필요 (Gitea 자동 트리거 없음) +- **Backend:** Supabase Edge Functions — `supabase functions deploy ` 으로 개별 배포