Shopping Assistant

쇼핑 중 발견한 옷의 상품 페이지 URL을 붙여 넣으면 "이 옷, 나한테 맞을까?"에 답해 주는 서비스입니다. 소재, 사이즈, 취향, 관리 난이도를 내 기준(체형, 선호 핏, 쇼핑 성향)으로 판단해 하나의 결과로 보여 줍니다.

로그인 없이 바로 쓸 수 있습니다. Supabase가 연결되어 있으면 첫 방문자는 익명 사용자로 생성되고, 프로필, 취향, 분석 기록은 Supabase DB에 저장됩니다. localStorage는 캐시와 네트워크 실패 fallback으로 계속 유지됩니다.

로컬 실행

npm install
npm run dev

http://localhost:3000을 엽니다. API 키 없이도 실행되며, 이때는 AI 없이 동작합니다(아래 "동작 모드" 참고).

Gemini API 연결

상품 페이지는 형식이 제각각이라, 페이지 텍스트를 구조화된 상품 정보로 바꾸는 단계에만 Gemini를 씁니다. 추천 점수는 Gemini가 만들지 않습니다. 점수, 소재 평가, 취향 매칭, 사이즈 추천, 관리법은 기존 규칙 기반 코드가 계산합니다.

1. Google AI Studio에서 API 키를 발급합니다.

2. .env.example을 .env.local로 복사하고 값을 채웁니다.

   cp .env.example .env.local
   

   변수	필수	설명
   GEMINI_API_KEY	예 (AI를 쓰려면)	서버에서만 읽습니다. 브라우저 번들, 로그, 에러 응답에 나가지 않습니다.
   GEMINI_MODEL	아니오	첫 번째로 시도할 모델. 기본값 gemini-3.5-flash-lite. 비워 두는 것을 권장합니다. 아래 fallback 순서는 이 값과 상관없이 뒤에 이어집니다.
   NEXT_PUBLIC_SUPABASE_URL	예 (동기화를 쓰려면)	Supabase Project URL. 브라우저에서 publishable key와 함께 사용합니다.
   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	예 (동기화를 쓰려면)	Supabase publishable key. service-role key는 절대 넣지 않습니다.

3. 개발 서버를 다시 시작합니다. 키를 넣는 것 외에 코드 수정은 필요 없습니다.

SDK는 공식 @google/genai를 쓰고, 모델에는 JSON Schema 기반 구조화 출력(responseJsonSchema)을 요청합니다. 모델 목록과 상태는 공식 모델 문서를 확인하세요. 모델 ID는 바뀔 수 있어서 코드가 아니라 환경변수로 둡니다.

동작 모드

상태	동작
GEMINI_API_KEY 있음	페이지에서 읽은 텍스트를 Gemini로 구조화하고, 결과를 페이지 원문과 대조해 검증합니다.
키 없음	구조화 데이터(JSON-LD), 메타 태그, 본문 정규식으로 추출합니다. 못 찾은 항목은 경고로 보여 주고, 설명 직접 입력으로 보완할 수 있습니다.
Gemini 오류, 한도 초과, 시간 초과	앱은 계속 동작합니다. 위 "키 없음"과 같은 결과에 "AI 분석을 쓰지 못했다"는 안내와 직접 입력 버튼이 붙습니다. 내부 오류 문구나 키는 노출하지 않습니다.
"샘플로 보기"	네트워크 없이 샘플 상품(가상 데이터)으로 전체 흐름을 보여 줍니다.

구조

상품 URL
  → POST /api/analyze-url                   (서버)
  → safeFetch: URL 검증, 연결 시점 IP 검증, 리다이렉트 재검증, 크기·시간 제한
  → htmlExtraction: JSON-LD / 메타 / 본문 텍스트 (결정론적 추출)
  → GeminiProductExtractionProvider        (키가 있을 때만)
        구조화 출력(JSON Schema) → zod 검증 → 페이지 원문 대조
  → ProductFacts (각 값에 출처 표시)
  → 소재 평가 · 취향 매칭 · 사이즈 추천 · 관리 안내 · 점수   (브라우저, 규칙 기반)
  → Result

