회원 카테고리 분리 API 문서

작성일: 2025-12-01
버전: 1.0
상태: ✅ 구현 완료 (빌드 성공)

📋 개요

AKC B2C 서비스는 같은 이메일, 아이디, 전화번호로도 일반회원과 법인회원을 구분하여 등록할 수 있도록 회원 시스템을 개선했습니다.

핵심 변경사항

✅ 같은 전화번호 → 일반회원 + 법인회원 이중 가입 가능
✅ 같은 이메일 → 일반회원 + 법인회원 이중 가입 가능
✅ 같은 아이디 → 일반회원 + 법인회원 이중 가입 가능
✅ 로그인/회원가입 엔드포인트 분리
✅ 중복 검사 엔드포인트 분리

🔐 인증 API (Authentication)

1. 회원가입 - 일반회원

POST /api/auth/signup/individual

요청 본문:

{
  "userId": "testuser001",
  "email": "user@example.com",
  "password": "SecurePass123!",
  "name": "홍길동",
  "phone": "010-1234-5678",
  "ageOver14Agreed": true,
  "termsAgreed": true,
  "privacyAgreed": true,
  "locationPolicyAgreed": true,
  "marketingEmailAgreed": true,
  "marketingSmsAgreed": false,
  "marketingPushAgreed": false
}

응답 (성공):

{
  "success": true,
  "data": {
    "memberUuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "홍길동",
    "memberType": "DIRECT"
  },
  "message": "일반회원 가입이 완료되었습니다"
}

HTTP Status: 200 OK

2. 회원가입 - 법인회원

POST /api/auth/signup/corporate

요청 본문:

{
  "userId": "corpuser001",
  "email": "corp@example.com",
  "password": "SecurePass123!",
  "name": "김기업",
  "phone": "010-1234-5678",
  "companyName": "테스트 법인",
  "businessNumber": "123-45-67890",
  "businessRegistration": "<MultipartFile>",
  "ageOver14Agreed": true,
  "termsAgreed": true,
  "privacyAgreed": true,
  "locationPolicyAgreed": true,
  "marketingEmailAgreed": true,
  "marketingSmsAgreed": false,
  "marketingPushAgreed": false
}

응답 (성공):

{
  "success": true,
  "data": {
    "memberUuid": "550e8400-e29b-41d4-a716-446655440001",
    "email": "corp@example.com",
    "name": "김기업",
    "memberType": "DIRECT"
  },
  "message": "법인회원 가입이 신청되었습니다. 승인 대기 중입니다"
}

HTTP Status: 200 OK

📌 주의:

같은 전화번호로 일반회원과 법인회원 모두 가입 가능
법인회원은 businessNumber와 businessRegistration 필수
법인회원은 관리자 승인 후 사용 가능 (PENDING → APPROVED)

3. 로그인 - 통합 (기존)

POST /api/auth/login

요청 본문:

{
  "userId": "testuser001",
  "password": "SecurePass123!"
}

응답 (성공):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "userInfo": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "testuser001",
      "email": "user@example.com",
      "name": "홍길동",
      "memberType": "DIRECT",
      "memberCategory": "INDIVIDUAL",
      "isIndividualUser": true,
      "isCorporateUser": false,
      "roles": ["INDIVIDUAL_USER"]
    }
  }
}

HTTP Status: 200 OK

4. 로그인 - 일반회원 전용

POST /api/auth/login/individual

요청 본문:

{
  "userId": "testuser001",
  "password": "SecurePass123!"
}

응답 (성공):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "userInfo": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "testuser001",
      "email": "user@example.com",
      "name": "홍길동",
      "memberType": "DIRECT",
      "memberCategory": "INDIVIDUAL",
      "isIndividualUser": true,
      "isCorporateUser": false,
      "roles": ["INDIVIDUAL_USER"]
    },
    "corporateInfo": null
  }
}

HTTP Status: 200 OK

오류 응답 (법인회원으로 로그인 시도):

{
  "success": false,
  "data": null,
  "errorCode": "UNAUTHORIZED",
  "message": "아이디 또는 비밀번호가 일치하지 않습니다"
}

HTTP Status: 401 Unauthorized

5. 로그인 - 법인회원 전용

POST /api/auth/login/corporate

요청 본문:

{
  "userId": "corpuser001",
  "password": "SecurePass123!"
}

응답 (성공):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "userInfo": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "userId": "corpuser001",
      "email": "corp@example.com",
      "name": "김기업",
      "memberType": "DIRECT",
      "memberCategory": "CORPORATE",
      "isIndividualUser": false,
      "isCorporateUser": true,
      "roles": ["CORPORATE_USER"]
    },
    "corporateInfo": {
      "companyName": "테스트 법인",
      "businessNumber": "123-45-67890",
      "approvalStatus": "APPROVED",
      "approvalMessage": "승인되었습니다"
    }
  }
}

