# 작업 보고: task-2954 — InsuRo 실손 세대지식 설계사 노출 MVP (B: 배선)

- **팀**: dev2-team (오딘/Odin)
- **검증 레벨**: critical
- **PR**: https://github.com/Jeon-Jonghyuk/InsuRo/pull/215 (**open — 머지 안 함**)
- **브랜치**: `task/task-2954-dev2` · 원격 head `64111fbd` (tree `15e8d17d` = 로컬 HEAD `dd3bab8` 트리와 일치)
- **worktree**: `/home/jay/projects/InsuRo/.worktrees/task-2954-dev2` · base `2ccc121`

---

## SCQA

**S**: 실손 세대 지식은 삼성 11 + 현대 2종 표준약관 1차출처 대조까지 끝나 값이 확정됐다(PR#214 `2ccc121`). 증권분석 파이프라인(`analyze-policy` + `PolicyAnalysis`)도 이미 라이브다.

**C**: 그러나 `analysis_bridge.py` 의 `attach_generation`/`describe_for_analysis` 는 **테스트 외 호출부가 0** — 머지는 됐으나 **휴면**이라 설계사에게 도달하지 못했다. codex↔ANU 합의대로 병목은 지식이 아니라 **배선**이었다.

**Q**: 기존 증권분석 로직과 gating 경로를 건드리지 않고, 확정된 세대 지식을 설계사 화면에 도달시킬 수 있는가?

**A**: `analyze-policy` 결과 조립 지점 **한 곳**에 `silson_summary` 를 순수 추가(+8줄)하고 `PolicyAnalysis` 결과 카드에 블록을 조건부 렌더해 달성했다. 변경은 **6파일 +995 / -0 (삭제 0줄)**. 회귀는 clean worktree 기준 base 1772 passed/0 failed → 브랜치 **1800 passed / 0 failed**(신규 실패 0), `npm run build` PASS(12.22s), 실브라우저 스크린샷 4종 확보.

---

## 작업 내용

### 1. 백엔드 — `silson_summary` 부착 (토르)
- **신규** `server/silson/analysis_summary.py` (216줄) — `build_silson_summary(meta, coverages, *, today, knowledge)`
  - 실손 담보 감지(1순위 `category == "실손"`, 보조 키워드 `("실손",)`) → **미감지 시 `applicable:false` 로 세대 판별 자체를 하지 않음**
  - `PolicyHeader` 를 모듈 내에서 최소 필드로 조립. `insured_name_masked`/`policy_number_masked` **None 고정**
  - 가입일을 `coverage_start_date` 가 아니라 `contract_date` 로만 전달 → `date_source="contract_date"` + caveat 이 정직하게 붙음
  - `describe_for_analysis` 결과를 확정 스키마로 재포장. **값이 `None` 인 지식 필드는 `highlights` 에서 제외**(0/빈칸 치환 금지)
  - 모듈 자체는 **logging 하지 않음**(PII 표면 최소화)
- **수정** `server/main.py` (+8줄) — `_analyze_files()` 에 비차단 배선. 예외 시 `silson_summary = None` + `logger.warning` 에 **예외 타입명만**
- **신규** `server/tests/test_silson_analysis_summary.py` (28 tests)

### 2. 프론트 — 세대 블록 (프레이야)
- **신규** `src/components/SilsonGenerationBlock.tsx` (272줄) — 타입 단일 소스 + 렌더. `!summary || applicable !== true` → `return null`(빈 박스도 없음)
- **수정** `src/pages/PolicyAnalysis.tsx` (+10줄) — 타입 확장 + 렌더 호출 1줄(688행 부근, 담보 그룹 직후)
- 표시: 세대명 / **"판별 불가" + 한국어 사유** / `date_source_caveat` 를 빨간 Alert("추정 — 확정 판정 아님") / `plan_type_resolution.caveat`(표준형·선택형 오독 방지) / `verification_notice` **원문 그대로** / 근거 출처 / **고정 고지문**
- **신규** `src/components/__tests__/SilsonGenerationBlock.test.tsx` (9 tests)

### 3. 리스크 가드 3종 (codex 지적 대응)
| 항목 | 조치 | 증거 |
|---|---|---|
| PII | `PolicyHeader` PII 필드 None 고정 · 모듈 무로깅 · 로그는 예외 타입명만 | 반환 JSON 에 고객명/증권번호 미포함 assert 테스트 · diff 정규식 스캔 PII net-new **0건** |
| 금소법 | 고지문 `"설계사 참고용입니다. 실제 증권·약관을 확인하세요."` 상시 노출 · 고객 자동판정 아님(`gating.py` 무변경) | 코드 상수 + 런타임 `==` 비교 + 스크린샷 3종 하단 |
| 운영 | 계약일 fallback 을 확정처럼 표시 금지 | `date_source="contract_date"` + caveat 응답 노출 + 화면 빨간 경고 |

---

## 생성/수정 파일 (6개 · +995 / -0)

| 파일 | 구분 | 줄 |
|---|---|---|
| `server/silson/analysis_summary.py` | 신규 | 216 |
| `server/tests/test_silson_analysis_summary.py` | 신규 | ~340 (28 tests) |
| `server/main.py` | 수정 | +8 (import 1 + 배선 7) |
| `src/components/SilsonGenerationBlock.tsx` | 신규 | 272 |
| `src/components/__tests__/SilsonGenerationBlock.test.tsx` | 신규 | 139 (9 tests) |
| `src/pages/PolicyAnalysis.tsx` | 수정 | +10 |

**무변경 확인**: `analysis_bridge.py` · `classify.py` · `models.py` · `knowledge.py` · **`gating.py`** · `policy_analyzer.py` · silson 지식 JSON — diff 에 없음. 임시 QA 파일 커밋 **0건**.

## 수정 파일별 검증 상태

| 파일 | 변경 내용 | grep 검증 | 상태 |
|---|---|---|---|
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/server/silson/analysis_summary.py | silson_summary 조립 모듈 신규 (216줄) | grep "build_silson_summary" OK | 완료 |
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/server/main.py | _analyze_files() 에 비차단 배선 +8줄 | grep "silson_summary" OK | 완료 |
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/server/tests/test_silson_analysis_summary.py | 단위 테스트 28건 신규 | grep "date_source" OK | 완료 |
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/src/components/SilsonGenerationBlock.tsx | 세대 블록 컴포넌트 신규 (272줄) | grep "SilsonGenerationBlock" OK | 완료 |
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/src/components/__tests__/SilsonGenerationBlock.test.tsx | 렌더 테스트 9건 신규 | grep "applicable" OK | 완료 |
| /home/jay/projects/InsuRo/.worktrees/task-2954-dev2/src/pages/PolicyAnalysis.tsx | 타입 확장 + 렌더 호출 +10줄 | grep "silson_summary" OK | 완료 |

---

## 테스트 결과

### 회귀 — ★ clean worktree(`.env` 없음 = CI parity)에서 base 대조
| 대상 | 결과 |
|---|---|
| base `2ccc121` | **1772 passed, 0 failed**, 3 skipped |
| 브랜치 `dd3bab8` | **1800 passed, 0 failed**, 3 skipped |
| 델타 | **+28 = 신규 테스트 수와 정확히 일치. 신규 실패 0** |

> `.env` 가 있는 트리에서 보이던 `test_consultation_history_get.py::test_cors_fail_closed_when_ext_origin_unset` 1건 실패는 `INSURO_EXTENSION_ORIGIN` **환경 오염**이 원인이다. ① base 에서도 동일 재현 ② `.env` 제거 시 해당 파일 21 passed ③ clean worktree 에서 base·브랜치 모두 0 failed — **3중 교차 확인으로 pre-existing 확정**(본 작업과 무관).

### 프론트
- `npx tsc --noEmit` — 에러 **0**
- `npx vitest run` — **9/9 PASS** (1.17s)
- `npm run build` — **PASS** (12.22s, PWA precache 177 entries, dist 21:40 갱신)

### 백엔드 단위
- `pytest tests/test_silson_analysis_summary.py -q` — **28 passed** (0.11s)
- 커버: 실손 미감지 / 감지+fallback caveat / **세대 경계일 10쌍(지식 번들 실측값)** / `missing_date` / `unparsable_date` / 1세대 `verification_notice` 원문 대조 / PII 가드 2종 / highlights None 금지 / 라벨맵 커버리지 / JSON 직렬화 / **과탐 방지 4건**

---

## L1 스모크테스트

- **서버 재시작**: 성공 — 별도 포트 8899 로 uvicorn 실기동(운영 8001 과 분리)
- **API 응답 확인**:
  - `from main import app` 임포트 OK, `/api/insuro/analyze-policy` in routes = True (총 122 routes)
  - `GET /api/status` → **200 `{"status":"ok"}`**
  - `POST /api/insuro/analyze-policy` (무인증) → **401 Missing or invalid authorization** (게이트 정상)
  - `build_silson_summary` 실런타임 호출 → `applicable=true`, `generation="GEN3_2017_04"`, `date_source="contract_date"`, caveat 비어있지 않음, 고지문 정확 일치
- **스크린샷** (실브라우저 vite dev + Playwright, 콘솔 에러 **0건**):
  - `/home/jay/workspace/memory/reports/screenshots/task-2954-silson-block-1.png` — 정상 3세대 + 빨간 caveat
  - `.../task-2954-silson-block-2.png` — 판별 불가 + 사유
  - `.../task-2954-silson-block-3.png` — 1세대 `verification_notice`
  - `.../task-2954-silson-block-full.png` — 전체(적대적 fixture 포함)
  - ※ `PolicyAnalysis` 전체 플로우는 Supabase 로그인 + 실증권 PDF 분석이 필요해 로그인 없이 결과 카드 도달 불가 → **실제 컴포넌트를 실브라우저에 마운트하는 방식**으로 대체 캡처. 임시 진입점 파일은 검증 후 삭제, 커밋 0건.
- **팀장 육안 확인**: 스크린샷 1번을 직접 열어 세대명·"추정 — 확정 판정 아님" 경고·표준형/선택형 표기 유의·근거 출처·하단 고지문 렌더를 확인함

---

## 게이트 결과

- **G1 Codex 사전 검증**: `pass: true` (critical 0) — 2회차. 1회차 FAIL 은 작업 진행 중 스냅샷(미완성 MT 3건 지적)이었고 완료 후 재실행에서 통과.
- **G3 독립 검증**: **PASS** (`fail_reasons: []`, 21:46:32). 1회차는 보고서 SCQA 표기 형식이 검증기 정규식과 불일치해 FAIL — **내용 부재가 아닌 포맷 불일치**였고, 형식 보정 + "수정 파일별 검증 상태" 표 추가 후 PASS. `.g3-fail` 마커는 clear-on-PASS 로 해소(현재 파일 없음).
- **마아트 독립 검증**(critical 필수): **PASS(조건부)** — 아래 절 참조

### 마아트 독립 검증 결과 (횡단조직)

마아트가 **자체 clean worktree 를 직접 생성**해 base/head 회귀를 재실행하고, PII 를 직접 주입해보는 방식으로 팀 주장 9개를 검증했다.

| 팀 주장 | 마아트 판정 |
|---|---|
| 회귀 1772 → 1800, 신규 실패 0 | **확인됨** (독립 재현: base 1772/3skip, head 1800/3skip) |
| `.env` 오염 pre-existing | **확인 불가** (오염 트리 직접 재현 안 함) — 단 clean 에서 양쪽 0 failed 라 결론과 정합 |
| tsc 0 / vitest 9-9 / build PASS | **확인됨** (전부 독립 재실행, EXIT 0) |
| 순수 추가 905줄 / 삭제 0 / 6파일 | **부분 반증** — 삭제 0·6파일은 맞으나 **추가는 905 가 아니라 995** |
| PII 없음 | **확인됨** — meta 에 고객명/증권번호/생년월일/연락처를 **직접 주입**해도 응답 JSON 에 유출 0건 |
| 고지문 정확 일치 | **확인됨** |
| fallback caveat 노출 | **확인됨** (코드 + 런타임) |
| 실손 미감지 시 판별 안 함 | **확인됨** |
| 내부 경로 미유출 | **확인됨** (1~5세대 전수, `/home/` 0건 · `local_path` 0건) |

추가 확인: `meta=None`/`coverages=None`/타입 오염 입력에도 크래시 없음 · 예외 주입 시 본체 무영향 · **배포 HOLD 이행**(프로덕션 dist mtime = Aug 9 불변) · **PR 미머지 상태 이행**.

**팀장 조치**: 마아트가 반증한 **라인 수 오기(905 → 995)를 본 보고서 전체에서 정정**했다. 원인은 초기 측정치(토르의 과탐 수정 후속 커밋 2건 이전)를 이후 갱신하지 않은 **stale 수치**다. 결론(순수 추가·삭제 0)에는 영향이 없으나 셀프 검증 정확도의 하자이며, 마아트 지적이 옳다.

### Codex 지적 5건 판정
| # | 심각도 | 지적 | 판정 |
|---|---|---|---|
| 1 | high | `_SILSON_KEYWORDS` 의 `"의료비"` 가 광범위 → 비실손 증권 과탐 | **수용·수정** — 키워드에서 제거(`("실손",)`), 과탐 방지 회귀 테스트 4건 추가. 근거: 참고용·금소법 민감 기능이라 **과탐 > 미탐** 순으로 위험 |
| 2 | medium | 프론트 렌더 테스트 부재 | **기각** — `src/components/__tests__/SilsonGenerationBlock.test.tsx`(139줄, 9 tests) 실재하며 vitest 9/9 PASS. Codex 미탐지 |
| 3 | medium | `sources` 에 `local_path` 등 서버 내부 경로 노출 위험 | **기각(실측)** — 지식 JSON 에 `local_path` 는 실재하나 응답 경로로 흐르지 않음. 1~5세대 전수 실행 결과 `/home/`·`local_path` 노출 **0건**. 남는 `.pdf` 는 약관 문서명 = task 가 요구한 근거 출처 표기 |
| 4 | low | "판별 불가" 문자열이 백엔드에 없고 프론트가 합성 | **기각(범위 외)** — 현재 소비자는 이 화면 1개. 백엔드는 `known:false` + `reason` 으로 기계 판독 가능 계약을 제공. 소비자 추가 시 재검토 |
| 5 | low | 임시 QA 자산이 `src` 아래 잔존 | **해소 확인** — 검증용 임시 파일이었고 삭제됨. `git log origin/main..HEAD --name-only` 로 커밋 0건 확인 |

### 레드팀 스캐너 오탐 판정
`red-team-auto-review.py` 가 `analysis_summary.py` 를 critical(Code Injection 2건)로 판정했으나 **오탐 확정**:
- 탐지 규칙이 `compile\s*\(` 정규식이라 `re.compile(` 을 무조건 매치 (`memory/red-team-auto-review.py:48`)
- **이미 머지된** `provenance.py`(PR#212)도 동일 규칙으로 동일 critical 판정 → 신규 결함 아님
- 실제 `eval`/`exec`/`__import__`/`subprocess` **0건**, `dangerouslySetInnerHTML` **0건** 교차 확인
- 정규식은 모듈 상수 리터럴이며 사용자 입력이 컴파일에 유입되지 않음. 중첩 수량자 없어 ReDoS 위험도 없음

---

## trip-wire 5종 (실측)

| 항목 | 실측치 | 근거 |
|---|---|---|
| Critical7 | **0** | 레드팀 critical 2건은 `re.compile` 오탐(기머지 파일 동일 판정으로 확정), 실제 코드실행/XSS 싱크 0건 |
| PII net-new | **0** | diff 972줄 정규식 스캔(주민번호/연락처/계좌/API키) 매치 0 · 응답 전 세대 실행 시 내부 경로 0건 |
| 회귀 실패 | **0** | clean worktree base 1772/0 → 브랜치 1800/0 |
| forbidden_paths 침범 | **0** | diff 6파일 전부 InsuRo 내부 대상 파일. `gating.py`/지식 JSON/타팀 디렉토리 무변경 |
| nonce | **task-2954 일치** | 브랜치·커밋·이벤트·보고서 전부 task-2954 |

---

## 발견 이슈 및 해결

| # | 심각도 | 이슈 | 처리 |
|---|---|---|---|
| 1 | **critical (운영사고)** | QA(헤임달)가 임시 uvicorn 정리 중 `pkill -f "uvicorn main:app"` 를 실행 → 포트 미필터링으로 **운영 `insuro-api.service`(8001)까지 종료**. systemd 자동 재기동(21:32:59) | **자진 신고 접수 + 팀장 독립 확인**: 현재 `active (running)`, `/api/status` **200** 정상. 다운타임 수 초. **코드 결함 아님(프로세스 사고)**. 재발 방지 = 종료 패턴에 포트/경로 한정 필수 → 아누 보고 |
| 2 | high | `"의료비"` 키워드 과탐 위험 | **해결** — Codex 지적 수용, 키워드 축소 + 회귀 테스트 4건 (`f7806b9`, `dd3bab8`) |
| 3 | medium | 현 배선에서는 `date_source=contract_date` 가 **상시**라 빨간 경고가 항상 노출 → 경고 피로(alert fatigue) 우려 | **미해결(의도적)** — task 지시가 caveat 노출을 요구. UX 톤 조정은 **미미르(UX) 검토 사안**으로 이관 권고. 디자인 작업은 개발팀 범위 밖 |
| 4 | medium | 세대 블록이 매우 길다(스크린샷 4262px). 설계사 가독성 저하 가능 | **미해결(범위 외)** — 접기/요약 UI 는 디자인 판단. 미미르 검토 권고 |
| 5 | low | `SourceItem` 의 dict 분기는 현재 백엔드 계약(`sources: tuple[str,...]`)상 도달 불가한 방어 코드 (테스트 미커버) | **수용(방어적 설계)** — 크래시 방지 목적. 스키마 변경 시 검증 필요 항목으로 기록 |
| 6 | low | `_normalize_enrollment_date` 가 `policy_analyzer.py` 의 날짜 정규식을 **복제** | **문서화로 처리** — `policy_analyzer.py` 가 읽기 전용 대상이라 복제 불가피. 모듈 주석에 "규칙 변경 시 두 곳 동시 수정" 명시 |
| 7 | low | `.env` 오염으로 CORS 테스트 1건이 로컬에서 상시 실패 | **본 작업 범위 외 pre-existing** — 3중 교차 확인 완료. 별도 위생 작업 대상 |

---

## 모델 사용 기록

| 팀원 | 역할 | 모델 | 비고 |
|---|---|---|---|
| 토르 (Thor) | 백엔드 | sonnet | 로직 구현 |
| 프레이야 (Freyja) | 프론트 | sonnet | 로직 구현 |
| 헤임달 (Heimdall) | 테스트/QA | sonnet | L1 스모크·E2E |
| 마아트 (Ma'at) | 횡단 독립 QC | sonnet | critical 레벨 필수 |
| 오딘 (Odin) | 팀장 | opus | 설계/분배/검토/통합만 — **직접 코딩 0** |

haiku 미사용(전부 로직 구현·분석 작업이라 sonnet 이상 적용).

---

## 머지 판단

- **머지 필요**: **No — task 지시상 머지 금지**
- **브랜치**: `task/task-2954-dev2`
- **워크트리 경로**: `/home/jay/projects/InsuRo/.worktrees/task-2954-dev2`
- **PR**: #215 (open)
- **머지 의견**: 코드 품질 관점에서는 머지 가능 상태로 판단한다(순수 추가 995/삭제 0, 회귀 신규 실패 0, build PASS, Codex 게이트 PASS, 리스크 가드 3종 실측 확인). 다만 **task-2954 지시서가 "머지 금지 — PR까지. ANU 검증 + 회장 보고 후 머지"** 로 못박았으므로 팀장은 머지하지 않았다. **실배포(CF Pages/서버 재기동)는 별도 회장 go 필요.**

---

## 회장님 결정 필요 사항

1. **PR #215 머지 여부** — ANU 독립 검증 후 승인 요청
2. **실배포 go** — 머지와 별개. CF Pages 배포 + `insuro-api.service` 재기동 필요
3. **UX 후속(미미르)** — 상시 노출되는 빨간 caveat 톤 + 블록 길이 접기 처리 여부
4. **운영사고 인지** — QA 과정에서 운영 API 수 초 재기동(자동 복구 완료). 재발 방지 규칙 강화 여부

---

## 비고

- 다음 순번은 **A(판례) 배선** (codex↔ANU 합의 순서: B → A)
- 이 배선은 **설계사 참고용**이며 고객 자동판정(gating) 경로와 무관하다. `primary_source_verified` 정책과 충돌하지 않는다.
- 3문서: `memory/plans/tasks/task-2954/` (plan/context-notes/checklist, status: completed, 3 Step Why A-B-C 기록)

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


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


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


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