DOMAIN_GAP_P4.md

# 도메인 GAP 분석 & P4 기획서

작성일: 2026-05-14  
작성자: PL (자율 모드)  
대상: 한국 GA(법인보험대리점) 수수료 정산 시스템

---

## 1. 현재까지의 도메인 커버리지 (P0~P3 + 부속)

| 영역 | 적용 항목 |
|---|---|
| **세무** (P0-1) | 사업소득 3.3% / 기타소득 8.8% / 지방세 10% / VAT 10% |
| **공제** (P0-2) | 월별 차감 마스터(agent_deduction) + 이체 명세 |
| **명세서** (P0-3) | commission_statement + Excel 출력 |
| **1200%룰** (P1-1) | regulatory_limit + 한도 검증 + 분급 큐 |
| **분급** (P1-2) | installment_plan 7년 (35/25/15/10/7/5/3) |
| **차등환수** (P1-3) | chargeback_grade 5단계 |
| **마감/정정/이의/보류** (P2-1~4) | period_close / settle_correction / commission_dispute / hold_reason_code |
| **시책·해촉·세금계산서·외부회신** (P2-5~8) | incentive_program/payment / termination_settlement / tax_invoice / carrier_reconciliation_out |
| **KPI** (P3) | mv_monthly/org/retention/cumulative + Service + 화면 |

---

## 2. 한국 GA 도메인에서 **여전히 빠진** 항목 (검토)

### 2-A. 영업/계약 라이프사이클 (필수)
- ❌ **청약(Proposal)** → 청약→인수심사→체결 단계. 청약 수당(소액) 처리 부재
- ❌ **인수심사 결과(Underwriting Result)** — 거절/조건부 승인/할증 결과 추적
- ❌ **계약 변경(Endorsement)** — 보험료/피보험자/수익자 변경 시 수수료 재계산 트리거
- ❌ **부활(Reinstatement)** — 실효된 계약 부활 시 환수 처리 + 수수료 재산정
- ❌ **계약 양도(Assignment)** — 설계사 간 계약 이관 → 수수료 재배분

### 2-B. 설계사 라이프사이클 (필수)
- ❌ **위촉계약(Agent Contract)** — 보험사-설계사 위촉계약서 + 위촉수수료
- ❌ **자격 관리(License)** — 자격증 만료/갱신 알림 (생보/손보/변액)
- ❌ **보수교육(Training)** — 의무 교육 시간 추적 (감독규정 12시간/년)
- ❌ **징계 이력(Discipline)** — 불완전판매 제재 → 환수 가중치
- ❌ **휴직(Suspension)** — 활동중지 기간 정산 제외

### 2-C. 회계/재무 (필수)
- ❌ **회계 전표(Accounting Entry)** — 수수료 지급액 자동 분개
- ❌ **출금 신청 워크플로우(Withdraw Request)** — 결재 → 펌뱅킹 → 결과
- ❌ **원천세 신고서(Tax Report)** — 분기 사업소득세 신고 자료 집계
- ❌ **부가세 신고 자료** — 매출/매입 집계 (세금계산서 기반)
- ❌ **결산(Period Settlement)** — period_close 와 별개의 월/분기/연 회계 마감

### 2-D. 컴플라이언스 (중요)
- ❌ **민원 관리(Complaint)** — 고객 민원 → 설계사 책임 추적 → 환수 트리거
- ❌ **불완전판매 모니터링** — 13M/25M 유지율 기반 이상 탐지
- ❌ **상품판매 자격 매트릭스** — 변액=변액자격필요, 매핑 검증

### 2-E. 시스템/UX (필수)
- ❌ **결재선/결재 요청(Approval)** — 정산 확정/이의/시책 결재 워크플로우
- ❌ **공지사항(Notice)** + **개인 알림(UserNotification)**
- ❌ **첨부파일(Attachment)** — 위촉계약서/민원자료 등 문서 저장
- ❌ **사용자 알림 채널** — 메일/SMS 발송 큐

### 2-F. 분석/리포트 보강 (있으면 좋음)
- ❌ **이상치 탐지** (Outlier KPI)
- ❌ **차월 예측** (예상 정산액)
- ❌ **연말 지급명세서** — 설계사 연 사업소득 세무 자료 PDF

---

## 3. 우선순위 결정 (PL 판단)

> 추가 검토 (2026-05-14): 사용자 지적 — **"오버라이드 / 수금수수료 같은 수수료 종류 정보가 많이 빠짐"**. 
> P4-A 로 **수수료 종류 보강** 5개 도메인을 우선 배치하고, 운영 9 도메인을 P4-B 로 후위 배치.

### **P4-A — 수수료 종류 보강 (5 도메인)** ⭐ 사용자 지적 반영
| # | 도메인 | 마이그레이션 | 핵심 |
|---|---|---|---|
| P4-A-1 | **commission_type 코드 + 통합 마스터** | V40 | 모집/유지/수금/오버라이드/갱신/부활/유지보수수당/시책/위촉 9종 통합 코드 + commission_master 마스터 |
| P4-A-2 | **수금수수료 (collection_commission_rule + collection_commission_ledger)** | V41 | 보험료 수납 단위(월) 발생. 납입주기별 차등 + 원장 |
| P4-A-3 | **갱신/부활 수수료 (renewal_commission, reinstatement_commission)** | V42 | 자동차/실비 갱신 + 실효 부활 시 별도 수수료 룰·원장 |
| P4-A-4 | **유지보수수당 (persistency_bonus_rule + persistency_bonus)** | V43 | 13M/25M/37M 유지율 충족 1회 지급. 등급별 정액 또는 정률 |
| P4-A-5 | **오버라이드 보강 (override_ledger + override_summary)** | V44 | 기존 override_rule + 8 Step 결과를 **원장 단위로 추적**. 직급별/조직별 합계 + 검증 |

### **P4-B — 운영 필수 9 도메인** (P4-A 완료 후)
| # | 도메인 | 마이그레이션 | 핵심 |
|---|---|---|---|
| P4-B-1 | **위촉계약 (agent_contract)** | V45 | 보험사-설계사 위촉계약서 + 위촉수수료 + 효력 기간 |
| P4-B-2 | **자격 관리 (agent_license)** | V46 | 생보/손보/변액 자격증 + 만료일 + 갱신 이력 |
| P4-B-3 | **보수교육 (agent_training)** | V47 | 교육 이수 시간 + 의무 12시간/년 충족 여부 |
| P4-B-4 | **계약 변경 (contract_endorsement)** | V48 | 변경 유형(보험료/수익자/피보험자) + 수수료 재계산 트리거 |
| P4-B-5 | **민원 관리 (complaint)** | V49 | 고객 민원 + 설계사 책임 + 처리 상태 + 환수 연동 |
| P4-B-6 | **결재 워크플로우 (approval_line + approval_request)** | V50 | 결재선 마스터 + 다단 결재 요청/처리 |
| P4-B-7 | **공지사항 + 알림 (notice + user_notification)** | V51 | 시스템 공지 + 사용자별 알림 (읽음 여부) |
| P4-B-8 | **첨부파일 (attachment)** | V52 | 도메인 무관 공통 첨부 (소속/파일경로/타입) |
| P4-B-9 | **출금 신청 (withdraw_request)** | V53 | 결재 + 펌뱅킹 송신 + 결과 반영 워크플로우 |

메뉴 INSERT 는 **V54** 한 파일에서 P4-A + P4-B 14개 메뉴 한 번에 등록.

### **P5 — 회계/분석 보강** (별도 라운드)
- 회계 전표 자동 분개 / 원천세·부가세 신고 자료 / 결산 / 이상치·예측 KPI / 연말 지급명세서

### **P6 — 모바일/외부 연동** (제일 후속)
- 펌뱅킹 실연동 / 모바일 셀프 조회 / SMS/카카오 발송

이번 라운드는 **P4 만** 일괄 진행. P5/P6 는 다음 라운드에서.

---

## 4. P4 이행 계획 (Wave 방식, 이미 검증된 패턴)

| Wave | 담당 | 산출물 |
|---|---|---|
| Wave 1 | dba-architect | V40~V48 9개 + V49 메뉴 INSERT (총 10 파일) |
| Wave 2 | core-architect | P4 VO/Resp/SaveReq/SearchParam + Mapper(IF+XML) + Enum |
| Wave 3 | api-developer | Service + Controller + 결재 AOP (또는 Service 가드) |
| Wave 4 | frontend-developer | 화면 9개 (토스 톤 일관) + 라우터 + Route 등록 |
| Wave 5 | infra-reviewer | 빌드/통합 검증 + README/HANDOFF 갱신 + 메뉴 적용 |

병렬화: Wave 1↔3 의존, Wave 4 는 Wave 3 후, Wave 5 는 마지막. 단 #8 KPI 대시보드 진행 중이므로 frontend Wave 4 는 #8 완료 후.

---

## 5. 도메인 가정값 (P4 채택)

| 항목 | 표준값 | 근거 |
|---|---|---|
| 보수교육 의무 시간 | 12 시간/년 | 보험업법 시행령 제17조 |
| 자격증 갱신 주기 | 5 년 | 보험업감독규정 |
| 민원 환수 기준 | 13M 이내 민원 = 환수 100% | 일반 GA 사내 규정 가정 |
| 결재 최대 단계 | 3 단계 | 일반 운영 가정 |
| 첨부 최대 크기 | 50 MB | 시스템 기본값 |
| 출금 신청 마감 | 매월 25일 | 정산일 익월 5일 가정 |

가정값 → system_config / approval_line / training_requirement 등 외부화 가능 구조로 등록.

---

## 6. 일정 추정

| Wave | 예상 시간 |
|---|---|
| Wave 1 (dba) | 5~7분 |
| Wave 2 (core) | 8~12분 |
| Wave 3 (api) | 6~10분 |
| Wave 4 (frontend, #8 후) | 10~15분 |
| Wave 5 (infra) | 5~8분 |
| **합계** | **35~50분** |

배치/AOP 같은 추가 통합은 P5 라운드로 미룸.
동기화 2026-05-14 01:21:27 +09:00			`# 도메인 GAP 분석 & P4 기획서`

			`작성일: 2026-05-14`
			`작성자: PL (자율 모드)`
			`대상: 한국 GA(법인보험대리점) 수수료 정산 시스템`

			`---`

			`## 1. 현재까지의 도메인 커버리지 (P0~P3 + 부속)`

			`\| 영역 \| 적용 항목 \|`
			`\|---\|---\|`
			`\| 세무 (P0-1) \| 사업소득 3.3% / 기타소득 8.8% / 지방세 10% / VAT 10% \|`
			`\| 공제 (P0-2) \| 월별 차감 마스터(agent_deduction) + 이체 명세 \|`
			`\| 명세서 (P0-3) \| commission_statement + Excel 출력 \|`
			`\| 1200%룰 (P1-1) \| regulatory_limit + 한도 검증 + 분급 큐 \|`
			`\| 분급 (P1-2) \| installment_plan 7년 (35/25/15/10/7/5/3) \|`
			`\| 차등환수 (P1-3) \| chargeback_grade 5단계 \|`
			`\| 마감/정정/이의/보류 (P2-1~4) \| period_close / settle_correction / commission_dispute / hold_reason_code \|`
			`\| 시책·해촉·세금계산서·외부회신 (P2-5~8) \| incentive_program/payment / termination_settlement / tax_invoice / carrier_reconciliation_out \|`
			`\| KPI (P3) \| mv_monthly/org/retention/cumulative + Service + 화면 \|`

			`---`

			`## 2. 한국 GA 도메인에서 여전히 빠진 항목 (검토)`

			`### 2-A. 영업/계약 라이프사이클 (필수)`
			`- ❌ 청약(Proposal) → 청약→인수심사→체결 단계. 청약 수당(소액) 처리 부재`
			`- ❌ 인수심사 결과(Underwriting Result) — 거절/조건부 승인/할증 결과 추적`
			`- ❌ 계약 변경(Endorsement) — 보험료/피보험자/수익자 변경 시 수수료 재계산 트리거`
			`- ❌ 부활(Reinstatement) — 실효된 계약 부활 시 환수 처리 + 수수료 재산정`
			`- ❌ 계약 양도(Assignment) — 설계사 간 계약 이관 → 수수료 재배분`

			`### 2-B. 설계사 라이프사이클 (필수)`
			`- ❌ 위촉계약(Agent Contract) — 보험사-설계사 위촉계약서 + 위촉수수료`
			`- ❌ 자격 관리(License) — 자격증 만료/갱신 알림 (생보/손보/변액)`
			`- ❌ 보수교육(Training) — 의무 교육 시간 추적 (감독규정 12시간/년)`
			`- ❌ 징계 이력(Discipline) — 불완전판매 제재 → 환수 가중치`
			`- ❌ 휴직(Suspension) — 활동중지 기간 정산 제외`

			`### 2-C. 회계/재무 (필수)`
			`- ❌ 회계 전표(Accounting Entry) — 수수료 지급액 자동 분개`
			`- ❌ 출금 신청 워크플로우(Withdraw Request) — 결재 → 펌뱅킹 → 결과`
			`- ❌ 원천세 신고서(Tax Report) — 분기 사업소득세 신고 자료 집계`
			`- ❌ 부가세 신고 자료 — 매출/매입 집계 (세금계산서 기반)`
			`- ❌ 결산(Period Settlement) — period_close 와 별개의 월/분기/연 회계 마감`

			`### 2-D. 컴플라이언스 (중요)`
			`- ❌ 민원 관리(Complaint) — 고객 민원 → 설계사 책임 추적 → 환수 트리거`
			`- ❌ 불완전판매 모니터링 — 13M/25M 유지율 기반 이상 탐지`
			`- ❌ 상품판매 자격 매트릭스 — 변액=변액자격필요, 매핑 검증`

			`### 2-E. 시스템/UX (필수)`
			`- ❌ 결재선/결재 요청(Approval) — 정산 확정/이의/시책 결재 워크플로우`
			`- ❌ 공지사항(Notice) + 개인 알림(UserNotification)`
			`- ❌ 첨부파일(Attachment) — 위촉계약서/민원자료 등 문서 저장`
			`- ❌ 사용자 알림 채널 — 메일/SMS 발송 큐`

			`### 2-F. 분석/리포트 보강 (있으면 좋음)`
			`- ❌ 이상치 탐지 (Outlier KPI)`
			`- ❌ 차월 예측 (예상 정산액)`
			`- ❌ 연말 지급명세서 — 설계사 연 사업소득 세무 자료 PDF`

			`---`

			`## 3. 우선순위 결정 (PL 판단)`

			`> 추가 검토 (2026-05-14): 사용자 지적 — "오버라이드 / 수금수수료 같은 수수료 종류 정보가 많이 빠짐".`
			`> P4-A 로 수수료 종류 보강 5개 도메인을 우선 배치하고, 운영 9 도메인을 P4-B 로 후위 배치.`

			`### P4-A — 수수료 종류 보강 (5 도메인) ⭐ 사용자 지적 반영`
			`\| # \| 도메인 \| 마이그레이션 \| 핵심 \|`
			`\|---\|---\|---\|---\|`
			`\| P4-A-1 \| commission_type 코드 + 통합 마스터 \| V40 \| 모집/유지/수금/오버라이드/갱신/부활/유지보수수당/시책/위촉 9종 통합 코드 + commission_master 마스터 \|`
			`\| P4-A-2 \| 수금수수료 (collection_commission_rule + collection_commission_ledger) \| V41 \| 보험료 수납 단위(월) 발생. 납입주기별 차등 + 원장 \|`
			`\| P4-A-3 \| 갱신/부활 수수료 (renewal_commission, reinstatement_commission) \| V42 \| 자동차/실비 갱신 + 실효 부활 시 별도 수수료 룰·원장 \|`
			`\| P4-A-4 \| 유지보수수당 (persistency_bonus_rule + persistency_bonus) \| V43 \| 13M/25M/37M 유지율 충족 1회 지급. 등급별 정액 또는 정률 \|`
			`\| P4-A-5 \| 오버라이드 보강 (override_ledger + override_summary) \| V44 \| 기존 override_rule + 8 Step 결과를 원장 단위로 추적. 직급별/조직별 합계 + 검증 \|`

			`### P4-B — 운영 필수 9 도메인 (P4-A 완료 후)`
			`\| # \| 도메인 \| 마이그레이션 \| 핵심 \|`
			`\|---\|---\|---\|---\|`
			`\| P4-B-1 \| 위촉계약 (agent_contract) \| V45 \| 보험사-설계사 위촉계약서 + 위촉수수료 + 효력 기간 \|`
			`\| P4-B-2 \| 자격 관리 (agent_license) \| V46 \| 생보/손보/변액 자격증 + 만료일 + 갱신 이력 \|`
			`\| P4-B-3 \| 보수교육 (agent_training) \| V47 \| 교육 이수 시간 + 의무 12시간/년 충족 여부 \|`
			`\| P4-B-4 \| 계약 변경 (contract_endorsement) \| V48 \| 변경 유형(보험료/수익자/피보험자) + 수수료 재계산 트리거 \|`
			`\| P4-B-5 \| 민원 관리 (complaint) \| V49 \| 고객 민원 + 설계사 책임 + 처리 상태 + 환수 연동 \|`
			`\| P4-B-6 \| 결재 워크플로우 (approval_line + approval_request) \| V50 \| 결재선 마스터 + 다단 결재 요청/처리 \|`
			`\| P4-B-7 \| 공지사항 + 알림 (notice + user_notification) \| V51 \| 시스템 공지 + 사용자별 알림 (읽음 여부) \|`
			`\| P4-B-8 \| 첨부파일 (attachment) \| V52 \| 도메인 무관 공통 첨부 (소속/파일경로/타입) \|`
			`\| P4-B-9 \| 출금 신청 (withdraw_request) \| V53 \| 결재 + 펌뱅킹 송신 + 결과 반영 워크플로우 \|`

			`메뉴 INSERT 는 V54 한 파일에서 P4-A + P4-B 14개 메뉴 한 번에 등록.`

			`### P5 — 회계/분석 보강 (별도 라운드)`
			`- 회계 전표 자동 분개 / 원천세·부가세 신고 자료 / 결산 / 이상치·예측 KPI / 연말 지급명세서`

			`### P6 — 모바일/외부 연동 (제일 후속)`
			`- 펌뱅킹 실연동 / 모바일 셀프 조회 / SMS/카카오 발송`

			`이번 라운드는 P4 만 일괄 진행. P5/P6 는 다음 라운드에서.`

			`---`

			`## 4. P4 이행 계획 (Wave 방식, 이미 검증된 패턴)`

			`\| Wave \| 담당 \| 산출물 \|`
			`\|---\|---\|---\|`
			`\| Wave 1 \| dba-architect \| V40~V48 9개 + V49 메뉴 INSERT (총 10 파일) \|`
			`\| Wave 2 \| core-architect \| P4 VO/Resp/SaveReq/SearchParam + Mapper(IF+XML) + Enum \|`
			`\| Wave 3 \| api-developer \| Service + Controller + 결재 AOP (또는 Service 가드) \|`
			`\| Wave 4 \| frontend-developer \| 화면 9개 (토스 톤 일관) + 라우터 + Route 등록 \|`
			`\| Wave 5 \| infra-reviewer \| 빌드/통합 검증 + README/HANDOFF 갱신 + 메뉴 적용 \|`

			`병렬화: Wave 1↔3 의존, Wave 4 는 Wave 3 후, Wave 5 는 마지막. 단 #8 KPI 대시보드 진행 중이므로 frontend Wave 4 는 #8 완료 후.`

			`---`

			`## 5. 도메인 가정값 (P4 채택)`

			`\| 항목 \| 표준값 \| 근거 \|`
			`\|---\|---\|---\|`
			`\| 보수교육 의무 시간 \| 12 시간/년 \| 보험업법 시행령 제17조 \|`
			`\| 자격증 갱신 주기 \| 5 년 \| 보험업감독규정 \|`
			`\| 민원 환수 기준 \| 13M 이내 민원 = 환수 100% \| 일반 GA 사내 규정 가정 \|`
			`\| 결재 최대 단계 \| 3 단계 \| 일반 운영 가정 \|`
			`\| 첨부 최대 크기 \| 50 MB \| 시스템 기본값 \|`
			`\| 출금 신청 마감 \| 매월 25일 \| 정산일 익월 5일 가정 \|`

			`가정값 → system_config / approval_line / training_requirement 등 외부화 가능 구조로 등록.`

			`---`

			`## 6. 일정 추정`

			`\| Wave \| 예상 시간 \|`
			`\|---\|---\|`
			`\| Wave 1 (dba) \| 5~7분 \|`
			`\| Wave 2 (core) \| 8~12분 \|`
			`\| Wave 3 (api) \| 6~10분 \|`
			`\| Wave 4 (frontend, #8 후) \| 10~15분 \|`
			`\| Wave 5 (infra) \| 5~8분 \|`
			`\| 합계 \| 35~50분 \|`

			`배치/AOP 같은 추가 통합은 P5 라운드로 미룸.`