# 계획서 — 보험금청구 계산기 (실손 / 정액 2종)

**작성**: 2026-08-30 KST · ANU
**레벨**: Lv.3 (신규 기능) · **저장소**: `Jeon-Jonghyuk/InsuRo`
**상태**: 회장 승인 대기

---

## 1. 목표

고객의 **증권·약관이 이미 등록된 상태**에서, **진료 서류를 업로드하면
보험사로부터 얼마를 받을 수 있을지 1차 검토**해주는 기능.

### 회장 원문
> "고객관리 내에, 고객등록 후 해당 고객의 **실제 증권/약관을 업로드 해두었을 경우**,
>  **진료비세부내역서 또는 진단서** 등의 서류를 업로드했을 때 보험사로부터
>  **얼마 받을 수 있을지 계산**을 해주는 거지."
> "크게 **2가지로 구분**해서 만들어야 해. **실손 vs 보장성보험**"
> - 실손: "고객의 실손정보를 체크해서 **몇 세대인지 구분**하고,
>   **자기부담금이 몇 % 적용**되는지 계산을 정확히"
> - 보장성: "수술/진단비/치료비 등 **담보별 가입한도**가 있을 텐데, 업로드한 서류에서
>   **진단코드 등을 파악**하고, 등록되어있는 **증권/약관과 대조**해서, 어떻게 적용
>   예상되며 **예상 보험금은 어느어느 담보에서 어떻게 받을 수 있다** 라는 걸
>   **1차적으로 검토**해주는 기능"

### 회장 확정 사항 (2026-08-30)
```
① 메뉴 위치   고객관리 > 신규설계 비교 **아래**에 "보험금 청구계산기"
              내부에서 **실손 / 정액 선택** 후 업로드
② 서류 샘플   응급 진료비 계산서·영수증 1건 수령 (경찰병원, 2025-07-30)
③ 금액 표시   **"검토 참고용"** — 단정적 금액 표기 금지
```

---

## 2. 범위 / 포함

### Phase 1 — 기존 실손계산기 **이동** + 고객 연계 (회장 (c) 채택)
★★ **실손 계산기는 이미 완성돼 있다** (ANU 실측, 아래 4번 참조).
   새로 만들지 말고 **위치를 옮기고 고객 연계를 붙인다.**
- `분석&도구 > 실손계산기`(`/tools/silson-calculator`)를
  **`고객관리 > 보험금 청구계산기`** 로 **이동**한다 (신규설계 비교 아래)
- 진입 시 **실손 / 정액 선택**. 정액은 이번 Phase 에서 **"준비 중"** 안내만
- ★ **고객 선택** 추가 — 등록된 실손 정보에서 **세대 자동 판정**
- ★ 결과에 **"검토 참고용"** 성격 명시
- ★ 기존 경로 `/tools/silson-calculator` 처리 방침을 정하라(리다이렉트 권장)

### Phase 2 — 진료비세부내역서 파싱 → 실손 자동 채움
- 업로드 → 파싱 → **엔진 입력 자동 채움** → 사용자 확인·수정 → 계산
- ★ **자동 채움은 초안이고 사용자 검증이 최종**이다

### Phase 3 — 진단서 파싱 + 진단코드(KCD) 추출
- 정액(보장성) 입구

### Phase 4 — KCD → 담보 매칭 + 예상 보험금
- 등록된 증권의 담보별 가입한도와 대조
- ★ **가장 불확실하다** (아래 4번 참조)

## 3. 범위 / 제외

- **확정 금액 제시 금지** — "검토 참고용"이 회장 확정 방침이다
- 보험사 청구 대행·전송 — 이번 범위 아님
- 실손 계산 엔진 로직 변경 — 봉인(t2955·t2958 결과물)
- 증권 분석·담보 그룹핑 엔진 변경 — 봉인(t2938 등)

---

## 4. ★ 선행 조사 결과 (ANU 실측, 2026-08-30)

### ★★ 실손 계산기는 **화면까지 이미 완성**돼 있다 (2026-08-30 재확인)
```
src/pages/SilsonCalculator.tsx        984줄
src/config/routes.ts:326~331
  path "/tools/silson-calculator" · title "실손계산기" · section "분석&도구"
라이브 API  /api/v1/silson/calculator/{table,estimate} → HTTP 401 (라우트 실재)

이미 구현된 것
  세대 목록 조회(GET table) · 세대 자동판별 · generation_resolution 처리
  5세대 전용 severity 조건부 노출 · plan_type 유효성 보정
```
★ ANU 가 Phase 1 을 "메뉴 신설 + 수동입력 UI 연결"로 잡았으나 **전부 이미 존재**한다.
   위임 직전 코드 확인으로 발견했다. 그대로 보냈으면 **봇이 있는 화면을 다시 만들 뻔**했다.

