# Implementation Plan: Studio Settlement (정산) Pages

## Task Type
- [x] 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)
```typescript
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)
```typescript
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)
```typescript
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

1. Types + Constants (의존성 없음)
2. Layout + Style (공통 기반)
3. Mock 데이터
4. Account 페이지 (출금 페이지에서 이미 링크됨 — 우선순위 높음)
5. Tax 페이지 (정보 표시 위주)
6. Sidebar 텍스트 수정
7. 기존 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 변경
1. 설정에 크리에이터 유형 선택: 개인/면세사업자/과세사업자/법인
2. 사업자등록번호 입력 + 국세청 API 상태조회
3. 과세/법인: 세금계산서 역발행 워크플로우 (월 마감 → 초안 생성 → 승인)
4. 원천징수 내역 페이지: 유형에 따라 표시 내용 분기
   - 개인/면세: 현재와 동일 (3.3% 원천징수)
   - 과세/법인: 세금계산서 발행내역 + VAT 내역

---

## Notes
- **세금계산서 → 원천징수 내역**: 기술적으로 정확한 명칭으로 변경 완료
- 공식 원천징수영수증은 국세청 홈택스에서 조회 — 플랫폼은 참고용 내역만 제공
- 계좌 등록은 출금 기능의 전제 조건 → 출금 페이지에서 이미 `/studio/settlement/account` 링크
- SESSION_ID: N/A (external model wrapper 미사용)