studio-settlement.md 15 KB
Implementation Plan: Studio Settlement (정산) Pages
Task Type
- Frontend
- Backend
- Fullstack
Research Summary: "세금계산서" 는 잘못된 명칭
핵심 발견
세금계산서(Tax Invoice)는 부가세(VAT) 문서로, 3.3% 원천징수 모델에서는 해당 없음.
현재 dpot의 크리에이터 정산 방식:
- 크리에이터 = 비사업자 프리랜서 → 사업소득 3.3% 원천징수 (소득세 3% + 지방소득세 0.3%)
- 플랫폼이 원천징수의무자로서 3.3%를 원천징수 후 국세청에 납부
- 플랫폼이 매년 3월 10일까지 사업소득 지급명세서를 국세청에 제출
- 크리에이터는 5월에 종합소득세 신고 시 기납부세액으로 처리
세금계산서가 필요한 경우 (현재 해당 없음)
- 과세사업자(921505) 크리에이터 → 크리에이터가 플랫폼에 세금계산서 발행 + 10% VAT 추가 지급
- 면세사업자(940306) 크리에이터 → 크리에이터가 플랫폼에 계산서(VAT 없음) 발행
- → 추후 사업자 크리에이터 지원 시 확장 가능하도록 설계
한국 플랫폼 사례
| 플랫폼 | 세금 관련 문서 제공 방식 |
|---|---|
| CHZZK | 정산내역에서 월별 내역 확인, 원천징수영수증은 홈택스에서 조회 |
| SOOP | 원천징수영수증 직접 미제공, 지급명세서 국세청 제출 후 홈택스에서 조회 |
| 투네이션 | 월별 정산 내역만 제공, 원천징수영수증은 홈택스에서 5월 이후 조회 안내 |
결론: 메뉴명 변경 권장
세금계산서→ "원천징수 내역" 또는 "세금 서류"- 실제 내용: 월별 원천징수 내역 + 연간 요약 + 종합소득세 신고 안내
Design Decision
메뉴 구조 (사이드바 수정)
| 현재 | 변경 후 | 경로 |
|---|---|---|
| 계좌 관리 | 계좌 관리 (유지) | /studio/settlement/account |
| 세금계산서 | 원천징수 내역 | /studio/settlement/tax |
2-Page Structure
1. 계좌 관리 (/studio/settlement/account)
- 출금 계좌 등록/수정 폼
- 은행 선택, 계좌번호, 예금주 입력
- 등록 상태 표시 (미등록/인증완료)
- 1원 인증은 Backend 의존 → 우선 기본 폼만 구현
2. 원천징수 내역 (/studio/settlement/tax)
- 연간 요약 카드 (총 지급액, 소득세, 지방소득세)
- 월별 원천징수 내역 테이블
- 종합소득세 신고 안내 가이드
Implementation Steps
Step 1: Type Definitions
File: types/response/settlement/account.ts (NEW)
export interface SettlementAccountResponse {
hasAccount: boolean;
bankCode: string|null; // '004' (KB), '088' (신한) 등
bankName: string|null;
accountNumber: string|null; // 마스킹: '****5678'
accountHolder: string|null;
isVerified: boolean;
registeredAt: string|null;
updatedAt: string|null;
}
export interface SaveAccountRequest {
bankCode: string;
accountNumber: string;
accountHolder: string;
}
File: types/response/settlement/tax.ts (NEW)
export interface WithholdingTaxSummaryResponse {
year: number;
annualSummary: {
totalGrossAmount: number; // 연간 총 지급액
totalIncomeTax: number; // 연간 소득세 (3%)
totalLocalTax: number; // 연간 지방소득세 (0.3%)
totalNetAmount: number; // 연간 실수령액
};
monthlyList: WithholdingTaxMonthItem[];
}
export interface WithholdingTaxMonthItem {
month: number; // 1~12
grossAmount: number; // 해당월 총 지급액
incomeTax: number; // 소득세 (3%)
localTax: number; // 지방소득세 (0.3%)
netAmount: number; // 실수령액
paymentCount: number; // 정산 건수
}
Step 2: Constants
File: app/studio/settlement/constants.ts (NEW)
export const BANK_LIST = [
{ code: '004', name: 'KB국민은행' },
{ code: '088', name: '신한은행' },
{ code: '020', name: '우리은행' },
{ code: '081', name: '하나은행' },
{ code: '011', name: 'NH농협은행' },
{ code: '023', name: 'SC제일은행' },
{ code: '027', name: '한국씨티은행' },
{ code: '071', name: '우체국' },
{ code: '031', name: 'DGB대구은행' },
{ code: '032', name: '부산은행' },
{ code: '039', name: '경남은행' },
{ code: '034', name: '광주은행' },
{ code: '035', name: '제주은행' },
{ code: '037', name: '전북은행' },
{ code: '007', name: '수협은행' },
{ code: '045', name: '새마을금고' },
{ code: '048', name: '신협' },
{ code: '090', name: '카카오뱅크' },
{ code: '092', name: '토스뱅크' },
{ code: '089', name: '케이뱅크' },
];
Step 3: Layout & Style
File: app/studio/settlement/layout.tsx (NEW)
- children 패스스루 + style.scss import
File: app/studio/settlement/style.scss (NEW)
- BEM Block:
.settlement - 기존 wallet 스타일 패턴 재사용
Step 4: 계좌 관리 페이지
File: app/studio/settlement/account/page.tsx (NEW)
Layout:
┌─────────────────────────────────────────────────┐
│ 계좌 관리 │
├─────────────────────────────────────────────────┤
│ │
│ ┌─ 등록된 계좌 ────────────────────────┐ │
│ │ KB국민은행 ****5678 (홍길동) │ │
│ │ ✓ 인증 완료 · 등록일 2026.03.15 │ │
│ │ [수정하기] │ │
│ └──────────────────────────────────────┘ │
│ │
│ ── OR (미등록 시) ── │
│ │
│ ┌─ 계좌 등록 ──────────────────────────┐ │
│ │ 은행 [KB국민은행 ▾] │ │
│ │ 계좌번호 [__________________] │ │
│ │ 예금주 [__________________] │ │
│ │ │ │
│ │ ※ 본인 명의 계좌만 등록 가능 │ │
│ │ ※ 출금 시 등록된 계좌로 입금됩니다 │ │
│ │ │ │
│ │ [등록하기] │ │
│ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────┘
구현:
- 상태:
mode('view' | 'edit') — 등록됨이면 view, 미등록이면 edit - 등록된 계좌 표시: 은행명, 마스킹 계좌번호, 예금주, 인증상태, 등록일
- 수정 모드: 은행 select, 계좌번호 input, 예금주 input
- Validation: 계좌번호 숫자만, 7~16자리
- API:
GET /api/studio/settlement/account - API:
POST /api/studio/settlement/account
Step 5: 원천징수 내역 페이지
File: app/studio/settlement/tax/page.tsx (NEW)
Layout:
┌─────────────────────────────────────────────────┐
│ 원천징수 내역 │
├─────────────────────────────────────────────────┤
│ 연도 선택: [2026 ▾] │
├───────────┬───────────┬───────────┬──────────────┤
│ 총 지급액 │ 소득세(3%)│지방세(0.3%)│ 실수령액 │
│ 1,520,000 │ -45,600 │ -4,560 │ 1,469,840 │
├───────────┴───────────┴───────────┴──────────────┤
│ │
│ 월별 상세 │
├──────────────────────────────────────────────────┤
│ 월 | 지급액 | 소득세 | 지방소득세 | 실수령 | 건수 │
│ 4 | 129,000 | -3,870 | -387 | 124,743 | 8 │
│ 3 | 250,000 | -7,500 | -750 | 241,750 | 15 │
│ ... │
├──────────────────────────────────────────────────┤
│ │
│ ℹ 종합소득세 신고 안내 │
│ ┌──────────────────────────────────────────┐ │
│ │ · 본 소득은 사업소득으로 분류됩니다. │ │
│ │ · 연말정산 대상이 아닙니다. │ │
│ │ · 매년 5월 종합소득세를 직접 신고해야 합니다. │ │
│ │ · 국세청 홈택스에서 지급명세서를 확인할 수 │ │
│ │ 있습니다. (My홈택스 > 지급명세서 제출내역) │ │
│ │ · 플랫폼은 매년 3/10까지 지급명세서를 국세청 │ │
│ │ 에 제출합니다. │ │
│ └──────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────┘
구현:
- 연도 선택 드롭다운 (현재 연도 기본)
- 연간 요약 카드 4개: 총 지급액, 소득세, 지방소득세, 실수령액
- 월별 테이블 (12개월, 역순 — 최신 월 상단)
- 종합소득세 신고 안내 정보 박스
- API:
GET /api/studio/settlement/tax?year={year}
Step 6: 사이드바 메뉴명 수정
File: app/studio/Sidebar.tsx (MODIFY)
세금계산서→원천징수 내역으로 텍스트만 변경
Key Files
| File | Operation | Description |
|---|---|---|
types/response/settlement/account.ts |
Create | 계좌 관리 타입 |
types/response/settlement/tax.ts |
Create | 원천징수 내역 타입 |
app/studio/settlement/constants.ts |
Create | 은행 목록 등 상수 |
app/studio/settlement/layout.tsx |
Create | style import 레이아웃 |
app/studio/settlement/style.scss |
Create | 전체 settlement 스타일 |
app/studio/settlement/account/page.tsx |
Create | 계좌 관리 페이지 |
app/studio/settlement/tax/page.tsx |
Create | 원천징수 내역 페이지 |
app/studio/settlement/mock.ts |
Create | Mock 데이터 |
app/studio/settlement/page.tsx |
Delete | 기존 플레이스홀더 삭제 |
app/studio/Sidebar.tsx:L343 |
Modify | '세금계산서' → '원천징수 내역' |
Risks and Mitigation
| Risk | Mitigation |
|---|---|
| Backend API 미존재 | Mock 데이터로 UI 구현, API 후속 연동 |
| 1원 인증 미구현 | 기본 계좌 등록 폼만 우선 구현, 1원 인증은 Backend 연동 시 추가 |
| 사업자 크리에이터 지원 | 현재는 개인(3.3%) 전용, 타입에 사업자 유형 필드 예약 |
| 원천징수 금액 정확성 | Frontend는 표시만, 계산은 Backend 담당 |
Implementation Order
- Types + Constants (의존성 없음)
- Layout + Style (공통 기반)
- Mock 데이터
- Account 페이지 (출금 페이지에서 이미 링크됨 — 우선순위 높음)
- Tax 페이지 (정보 표시 위주)
- Sidebar 텍스트 수정
- 기존 placeholder 삭제
사업자 유형별 세금 처리 (Research)
크리에이터 유형 분류
| 유형 | 원천징수 3.3% | VAT 10% | 세금계산서 | 정산 금액 |
|---|---|---|---|---|
| 개인 비사업자 | O | X | 발행 불가 | 공급가액 - 3.3% |
| 면세 개인사업자 (940306) | O | X | 계산서(면세) | 공급가액 - 3.3% |
| 과세 개인사업자 (921505) | X | O | 세금계산서 필수 | 공급가액 + VAT 10% |
| 법인사업자 | X | O | 세금계산서 필수 | 공급가액 + VAT 10% |
유형별 상세
1. 개인 비사업자 (현재 기본)
- 주민등록번호 + 계좌만 필요
- 플랫폼이 3.3% 원천징수 → 국세청 납부 + 지급명세서 제출
- 크리에이터: 5월 종합소득세 신고
2. 면세 개인사업자 (940306: 1인 미디어 콘텐츠 창작자)
- 사업자등록번호 필요
- 원천징수 3.3% 동일 적용 (면세 인적용역이므로)
- 비사업자와 정산 흐름 동일하나, 경비처리/세액감면 가능
- 2월: 사업장현황신고 / 5월: 종합소득세 신고
3. 과세 개인사업자 (921505: 미디어콘텐츠창작업)
- 사업자등록번호 필요
- 원천징수 없음 → 크리에이터가 세금계산서 발행
- 플랫폼은 공급가액 + VAT 10% 지급
- 크리에이터: 부가세 신고(반기) + 종합소득세(5월)
- CHZZK 사례: 역발행(플랫폼이 초안 생성, 크리에이터 승인) 방식
4. 법인사업자
- 법인 사업자등록번호 필요
- 과세 개인사업자와 동일 흐름 (세금계산서 + VAT)
- 법인세(10~25%) 적용, 종합소득세 대상 아님
- 전자세금계산서 의무 발행 (매출 무관)
현재 구현 범위
- V1 (현재): 개인 비사업자 전용 — 3.3% 원천징수 내역만 표시
- V2 (추후): 크리에이터 유형 선택 UI + 사업자등록번호 입력 + 유형별 정산 분기
V2 확장 시 필요한 UI 변경
- 설정에 크리에이터 유형 선택: 개인/면세사업자/과세사업자/법인
- 사업자등록번호 입력 + 국세청 API 상태조회
- 과세/법인: 세금계산서 역발행 워크플로우 (월 마감 → 초안 생성 → 승인)
- 원천징수 내역 페이지: 유형에 따라 표시 내용 분기
- 개인/면세: 현재와 동일 (3.3% 원천징수)
- 과세/법인: 세금계산서 발행내역 + VAT 내역
Notes
- 세금계산서 → 원천징수 내역: 기술적으로 정확한 명칭으로 변경 완료
- 공식 원천징수영수증은 국세청 홈택스에서 조회 — 플랫폼은 참고용 내역만 제공
- 계좌 등록은 출금 기능의 전제 조건 → 출금 페이지에서 이미
/studio/settlement/account링크 - SESSION_ID: N/A (external model wrapper 미사용)