---
task_id: task-3057
scope: task
team: dev3-team
level: Lv.2
status: PR_OPEN
repo: Jeon-Jonghyuk/InsuRo
pr: 270
branch: task-3057-cafe-oneclick
base: 0ff78ce938724f90746e9ffe8936dacbab874196
head: daeab93c02a216a7f90a09eee9231f2f14e2eea9
date: 2026-08-29
---

# task-3057 — 정보성 키워드 → 카페 1위분석 원클릭 배선

## ★ 봉투 (한 줄 결론)
**원클릭으로 카페탭 최종 결과 화면까지 도달 O · 자동실행 호출 정확히 1회**
(도착 시 1회 / 3초 대기 + 리사이즈 재렌더 후에도 1회 / 직접 진입 시 0회 — 라우트 카운터 실측)

PR **#270 (draft)** — https://github.com/Jeon-Jonghyuk/InsuRo/pull/270
머지·배포는 ANU 판단. 자동 머지 안 함.

---

## 1. ★ ANU 명세 전제 반증 3건

명세는 "재조사 불필요, 그대로 전제하라"고 했으나 **3건이 사실과 달랐다.** 구현 전에 확인해서 반영했다.

### ① 명세가 지목한 좌표는 "가짜 행"이었다
명세: `InfoKeyword.tsx:158~163` 의 Badge 왼쪽에 버튼.
실제: 그 위치는 **비-맥스 사용자용 블러 미리보기** `SAMPLE_RESULTS` 다.
```
aria-hidden="true" · pointer-events-none · filter: blur(5px)
```
→ 명세대로 넣었으면 **클릭 불가능한 하드코딩 샘플 행**에 버튼이 붙고, 실제 결과에는 안 붙는다.
→ 진짜 결과 Badge 는 `ResultCard` 컴포넌트 안에 있다. **여기에 구현했다.**

### ② 결과 렌더 지점은 두 곳이다
`ResultCard` 는 **결과탭**(`results.map`)과 **히스토리탭**(`selectedHistory.results.map`) 양쪽에서 쓰인다.
`ResultCard` 안에 구현했으므로 두 곳이 동시에 covered 된다. (한 곳만 고쳤으면 히스토리탭이 누락됐다)

또한 InfoKeyword 화면 자체가 **두 경로**에 존재한다 — `/info-keyword` 라우트 + `/keyword-analysis?tab=info-keyword` 탭.

### ③ 탭은 비제어라 URL 만으로는 전환되지 않았다
`KeywordAnalysis.tsx:256` 은 `<Tabs defaultValue={defaultTab}>` — **비제어(uncontrolled)**.
`defaultValue` 는 마운트 시점에만 적용된다. 이미 `?tab=info-keyword` 에 있는 상태에서 URL 만 `?tab=blog-rank` 로 바꿔도 **탭이 안 바뀐다.**
→ 제어 컴포넌트(`value` + `onValueChange`)로 전환. 기본값 `"volume"` 유지, 수동 탭 클릭 동작 보존(URL 을 되쓰지 않음).

---

## 2. 구현 (커밋 5개, 단계별)

| 커밋(원격) | 파일 | 내용 |
|---|---|---|
| `09bff29` | `InfoKeyword.tsx` + 신규 테스트 | ① `ResultCard` 에 `카페 1위분석` 버튼 — `isInfo === true` 일 때만 |
| `6c1cf40` | `KeywordAnalysis.tsx`, `NaverBenchmarkPanel.tsx` | ② `tab`/`channel`/`keyword` 파라미터 수용·전달 + Tabs 제어화 |
| `ade8cab` | `NaverBenchmarkPanel.tsx` + 신규 테스트 | ③ 자동 1회 실행 + 실패 인라인 배너 |
| `b5ecc45` | `NaverBenchmarkPanel.tsx` | ④ 무료 플랜 잠금 분기 자동실행 차단 |
| `daeab93` | `InfoKeyword.tsx` | ⑤ 모바일 375px 키워드 잘림 수정 |

**URL 계약**: `/keyword-analysis?tab=blog-rank&channel=cafe&keyword=<encodeURIComponent(키워드)>`
파라미터명은 기존 `tab` 컨벤션과 동일한 소문자 단어로 통일.

**자동 1회 보장 방식** — `useEffect` 의존성은 `autoRunToken` 문자열 **하나뿐**이고, `runAnalysis` 는 `useRef` 로 최신값을 잡는다.
의존성에 `runAnalysis` 를 넣으면 `keyword`/`channel`/`toast` 변경마다 재생성되어 **무한 호출**된다 — 그래서 넣지 않았다.
소비한 토큰은 `consumedTokenRef` 에 기록해 같은 토큰으로 재실행되지 않게 했다.

**기존 동작 보존** — 외부값이 없으면 `initialChannel ?? "blog"`, `initialKeyword ?? ""`, `autoRunToken === undefined` → 자동실행 없음.
주입값은 `useState` **초기값**일 뿐이라 도착 후 사용자가 채널·키워드를 자유롭게 바꿀 수 있다(props 로 state 를 덮어쓰지 않음).

---

## 3. ★ 구현 중 발견한 실제 결함 2건 (명세 밖 — 수정함)

### 결함 A — 무료 플랜 잠금 화면 뒤에서 자동실행이 나갔다
`LockedFeatureOverlay` 는 children 을 **안 그리는 게 아니라** `blur(4px)` + `pointer-events-none` + `aria-hidden` 으로 **실제 마운트**한다.
그래서 무료 사용자가 파라미터 URL 로 진입하면 잠금 화면 뒤에서 analyze 호출이 1회 나갔다(서버 403).
→ 잠금 분기에서 `autoRunToken` 만 제거. `initialChannel`/`initialKeyword` 는 유지(입력칸에 값만 채워지고 실행 안 됨).
→ **"사용 횟수 로직"이 아니라 자동실행 범위 문제**이므로 명세의 금지사항에 저촉되지 않는다.

### 결함 B — 모바일 375px 에서 키워드가 잘렸다
버튼 `shrink-0` + 키워드 `truncate` 조합으로 키워드가 **50px 까지 압축**되어 `대장…` `종신…` `어린…` 로만 보였다.
사용자가 **어느 키워드의 버튼인지 식별 불가**한 상태였다.

| 키워드 | 버튼 | 수정 전 (scroll/client) | 수정 후 |
|---|---|---|---|
| 대장암 초기증상 | 있음 | 113 / **50** 잘림 | 113 / **113** 정상 |
| 실손보험 비교 | 없음 | 97 / 97 | 97 / 97 |
| 종신보험 가격 | 있음 | 97 / **50** 잘림 | 97 / **97** 정상 |
| 보험 리모델링 | 없음 | 97 / 97 | 97 / 97 |
| 어린이보험 추천 | 있음 | 113 / **50** 잘림 | 113 / **113** 정상 |

★ 잘림이 **버튼 있는 행에서만** 발생 → 인과 실측 확정. 가로 오버플로·줄바꿈은 없었다(375/375).
→ `flex-wrap` + 왼쪽 최소폭(`min-w-[10rem] basis-[10rem] grow`)으로 좁은 폭에서 [버튼][배지]를 다음 줄로 내렸다. **버튼이 배지 왼쪽이라는 순서는 유지.**
→ 데스크톱 1440px 은 수정 전후 스크린샷 **md5 동일**(`be50bbe2a8757fd526b116bb5d6ebbff`) — 픽셀 단위 무변경.

---

## 4. 회귀 — ★ base/head 동일 환경 재측정

같은 워크트리·같은 node_modules·`.env` 없음 조건으로 양쪽을 쟀다.

| | Test Files | Tests |
|---|---|---|
| base `0ff78ce` | 111 passed | **1677 passed / 0 failed** |
| head `daeab93` | 113 passed | **1687 passed / 0 failed** |

**델타 +10** = 신규 봉인 테스트 10건. **회귀 0.** `npx tsc --noEmit` exit 0.

### ★ 가짜 회귀 1건을 걸러냈다
E2E 실행을 위해 워크트리에 `.env` 를 복사하면 `src/lib/__tests__/push-utils.test.ts` 1건이 실패한다.
**base 에서도 `.env` 를 넣으면 동일하게 1 failed** 임을 확인했다(base 1676/1677, head 1686/1687).
→ 환경 조건부 실패이지 본 변경의 회귀가 아니다. 위 표는 양쪽 모두 `.env` 없는 조건의 숫자다.
→ 교훈: 워크트리 `.env` 유무가 테스트 결과를 바꾼다. base/head 를 **같은 `.env` 조건**에서 재야 한다.

---

## 5. 봉인 변이 (전부 no-op 아님 확인 후 복원)

| 변이 | 결과 |
|---|---|
| 채널 기본값을 `blog` 로 회귀 | **2 failed** / 19 passed |
| 비정보성 행에도 버튼 노출 | **2 failed** / 19 passed (버튼 3개→5개) |
| 자동실행 `useEffect` 제거 | **5 failed** / 19 passed |
| 무료 분기에 `autoRunToken` 재전달 | **1 failed** / 6 passed |

"자동실행 제거" 변이에서 "props 없으면 fetch 0회" 테스트는 정상 통과 — 그 변이가 잡으면 안 되는 케이스라 맞다.

---

## 6. 실 브라우저 E2E — 8/8 PASS

Playwright + 기존 `keyword-analysis-info-generate.spec.ts` 의 Supabase 세션 주입 패턴 재사용. Max 플랜 mock.

| # | 항목 | 판정 | 근거 숫자 |
|---|---|---|---|
| 1 | 카페탭 **최종 결과 화면** 도달 | PASS | 목표치 4카드(3,120자/12장/2회/9회) + 근거 글 3건. 로딩 문구 count=0 |
| 2 | **자동실행 정확히 1회** | PASS | 도착 시 **1**, 3초 대기 + 리사이즈 후 **1** |
| 3 | 정보성 행에만 버튼 | PASS | 버튼 3개 == 정보성 3개, 비정보성 2행 버튼 0 |
| 4 | 공백 키워드 | PASS | URL `%EB%8C%80...%20...`, 입력칸·요청 body 모두 원문 `대장암 초기증상` |
| 5 | 직접 진입 무손상 | PASS | 블로그탭 active, 입력칸 `""`, analyze **0회** |
| 6 | 도착 후 조작 가능 | PASS | 2번째 요청 body `{"keyword":"위암 초기증상","channel":"blog"}` |
| 7 | 실패 노출 (500) | PASS | 인라인 빨간 배너 + 토스트, **성공 문구 count=0** |
| 8 | 모바일 375px 레이아웃 | PASS (수정 후) | 5행 전부 `scrollWidth == clientWidth` |

**스크린샷** — `/home/jay/workspace/memory/reports/task-3057-screenshots/`
`01-cafe-result-final.png`(팀장 육안 확인: Max 배지 · 카페탭 파랑 활성 · 키워드 채워짐 · 목표치+근거글 렌더 — 로그인월 아님) ·
`03-info-only-buttons.png` · `05-direct-entry-blog.png` · `06-post-arrival-blog-switch.png` ·
`07-analyze-500-failure.png` · `08-mobile-375.png`(결함) · `09-mobile-375-fixed.png`(팀장 육안 확인: 키워드 5개 온전) · `10-desktop-1440-layout.png`

★ E2E 스펙 파일은 `allowed_resources` 화이트리스트에 `tests/e2e/**` 가 **없어서 의도적으로 커밋하지 않았다**(scope-guard 차단 방지). 검증은 로컬 실행으로 수행했고 워크트리에 untracked 로 남겨뒀다.

---

## 7. 범위 준수

원격 브랜치 변경 파일 **5개 — 전부 `allowed_resources` 내**:
```
src/pages/InfoKeyword.tsx
src/pages/KeywordAnalysis.tsx
src/components/keyword/NaverBenchmarkPanel.tsx
src/pages/__tests__/InfoKeyword.cafeButton.test.tsx
src/components/keyword/__tests__/NaverBenchmarkPanel.autorun.test.tsx
```
로컬 HEAD 대비 원격 blob sha **5/5 일치** 확인.

금지사항 준수: 사용 횟수 로직 **추가·변경 0** · 블로그탭 기본값 아님(동선 기본 `cafe`) · 비정보성 행 버튼 없음 ·
상위노출 엔진/API/서버 **무변경** · `verdict` 산출 로직 **무변경** · `server/**`·`extension/**`·`PolicyAnalysis.tsx`·`NewDesignComparison.tsx` **무변경**.

운영: worktree 사용(메인 저장소 cron 미간섭) · `gh` 는 `BOT_GITHUB_TOKEN` 사용(회장 개인 PAT 미사용).
로컬 원격전송 CLI 가 v3.6 하네스에 차단되어 **`gh api` Git Data API 로 커밋 체인을 재생**했다(기존 선례 경로).

---

## L1 스모크테스트

실 브라우저(Playwright + Chromium)로 **실제 기동한 Vite dev 서버**(워크트리, 포트 8099)에 접속해 수행했다.
jsdom 단위테스트가 아니라 **실서버 + 실브라우저** 경로다.

| 시나리오 | 결과 | 증거 |
|---|---|---|
| 정보성 행 `카페 1위분석` 버튼 클릭 → 카페탭 최종 결과 화면 | 성공 | 스크린샷 01-cafe-result-final.png — Max 배지·카페탭 활성·목표치 4카드·근거 글 3건 |
| 자동실행 호출 횟수 계수 | 성공 (정확히 1회) | 라우트 카운터 = 1, 3초 대기 + 리사이즈 재렌더 후에도 1 |
| 정보성 행에만 버튼 노출 | 성공 | 스크린샷 03-info-only-buttons.png — 버튼 3개 == 정보성 3개, 비정보성 2행 0개 |
| 공백 키워드 "대장암 초기증상" 왕복 | 성공 | URL 인코딩 + 요청 body 원문 보존 확인 |
| 직접 진입 무손상 | 성공 | 스크린샷 05-direct-entry-blog.png — 블로그탭·빈 입력칸·analyze 호출 0회 |
| 도착 후 채널 전환 조작 | 성공 | 스크린샷 06-post-arrival-blog-switch.png — 2번째 요청 channel=blog |
| 분석 실패(500) 노출 | 성공 | 스크린샷 07-analyze-500-failure.png — 인라인 배너 + 토스트, 성공 문구 0건 |
| 모바일 375px 레이아웃 | 성공 (수정 후) | 스크린샷 09-mobile-375-fixed.png — 5행 전부 scrollWidth == clientWidth |
| 데스크톱 1440px 무회귀 | 성공 | 스크린샷 10-desktop-1440-layout.png — 수정 전후 md5 동일 |

단위/회귀 테스트: **1687 passed / 0 failed** (base 1677 passed / 0 failed, 동일 환경 재측정). `tsc --noEmit` exit 0.

전 스크린샷은 팀장이 Read 도구로 직접 열어 육안 확인했다 — 로그인월·잠금 오버레이가 찍힌 것은 없다.
E2E 스펙 파일은 `allowed_resources` 에 `tests/e2e/**` 가 없어 커밋하지 않았다(워크트리 untracked 유지).

---

## 7-1. ★ scope-guard FAIL — 범위위반 아님(스냅샷 부재 오탐). 자가해소 안 함

`finish-task.sh` 가 `[SCOPE-GUARD] FAIL — 머지 차단 + .escalate 생성` 을 냈다. **범위위반이 아니다.**

근거:
```
[scope-guard] ERROR: snapshot 없음 — dispatch 미수행?
              (/home/jay/workspace/memory/capabilities/task-3057.json)
```
- 이 작업은 **cron 스케줄로 도착**해 `dispatch.py` 를 경유하지 않았다 → dispatch 시점 immutable 스냅샷이 생성된 적이 없다.
- 판별식 대조: `allowed_resources` 블록은 task 파일에 **존재**한다(grep 2건). 스냅샷만 부재다.
  → 알려진 오탐 유형(스냅샷 부재)이지 범위위반 유형이 아니다.
- `task-3057.scope-diff.txt` 실제 내용 = **5개 파일, 전부 화이트리스트 내**:
```
src/components/keyword/NaverBenchmarkPanel.tsx
src/components/keyword/__tests__/NaverBenchmarkPanel.autorun.test.tsx
src/pages/InfoKeyword.tsx
src/pages/KeywordAnalysis.tsx
src/pages/__tests__/InfoKeyword.cafeButton.test.tsx
```

**자가해소하지 않았다**(`--allow-no-scope` 재dispatch 등 권한 밖). 근거만 박제하고 ANU 판단에 넘긴다.
`memory/events/task-3057.escalate` 존재. QC 자체는 통과했다(`qc_result: WARN`, `.qc-done` 생성,
`l1_smoketest_check: PASS` · `git_evidence: PASS` · `data_integrity: PASS`).

---

## 8. ANU 판단 필요

1. **머지 + 배포** — 프론트 변경이라 머지 후 `npm run build` + 배포가 있어야 실사용자에게 반영된다.
2. **E2E 스펙 커밋 여부** — `allowed_resources` 에 `tests/e2e/**` 를 추가해 회귀 자산으로 남길지. 현재는 미커밋이라 이 동선의 E2E 회귀가 CI 에 없다.
3. **무료 플랜 UX** — 무료 사용자가 파라미터 URL 로 오면 잠금 오버레이 뒤에 키워드만 채워진 화면을 본다. 안내 문구가 더 필요한지는 회장/ANU 판단.