sam-react-prod/claudedocs/accounting/[PLAN-2025-12-18] sales-management.md

[PLAN-2025-12-18] 매출관리 페이지 구현 계획서

개요

• 목표: 회계관리 > 매출관리 페이지 구현
• 참조: 기안함(DraftBox) 구조 기반
• 페이지 수: 2개 (리스트 + 상세/등록)

---

1. 리스트 페이지 (매출관리)

1.1 페이지 구조

• 경로: /accounting/sales
• 컴포넌트: src/components/accounting/SalesManagement/index.tsx
• IntegratedListTemplateV2 사용

1.2 헤더 영역

• DateRangeSelector (공통 달력)
• 상태 필터 버튼들
  • 당월마감
  • 전월
  • 합의
  • 미수
  • 전체
• 매출 등록 버튼 (클릭 시 등록 페이지로 이동)

1.3 통계 카드 (4개)

• 매출금액 합계 (예: 3,123,000원)
• 입금금액 합계 (예: 3,123,000원)
• 미수건수 (예: 3건)
• 전체건수 (예: 4건)

1.4 필터 셀렉트 박스들

필터명	설명	옵션	기본값
계정과목별	계정과목명으로 분류	전체, 외상 매출, 상품 매출, 부품 매출, 공사 매출, 임대 수익, 기타 매출	제품 매출
거래처 필터	거래처별 검색/필터	거래처 검색 (검색 가능)	-
매출유형 필터	다중 선택 가능	외상 매출, 상품 매출, 부품 매출, 공사 매출, 임대 수익, 기타 매출	전체
정렬	단독 선택	최신순, 금액 높은 순, 금액 낮은 순	최신순

1.5 테이블 컬럼

컬럼	설명
체크박스	다중 선택
번호	순번
매출번호	자동 채번 (포맷: 조합+자동생성)
매출일	날짜
거래처명	거래처
결제대면(?)	결제 방식
매출금액	금액
미수금액	미수 금액
비고	적요
작업	수정/삭제 아이콘

1.6 기능

• 검색 기능 (매출번호, 거래처명, 적요)
• 페이지네이션 (20건씩)
• 체크박스 전체/개별 선택
• 행 클릭 → 상세 페이지 이동

---

2. 상세/등록 페이지 (매출 상세)

2.1 페이지 구조

• 경로: /accounting/sales/[id] (상세/수정)
• 경로: /accounting/sales/new (신규 등록)
• 컴포넌트: src/components/accounting/SalesManagement/SalesDetail.tsx

2.2 헤더 영역

• 페이지 제목: "매출 상세" 또는 "매출 상세_직접 등록"
• 버튼
  • 삭제 버튼 (신규 등록 시)
  • 수정 버튼

2.3 기본 정보 섹션

필드	타입	설명
매출번호	텍스트 (읽기전용/자동채번)	수정 시 표시, 신규 시 자동 채번
매출일	DatePicker	날짜 선택
거래처명	Select (검색 가능)	거래처 선택
매출 유형	Select	외상 매출, 상품 매출, 부품 매출, 공사 매출, 임대 수익, 기타 매출 (기본: 제품 매출)

2.4 품목 정보 섹션

• 테이블 형태의 품목 입력

  컬럼	타입	설명
  번호	자동	순번
  품목명	Select/Input	품목 선택 또는 입력
  수량	Number	수량 입력
  단가	Number	단가 입력
  공급가액	Number (계산)	수량 × 단가 자동 계산
  부가세	Number (계산)	공급가액 × 10% 자동 계산
  적요	Text	메모
  삭제	Button	행 삭제 (X 버튼)

• 합계 행: 공급가액 합계, 부가세 합계

• 추가 버튼: 품목 행 추가

2.5 세금계산서 섹션

• 세금계산서 발행 토글 (Switch)
  • 클릭 시: 미발행 ↔ 발행완료 토글
  • 세금계산서 수동 발행 후 발행 상태로 변경

2.6 거래명세서 섹션

• 거래명세서 발행 토글 (Switch)
  • 클릭 시: 미발행 ↔ 발행완료 토글
• 거래명세서 발행하기 버튼
  • 클릭 시: 거래처 이메일로 자동 발송
  • Alert: "거래명세서가 'abc@email.com'으로 발송되었습니다"
  • 발행 후 자동으로 발행 상태 변경

---

3. 파일 구조

