sam-react-prod/claudedocs/accounting/[IMPL-2025-12-18] vendor-management-checklist.md

거래처 관리 (Vendor Management) 구현 체크리스트

상태: ✅ 완료 (2025-12-18) 리스트 수정: ✅ 완료 (2025-12-18) - 필터/액션버튼/신규등록 수정

개요

• 경로: /accounting/vendors (리스트), /accounting/vendors/[id] (상세), /accounting/vendors/new (신규등록)
• 기능: 거래처 등록, 조회, 수정, 삭제
• 참고: 스크린샷 4장 (리스트 1장, 상세 3장)

---

Phase 1: 타입 및 상수 정의 ✅

1.1 types.ts 생성

• 거래처 구분 타입 (VendorCategory): sales | purchase | both
• 신용등급 타입 (CreditRating): AAA | AA | A | BBB | BB | B | CCC | CC | C | D
• 거래등급 타입 (TransactionGrade): A | B | C | D | E
• 악성채권 상태 타입 (BadDebtStatus): none | normal | warning
• 정렬 옵션 타입 (SortOption)
• 거래처 인터페이스 (Vendor)
  • id, vendorCode, businessNumber
  • vendorName, representativeName
  • category (sales/purchase/both)
  • businessType, businessCategory
  • address (zipCode, address1, address2)
  • phone, mobile, fax, email
  • managerName, managerPhone, systemManager
  • logoUrl
  • purchasePaymentDay, salesPaymentDay
  • creditRating, transactionGrade
  • taxInvoiceEmail, bankName, accountNumber, accountHolder
  • outstandingAmount, overdueAmount, overdueDays
  • unpaidAmount, badDebtStatus
  • overdueToggle, badDebtToggle
  • memos: Memo[]
  • createdAt, updatedAt

1.2 상수 정의

• VENDOR_CATEGORY_OPTIONS (구분 필터)
• CREDIT_RATING_OPTIONS (신용등급 필터)
• TRANSACTION_GRADE_OPTIONS (거래등급 필터)
• BAD_DEBT_STATUS_OPTIONS (악성채권 필터)
• SORT_OPTIONS (정렬 옵션)
• PAYMENT_DAY_OPTIONS (결제일 1~31일)
• BANK_OPTIONS (은행 목록)

---

Phase 2: 리스트 페이지 구현 ✅

2.1 페이지 라우트 생성

• /src/app/[locale]/(protected)/accounting/vendors/page.tsx 생성

2.2 VendorManagement 컴포넌트

• /src/components/accounting/VendorManagement/index.tsx 생성

2.2.1 상단 통계 카드 (3개)

카드	값	아이콘 색상
전체 거래처	{count}개	blue
매출 거래처	{count}개	green
매입 거래처	{count}개	orange

2.2.2 필터 조건 (5개 셀렉트박스)

필터	옵션	기본값
구분	전체, 매출, 매입, 매입매출	전체
신용등급	전체, AAA, AA, A, BBB, BB, B, CCC, CC, C, D	전체
거래등급	전체, A(우수), B(양호), C(보통), D(주의), E(위험)	전체
악성채권	전체, 미설정, 정상	전체
정렬	최신순, 등록순, 거래처명 오름차순, 거래처명 내림차순, 미수금 높은순, 미수금 낮은순	최신순

2.2.3 테이블 컬럼 (체크박스 + 9개)

순서	컬럼명	정렬	비고
0	체크박스	center	-
1	번호	center	globalIndex + 1
2	구분	center	Badge (매출/매입/매입매출)
3	거래처명	left	-
4	매입 결제일	center	{n}일
5	매출 결제일	center	{n}일
6	신용등급	center	Badge
7	거래등급	center	Badge
8	미수금	right	금액 포맷
9	악성채권	center	Badge or -

2.2.4 행 선택 시 버튼

• 상세 버튼 → /accounting/vendors/{id} 이동
• 수정 버튼 → /accounting/vendors/{id}?mode=edit 이동
• 삭제 버튼 → 삭제 확인 AlertDialog
• 취소 버튼 → 선택 해제

2.2.5 헤더 액션

• 신규등록 버튼 → /accounting/vendors/new 이동

---

Phase 3: 상세/수정/등록 페이지 구현 ✅

3.1 페이지 라우트 생성

• /src/app/[locale]/(protected)/accounting/vendors/[id]/page.tsx (상세/수정)
• /src/app/[locale]/(protected)/accounting/vendors/new/page.tsx (신규등록)

3.2 VendorDetail 컴포넌트

• /src/components/accounting/VendorManagement/VendorDetail.tsx 생성
• mode prop: view | edit | new

3.2.1 상단 버튼

모드	버튼
view	삭제, 수정
edit	취소, 저장
new	취소, 등록

3.2.2 기본 정보 섹션

필드명	타입	필수	비고
사업자등록번호	text (마스크: 000-00-00000)	*	-
거래처코드	text	-	자동생성 또는 수동입력
거래처명	text	*	-
대표자명	text	-	-
거래처 유형	select	*	매출매입, 매출, 매입
업태	text	-	-
업종	text	-	-

3.2.3 연락처 정보 섹션

필드명	타입	필수	비고
주소	address	-	우편번호 찾기 + 기본주소 + 상세주소
전화번호	tel	-	02-0000-0000
모바일	tel	-	010-0000-0000
팩스	tel	-	02-0000-0000
이메일	email	-	-

