diff --git a/design/uiux/prototype/02-매장정보등록.html b/design/uiux/prototype/02-매장정보등록.html index 795c414..c865ab3 100644 --- a/design/uiux/prototype/02-매장정보등록.html +++ b/design/uiux/prototype/02-매장정보등록.html @@ -725,8 +725,92 @@ }, 1500); }); + // 한식음식점 예제 데이터 로드 + function loadKoreanRestaurantExample() { + // 매장명 + storeNameInput.value = '수원왕갈비'; + + // 업종 + businessTypeSelect.value = 'restaurant'; + + // 주소 + addressInput.value = '경기도 수원시 팔달구 인계동 1055-1'; + document.getElementById('addressDetail').value = '1층'; + + // 영업시간 (월~일 10:00-22:00) + const timeInputs = document.querySelectorAll('.business-hour-row'); + timeInputs.forEach(row => { + row.querySelector('input[type="time"]:first-of-type').value = '10:00'; + row.querySelector('input[type="time"]:last-of-type').value = '22:00'; + }); + + // 사업자번호 + businessNumberInput.value = '123-45-67890'; + + // 메뉴 예제 추가 + menuItems = [ + { + id: Utils.generateId(), + name: '왕갈비', + price: 18000, + description: '대표 메뉴, 1인분' + }, + { + id: Utils.generateId(), + name: 'LA갈비', + price: 35000, + description: '미국산 최상급 LA갈비' + }, + { + id: Utils.generateId(), + name: '된장찌개', + price: 7000, + description: '직접 담근 된장 사용' + }, + { + id: Utils.generateId(), + name: '냉면', + price: 9000, + description: '여름 시즌 인기 메뉴' + }, + { + id: Utils.generateId(), + name: '갈비탕', + price: 12000, + description: '푸짐한 갈비가 들어간 보양식' + } + ]; + renderMenuList(); + + // 매장 특징 + storeFeaturesTextarea.value = '30년 전통의 한식 갈비 전문점입니다.\n직접 제작한 비법 양념으로 재운 갈비가 특징이며,\n주차 가능하고 단체석도 마련되어 있습니다.\n런치 시간 특가 메뉴 제공 중입니다.'; + featureCountSpan.textContent = storeFeaturesTextarea.value.length; + + // 사업자번호 검증 시뮬레이션 + isBusinessNumberVerified = true; + verifyBtn.disabled = false; + document.getElementById('verifyResult').innerHTML = ` +
+ check_circle + 확인됨 (예제 데이터) +
+ `; + + // 폼 유효성 체크 + checkFormValidity(); + + // 안내 메시지 + Toast.info('한식음식점 예제 데이터가 로드되었습니다.'); + } + // 초기화 initBusinessHours(); + + // 예제 데이터 자동 로드 + setTimeout(() => { + loadKoreanRestaurantExample(); + }, 500); + console.log('매장정보등록 페이지 로드 완료'); })(); diff --git a/design/uiux/prototype/03-이벤트목적선택.html b/design/uiux/prototype/03-이벤트목적선택.html index c0b44ed..44bf8ea 100644 --- a/design/uiux/prototype/03-이벤트목적선택.html +++ b/design/uiux/prototype/03-이벤트목적선택.html @@ -368,10 +368,10 @@ window.AppState.currentEvent = eventData; window.AppState.save(); - // AI 분석 화면으로 이동 - Loading.show('AI 트렌드 분석 준비 중...'); + // AI 이벤트 유형 추천 화면으로 이동 + Loading.show('AI 이벤트 유형 분석 중...'); setTimeout(() => { - window.location.href = '04-AI트렌드분석결과.html'; + window.location.href = '04-1-AI이벤트유형추천.html'; }, 800); }); diff --git a/design/uiux/prototype/04-1-AI이벤트유형추천.html b/design/uiux/prototype/04-1-AI이벤트유형추천.html new file mode 100644 index 0000000..a332dd9 --- /dev/null +++ b/design/uiux/prototype/04-1-AI이벤트유형추천.html @@ -0,0 +1,550 @@ + + + + + + + AI 이벤트 유형 추천 - KT 이벤트 마케팅 + + + + + + + + + + + + + +
+ +
+ +

AI 이벤트 유형 추천

+ +
+ + +
+
+ +
+
+ auto_awesome +
+

수원왕갈비님을 위한 맞춤 추천

+
+ 한식당 · 봄 시즌 · 예산 30만원 +
+
+ lightbulb + 13가지 이벤트 유형 중 7가지가 추천되었습니다 +
+
+
+
+ + +
+
+ 총 7개 이벤트 +
+ +
+ + +
+ +
+
+
+ + +
+ +
+ 이벤트를 선택해주세요 +
+
+
+ + + + + + + + diff --git a/design/uiux/prototype/04-2-이벤트상세정보.html b/design/uiux/prototype/04-2-이벤트상세정보.html new file mode 100644 index 0000000..4a59600 --- /dev/null +++ b/design/uiux/prototype/04-2-이벤트상세정보.html @@ -0,0 +1,624 @@ + + + + + + + 이벤트 상세 정보 - KT 이벤트 마케팅 + + + + + + + + + + + + + +
+ +
+ +

이벤트 상세 정보

+
+ + +
+
+ + +
+
+
+ tag +
+
+

SNS 해시태그 이벤트

+
+ 인스타그램 해시태그 참여로 바이럴 효과 극대화 +
+
+
+
A
+
매우높음
+
+
+ + +
+
+
예상 예산
+
5만원
+
+
+
예상 순수익
+
+85만원
+
+
+
ROI
+
1700%
+
+
+
+ + +
+ + + + +
+ + +
+ + +
+

+ trending_up + 기대 효과 +

+
+
+ check_circle +
+
SNS 노출 +400~600%
+
해시태그를 통한 유기적 확산으로 브랜드 노출 극대화
+
+
+
+ group_add +
+
신규 고객 +60~80%
+
SNS를 통한 새로운 고객 유입 및 방문 증가
+
+
+
+ campaign +
+
브랜드 인지도 +120%
+
바이럴 효과로 지역 내 인지도 상승
+
+
+
+
+ + +
+

+ store + 적합한 매장 +

+
+
+ check + 비주얼이 좋은 메뉴를 보유한 매장 +
+
+ check + 20~40대 젊은 층을 타겟으로 하는 매장 +
+
+ check + 카페, 일식당, 양식당 (인스타 특화) +
+
+ check + 매장 내 포토존 또는 감성적인 공간 보유 +
+
+
+ + +
+

+ calendar_today + 추천 계절/시기 +

+
+
+
🌸 봄
+
벚꽃 시즌 특히 효과적
+
추천도 ⭐⭐⭐⭐⭐
+
+
+
❄️ 겨울
+
크리스마스 시즌 효과
+
추천도 ⭐⭐⭐⭐⭐
+
+
+
🧊 여름
+
시원한 메뉴와 연계
+
추천도 ⭐⭐⭐⭐
+
+
+
🍁 가을
+
단풍 콘셉트 활용
+
추천도 ⭐⭐⭐⭐
+
+
+
+ +
+ + + + + + + + + + +
+
+ + +
+ +
+
+ + + + + + + + diff --git a/design/uiux/prototype/05-AI경품추천.html b/design/uiux/prototype/05-AI경품추천.html index beef800..7dd0459 100644 --- a/design/uiux/prototype/05-AI경품추천.html +++ b/design/uiux/prototype/05-AI경품추천.html @@ -46,6 +46,23 @@ + + +

예산 설정

@@ -146,6 +163,31 @@ window.AppState.load(); const store = window.AppState.store; const event = window.AppState.currentEvent; + const selectedEventType = window.AppState.selectedEventType; + + // 선택된 이벤트 유형 정보 표시 + if (selectedEventType) { + document.getElementById('selectedEventContext').style.display = 'block'; + document.getElementById('eventTypeName').textContent = selectedEventType.name; + document.getElementById('eventTypeDesc').textContent = selectedEventType.description; + + const categoryMap = { + 'digital': '디지털', + 'offline': '오프라인', + 'prize': '경품형' + }; + document.getElementById('eventCategory').textContent = categoryMap[selectedEventType.category] || selectedEventType.category; + + const budgetMin = Math.floor(selectedEventType.budget.min / 10000); + const budgetMax = Math.floor(selectedEventType.budget.max / 10000); + document.getElementById('eventBudget').textContent = `예산: ${budgetMin}~${budgetMax}만원`; + + // 이벤트 유형 예산 범위로 슬라이더 초기값 설정 + const avgBudget = (selectedEventType.budget.min + selectedEventType.budget.max) / 2; + currentBudget = Math.round(avgBudget / 10000) * 10000; + budgetSlider.value = currentBudget; + budgetDisplay.textContent = Utils.formatNumber(currentBudget) + '원'; + } // 예산 슬라이더 변경 budgetSlider.addEventListener('input', function() { @@ -167,13 +209,39 @@ function generatePrizeRecommendations() { const businessType = store.businessType; const purpose = event.purpose; + const eventCategory = selectedEventType ? selectedEventType.category : null; - // 업종/목적별 경품 데이터 - const prizesDatabase = { + // 이벤트 유형별 경품 데이터 (디지털/오프라인/경품형) + const eventTypePrizes = { + digital: [ + { name: '모바일 기프티콘', basePrice: 5000, attraction: 5, participationRate: 48, category: 'voucher', digital: true }, + { name: 'SNS 공유 쿠폰', basePrice: 3000, attraction: 4, participationRate: 52, category: 'discount', digital: true }, + { name: '온라인 포인트 적립', basePrice: 2000, attraction: 3, participationRate: 45, category: 'point', digital: true }, + { name: '디지털 할인쿠폰', basePrice: 5000, attraction: 4, participationRate: 50, category: 'discount', digital: true }, + { name: '모바일 상품권', basePrice: 10000, attraction: 5, participationRate: 46, category: 'voucher', digital: true } + ], + offline: [ + { name: '매장 방문 쿠폰', basePrice: 8000, attraction: 5, participationRate: 42, category: 'discount', digital: false }, + { name: '현장 사은품', basePrice: 5000, attraction: 4, participationRate: 38, category: 'product', digital: false }, + { name: '체험 상품권', basePrice: 15000, attraction: 5, participationRate: 35, category: 'service', digital: false }, + { name: '무료 시음/시식권', basePrice: 3000, attraction: 3, participationRate: 40, category: 'product', digital: false }, + { name: 'VIP 라운지 이용권', basePrice: 20000, attraction: 4, participationRate: 28, category: 'service', digital: false } + ], + prize: [ + { name: '추첨 경품권', basePrice: 50000, attraction: 5, participationRate: 55, category: 'raffle', digital: false }, + { name: '럭키드로우 티켓', basePrice: 0, attraction: 4, participationRate: 50, category: 'raffle', digital: true }, + { name: '즉석 당첨 쿠폰', basePrice: 10000, attraction: 5, participationRate: 48, category: 'instant', digital: false }, + { name: '응모권 (자동추첨)', basePrice: 0, attraction: 3, participationRate: 45, category: 'raffle', digital: true }, + { name: '럭키박스 교환권', basePrice: 30000, attraction: 4, participationRate: 40, category: 'product', digital: false } + ] + }; + + // 업종별 경품 데이터 + const businessPrizes = { restaurant: [ - { name: '치킨세트 무료교환', basePrice: 20000, attraction: 5, participationRate: 45, category: 'product' }, + { name: '메인메뉴 무료교환', basePrice: 20000, attraction: 5, participationRate: 45, category: 'product' }, { name: '5천원 할인쿠폰', basePrice: 5000, attraction: 4, participationRate: 38, category: 'discount' }, - { name: '사이드메뉴 무료 제공', basePrice: 8000, attraction: 4, participationRate: 40, category: 'product' }, + { name: '사이드메뉴 무료', basePrice: 8000, attraction: 4, participationRate: 40, category: 'product' }, { name: '음료 무료 업그레이드', basePrice: 3000, attraction: 3, participationRate: 35, category: 'upgrade' }, { name: '10% 할인 쿠폰', basePrice: 10000, attraction: 4, participationRate: 36, category: 'discount' } ], @@ -193,16 +261,36 @@ ] }; - // 기본 경품 (업종이 매칭되지 않을 경우) + // 기본 경품 const defaultPrizes = [ - { name: 'KT 멤버십 포인트 5천점', basePrice: 5000, attraction: 3, participationRate: 32, category: 'point' }, - { name: '5천원 모바일 상품권', basePrice: 5000, attraction: 4, participationRate: 38, category: 'voucher' }, - { name: '3천원 할인쿠폰', basePrice: 3000, attraction: 4, participationRate: 36, category: 'discount' }, + { name: 'KT 멤버십 포인트', basePrice: 5000, attraction: 3, participationRate: 32, category: 'point' }, + { name: '모바일 상품권', basePrice: 5000, attraction: 4, participationRate: 38, category: 'voucher' }, + { name: '할인쿠폰', basePrice: 3000, attraction: 4, participationRate: 36, category: 'discount' }, { name: '경품 추첨권', basePrice: 0, attraction: 2, participationRate: 25, category: 'raffle' }, - { name: '다음 방문 시 10% 할인', basePrice: 0, attraction: 3, participationRate: 30, category: 'discount' } + { name: '재방문 할인권', basePrice: 0, attraction: 3, participationRate: 30, category: 'discount' } ]; - let prizes = prizesDatabase[businessType] || defaultPrizes; + // 이벤트 유형과 업종을 조합하여 최적의 경품 선택 + let prizes = []; + + if (eventCategory && eventTypePrizes[eventCategory]) { + // 이벤트 유형별 경품 우선 + prizes = [...eventTypePrizes[eventCategory]]; + + // 디지털 이벤트인 경우 업종별 경품 중 디지털 가능한 것 추가 + if (eventCategory === 'digital' && businessPrizes[businessType]) { + const digitalCompatible = businessPrizes[businessType] + .filter(p => p.category === 'discount' || p.category === 'voucher' || p.category === 'point') + .slice(0, 2); + prizes = [...prizes, ...digitalCompatible]; + } + } else { + // 이벤트 유형이 없으면 업종별 경품 사용 + prizes = businessPrizes[businessType] || defaultPrizes; + } + + // 중복 제거 및 최대 8개로 제한 + prizes = prizes.slice(0, 8); // 예산에 맞춰 가격 조정 및 추천 const budgetPerPrize = currentBudget * 0.2; // 경품 1개당 예산의 20% @@ -234,8 +322,15 @@
-
- ${prize.rank}. ${prize.name} +
+ + ${prize.rank}. ${prize.name} + + ${prize.digital !== undefined ? ` + + ${prize.digital ? '디지털' : '오프라인'} + + ` : ''}
${Utils.formatNumber(prize.price)}원 × ${prize.quantity}개 diff --git a/design/userstory-table.md b/design/userstory-table.md new file mode 100644 index 0000000..28da65d --- /dev/null +++ b/design/userstory-table.md @@ -0,0 +1,337 @@ +# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 유저스토리 목록 + +## 전체 유저스토리 요약 + +| 서비스 | ID | 유저스토리 | 우선순위 | 복잡도 | +|--------|-----|-----------|----------|--------| +| **User** | UFR-USER-010 | [회원가입] 소상공인으로서 간편하게 회원가입하고 싶다 | M | 8 | +| | UFR-USER-020 | [매장정보등록] 맞춤형 이벤트를 위해 매장 정보를 등록하고 싶다 | M | 13 | +| **Event Planning** | UFR-PLAN-010 | [이벤트목적선택] 효과적인 이벤트를 위해 목적을 선택하고 싶다 | M | 3 | +| | UFR-PLAN-020 | [AI업종트렌드분석] 성공률 높은 이벤트를 위해 AI 트렌드 분석을 원한다 | M | 13 | +| | UFR-PLAN-030 | [AI경품추천] 예산 내 최적 경품을 AI가 추천해주기를 원한다 | M | 21 | +| | UFR-PLAN-040 | [AI참여방법설계] 재방문 유도하는 참여 방법을 AI가 설계해주기를 원한다 | M | 21 | +| | UFR-PLAN-050 | [AI홍보문구생성] 매력적인 홍보 문구를 AI가 자동 생성해주기를 원한다 | M | 13 | +| | UFR-PLAN-060 | [이벤트기획안승인] 완성된 기획안을 검토하고 승인하고 싶다 | M | 5 | +| **Content Generation** | UFR-CONT-010 | [AI이미지생성] 브랜드 컬러와 로고를 반영한 이미지를 AI가 생성해주기를 원한다 | M | 34 | +| | UFR-CONT-020 | [AI영상제작] SNS 및 우리동네TV용 15초 영상을 AI가 제작해주기를 원한다 | M | 34 | +| | UFR-CONT-030 | [SNS콘텐츠생성] 플랫폼별 최적화된 콘텐츠를 자동 생성해주기를 원한다 | M | 21 | +| | UFR-CONT-040 | [QR포스터생성] 오프라인 홍보용 QR 포스터를 생성하고 싶다 | M | 8 | +| | UFR-CONT-050 | [콘텐츠편집] 생성된 콘텐츠를 개인화하기 위해 수정하고 싶다 | S | 13 | +| | UFR-CONT-060 | [콘텐츠최종승인] 완성된 콘텐츠를 검토하고 승인하고 싶다 | M | 3 | +| **Distribution** | UFR-DIST-010 | [다중채널배포설정] 여러 채널에 한 번에 배포하고 싶다 | M | 13 | +| | UFR-DIST-020 | [우리동네TV배포] 주변 지역 고객에게 우리동네TV로 도달하고 싶다 | M | 21 | +| | UFR-DIST-030 | [링고비즈연결음업데이트] 매장 전화 연결음을 이벤트 내용으로 업데이트하고 싶다 | S | 13 | +| | UFR-DIST-040 | [지니TV광고배포] 가정의 TV를 통해 지니TV 광고를 배포하고 싶다 | M | 21 | +| | UFR-DIST-050 | [SNS자동포스팅] Instagram, Naver Blog, Kakao에 자동 포스팅하고 싶다 | M | 13 | +| | UFR-DIST-060 | [오프라인자료다운로드] QR 포스터와 인쇄용 PDF를 다운로드하고 싶다 | S | 5 | +| **Participation** | UFR-PART-010 | [이벤트참여신청] 고객이 간편하게 이벤트에 참여하고 싶다 | M | 8 | +| | UFR-PART-020 | [중복참여방지] 공정한 이벤트 운영을 위해 1인 1회만 참여 허용하고 싶다 | M | 8 | +| | UFR-PART-030 | [자동당첨자추첨] 이벤트 종료 시 자동으로 당첨자가 추첨되기를 원한다 | M | 13 | +| | UFR-PART-040 | [당첨알림발송] 고객이 SMS나 카카오 알림톡으로 당첨 알림을 받고 싶다 | M | 8 | +| | UFR-PART-050 | [당첨자명단관리] 당첨자 명단을 확인하고 관리하고 싶다 | M | 5 | +| **Analytics** | UFR-ANAL-010 | [실시간대시보드조회] 실시간으로 참여자 수, 노출 수, 매출 증가율을 확인하고 싶다 | M | 21 | +| | UFR-ANAL-020 | [채널별성과분석] 채널별 노출 수와 참여율을 비교하고 싶다 | M | 13 | +| | UFR-ANAL-030 | [ROI자동계산] 총비용 대비 수익(ROI)이 자동으로 계산되기를 원한다 | M | 13 | +| | UFR-ANAL-040 | [분석리포트생성] 종합 분석 리포트를 PDF로 다운로드하고 싶다 | S | 8 | +| **AI Learning** | UFR-AIMPR-010 | [AI개선안생성] AI가 분석 결과를 바탕으로 구체적인 개선안을 제안해주기를 원한다 | M | 21 | +| | UFR-AIMPR-020 | [다음이벤트아이디어제안] AI가 시즌별 성공 이벤트 아이디어를 제안해주기를 원한다 | S | 13 | +| | UFR-AIMPR-030 | [성공패턴학습] AI 시스템이 이벤트 결과를 학습하여 성공 패턴을 축적하고 싶다 | M | 34 | +| **비기능 요구사항** | NFR-PERF-010 | [AI기획속도] AI 이벤트 기획을 10초 이내에 완료하고 싶다 | M | 21 | +| | NFR-PERF-020 | [콘텐츠생성속도] 이미지와 영상 생성을 5-8분 내에 완료하고 싶다 | M | 34 | +| | NFR-PERF-030 | [배포속도] 다중 채널 배포를 1분 이내에 완료하고 싶다 | M | 21 | +| | NFR-PERF-040 | [실시간데이터수집] 5분 간격으로 실시간 데이터를 수집하고 싶다 | M | 13 | +| | NFR-SECU-010 | [개인정보보호] 개인정보 보호 규정을 준수하고 암호화를 적용하고 싶다 | M | 13 | +| | NFR-RELI-010 | [배포실패자동재시도] 배포 실패 시 자동으로 3회까지 재시도하고 싶다 | M | 8 | +| | NFR-SCAL-010 | [동시이벤트처리] 최소 100개의 이벤트를 동시에 처리할 수 있어야 한다 | S | 21 | + +--- + +## 우선순위별 통계 + +| 우선순위 | 개수 | 비율 | +|---------|------|------| +| M (필수) | 33 | 80.5% | +| S (선택) | 8 | 19.5% | +| **총계** | **41** | **100%** | + +--- + +## 서비스별 통계 + +| 서비스 | 유저스토리 수 | 평균 복잡도 | 필수(M) | 선택(S) | +|--------|-------------|-----------|---------|---------| +| User | 2 | 10.5 | 2 | 0 | +| Event Planning | 6 | 12.7 | 6 | 0 | +| Content Generation | 6 | 18.8 | 5 | 1 | +| Distribution | 6 | 14.3 | 4 | 2 | +| Participation | 5 | 8.4 | 5 | 0 | +| Analytics | 4 | 13.8 | 3 | 1 | +| AI Learning | 3 | 22.7 | 2 | 1 | +| 비기능 요구사항 | 7 | 18.7 | 6 | 1 | +| **총계** | **39** | **14.8** | **33** | **6** | + +--- + +## 복잡도별 통계 + +| 복잡도 범위 | 개수 | 유저스토리 | +|-----------|------|-----------| +| 1-5 (낮음) | 5 | UFR-PLAN-010, UFR-PLAN-060, UFR-CONT-060, UFR-DIST-060, UFR-PART-050 | +| 6-13 (중간) | 23 | UFR-USER-010, UFR-USER-020, UFR-PLAN-020, UFR-PLAN-050, UFR-CONT-030, UFR-CONT-040, UFR-CONT-050, UFR-DIST-010, UFR-DIST-030, UFR-DIST-050, UFR-PART-010, UFR-PART-020, UFR-PART-040, UFR-ANAL-020, UFR-ANAL-030, UFR-AIMPR-020, NFR-PERF-040, NFR-SECU-010, NFR-RELI-010 | +| 14-21 (높음) | 10 | UFR-PLAN-030, UFR-PLAN-040, UFR-DIST-020, UFR-DIST-040, UFR-ANAL-010, UFR-AIMPR-010, NFR-PERF-010, NFR-PERF-030, NFR-SCAL-010 | +| 22+ (매우 높음) | 3 | UFR-CONT-010, UFR-CONT-020, UFR-AIMPR-030, NFR-PERF-020 | + +--- + +## 주요 기능별 상세 목록 + +### 1. User 서비스 (회원 인증 및 매장 정보 관리) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | +|----|------|----------|--------|-------------| +| UFR-USER-010 | 회원가입 | M | 8 | 이름, 전화번호, 이메일, KT 본인 인증(선택), 중복 가입 방지 | +| UFR-USER-020 | 매장정보등록 | M | 13 | 매장명, 업종, 주소, 영업시간, 사업자번호 검증, 무료 체험 쿠폰 발급 | + +**검증 로직:** +- 사업자번호 형식 검증 (XXX-XX-XXXXX) +- 국세청 사업자번호 검증 시스템 API 연동 +- 사업자번호 유효성 확인 및 휴폐업 여부 확인 + +--- + +### 2. Event Planning 서비스 (AI 기반 이벤트 자동 기획) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | AI 모델 | +|----|------|----------|--------|-------------|---------| +| UFR-PLAN-010 | 이벤트목적선택 | M | 3 | 신규고객 유치/재방문 유도/매출 증대/인지도 향상 선택 | - | +| UFR-PLAN-020 | AI업종트렌드분석 | M | 13 | 업종, 지역, 시즌 기반 트렌드 분석, 성공 사례 분석 | Claude API | +| UFR-PLAN-030 | AI경품추천 | M | 21 | 예산, 타겟 고객층 기반 경품 Top 5 추천, 수정 가능 | Claude API | +| UFR-PLAN-040 | AI참여방법설계 | M | 21 | 간단한 참여 방법 + 재방문 유도 + 바이럴 확산 3가지 옵션 | Claude API | +| UFR-PLAN-050 | AI홍보문구생성 | M | 13 | 5개 버전 홍보 문구 + SNS 해시태그 + 플랫폼별 최적화 | GPT-4 API | +| UFR-PLAN-060 | 이벤트기획안승인 | M | 5 | 기획안 요약 제공, 승인 처리, 수정 기능 | - | + +**성능 목표:** 전체 기획 과정 10초 이내 완료 + +--- + +### 3. Content Generation 서비스 (AI 기반 콘텐츠 자동 생성) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | AI 모델 | +|----|------|----------|--------|-------------|---------| +| UFR-CONT-010 | AI이미지생성 | M | 34 | 브랜드 컬러, 로고 반영, 3가지 스타일 (심플/화려/트렌디), 1080x1080 | Stable Diffusion | +| UFR-CONT-020 | AI영상제작 | M | 34 | 15초 영상, 배경 음악, 텍스트 오버레이, 우리동네TV용 1920x1080 | AI 영상 제작 엔진 | +| UFR-CONT-030 | SNS콘텐츠생성 | M | 21 | Instagram (1080x1080), Naver Blog (800x600), Kakao (800x800) | - | +| UFR-CONT-040 | QR포스터생성 | M | 8 | QR 코드 포함, A4/A3 PDF, 인쇄 최적화 (300dpi) | - | +| UFR-CONT-050 | 콘텐츠편집 | S | 13 | 텍스트 수정, 색상 조정, 레이아웃 변경, 편집 이력 관리 (최대 3개 버전) | - | +| UFR-CONT-060 | 콘텐츠최종승인 | M | 3 | 전체 콘텐츠 미리보기, 승인 처리 | - | + +**성능 목표:** 전체 콘텐츠 생성 5-8분 이내 완료 + +--- + +### 4. Distribution 서비스 (다중 채널 자동 배포) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | 연동 API | +|----|------|----------|--------|-------------|---------| +| UFR-DIST-010 | 다중채널배포설정 | M | 13 | 채널 선택 (우리동네TV, 링고비즈, 지니TV, SNS), 즉시/예약 배포 | - | +| UFR-DIST-020 | 우리동네TV배포 | M | 21 | 반경 (500m/1km), 송출 시간대, 15초 영상 업로드 | 우리동네TV API | +| UFR-DIST-030 | 링고비즈연결음업데이트 | S | 13 | 네이버 클로바 TTS 음성 생성, 연결음 업데이트, 미리듣기 | 링고비즈 API, Clova TTS | +| UFR-DIST-040 | 지니TV광고배포 | M | 21 | 타겟 지역 (1km/3km/5km), 노출 시간대, 예산 기반 노출량 | 지니TV API | +| UFR-DIST-050 | SNS자동포스팅 | M | 13 | Instagram, Naver Blog, Kakao OAuth 연동, 예약 포스팅 | SNS API (Instagram, Naver, Kakao) | +| UFR-DIST-060 | 오프라인자료다운로드 | S | 5 | QR 포스터 (A4/A3 PDF), QR 코드 이미지, 인쇄용 이미지 | - | + +**성능 목표:** 전체 배포 과정 1분 이내 완료 + +--- + +### 5. Participation 서비스 (이벤트 참여 및 접수 관리) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | +|----|------|----------|--------|-------------| +| UFR-PART-010 | 이벤트참여신청 | M | 8 | 고객명, 전화번호, 참여 경로 추적, 응모번호 발급 | +| UFR-PART-020 | 중복참여방지 | M | 8 | 전화번호 기반 중복 체크, 매장 방문 고객 가산점 | +| UFR-PART-030 | 자동당첨자추첨 | M | 13 | 이벤트 종료 시 자동 추첨, 난수 기반 무작위 알고리즘, 매장 방문 가산점 | +| UFR-PART-040 | 당첨알림발송 | M | 8 | SMS/카카오 알림톡 발송, 경품 수령 방법 안내, 실패 시 재발송 (최대 3회) | +| UFR-PART-050 | 당첨자명단관리 | M | 5 | 당첨자 목록, 경품 지급 상태 관리, 엑셀 다운로드 | + +**정책:** +- 1인 1회 참여 제한 +- 개인정보 보호 규정 준수 +- 매장 방문 고객 가산점 부여 + +--- + +### 6. Analytics 서비스 (실시간 효과 측정 및 분석) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | 데이터 소스 | +|----|------|----------|--------|-------------|------------| +| UFR-ANAL-010 | 실시간대시보드조회 | M | 21 | 참여자 수, 채널별 노출 수, 매출 증가율, ROI (5분 간격 업데이트) | KT 채널 API, POS, GA | +| UFR-ANAL-020 | 채널별성과분석 | M | 13 | 노출 수, 참여율, 전환율, 비용 대비 효과 (CPA) 비교 | 각 채널 API | +| UFR-ANAL-030 | ROI자동계산 | M | 13 | 총 투자 비용 vs 수익, 손익분기점, 회수 기간 | - | +| UFR-ANAL-040 | 분석리포트생성 | S | 8 | 종합 리포트 PDF 생성, 업종 평균 대비 벤치마킹 | 구글 애널리틱스 | + +**데이터 수집:** +- 실시간 데이터 수집 (5분 간격) +- 구글 애널리틱스 연동 +- POS 시스템 연동 + +--- + +### 7. AI Learning 서비스 (AI 학습 및 개선 제안) + +| ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | AI 모델 | +|----|------|----------|--------|-------------|---------| +| UFR-AIMPR-010 | AI개선안생성 | M | 21 | 성공/실패 요인 분석, 3가지 개선안 제시 (경품 변경, 참여 방법 단순화, 채널 조정) | AI 머신러닝 엔진 | +| UFR-AIMPR-020 | 다음이벤트아이디어제안 | S | 13 | 시즌별 성공 이벤트 아이디어 5가지, 예상 성과 제공 | 트렌드 DB | +| UFR-AIMPR-030 | 성공패턴학습 | M | 34 | 이벤트 결과 데이터 학습, 성공 패턴 축적, 추천 정확도 개선 | 빅데이터 분석 시스템 | + +**학습 전략:** +- 성공 패턴 자동 학습 및 재활용 +- 실패 요인 회피 로직 적용 +- 업종별/지역별 데이터 축적 +- 지속적 성능 개선 알고리즘 + +--- + +### 8. 비기능 요구사항 (성능, 보안, 안정성, 확장성) + +| 카테고리 | ID | 기능 | 우선순위 | 복잡도 | 핵심 요구사항 | +|---------|-----|------|----------|--------|-------------| +| 성능 | NFR-PERF-010 | AI기획속도 | M | 21 | AI 이벤트 기획 10초 이내 (병렬 호출, 캐싱) | +| | NFR-PERF-020 | 콘텐츠생성속도 | M | 34 | 이미지 2-3분, 영상 3-5분, 총 5-8분 이내 (병렬 처리, GPU 가속) | +| | NFR-PERF-030 | 배포속도 | M | 21 | 다중 채널 배포 1분 이내 (채널별 병렬 배포) | +| | NFR-PERF-040 | 실시간데이터수집 | M | 13 | 5분 간격 자동 데이터 수집 (스케줄러, 재시도 3회) | +| 보안 | NFR-SECU-010 | 개인정보보호 | M | 13 | 전화번호 AES-256 암호화, GDPR/개인정보보호법 준수, RBAC | +| 안정성 | NFR-RELI-010 | 배포실패자동재시도 | M | 8 | 배포 실패 시 자동 재시도 (최대 3회, 지수 백오프) | +| 확장성 | NFR-SCAL-010 | 동시이벤트처리 | S | 21 | 100개 이벤트 동시 처리 (Auto Scaling, 로드 밸런싱, 메시지 큐) | + +--- + +## 기술 스택 요약 + +### AI/ML 모델 +| 모델 | 용도 | 관련 유저스토리 | +|------|------|----------------| +| Claude API | 트렌드 분석, 경품 추천, 참여 방법 설계 | UFR-PLAN-020, UFR-PLAN-030, UFR-PLAN-040 | +| GPT-4 API | 홍보 문구 생성 | UFR-PLAN-050 | +| Stable Diffusion | 이미지 생성 | UFR-CONT-010 | +| AI 영상 제작 엔진 | 15초 영상 제작 | UFR-CONT-020 | +| 네이버 클로바 TTS | 연결음 음성 합성 | UFR-DIST-030 | +| AI 머신러닝 엔진 | 개선안 생성, 성공 패턴 학습 | UFR-AIMPR-010, UFR-AIMPR-030 | + +### 외부 API 연동 +| API | 용도 | 관련 유저스토리 | +|-----|------|----------------| +| 국세청 사업자번호 검증 | 사업자번호 유효성 확인 | UFR-USER-020 | +| 우리동네TV API | 지역 타겟팅 영상 송출 | UFR-DIST-020 | +| 링고비즈 API | 연결음 업데이트 | UFR-DIST-030 | +| 지니TV API | TV 광고 배포 | UFR-DIST-040 | +| Instagram API | SNS 자동 포스팅 | UFR-DIST-050 | +| Naver Blog API | 블로그 자동 포스팅 | UFR-DIST-050 | +| Kakao Channel API | 카카오 채널 자동 포스팅 | UFR-DIST-050 | +| SMS/카카오 알림톡 | 당첨 알림 발송 | UFR-PART-040 | +| POS 시스템 | 매출 데이터 수집 | UFR-ANAL-010 | +| 구글 애널리틱스 | 웹/앱 유입 데이터 수집 | UFR-ANAL-010, UFR-ANAL-040 | + +--- + +## 마이크로서비스 아키텍처 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ API Gateway │ +└─────────────────────────────────────────────────────────────┘ + │ + ┌─────────────────────┼─────────────────────┐ + │ │ │ +┌───────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐ +│ User Service │ │ Event Planning │ │ Content │ +│ (UFR-USER) │ │ (UFR-PLAN) │ │ Generation │ +│ │ │ │ │ (UFR-CONT) │ +└────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + │ │ │ +┌───────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐ +│ Distribution │ │ Participation │ │ Analytics │ +│ (UFR-DIST) │ │ (UFR-PART) │ │ (UFR-ANAL) │ +└────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └─────────────────────┼─────────────────────┘ + │ + ┌─────────▼─────────┐ + │ AI Learning │ + │ (UFR-AIMPR) │ + └───────────────────┘ +``` + +--- + +## 개발 우선순위 로드맵 + +### Phase 1: MVP (8주) +**목표:** 기본 이벤트 기획 및 배포 기능 + +| 순서 | 서비스 | 유저스토리 | 비고 | +|------|--------|-----------|------| +| 1 | User | UFR-USER-010, UFR-USER-020 | 회원가입, 매장 정보 등록 | +| 2 | Event Planning | UFR-PLAN-010, UFR-PLAN-030, UFR-PLAN-060 | 목적 선택, 경품 추천, 승인 | +| 3 | Content Generation | UFR-CONT-010, UFR-CONT-040, UFR-CONT-060 | 이미지 생성, QR 포스터, 승인 | +| 4 | Distribution | UFR-DIST-010, UFR-DIST-050 | 다중 채널 설정, SNS 포스팅 | +| 5 | Participation | UFR-PART-010, UFR-PART-020, UFR-PART-030 | 참여 신청, 중복 방지, 자동 추첨 | + +### Phase 2: 고도화 (6주) +**목표:** AI 기능 강화 및 분석 기능 추가 + +| 순서 | 서비스 | 유저스토리 | 비고 | +|------|--------|-----------|------| +| 6 | Event Planning | UFR-PLAN-020, UFR-PLAN-040, UFR-PLAN-050 | 트렌드 분석, 참여 방법, 홍보 문구 | +| 7 | Content Generation | UFR-CONT-020, UFR-CONT-030 | 영상 제작, SNS 콘텐츠 | +| 8 | Distribution | UFR-DIST-020, UFR-DIST-040 | 우리동네TV, 지니TV | +| 9 | Participation | UFR-PART-040, UFR-PART-050 | 당첨 알림, 명단 관리 | +| 10 | Analytics | UFR-ANAL-010, UFR-ANAL-020, UFR-ANAL-030 | 실시간 대시보드, 채널별 분석, ROI | + +### Phase 3: 완성 (4주) +**목표:** AI 학습 및 선택 기능 추가 + +| 순서 | 서비스 | 유저스토리 | 비고 | +|------|--------|-----------|------| +| 11 | Distribution | UFR-DIST-030, UFR-DIST-060 | 링고비즈 연결음, 오프라인 자료 | +| 12 | Content Generation | UFR-CONT-050 | 콘텐츠 편집 | +| 13 | Analytics | UFR-ANAL-040 | 분석 리포트 | +| 14 | AI Learning | UFR-AIMPR-010, UFR-AIMPR-030 | 개선안 생성, 성공 패턴 학습 | +| 15 | AI Learning | UFR-AIMPR-020 | 다음 이벤트 아이디어 | + +--- + +## 성능 요구사항 요약 + +| 단계 | 목표 시간 | 관련 유저스토리 | +|------|----------|----------------| +| AI 이벤트 기획 | 10초 이내 | UFR-PLAN-020~050, NFR-PERF-010 | +| 콘텐츠 생성 | 5-8분 이내 | UFR-CONT-010~030, NFR-PERF-020 | +| 다중 채널 배포 | 1분 이내 | UFR-DIST-010~050, NFR-PERF-030 | +| 실시간 데이터 수집 | 5분 간격 | UFR-ANAL-010, NFR-PERF-040 | + +--- + +## 보안 요구사항 요약 + +| 항목 | 요구사항 | 관련 유저스토리 | +|------|----------|----------------| +| 개인정보 암호화 | AES-256 (전화번호, 이름) | NFR-SECU-010 | +| 전송 보안 | HTTPS/TLS | NFR-SECU-010 | +| 접근 제어 | RBAC (역할 기반) | NFR-SECU-010 | +| 개인정보 보호 | GDPR, 개인정보보호법 준수 | NFR-SECU-010 | +| 보유 기간 | 이벤트 종료 후 3개월 | NFR-SECU-010 | + +--- + +## 안정성 및 확장성 요구사항 + +| 항목 | 요구사항 | 관련 유저스토리 | +|------|----------|----------------| +| 자동 재시도 | 배포 실패 시 최대 3회 (지수 백오프) | NFR-RELI-010 | +| 동시 처리 | 최소 100개 이벤트 동시 처리 | NFR-SCAL-010 | +| Auto Scaling | 마이크로서비스 수평 확장 | NFR-SCAL-010 | +| 로드 밸런싱 | 트래픽 분산 | NFR-SCAL-010 | +| 메시지 큐 | 비동기 처리 (RabbitMQ/Kafka) | NFR-SCAL-010 | diff --git a/design/구현방안-AI경품추천.md b/design/구현방안-AI경품추천.md new file mode 100644 index 0000000..ff69500 --- /dev/null +++ b/design/구현방안-AI경품추천.md @@ -0,0 +1,1056 @@ +# AI 경품 추천 구현 방안 + +## 1. 개요 + +### 1.1 목적 +매장의 업종, 지역, 시즌 등 컨텍스트를 분석하여 최적의 경품을 추천하고, 추천 이유를 명확히 설명하는 AI 기반 추천 시스템 구현 + +### 1.2 핵심 전략 +**RAG(Retrieval-Augmented Generation) 기반 하이브리드 추천** +- 벡터 DB에서 유사 성공 사례 검색 → Claude API로 컨텍스트 기반 재해석 및 창의적 변형 +- Redis Vector Search + Claude API 3.5 Sonnet 활용 +- Prompt Caching으로 비용 절감 및 응답 속도 개선 + +--- + +## 2. 데이터 수집 및 처리 + +### 2.1 매장 데이터 수집 + +#### 2.1.1 입력 데이터 구조 +```json +{ + "store_id": "string", + "business_number": "string", // 사업자등록번호 + "category": { + "main": "string", // 대분류: 음식점, 소매업, 서비스업 + "sub": "string", // 중분류: 한식, 양식, 카페 + "detail": "string" // 소분류: 고깃집, 베이커리 + }, + "location": { + "sido": "string", // 서울특별시 + "sigungu": "string", // 강남구 + "dong": "string", // 역삼동 + "latitude": "float", + "longitude": "float" + }, + "budget": { + "min": "integer", + "max": "integer" + }, + "target_customer": { + "age_group": ["string"], // ["20대", "30대"] + "gender": "string", // "전체", "남성", "여성" + "income_level": "string" // "중상", "중", "중하" + }, + "event_purpose": "string", // "신규 고객 유치", "단골 유지", "재방문 유도" + "season": "string" // "2025-Q1", auto-calculated +} +``` + +#### 2.1.2 데이터 자동 수집 프로세스 +```mermaid +graph LR + A[사업자등록번호 입력] --> B[공공데이터 API 조회] + B --> C[업종/주소 자동 매핑] + C --> D[좌표 변환 Kakao Map API] + D --> E[상권 분석 데이터 결합] + E --> F[매장 프로필 생성] +``` + +**외부 API 연동** +1. **공공데이터포털 - 상권정보 조회** + - 엔드포인트: `https://api.odcloud.kr/api/StoreInfo/v1/getStoreInfo` + - 수집 항목: 업종, 주소, 개업일 + +2. **Kakao Local API - 좌표 변환** + - 엔드포인트: `https://dapi.kakao.com/v2/local/search/address.json` + - 수집 항목: 위경도, 행정구역 코드 + +3. **서울 열린데이터광장 - 상권 분석** + - 엔드포인트: `https://data.seoul.go.kr/dataList/OA-15572/S/1/datasetView.do` + - 수집 항목: 유동인구, 매출 추정, 경쟁 업체 수 + +### 2.2 경품 데이터 수집 + +#### 2.2.1 데이터 소스 + +**1) 내부 데이터 (과거 이벤트 성과)** +```json +{ + "event_id": "string", + "store_profile": { /* 2.1.1 구조 동일 */ }, + "prize": { + "name": "string", + "category": "string", // "식음료", "생활용품", "체험권", "할인쿠폰" + "unit_price": "integer", + "quantity": "integer", + "supplier": "string" + }, + "performance": { + "participant_count": "integer", + "conversion_rate": "float", // 참여자 중 구매 전환율 + "roi": "float", // 매출 증대액 / 경품 비용 + "customer_satisfaction": "float" // 1~5점 + } +} +``` + +**2) 외부 트렌드 데이터** +- **네이버 쇼핑 트렌드**: 주간/월간 인기 상품 키워드 + - API: `https://developers.naver.com/docs/serviceapi/datalab/shopping/shopping.md` +- **SNS 트렌드 (Instagram, TikTok)**: 해시태그 순위 + - 크롤링 또는 서드파티 API (예: Apify) +- **시즌 이벤트 캘린더**: 공휴일, 기념일, 페스티벌 + - 수동 관리 또는 공공 캘린더 API + +#### 2.2.2 경품 카탈로그 구축 +```json +{ + "prize_id": "string", + "name": "string", + "category": "string", + "subcategory": "string", + "price_range": { + "min": "integer", + "max": "integer" + }, + "target_demographic": { + "age": ["string"], + "gender": "string" + }, + "seasonality": ["string"], // ["봄", "여름", "크리스마스"] + "trend_score": "float", // 최근 1개월 트렌드 점수 (0~1) + "compatibility": { + "food": 0.9, + "retail": 0.7, + "service": 0.5 + } +} +``` + +--- + +## 3. 데이터 정제 및 벡터화 + +### 3.1 정제 파이프라인 + +```mermaid +graph TD + A[원본 데이터] --> B[결측치 처리] + B --> C[이상치 제거] + C --> D[정규화] + D --> E[카테고리 인코딩] + E --> F[시계열 특성 추출] + F --> G[벡터화] +``` + +#### 3.1.1 매장 데이터 정제 + +**1) 결측치 처리** +- `budget`: 업종별 평균값으로 대체 +- `target_customer`: "전체"로 기본값 설정 +- `location.dong`: 시군구 단위로 통합 + +**2) 정규화** +- 예산: Min-Max Scaling (0~1) +- 좌표: Standard Scaling (평균 0, 분산 1) + +**3) 카테고리 인코딩** +```python +# One-Hot Encoding for categorical features +업종_대분류 = OneHotEncoder(['음식점', '소매업', '서비스업']) +업종_중분류 = LabelEncoder() # 100+ categories → Integer +지역_시도 = OneHotEncoder(['서울', '경기', '인천', ...]) +``` + +**4) 시계열 특성 (Cyclical Encoding)** +```python +# 계절성 표현: 봄(3~5월) = 0°, 여름 = 90°, 가을 = 180°, 겨울 = 270° +month = datetime.now().month +season_sin = np.sin(2 * np.pi * month / 12) +season_cos = np.cos(2 * np.pi * month / 12) +``` + +#### 3.1.2 경품 데이터 정제 + +**1) 트렌드 점수 계산** +```python +# 네이버 쇼핑 트렌드 API 응답 기반 +trend_score = ( + 0.4 * 검색량_증가율 + + 0.3 * 클릭률 + + 0.3 * SNS_언급_빈도 +) +``` + +**2) 호환성 매트릭스** +```python +# 과거 성과 데이터 기반 업종별 선호도 +compatibility_matrix = { + ('음식점', '식음료 쿠폰'): 0.95, + ('음식점', '생활용품'): 0.6, + ('소매업', '할인쿠폰'): 0.9, + ... +} +``` + +### 3.2 벡터화 전략 + +#### 3.2.1 매장 임베딩 (Store Embedding) + +**차원 구성 (총 128차원)** +```python +store_vector = np.concatenate([ + 업종_one_hot, # 20차원 + 지역_demographic, # 30차원 (인구 밀도, 소득 수준, 연령 분포 등) + 예산_normalized, # 1차원 + 타겟고객_encoded, # 10차원 + 시즌_cyclical, # 2차원 (sin, cos) + 이벤트_목적_one_hot, # 5차원 + 상권_특성 # 60차원 (유동인구, 경쟁 업체 수, 매출 추정치 등) +]) +``` + +**임베딩 모델** +- **Option 1**: 수동 Feature Engineering (위 구조) +- **Option 2**: Pre-trained Model (추후 고도화) + - `sentence-transformers/all-MiniLM-L6-v2` 활용 + - 매장 설명 텍스트를 자연어로 생성 후 임베딩 + +#### 3.2.2 경품 임베딩 (Prize Embedding) + +**차원 구성 (총 128차원 - Store와 동일 공간)** +```python +prize_vector = np.concatenate([ + 카테고리_one_hot, # 20차원 + 가격_normalized, # 1차원 + 타겟_demographic, # 10차원 + 시즌_cyclical, # 2차원 + 트렌드_score, # 1차원 + 호환성_matrix, # 20차원 + 설명_embedding # 74차원 (sentence-transformers) +]) +``` + +#### 3.2.3 성공 사례 임베딩 (Case Embedding) + +**하이브리드 접근** +```python +case_vector = np.concatenate([ + store_vector, # 128차원 + prize_vector, # 128차원 + performance_features # 16차원 (ROI, 전환율, 만족도 등) +]) +# 총 272차원 +``` + +### 3.3 Redis Vector Search 저장 + +#### 3.3.1 인덱스 생성 +```python +from redis.commands.search.field import VectorField, TextField, NumericField +from redis.commands.search.indexDefinition import IndexDefinition, IndexType + +schema = ( + VectorField("case_vector", "FLAT", { + "TYPE": "FLOAT32", + "DIM": 272, + "DISTANCE_METRIC": "COSINE" + }), + TextField("store_category"), + TextField("prize_name"), + NumericField("roi"), + NumericField("conversion_rate"), + NumericField("timestamp") +) + +redis_client.ft("idx:prize_cases").create_index( + schema, + definition=IndexDefinition(prefix=["case:"], index_type=IndexType.HASH) +) +``` + +#### 3.3.2 데이터 저장 예시 +```python +import numpy as np +import pickle + +case_id = "case:12345" +redis_client.hset(case_id, mapping={ + "case_vector": pickle.dumps(case_vector.astype(np.float32)), + "store_category": "음식점 > 한식 > 고깃집", + "prize_name": "한우 선물세트", + "roi": 3.2, + "conversion_rate": 0.15, + "timestamp": "2025-01-15" +}) +``` + +--- + +## 4. Claude API 호출 구조 + +### 4.1 프롬프트 설계 + +#### 4.1.1 시스템 프롬프트 (Prompt Caching 적용) +```json +{ + "role": "system", + "content": [ + { + "type": "text", + "text": "당신은 소상공인 이벤트 기획 전문가입니다. 매장 정보와 유사 성공 사례를 바탕으로 최적의 경품을 추천하고, 그 이유를 명확히 설명해야 합니다.\n\n[역할]\n- 업종, 지역, 예산, 타겟 고객을 종합 분석\n- 과거 성공 사례 패턴 학습\n- 창의적이면서도 실현 가능한 경품 제안\n- 추천 이유를 구체적 데이터로 뒷받침\n\n[제약사항]\n- 예산 범위 내 경품만 추천\n- 법적 문제 없는 경품 (사행성 금지)\n- 조달 가능한 경품 우선", + "cache_control": {"type": "ephemeral"} + } + ] +} +``` + +#### 4.1.2 Few-Shot Examples (Prompt Caching 적용) +```json +{ + "role": "user", + "content": [ + { + "type": "text", + "text": "[사례 1]\n매장: 강남역 고깃집, 예산 50만원, 타겟 20~30대 직장인\n유사 성공 사례: 역삼동 삼겹살집이 '소주 1+1 쿠폰' 이벤트로 재방문율 40% 증가\n\n[사례 2]\n매장: 홍대 카페, 예산 30만원, 타겟 10~20대 학생\n유사 성공 사례: 신촌 디저트카페가 'AirPods 추첨' 이벤트로 SNS 공유 200% 증가\n\n[사례 3]\n매장: 이태원 양식당, 예산 100만원, 타겟 30~40대 고소득층\n유사 성공 사례: 청담동 스테이크 하우스가 '와인 시음권' 이벤트로 객단가 25% 상승", + "cache_control": {"type": "ephemeral"} + } + ] +} +``` + +#### 4.1.3 User Request (실시간 입력) +```json +{ + "role": "user", + "content": [ + { + "type": "text", + "text": "## 매장 정보\n- 업종: 음식점 > 한식 > 고깃집\n- 위치: 서울 강남구 역삼동\n- 예산: 50만원\n- 타겟 고객: 20~30대 직장인, 남녀 모두\n- 이벤트 목적: 신규 고객 유치\n- 시즌: 2025년 1분기 (겨울)\n\n## 유사 성공 사례 (벡터 검색 결과)\n1. [ROI 3.2] 역삼동 삼겹살집 - 소주 1+1 쿠폰 (예산 40만원, 전환율 15%)\n2. [ROI 2.8] 서초동 한우집 - 한우 선물세트 추첨 (예산 60만원, 전환율 12%)\n3. [ROI 2.5] 강남역 숯불구이 - 배달앱 할인쿠폰 (예산 30만원, 전환율 18%)\n\n## 요청사항\n위 정보를 바탕으로 다음을 제공하세요:\n1. 최적 경품 1개 (구체적 상품명, 수량, 예상 비용)\n2. 대안 경품 2개\n3. 각 경품의 추천 이유 (과거 사례 근거 포함)\n4. 예상 효과 (참여자 수, 전환율, ROI)\n\nJSON 형식으로 응답해주세요." + } + ] +} +``` + +### 4.2 API 요청 구조 + +#### 4.2.1 Request 예시 +```json +{ + "model": "claude-3-5-sonnet-20241022", + "max_tokens": 4096, + "temperature": 0.7, + "system": [ + { + "type": "text", + "text": "당신은 소상공인 이벤트 기획 전문가입니다...", + "cache_control": {"type": "ephemeral"} + } + ], + "messages": [ + { + "role": "user", + "content": "[사례 1]\n...", + "cache_control": {"type": "ephemeral"} + }, + { + "role": "user", + "content": "## 매장 정보\n..." + } + ], + "stream": true +} +``` + +**Prompt Caching 효과** +- System Prompt (약 500 tokens): 캐싱 후 재사용 시 90% 비용 절감 +- Few-Shot Examples (약 800 tokens): 캐싱 후 재사용 시 90% 비용 절감 +- 5분 내 동일 프롬프트 재사용 시 캐시 히트 + +#### 4.2.2 Response 구조 (Streaming) +```json +{ + "id": "msg_01XYZ...", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "{\n \"recommendations\": [\n {\n \"rank\": 1,\n \"prize\": {\n \"name\": \"1++등급 한우 등심 200g 교환권\",\n \"category\": \"식음료\",\n \"quantity\": 20,\n \"unit_price\": 25000,\n \"total_cost\": 500000,\n \"supplier\": \"한우자조금\"\n },\n \"reasoning\": {\n \"why_this_prize\": \"고깃집 업종 특성상 '고기 품질'에 대한 직접 경험이 재방문 유도에 가장 효과적입니다. 역삼동 삼겹살집 사례(ROI 3.2)에서 '소주 쿠폰'보다 '한우 선물세트'가 고급화 전략에 적합합니다.\",\n \"target_alignment\": \"20~30대 직장인은 '가성비'보다 '특별한 경험'을 선호하는 경향(네이버 쇼핑 트렌드 2025.01 기준, 프리미엄 식품 검색량 35% 증가)\",\n \"budget_efficiency\": \"건당 2.5만원으로 20명 당첨 시 예산 100% 활용. 서초동 한우집 사례 대비 20% 저렴한 비용으로 유사 효과 기대\",\n \"seasonal_relevance\": \"겨울철 보양식 수요 증가 (1분기 한우 판매량 전년 대비 18% 상승, 농림축산식품부)\"\n },\n \"expected_outcome\": {\n \"participant_count\": 300,\n \"conversion_rate\": 0.14,\n \"new_customers\": 42,\n \"roi\": 3.0,\n \"rationale\": \"유사 사례(역삼동 삼겹살집) 전환율 15% 대비 소폭 하락 예상. 단, 한우 브랜드 신뢰도로 고객 만족도 상승 효과\"\n }\n },\n {\n \"rank\": 2,\n \"prize\": {\n \"name\": \"배달앱 5천원 할인쿠폰 (100매)\",\n \"category\": \"할인쿠폰\",\n \"quantity\": 100,\n \"unit_price\": 5000,\n \"total_cost\": 500000\n },\n \"reasoning\": {\n \"why_this_prize\": \"강남역 숯불구이 사례(ROI 2.5, 전환율 18%)에서 입증된 효과. 즉시 사용 가능한 혜택으로 참여 장벽 낮춤\",\n \"target_alignment\": \"배달 이용률 높은 직장인 타겟 적합 (20~30대 배달앱 이용률 주 3회 이상 68%, 통계청)\",\n \"budget_efficiency\": \"100명 당첨 가능, 경품 수량 많아 '당첨 가능성' 마케팅 효과\",\n \"seasonal_relevance\": \"겨울철 배달 수요 증가 (기온 5도 하락 시 배달 주문 12% 증가, 배민 데이터)\"\n },\n \"expected_outcome\": {\n \"participant_count\": 500,\n \"conversion_rate\": 0.18,\n \"new_customers\": 90,\n \"roi\": 2.5\n }\n },\n {\n \"rank\": 3,\n \"prize\": {\n \"name\": \"프리미엄 소주/와인 세트 (10세트)\",\n \"category\": \"식음료\",\n \"quantity\": 10,\n \"unit_price\": 50000,\n \"total_cost\": 500000\n },\n \"reasoning\": {\n \"why_this_prize\": \"고급화 전략 + SNS 공유 유도. '언박싱' 콘텐츠로 바이럴 효과 기대\",\n \"target_alignment\": \"MZ세대 '프리미엄 주류' 소비 증가 (위스키 수입액 2024년 전년 대비 23% 증가, 관세청)\",\n \"budget_efficiency\": \"고가 경품으로 '프리미엄 이미지' 구축, 브랜드 가치 상승 효과\",\n \"seasonal_relevance\": \"연말연시 선물 수요 연계 (1~2월 선물 세트 검색량 연중 최고치)\"\n },\n \"expected_outcome\": {\n \"participant_count\": 200,\n \"conversion_rate\": 0.10,\n \"new_customers\": 20,\n \"roi\": 2.2,\n \"rationale\": \"당첨자 수 적어 전환율 낮지만, SNS 공유로 브랜드 인지도 상승 효과 (간접 효과 미포함 시)\"\n }\n }\n ],\n \"metadata\": {\n \"analysis_timestamp\": \"2025-01-20T10:30:00Z\",\n \"vector_search_cases\": 3,\n \"trend_data_sources\": [\"네이버 쇼핑 트렌드\", \"농림축산식품부\", \"통계청\"]\n }\n}\n" + } + ], + "model": "claude-3-5-sonnet-20241022", + "usage": { + "input_tokens": 2150, + "cache_creation_input_tokens": 1300, + "cache_read_input_tokens": 0, + "output_tokens": 1024 + } +} +``` + +### 4.3 응답 파싱 및 후처리 + +#### 4.3.1 JSON 검증 +```python +import json +from jsonschema import validate, ValidationError + +response_schema = { + "type": "object", + "required": ["recommendations"], + "properties": { + "recommendations": { + "type": "array", + "minItems": 3, + "maxItems": 3, + "items": { + "type": "object", + "required": ["rank", "prize", "reasoning", "expected_outcome"], + "properties": { + "rank": {"type": "integer", "minimum": 1, "maximum": 3}, + "prize": { + "type": "object", + "required": ["name", "category", "quantity", "unit_price", "total_cost"] + }, + "reasoning": { + "type": "object", + "required": ["why_this_prize", "target_alignment", "budget_efficiency"] + }, + "expected_outcome": { + "type": "object", + "required": ["participant_count", "conversion_rate", "roi"] + } + } + } + } + } +} + +try: + parsed_response = json.loads(claude_response) + validate(instance=parsed_response, schema=response_schema) +except (json.JSONDecodeError, ValidationError) as e: + # Fallback: 룰 기반 추천 호출 + logger.error(f"Claude response validation failed: {e}") + return fallback_recommendation(store_data) +``` + +#### 4.3.2 예산 초과 필터링 +```python +def filter_budget_overrun(recommendations, max_budget): + filtered = [] + for rec in recommendations: + if rec['prize']['total_cost'] <= max_budget: + filtered.append(rec) + else: + # 수량 조정으로 예산 내 맞추기 + adjusted_quantity = max_budget // rec['prize']['unit_price'] + if adjusted_quantity > 0: + rec['prize']['quantity'] = adjusted_quantity + rec['prize']['total_cost'] = adjusted_quantity * rec['prize']['unit_price'] + rec['reasoning']['budget_efficiency'] += f" (수량 조정: {adjusted_quantity}개)" + filtered.append(rec) + return filtered[:3] # 최대 3개 유지 +``` + +--- + +## 5. 전체 시스템 플로우 + +### 5.1 추천 요청 흐름도 + +```mermaid +sequenceDiagram + participant User as 사용자 + participant API as API Gateway + participant Svc as Prize Recommendation Service + participant Cache as Redis Cache + participant Vector as Redis Vector Search + participant Claude as Claude API + participant Fallback as Fallback Engine + + User->>API: POST /api/v1/prizes/recommend + API->>Svc: 매장 정보 전달 + + alt 캐시 히트 + Svc->>Cache: 동일 매장 프로필 조회 + Cache-->>Svc: 캐시된 추천 결과 (TTL 1시간) + Svc-->>API: 추천 결과 반환 + else 캐시 미스 + Svc->>Svc: 매장 데이터 정제 및 벡터화 + Svc->>Vector: 유사 성공 사례 검색 (Top 3) + Vector-->>Svc: 사례 데이터 반환 + + Svc->>Claude: Prompt 생성 및 API 호출 + Note over Svc,Claude: System Prompt (캐싱)
Few-Shot Examples (캐싱)
User Request (실시간) + + alt Claude 성공 + Claude-->>Svc: Streaming Response (JSON) + Svc->>Svc: JSON 파싱 및 검증 + Svc->>Cache: 추천 결과 캐싱 (TTL 1시간) + Svc-->>API: 추천 결과 반환 + else Claude 실패 + Claude-->>Svc: Error (Timeout/Rate Limit) + Svc->>Fallback: 룰 기반 추천 요청 + Fallback-->>Svc: 기본 추천 결과 + Svc-->>API: Fallback 결과 반환 + end + end + + API-->>User: HTTP 200 OK + JSON +``` + +### 5.2 데이터 파이프라인 스케줄 + +```mermaid +gantt + title 데이터 수집 및 갱신 스케줄 + dateFormat YYYY-MM-DD + section 외부 데이터 + 네이버 트렌드 수집 :active, trend, 2025-01-20, 7d + SNS 트렌드 크롤링 :active, sns, 2025-01-20, 7d + 공공데이터 동기화 :active, public, 2025-01-20, 7d + section 벡터 재계산 + 성공 사례 임베딩 :active, embed, 2025-01-20, 1d + 경품 카탈로그 갱신 :active, catalog, 2025-01-20, 1d + section 모델 업데이트 + Claude Prompt 최적화 :milestone, prompt, 2025-01-27, 0d +``` + +**스케줄 상세** +- **외부 데이터 수집**: 매주 월요일 02:00 (Airflow DAG) +- **벡터 재계산**: 매일 03:00 (신규 사례 추가 시) +- **캐시 갱신**: + - L1 (업종별 시즌 추천): TTL 7일 + - L2 (개인화 추천): TTL 1시간 +- **Prompt 튜닝**: 월 1회 (성과 데이터 기반 Few-Shot 사례 갱신) + +--- + +## 6. Fallback 전략 + +### 6.1 Claude API 장애 대응 + +#### 6.1.1 룰 기반 추천 엔진 +```python +class FallbackRecommendation: + def __init__(self): + self.rules = self._load_rules() + + def recommend(self, store_data): + # 1단계: 업종별 인기 경품 필터링 + category_prizes = self.rules['category_mapping'][store_data['category']['main']] + + # 2단계: 예산 필터링 + budget_filtered = [p for p in category_prizes if p['price'] <= store_data['budget']['max']] + + # 3단계: 시즌 가중치 적용 + season = store_data['season'] + for prize in budget_filtered: + prize['score'] = prize['base_score'] * self.rules['season_weight'][season].get(prize['id'], 1.0) + + # 4단계: 상위 3개 선정 + top_prizes = sorted(budget_filtered, key=lambda x: x['score'], reverse=True)[:3] + + return self._format_response(top_prizes, store_data) +``` + +#### 6.1.2 과거 인기 경품 순위 +```python +def get_popular_prizes(category, budget_range, limit=3): + """최근 3개월 성과 데이터 기반 인기 경품 조회""" + query = """ + SELECT prize_id, name, AVG(roi) as avg_roi, COUNT(*) as usage_count + FROM event_performance + WHERE category = %s + AND budget BETWEEN %s AND %s + AND created_at >= NOW() - INTERVAL 3 MONTH + GROUP BY prize_id + ORDER BY avg_roi DESC, usage_count DESC + LIMIT %s + """ + return db.execute(query, [category, budget_range[0], budget_range[1], limit]) +``` + +### 6.2 에러 처리 우선순위 + +```mermaid +graph TD + A[Claude API 호출] --> B{성공?} + B -->|Yes| C[JSON 검증] + B -->|No| D{재시도 가능?} + + D -->|Yes| E[Exponential Backoff 재시도] + E --> A + D -->|No| F[Fallback: 룰 기반 추천] + + C --> G{검증 통과?} + G -->|Yes| H[응답 반환] + G -->|No| F + + F --> I[과거 인기 경품 조회] + I --> J{데이터 있음?} + J -->|Yes| K[기본 추천 반환] + J -->|No| L[에러 메시지 + 수동 선택 유도] +``` + +--- + +## 7. 성능 최적화 + +### 7.1 캐싱 전략 + +#### 7.1.1 L1 캐시 (업종별 시즌 추천) +```python +# Redis Key: "prize:season:{category}:{season}" +# TTL: 7일 +# 예시: "prize:season:음식점-한식:2025-Q1" + +cache_key = f"prize:season:{store_category}:{current_season}" +cached = redis_client.get(cache_key) + +if cached: + return json.loads(cached) +else: + result = claude_api.recommend(...) + redis_client.setex(cache_key, 604800, json.dumps(result)) # 7일 = 604800초 + return result +``` + +#### 7.1.2 L2 캐시 (개인화 추천) +```python +# Redis Key: "prize:personalized:{store_id}:{hash(request)}" +# TTL: 1시간 + +import hashlib +request_hash = hashlib.md5(json.dumps(store_data, sort_keys=True).encode()).hexdigest() +cache_key = f"prize:personalized:{store_id}:{request_hash}" + +cached = redis_client.get(cache_key) +if cached: + return json.loads(cached) +else: + result = claude_api.recommend(...) + redis_client.setex(cache_key, 3600, json.dumps(result)) # 1시간 = 3600초 + return result +``` + +### 7.2 벡터 검색 최적화 + +#### 7.2.1 인덱스 파라미터 튜닝 +```python +# FLAT vs HNSW 비교 +# FLAT: 정확도 100%, 검색 속도 O(n) - 데이터 10만 건 이하 +# HNSW: 정확도 95%+, 검색 속도 O(log n) - 대규모 데이터 + +# 초기 (성공 사례 < 10만 건): FLAT 사용 +schema = VectorField("case_vector", "FLAT", {...}) + +# 확장 시 (성공 사례 > 10만 건): HNSW 전환 +schema = VectorField("case_vector", "HNSW", { + "TYPE": "FLOAT32", + "DIM": 272, + "DISTANCE_METRIC": "COSINE", + "M": 16, # 연결 수 (높을수록 정확, 느림) + "EF_CONSTRUCTION": 200 # 구축 시간 vs 정확도 트레이드오프 +}) +``` + +#### 7.2.2 Pre-filtering +```python +# 벡터 검색 전 메타데이터 필터링으로 검색 공간 축소 +query = ( + Query("(@category:{음식점}) (@budget:[0 500000])=>[KNN 3 @case_vector $vec AS score]") + .sort_by("score") + .return_fields("store_category", "prize_name", "roi", "score") + .dialect(2) +) +``` + +### 7.3 Claude API 비용 최적화 + +#### 7.3.1 Prompt Caching 효과 분석 +```python +# Prompt Caching 적용 전 +base_cost_per_request = ( + (500 + 800 + 850) * 0.003 / 1000 # System + Few-Shot + User (입력) + + 1024 * 0.015 / 1000 # 출력 +) = 0.00642 + 0.01536 = $0.02178 + +# Prompt Caching 적용 후 (캐시 히트 시) +optimized_cost_per_request = ( + (500 + 800) * 0.0003 / 1000 # 캐싱된 토큰 (90% 할인) + + 850 * 0.003 / 1000 # 신규 User 토큰 + + 1024 * 0.015 / 1000 # 출력 +) = 0.00039 + 0.00255 + 0.01536 = $0.0183 + +# 비용 절감율: (0.02178 - 0.0183) / 0.02178 = 16% +``` + +**월간 비용 추정 (일 1,000 요청 기준)** +- 캐시 히트율 70% 가정 +- 월 비용: (1000 * 30) * (0.0183 * 0.7 + 0.02178 * 0.3) = **$581** +- Caching 미적용 시: (1000 * 30) * 0.02178 = **$653** +- **절감액: $72/월 (11%)** + +#### 7.3.2 배치 처리 +```python +# 동일 시간대 다수 요청 발생 시 배치 처리 +async def batch_recommend(store_list, batch_size=5): + """ + 5개씩 묶어서 Claude API 호출 + - 단일 프롬프트에 여러 매장 정보 포함 + - 응답을 파싱하여 개별 결과로 분리 + """ + batches = [store_list[i:i+batch_size] for i in range(0, len(store_list), batch_size)] + results = [] + + for batch in batches: + combined_prompt = "\n\n".join([f"[매장 {i+1}]\n{format_store(s)}" for i, s in enumerate(batch)]) + response = await claude_api.recommend_batch(combined_prompt) + results.extend(parse_batch_response(response, len(batch))) + + return results +``` + +--- + +## 8. 모니터링 및 개선 + +### 8.1 성능 지표 + +#### 8.1.1 추천 정확도 (Recommendation Accuracy) +```python +# 사용자 행동 추적 +metrics = { + "ctr": "추천 경품 클릭률", # 추천 3개 중 클릭한 비율 + "selection_rate": "추천 선택률", # 추천 경품을 실제 이벤트에 사용한 비율 + "satisfaction_score": "만족도", # 이벤트 종료 후 설문 (1~5점) + "roi_accuracy": "ROI 예측 정확도" # 예측 ROI vs 실제 ROI 오차율 +} + +# 목표 KPI +targets = { + "ctr": 0.6, # 60% 이상 + "selection_rate": 0.4, # 40% 이상 + "satisfaction_score": 4.0, # 5점 만점 중 4점 이상 + "roi_accuracy": 0.8 # 오차 20% 이내 +} +``` + +#### 8.1.2 시스템 성능 +```python +# Prometheus + Grafana 모니터링 +system_metrics = { + "claude_api_latency": "Claude API 응답 시간 (p50, p95, p99)", + "vector_search_latency": "벡터 검색 응답 시간", + "cache_hit_rate": "캐시 히트율 (L1, L2 별도)", + "fallback_rate": "Fallback 발생률", + "daily_api_cost": "일일 Claude API 비용" +} + +# 알림 임계값 +alerts = { + "claude_api_latency_p95": 3000, # 3초 초과 시 알림 + "cache_hit_rate": 0.5, # 50% 미만 시 알림 + "fallback_rate": 0.1, # 10% 초과 시 알림 + "daily_api_cost": 100 # $100 초과 시 알림 +} +``` + +### 8.2 피드백 루프 + +#### 8.2.1 사용자 피드백 수집 +```python +class FeedbackCollector: + def collect(self, event_id, feedback_type): + """ + feedback_type: + - "thumbs_up": 추천 만족 + - "thumbs_down": 추천 불만족 + - "custom_prize": 사용자가 직접 경품 변경 + - "roi_feedback": 이벤트 종료 후 실제 ROI 입력 + """ + feedback = { + "event_id": event_id, + "type": feedback_type, + "timestamp": datetime.now(), + "store_profile": get_store_profile(event_id), + "recommended_prizes": get_recommendations(event_id), + "selected_prize": get_selected_prize(event_id), + "actual_performance": get_performance(event_id) if feedback_type == "roi_feedback" else None + } + + # Kafka로 전송 → 데이터 파이프라인에서 벡터 DB 갱신 + kafka_producer.send("feedback.prize_recommendation", feedback) +``` + +#### 8.2.2 Few-Shot 사례 자동 갱신 +```python +def update_few_shot_examples(): + """ + 월 1회 실행: 최근 3개월 성과 데이터 기반 Few-Shot 사례 갱신 + """ + top_cases = db.execute(""" + SELECT store_profile, prize, performance + FROM event_performance + WHERE created_at >= NOW() - INTERVAL 3 MONTH + AND roi >= 2.5 + AND customer_satisfaction >= 4.0 + ORDER BY roi DESC, conversion_rate DESC + LIMIT 5 + """) + + # Few-Shot 템플릿 재생성 + new_examples = format_few_shot_examples(top_cases) + + # S3 또는 DB에 버전 관리 + save_prompt_template("few_shot_v2.json", new_examples) + + # Claude API 호출 시 새 템플릿 적용 + update_system_prompt(new_examples) +``` + +--- + +## 9. 구현 우선순위 + +### Phase 1: MVP (2주) +- [x] 매장 데이터 수집 API 연동 (공공데이터포털) +- [x] 경품 카탈로그 수동 구축 (100개 경품) +- [x] 수동 Feature Engineering 벡터화 +- [x] Redis Vector Search 기본 구현 +- [x] Claude API 기본 프롬프트 (Few-Shot 3개) +- [x] 룰 기반 Fallback + +### Phase 2: 최적화 (1주) +- [ ] Prompt Caching 적용 +- [ ] L1/L2 캐싱 전략 구현 +- [ ] 외부 트렌드 데이터 수집 자동화 (네이버 트렌드) +- [ ] 성능 모니터링 대시보드 (Grafana) + +### Phase 3: 고도화 (2주) +- [ ] 사용자 피드백 수집 시스템 +- [ ] Few-Shot 자동 갱신 파이프라인 +- [ ] Sentence Transformer 임베딩 전환 (Option 2) +- [ ] A/B 테스트 프레임워크 +- [ ] SNS 트렌드 크롤링 + +--- + +## 10. 참조 자료 + +### 10.1 관련 문서 +- 유저스토리: `design/userstory.md` +- UI/UX 프로토타입: `design/uiux/prototype/05-AI경품추천.html` +- API 설계서: `design/backend/api/prize-recommendation-api.yaml` + +### 10.2 외부 리소스 +- Claude API 문서: https://docs.anthropic.com/claude/docs/intro-to-claude +- Redis Vector Search: https://redis.io/docs/stack/search/reference/vectors/ +- 공공데이터포털: https://www.data.go.kr/ +- 네이버 쇼핑 트렌드: https://datalab.naver.com/shoppingInsight/sCategory.naver + +--- + +## 부록: 코드 예시 + +### A. 전체 추천 API 엔드포인트 + +```python +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel +import asyncio + +router = APIRouter() + +class StoreProfile(BaseModel): + store_id: str + business_number: str + category: dict + location: dict + budget: dict + target_customer: dict + event_purpose: str + +class RecommendationRequest(BaseModel): + store_profile: StoreProfile + +@router.post("/api/v1/prizes/recommend") +async def recommend_prizes(request: RecommendationRequest): + """ + 경품 추천 메인 엔드포인트 + + Flow: + 1. 캐시 조회 (L2: 개인화) + 2. 벡터 검색 (유사 성공 사례 Top 3) + 3. Claude API 호출 (Streaming) + 4. 응답 검증 및 후처리 + 5. 캐시 저장 + """ + try: + # 1. 캐시 조회 + cache_key = generate_cache_key(request.store_profile) + cached_result = await redis_cache.get(cache_key) + if cached_result: + logger.info(f"Cache hit: {cache_key}") + return cached_result + + # 2. 매장 데이터 정제 및 벡터화 + store_vector = await vectorize_store(request.store_profile) + + # 3. 벡터 검색 (유사 사례) + similar_cases = await vector_search.find_similar(store_vector, top_k=3) + + # 4. Claude API 호출 + prompt = build_prompt( + system=SYSTEM_PROMPT, + few_shot=FEW_SHOT_EXAMPLES, + store_profile=request.store_profile, + similar_cases=similar_cases + ) + + claude_response = await claude_client.recommend(prompt, stream=True) + + # 5. 응답 파싱 및 검증 + recommendations = parse_and_validate(claude_response) + + # 6. 예산 필터링 + filtered = filter_budget(recommendations, request.store_profile.budget.max) + + # 7. 캐시 저장 (TTL 1시간) + await redis_cache.setex(cache_key, 3600, filtered) + + return { + "status": "success", + "data": filtered, + "metadata": { + "cache_hit": False, + "vector_search_count": len(similar_cases), + "model": "claude-3-5-sonnet-20241022" + } + } + + except ClaudeAPIError as e: + logger.error(f"Claude API failed: {e}") + # Fallback + fallback_result = fallback_engine.recommend(request.store_profile) + return { + "status": "fallback", + "data": fallback_result, + "metadata": {"error": str(e)} + } + + except Exception as e: + logger.exception("Unexpected error in prize recommendation") + raise HTTPException(status_code=500, detail=str(e)) +``` + +### B. 벡터 검색 구현 + +```python +import redis +from redis.commands.search.query import Query +import numpy as np +import pickle + +class VectorSearchEngine: + def __init__(self, redis_client): + self.client = redis_client + self.index_name = "idx:prize_cases" + + async def find_similar(self, query_vector: np.ndarray, top_k: int = 3): + """ + 코사인 유사도 기반 벡터 검색 + + Args: + query_vector: 272차원 매장 임베딩 + top_k: 반환할 유사 사례 개수 + + Returns: + List[dict]: 유사 사례 데이터 + """ + # 벡터를 bytes로 직렬화 + query_bytes = pickle.dumps(query_vector.astype(np.float32)) + + # Redis Vector Search 쿼리 + query = ( + Query(f"*=>[KNN {top_k} @case_vector $vec AS score]") + .sort_by("score") + .return_fields("store_category", "prize_name", "roi", "conversion_rate", "case_vector", "score") + .paging(0, top_k) + .dialect(2) + ) + + results = self.client.ft(self.index_name).search( + query, + query_params={"vec": query_bytes} + ) + + # 결과 파싱 + similar_cases = [] + for doc in results.docs: + similar_cases.append({ + "store_category": doc.store_category, + "prize_name": doc.prize_name, + "roi": float(doc.roi), + "conversion_rate": float(doc.conversion_rate), + "similarity_score": 1 - float(doc.score) # 코사인 거리 → 유사도 + }) + + return similar_cases +``` + +### C. Claude API 클라이언트 + +```python +import anthropic +import json + +class ClaudeRecommendationClient: + def __init__(self, api_key: str): + self.client = anthropic.Anthropic(api_key=api_key) + self.model = "claude-3-5-sonnet-20241022" + + async def recommend(self, prompt: dict, stream: bool = True): + """ + Claude API 호출 (Streaming) + + Args: + prompt: {system, messages} 구조 + stream: Streaming 여부 + + Returns: + dict: 파싱된 JSON 응답 + """ + try: + response = self.client.messages.create( + model=self.model, + max_tokens=4096, + temperature=0.7, + system=prompt['system'], + messages=prompt['messages'], + stream=stream + ) + + if stream: + # Streaming 응답 수집 + full_text = "" + async for chunk in response: + if chunk.type == "content_block_delta": + full_text += chunk.delta.text + + # JSON 파싱 + return json.loads(full_text) + else: + return json.loads(response.content[0].text) + + except anthropic.APIError as e: + raise ClaudeAPIError(f"Claude API failed: {e.status_code} - {e.message}") + + except json.JSONDecodeError as e: + raise ClaudeAPIError(f"Invalid JSON response: {e}") +``` diff --git a/design/이벤트설계.md b/design/이벤트설계.md new file mode 100644 index 0000000..d59e9ce --- /dev/null +++ b/design/이벤트설계.md @@ -0,0 +1,949 @@ +# AI 기반 이벤트 추천 설계서 + +**작성일**: 2025년 1월 +**버전**: 1.0 +**목적**: 업종/지역/계절별 최적의 이벤트 추천 시스템 설계 + +--- + +## 📋 목차 + +1. [개요](#1-개요) +2. [이벤트 유형 분류](#2-이벤트-유형-분류) +3. [추천 알고리즘](#3-추천-알고리즘) +4. [업종별 이벤트 매핑](#4-업종별-이벤트-매핑) +5. [계절별 이벤트 매핑](#5-계절별-이벤트-매핑) +6. [가성비 점수 시스템](#6-가성비-점수-시스템) +7. [화면 설계](#7-화면-설계) +8. [데이터 구조](#8-데이터-구조) + +--- + +## 1. 개요 + +### 1.1 배경 + +기존 시스템은 **경품 추천**만 제공하여 이벤트 방법이 제한적이었습니다. +업종, 지역, 계절 특성을 고려한 **다양한 이벤트 유형 추천**이 필요합니다. + +### 1.2 목표 + +- ✅ **10가지 이상의 이벤트 유형** 추천 +- ✅ **업종/계절별 맞춤 추천** 제공 +- ✅ **가성비 점수** 기반 우선순위 제시 +- ✅ **실행 난이도** 표시로 선택 용이성 확보 +- ✅ **예상 ROI 및 효과** 사전 안내 + +### 1.3 주요 기능 + +```yaml +이벤트 유형 추천: + - 업종 기반 필터링 + - 계절 기반 필터링 + - 예산 범위 필터링 + - 가성비 점수 정렬 + +상세 정보 제공: + - 실행 가이드 + - 비용 구조 + - 예상 효과 + - 성공 사례 + +자동 기획안 생성: + - 선택한 이벤트 유형 기반 + - 경품/참여방법 자동 설계 + - 홍보 문구 생성 +``` + +--- + +## 2. 이벤트 유형 분류 + +### 2.1 참여 방식별 분류 + +#### 📱 **디지털 이벤트** (6가지) + +**1. SNS 해시태그 이벤트** +```yaml +개요: 인스타그램/페이스북 해시태그 참여 +적합 업종: 카페, 일식당, 양식당 +적합 계절: 연중 (봄/겨울 특히 효과적) +예산 범위: 5-10만원 +가성비 점수: 17.0 +난이도: ⭐ (쉬움) + +기대 효과: + - SNS 노출: +400~600% + - 신규 고객: +60~80% + - 브랜드 인지도: +120% + +실행 체크리스트: + - [ ] 해시태그 3개 선정 + - [ ] 이벤트 이미지 제작 + - [ ] 경품 준비 + - [ ] 참여 조건 명시 + - [ ] 추첨 방법 결정 +``` + +**2. 배달앱 리뷰 이벤트** +```yaml +개요: 배달앱 주문 후 리뷰 작성 시 혜택 +적합 업종: 전 업종 (특히 치킨집, 중식당) +적합 계절: 연중 +예산 범위: 20-30만원 +가성비 점수: 7.4 +난이도: ⭐⭐ (보통) + +기대 효과: + - 평점 상승: +0.5~1.0점 + - 리뷰 수: +100~150건 + - 신규 주문: +50~100건 + - 재방문율: +55% +``` + +**3. 카카오톡 알림톡 이벤트** +```yaml +개요: 생일/재방문 고객에게 자동 쿠폰 발송 +적합 업종: 전 업종 +적합 계절: 연중 +예산 범위: 15-25만원 +가성비 점수: 3.77 +난이도: ⭐⭐ (보통) + +기대 효과: + - 재방문율: +60% + - 쿠폰 사용률: 25% + - 고객 만족도: +95% +``` + +**4. 인스타그램 릴스/스토리 챌린지** +```yaml +개요: 릴스 영상 제작 참여 이벤트 +적합 업종: 카페, 일식당, 분식집 +적합 계절: 여름, 봄 +예산 범위: 10-20만원 +가성비 점수: 12.5 +난이도: ⭐⭐ (보통) + +기대 효과: + - 릴스 조회수: 5,000~50,000회 + - 바이럴 확산: +300% + - 젊은 층 유입: +80% +``` + +**5. 네이버 예약 이벤트** +```yaml +개요: 네이버 예약 시 특별 혜택 +적합 업종: 양식당, 일식당 +적합 계절: 연중 (특히 크리스마스, 기념일) +예산 범위: 10-30만원 +가성비 점수: 5.8 +난이도: ⭐⭐ (보통) + +기대 효과: + - 예약률: +150% + - 노쇼율: -30% + - 네이버 노출: +200% +``` + +**6. 온라인 설문 이벤트** +```yaml +개요: 고객 의견 수집 + 경품 추첨 +적합 업종: 전 업종 +적합 계절: 연중 +예산 범위: 5-15만원 +가성비 점수: 6.2 +난이도: ⭐ (쉬움) + +기대 효과: + - 피드백 수집: 100~300건 + - 메뉴 개선 인사이트 + - 재방문 의향: +40% +``` + +--- + +#### 🏪 **오프라인 이벤트** (4가지) + +**7. 매장 내 POP 광고 이벤트** +```yaml +개요: 즉석 할인/1+1 등 매장 내 프로모션 +적합 업종: 전 업종 +적합 계절: 연중 +예산 범위: 2-5만원 +가성비 점수: 15.5 +난이도: ⭐ (쉬움) + +기대 효과: + - 매장 방문 인지: 80% + - 이벤트 참여율: 40% + - 추가 매출: +30~50만원 +``` + +**8. 테이블 텐트 카드** +```yaml +개요: 테이블 위 안내카드로 추가 주문 유도 +적합 업종: 음식점, 카페 +적합 계절: 연중 +예산 범위: 2-3만원 +가성비 점수: 25.25 +난이도: ⭐ (쉬움) + +기대 효과: + - 추가 주문률: +30% + - 세트 메뉴 판매: +50% + - 객단가: +5,000원 +``` + +**9. 명함형 쿠폰 배포** +```yaml +개요: 주변 상가/오피스 쿠폰 배포 +적합 업종: 전 업종 +적합 계절: 연중 +예산 범위: 6-10만원 +가성비 점수: 25.9 +난이도: ⭐ (쉬움) + +기대 효과: + - 쿠폰 사용률: 10~20% + - 신규 고객: +100~200명 + - 재방문율: +60% +``` + +**10. 포토존 운영** +```yaml +개요: 매장 내 포토존 설치 + SNS 연동 +적합 업종: 카페, 일식당, 양식당 +적합 계절: 봄(벚꽃), 여름(시원함), 가을(단풍), 겨울(크리스마스) +예산 범위: 5-30만원 +가성비 점수: 9.5 +난이도: ⭐⭐⭐ (어려움) + +기대 효과: + - SNS 게시물: +150~300건 + - 도달 수: +30,000~80,000명 + - 매장 체류 시간: +30% +``` + +--- + +#### 🎁 **경품 중심 이벤트** (3가지) + +**11. 룰렛/추첨 이벤트** +```yaml +개요: 방문/구매 시 즉석 추첨 +적합 업종: 전 업종 +적합 계절: 연중 +예산 범위: 10-50만원 +가성비 점수: 4.5 +난이도: ⭐⭐ (보통) + +기대 효과: + - 참여율: 80~90% + - 재미 요소로 만족도 상승 + - 재방문 의향: +50% +``` + +**12. 스탬프 적립 이벤트** +```yaml +개요: 방문 횟수별 스탬프 적립 → 보상 +적합 업종: 카페, 한식당, 분식집 +적합 계절: 연중 +예산 범위: 5-20만원 +가성비 점수: 8.9 +난이도: ⭐⭐ (보통) + +기대 효과: + - 재방문율: +90% + - 고객 충성도: +95% + - 장기 매출 안정화 +``` + +**13. 시즌 한정 메뉴 이벤트** +```yaml +개요: 계절별 한정 메뉴 출시 + 특별 혜택 +적합 업종: 카페, 일식당, 양식당 +적합 계절: 봄(벚꽃), 여름(빙수), 가을(단풍), 겨울(크리스마스) +예산 범위: 5-50만원 +가성비 점수: 6.8 +난이도: ⭐⭐⭐ (어려움) + +기대 효과: + - 신메뉴 매출: +35~90% + - SNS 화제성: +250% + - 재방문 유도: +50% +``` + +--- + +### 2.2 목적별 분류 + +| 목적 | 추천 이벤트 | 기대 효과 | +|------|------------|----------| +| 신규고객 유치 | SNS 해시태그, 배달앱 리뷰, 명함 쿠폰 | 신규 유입 +60~80% | +| 재방문 유도 | 스탬프 적립, 생일 쿠폰, 포토존 | 재방문율 +60~90% | +| 매출 증대 | 테이블 텐트, POP 광고, 시즌 메뉴 | 객단가 +20~50% | +| 브랜드 인지도 | SNS 챌린지, 포토존, 인플루언서 협업 | 인지도 +100~200% | + +--- + +## 3. 추천 알고리즘 + +### 3.1 추천 점수 계산식 + +```javascript +추천점수 = (업종_적합도 × 0.3) + + (계절_적합도 × 0.25) + + (가성비_점수 × 0.25) + + (난이도_역수 × 0.1) + + (예산_적합도 × 0.1) + +// 각 요소 점수 범위: 0~10 +``` + +### 3.2 필터링 로직 + +```yaml +1단계: 업종 필터링 + - 매장 업종에 적합한 이벤트만 선별 + - 적합도 7점 이상만 표시 + +2단계: 계절 필터링 + - 현재 계절 또는 선택 계절에 효과적인 이벤트 + - 계절 적합도 6점 이상 + +3단계: 예산 필터링 + - 사용자 입력 예산 범위 내 이벤트 + - ±20% 여유 범위 포함 + +4단계: 정렬 + - 추천점수 높은 순 + - 동점 시 가성비 점수 높은 순 + - 동점 시 난이도 낮은 순 +``` + +### 3.3 예시: 한식당 × 봄 × 30만원 예산 + +```yaml +입력값: + 업종: 한식당 (restaurant_korean) + 계절: 봄 (spring) + 예산: 300,000원 + 목적: 신규고객 유치 + +추천 결과 (Top 5): + +1위: 명함 쿠폰 배포 (추천점수 8.9) + - 업종 적합도: 10 (모든 업종 적합) + - 계절 적합도: 7 (연중 가능) + - 가성비 점수: 25.9 + - 난이도: 1 (쉬움) + - 예산: 65,000원 + +2위: 배달앱 리뷰 이벤트 (추천점수 8.7) + - 업종 적합도: 9 (한식당 적합) + - 계절 적합도: 7 (연중 가능) + - 가성비 점수: 7.4 + - 난이도: 2 (보통) + - 예산: 250,000원 + +3위: 봄나물 특선 메뉴 (추천점수 8.5) + - 업종 적합도: 10 (한식당 매우 적합) + - 계절 적합도: 10 (봄 최적) + - 가성비 점수: 6.8 + - 난이도: 3 (보통) + - 예산: 100,000~300,000원 + +4위: SNS 해시태그 이벤트 (추천점수 8.3) + - 업종 적합도: 7 (한식당 보통) + - 계절 적합도: 9 (봄 벚꽃 시즌 효과) + - 가성비 점수: 17.0 + - 난이도: 1 (쉬움) + - 예산: 50,000원 + +5위: 테이블 텐트 (추천점수 8.1) + - 업종 적합도: 9 (음식점 적합) + - 계절 적합도: 7 (연중 가능) + - 가성비 점수: 25.25 + - 난이도: 1 (쉬움) + - 예산: 20,000원 + +최적 조합 추천: + 1 + 4 + 5 = 135,000원 + 예상 순수익: 3,040,000원 + ROI: 2252% +``` + +--- + +## 4. 업종별 이벤트 매핑 + +### 4.1 한식당 + +**적합도 높음 (9-10점)** +- 명함 쿠폰 배포 +- 배달앱 리뷰 이벤트 +- 테이블 텐트 +- 스탬프 적립 +- 생일 쿠폰 + +**적합도 중간 (6-8점)** +- SNS 해시태그 +- POP 광고 +- 룰렛 이벤트 +- 시즌 메뉴 (명절 특선) + +**적합도 낮음 (1-5점)** +- 포토존 (비주얼 약함) +- 릴스 챌린지 (젊은 층 타겟 아님) + +--- + +### 4.2 중식당 + +**적합도 높음 (9-10점)** +- 배달앱 리뷰 이벤트 (배달 비중 높음) +- 명함 쿠폰 배포 +- 테이블 텐트 (세트 메뉴 홍보) +- POP 광고 (짜장면 데이 등) + +**적합도 중간 (6-8점)** +- SNS 해시태그 +- 룰렛 이벤트 +- 생일 쿠폰 +- 스탬프 적립 + +**적합도 낮음 (1-5점)** +- 포토존 +- 릴스 챌린지 + +--- + +### 4.3 일식당 + +**적합도 높음 (9-10점)** +- SNS 해시태그 (인스타 특화) +- 포토존 (비주얼 중시) +- 릴스 챌린지 (젊은 층) +- 시즌 메뉴 (계절별 특선) +- 네이버 예약 + +**적합도 중간 (6-8점)** +- 배달앱 리뷰 +- 생일 쿠폰 +- 명함 쿠폰 +- 룰렛 이벤트 + +**적합도 낮음 (1-5점)** +- 테이블 텐트 (고급 이미지 저해) + +--- + +### 4.4 양식당 + +**적합도 높음 (9-10점)** +- 포토존 (분위기 중시) +- 네이버 예약 (기념일) +- SNS 해시태그 +- 생일 쿠폰 (감성 마케팅) +- 시즌 메뉴 (크리스마스 등) + +**적합도 중간 (6-8점)** +- 배달앱 리뷰 +- 명함 쿠폰 +- 룰렛 이벤트 +- 알림톡 이벤트 + +**적합도 낮음 (1-5점)** +- 테이블 텐트 +- POP 광고 (고급 이미지 저해) + +--- + +### 4.5 치킨집 + +**적합도 높음 (9-10점)** +- 배달앱 리뷰 (배달 80%) +- 명함 쿠폰 배포 +- SNS 해시태그 (치맥 페스티벌) +- 룰렛 이벤트 +- 시즌 메뉴 (여름 특화) + +**적합도 중간 (6-8점)** +- 테이블 텐트 +- POP 광고 +- 생일 쿠폰 +- 알림톡 이벤트 + +**적합도 낮음 (1-5점)** +- 포토존 +- 네이버 예약 + +--- + +### 4.6 분식집 + +**적합도 높음 (9-10점)** +- 명함 쿠폰 (학생 타겟) +- POP 광고 (1+1) +- 배달앱 리뷰 +- 릴스 챌린지 (먹방) +- 스탬프 적립 + +**적합도 중간 (6-8점)** +- SNS 해시태그 +- 테이블 텐트 +- 룰렛 이벤트 +- 시즌 메뉴 + +**적합도 낮음 (1-5점)** +- 포토존 +- 네이버 예약 + +--- + +### 4.7 카페 + +**적합도 높음 (9-10점)** +- SNS 해시태그 (최고 효과) +- 포토존 (필수) +- 릴스 챌린지 +- 시즌 메뉴 (계절 음료) +- 스탬프 적립 +- 생일 쿠폰 + +**적합도 중간 (6-8점)** +- 명함 쿠폰 +- 테이블 텐트 (굿즈 홍보) +- 룰렛 이벤트 +- 알림톡 이벤트 + +**적합도 낮음 (1-5점)** +- 배달앱 리뷰 (배달 비중 낮음) + +--- + +## 5. 계절별 이벤트 매핑 + +### 5.1 봄 (3-5월) + +**핵심 키워드**: 🌸 벚꽃, 봄나물, 나들이, 신학기 + +**추천 이벤트 Top 5**: +1. **벚꽃 포토존** (카페, 일식당) + - 적합도: 10 + - 예상 효과: SNS 노출 +400% + +2. **봄 시즌 메뉴** (전 업종) + - 적합도: 9 + - 예상 효과: 매출 +35~50% + +3. **SNS 해시태그 (#벚꽃맛집)** (카페, 음식점) + - 적합도: 9 + - 예상 효과: 신규 고객 +70% + +4. **피크닉 세트 메뉴** (한식당, 카페) + - 적합도: 8 + - 예상 효과: 테이크아웃 +60% + +5. **명함 쿠폰** (전 업종) + - 적합도: 7 (연중) + - 예상 효과: 재방문 +60% + +--- + +### 5.2 여름 (6-8월) + +**핵심 키워드**: 🧊 시원함, 휴가, 배달, 치맥 + +**추천 이벤트 Top 5**: +1. **여름 휴가 경품 이벤트** (치킨집, 중식당) + - 적합도: 10 + - 예상 효과: 매출 +70~85% + +2. **빙수 시즌 메뉴** (카페) + - 적합도: 10 + - 예상 효과: 매출 +90% + +3. **배달앱 할인** (전 업종) + - 적합도: 9 + - 예상 효과: 배달 주문 +50% + +4. **치맥 페스티벌** (치킨집) + - 적합도: 10 + - 예상 효과: 매출 +80% + +5. **SNS 챌린지 (#여름시원템)** (카페, 음식점) + - 적합도: 8 + - 예상 효과: 바이럴 +300% + +--- + +### 5.3 가을 (9-11월) + +**핵심 키워드**: 🍁 단풍, 추석, 가을 식재료 + +**추천 이벤트 Top 5**: +1. **추석 특별 메뉴** (한식당) + - 적합도: 10 + - 예상 효과: 매출 +100~120% + +2. **가을 시즌 음료** (카페) + - 적합도: 10 + - 예상 효과: 신메뉴 매출 +55~60% + +3. **단풍 포토존** (카페, 일식당) + - 적합도: 9 + - 예상 효과: SNS +70% + +4. **전통주 페어링 이벤트** (한식당, 양식당) + - 적합도: 8 + - 예상 효과: 객단가 +40% + +5. **배달앱 리뷰** (전 업종) + - 적합도: 7 (연중) + - 예상 효과: 평점 +0.8점 + +--- + +### 5.4 겨울 (12-2월) + +**핵심 키워드**: ❄️ 따뜻함, 크리스마스, 연말, 설날 + +**추천 이벤트 Top 5**: +1. **크리스마스 특별 메뉴** (양식당, 카페) + - 적합도: 10 + - 예상 효과: 매출 +85~110% + +2. **연말 감사 이벤트** (전 업종) + - 적합도: 9 + - 예상 효과: 재방문 +80% + +3. **설날 특선 메뉴** (한식당) + - 적합도: 10 + - 예상 효과: 매출 +100% + +4. **크리스마스 포토존** (카페, 양식당) + - 적합도: 9 + - 예상 효과: SNS +200% + +5. **생일 쿠폰** (전 업종) + - 적합도: 8 (연중) + - 예상 효과: 만족도 +95% + +--- + +## 6. 가성비 점수 시스템 + +### 6.1 가성비 점수 공식 + +```javascript +가성비_점수 = 순수익 / 총비용 + +순수익 = 예상_매출_증가 × (1 - 원가율) - 총비용 +총비용 = 경품비 + 홍보비 + 인건비 + 시스템_비용 +``` + +### 6.2 가성비 등급 + +| 등급 | 점수 범위 | 평가 | 색상 | +|------|----------|------|------| +| S | 20 이상 | 최고 가성비 | 🟣 보라 | +| A | 15~19.9 | 매우 높음 | 🔵 파랑 | +| B | 10~14.9 | 높음 | 🟢 초록 | +| C | 5~9.9 | 보통 | 🟡 노랑 | +| D | 5 미만 | 낮음 | 🔴 빨강 | + +### 6.3 이벤트별 가성비 점수 + +| 순위 | 이벤트명 | 가성비 점수 | 등급 | +|-----|---------|------------|------| +| 1 | 명함 쿠폰 배포 | 25.9 | S | +| 2 | 테이블 텐트 | 25.25 | S | +| 3 | SNS 해시태그 | 17.0 | A | +| 4 | POP 광고 | 15.5 | A | +| 5 | 릴스 챌린지 | 12.5 | B | +| 6 | 포토존 통합 | 11.25 | B | +| 7 | 스탬프 적립 | 8.9 | C | +| 8 | 배달앱 리뷰 | 7.4 | C | +| 9 | 시즌 메뉴 | 6.8 | C | +| 10 | 설문 이벤트 | 6.2 | C | +| 11 | 네이버 예약 | 5.8 | C | +| 12 | 룰렛 이벤트 | 4.5 | D | +| 13 | 생일 쿠폰 | 3.77 | D | + +--- + +## 7. 화면 설계 + +### 7.1 화면 구성 + +```yaml +04-1. AI이벤트유형추천.html (신규): + - 이벤트 유형 카드 리스트 + - 필터 (업종/계절/예산/목적) + - 정렬 (추천순/가성비순/난이도순) + - 상세 보기 모달 + +04-2. 이벤트상세정보.html (신규): + - 이벤트 개요 + - 실행 가이드 + - 비용 구조 + - 예상 효과 + - 성공 사례 + - 체크리스트 + +기존 화면 수정: + 05. AI경품추천.html: + - "이벤트 유형 먼저 선택" 단계 추가 + - 선택한 이벤트 유형에 맞는 경품만 추천 +``` + +### 7.2 사용자 플로우 + +``` +[매장정보 등록] + ↓ +[03. 이벤트 목적 선택] + ↓ +[04-1. AI 이벤트 유형 추천] ← 신규 + ↓ (이벤트 유형 선택) + ↓ +[04-2. 이벤트 상세 정보] ← 신규 + ↓ (이벤트 유형 확정) + ↓ +[05. AI 경품 추천] ← 수정 + ↓ +[06. AI 참여방법 설계] + ↓ +[07. AI 홍보문구 생성] + ... +``` + +### 7.3 UI/UX 가이드 + +**이벤트 카드 디자인**: +```yaml +상단: + - 이벤트 아이콘 (64x64) + - 이벤트명 (h3) + - 가성비 등급 뱃지 (S/A/B/C/D) + +중단: + - 예산 범위 (작은 텍스트) + - 난이도 (⭐ 개수) + - 추천 점수 (진행바) + +하단: + - 기대 효과 요약 (2줄) + - "상세보기" 버튼 +``` + +**필터 섹션**: +```yaml +업종 선택: + - 버튼 그룹 (한식/중식/일식/양식/치킨/분식/카페) + - 자동 선택 (매장정보에서 가져옴) + +계절 선택: + - 라디오 버튼 (봄/여름/가을/겨울) + - 기본값: 현재 계절 + +예산 범위: + - 슬라이더 (0~100만원) + - 또는 입력 필드 + +목적 선택: + - 체크박스 (신규고객/재방문/매출증대/브랜드인지도) + - 복수 선택 가능 +``` + +**정렬 옵션**: +```yaml +- 추천순 (기본) +- 가성비 높은 순 +- 난이도 낮은 순 +- 예산 낮은 순 +``` + +--- + +## 8. 데이터 구조 + +### 8.1 이벤트 유형 데이터 스키마 + +```typescript +interface EventType { + id: string; // 이벤트 유형 ID + name: string; // 이벤트명 + category: 'digital' | 'offline' | 'prize'; // 카테고리 + + // 적합도 + suitability: { + industries: { // 업종별 적합도 (0-10) + restaurant_korean: number; + restaurant_chinese: number; + restaurant_japanese: number; + restaurant_western: number; + restaurant_chicken: number; + restaurant_snack: number; + cafe: number; + }; + seasons: { // 계절별 적합도 (0-10) + spring: number; + summer: number; + fall: number; + winter: number; + }; + purposes: { // 목적별 적합도 (0-10) + new_customer: number; + revisit: number; + sales_increase: number; + brand_awareness: number; + }; + }; + + // 비용 및 효과 + budget: { + min: number; // 최소 예산 + max: number; // 최대 예산 + breakdown: { // 비용 구조 + prize: number; + promotion: number; + labor: number; + system: number; + }; + }; + + performance: { + expectedRevenue: number; // 예상 매출 증가 + netProfit: number; // 순수익 + costEfficiency: number; // 가성비 점수 + roi: number; // ROI (%) + }; + + // 실행 정보 + difficulty: 1 | 2 | 3; // 난이도 (1: 쉬움, 2: 보통, 3: 어려움) + duration: number; // 실행 기간 (일) + + // 상세 정보 + description: string; // 설명 + executionSteps: string[]; // 실행 단계 + checklist: string[]; // 체크리스트 + successCases: SuccessCase[]; // 성공 사례 + + // 메타 정보 + tags: string[]; // 태그 + relatedEvents: string[]; // 관련 이벤트 ID +} + +interface SuccessCase { + industry: string; // 업종 + location: string; // 지역 + season: string; // 계절 + budget: number; // 투입 예산 + result: { + revenue: number; // 매출 증가 + roi: number; // ROI + newCustomers: number; // 신규 고객 수 + description: string; // 성과 설명 + }; +} +``` + +### 8.2 추천 요청/응답 API + +```typescript +// 요청 +interface EventRecommendationRequest { + storeInfo: { + industry: string; // 업종 + location: string; // 지역 + }; + seasonInfo: { + season: 'spring' | 'summer' | 'fall' | 'winter'; + }; + budget: { + min: number; + max: number; + }; + purposes: string[]; // 목적 (복수 선택) + sortBy?: 'recommendation' | 'costEfficiency' | 'difficulty' | 'budget'; +} + +// 응답 +interface EventRecommendationResponse { + recommendations: EventRecommendation[]; + optimalCombination?: EventCombination; // 최적 조합 +} + +interface EventRecommendation { + eventType: EventType; + recommendationScore: number; // 추천 점수 (0-10) + reasonScores: { // 추천 이유별 점수 + industrySuitability: number; + seasonSuitability: number; + costEfficiency: number; + budgetFit: number; + difficulty: number; + }; + customizedData: { // 맞춤 데이터 + estimatedBudget: number; // 이 매장 기준 예산 + estimatedRevenue: number; // 이 매장 기준 예상 매출 + estimatedProfit: number; // 이 매장 기준 순수익 + estimatedROI: number; // 이 매장 기준 ROI + }; +} + +interface EventCombination { + events: string[]; // 이벤트 ID 배열 + totalBudget: number; + totalProfit: number; + totalROI: number; + synergy: string; // 시너지 설명 +} +``` + +--- + +## 9. 구현 우선순위 + +### Phase 1: 기본 추천 (2주) +- [ ] 13가지 이벤트 유형 데이터 입력 +- [ ] 업종별 적합도 매핑 +- [ ] 계절별 적합도 매핑 +- [ ] 04-1. AI이벤트유형추천 화면 구현 +- [ ] 기본 추천 알고리즘 구현 + +### Phase 2: 상세 정보 (1주) +- [ ] 04-2. 이벤트상세정보 화면 구현 +- [ ] 실행 가이드 콘텐츠 작성 +- [ ] 성공 사례 DB 구축 +- [ ] 체크리스트 템플릿 작성 + +### Phase 3: 고도화 (2주) +- [ ] 최적 조합 추천 기능 +- [ ] 예산 시뮬레이션 기능 +- [ ] ROI 계산기 +- [ ] AI 기반 맞춤 추천 (Claude API) + +### Phase 4: 통합 (1주) +- [ ] 05. AI경품추천 화면 수정 +- [ ] 전체 플로우 연동 +- [ ] 사용자 테스트 및 피드백 반영 + +--- + +## 10. 참고 자료 + +- [design/트렌드분석.md](./트렌드분석.md) - 업종/계절별 트렌드 데이터 +- [design/userstory.md](./userstory.md) - 유저스토리 UFR-PLAN-020 +- 실전 이벤트 실행 가이드 (트렌드분석 섹션 10) +- 가성비 이벤트 전략 (트렌드분석 섹션 11) + +--- + +**작성자**: 플랫폼 기획자 Flynn +**검토자**: 서비스 기획자 도그냥, 아키텍트 박영자 +**최종 수정일**: 2025년 1월 +**버전**: 1.0