주요 위치:

경로	역할
components/ShoppingApp.tsx	화면 전체 (Home, Analyzing, Result, Fit, Preferences, History)
app/api/analyze-url/route.ts	분석 API (입력 검증, 스로틀, 중복 요청 합치기)
services/extraction/safeFetch.ts	SSRF 방어 fetch
services/extraction/geminiProvider.ts, geminiSchema.ts	Gemini 호출, 스키마, 검증, 매핑
services/extraction/urlExtraction.ts	추출 파이프라인과 병합 규칙
domain/	소재, 취향, 사이즈, 점수 규칙 (Gemini와 무관)
repository/localShoppingRepository.ts	localStorage cache/fallback 저장소
repository/supabaseShoppingRepository.ts	Supabase Auth/DB 저장소, 익명 세션, Kakao identity linking, migration
lib/supabase/	Supabase browser/server/proxy client
lib/urlSafety.ts, lib/env.ts, lib/requestGuard.ts	URL 안전 규칙, 환경변수 검증, 남용 방어

취향과 평가 metric

취향은 13개이고, 각 취향은 자기만의 metric 하나로만 평가합니다. 서로 다른 취향이 같은 값을 쓰지 않아서, 두 개를 골라도 같은 사실이 두 번 계산되지 않습니다(data/preferences.ts, 테스트로 고정).

분류	취향	metric
착용감	부드러운 촉감	softness
	가벼운 옷	lightweight
기능	보온성	warmth
	통기성	breathability (공기가 통하는 정도)
	땀 배출·속건	moistureWicking (땀을 이동시키고 말리는 정도)
	신축성	stretch
관리	세탁이 편함	washEase
	건조기 사용 가능	dryerSafe
	보풀 적음	pillingResistance
	구김 적음	wrinkleResistance
구매 성향	오래 입기	durability
	천연 소재 선호	naturalFiberRatio (천연 섬유 비중)
	가성비	valueForMoney (가격 대비 구성, 아래 참고)

이전 버전에서 합치거나 뺀 항목:

• 까슬거림 싫음 → 부드러운 촉감에 통합. 둘 다 같은 softness로 계산되던 중복이었습니다.
• 품질 우선은 제거. 브랜드, 봉제, 원단 등급은 상품 페이지만으로 판단할 수 없어서, 다른 항목으로 바꾸지 않고 뺐습니다.
• 통기성과 땀 배출, 세탁과 건조와 구김은 서로 다른 특성이라 각각 독립 metric이 되었습니다. "세탁은 쉬운데 건조기는 안 되는" 옷도 그대로 표현됩니다.

관리 항목은 제조사 안내가 있으면 그것을 가장 먼저 따르고(basis: product_page, 신뢰도 높음), 없을 때만 소재 특성으로 예상합니다(material_inference, 결과 화면에 구분해서 표시).

가격과 가성비

가격은 ProductFacts.pricing에 currentPrice(실제 결제하는 가격), originalPrice, discountRate, currency, 출처, 신뢰도로 들어갑니다. 할인율은 두 가격에서 직접 계산하고, 마케팅 문구는 믿지 않습니다.

추출 우선순위: JSON-LD Product/Offer → 메타 태그(product:price:*, og:price:*) → 마이크로데이터 → 본문의 라벨이 붙은 가격(정가, 판매가, 할인가 …) → Gemini. 본문에서는 통화 표시와 라벨이 모두 있는 숫자만 읽습니다(사이즈, 상품번호, 배송비를 가격으로 읽지 않기 위해서). Gemini가 돌려준 가격도 페이지에 그 숫자와 통화가 실제로 있어야만 인정하고, 없으면 null로 둡니다. 가격을 못 찾으면 비워 두고 경고만 남깁니다.

가성비(valueForMoney)는 내구성과 별개로 계산합니다. "현재 판매가에 비해 소재 구성과 기능이 어느 정도인가"를 보는 값입니다.