### 기존 화면 vs 회장 구상 — 실제 차이
```
기존                        회장 구상
분석&도구 메뉴               고객관리 > 신규설계 비교 아래
독립 도구(고객 무관)          ★ 고객 선택 → 등록 증권/약관 연계
수동 입력                    ★ 서류 업로드 → 자동 채움
실손 전용                    실손 / 정액 선택
```
**계산 엔진과 입력 폼은 재활용한다.** 새로 만드는 것은 **고객 연계**와 **서류 업로드**다.

### 실손 — 엔진 입력은 **수동 전제**
```python
# server/silson/calc/engine.py
class EstimateItem(BaseModel):
    """영수증 1줄(수동 입력)."""      ← ★ 수동 전제
    care_type:       "inpatient" | "outpatient"
    benefit_type:    "covered" | "uncovered"
    provider_tier:   "clinic"|"hospital"|"general"|"tertiary"|"any"
    severity:        "severe" | "non_severe" | None
    special_benefit: "mri"|"manual_therapy"|"injection" | None
    amount: int
class EstimateRequest: generation · enrollment_date · plan_type · items[1..30]
```
API: `server/routes/silson_calculator_v1.py` (GET 테이블 · POST estimate)
세대 판정: `server/silson/classify.py` `classify_generation` · `analysis_bridge.attach_generation`

★ ANU 가 앞서 "실손은 거의 완성"이라 보고했으나 **부정확**했다.
계산은 되지만 **서류→입력 변환이 통째로 없다.**

### 실물 영수증 대조 (회장 제공 샘플)
```
엔진 필드          영수증 실재 여부
care_type          ✅ 진료기간 1일 · 입원료 칸 공란 → 외래
                      ⚠️ 단 '응급'이라 통원/입원 판정 주의
benefit_type       ✅ 급여(본인부담/공단부담) · 비급여 열이 명시 분리
provider_tier      ✅ "요양기관 종류: 종합병원"
amount             ✅ 항목별 + 합계 ①~⑤ (진료비총액 579,390 / 환자부담 315,350)
severity           ⚠️ **영수증에 없음** — 진단코드·질병명 별도 필요
special_benefit    ⚠️ MRI/PET 행은 있으나 이 건은 공란
```
**6개 중 4개는 영수증에서 직접 추출 가능**하다. 나머지 2개가 문제다.

### 정액(보장성) — 담보 한도는 나오나 매칭 경로가 없다
```python
# server/policy_extract/models.py
class CoverageRecord:
    amount_manwon: float | None   # 가입금액(만원). None = UNKNOWN
    amount_raw: str               # 원문 그대로 ("5,000만원")
```
★ **진단코드(KCD) → 담보 매칭 경로가 없다.** 담보 그룹핑 엔진은 **담보명끼리** 매칭한다.
★★ 지식DB 담보 등록률 **14/299(메리츠, t3024 실측)** — 매칭 실패가 대량 발생할 수 있다.

---

## 5. 검증 기준 (전 Phase 공통)

1. **★ 회장 제공 실물 영수증으로 검증** — 파싱·계산 모두 그 파일로
2. **★ "검토 참고용" 문구가 결과 화면에 실재**하는지
3. **자동 채움은 수정 가능**한지 — 파싱 오류를 사용자가 잡을 수 있어야 한다
4. **파싱 실패가 드러나는지** — 조용히 0/빈값으로 계산하면 FAIL
5. **세대 판정** — 고객 실손 정보에서 세대·자기부담률이 정확히 나오는지
6. **매칭 실패 고지** — 담보를 못 찾으면 그 사실을 명시(t3024 의 `CoverageNotice` 패턴)

## 6. 위임 계획

| Phase | 선행 조건 | 난이도 |
|---|---|---|
| 1 | 없음 | 낮음 (엔진 있음) |
| 2 | Phase 1 머지 | 중간 (양식 편차) |
| 3 | Phase 2 머지 | 중간~높음 |
| 4 | Phase 3 머지 | **높음 (지식DB 의존)** |

★ **Phase 1 이 끝나면 회장이 화면을 먼저 확인**하고 방향을 점검한다.
★ Phase 4 는 지식DB 등록률이 낮아 **결과가 실망스러울 수 있다** — 착수 전 재평가한다.