사건 상세 — 회수 탭 debt 분기 화면 설계

관련 기능: 채권 계산 엔진 · 서류 자동 생성 관련 ADR: 0010 회수 유형 UI 분기 · 0037 채권계산 탭 흡수

개요

사건 상세 회수 탭 의 recoveryType === "debt" 분기 화면. 대여·변제 인라인 편집 + 3뷰 결과 + 청구취지 생성 + 스냅샷 관리.

명칭 이력: ADR 0010 (2026-04-22) 으로 단일 회수 탭 도입, ADR 0037 (2026-05-06) 로 별도 ?tab=debt-settlement (채권계산) 탭이 제거되어 회수 탭의 debt 분기로 일원화됐다. 본 문서가 다루는 화면은 회수 탭 debt 분기에서 그대로 살아 있다 (DebtSettlementTab.tsx 컴포넌트가 RecoveryTab 의 debt 분기에서 wrap). ?tab=debt-settlement deep link 는 parseTab 에서 recovery 로 자동 정규화.

탭 위치

사건 상세 탭 순서 (ADR 0037 후):

overview | documents | evidence | hearings | recovery | messages | notes

회수 탭 진입 후 recoveryType === "debt" 분기에서 본 화면이 렌더된다. 비-debt 사건 (Pack 2~5) 은 같은 회수 탭의 도메인별 분기 (NonDebtRecoveryRouter) 로 빠진다.

사용자 여정

첫 방문 (빈 상태)

1. 변호사·사무원이 "회수" 탭 클릭 (대여금 사건은 자동으로 debt 분기 화면 진입)
2. 빈 상태 "대여 내역을 입력하세요" 카드 + "CSV 붙여넣기" / "수기 입력" CTA
3. 대여 1건 입력 후 실시간 계산 결과 (0건 변제 = 원금+이자만)

반복 사용

1. 의뢰인 전화 → 변제 1건 추가 요청
2. 변제 섹션 하단 "+ 행 추가" (Cmd+Enter 단축키)
3. 날짜·금액 입력 → 실시간 재계산
4. 결과 카드 갱신 · 스냅샷 영향 없음 (기존 스냅샷 불변)

소장 첨부본 스냅샷

1. 계산 결과 만족 → "스냅샷 저장" 클릭
2. 이름 입력 ("소장 첨부본 2026-02-10")
3. 기산일·법정/지정 충당 플래그 고정
4. 동결 상태로 저장 · "청구취지 생성" 버튼 활성화

전체 화면 구조 (ASCII 와이어)

┌─ 사건 상세 > 김철수 vs 박영희 > 회수 (대여금) ─────── [청구취지 생성] ┐
│                                                                      │
│ [시나리오 A · 의뢰인] [B · 상대방] [+]   계산방식: ⦿개별 ○잔액      │
│                                                                      │
│ ▼ 대여 내역                                                   3건   │
│ ┌──────────┬─────────────┬──────────┬──────────┬──────────────┐    │
│ │ 날짜      │ 원금        │ 이자율   │ 기산일   │ 비고         │    │
│ ├──────────┼─────────────┼──────────┼──────────┼──────────────┤    │
│ │ 2024.03.01│ 50,000,000 │ 연 12%   │ 대여일   │ 계약서 #1    │    │
│ │ 2024.07.15│ 20,000,000 │ 연 12%   │ 대여일   │ 계약서 #2    │    │
│ │ 2024.11.20│ 10,000,000 │ 연 5%(법)│ 대여일   │ 구두 약정    │    │
│ │ [+ 행 추가]                                                   │    │
│ └──────────────────────────────────────────────────────────────┘    │
│                                                                      │
│ ▼ 변제 내역                                                   5건   │
│ ┌──────────┬──────────┬────────────────────────┬──────────────┐    │
│ │ 날짜      │ 금액     │ 충당: 원금/이자/지연    │ 비고         │    │
│ ├──────────┼──────────┼────────────────────────┼──────────────┤    │
│ │ 2024.09.10│ 8,000,000│ 0 / 3,200k / 4,800k ▸ │ 계좌 입금    │    │
│ │ 2025.01.20│10,000,000│ 7,000k / 1,500k / 1,500k│ 계좌 입금    │    │
│ │ 2025.05.15│ 5,000,000│ 3,200k / 1,100k / 700k │ 현금         │    │
│ │ 2025.09.01│ 3,000,000│ 2,100k / 500k / 400k   │ 계좌         │    │
│ │ 2026.01.10│12,000,000│ 9,000k / 2,100k / 900k │ 계좌         │    │
│ │ [+ 행 추가] [📋 CSV 붙여넣기]                                  │    │
│ └──────────────────────────────────────────────────────────────┘    │
│                                                                      │
│ ╔══ 계산 결과 ═══════════════════════════ 기준일 2026.04.20 ═══════╗│
│ ║                                                                   ║│
│ ║  원금잔액      이자합계       지연손해금     합계                  ║│
│ ║  42,000,000   6,340,000     1,180,000    49,520,000              ║│
│ ║                                                                   ║│
│ ║  [ 요약 ] [ 충당표 ] [ 타임라인 ]         [B 대비 +3,240,000]     ║│
│ ║                                                                   ║│
│ ║  📎 참고: 사무소 기억 2건 · 대법원 판례 3건                        ║│
│ ║                                                                   ║│
│ ╚═══════════════════════════════════════════════════════════════════╝│
│                                                                      │
│ ▼ 스냅샷 (3)                                                         │
│   · 소장 첨부본 (2026-02-10) · 원장잔액 45,200k · [열기]            │
│   · 준비서면 v1 (2026-03-15) · 원장잔액 43,800k · [열기]            │
│   · 준비서면 v2 (2026-04-03) · 원장잔액 42,500k · [열기]            │
│   [+ 현재 상태를 스냅샷으로 저장]                                    │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

컴포넌트 스펙

1. 상단 툴바

• 시나리오 탭 (Phase 1+): 의뢰인 주장 A / 상대방 주장 B / [+] 추가
• 계산방식 라디오: ⦿개별 (A방식) / ○잔액 (B방식)
• 청구취지 생성 버튼: 우상단, 스냅샷 없을 시 비활성화

Phase 0 제약: 시나리오 탭은 A 고정 · 계산방식 잔액은 "Phase 1 예정" 다이얼로그만

2. 대여·변제 인라인 편집 테이블

키보드 네비:

• Tab: 다음 셀
• Shift+Tab: 이전 셀
• Enter: 같은 열 아래 셀
• Cmd+Enter: 새 행 추가
• Esc: 편집 취소

셀 유형:

• 날짜: <input type="date"> · KST 포맷 자동 · todayKST() 기본값
• 금액: 한글 쉼표 자동 (Intl.NumberFormat("ko-KR")), 정수 원
• 이자율: 프리셋 드롭다운 ("연 5% (민사 법정)", "연 6% (상사)", "연 12% (소촉법)", "연 15%", "연 20% (이자제한 상한)", "수기")
• 기산일: 프리셋 ("대여일", "이행기", "소제기일", "판결선고일", "수기")
• 비고: 자유 텍스트 + 증거 링크 (차용증·계약서 업로드 영역)

행 작업:

• 행 선택 → Delete 키 삭제 (확인 다이얼로그)
• 드래그 정렬 (날짜순 자동 정렬도 토글)

3. CSV 붙여넣기 모달

변제 섹션 하단 [📋 CSV 붙여넣기] 클릭 시:

┌─ CSV 붙여넣기 ────────────────────────────────┐
│                                                │
│ 은행 선택: [ 국민은행 ▾ ]                      │
│           │ 국민·카카오뱅크·토스뱅크 (Phase 0)│
│           │ 기타 포맷 수기 ▾                  │
│                                                │
│ ┌──────────────────────────────────────────┐ │
│ │ 여기에 엑셀·CSV 붙여넣기 (Ctrl+V)         │ │
│ │                                           │ │
│ │ (첫 5행 미리보기)                         │ │
│ └──────────────────────────────────────────┘ │
│                                                │
│ 컬럼 매핑:                                     │
│   거래일 → [ 거래일시 ▾ ]                      │
│   금액   → [ 입금액   ▾ ]                      │
│   적요   → [ 적요     ▾ ]                      │
│                                                │
│ 자동 분류 (규칙): 12건 중 10건 "변제"·2건 제외│
│ [ 검토 ]                                       │
└────────────────────────────────────────────────┘

• 중복 방지: (거래일+금액+적요) 해시
• 정상 중복 (급여·월세) 경고 배지만, 차단 아님
• 미확실 건은 "미분류" 상태로 수동 배치

4. 결과 카드 (3뷰 토글)

요약 뷰 (기본):

• 큰 숫자 4개 (원금잔액·이자합계·지연손해금·합계)
• 기준일 (기본 오늘, 수정 가능)
• B 대비 diff (Phase 1+)
• "참고 자료" 서브: 사무소 기억·공개 판례 개수

충당표 뷰:

┌─ 충당표 (별지 계산서) ──────────────────────────┐
│                                                  │
│ 일자         거래        원금잔액  이자잔액  지연│
│ 2024.03.01   대여 #1    50,000k    -        -   │
│ 2024.07.15   대여 #2    70,000k    -        -   │
│ 2024.09.10   변제 1     70,000k  -3,200k  -4,800k│
│             ↳ 충당: 이자 3,200k·지연 4,800k     │
│             │ 수식: 50,000k × 12% × 193일/365   │
│             │       = 3,172,602원 (원미만 절사) │
│ ...                                              │
│                                                  │
│ [ 💾 PDF 다운로드 ] [ 📊 CSV 내보내기 ]         │
└──────────────────────────────────────────────────┘

타임라인 뷰:

• 세로 타임라인 + 연결선
• 각 변제 → 어느 대여의 이자·원금에 충당됐는지 호버 툴팁
• 인쇄·PDF 친화 (산키 다이어그램 ❌ — 법원 부적합)

5. 비슷한 과거 기억 사이드 패널 (Phase 1)

결과 카드 우측:

┌─ 비슷한 과거 기억 ──────────┐
│ 🏆 2023 대여금              │
│    박철수 vs 김영수          │
│    원고 승소                 │
│    전략: 필적감정            │
│    [서류 3건]                │
│                             │
│ ⚖️ 2021 대여금              │
│    이순신 vs 강감찬          │
│    조정 성립                 │
│    전략: 시효 항변           │
│                             │
│ [더 보기]                    │
└─────────────────────────────┘

6. 스냅샷 목록

화면 하단:

• 이름·기산일·잔액·[열기] 버튼
• 기존 스냅샷 불변 (편집 불가, 열람만)
• [+ 현재 상태를 스냅샷으로 저장] → 이름 입력 다이얼로그

7. 청구취지 생성 다이얼로그

우상단 [청구취지 생성] 버튼 클릭 시:

┌─ 청구취지 생성 ────────────────────────────────┐
│                                                  │
│ 기준 스냅샷: [ 준비서면 v2 (2026-04-03) ▾ ]    │
│                                                  │
│ 프리셋 선택:                                     │
│   ⦿ 청구취지형 (표준 법원 제출용)               │
│   ○ 준비서면 계산표형 (마크다운 표)             │
│   ○ 엑셀 CSV (xlsx 다운로드)                    │
│                                                  │
│ ┌─ 미리보기 ─────────────────────────────┐    │
│ │ 피고는 원고에게 금 49,520,000원 및 이에 │    │
│ │ 대한 2026.2.15.부터 다 갚는 날까지 연    │    │
│ │ 12% 의 비율로 계산한 돈을 지급하라.     │    │
│ └─────────────────────────────────────────┘    │
│                                                  │
│ [📋 복사] [💾 다운로드] [📎 서류에 삽입]       │
│                                                  │
│ ※ AI 생성 아님 · 결정론 템플릿 치환            │
└──────────────────────────────────────────────────┘

상태 디자인

로딩

• 계산 중: 결과 카드에 스켈레톤 · 입력 필드는 사용 가능 (비차단)
• CSV 파싱 중: 모달 내 스피너 · 5초 이상 시 "오래 걸리고 있어요" 메시지

에러

에러 코드	UI
SETTLEMENT_INPUT_INVALID	해당 입력 필드 빨간 테두리 + 에러 메시지 (예: "음수 원금은 입력 불가")
SETTLEMENT_RATE_MISSING	"이 기간의 이자율이 없습니다. 법정이자 5% 로 추정?" 제안 버튼
SETTLEMENT_SNAPSHOT_STALE	"동결된 스냅샷은 수정 불가. 새 스냅샷을 만드세요." 안내
네트워크 에러	"연결이 끊겼습니다. [재시도]" (작성 중 데이터는 로컬 임시 보존)

빈 상태

• 대여 0건: "대여 내역을 입력하세요" + CSV 업로드 / 수기 입력 CTA
• 변제 0건: "변제 내역 입력 (선택)" + "변제 없음" 체크박스
• 스냅샷 0건: "첫 스냅샷을 저장해보세요 (소장 첨부본·준비서면 버전 관리)"

시맨틱 토큰 (CLAUDE.md 원칙)

• 배경: bg-card · 테두리 border-border
• 텍스트: text-foreground · 보조 text-muted-foreground
• 강조: bg-muted/50 (호버), hover:bg-accent
• 숫자·금액: tabular-nums class · 오른쪽 정렬
• 대여 행 좌측: border-l-4 border-l-emerald-500 (4px 컬러 바)
• 변제 행 좌측: border-l-4 border-l-blue-500
• 지연손해금 배지: bg-amber-500/10 text-amber-700

하드코딩 금지 (CLAUDE.md): text-white/XX·bg-white/[0.XX]·인라인 스타일·hex 리터럴.

접근성

• 모든 버튼 aria-label (아이콘 버튼 포함)
• 테이블 <table> 시맨틱 + <caption> 스크린리더용
• 키보드만으로 모든 기능 사용 가능
• 색상만으로 정보 전달 금지 (배지는 아이콘 + 텍스트 병기)

기술 노트

• Next.js 16 Server Component (기본) + Client Component (인라인 편집)
• Firestore onSnapshot 실시간 동기화 → serializeFirestoreValue 필수
• 순수 계산 함수는 Client Component 에서 직접 호출 (Server Action 안 거침)
• 저장·스냅샷 생성만 Server Action

관련 문서

• 채권 계산 엔진 기능 정의서
• CSV 은행 파서 기능 정의서 (작성 예정)
• Pack 1 데이터 모델 (작성 예정)