3.2.4 담당자 정보 섹션

필드명	타입	필수	비고
담당자명	text	-	-
담당자 전화	tel	-	-
시스템 관리자	text	-	-

3.2.5 회사 정보 섹션

필드명	타입	필수	비고
회사 로고	file	-	750x250px, 10MB 이하, PNG/JPEG/GIF
매입 결제일	select	-	1~31일
매출 결제일	select	-	1~31일

3.2.6 신용/거래 정보 섹션

필드명	타입	필수	비고
신용등급	select	-	AAA~D
거래등급	select	-	A(우수)~E(위험)
세금계산서 이메일	email	-	-
입금계좌 은행	select	-	은행 목록
계좌	text	-	숫자만
예금주	text	-	-

3.2.7 추가 정보 섹션

필드명	타입	필수	비고
미수금	number	-	금액 입력
연체	number + toggle	-	일수 + ON/OFF
미지급	number	-	금액 입력
악성채권	select + toggle	-	선택 + ON/OFF (악성채권 추심관리 연동)

3.2.8 메모 섹션

필드명	타입	비고
메모	textarea + list	추가 버튼으로 메모 리스트에 추가
메모 리스트	table	날짜, 내용, 삭제버튼

---

Phase 4: 다이얼로그 ✅

4.1 삭제 확인 다이얼로그

• AlertDialog 사용
• 제목: "거래처(명)을 삭제하시겠습니까?"
• 설명: 확인 클릭 시 거래처관리 목록으로 이동
• 버튼: 취소, 삭제

4.2 수정 확인 다이얼로그

• AlertDialog 사용
• 제목: "정말 수정하시겠습니까?"
• 설명: 확인 클릭 시 "수정이 완료되었습니다." 알림
• 버튼: 취소, 확인

---

Phase 5: 파일 구조 ✅

src/
├── app/[locale]/(protected)/accounting/vendors/
│   ├── page.tsx                    # 리스트 페이지 ✅
│   ├── [id]/
│   │   └── page.tsx                # 상세/수정 페이지 ✅
│   └── new/
│       └── page.tsx                # 신규등록 페이지 ✅
└── components/accounting/VendorManagement/
    ├── index.tsx                   # 리스트 컴포넌트 ✅
    ├── VendorDetail.tsx            # 상세/수정/등록 컴포넌트 ✅
    └── types.ts                    # 타입 및 상수 정의 ✅

---

구현 완료 요약

Step 1: 기본 구조 ✅

• types.ts 생성 및 타입/상수 정의
• 페이지 라우트 파일 생성

Step 2: 리스트 페이지 ✅

• index.tsx 생성
• IntegratedListTemplateV2 활용
• 통계 카드 (3개)
• 필터 (5개 셀렉트박스)
• 테이블 (체크박스 + 번호 + 9개 컬럼)
• 행 선택 시 버튼 (상세/수정/삭제/취소)
• 삭제 확인 다이얼로그

Step 3: 상세 페이지 ✅

• VendorDetail.tsx 생성
• 기본 정보 섹션
• 연락처 정보 섹션
• 담당자 정보 섹션
• 회사 정보 섹션 (로고 업로드 영역 포함)
• 신용/거래 정보 섹션
• 추가 정보 섹션 (토글 포함)
• 메모 섹션

Step 4: 수정/등록 기능 ✅

• mode별 버튼 및 동작 구현
• 수정/삭제 확인 다이얼로그

---

테스트 URL

페이지	URL
리스트	/ko/accounting/vendors
상세	/ko/accounting/vendors/vendor-1
수정	/ko/accounting/vendors/vendor-1?mode=edit
신규등록	/ko/accounting/vendors/new

---

참고 사항

공통 컴포넌트 사용

• IntegratedListTemplateV2 (리스트 템플릿)
• AlertDialog (삭제/수정 확인)
• Card, CardHeader, CardContent (섹션 구분)
• Select, Input, Textarea (폼 요소)
• Switch (토글)
• Badge (상태 표시)

스타일 가이드

• 주요 색상: orange (강조), blue/green (통계 카드)
• Badge 색상:
  • 구분: 매출(green), 매입(orange), 매입매출(blue)
  • 신용등급: AAAA(green), BBBB(yellow), CCC~D(red)
  • 거래등급: A(green), B(blue), C(yellow), D(orange), E(red)
  • 악성채권: 정상(green), 미설정(-), 경고(red)

주의사항

• 상세 페이지는 페이지로 구현 (모달 X) ✅
• 테이블에 번호 컬럼 필수 (체크박스 바로 뒤) ✅
• 금액은 toLocaleString() 포맷 사용 ✅
• 행 클릭 시 상세 페이지로 이동 ✅

---

리스트 페이지 수정 (2025-12-18)

수정 사항

• 악성채권 필터 옵션: "미설정" → "악성채권" 변경
• BadDebtStatus 타입: 'warning' → 'badDebt' 변경
• 작업 버튼: 상단 액션바 → 테이블 맨 끝 컬럼으로 이동
• 체크박스 선택 시에만 수정/삭제 버튼 표시
• headerActions (신규등록 버튼) 제거
• beforeTableContent (상단 액션 바) 제거
• 미사용 핸들러 정리 (handleNewVendor, handleCancelSelection)