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

> 작성일: 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: 파일 구조 및 타입 정의
- [x] 1.1 `src/components/accounting/BadDebtCollection/types.ts` 생성
  - BadDebtRecord 인터페이스
  - CollectionStatus 타입 (추심중, 법적조치, 회수완료, 대손처리)
  - SortOption 타입
  - 상태 라벨/컬러 상수
- [x] 1.2 `src/app/[locale]/(protected)/accounting/bad-debt-collection/page.tsx` 생성
- [x] 1.3 `src/app/[locale]/(protected)/accounting/bad-debt-collection/[id]/page.tsx` 생성
- [x] 1.4 `src/app/[locale]/(protected)/accounting/bad-debt-collection/[id]/edit/page.tsx` 생성
- [x] 1.5 `src/app/[locale]/(protected)/accounting/bad-debt-collection/new/page.tsx` 생성

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

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

### Phase 4: 연동 기능 구현
- [x] 4.1 어음관리 페이지 수정 - vendorId 쿼리 파라미터 지원
- [x] 4.2 미수금 현황 페이지 수정 - highlight 쿼리 파라미터 지원 (해당 거래처 행 하이라이트)

### Phase 5: 최종 검증 및 문서화
- [x] 5.1 리스트 페이지 테스트
- [x] 5.2 상세/수정/등록 페이지 테스트
- [x] 5.3 어음관리 연동 테스트
- [x] 5.4 미수금 현황 연동 테스트
- [x] 5.5 모바일 반응형 테스트
- [x] 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}`
- **동작**: 해당 거래처 행을 하이라이트 표시

---

## 📝 작업 완료 후 체크

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

---

## ✅ 구현 완료

> 완료일: 2025-12-19