💪 멘토 정산

Status: Draft · Layer: 💪 멘토 · Updated: 2026-05-13 관련 결정: 3G 정산 · 3E 운영 모델 · 3F 일반 멘토 · 3C 강사 VP · 4B 세션 포맷 📡 API: 정산 🗄️ Data: 9. Payout 현재 코드: apps/partner/src/pages/earnings-page.tsx, apps/api settlements 라우트

1. 배경

기존 MVP는 settlements 테이블 (월 단위) + coaches.premium_rate 단일 단가. 새 모델은:

30분 1:1 = 1회 카운트 (멘토 1시간 = 2 회원 = 2 회 정산)
일반 회당 고정 + Pro 인증 자율 단가
격주 (2주) 정산
본사 결제 직수령 → 자동 분배
회원·멘토 노쇼 시 처리 차등

2. 정책서 락된 사항

정산 구조 (3G)

일반 멘토: 회당 X원 고정 (본사 결정)
Pro 인증: 회당 자율 (본사 min~max 한도)
등급 보너스 ❌ — 자율 단가가 그 역할
분배 가설 (90분 회원 결제 기준): 멘토 ~50% / 본사 ~30% / 가맹점주 ~20%
회원 평점 등급 = Pro 승격 자격·매칭 우선순위에 사용, 단가 직접 영향 ❌
정산 주기: 격주 (2주마다)
결제 흐름: 회원 결제 → 본사 앱 직접 수령 → 자동 분배

세션 단위 (4B)

회원 1세션 = 90분 (카디오 30 + 방 60)
멘토 = 방 안 30분만 1:1
멘토 1시간 = 2 회원 = 정산 2회

패널티 (정책서 + 5A)

회원 노쇼: 멘토는 정상 정산 (회원 회차만 차감)
본사·멘토 노쇼: 회원 회차 +1 보상, 멘토 등급 패널티 + 정산 차감
6h 이내 본인 취소: 정산 차감

3. 현재 코드 vs 새 시스템

영역	현재	새 시스템
정산 주기	월 단위 (`settlements.period`)	격주 (2주마다)
회당 단가	`included_pt_amount` (15,000) + `additional_pt_amount` (30,000)	일반 고정 + Pro 자율
세션 단위	session 1 = 1 정산 (60분)	session 1 = 1 정산 (30분 1:1)
등급 단가	premium_rate (자유)	tier 따라 (verified 고정 / pro_certified 자율)
차감 항목	없음	노쇼·6h 이내 취소 패널티
결제 흐름	미상 (settlements는 후 계산)	본사 직수령 + 자동 분배
세무 자료	❌	월 1회 사업소득 명세서 PDF
4대 보험	모델 없음	본사 정보 제공 (멘토는 프리랜서)

4. 멘토 시나리오

4.1 세션 진행 → 정산 카운트

세션 완료 (회원 1명, 30분 1:1)
→ 정산 카운트 +1 (단가 적용)
→ "정산 가능" 상태로 7일 유지 (환불 가능 기간)
→ 7일 후 "정산 확정"

4.2 정산 대시보드 (`/earnings`)

정산 대시보드
─────────────────
이번 격주 (5/1 ~ 5/14)
  진행 세션: 24
  예상 정산: 480,000원
  차감 항목: 0
  실 지급액: 480,000원

다음 입금 예정: 5/16 (금)
계좌: 신한 110-***-12345

[명세서 다운로드]  [세무 자료]

4.3 명세서 상세

정산 명세서 — 2026-05-01 ~ 2026-05-14
─────────────────
세션별 내역:
  5/01 19:30 김OO 일반멘토 20,000원
  5/01 20:00 이OO 일반멘토 20,000원
  5/02 19:30 박OO 일반멘토 20,000원
  ...
  (24건)

소계: 480,000원

차감:
  (없음)

총 정산: 480,000원

[PDF 다운로드]  [Excel 다운로드]

4.4 Pro 인증 멘토 — 자율 단가 정산

정산 — Pro 인증 자율 단가
─────────────────
세션별 내역:
  5/01 19:30 김OO 22,000원 (Pro)
  5/02 14:00 이OO 22,000원 (Pro)
  5/03 10:00 박OO 20,000원 (5/3 이전 단가)
  ...

