[4주차 크루 미션 - 최종 발표 & 회고] ellipsis 미션 제출합니다.

.gitignore

@@ -1,4 +1,7 @@
 .DS_Store
+__pycache__/
+*.py[cod]
+.venv/
 
 # Local scratch files created during setup.
 /android-mini-projects/

AGENTS.md

@@ -50,39 +50,57 @@ cd impl && python3 crawl.py
 cd keybuddy/frontend && npm run sync:data   # output/keyboards.json -> 프론트 + Edge Function 사본
 ```
 
-## 아키텍처: 두 개의 추천 경로
+## 아키텍처: 추천 경로 (현행 + 레거시)
 
-keybuddy의 핵심은 **추천 엔진이 두 갈래로 존재**한다는 점이다. 혼동하지 말 것.
+> **2026-06 갱신**: 결정론 의도 하네스가 UI에 배선됐다. 현행 프로덕션은 "Edge Function 태그추출(OpenAI) + 클라이언트 결정론 검색" 하이브리드이고, 과거의 "Edge Function 전체 추천 생성"과 "클라이언트 claude 태그추출"은 코드만 남은 레거시다. 혼동하지 말 것.
 
-1. **현재 UI에 연결된 경로 (production)**: `App.tsx` → `lib/recommend.ts`(HTTP fetch) → Supabase Edge Function `recommend/index.ts`. Edge Function이 키워드 스코어링(`scoreKeyboard`)으로 후보를 40개 이하로 압축한 뒤 **OpenAI**(`gpt-5.4`)에 넘겨 추천 사유를 생성한다. `OPENAI_API_KEY`는 브라우저에 절대 내려가지 않고 Supabase secret에만 존재한다 (`recommend.ts`는 `apikey` 헤더만 보냄).
+**현행 프로덕션 경로 (UI 연결)**: `App.tsx` → `lib/recommend.ts`
 
-2. **결정론적 의도 하네스 (lib/, 테스트로만 검증됨 - 아직 UI 미연결)**: `extractRawTags.ts`(유일한 LLM 호출, `claude-sonnet-4-6`로 자연어→의도+명시제약 번역) → `intentProfile.ts`(의도를 차원별 태그로 정적 확장) → `intentSearch.ts`/`searchEngine.ts`(하드필터 + 소프트 스코어링 + 무결과 시 제약 완화). 설계 의도는 `docs/tag-extraction-flow.md` 참고. **"LLM은 번역만, 태그 확장·검색은 전부 결정론"**이 핵심 불변식이며, 같은 입력→같은 출력을 보장한다.
+- **freeform(자연어)**: `recommend.ts`가 `{mode:'extract'}`로 Edge Function `recommend/index.ts`를 호출하면, Edge Function이 **OpenAI**(`gpt-5.4`, `OPENAI_MODEL`로 override)로 자연어를 `{intents, hardConstraints, softIntentTags}`로 **태그추출만** 한다. 이후 클라이언트가 `expandIntents`(intentProfile) → `searchWithProfile`(intentSearch)로 **결정론 검색**하고 점수순 상위 3개로 압축한다.
+- **guided(단계선택)**: 네트워크 0회. `selectionOptionConverter`가 답변을 태그로 변환한 뒤 위와 동일한 결정론 검색을 탄다.
+- `OPENAI_API_KEY`는 브라우저에 절대 내려가지 않고 Supabase secret에만 존재한다(`recommend.ts`는 `apikey` 헤더만 보냄). 양쪽 모두 **"LLM은 번역(또는 0회)만, 태그 확장·검색·랭킹은 전부 결정론"**이라는 불변식을 지켜 같은 입력→같은 출력을 보장한다.
 
-`docs/tag-extraction-flow.md`는 경로 2를 "현재 흐름"으로 서술하지만 실제 `recommend.ts`는 경로 1(Edge Function)을 호출한다. 경로 2는 구축·테스트 완료됐으나 아직 `recommend.ts`에 배선되지 않았다 - 이 갭이 TODO의 "키보드 에이전트 직접 설계" 작업 대상이다.
+**레거시 (코드만 존재, 현 UI 미사용)**:
 
-### lib/ 파이프라인 핵심 모듈 (경로 2)
+- Edge Function 전체 추천 생성 모드: `scoreKeyboard`로 후보를 압축한 뒤 `gpt-5.4`가 후보 중 직접 선택·사유 생성 → `composeRecommendations`. `index.ts`에 남아있으나 현재 UI는 호출하지 않는다(해당 분기 주석 "현재 UI는 미사용" 참조).
+- 클라이언트 `extractRawTags.ts`의 LLM 호출(`claude-sonnet-4-6`, `dangerouslyAllowBrowser`). 프로덕션 추출은 Edge Function extract(OpenAI)가 담당하므로 이 함수들은 현재 직접 호출되지 않는다(타입·테스트용).
 
-- `extractRawTags.ts` - 자연어 → `ExtractedTags { hardConstraints, softIntentTags }` (LLM 1회)
+`docs/tag-extraction-flow.md`는 이 결정론 하네스의 설계를 서술한다(문서는 클라이언트 claude 추출 기준으로 작성됐고, 실제 프로덕션 추출은 Edge Function의 OpenAI extract가 대체한다). 과거 이 문서가 가리키던 "미연결" 갭은 해소됐다.
+
+### lib/ 결정론 파이프라인 핵심 모듈 (현행 검색 경로)
+
+- `extractRawTags.ts` - 태그 정제(`sanitizeTags`)와 타입 정의. 브라우저 LLM 추출 함수(`extractRawTags`/`extractIntentInput`, `claude-sonnet-4-6`)도 있으나 현행 프로덕션은 Edge Function extract를 쓰므로 미사용(테스트용)
 - `tagSchema.ts` - 소프트 의도 태그 어휘(controlled vocabulary)와 검증
 - `softTagRules.ts` - 소프트 태그 → 키보드 매칭 술어(규칙 맵)
 - `intentProfile.ts` - 고수준 의도(사무용/게이밍/휴대용)를 차원별 요구로 확장. 강도는 `필수`(하드 승격)/`선호`(소프트 점수)/`상관없음`. 명시 제약이 의도보다 우선.
 - `hardFilter.ts` - 하드 제약 위반 키보드 제외 (위반 0건 보장)
 - `softScorer.ts` - 소프트 태그 매칭 점수 → 랭킹
 - `searchEngine.ts`/`intentSearch.ts` - 무결과 시 제약을 우선순위 역순으로 1개씩 완화 후 재검색(`HARD_CONSTRAINT_RELAXATION_ORDER`). `searchKeyboards`는 LEGACY, `searchWithProfile`이 신규 진입점.
 
+### 이벤트 수집 (구매 클릭 / 추천 별점)
+
+추천 가설 검증용 데이터를 모으기 위해 두 가지 사용자 행동을 Supabase에 적재한다(커머스 아님, 실결제 없음).
+
+- `lib/session.ts` - 로그인 없는 익명 세션 식별자(localStorage UUID). 추천 -> 구매 클릭 -> 별점 흐름을 느슨하게 묶는다. PII 아님.
+- `lib/events.ts` - `purchase_click`('구매하기' 버튼 클릭, payload `{product_code}`)과 `rating`(추천 전체 별점, payload `{rating}`)을 anon key로 PostgREST `/rest/v1/events`에 직접 insert. **best-effort**라 설정 누락/네트워크 실패는 삼키고 `false`만 반환해 UX를 막지 않는다.
+- 스키마: `supabase/migrations/20260617000000_create_events.sql` - 단일 `events`(id, event_type, session_id, payload jsonb, created_at) + **insert-only RLS**(anon은 insert만, select/update/delete는 정책 부재로 기본 거부).
+- 검증: `__tests__/events.test.ts`가 payload 형태와 PostgREST 요청/실패 동작을 단위검증. 실제 적재는 라이브 Supabase에서 수동 확인(아래 README 참고).
+
 ## 데이터 파이프라인
 
 `crawl.py`는 다나와 **목록 페이지만** 조회한다(상세 페이지 요청 안 함, `DELAY_SEC` 레이트리밋 준수). 한 상품에 스위치 옵션이 여럿이면 제품-스위치 조합별 레코드로 펼치고 최종 **600개**로 제한(`TARGET_RECORDS`). 스위치 이름은 `src/data/switch_aliases.json` 규칙으로만 매칭하고, 매칭 실패는 추론하지 않고 `output/unmatched_switches.json`에 격리한다.
 
 카탈로그 `keyboards.json`은 **두 군데에 사본**으로 존재한다(프론트 표시용 + Edge Function 후보용). 반드시 `npm run sync:data`로 함께 갱신해야 둘이 엇갈리지 않는다.
 
+YouTube 타건 영상 링크는 공식 YouTube Data API로만 수집한다(YouTube HTML 검색/스크래핑 우회 금지). `impl/output/youtube_media_cache.json`은 누적 캐시이며, 다음 크롤링 때 캐시를 먼저 입히고 캐시 미스만 새로 검색한다. `keyboards.json`에는 영상 메타데이터 전체를 넣지 않고 `media_url`, `media_url_is_placeholder`만 반영한다. 제목·점수·채널 등 감사 정보는 `youtube_media_cache.json`/`youtube_media_report.json`에 둔다.
+
 ## 버전 관리
 
 앱 버전의 단일 소스는 `frontend/package.json`의 `version`이다. `npm run build`/`deploy:function`이 `sync:function-version`으로 이 값을 Edge Function의 `version.ts`에 주입하며, Edge Function은 `GET /recommend`, 응답 `meta.version`, `X-Keybuddy-Version` 헤더로 노출한다. 배포 전 `npm version patch|minor|major --no-git-tag-version`으로 SemVer 증가.
 
 ## 테스트 규약
 
-`src/__tests__/`에 36개 vitest 스위트가 있다. 특징적인 패턴:
+`src/__tests__/`에 40개 vitest 스위트가 있다. 특징적인 패턴:
 
 - **`*LlmNoCall.test.ts`** - 결정론 경로가 실제로 LLM을 호출하지 않음을 강제하는 불변식 테스트. lib/ 검색 로직 수정 시 이 보증을 깨지 말 것.
 - **`*.goldset.test.ts`** - 정답셋 기반 정확도 회귀 테스트(하드제약/소프트의도 정확도).

docs/youtube-media-enrichment.md

@@ -0,0 +1,156 @@
+# YouTube 타건 영상 링크 보강
+
+이 문서는 다나와 키보드 목록 크롤러가 수집한 제품-스위치 레코드에 YouTube 타건 영상
+링크를 보강하는 설계와 운영 규칙을 정리한다.
+
+## 원칙
+
+- YouTube 링크는 공식 YouTube Data API로만 수집한다.
+- YouTube 검색 HTML을 직접 파싱하거나 스크래핑으로 쿼터를 우회하지 않는다.
+- 다나와 크롤링은 기존처럼 목록 페이지만 조회한다. YouTube 보강은 다나와 수집 이후의
+  별도 enrichment 단계다.
+- `keyboards.json`에는 재생에 필요한 최소 필드만 넣는다.
+
+## 데이터 계약
+
+`impl/output/keyboards.json`의 각 레코드에는 기존 UI 계약을 유지해 아래 필드만 반영한다.
+
+```json
+{
+  "media_url": "https://www.youtube.com/watch?v=VIDEO_ID",
+  "media_url_is_placeholder": false
+}
+```
+
+링크를 찾지 못했거나 아직 검색하지 않은 경우:
+
+```json
+{
+  "media_url": null,
+  "media_url_is_placeholder": true
+}
+```
+
+영상 제목, 채널명, 점수, 검색어, 실패 이유 같은 감사 정보는 `keyboards.json`에 넣지
+않고 별도 파일에 둔다.
+
+## 파일 역할
+
+- `impl/output/youtube_media_cache.json`: 누적 캐시. 다음 실행에서 먼저 읽어
+  `keyboards.json`에 다시 반영한다.
+- `impl/output/youtube_media_report.json`: 최근 실행 리포트. 성공, 실패, 스킵, 쿼터 제한,
+  오류를 확인한다.
+- `impl/output/keyboards.json`: 앱이 사용할 원본 카탈로그. YouTube 보강 후 저장된다.
+- `impl/keybuddy/frontend/src/data/keyboards.json`: 프론트 표시용 사본.
+- `impl/keybuddy/supabase/functions/recommend/keyboards.json`: Edge Function 추천 후보용 사본.
+
+## 검색 키
+
+검색어는 제품명과 스위치명을 조합한다.
+
+```text
+상품명 + raw_switch_name
+```
+
+`raw_switch_name`이 없으면 `switch_name`을 사용한다. 둘 다 없으면 YouTube 검색을 건너뛰고
+placeholder 상태를 유지한다.
+
+캐시 키는 `product_code`가 있으면 우선 사용한다.
+
+```text
+product_code:<product_code>::switch:<switch_label>
+```
+
+`product_code`가 없을 때만 정규화된 `product_name + switch_label`로 fallback한다.
+
+## 실행
+
+기본 크롤링은 YouTube API를 호출하지 않는다.
+
+```bash
+cd impl
+python3 crawl.py
+```
+
+YouTube 링크를 새로 수집하려면 API 키와 limit을 지정한다.
+
+```bash
+cd impl
+YOUTUBE_API_KEY=<key> python3 crawl.py --with-youtube --youtube-limit 90
+```
+
+새 검색 없이 기존 캐시만 현재 `keyboards.json`에 다시 입히려면:
+
+```bash
+cd impl
+python3 crawl.py --with-youtube --youtube-limit 0
+```
+
+기존 캐시를 무시하고 다시 검색하려면:
+
+```bash
+cd impl
+YOUTUBE_API_KEY=<key> python3 crawl.py --with-youtube --youtube-refresh --youtube-limit 90
+```
+
+## 이어서 수집되는 방식
+
+매 실행은 다음 순서로 동작한다.
+
+1. 다나와 목록에서 새 `collected` 레코드를 만든다.
+2. `youtube_media_cache.json`을 읽는다.
+3. 캐시에 있는 항목은 API 호출 없이 `media_url`을 바로 반영한다.
+4. 캐시에 없는 항목만 `--youtube-limit` 범위 안에서 새로 검색한다.
+5. 새 검색 결과를 캐시에 추가한다.
+6. 캐시 반영분과 새 수집분이 합쳐진 상태로 `impl/output/keyboards.json`을 저장한다.
+
+즉 `keyboards.json`을 이어붙이는 방식이 아니라, 매번 새 다나와 결과에 누적 캐시를 다시
+입히는 방식이다. 다나와 상품명이나 옵션명이 바뀌어도 `product_code` 기반 캐시 키가
+있으면 기존 링크를 재사용할 수 있다.
+
+## 동기화
+
+`impl/output/keyboards.json`을 갱신한 뒤에는 반드시 프론트와 Edge Function 사본을 함께
+동기화한다.
+
+```bash
+cd impl/keybuddy/frontend
+npm run sync:data
+```
+
+이 명령은 아래 두 파일을 함께 갱신한다.
+
+```text
+src/data/keyboards.json
+../supabase/functions/recommend/keyboards.json
+```
+
+둘 중 하나만 갱신하면 프론트 표시와 추천 후보 데이터가 어긋날 수 있다.
+
+## 검증
+
+최소 검증:
+
+```bash
+impl/.venv/bin/python -m unittest discover -s impl -p 'test*.py'
+```
+
+데이터 동기화 확인:
+
+```bash
+cmp -s impl/output/keyboards.json impl/keybuddy/frontend/src/data/keyboards.json
+cmp -s impl/output/keyboards.json impl/keybuddy/supabase/functions/recommend/keyboards.json
+```
+
+UI 검증:
+
+- `media_url`이 있는 추천 카드에서 영상 버튼이 표시되는지 확인한다.
+- 버튼 클릭 시 새 탭에서 YouTube 영상 페이지가 열리는지 확인한다.
+- `media_url`이 없는 항목은 준비 중 상태로 표시되는지 확인한다.
+
+## 주의
+
+- API 키는 문서, 커밋, 프론트 `.env.local`에 남기지 않는다.
+- `YOUTUBE_API_KEY`는 크롤러 실행 환경 변수로만 주입한다.
+- YouTube API 쿼터를 고려해 기본 운영 limit은 하루 90건 정도로 둔다.
+- 403 오류가 나면 쿼터 초과나 API key 제한 설정을 먼저 확인한다.

impl/crawl.py

@@ -5,8 +5,10 @@
 제품-스위치 조합별 레코드로 펼쳐 JSON과 CSV에 저장한다.
 """
 
+import argparse
 import csv
 import json
+import os
 import re
 import time
 from collections import defaultdict
@@ -16,6 +18,11 @@
 import requests
 from bs4 import BeautifulSoup
 
+try:
+    from .youtube_media import enrich_items_with_youtube
+except ImportError:
+    from youtube_media import enrich_items_with_youtube
+
 LIST_URL = "https://prod.danawa.com/list/"
 LIST_AJAX_URL = "https://prod.danawa.com/list/ajax/getProductList.ajax.php"
 CATEGORY_CODE = "112782"
@@ -28,6 +35,8 @@
 SWITCH_DATA_DIR = BASE_DIR / "keybuddy" / "frontend" / "src" / "data"
 SWITCHES_PATH = SWITCH_DATA_DIR / "switches.json"
 SWITCH_ALIASES_PATH = SWITCH_DATA_DIR / "switch_aliases.json"
+YOUTUBE_CACHE_PATH = OUTPUT_DIR / "youtube_media_cache.json"
+YOUTUBE_REPORT_PATH = OUTPUT_DIR / "youtube_media_report.json"
 
 # 기존 데이터셋의 완전성 기준은 유지한다. 새 스위치 필드는 결측을 허용한다.
 REQUIRED_FIELDS = (
@@ -636,8 +645,47 @@ def save_results(collected: list[dict]) -> None:
     print(f"미매칭 스위치: {unmatched_path} ({len(unmatched)}종)")
 
 
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="다나와 키보드 목록 크롤러")
+    parser.add_argument(
+        "--with-youtube",
+        action="store_true",
+        help="공식 YouTube Data API로 타건 영상 링크를 보강합니다.",
+    )
+    parser.add_argument(
+        "--youtube-limit",
+        type=int,
+        default=90,
+        help="이번 실행에서 새로 검색할 YouTube query 수입니다. 캐시 hit는 제외합니다.",
+    )
+    parser.add_argument(
+        "--youtube-refresh",
+        action="store_true",
+        help="기존 YouTube cache를 무시하고 새로 검색합니다.",
+    )
+    parser.add_argument(
+        "--youtube-cache-path",
+        type=Path,
+        default=YOUTUBE_CACHE_PATH,
+        help="YouTube 검색 결과 cache JSON 경로입니다.",
+    )
+    parser.add_argument(
+        "--youtube-report-path",
+        type=Path,
+        default=YOUTUBE_REPORT_PATH,
+        help="YouTube 검색 리포트 JSON 경로입니다.",
+    )
+    return parser.parse_args()
+
+
 def main():
+    args = parse_args()
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    youtube_limit = max(0, args.youtube_limit)
+    youtube_api_key = os.environ.get("YOUTUBE_API_KEY", "").strip()
+    if args.with_youtube and youtube_limit > 0 and not youtube_api_key:
+        raise SystemExit("YOUTUBE_API_KEY 환경변수가 필요합니다.")
+
     switches, aliases = load_switch_data()
 
     collected = []
@@ -696,6 +744,26 @@ def main():
             page += 1
             time.sleep(DELAY_SEC)
 
+    if args.with_youtube:
+        youtube_stats = enrich_items_with_youtube(
+            collected,
+            api_key=youtube_api_key,
+            cache_path=args.youtube_cache_path,
+            report_path=args.youtube_report_path,
+            search_limit=youtube_limit,
+            refresh=args.youtube_refresh,
+        )
+        print(
+            "YouTube 보강: "
+            f"cache {youtube_stats['cache_hits']}, "
+            f"검색 {youtube_stats['api_searches']}, "
+            f"매칭 {youtube_stats['matched']}, "
+            f"미발견 {youtube_stats['not_found']}, "
+            f"스킵 {youtube_stats['skipped']}, "
+            f"제한 {youtube_stats['limited']}, "
+            f"오류 {youtube_stats['errors']}"
+        )
+
     save_results(collected)
     print(f"\n상품 {product_count}개에서 제품-스위치 조합 {len(collected)}개 수집 완료")
 

impl/keybuddy/README.md

@@ -34,6 +34,7 @@ keybuddy/
 - `docs/tag-extraction-flow.md` - 자연어를 의도/제약 태그로 번역하고 결정론적으로 확장하는 흐름
 - `docs/intent-harness-before-after.md` - 의도 하네스 적용 전/후 정성 비교
 - `docs/deployment-version-management.md` - 배포 및 버전 관리 규칙
+- `docs/youtube-media-enrichment.md` - YouTube 타건 영상 링크 수집·캐시·동기화 운영 규칙
 
 ## 크롤링 데이터와 스위치 매칭
 
@@ -58,6 +59,19 @@ keybuddy/
 `null`로 저장합니다. `media_url`은 실제 자료를 확보하기 전까지 `null`로 저장하고
 `media_url_is_placeholder`로 준비 중 상태를 표시합니다.
 
+타건 영상 링크는 기본 크롤링에는 포함하지 않고, 공식 YouTube Data API 키가 있을 때만
+선택적으로 보강합니다. 검색어는 `상품명 + raw_switch_name`(없으면 `switch_name`)이며,
+결과는 `../output/youtube_media_cache.json`에 누적합니다. 다음 실행에서는 캐시를 먼저
+입혀 이미 수집한 링크를 `keyboards.json`에 다시 반영하고, 캐시에 없는 항목만 새로
+검색합니다.
+
+```bash
+cd impl
+YOUTUBE_API_KEY=<key> python3 crawl.py --with-youtube --youtube-limit 90
+```
+
+`--youtube-limit 0`은 새 검색 없이 기존 캐시만 반영할 때 사용합니다.
+
 ## 요청 흐름
 
 ```text
