sam-react-prod/claudedocs/accounting/[IMPL-2025-12-19] bad-debt-collection-management.md

악성채권 추심관리 구현 계획서

작성일: 2025-12-19 URL: /ko/accounting/bad-debt-collection

---

📋 스크린샷 분석 요약

리스트 화면

• 제목: 악성채권 추심관리
• 통계 카드 4개: 총 악성채권, 추심중, 법적조치, 회수완료
• 필터 3개:
  1. 거래처 필터 (검색 + 다중선택, 디폴트: 전체)
  2. 상태 필터 (전체, 추심중, 법적조치, 회수완료, 대손처리)
  3. 정렬 (최신순, 등록순, 디폴트: 최신순)
• 테이블 컬럼: No., 거래처, 채권금액, 발생일, 연체일수, 담당자, 상태, 설정, 작업
• 설정 컬럼: ON/OFF 토글
• 작업 컬럼: 수정/삭제 아이콘

상세 화면 (view/edit/new 모드)

1. 기본 정보: 사업자등록번호, 거래처코드, 거래처명, 대표자명, 거래처유형(토글), 악성채권등록(업태/업종)
2. 연락처 정보: 주소(우편번호 찾기), 전화번호, 모바일, 팩스, 이메일
3. 담당자 정보: 담당자명, 담당자전화, 시스템관리자
4. 필요 서류: 사업자등록증, 세금계산서, 추가서류 (파일 첨부)
5. 악성 채권 정보:
   • 미수금 + 상태 셀렉트 (추심중, 법적조치, 회수완료, 대손처리)
   • 연체일수 + 본사 담당자 셀렉트 (부서명 이름 직급명 연락처)
   • 악성채권 발생일 / 종료일
   • 수취 어음 현황 버튼 → 어음관리 화면 (해당 거래처 필터)
   • 거래처 미수금 현황 버튼 → 미수금 현황 화면 (해당 거래처 하이라이트)
6. 메모: 타임스탬프 형식 메모 목록

---

✅ 구현 체크리스트

Phase 1: 파일 구조 및 타입 정의

• 1.1 src/components/accounting/BadDebtCollection/types.ts 생성
  • BadDebtRecord 인터페이스
  • CollectionStatus 타입 (추심중, 법적조치, 회수완료, 대손처리)
  • SortOption 타입
  • 상태 라벨/컬러 상수
• 1.2 src/app/[locale]/(protected)/accounting/bad-debt-collection/page.tsx 생성
• 1.3 src/app/[locale]/(protected)/accounting/bad-debt-collection/[id]/page.tsx 생성
• 1.4 src/app/[locale]/(protected)/accounting/bad-debt-collection/[id]/edit/page.tsx 생성
• 1.5 src/app/[locale]/(protected)/accounting/bad-debt-collection/new/page.tsx 생성

Phase 2: 리스트 컴포넌트 구현

• 2.1 src/components/accounting/BadDebtCollection/index.tsx 생성
  • IntegratedListTemplateV2 사용
• 2.2 통계 카드 4개 구현 (총 악성채권, 추심중, 법적조치, 회수완료)
• 2.3 필터 3개 구현
  • 거래처 필터 (검색 + 다중선택)
  • 상태 필터 (전체, 추심중, 법적조치, 회수완료, 대손처리)
  • 정렬 (최신순, 등록순)
• 2.4 테이블 컬럼 구현 (체크박스 + No. + 거래처 + 채권금액 + 발생일 + 연체일수 + 담당자 + 상태 + 설정 + 작업)
  • No.: 순번 (1부터)
  • 거래처: 거래처명
  • 채권금액: 금액 (원)
  • 발생일: YYYY-MM-DD
  • 연체일수: 숫자 + "일"
  • 담당자: 담당자명
  • 상태: Badge (추심중/법적조치/회수완료/대손처리)
  • 설정: ON/OFF 토글 (Switch)
  • 작업: 수정/삭제 아이콘 (row 선택 시 표시)
• 2.5 Mock 데이터 생성 함수
• 2.6 행 클릭 → 상세 페이지 이동 기능
• 2.7 모바일 카드 렌더링

Phase 3: 상세/수정/등록 컴포넌트 구현

• 3.1 src/components/accounting/BadDebtCollection/BadDebtDetail.tsx 생성
  • mode prop (view/edit/new)
• 3.2 기본 정보 섹션
  • 사업자등록번호 (Input, readonly)
  • 거래처 코드 (Input, readonly)
  • 거래처명 (Input)
  • 대표자명 (Input)
  • 거래처 유형 (Switch - 매출매입)
  • 악성채권 등록 - 업태 (Input)
  • 악성채권 등록 - 업종 (Input)
• 3.3 연락처 정보 섹션
  • 주소 (우편번호 찾기 버튼 + Input 3개)
  • 전화번호 (Input)
  • 모바일 (Input)
  • 팩스 (Input)
  • 이메일 (Input)