내 단가 변경 이력:
  ~ 5/2 = 20,000원
  5/3 ~ = 22,000원

소계: 528,000원

4.5 정산 차감 사례

정산 — 5/8 ~ 5/21
─────────────────
세션 12회 × 20,000 = 240,000원

차감:
  5/15 노쇼 (본인 사정 6h 이내) -20,000원
  → 회원 회차 +1 보상 발급

총 정산: 220,000원

4.6 세무 자료 (월별)

2026년 4월 사업소득 명세서
─────────────────
총 수입: 920,000원
원천세 (3.3%): -30,360원
실수령: 889,640원

[PDF 다운로드] [세무 자료 안내]

4.7 4대 보험·세무 안내

멘토 = 프리랜서 (사업소득)
본사가 원천세 3.3% 자동 공제
4대 보험 = 멘토 본인 책임 (가입 의무 ❌)
본사가 매월 사업소득 신고 자료 제공

5. 화면 요구사항

5.1 정산 대시보드 (`/earnings`)

컴포넌트: earnings-page.tsx (재작성)

정산 대시보드
─────────────────────
[탭] 이번 격주 / 최근 / 연간

# 이번 격주
2026-05-01 ~ 2026-05-14

진행 세션: 24회
─────────────────
일반 정산:
  24 × 20,000 = 480,000원

차감:
  (없음)

총 예상: 480,000원
다음 입금: 5/16 (금)

[명세서] [계좌 변경]

# 최근 (지난 6개월)
[그래프: 격주별 정산액]
[리스트: 격주별 상세]

# 연간 (세무용)
[탭: 월 단위]
[월별 누적 + 원천세]
[PDF: 월별 명세서]

5.2 명세서 상세 페이지

컴포넌트: payout-detail-page.tsx (신규)

정산 명세서 #2026-05-01-2026-05-14
─────────────────
1️⃣ 요약
   세션: 24 / 일반 정산: 480,000원 / 차감: 0

2️⃣ 세션별 내역
   [정렬: 날짜 / 회원 / 단가]
   - 5/01 19:30 김OO ........ 20,000원
   - 5/01 20:00 이OO ........ 20,000원
   ...

3️⃣ 차감 항목
   (없음)

4️⃣ 입금 정보
   계좌: 신한 110-***-12345
   입금 예정: 5/16 (금)

[PDF 내보내기]  [Excel 내보내기]

5.3 단가 변경 이력 (Pro 인증만)

Pro 인증 단가 이력
─────────────────
2026-05-03 ~ : 22,000원 (현재)
2026-04-01 ~ 2026-05-02: 20,000원
2026-03-15 ~ 2026-03-31: 18,000원 (초기)

[단가 변경] (Pro 인증 멘토만)

5.4 세무 자료 화면

세무 자료 (사업소득)
─────────────────
2026년 4월:
  총 수입: 920,000원
  원천세 (3.3%): -30,360원
  실수령: 889,640원
  [PDF 다운로드]

연간 누적 (2026):
  1월: 720,000원
  2월: 880,000원
  3월: 1,100,000원
  4월: 920,000원
  ────────────────
  소계: 3,620,000원

[세무 신고 안내]
  - 5월 종합소득세 신고 안내
  - 사업자 등록 필요 여부
  - 4대 보험 가입 안내 (선택)

5.5 계좌 등록·변경

정산 계좌
─────────────────
은행: [신한 ▼]
계좌번호: [110-123-4567890]
예금주: [김멘토]

[저장]
  - 변경 시 다음 정산부터 적용
  - 본인 명의 확인 필수

6. 데이터 모델

interface PayoutPeriod {
  id: string
  startDate: string  // 격주 시작 (월요일)
  endDate: string    // 격주 끝 (다음 일요일)
  cutoffAt: string   // 마감 시각
  paymentDate: string  // 입금 예정일
}

interface MentorPayout {
  id: string
  mentorId: string
  periodId: string
  sessionCount: number
  grossAmount: number
  deductions: number
  netAmount: number
  status: 'calculated' | 'paid' | 'failed'
  paidAt?: string
  transactionId?: string
  bankAccount: { bank: string, last4: string }
}

interface PayoutLineItem {
  id: string
  payoutId: string
  sessionId: string
  sessionDate: string
  memberName: string
  rateApplied: number
  amount: number
  mentorTierAtTime: 'verified' | 'pro_certified'  // 진행 당시 등급
}