@@ -193,6 +207,33 @@ VITE_SUPABASE_URL=https://your-project-ref.supabase.co
 VITE_SUPABASE_ANON_KEY=your-supabase-publishable-key
 ```
 
+#### 이벤트 수집 테이블 적용
+
+구매 클릭/추천 별점을 수집하려면 `events` 테이블 마이그레이션을 한 번 적용해야 합니다.
+(같은 `VITE_SUPABASE_URL`/`VITE_SUPABASE_ANON_KEY`를 쓰는 프론트가 PostgREST로 직접 insert 합니다.)
+
+```bash
+cd impl/keybuddy
+supabase db push --project-ref your-project-ref
+```
+
+CLI를 쓰지 않는다면 Supabase 대시보드 SQL Editor에
+`supabase/migrations/20260617000000_create_events.sql` 내용을 붙여 실행해도 됩니다.
+이 마이그레이션은 anon에게 **insert만** 허용하는 RLS를 걸어, 이벤트는 적재만 되고
+브라우저로 다시 조회되지 않습니다.
+별점 이벤트는 한 추천 결과 화면에서 최초 1회만 적재하며, DB 정책에서도 `rating`
+payload가 `0.5` 이상 `5.0` 이하인 숫자인 경우만 허용합니다.
+
+**수동 적재 확인**: 프론트에서 추천을 받은 뒤 ① '구매하기' 버튼 클릭 ② 별점 클릭을 하고,
+대시보드 SQL Editor에서 다음으로 행이 쌓였는지 확인합니다.
+
+```sql
+select event_type, session_id, payload, created_at
+from public.events
+order by created_at desc
+limit 10;
+```
+
 ## 로컬 실행
 
 프론트: