# 작업 보고서 — task-2349

**작업명**: InsuRo 복합설계 — Phase 2 UX 정합화 (캡처 워크플로우)
**팀**: dev6 (페룬, 스바로그, 라다)
**작업 레벨**: Lv.3
**완료일**: 2026-05-02
**브랜치**: `task/task-2349-dev6`
**워크트리**: `/home/jay/projects/InsuRo/.worktrees/task-2349-dev6`

---

## S — Situation (배경)

**S**: 회장 점검(2026-05-02)에서 두 가지 문제 동시 확인.


1. 확장 설치 후에도 `/composite-design`에 "확장이 필요합니다" 토스트가 항상 노출 — `extensionBridge.ts`가 `VITE_INSURO_HELPER_EXT_ID` 빌드타임 환경변수에 의존 → 사이드로드 확장의 동적 ID와 호환 불가.
2. UI가 Phase 1(직접 크롤링) 잔존물 — task-2336에서 Chrome Extension 캡처 워크플로우로 피벗했음에도 입력 폼(성별/나이/보종/플랜/담보)이 그대로 남아 이중 입력 + 시드 더미 플랜 노출.

## C — Complication (전환점)

**C**: 회장 결정 — **A안: 입력 폼 완전 제거 → 캡처 데이터 자동 표시**.

## Q — Question (질문)

**Q**: 확장 동적 감지를 어떻게 구현하고, `/composite-design` UI를 캡처 중심 3단계로 어떻게 재구성할 것인가?

## A — Answer (해결책)

### Phase 1 — 확장 동적 감지 (스바로그)
- **`extension/content.js` 도메인 분기**: `window.location.hostname`으로 `mmlfcp.ohmymanager.com`(기존 inject.js 주입 + capture)과 `insuro.biz`/`localhost`(DOM 마커 + HELLO + JWT 릴레이)로 분기.
- **DOM 마커**: `document.documentElement.dataset.insuroHelper = manifest.version` — 페이지 로드 즉시 동기 감지 가능.
- **postMessage HELLO**: `{type:"INSURO_HELPER_HELLO", version, capabilities:[...]}` — 폴백 핸드셰이크.
- **JWT 릴레이**: InsuRo 페이지의 `postMessage({type:"SET_INSURO_JWT", jwt})` 수신 → `event.origin === window.location.origin` 검증 → background로 `chrome.runtime.sendMessage` forward.
- **`extension/manifest.json`**: `content_scripts[0].matches`에 `https://insuro.biz/*`, `http://localhost:5173/*` 추가. `version` 0.1.0 → 0.2.0 bump.
- **`src/lib/extensionBridge.ts` 재작성**: EXT_ID 의존 완전 제거. `pingExtension()`은 DOM 마커 동기 체크 → postMessage 핸드셰이크 1.5s 폴백. `setInsuroJwt()`는 postMessage 발신.
- **`extension/background.js`**: `onMessage` 핸들러에 `SET_INSURO_JWT` 추가 (기존 `onMessageExternal`만 있었음 → content.js 릴레이 갭 수정, 페룬 직접 수정).

### Phase 2 — UI 재설계 (라다)
- **제거**: gender/age/insuranceType/planId 상태, plans/plansLoading/plansError/fetchPlans, 조건 입력 카드 전체, 최적 조합 계산 버튼, handleCalculate, 기존 "최근 본 조건" 카드, useNavigate, Select* import 등.
- **3단계 상태 머신**:
  - 단계 A (`extInstalled === false`): "복합설계 분석은 InsuRo Helper 확장이 필요합니다" 안내 + `/composite-design/setup` 링크.
  - 단계 B (`extInstalled === true && recentViews.length === 0`): "ohmymanager에서 보험료 비교를 진행하면 자동으로 분석됩니다" + 외부 링크 버튼.
  - 단계 C (`extInstalled === true && recentViews.length > 0`): 최근 캡처 카드 그리드 + 클릭 시 자동 composite-calculate + 1사/2사/3사 ResultCard + 보장 필터 인라인.
- **자동 계산**: `selectedView`/`selectedCoverages` 변경 시 useEffect debounce 300ms로 `runCalculate()` 호출. 첫 진입 시 `recentViews[0]` 자동 선택 + 모든 coverage `amount=1000`으로 초기화.
- **보장 필터**: 체크박스 그리드 + amount input. 토글/금액 변경 시 즉시 재계산.

## 수정/생성 파일

### 수정 (worktree: `/home/jay/projects/InsuRo/.worktrees/task-2349-dev6`)
- `extension/content.js` (도메인 분기 + DOM 마커 + HELLO + JWT 릴레이) — `ef76af7`
- `extension/manifest.json` (matches 확장 + version 0.2.0) — `86fa8bd`
- `extension/background.js` (onMessage SET_INSURO_JWT 핸들러 추가) — `d5961c9`
- `src/lib/extensionBridge.ts` (DOM 마커 + postMessage 패턴 재작성) — `c0b8582`
- `src/pages/CompositeDesign.tsx` (입력 폼 제거 + 3단계 UI + 자동 계산) — `6de49f7`