HTTP Status: 200 OK

오류 응답 (일반회원으로 로그인 시도):

{
  "success": false,
  "data": null,
  "errorCode": "UNAUTHORIZED",
  "message": "아이디 또는 비밀번호가 일치하지 않습니다"
}

HTTP Status: 401 Unauthorized

✅ 중복 검사 API (Duplicate Validation)

6. 아이디 중복 검사 - 통합 (기존)

GET /api/auth/check-userid

요청 파라미터:

userId=testuser001

응답 (사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 아이디입니다"
  }
}

응답 (중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 사용중인 아이디입니다"
  }
}

HTTP Status: 200 OK

7. 아이디 중복 검사 - 일반회원

GET /api/auth/check-userid/individual

요청 파라미터:

userId=testuser001

응답 (사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 아이디입니다"
  }
}

응답 (일반회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 일반회원으로 사용중인 아이디입니다"
  }
}

응답 (법인회원으로는 사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 아이디입니다"
  }
}

HTTP Status: 200 OK

8. 아이디 중복 검사 - 법인회원

GET /api/auth/check-userid/corporate

요청 파라미터:

userId=corpuser001

응답 (사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 아이디입니다"
  }
}

응답 (법인회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 법인회원으로 사용중인 아이디입니다"
  }
}

HTTP Status: 200 OK

9. 이메일 중복 검사 - 통합 (기존)

GET /api/auth/check-email

요청 파라미터:

email=user@example.com

응답 (사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 이메일입니다"
  }
}

응답 (중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 사용중인 이메일입니다"
  }
}

HTTP Status: 200 OK

10. 이메일 중복 검사 - 일반회원

GET /api/auth/check-email/individual

요청 파라미터:

email=user@example.com

응답 (일반회원으로 사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 이메일입니다"
  }
}

응답 (일반회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 일반회원으로 사용중인 이메일입니다"
  }
}

HTTP Status: 200 OK

11. 이메일 중복 검사 - 법인회원

GET /api/auth/check-email/corporate

요청 파라미터:

email=corp@example.com

응답 (법인회원으로 사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 이메일입니다"
  }
}

응답 (법인회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 법인회원으로 사용중인 이메일입니다"
  }
}

HTTP Status: 200 OK

12. 전화번호 중복 검사 - 통합 (기존)

GET /api/auth/check-phone

요청 파라미터:

phone=010-1234-5678

응답 (사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 전화번호입니다"
  }
}

응답 (중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 등록된 전화번호입니다"
  }
}

HTTP Status: 200 OK

13. 전화번호 중복 검사 - 일반회원

GET /api/auth/check-phone/individual

요청 파라미터:

phone=010-1234-5678

응답 (일반회원으로 사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 전화번호입니다"
  }
}

응답 (일반회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 일반회원으로 등록된 전화번호입니다"
  }
}

HTTP Status: 200 OK

14. 전화번호 중복 검사 - 법인회원

GET /api/auth/check-phone/corporate

요청 파라미터:

phone=010-1234-5678

응답 (법인회원으로 사용 가능):

{
  "success": true,
  "data": {
    "available": true,
    "message": "사용 가능한 전화번호입니다"
  }
}

응답 (법인회원으로 중복):

{
  "success": true,
  "data": {
    "available": false,
    "message": "이미 법인회원으로 등록된 전화번호입니다"
  }
}

HTTP Status: 200 OK

🔍 회원 찾기 API (이전 구현 - 이미 분리됨)

15. 일반회원 아이디 찾기

POST /api/members/individual/find-id

요청 본문:

{
  "name": "홍길동",
  "phoneNumber": "010-1234-5678"
}

응답 (성공):

{
  "success": true,
  "data": {
    "maskedUserId": "te***01"
  },
  "message": null
}

HTTP Status: 200 OK

16. 법인회원 아이디 찾기

POST /api/members/corporate/find-id

요청 본문:

{
  "businessNumber": "123-45-67890",
  "phoneNumber": "010-1234-5678"
}

응답 (성공):

{
  "success": true,
  "data": {
    "maskedUserId": "co***01",
    "companyName": "테스트 법인"
  },
  "message": null
}

HTTP Status: 200 OK

💼 회원 정보 관리 API

17. 이메일 수정

PUT /api/members/myinfo/email

요청 헤더:

Authorization: Bearer <accessToken>
Content-Type: application/json

요청 본문:

{
  "newEmail": "newemail@example.com"
}

응답 (성공):

