263 lines
10 KiB
Markdown
263 lines
10 KiB
Markdown
# INFINITH SaaS Database Schema V3
|
|
|
|
**작성일**: 2026-04-05
|
|
**마이그레이션 파일**: `supabase/migrations/20260405_saas_schema_v3.sql`
|
|
|
|
## 설계 원칙
|
|
|
|
1. **CLINIC-CENTRIC**: 병원 1개 = 1행. URL이 달라도 같은 병원이면 같은 행
|
|
2. **TIME-SERIES**: 채널 메트릭은 INSERT-only 스냅샷 (시계열 쿼리)
|
|
3. **SEPARATION**: 원시 데이터 / 분석 리포트 / 콘텐츠 전략 분리
|
|
4. **LOOP-READY**: 매 분석이 이전 데이터를 참조해 전략 자동 조정
|
|
5. **MULTI-TENANT**: user_id 기반 접근 제어 (미래 auth)
|
|
|
|
---
|
|
|
|
## ERD (Entity Relationship)
|
|
|
|
```
|
|
clinics (병원 마스터)
|
|
├─ analysis_runs (분석 실행 히스토리) ← 매주 1행씩 쌓임
|
|
│ ├─ channel_snapshots (채널별 시계열 메트릭) ← INSERT-only
|
|
│ ├─ screenshots (스크린샷 증거)
|
|
│ └─ performance_metrics (성과 메트릭)
|
|
│ └─ strategy_adjustments (전략 조정 근거)
|
|
├─ channel_configs (사용자 수동 채널 연결)
|
|
├─ content_plans (콘텐츠 기획 — 활성 1개)
|
|
│ └─ content_performance (개별 콘텐츠 성과)
|
|
└─ (marketing_reports) ← 레거시 호환
|
|
```
|
|
|
|
---
|
|
|
|
## 테이블 상세
|
|
|
|
### 1. `clinics` — 병원 마스터
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| user_id | UUID | 소유자 (미래 auth) |
|
|
| url | TEXT UNIQUE | 대표 URL |
|
|
| name | TEXT | 한국어 병원명 |
|
|
| name_en | TEXT | 영문 병원명 |
|
|
| domain | TEXT | 도메인 |
|
|
| address, phone | TEXT | 기본 정보 |
|
|
| established_year | INT | 개원 연도 |
|
|
| services | TEXT[] | 시술 목록 |
|
|
| branding | JSONB | 컬러, 폰트, 로고, 태그라인 |
|
|
| social_handles | JSONB | 검증된 소셜 핸들 |
|
|
| verified_channels | JSONB | Phase 1 결과 캐시 |
|
|
| analysis_frequency | TEXT | 'manual' / 'daily' / 'weekly' / 'monthly' |
|
|
| last_analyzed_at | TIMESTAMPTZ | 마지막 분석 시간 |
|
|
|
|
### 2. `analysis_runs` — 분석 실행 히스토리
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id | UUID FK → clinics | |
|
|
| status | TEXT | pending/discovering/collecting/generating/complete/partial/error |
|
|
| scrape_data | JSONB | Firecrawl 원시 데이터 |
|
|
| raw_channel_data | JSONB | API 수집 원시 데이터 |
|
|
| analysis_data | JSONB | 시장 분석 |
|
|
| vision_analysis | JSONB | Vision 분석 결과 |
|
|
| report | JSONB | AI 리포트 |
|
|
| channel_errors | JSONB | 채널별 에러 기록 |
|
|
| trigger | TEXT | 'manual' / 'scheduled' / 'webhook' |
|
|
|
|
### 3. `channel_snapshots` — 채널별 시계열 ⭐ 핵심
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id | UUID FK → clinics | |
|
|
| run_id | UUID FK → analysis_runs | |
|
|
| channel | TEXT | youtube/instagram/facebook/gangnamUnni/... |
|
|
| handle | TEXT | @handle 또는 URL |
|
|
| followers | INT | 구독자/팔로워 |
|
|
| posts | INT | 게시물/영상 수 |
|
|
| total_views | BIGINT | 총 조회수 |
|
|
| rating | NUMERIC(3,1) | 평점 |
|
|
| reviews | INT | 리뷰 수 |
|
|
| health_score | INT | 0-100 |
|
|
| details | JSONB | 상세 (top videos, latest posts 등) |
|
|
| screenshot_url | TEXT | 채널 랜딩 스크린샷 |
|
|
| captured_at | TIMESTAMPTZ | 캡처 시간 |
|
|
|
|
**핵심**: INSERT-only. 절대 UPDATE 하지 않음. `captured_at` 기준 시계열 쿼리.
|
|
|
|
### 4. `screenshots` — 스크린샷 증거
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id, run_id | UUID FK | |
|
|
| channel | TEXT | 어떤 채널 |
|
|
| page_type | TEXT | main/doctors/surgery/landing |
|
|
| url | TEXT | 이미지 URL (Supabase Storage) |
|
|
| source_url | TEXT | 원본 페이지 URL |
|
|
| vision_data | JSONB | Gemini Vision 추출 데이터 |
|
|
|
|
### 5. `content_plans` — 콘텐츠 기획
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id | UUID FK → clinics | |
|
|
| run_id | UUID FK → analysis_runs | 어떤 분석 기반 |
|
|
| brand_guide | JSONB | 브랜딩 가이드 |
|
|
| channel_strategies | JSONB | 채널별 전략 |
|
|
| content_strategy | JSONB | 필라, 타입, 워크플로우 |
|
|
| calendar | JSONB | 4주 캘린더 |
|
|
| is_active | BOOLEAN | 현재 활성 기획 |
|
|
|
|
### 6. `channel_configs` — 사용자 수동 채널 연결
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id | UUID FK | |
|
|
| channel | TEXT | 채널 종류 |
|
|
| handle | TEXT | @handle |
|
|
| is_verified | BOOLEAN | 사용자가 직접 확인 |
|
|
| access_token | TEXT | OAuth token (미래) |
|
|
|
|
### 7. `performance_metrics` — 성과 메트릭 (루프 핵심)
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id, run_id | UUID FK | |
|
|
| prev_run_id | UUID FK | 이전 분석 (비교 기준) |
|
|
| channel_deltas | JSONB | 채널별 변화량 |
|
|
| kpi_progress | JSONB | KPI 달성률 |
|
|
| top_performing_content | JSONB | 성과 좋은 콘텐츠 |
|
|
| underperforming_channels | TEXT[] | 성과 미달 채널 |
|
|
| strategy_suggestions | JSONB | AI 전략 조정 제안 |
|
|
|
|
### 8. `content_performance` — 개별 콘텐츠 성과
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id | UUID FK | |
|
|
| plan_id | UUID FK | 어떤 기획의 콘텐츠 |
|
|
| channel, content_type | TEXT | 채널 + 유형 |
|
|
| views, likes, comments, shares | INT | 반응 지표 |
|
|
| engagement_rate | NUMERIC | 참여율 |
|
|
| performance_score | INT | 0-100 |
|
|
|
|
### 9. `strategy_adjustments` — 전략 조정 히스토리
|
|
| 컬럼 | 타입 | 설명 |
|
|
|------|------|------|
|
|
| id | UUID PK | |
|
|
| clinic_id, plan_id | UUID FK | |
|
|
| performance_id | UUID FK | 어떤 성과 분석 기반 |
|
|
| adjustment_type | TEXT | frequency_change/pillar_shift/channel_add/... |
|
|
| description | TEXT | "YouTube Shorts 주 3회 → 5회로 증가" |
|
|
| reason | TEXT | "Shorts 조회수가 Long-form 대비 300% 높음" |
|
|
| before_value, after_value | JSONB | 변경 전/후 값 |
|
|
|
|
---
|
|
|
|
## Views (트렌드 쿼리용)
|
|
|
|
### `channel_latest`
|
|
각 채널의 최신 스냅샷만 반환. `DISTINCT ON` + `ORDER BY captured_at DESC`.
|
|
|
|
### `channel_weekly_delta`
|
|
현재 vs 7일 전 스냅샷을 `LATERAL JOIN`으로 비교. 팔로워 변화율(%) 자동 계산.
|
|
|
|
---
|
|
|
|
## 성과 → 기획 루프 플로우
|
|
|
|
```
|
|
Week N:
|
|
1. analysis_run 생성
|
|
2. channel_snapshots INSERT (현재 메트릭)
|
|
3. performance_metrics 생성 (이전 run과 비교)
|
|
→ channel_deltas: {youtube: +2%, instagram: +7.1%}
|
|
→ kpi_progress: [{metric: "YouTube 구독자", progress: 97.4%}]
|
|
→ strategy_suggestions: ["Instagram Reels 빈도 증가 권장"]
|
|
4. strategy_adjustments INSERT (조정 내역)
|
|
5. content_plans UPDATE (조정 반영)
|
|
→ Content Director가 strategy_suggestions를 기반으로 캘린더 자동 조정
|
|
6. report 생성 (이전 분석 대비 변화 포함)
|
|
|
|
Week N+1:
|
|
→ 2번부터 반복. channel_snapshots에 데이터가 쌓이면서 트렌드 정확도 ↑
|
|
```
|
|
|
|
---
|
|
|
|
## 기존 호환성
|
|
|
|
| 기존 테이블 | 상태 | 이관 계획 |
|
|
|-----------|------|---------|
|
|
| `marketing_reports` | 유지 (deprecated) | 기존 API 호환 유지, 새 데이터는 새 테이블에만 저장 |
|
|
| `scrape_results` | 유지 | 캐시용 |
|
|
|
|
---
|
|
|
|
## 구현 체크리스트
|
|
|
|
### Phase 1: DB 마이그레이션 (테이블 생성)
|
|
|
|
- [ ] Supabase Dashboard에서 `20260405_saas_schema_v3.sql` 실행
|
|
- [ ] 테이블 9개 생성 확인: clinics, analysis_runs, channel_snapshots, screenshots, content_plans, channel_configs, performance_metrics, content_performance, strategy_adjustments
|
|
- [ ] View 2개 생성 확인: channel_latest, channel_weekly_delta
|
|
- [ ] RLS 정책 적용 확인
|
|
- [ ] 인덱스 생성 확인
|
|
|
|
### Phase 2: Edge Function 전환 — discover-channels
|
|
|
|
- [ ] `discover-channels/index.ts`: `clinics` 테이블에 UPSERT (url 기준)
|
|
- [ ] `discover-channels/index.ts`: `analysis_runs` 테이블에 INSERT (status: 'discovering')
|
|
- [ ] `discover-channels/index.ts`: `clinic.verified_channels` 업데이트
|
|
- [ ] 기존 `marketing_reports`에도 병행 쓰기 유지 (호환성)
|
|
- [ ] 검증: 분석 실행 → clinics + analysis_runs 행 생성 확인
|
|
|
|
### Phase 3: Edge Function 전환 — collect-channel-data
|
|
|
|
- [ ] `collect-channel-data/index.ts`: `channel_snapshots`에 채널별 INSERT
|
|
- [ ] `collect-channel-data/index.ts`: `screenshots`에 스크린샷 INSERT
|
|
- [ ] `collect-channel-data/index.ts`: `analysis_runs.raw_channel_data` 업데이트
|
|
- [ ] `collect-channel-data/index.ts`: `analysis_runs.vision_analysis` 업데이트
|
|
- [ ] 기존 `marketing_reports.channel_data`에도 병행 쓰기 유지
|
|
- [ ] 검증: channel_snapshots에 채널별 행 생성 확인
|
|
|
|
### Phase 4: Edge Function 전환 — generate-report
|
|
|
|
- [ ] `generate-report/index.ts`: `analysis_runs.report` 업데이트
|
|
- [ ] `generate-report/index.ts`: `analysis_runs.status = 'complete'`
|
|
- [ ] `generate-report/index.ts`: `clinics.last_analyzed_at` 업데이트
|
|
- [ ] `content_plans` 자동 생성 (transformPlan 로직 서버사이드 이동)
|
|
- [ ] 기존 `marketing_reports.report`에도 병행 쓰기 유지
|
|
- [ ] 검증: analysis_runs.status = 'complete' + report JSONB 생성 확인
|
|
|
|
### Phase 5: 성과 분석 루프 구현
|
|
|
|
- [ ] 반복 분석 시 `performance_metrics` 자동 생성 (이전 run 대비)
|
|
- [ ] `channel_weekly_delta` View 쿼리 테스트
|
|
- [ ] `strategy_suggestions` 생성 로직 (Content Director 연동)
|
|
- [ ] `content_plans` 자동 업데이트 (전략 조정 반영)
|
|
- [ ] `strategy_adjustments` 히스토리 기록
|
|
- [ ] 검증: 2회 연속 분석 → performance_metrics에 변화량 기록 확인
|
|
|
|
### Phase 6: Frontend 전환
|
|
|
|
- [ ] `useReport` 훅: analysis_runs + channel_snapshots에서 읽기
|
|
- [ ] `useMarketingPlan` 훅: content_plans에서 읽기
|
|
- [ ] ReportPage: channel_snapshots 시계열 데이터로 트렌드 차트 추가
|
|
- [ ] KPIDashboard: performance_metrics의 달성률 표시
|
|
- [ ] 검증: 기존 리포트 URL이 새 테이블에서도 정상 렌더링
|
|
|
|
### Phase 7: 스케줄링
|
|
|
|
- [ ] `clinics.analysis_frequency` 기반 자동 분석 트리거
|
|
- [ ] Supabase Cron 또는 external scheduler 연동
|
|
- [ ] `analysis_runs.trigger = 'scheduled'` 기록
|
|
- [ ] 검증: 주간 자동 분석 실행 확인
|
|
|
|
### Phase 8: 기존 데이터 이관
|
|
|
|
- [ ] `marketing_reports` → `clinics` + `analysis_runs` 이관 스크립트
|
|
- [ ] `marketing_reports.channel_data` → `channel_snapshots` 변환
|
|
- [ ] `marketing_reports.report` → `analysis_runs.report` 복사
|
|
- [ ] 이관 후 기존 리포트 URL 정상 작동 확인
|
|
- [ ] `marketing_reports` deprecated 마킹
|