1. 상품 종류와 통화별 기준 가격(data/priceReference.ts)에 소재 원가 계수(폴리에스터 1 … 캐시미어 6)를 곱해 "비슷한 구성의 참고 가격대"를 만듭니다.
2. 현재 가격 ÷ 참고 가격대로 점수를 매기고, 내구성과 보풀 저항으로 ±5점만 보정합니다. 할인율은 점수를 올리지 않습니다(정가가 부풀려졌을 수 있어서).
3. 시장 전체 가격 데이터는 없으므로 결과는 "참고 추정"입니다. 신뢰도는 최대 medium이고, 화면에는 "브랜드, 봉제 완성도, 원단 등급은 반영하지 못했다"는 안내가 항상 붙습니다.
4. 가격, 소재, 상품 종류, 지원 통화 중 하나라도 없으면 "판단 어려움"이고 점수를 만들지 않습니다.

기준 가격표는 의도적으로 거칠고 고치기 쉬운 상수입니다. KRW와 USD만 지원하며, 다른 통화는 판단하지 않습니다.

정보가 부족할 때

• 판단할 수 없는 metric은 available: false입니다. 가짜 중간 점수를 넣지 않습니다.
• 취향 점수는 판단 가능한 항목만의 가중 평균이고, 판단 불가 항목은 분자와 분모에서 모두 빠집니다. 선택한 취향이 전부 판단 불가면 취향 점수는 null이고, 전체 궁합 점수는 남은 구성요소로만 계산합니다. 소재와 관리도 같은 방식입니다.
• 소재 정보가 일부만 있으면 신뢰도가 low가 되고 취향 점수에서 0.6배로 반영됩니다. 소재 특성으로 예상한 값은 신뢰도가 medium을 넘지 않습니다.
• 가격은 사용자가 가성비를 선택했을 때만 궁합 점수에 들어옵니다. 선택하지 않았다면 가격이 달라도 점수는 같습니다(테스트로 고정).
• 결과 화면은 선택한 기준마다 ✓ 잘 맞아요, △ 보통이에요, ✕ 아쉬워요, ? 정보가 부족해요로 보여 줍니다.

저장된 취향 마이그레이션

저장소는 스키마 버전(shopping-assistant:schema, 현재 2)을 갖습니다. 이전 버전에서 저장된 취향은 처음 읽을 때 한 번만 변환됩니다.

• 부드러운 촉감과 까슬거림 싫음 중 하나 또는 둘 다 선택돼 있으면 부드러운 촉감 하나가 됩니다. 두 항목이 모두 있으면 가중치는 합이 아니라 큰 쪽을 씁니다(두 배가 되지 않도록).
• 품질 우선은 삭제되고 다른 항목으로 바뀌지 않습니다.
• 프로필과 분석 기록은 건드리지 않습니다. 이전 기록은 저장된 그대로 열립니다.

사실과 추정의 구분

각 소재와 사이즈 값에는 출처(source)가 붙고 결과 화면에 표시됩니다.

• 상품 페이지에서 확인: structured-data, meta, page
• AI가 페이지에서 추출하고 페이지의 숫자와 대조: gemini-extracted
• 직접 입력: user-input, 샘플: demo
• 보온성, 촉감 같은 소재 감각과 관리법은 소재별 일반 특성으로 예상한 값이며, 상품 페이지의 관리 안내가 있으면 그것을 우선합니다.

Gemini가 상상한 값이 점수에 들어가지 않도록 두 겹으로 막습니다.

1. 프롬프트: 페이지에 없는 값은 null, [], unknown으로 돌려주도록 지시하고, 페이지 내용은 신뢰할 수 없는 데이터로 취급합니다(프롬프트 인젝션 대비).
2. 코드: 소재 비율과 사이즈 수치는 페이지 텍스트에 실제로 나타날 때만 통과합니다. 없으면 제외하고 경고를 남깁니다. 인치 표기는 cm로 환산하고 알립니다.

공유 링크 (지그재그)

지그재그 앱의 "공유하기"로 복사한 https://s.zigzag.kr/... 링크를 그대로 붙여 넣어도 분석됩니다. 일반 상품 URL은 아무 변화 없이 기존 경로를 탑니다.

