[FEAT] 정산 - 판매자 정보 변경 화면 API 및 LEGACY 은행코드 정리

[minij02]

✨ 기능 설명

판매자 정보 변경 화면에서 기존 등록 데이터를 prefill 하고, 같은 유형 내 수정 / 유형 변경 / 사업자 정보 변경(승인 필요)을 모두 지원하는 API를 구현합니다.
또한 #470에서 임시 보존했던 LEGACY_PAYPLE_BANKS를 운영 점검 결과에 따라 정리합니다.

✨ 화면 명세 (참고)

• 일반 개인 판매자가 정산관리 화면에서 [정보 수정하기] → 기존 데이터 prefill 된 등록폼 이동
• 판매자 유형 변경 (INDIVIDUAL ↔ BUSINESS) 시 폼 초기화 상태
• [수정하기] 버튼 활성화 조건: 모든 필드 입력 + 계좌 인증 통과 + 개인정보 수집 동의
• [수정하기] 후 모달 분기:
  • 관리자 승인 필요 (최초 사업자 등록 / 개인 → 사업자 / 사업자 → 사업자 정보변경) → 승인 대기 안내
  • 승인 불필요 (개인 → 개인 / 사업자 → 개인) → 변경 완료 안내
• [취소] → 정산관리 화면으로 이동

✨ 개발 목록

신규 API

• GET /api/settlements/account/detail — 수정 화면 prefill용 전체 계좌 데이터
  • INDIVIDUAL: bank, accountNumber, holderName, name(=account_holder)
  • BUSINESS: + businessType, businessNumber(마스킹 123-45-****1), companyName, representativeName, businessLicenseUrl, status
  • birth_date는 우리 정책상 미저장 → 응답에 없음, 프론트가 재입력 받음
  • 등록 안 된 사용자: 404

기존 등록 API 동작 확장

• POST /register/business — 기존 INDIVIDUAL 사용자도 허용 (개인 → 사업자 전환). 기존 INDIVIDUAL 삭제 + 신규 BUSINESS PENDING 생성
• POST /register/individual은 이미 upsert + BUSINESS 삭제 로직 있어 동작 그대로

사업자 정보 변경 API

• 옵션 결정 필요 (기획자 확인):
  • A. POST /register/business가 BUSINESS 사용자도 받게 확장 (단순)
  • B. 신규 PATCH /api/settlements/account/business (의미 명확)
• 변경 신청 시 기존 사업자 데이터 처리 정책 결정 필요:
  • 즉시 PENDING으로 되돌리고 비활성화 / 신청 완료까지 기존 활성 유지 / 변경 신청 별도 테이블

응답 분기 (프론트 모달용)

• 등록/변경 API 응답에 requiresApproval: boolean + status: APPROVED | PENDING 명시
• 시나리오별 응답:

시나리오	requiresApproval	status
개인 → 개인	false	APPROVED
사업자 → 개인	false	APPROVED
개인 → 사업자	true	PENDING
사업자 → 사업자 (정보변경)	true	PENDING
최초 사업자 등록	true	PENDING

Phase 11 — LEGACY 은행코드 정리

• 운영 DB에서 폐기 은행코드(008, 054~063, 067, 076, 077) 사용 SettlementAccount 행 점검
• 0건이면 LEGACY_PAYPLE_BANKS, ALL_KNOWN_BANKS, isKnownBank 헬퍼 삭제
• 0건이 아니면 사용자에게 재인증 안내 정책 결정 후 데이터 정리

Swagger / 검증

• 신규/변경 API Swagger 작성
• pnpm build / pnpm tsc --noEmit 통과
• sandbox e2e (4가지 변경 시나리오 + 사업자 정보변경)

✨ 기타 설명 / 질문

• 사업자 → 사업자 (정보변경) 시 기존 데이터 처리 정책 (위)
• 사업자 승인 대기 중 [수정하기] 재요청 정책?
• 사업자등록증을 새로 업로드 안 하고 기존 것 그대로 사용 허용? (businessLicenseUrl optional 처리)
• 정보 변경 시에도 verify-account → registerToken 흐름 동일하게 적용 (TOCTOU 보호 유지)
• 관련 PR/이슈: [FEAT] 정산 - 판매자 등록 흐름 Payple 명세 정합화 및 보안 개선 #470, [FEAT] 정산 - 판매자 등록 흐름 Payple 명세 정합화 및 보안 개선 (#470) #471