MatchCut

생성 이미지를 업로드하고, 기준 이미지와 비교해 품질을 검수하는 데이터 운영 도구입니다. 자동 판정은 기준 비교가 실제로 수행된 결과에만 적용하고, 그 외 결과는 사람 검토 대상으로 남깁니다.

• 프론트엔드: Next.js
• 로컬 분석: transformers.js (CLIP Vision)
• 서버 분석(선택): FastAPI + InsightFace
• 저장소: Supabase (DB + Storage)

---

핵심 흐름

graph TD
    U["Data Manager"] --> A["Next.js UI"]
    A --> B["Supabase Storage/DB"]

    A --> C["Client Analysis: CLIP"]
    A --> D["API Proxy (/api/python)"]
    D --> E["FastAPI Backend"]
    E --> F["InsightFace Analysis"]

    C --> G["Score Result"]
    F --> G
    G --> H["Status Update in Supabase"]

Loading

---

현재 구현 기능

• Ingest: 이미지 업로드 + 메타데이터(batch/label/scene) 저장
• Client 분석: CLIP 임베딩 유사도 계산
• Server 분석: FastAPI에서 대상/기준 이미지를 다운로드해 얼굴 임베딩 코사인 유사도 계산
• Fallback 규칙: 기준 이미지가 없거나 비교 실패 시 얼굴 검출 신뢰도 기반 점수로 fallback (참고용 점수)
• 배치 판정 규칙:
  • 기준 비교 성공 결과만 자동 판정
  • 80점 이상: approved
  • 60점 미만: flagged
  • 60~79점: pending 유지
  • fallback/오류 결과: pending 유지(사람 검토)
• 업로드 실패 롤백: Storage/DB 실패 시 업로드 파일 정리
• 백엔드 상태 표시: 대시보드에 Backend Health(Online/Offline) 상태 카드 표시

---

빠른 시작

1) Frontend

cd MatchCut
npm install
npm run dev

2) Backend (선택)

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

백엔드를 같이 쓰면 프론트에서 /api/python/* 경로로 프록시 호출됩니다. (NODE_ENV !== production 이고 NEXT_PUBLIC_API_URL 미설정일 때만 로컬 프록시 사용)

---

Cloudflare 배포 (Frontend + Backend)

순서: Backend 먼저 배포 → 배포 URL을 Frontend 환경 변수에 연결

1) Frontend 프로젝트 (Cloudflare Workers + OpenNext)

cd MatchCut
npm install
npm run cf:build
npm run cf:deploy

• 설정 파일: wrangler.jsonc
• 배포 산출물: .open-next/
• NEXT_PUBLIC_API_URL 에 Backend Worker URL을 넣어야 합니다.

2) Backend 프로젝트 (Cloudflare Containers)

cd backend
npm install
npm run cf:deploy

• 설정 파일: backend/wrangler.jsonc
• Worker 엔트리: backend/cloudflare-worker/index.ts
• 컨테이너 이미지: backend/Dockerfile
• Wrangler에서 vars.MATCHCUT_CORS_ORIGINS를 프론트 도메인으로 반드시 변경하세요.

예시:

MATCHCUT_CORS_ORIGINS=https://matchcut.example.com,https://www.matchcut.example.com

---

환경 변수

Frontend (.env.local)

Key	설명
NEXT_PUBLIC_SUPABASE_URL	Supabase URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key
NEXT_PUBLIC_SUPABASE_ASSETS_BUCKET	업로드 에셋 버킷명 (기본값: matchcut-assets)
NEXT_PUBLIC_SUPABASE_REFERENCES_BUCKET	레퍼런스 버킷명 (기본값: matchcut-references)
NEXT_PUBLIC_API_URL	백엔드 직접 URL (Cloudflare 배포 시 필수, 예: https://matchcut-backend.<subdomain>.workers.dev)
MATCHCUT_LOCAL_BACKEND_URL	로컬 프록시 대상 URL (NEXT_PUBLIC_API_URL가 없을 때만 사용, 기본값 http://127.0.0.1:8000)

Backend (선택)

Key	기본값	설명
MATCHCUT_REQUEST_TIMEOUT	10	이미지 다운로드 타임아웃(초)
MATCHCUT_ALLOWED_IMAGE_HOSTS	빈값	허용 호스트 allowlist(쉼표 구분)
MATCHCUT_ENABLE_REFERENCE_COMPARE	true	false면 기준 이미지 비교를 비활성화하고 fallback만 사용
MATCHCUT_CORS_ORIGINS	http://localhost:3000,http://127.0.0.1:3000	허용할 프론트엔드 Origin 목록(쉼표 구분)
PORT	8000	FastAPI 포트

---

DB 마이그레이션 (레거시 정리)

기존 스키마(character_references, character_name, webtoon_title)를 사용 중이라면 아래 SQL을 먼저 실행하세요.

• scripts/migrations/20260221_cleanup_legacy_schema.sql

신규 프로젝트는 supabase_setup.sql을 그대로 적용하면 됩니다.

---

한계 / 참고

• 기준 이미지에 얼굴이 없거나 URL 접근이 불가하면 비교 점수 대신 fallback 점수를 생성할 수 있습니다. 이 값은 운영 참고용이며 자동 승인/반려에는 사용하지 않습니다.
• SSRF 방지를 위해 사설/로컬 주소는 차단되며, 필요 시 MATCHCUT_ALLOWED_IMAGE_HOSTS로 공개 호스트만 허용하는 방식으로 운영하세요.
• 서버 분석을 쓰려면 백엔드 프로세스가 실행 중이어야 합니다.

---

디렉터리

├── app/                          # Next.js pages
├── components/features/          # Ingest/Verify UI
├── lib/analyze-client.ts         # CLIP client analysis
├── lib/backend-client.ts         # FastAPI client
├── backend/main.py               # FastAPI + InsightFace
├── backend/cloudflare-worker/    # Cloudflare Container Worker entry
├── backend/wrangler.jsonc        # Cloudflare backend deploy config
├── wrangler.jsonc                # Cloudflare frontend deploy config
├── supabase_setup.sql            # DB schema
└── README.md