입력 URL → 검증 → 공유 링크 resolver → 상품 페이지 URL → 기존 fetch → 추출 → Gemini

• 감지: s.zigzag.kr만 지그재그 공유 링크로 봅니다. 알려진 단축/딥링크 호스트(abr.ge, bit.ly, kko.to 등)는 일반 리다이렉트 resolver가 따라갑니다. 그 외 호스트는 요청 없이 그대로 통과합니다.
• 해석: 실제 응답은 s.zigzag.kr → abr.ge(추적 리다이렉트) → zigzag://... 구조이고, 목적지(fallback_desktop, 앱 링크의 url, catalog_product_id)가 추적 URL의 쿼리에 들어 있습니다. 첫 Location만 읽지 않고 쿼리, 앱 스킴, intent://, meta refresh, script 이동, 페이지 안의 fallback 필드를 모두 찾습니다. 이동 주소 안에 목적지가 이미 있으면 그 주소는 요청하지도 않습니다.
• 앱 스킴: zigzag://, intent://는 요청하지 않고 읽기만 합니다. javascript:, data:, file:, ftp: 등은 무시합니다. 링크에 웹 주소 없이 상품 ID만 있으면, 같은 링크의 fallback_desktop에서 확인한 형태(https://zigzag.kr/p/<id>)로만 만들고 derivedFromId로 표시합니다.
• 보안: 요청하는 모든 주소, 그리고 채택하는 목적지는 일반 URL과 같은 검증(사설/루프백/링크 로컬/메타데이터 IP, 포트, 자격 증명)을 다시 통과해야 합니다. 지그재그 resolver는 지그재그 호스트의 상품 경로만 채택합니다. 리다이렉트 5회, 해석 시간 6초, 루프 감지로 제한합니다.
• 상품 정보: 지그재그 상품 페이지는 상품 데이터(가격, 이미지, 판매자 상세 설명)를 __NEXT_DATA__ JSON에 담고 있어 화면 텍스트에는 보이지 않습니다. 지그재그 adapter가 이 JSON을 먼저 읽고(브라우저 렌더링 없음), 혼용률과 사이즈는 상세 설명 텍스트에서 읽습니다. 쿠폰가는 안내만 하고 판매가로 쓰지 않습니다. 페이지에 없는 값은 만들지 않습니다.
• 실패: 상품 페이지를 못 찾으면 "이 공유 링크에서 실제 상품 페이지를 찾지 못했어요."와 함께 상품 설명 직접 입력이 열립니다.
• 다른 쇼핑몰 추가: services/extraction/resolution/에 ShortUrlResolver를 구현하고 index.ts의 목록에 넣으면 됩니다. 페이지 데이터를 읽는 adapter는 services/extraction/adapters/에 추가합니다.

상세 정보가 접혀 있거나 이미지로만 있을 때

소재·사이즈·관리법이 본문에 없다고 바로 "정보 없음"으로 끝내지 않고, 클릭 없이 읽을 수 있는 곳을 순서대로 확인합니다. 브라우저 자동화(Playwright로 "더보기" 클릭)는 쓰지 않습니다. 앞 단계에서 얻은 값은 뒤 단계가 덮어쓰지 않고, 비어 있는 항목만 채웁니다.

단계	source 기록	읽는 곳
1	zigzag-next-data	페이지에 이미 들어 있는 __NEXT_DATA__ JSON. 접힌 "상품정보 제공고시"(essentials, product_info_map)와 판매자 상세 설명이 여기에 있습니다. "상세정보 참고" 같은 항목은 사실이 아니므로 버립니다.
2	zigzag-detail-api	사이즈 탭은 클릭해야 불러오는 데이터라서, 사이트가 쓰는 공개 GraphQL(api.zigzag.kr의 GetSizeInfo)을 같은 방식으로 한 번 호출합니다. 페이지 데이터에 사이즈가 없을 때만 호출합니다.
3	(텍스트 추출)	확보한 상세 설명·고시 항목에서 소재, 사이즈, 세탁법을 다시 읽고, Gemini 텍스트 추출에도 근거로 넘깁니다.
4	product-detail-image-vision	소재나 사이즈가 아직 비어 있을 때만, 상세 이미지를 후보 선별 후 Gemini 멀티모달로 읽습니다(아래).
5	직접 입력	그래도 없을 때만 사용자에게 설명 붙여넣기를 안내합니다.