{
  "success": true,
  "data": {
    "email": "new***l@example.com",
    "message": "이메일이 변경되었습니다"
  }
}

HTTP Status: 200 OK

📊 엔드포인트 비교표

기능	통합 (기존)	일반회원 (NEW)	법인회원 (NEW)
회원가입	-	`POST /api/auth/signup/individual`	`POST /api/auth/signup/corporate`
로그인	`POST /api/auth/login`	`POST /api/auth/login/individual`	`POST /api/auth/login/corporate`
아이디 중복 검사	`GET /api/auth/check-userid`	`GET /api/auth/check-userid/individual`	`GET /api/auth/check-userid/corporate`
이메일 중복 검사	`GET /api/auth/check-email`	`GET /api/auth/check-email/individual`	`GET /api/auth/check-email/corporate`
전화번호 중복 검사	`GET /api/auth/check-phone`	`GET /api/auth/check-phone/individual`	`GET /api/auth/check-phone/corporate`
회원 찾기	-	`POST /api/members/individual/find-id`	`POST /api/members/corporate/find-id`
이메일 수정	`PUT /api/members/myinfo/email`	(JWT 기반, 동일)	(JWT 기반, 동일)

🎯 사용 시나리오

시나리오 1: 같은 전화번호로 일반 + 법인 회원가입

1️⃣ 일반회원 가입
   POST /api/auth/signup/individual
   phone: "010-1234-5678"
   userId: "individual001"
   → 성공 ✅

2️⃣ 법인회원 가입 (같은 전화번호)
   POST /api/auth/signup/corporate
   phone: "010-1234-5678"  ← 같은 전화번호
   userId: "corporate001"
   → 성공 ✅ (memberCategory 다르므로 중복 아님)

시나리오 2: 회원 찾기

일반회원이 아이디를 잊은 경우:
  POST /api/members/individual/find-id
  name: "홍길동"
  phone: "010-1234-5678"
  → maskedUserId: "in***01" 반환

법인회원이 아이디를 잊은 경우:
  POST /api/members/corporate/find-id
  businessNumber: "123-45-67890"
  phone: "010-1234-5678"
  → maskedUserId: "co***01", companyName 반환

시나리오 3: 로그인 선택

통합 로그인 (기존):
  POST /api/auth/login (memberCategory 구분 안 함)
  
분리된 로그인 (새로운):
  - 일반회원 전용: POST /api/auth/login/individual
  - 법인회원 전용: POST /api/auth/login/corporate

⚠️ 주의사항

memberCategory 필드
- 모든 회원은 INDIVIDUAL 또는 CORPORATE 중 하나의 카테고리를 가짐
- 회원가입 시 자동 설정됨
- 변경 불가
중복 검사
- 통합 API: 모든 회원 중복 검사
- 카테고리별 API: 해당 카테고리 내에서만 중복 검사
- 예: check-userid/individual에서 사용 가능해도 check-userid/corporate에서는 중복일 수 있음
로그인 선택
- 클라이언트가 회원 타입을 알고 있으면 분리 API 사용 권장
- 회원 타입을 모를 경우 통합 API 사용
법인회원 승인
- 법인회원은 businessNumber와 businessRegistration 파일 필수
- 관리자 승인 전: approvalStatus = PENDING
- 관리자 승인 후: approvalStatus = APPROVED → 서비스 이용 가능

🔗 cURL 테스트 예제

일반회원 가입

curl -X POST http://localhost:8089/api/auth/signup/individual \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "testuser001",
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "홍길동",
    "phone": "010-1234-5678",
    "ageOver14Agreed": true,
    "termsAgreed": true,
    "privacyAgreed": true,
    "locationPolicyAgreed": true,
    "marketingEmailAgreed": true,
    "marketingSmsAgreed": false,
    "marketingPushAgreed": false
  }'

일반회원 로그인

curl -X POST http://localhost:8089/api/auth/login/individual \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "testuser001",
    "password": "SecurePass123!"
  }'

아이디 중복 검사 (일반회원)

curl -X GET "http://localhost:8089/api/auth/check-userid/individual?userId=testuser001"

이메일 중복 검사 (법인회원)

curl -X GET "http://localhost:8089/api/auth/check-email/corporate?email=corp@example.com"

전화번호 중복 검사 (일반회원)

curl -X GET "http://localhost:8089/api/auth/check-phone/individual?phone=010-1234-5678"

📝 버전 히스토리

버전	날짜	변경사항
1.0	2025-12-01	초기 작성 - 회원 카테고리 분리 API 문서화

💬 지원

API 관련 문의 사항이 있으시면 백엔드 팀에 연락 주시기 바랍니다.

마지막 업데이트: 2025-12-01