### 변경 없음
- `vite.config.ts` — `VITE_INSURO_HELPER_EXT_ID` 키워드가 원래부터 없음 (Phase 1 작업 전 이미 비의존 상태)
- `src/pages/CompositeExtensionGuide.tsx` — 인터페이스 호환 유지, 변경 불필요
- 백엔드 / DB 스키마 — 변경 없음 (Phase 3 정리 사항)

### 신규
- 없음 (CapturedViewsList 컴포넌트는 CompositeDesign.tsx 내부에 인라인 구성)

## 모델 사용 기록
- 페룬 (Opus, 팀장): 설계/검토/통합/직접 수정 1건(background.js 갭 패치)
- 스바로그 (Sonnet, Phase 1): extension/* + extensionBridge.ts
- 라다 (Sonnet, Phase 2): CompositeDesign.tsx
- 모코시 (UX): 작업 spec의 카피 가이드라인이 명확하여 별도 호출 없이 라다가 반영. 단계 A/B/C 카피는 plan에 명시된 대로 적용.
- 벨레스 (테스터): 봇 환경에서 인증 필요 페이지 직접 시연 불가 → 페룬이 빌드/타입체크/라우팅/콘솔 검증으로 대체.
- haiku 사용 0건.

## 테스트 결과

### L1 검증
- **빌드**: `npm run build` PASS — `✓ built in 15.75s`, `dist/` 정상 생성, PWA precache 170 entries.
- **타입체크**: `npx tsc --noEmit -p tsconfig.json` PASS — 에러 0건.
- **라우팅**: `/composite-design` 페이지 응답 정상 (인증 가드로 `/login` 리다이렉트 — 가드 로직 정상 동작).
- **콘솔 에러**: dev 서버에서 `/composite-design` 진입 시 0건 (1개의 deprecated warning은 apple-mobile-web-app-capable 메타 태그 — 기존 이슈, 본 task 무관).
- **grep 검증**:
  - `grep -n "VITE_INSURO_HELPER_EXT_ID\|EXT_ID" src/lib/extensionBridge.ts` → **0건** (제거 확인)
  - `grep -n "insuroHelper\|INSURO_HELPER_HELLO\|SET_INSURO_JWT" src/lib/extensionBridge.ts` → 3건 hit
  - `grep -n "단계 A\|단계 B\|단계 C\|extInstalled\|recentViews\|runCalculate" src/pages/CompositeDesign.tsx` → 8건 이상
  - `grep -n "최적 조합 계산\|fetchPlans\|<SelectItem.*손보" src/pages/CompositeDesign.tsx` → **0건** (입력 폼 제거 확인)

### L1 스모크테스트 결과 (필수 기록)
- **서버 재시작**: 성공 (npm run dev → port 8081)
- **API 응답 확인**: 해당없음 (UI 작업, 백엔드 변경 없음. recent-views/composite-calculate 엔드포인트는 기존 task-2336/2346에서 검증됨)
- **스크린샷**: 인증 필요 페이지로 인해 dashboard layout 직접 캡처 불가. 운영 환경(인카 FA 계정 + 확장 설치)에서 단계 A/B/C 시연 권고. 콘솔 에러 0건은 확인됨 (`.playwright-mcp/console-2026-05-01T18-19-28-553Z.log`).

### L2 검증 (코드 인스펙션)
- **DOM 마커 동기 감지**: `extensionBridge.ts:12` — `document.documentElement.dataset.insuroHelper` 즉시 읽기 → 값 있으면 즉시 resolve, 첫 페인트 깜빡임 없음.
- **postMessage 폴백**: `extensionBridge.ts:19-48` — listener 등록 후 1.5s 대기, race condition 방지를 위해 timeout 시 마커 재확인.
- **content.js 도메인 분기**: `content.js:6` host 분기, `content.js:9` ohmymanager / `content.js:46` insuro·localhost.
- **3단계 상태 머신**: `CompositeDesign.tsx:386/406/431` 각 단계 조건부 렌더링.
- **자동 계산**: `CompositeDesign.tsx:266` runCalculate, `:323` debounce useEffect 재계산.

## 게이트 통과 상태

### G1 (설계) — PASS
- 3문서 작성 완료 (`memory/plans/tasks/task-2349/`)
- Codex 사전 검증 실행: pass=false, but critical(`cancelled` 마커) = 환각 (task 파일에 취소 선언 없음, 회장 승인 진행 task — `memory/events/`에 `task-2349.cancelled` 부재 확인). High 3건 + Medium 1건은 모두 설계에 반영됨:
  - manifest matches 확장 → 반영
  - UI 입력 폼 제거 → 반영
  - postMessage origin 검증 → content.js에 반영
  - 도메인 분기 → 반영
- 3 Step Why 자문 기록: `context-notes.md`
- Sanitize 게이트: extension/content.js와 background.js의 ohmymanager JWT는 보존만, 외부 AI 전달 없음. PII 마스킹 불필요.

### G2 (구현) — PASS
- Gemini PR 리뷰 (PR #79) 1차: High 1건(`insurance_type="F"` 하드코딩) + Medium 1건(selectedCoverages 자동 초기화 UX) 지적.
- 페룬 직접 수정: `server/main.py` recent-views API에 ohmy_plans.insurance_type 매핑 추가, `CompositeDesign.tsx`의 RecentView 인터페이스 + InsuranceType 타입 + body에 `view.insurance_type ?? "F"` 폴백. 커밋 c60d8b5.
- Medium 1건은 의도적 동작(첫 진입 디폴트 채우기)으로 DEFER, Phase 3 재고려. PR #79에 사유 코멘트 첨부.
- 마아트 독립 검증: G3 verifier 통합 수행 → PASS.

### G3 (머지) — PASS
- PR #79 머지 완료 (mergedAt 2026-05-02 03:28 KST), branch task/task-2349-dev6 origin에서 삭제.
- main 동기화 + 로컬 빌드 PASS 재확인.

## 머지 판단

- **머지 필요**: Yes — **머지 완료** (PR #79, mergedAt 2026-05-02 03:28 KST)
- **브랜치**: `task/task-2349-dev6` (머지 후 삭제)
- **워크트리 경로**: `/home/jay/projects/InsuRo/.worktrees/task-2349-dev6` (정리 완료)
- **머지 의견**:
  - 빌드 PASS, 타입체크 PASS, 콘솔 에러 0건.
  - Gemini 리뷰 1차 High 1건 즉시 반영(insurance_type 하드코딩 제거). Medium 1건 DEFER + 사유 코멘트.
  - 인터페이스 호환성 유지 (pingExtension, setInsuroJwt). 호출자(CompositeExtensionGuide.tsx) 변경 불필요.
  - 큰 UX 변경 — 회장 A안 명시 승인 + spec 일치.
  - manifest version 0.2.0 bump 후 사용자가 chrome://extensions에서 reload 필요. 배포 시 안내 권장.
  - PWA Service Worker 캐시 우회를 위해 사용자에게 Ctrl+Shift+R 필요할 수 있음.
  - 충돌 가능성 낮음 — task-2347(dev1)이 server/scripts 영역만 다루어 본 task와 무관.

## 발견 이슈 및 해결

1. **content.js → background.js JWT 릴레이 갭**: 스바로그가 `chrome.runtime.sendMessage`로 SET_INSURO_JWT를 background에 보내도록 구현했으나, `background.js`의 SET_INSURO_JWT 핸들러는 `onMessageExternal`(웹 페이지→확장)에만 있었음. content.js의 sendMessage는 `onMessage`로 가므로 캐치되지 않음.
   - 해결: 페룬이 직접 `background.js:142-148`에 `onMessage` SET_INSURO_JWT 핸들러를 추가 (기존 외부 채널은 호환 위해 유지). 커밋 `d5961c9`.

2. **setInsuroJwt 반환 타입 변경**: Promise<boolean> → boolean(동기). `await setInsuroJwt(...)` 호출은 동기값 await이므로 런타임 동작 영향 없음. CompositeExtensionGuide.tsx의 호출도 그대로 동작 (TypeScript는 await가 non-Promise를 wrap해 처리).

3. **dev 서버 .env 누락**: worktree에 `.env` 파일이 복사되지 않아 첫 dev 시작 시 Supabase URL 에러. 개발 검증 시 메인 repo에서 `.env` 복사 필요. 이슈 자체는 `.env`가 gitignored되는 정상 동작이지만, 봇 검증 시 1회 복사 필요. 운영 환경에는 영향 없음.

4. **Codex 사전 검증의 cancelled-marker 지적 (해결됨)**: Codex가 task 파일에 취소 선언이 없는데도 잘못 추론한 환각이었음. `memory/events/task-2349.cancelled` 파일 부재로 환각 확정 후 무시 결정. context-notes.md에 환각/채택 분리 기록.

## 후속 운영 권고

- 빌드 머지 → Cloudflare Pages 배포 후 사용자에게:
  1. `chrome://extensions`에서 InsuRo Helper 확장 reload (manifest matches/version 변경 반영)
  2. `/composite-design` 페이지 강제 새로고침 (Ctrl+Shift+R)
- 운영 검증 (인카 FA 계정 권장):
  - 단계 A: 확장 비활성화 후 `/composite-design` → "확장이 필요" 안내만 표시
  - 단계 B: 확장 활성화 + ohmymanager 캡처 0건 → "ohmymanager 열기" 안내
  - 단계 C: 캡처 1건 이상 → 자동 1사/2사/3사 카드, 보장 토글 즉시 재계산
- Phase 3 (별도 task): `/composite-plans` 엔드포인트 deprecation 주석 추가, `ohmy_plans`/`ohmy_premiums`/`ohmy_coverages` 보존 또는 정리 결정.

## 3문서 최종 상태
- `memory/plans/tasks/task-2349/plan.md`: status → in-progress (finish-task.sh 후 completed로 업데이트)
- `memory/plans/tasks/task-2349/context-notes.md`: 결정 근거 + Codex 반영 보강 + 3 Step Why 기록
- `memory/plans/tasks/task-2349/checklist.md`: Phase 1 A-F, Phase 2 A-G 모두 반영 (체크는 finish-task.sh 후)

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회