• 3.4 담당자 정보 섹션
  • 담당자명 (Input)
  • 담당자 전화 (Input)
  • 시스템 관리자 (Input, readonly)
• 3.5 필요 서류 섹션
  • 사업자등록증 (파일 찾기)
  • 세금계산서 (파일 찾기)
  • 추가 서류 (파일 찾기 + 추가 버튼 + 삭제 X)
• 3.6 악성 채권 정보 섹션
  • 미수금 (Input, readonly)
  • 상태 (Select: 추심중, 법적조치, 회수완료, 대손처리)
  • 연체일수 (Switch + Input)
  • 본사 담당자 (Select: 부서명 이름 직급명 연락처)
  • 악성채권 발생일 (DatePicker)
  • 악성채권 종료일 (DatePicker)
  • 수취 어음 현황 버튼 → /ko/accounting/bills?vendorId={id}&type=received
  • 거래처 미수금 현황 버튼 → /ko/accounting/receivables-status?highlight={id}
• 3.7 메모 섹션
  • 메모 목록 (Textarea, readonly)
  • 메모 추가 기능 (타임스탬프 자동 생성)
• 3.8 삭제/수정 버튼 및 다이얼로그
• 3.9 저장 기능 (mock)

Phase 4: 연동 기능 구현

• 4.1 어음관리 페이지 수정 - vendorId 쿼리 파라미터 지원
• 4.2 미수금 현황 페이지 수정 - highlight 쿼리 파라미터 지원 (해당 거래처 행 하이라이트)

Phase 5: 최종 검증 및 문서화

• 5.1 리스트 페이지 테스트
• 5.2 상세/수정/등록 페이지 테스트
• 5.3 어음관리 연동 테스트
• 5.4 미수금 현황 연동 테스트
• 5.5 모바일 반응형 테스트
• 5.6 [REF] all-pages-test-urls.md 업데이트

---

📁 파일 구조

src/
├── app/[locale]/(protected)/accounting/
│   └── bad-debt-collection/
│       ├── page.tsx                    # 리스트 페이지
│       ├── new/
│       │   └── page.tsx                # 등록 페이지
│       └── [id]/
│           ├── page.tsx                # 상세 페이지
│           └── edit/
│               └── page.tsx            # 수정 페이지
└── components/accounting/
    └── BadDebtCollection/
        ├── index.tsx                   # 리스트 컴포넌트
        ├── BadDebtDetail.tsx           # 상세/수정/등록 컴포넌트
        └── types.ts                    # 타입 정의

---

🔗 URL 구조

페이지	URL	비고
리스트	/ko/accounting/bad-debt-collection	메인
등록	/ko/accounting/bad-debt-collection/new
상세	/ko/accounting/bad-debt-collection/[id]
수정	/ko/accounting/bad-debt-collection/[id]/edit

---

📊 테이블 컬럼 상세

컬럼	key	label	정렬	비고
체크박스	checkbox	-	center	Checkbox
번호	no	No.	center	1부터 시작
거래처	vendorName	거래처	left
채권금액	debtAmount	채권금액	right	1,000,000원
발생일	occurrenceDate	발생일	center	YYYY-MM-DD
연체일수	overdueDays	연체일수	center	100일
담당자	managerName	담당자	left
상태	status	상태	center	Badge
설정	settingToggle	설정	center	Switch
작업	actions	작업	center	수정/삭제

---

🎨 상태 Badge 스타일

상태	라벨	스타일
collecting	추심중	border-orange-300 text-orange-600 bg-orange-50
legalAction	법적조치	border-red-300 text-red-600 bg-red-50
recovered	회수완료	border-green-300 text-green-600 bg-green-50
badDebt	대손처리	border-gray-300 text-gray-600 bg-gray-50

---

🔍 필터 상세

1. 거래처 필터

• 타입: 검색 + 다중선택 (Combobox/MultiSelect)
• 옵션: 전체, 거래처 목록 (API)
• 디폴트: 전체

2. 상태 필터

• 타입: Select
• 옵션: 전체, 추심중, 법적조치, 회수완료, 대손처리
• 디폴트: 악성채권 설정 시 디폴트 상태

3. 정렬

• 타입: Select
• 옵션: 최신순, 등록순
• 디폴트: 최신순

---

🔗 연동 기능

수취 어음 현황 버튼

• 대상: 어음관리 페이지 (/ko/accounting/bills)
• 쿼리: ?vendorId={id}&type=received
• 동작: 해당 거래처의 수취 어음만 필터링하여 표시

거래처 미수금 현황 버튼

• 대상: 미수금 현황 페이지 (/ko/accounting/receivables-status)
• 쿼리: ?highlight={id}
• 동작: 해당 거래처 행을 하이라이트 표시

---

📝 작업 완료 후 체크

• claudedocs/[REF] all-pages-test-urls.md 업데이트
• 빌드 오류 없음 확인
• 리스트/상세/수정/등록 페이지 정상 작동
• 연동 페이지 정상 작동

---

✅ 구현 완료

완료일: 2025-12-19