extractionMetadata.detailSources에 단계별로 어떤 항목을 얻었는지 순서대로 남고, 이미지로 읽은 값은 개별 값에도 source: "image-vision"이 붙습니다.

이미지 읽기는 소재나 사이즈가 비어 있을 때만 시작합니다. 둘 다 있으면 관리법이 비어 있어도 시작하지 않고(이미지를 읽는 김에 관리법도 찾을 뿐, 관리법 하나만으로는 시작하지 않습니다), 비어 있는 항목만 묻고 채웁니다. 이미 확보한 값은 덮어쓰지 않습니다.

상세 이미지 URL 목록(뒤쪽 → 앞쪽 순으로 최대 24장 다운로드)
  → 긴 이미지는 겹치는 세로 타일로 자르고, 넓은 이미지는 폭 1000px로 줄여 JPEG로 압축 (sharp)
  → 타일이 6개 이하면 바로 읽기
  → 많으면: 흰 바탕 글자 이미지(표·안내문)처럼 보이는 타일 최대 24개를 번호가 그려진 contact sheet 2장으로 묶어
     Gemini가 "소재표 / 사이즈표 / 세탁정보가 있을 것 같은 번호"만 고름 (글자는 읽지 않음)
  → 정밀 추출은 두 번: ① 가장 표처럼 보이는 타일 4장(후보 선택과 동시에 시작) ② 후보 선택이 고른 나머지 타일 4장.
     부족한 항목만 지정해 원본 해상도로 읽음

• 번호는 17(17번 이미지) 또는 17-2(17번 이미지의 두 번째 타일)입니다. 폰트가 없는 서버에서도 읽히도록 번호는 글꼴 대신 도형(7-segment)으로 그립니다.
• 이미지 호출은 응답 시간 편차가 큽니다(같은 크기에서 2초~16초). 그래서 ① 후보 선택과 첫 정밀 추출을 순서대로 하지 않고 동시에 하고, ② 한 모델이 일정 시간(후보 선택 4초, 정밀 추출 6초) 안에 답하지 않으면 timeout을 기다리지 않고 다음 모델을 옆에서 함께 시작해(동시에 최대 2개) 먼저 유효한 답을 쓰며, ③ 이미지가 4장 이하이면 후보 선택 없이 모든 타일(최대 12개)을 4개씩 나눠 동시에 읽습니다. 한 상품에 여러 옷(자켓+스커트 세트)의 사이즈표가 섞이면 더 많은 쪽 한 종류만 쓰고 그렇게 했다고 알립니다. 후보 선택용 contact sheet는 낮은 해상도 토큰(MEDIA_RESOLUTION_MEDIUM)으로 보냅니다.
• 후보 선택이 실패하거나 시간이 모자라면 "표처럼 보이는 정도"로만 골라 읽습니다(mode: "heuristic").
• 시간 예산: 이미지 다운로드 6초, 후보 선택 12초 이내(각 시도 9초), 정밀 추출은 남은 시간(최소 8초), 이미지 단계 전체 30초. 요청 전체 54초 예산에서 남은 시간이 12초 미만이면 시작하지 않습니다. 실패해도 이미 얻은 값은 그대로 두고 경고만 붙입니다.
• 이미지 URL은 판매자가 올린 값이라 신뢰하지 않습니다. 페이지와 같은 SSRF 방어(사설/루프백/메타데이터 IP 차단, DNS 재검증, 리다이렉트 재검증)를 거치고, JPEG/PNG/WebP만 받으며, 장당 4MB·합계 30MB로 제한합니다. 디코딩에 실패한 이미지는 건너뜁니다.
• 이미지에는 원문 텍스트가 없어 글자와 대조할 수 없으므로 타당성으로 검증합니다. 혼용률 합계가 95~105%가 아니면 버리고, 치수는 옷 치수 범위를 벗어나면 버립니다. 관리법은 "세탁 가이드 바로가기" 같은 링크 문구를 걸러냅니다.
• 신뢰도는 최대 "medium"이고, 값에는 source: "image-vision"이, 메타데이터에는 어느 이미지(imageIndex)의 몇 번째 타일(tileIndex)에서 읽었는지(vision.evidence)와 단계별 소요 시간(vision.durationsMs, timingsMs)이 남습니다. 화면에는 "상세 이미지에서 AI가 읽은 값 (참고용)"으로 표시되고, 이 관리법으로 만든 건조기·세탁 평가도 "참고" 수준입니다.
• 이미지 안의 문구는 명령으로 취급하지 않습니다(시스템 지시에 명시).

