---
task_id: task-2420
type: context
scope: task
created: 2026-05-03
updated: 2026-05-03
status: completed
---

# 맥락 노트: task-2420

## 결정 1: Root cause 재진단 (회장 가설 정정)

**회장 가설**: "manifest content_scripts.matches 패턴이 서브도메인(mmlfcp.) 미매칭"
**실제 코드**: manifest.json:15 `["https://mmlfcp.ohmymanager.com/*", ...]` — 이미 mmlfcp 매칭됨
**진짜 원인**: content.js:9 하드코딩 `host === "mmlfcp.ohmymanager.com"` (서브도메인 확장 불가)
**Codex 동의**: high severity 2건이 모두 동일 진단

→ 회장 가설을 그대로 따르지 않고 코드를 직접 확인한 후 Codex 검증을 거쳐 재진단 확정.

## 결정 2: 와일드카드 + 매칭 함수 추출

- 옵션 A: manifest.json만 와일드카드 (단순)
- 옵션 B: 매칭 함수를 별도 모듈로 추출하고 content.js + test가 동일 로직 공유
- **선택**: B
- **근거**:
  - 회귀 테스트가 필수 요구사항 (Fix 4)
  - content.js 안에 inline 매칭 함수만 두면 테스트 격리 어려움
  - UMD 패턴(global + module.exports)으로 chrome content script + vitest 양쪽 호환

## 결정 3: 진단 로그 추가 (Codex 권고)

**왜 필요**: 회장 캡처가 "InsuRo Helper 로그 0건" → 미주입 추정 → 잘못된 root cause 가설 발생
**해결**: content.js 진입 첫 줄에 `console.log("[InsuRo Helper] content.js loaded on:", host, "version:", v)` 추가
**효과**: 회장 다음 시연 시 (a) 미주입 vs (b) JWT 미설정 정상 미표시를 콘솔로 즉시 구분
**JWT 사유**: `console.warn("[InsuRo Helper] JWT 미설정/만료 — 버튼 미표시(정책 #10)")`

## 결정 4: SPA hashchange 재렌더 — 본 task 제외

**판단**: 현재 플로팅 버튼은 `position: fixed`, body에 직접 append → SPA hash 변경에도 사라지지 않음
**제외 사유**:
- 회장 명시 시나리오에 hashchange 미포함
- task scope 확장 시 검증 시간 증가
- 별도 task로 후속 처리 권장 (보고서에 명시)

## 결정 5: 버전 bump 0.3.0 → 0.4.0

Manifest 변경 시 minor bump → 회장 사이드로드 시 reload 명확.

## 3 Step Why (Lv.3+ 검증)

**1st Why**: 왜 이 설계(host-matcher 모듈 + 진단 로그 + 회귀 테스트)가 필요한가?
→ A: 회장 가설(manifest 미매칭)이 틀린 상태에서 fix를 진행하면 silent fail 위험. 진단 로그가 있어야 다음 시연 시 root cause 확정 가능. 회귀 테스트가 있어야 host 와일드카드 변경의 보안 회귀(피싱 도메인 매칭) 방지.

**2nd Why**: 왜 host-matcher 모듈 분리가 최선의 접근인가?
→ B: content.js는 chrome content script이라 ESM import 불가. 하지만 매칭 로직을 inline하면 vitest로 단위 테스트 불가. UMD 패턴으로 매칭 함수를 분리하면 (1) chrome 환경에서 globalThis로 접근, (2) vitest에서 import로 단위 테스트 — 양쪽 호환. 코드 중복 0.

**3rd Why**: 왜 UMD 분리가 다른 대안(코드 중복 + sync 코멘트, build-time inline)보다 나은가?
→ C: 코드 중복은 동기화 책임이 사람에게 떠넘겨져 drift 위험. build-time inline은 vite 설정 + chrome extension 빌드 파이프라인 추가 필요(현재 extension은 별도 빌드 파이프라인 없이 raw js 사용). UMD는 추가 빌드 도구 0, vitest 단위 테스트 가능, chrome content_scripts에 두 파일 등록만으로 동작.

**A-B-C 일관성**: ✅ 진단 가능성 + 회귀 안전망 + 단순성이 일관되게 설계 동기를 정당화.

## 참조 자료

- 회장 캡처 (Edge DevTools Console, 2026-05-03)
- task-2354 Phase 1 PR #80 (직접 후속)
- 회장 메모리 결정 #10 (미인증 시 버튼 미표시)
- Codex G1 PASS 결과 (5 risks, critical=False, 동일 진단 합치)

## 주의사항

- `host_permissions`/`matches`/`web_accessible_resources` 와일드카드를 통일해야 함 (한 곳만 바꾸면 web_accessible_resources에서 매칭 실패)
- content.js의 두 분기(ohmymanager / insuro)가 동일 IIFE 내에 있음 → host-matcher import 순서 주의
- vitest config의 `include` 패턴 확인 필요 (`extension/__tests__/` 포함 여부)