interface PayoutDeduction {
  id: string
  payoutId: string
  type: 'no_show' | 'late_cancel' | 'tier_demotion'
  sessionId?: string
  amount: number
  reason: string
}

interface MentorBankAccount {
  mentorId: string
  bank: string  // "신한"
  accountNumber: string  // encrypted
  accountHolder: string
  lastUpdatedAt: string
}

interface TaxReport {
  mentorId: string
  period: string  // "2026-04"
  grossIncome: number
  withholdingTax: number  // 3.3% 원천세
  netIncome: number
  reportUrl: string  // PDF
}

7. API 통신

7.1 새 엔드포인트

GET    /api/mentors/me/payouts/current
       Response: { period, sessionCount, estimatedAmount, deductions }

GET    /api/mentors/me/payouts?from=YYYY-MM-DD&to=YYYY-MM-DD
       Response: MentorPayout[]

GET    /api/mentors/me/payouts/:id
       Response: { payout, lineItems, deductions }

GET    /api/mentors/me/payouts/:id/statement
       Response: PDF stream

GET    /api/mentors/me/rate-history
       Response: MentorRateChange[]

GET    /api/mentors/me/tax-reports/:month  // "2026-04"
       Response: TaxReport

PATCH  /api/mentors/me/bank-account
       Body: { bank, accountNumber, accountHolder }
       Response: { success, lastUpdatedAt }

7.2 응답 예시

// GET /api/mentors/me/payouts/current
{
  "period": {
    "startDate": "2026-05-01",
    "endDate": "2026-05-14",
    "cutoffAt": "2026-05-14T23:59:59+09:00",
    "paymentDate": "2026-05-16"
  },
  "sessionCount": 24,
  "estimatedAmount": 480000,
  "deductions": 0,
  "netEstimated": 480000,
  "tier": "verified",
  "currentRate": 20000
}

8. 엣지 케이스

케이스	처리
회원이 결제 후 7일 이내 환불	멘토 정산도 회수 (다음 격주 차감)
Pro 단가 변경 후 매칭된 예약 진행	진행 당시 단가 lookup (rateApplied 기록)
6h 이내 본인 취소	정산 -1세션 + 회원 회차 +1
회원 노쇼	멘토 정상 정산 (회원 회차만 차감)
본사 노쇼 (Pro→일반 swap 등)	회원 보상은 본사 부담, 멘토는 진행 시 정상
입금 실패 (계좌 오류)	멘토 알림 → 계좌 정정 → 재시도 (3회)
계좌 변경 후 처음 입금	1차 입금은 1원 송금 후 본인 확인
멘토 활동 중단	마지막 활동 다음 격주에 자동 정산 종료

9. 측정 지표

지표	목표
정산 정확도	100% (오류 0건)
입금 SLA	격주 마감 후 영업일 2일 이내
정산 만족도 (멘토 인터뷰)	≥ 4.0 / 5
명세서 다운로드 비율	≥ 70% (월간)
Pro 인증 멘토 평균 단가	≥ 25,000원 (자율 단가 효과)

10. 구현 작업 분해

10.1 페이지

src/pages/earnings-page.tsx — 정산 대시보드 (개편)
src/pages/payout-detail-page.tsx (신규) — 명세서 상세
src/pages/tax-report-page.tsx (신규) — 세무 자료
src/pages/bank-account-page.tsx (신규) — 계좌 등록·변경

10.2 컴포넌트

src/components/PayoutSummaryCard.tsx — 이번 격주 요약
src/components/PayoutLineItemTable.tsx — 세션별 내역
src/components/PayoutHistoryChart.tsx — 격주별 그래프
src/components/RateChangeLog.tsx — Pro 단가 이력
src/components/TaxReportCard.tsx — 월별 세무

10.3 서비스 / 스토어

src/services/payout.ts — 정산 조회·명세서
src/services/bank.ts — 계좌 관리
src/services/tax.ts — 세무 자료

10.4 타입

packages/api-types/src/payout.ts — 위 정의

2026-05-13	초안
2026-05-13	정책서 5개 cross-ref + 현재 코드 비교 + 7 시나리오 + 5 화면 + 데이터 모델·API 상세화