사이즈표 해석 (옷 종류별)

사이즈표의 열이 어떤 치수인지는 옷 종류마다 다릅니다. 상품명으로 종류를 정하고(domain/garment.ts: 원피스 > 스커트 > 아우터 > 바지 > 니트 > 상의 > 셔츠 순으로 옷 이름이 소재·스타일 단어를 이깁니다), 카테고리를 모르면 표의 열(밑위·허벅지면 하의, 가슴이면 상의)로 정합니다.

종류	치수
상의 · 아우터	어깨, 가슴, 소매, 총장
하의	허리, 엉덩이, 허벅지, 밑위, 밑단, 총장
원피스	어깨, 가슴, 허리, 엉덩이, 소매, 총장
스커트	허리, 엉덩이, 총장, 밑단

"단면"(펼쳐 잰 폭)은 무조건 2배 하지 않고, 값이 단면으로 가능한 범위일 때만 둘레로 환산합니다. 표시가 "단면"인데 값이 너무 커서 단면일 수 없으면 판매자가 둘레를 잘못 적은 것으로 보고 그대로 쓰며 신뢰도를 낮춥니다. 표시가 없으면 둘레일 수 없는 작은 값만 환산하고, 둘 다 가능한 구간은 적힌 그대로 둡니다(domain/sizeMeasurements.ts). 하의와 스커트는 허리둘레로 사이즈를 고르고, 허리둘레를 입력하지 않았다면 키·몸무게로 추정하지 않고 입력을 안내합니다.

모션과 인터랙션

의존성을 더하지 않고 CSS와 작은 훅으로 만들었습니다(app/motion.css, components/motion/, lib/motion.ts). 효과의 수가 아니라 일관성을 기준으로 삼았습니다.

• 모션 토큰: 시간은 fast 160ms(누름, hover), standard 280ms(토글, 아코디언), slow 480ms(섹션·화면 전환), cinematic 1100ms(Home 인트로 한정) 네 가지, 곡선도 이름이 붙은 네 가지만 씁니다.
• GPU 친화: 계속 움직이는 속성은 transform과 opacity뿐입니다. 포인터 값은 rAF로 한 프레임에 한 번만 CSS 변수로 내보냅니다.
• 화면별 연출
  • Home: 확대 상태에서 자리잡는 인트로, 마우스에 반응하는 몇 픽셀의 시차, 천천히 움직이는 빛, 아주 약한 마그네틱 CTA.
  • Home → Analyzing: 누른 버튼에서 화면이 번지는 전환 뒤 Analyzing이 드러납니다. 분석은 그 전에 이미 시작돼 있고, 진행 레일은 실제 진행 상태를 따라갑니다.
  • Preferences: 포인터 위치 조명, 절제된 3D 기울기, 테두리를 따라 도는 빛, 선택 시 따뜻한 라임·크림 톤 오로라(선택·hover 상태에서만 켜짐).
  • Result: 스크롤 위치(IntersectionObserver)에 따라 왼쪽 비주얼이 MATCH → 사이즈 → 소재 → 취향 → 관리로 바뀝니다. 스크롤을 가로채거나 스냅하지 않습니다.
  • History: 3D Coverflow. 네이티브 스크롤과 scroll-snap 위에 위치만 CSS 변수로 얹었고, 버튼과 방향키로도 이동합니다.
  • 상품을 열면 View Transitions로 상품 비주얼이 다음 화면으로 이어집니다(미지원 브라우저는 그냥 전환).
