인증/권한

CSO 정산 포털의 인증 구조와 권한 관리 방법을 설명합니다.

인증 구조

JWT 기반 인증

포털은 Supabase Auth를 사용하지 않고 자체 JWT 인증을 구현합니다.

JWT 페이로드에는 UserSession 객체가 포함됩니다.

{
  id, business_number, company_name, email,
  is_admin, is_approved, is_test,
  must_change_password, profile_complete
}

로그인 절차

1. 사용자가 사업자번호(10자리)와 비밀번호를 입력합니다.
2. 서버에서 사업자번호를 정규화하고(- 제거), DB에서 회원을 조회합니다.
3. bcrypt로 비밀번호를 검증합니다 (Salt Rounds: 12).
4. 인증 성공 시 JWT를 생성하고 httpOnly 쿠키에 저장합니다.

로그인 실패 처리

계정 잠금 시 등록된 이메일로 비밀번호 재설정 링크가 자동 발송됩니다.

로그인 후 분기

로그인 성공 후 사용자 상태에 따라 리다이렉트됩니다.

세션 관리

쿠키 설정

클라이언트 상태 동기화

서버 쿠키와 별도로 localStorage(cso_auth_user 키)에 사용자 정보를 캐싱합니다. AuthContext가 클라이언트 마운트 시 서버 세션(/api/auth/session)과 동기화하여 Hydration 불일치를 방지합니다.

로그아웃

1. 서버: cso_session 쿠키 삭제
2. 클라이언트: localStorage 항목 삭제 + AuthContext 초기화
3. 로그인 페이지로 리다이렉트

관리자 vs 일반회원

권한 차이

권한 검증 방식

모든 관리자 API는 요청 시 JWT에서 is_admin 필드를 확인합니다. 관리자가 아닌 경우 403 응답을 반환합니다.

쿠키 → JWT 검증 → UserSession 추출 → is_admin 확인 → 처리 or 403

일반회원의 정산 데이터 접근은 cso_matching 테이블을 통해 필터링됩니다. 회원의 사업자번호와 매칭된 CSO관리업체에 해당하는 정산만 조회됩니다.

회원가입 승인/거부 절차

가입 신청 흐름

1. CSO 업체 담당자가 회원가입 폼을 작성합니다.
   • 필수: 사업자번호, 업체명, 대표자명, 주소, 연락처, 이메일, 비밀번호
   • 사업자번호 중복 검사 자동 수행
2. 가입 신청이 접수되면 is_approved: false 상태로 DB에 저장됩니다.
3. 관리자에게 가입 신청 알림 이메일이 발송됩니다.

관리자 승인/거부 (/admin/members)

회원 관리 페이지에서 전체 회원을 조회하고 관리합니다.

통계 카드

페이지 상단에 회원 현황이 카드로 표시됩니다.

• 전체 회원 수
• 승인 대기 수 (주황색 뱃지)
• 승인 완료 수
• 테스트 계정 수

회원 필터링

• 상태별: 전체, 승인대기, 승인완료
• 검색: 업체명, 사업자번호, 이메일로 검색
• 일괄 처리: 체크박스로 여러 회원 선택 후 일괄 승인

승인 처리

1. 승인 대기 필터 선택 → 대상 회원 확인
2. 승인 버튼 클릭 → is_approved: true로 업데이트
3. 회원에게 승인 완료 이메일 자동 발송
4. 일괄 승인 시 이메일 간 200ms 간격으로 순차 발송 (Rate Limit 방어)

거부 처리

1. 거부 버튼 클릭 → 거부 사유 입력 다이얼로그 표시
2. 사유 입력 후 확인 → 회원에게 거부 이메일 발송 (사유 포함)
3. 해당 회원 계정 삭제

기타 관리 기능

비밀번호 재설정

사용자 요청 (비밀번호 찾기)

1. 로그인 페이지에서 비밀번호 찾기 클릭
2. 사업자번호 입력 → 등록된 이메일 주소로 재설정 링크 발송
3. 링크 유효기간: 30분
4. 링크 클릭 → 새 비밀번호 입력 → 변경 완료

관리자 초기화

1. /admin/members 에서 해당 회원의 비밀번호 초기화 클릭
2. 시스템이 임시 비밀번호를 생성하여 이메일로 발송
3. 회원은 다음 로그인 시 비밀번호 변경 페이지로 강제 이동

비밀번호 정책