src/
├── app/[locale]/(protected)/accounting/
│   └── sales/
│       ├── page.tsx                    # 리스트 페이지
│       ├── [id]/
│       │   └── page.tsx                # 상세/수정 페이지
│       └── new/
│           └── page.tsx                # 신규 등록 페이지
│
└── components/accounting/
    └── SalesManagement/
        ├── index.tsx                   # 리스트 컴포넌트
        ├── SalesDetail.tsx             # 상세/등록 컴포넌트
        ├── SalesItemTable.tsx          # 품목 테이블 컴포넌트
        ├── TaxInvoiceSection.tsx       # 세금계산서 섹션
        ├── TransactionStatementSection.tsx  # 거래명세서 섹션
        └── types.ts                    # 타입 정의

---

4. 타입 정의 (types.ts)

// 매출 레코드
interface SalesRecord {
  id: string;
  salesNo: string;           // 매출번호
  salesDate: string;         // 매출일
  vendorId: string;          // 거래처 ID
  vendorName: string;        // 거래처명
  salesType: SalesType;      // 매출 유형
  items: SalesItem[];        // 품목 목록
  totalSupplyAmount: number; // 공급가액 합계
  totalVat: number;          // 부가세 합계
  totalAmount: number;       // 총 금액
  receivedAmount: number;    // 입금액
  outstandingAmount: number; // 미수금액
  taxInvoiceIssued: boolean; // 세금계산서 발행 여부
  transactionStatementIssued: boolean; // 거래명세서 발행 여부
  note: string;              // 비고
  status: SalesStatus;       // 상태
  createdAt: string;
  updatedAt: string;
}

// 매출 유형
type SalesType =
  | 'credit'      // 외상 매출
  | 'product'     // 제품 매출
  | 'goods'       // 상품 매출
  | 'parts'       // 부품 매출
  | 'construction'// 공사 매출
  | 'rental'      // 임대 수익
  | 'other';      // 기타 매출

// 매출 품목
interface SalesItem {
  id: string;
  itemName: string;      // 품목명
  quantity: number;      // 수량
  unitPrice: number;     // 단가
  supplyAmount: number;  // 공급가액
  vat: number;           // 부가세
  note: string;          // 적요
}

// 매출 상태
type SalesStatus =
  | 'monthlyClose'  // 당월마감
  | 'lastMonth'     // 전월
  | 'agreed'        // 합의
  | 'outstanding'   // 미수
  | 'all';          // 전체

// 필터 옵션
type FilterOption = 'all' | 'monthlyClose' | 'lastMonth' | 'agreed' | 'outstanding';

// 정렬 옵션
type SortOption = 'latest' | 'amountHigh' | 'amountLow';

---

5. 구현 체크리스트

Phase 1: 기본 구조 설정

• 폴더 구조 생성
• 라우트 페이지 생성 (page.tsx들)
• types.ts 작성

Phase 2: 리스트 페이지 구현

• SalesManagement/index.tsx 생성
• IntegratedListTemplateV2 연동
• DateRangeSelector 연동
• 상태 필터 버튼 구현
• 통계 카드 구현
• 필터 셀렉트 박스들 구현
• 테이블 렌더링 구현
• 모바일 카드 렌더링 구현
• 페이지네이션 구현
• 검색 기능 구현
• Mock 데이터 생성

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

• SalesDetail.tsx 생성
• 기본 정보 섹션 구현
• SalesItemTable.tsx 구현 (품목 테이블)
  • 품목 행 추가/삭제
  • 자동 계산 (공급가액, 부가세)
  • 합계 행
• TaxInvoiceSection.tsx 구현
• TransactionStatementSection.tsx 구현
• 폼 유효성 검사
• 저장/수정 로직

Phase 4: 연동 및 테스트

• 리스트 ↔ 상세 페이지 연결
• 신규 등록 플로우 확인
• 수정 플로우 확인
• 반응형 레이아웃 확인

---

6. 참고 사항

기안함(DraftBox)에서 참고할 패턴

• IntegratedListTemplateV2 사용법
• DateRangeSelector 연동
• 필터/정렬 셀렉트 박스 패턴
• 테이블/모바일 카드 렌더링
• 체크박스 선택 관리
• 페이지네이션

주의 사항

1. 매출번호 자동 채번 로직 확인 필요 (API 연동 시)
2. 거래처 목록 API 연동 필요
3. 품목 목록 API 연동 필요
4. 세금계산서/거래명세서 발행 API 연동 필요

---

7. 예상 작업 시간

• Phase 1: 기본 구조 설정
• Phase 2: 리스트 페이지 구현
• Phase 3: 상세/등록 페이지 구현
• Phase 4: 연동 및 테스트

---

작성일: 2025-12-18 작성자: Claude 상태: 계획 검토 대기