• 접근성: hover는 (hover: hover) and (pointer: fine)에서만 동작해 터치 기기에서 고착되지 않고, prefers-reduced-motion에서는 움직임이 빠지되 상태 변화는 그대로 보입니다.

보안

• API 키는 서버 코드에서만 읽고, 클라이언트 컴포넌트는 lib/env.ts를 import하지 않습니다.
• .env.local은 .gitignore에 포함되어 있습니다. .env.example에는 빈 값만 있습니다.
• URL 분석은 SSRF 방어를 적용합니다.
  • http/https만 허용, 기본 포트(80/443)만 허용, 계정 정보(user:pw@)와 2048자 초과 URL 차단
  • localhost, *.local, *.internal, 단일 라벨 호스트, 사설/루프백/링크로컬/CGNAT/메타데이터(169.254.169.254)/예약 대역 차단 (IPv4, IPv6, IPv4-mapped, NAT64, 6to4 포함)
  • DNS 조회 결과를 연결 시점에 검증하고(DNS rebinding 방어), 리다이렉트는 최대 4번까지 매번 다시 검증
  • 응답 시간 8초, 압축 해제 후 1.5MB 제한, HTML Content-Type만 허용
• API는 JSON만 받고 본문 크기를 제한하며, 응답은 no-store입니다.

남용 방지와 한계

로그인이 없는 공개 API라 Gemini 호출 비용이 남용될 수 있습니다. 현재는 다음만 적용돼 있습니다.

• 입력 검증, 본문 크기 제한, 타임아웃, 서버 전용 API 키
• 같은 URL의 동시 요청 합치기, 화면의 중복 분석 방지
• 클라이언트별 분당 12회 제한

마지막 항목은 보안 장치가 아닙니다. 서버리스 인스턴스마다 메모리가 따로이고 인스턴스가 자주 바뀌므로, 한 인스턴스의 짧은 폭주만 완화합니다. 의도적인 우회는 막지 못합니다. 트래픽이 늘면 영구 저장소 기반 제한이 필요합니다(Vercel WAF의 Rate Limiting, Upstash Redis 등). 그 전까지는 Google AI Studio에서 키의 일일 한도와 예산 알림을 설정해 두세요.

배포 (GitHub, Vercel)

1. GitHub 저장소: https://github.com/chltmdgh1028-svg/AI-Shopping-Assistant (main 브랜치)
2. Vercel에서 저장소를 Import합니다. Framework는 Next.js로 자동 인식되며 별도 설정이 필요 없습니다.
3. Project → Settings → Environment Variables에서 GEMINI_API_KEY, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY를 추가합니다. GEMINI_MODEL은 선택입니다. Production(필요하면 Preview도)에 적용합니다.
4. 환경변수는 새 배포에만 적용됩니다. 값을 추가한 뒤 Redeploy 하세요.

키를 추가하기 전에도 배포는 정상 동작하고(AI 없이), 추가 후 재배포하면 Gemini 분석이 켜집니다.

Supabase 저장/로그인

Supabase Auth에서 Anonymous Sign-ins, Kakao provider, Allow users without an email, Manual identity linking을 켭니다.

DB schema와 RLS는 supabase/migrations/20261010120000_user_storage.sql에 있습니다.

npx supabase link --project-ref <project-ref>
npx supabase db push

테이블:

테이블	용도	RLS 기준
profiles	사용자 신체/핏 프로필 1개	user_id = auth.uid()
preferences	쇼핑 성향 배열 1개	user_id = auth.uid()
analysis_history	분석 결과 기록, (user_id, id) 복합 PK	user_id = auth.uid()

흐름:

1. 첫 방문 시 Supabase env가 있으면 signInAnonymously()로 익명 세션을 만듭니다.
2. 기존 localStorage profile/preferences/history는 첫 Supabase 연결 때 DB로 migration합니다. 원격 데이터가 이미 있으면 덮어쓰지 않고, history만 id 기준으로 합칩니다.
3. 이후 DB를 source of truth로 읽고, 읽은 snapshot을 localStorage에 cache합니다.
4. DB/network 실패 시 기존 localStorage fallback으로 계속 동작합니다.
5. Profile/History의 “Kakao로 연결”은 supabase.auth.linkIdentity({ provider: "kakao" })를 사용해 현재 anonymous user에 Kakao identity를 붙입니다.
6. 다른 기기에서 이미 연결한 Kakao 기록을 불러올 때는 “연결한 기록 불러오기”가 Kakao OAuth sign-in을 시작합니다.

테스트와 검증

npm test          # 단위, 통합 테스트
npm run lint
npm run typecheck
npm run build

테스트는 규칙 기반 도메인(소재, 취향, 사이즈, 점수), URL 안전 규칙, 로컬 HTTP 서버를 쓰는 fetch 동작(리다이렉트, 압축, EUC-KR, 크기·시간 제한), Gemini 스키마·검증·오류 처리(SDK는 모킹), 추출 파이프라인의 대체 동작, API 라우트의 입력 제한을 다룹니다. 실제 Gemini 호출은 자동 테스트에 포함되지 않습니다(키와 요금이 필요). 키를 넣은 뒤 개발 서버에서 상품 URL을 분석해 확인하세요.

현재 제한사항

• 자바스크립트로 그려지는 쇼핑몰(상품 정보를 클라이언트에서 렌더링)은 서버가 받는 HTML에 정보가 없을 수 있습니다. 이 경우 "설명 직접 입력"으로 보완합니다. 브라우저 렌더링 단계는 아직 없습니다.
• 일부 쇼핑몰은 자동 요청을 차단합니다. 쇼핑몰의 이용약관과 robots 정책은 별도로 확인해야 합니다.
• 사이즈 추천은 상품 사이즈표와 입력한 체형에 기반한 추정이며, 사이즈표를 못 읽으면 신뢰도를 낮게 표시합니다.
• Gemini 모델은 안정 라인이라도 시간이 지나면 교체됩니다. GEMINI_MODEL로 첫 모델을 바꿀 수 있고, 전체 순서는 lib/env.ts의 GEMINI_FALLBACK_MODELS에 있습니다.

모델 fallback

gemini-3.5-flash-lite → gemini-3.1-flash-lite → gemini-3.5-flash → gemini-3.8-flash → gemini-3-flash-preview → gemini-2.5-flash-lite → gemini-2.5-flash

• 각 모델은 1회만 시도합니다(SDK 자체 재시도는 끕니다). 한 모델이 timeout 이전에 끝나지 않으면 다음 모델로 넘어갑니다.
• 모델당 12초, 전체 28초 예산입니다. 예산이 소진되면 새 모델을 시작하지 않고, 페이지 기반 분석으로 계속합니다.
• 다음 경우에만 다음 모델로 넘어갑니다: 429(rate limit/quota), 404 또는 모델 접근 불가, 5xx, 네트워크 오류, timeout.
• API 키 오류, 잘못된 요청(400), 모델이 낸 형식 불량 출력은 모든 모델에서 똑같이 실패하므로 fallback 하지 않습니다.
• gemini-3.1-flash는 텍스트 모델로 존재하지 않고, gemini-3-flash는 gemini-3-flash-preview로만 제공됩니다. 2.5 계열은 기존 사용자에게만 열려 있어 마지막에 둡니다.
• 응답한 모델명은 extractionMetadata.aiModel에 기록되며 화면에는 표시하지 않습니다.
• Supabase 환경변수가 없거나 DB 연결에 실패하면 프로필, 취향, 기록은 이 기기 localStorage에만 저장됩니다.

앞으로의 계획

• 영구 저장소 기반 레이트 리미팅과 사용자별 한도
• 주요 쇼핑몰 전용 파서, JS 렌더링이 필요한 페이지 대응
• 상품 비교