#  회원 (User)

### [관리자] 회원 통계 조회
- **URL**: `GET /users/stats`
- **Header**: `Authorization` 필수 (ADMIN)
- **Response**: `200 OK`

### [관리자] 회원 목록 조회
- **URL**: `GET /users`
- **Header**: `Authorization` 필수 (ADMIN)
- **Query Params**:
  - `page`: 페이지 번호 (기본 1)
  - `limit`: 페이지당 개수 (기본 10)
  - `role`: `CUSTOMER` | `SELLER` | `ADMIN` (선택)
  - `searchType`: `nickname` | `email` | `phone` (선택)
  - `search`: 검색어 (선택, searchType과 함께 사용)
- **Response**: `200 OK` (Paging)

### [관리자 / 본인] 회원 상세 조회
관리자는 모든 회원, 일반 회원은 본인만 조회 가능합니다.

- **URL**: `GET /users/:id`
- **Header**: `Authorization` 필수
- **Response**: `200 OK`
- **Error Codes**:
  - `401`: 인증 필요
  - `403`: 타인 조회 시도 (본인 또는 ADMIN만 가능)
  - `USER_NOT_FOUND`: 회원 없음

### [로그인 유저] 내 프로필 수정
- **URL**: `PATCH /users/me`
- **Header**: `Authorization` 필수
- **Body** (multipart/form-data 또는 application/json):
  - `nickname`: 닉네임 (선택)
  - `phone`: 연락처 (선택)
  - `introduction`: 자기소개 (선택, SELLER 등)
  - `password`: 새 비밀번호 (선택)
  - `profileImage`: 프로필 이미지 파일 (선택, multipart 시)
- **Response**: `200 OK`
- **Error Codes**:
  - `NO_UPDATE_DATA`: 수정할 항목 없음

### [관리자] 회원 메모 수정
회원 상세에 대한 관리자 전용 메모를 저장/수정합니다. 상세 조회 시 `note` 필드로 내려갑니다.

- **URL**: `PATCH /users/:id/note`
- **Header**: `Authorization` 필수 (ADMIN)
- **Body**:
  ```json
  { "note": "메모 내용" }

• note: 문자열(최대 500자) 또는 null(메모 삭제)
• Response: 200 OK — { "success": true, "data": { "note": "..." } }
• Error Codes:
  • MISSING_NOTE: body에 note 미포함
  • USER_NOT_FOUND: 회원 없음

예약 (Reservation)

[고객] 예약 생성 (결제 포함)

슬롯을 선택하고 포인트를 차감하여 예약을 생성합니다. (쿠폰 적용 가능)

• URL: POST /reservations
• Header: Authorization 필수
• Body:

  {
    "slotId": "uuid",
    "userCouponId": "uuid (선택)"
  }
  

• Response: 201 Created

  {
    "success": true,
    "data": { "id": "reservation_id", "status": "BOOKED", ... }
  }
  

• Error Codes:
  • SLOT_NOT_FOUND: 슬롯이 없음
  • SLOT_CLOSED: 예약 마감됨
  • SLOT_FULL: 정원 초과
  • INSUFFICIENT_POINTS: 포인트 잔액 부족

[고객] 내 예약 목록 조회

• URL: GET /reservations/me
• Header: Authorization 필수
• Query Params:
  • page: 페이지 번호 (기본 1)
  • limit: 페이지당 개수 (기본 10)
  • status: BOOKED | CANCELED | COMPLETED (선택)
• Response: 200 OK (Paging)

[고객] 예약 취소 (환불)

• URL: DELETE /reservations/:id
• Header: Authorization 필수
• Body:

  {
    "cancelNote": "단순 변심" // (선택)
  }
  

• Response: 200 OK

리뷰 (Review)

[고객] 리뷰 작성

수강 완료(COMPLETED)된 클래스에 대해 리뷰를 작성합니다.

• URL: POST /reviews
• Header: Authorization 필수
• Body:

  {
    "reservationId": "uuid", // 필수
    "rating": 5, // 1~5 정수
    "content": "강사님이 친절해요",
    "imgUrls": ["https://...", "https://..."] // 선택
  }
  

• Response: 201 Created
• Error Codes:
  • DUPLICATE_REVIEW: 이미 리뷰를 작성함
  • INVALID_STATUS: 완료된 예약이 아님

[공통] 센터별 리뷰 조회

• URL: GET /reviews/center/:centerId
• Query Params: page, limit
• Response: 200 OK

포인트 (Point)

[고객] 포인트 충전

PG사 결제 완료 후 호출하여 충전 처리합니다.

• URL: POST /points/charge
• Header: Authorization 필수
• Body:

  {
    "amount": 10000,
    "paymentKey": "toss_payment_key", 
    "orderId": "order_id"
  }
  

• Response: 200 OK

  {
    "success": true,
    "data": { "pointHistory": { ... }, "balanceAfter": 15000 }
  }
  

[고객] 내 포인트 잔액 조회

• URL: GET /points/me
• Header: Authorization 필수
• Response: 200 OK

  { "success": true, "data": { "pointBalance": 5000 } }
  

쿠폰 (Coupon)

Base path: /coupons. 모든 API는 Authorization 헤더 필수입니다.

[판매자/관리자] 쿠폰 템플릿 생성

• URL: POST /coupons
• Header: Authorization 필수 (SELLER 또는 ADMIN)
• Body:

  {
    "name": "신규 가입 1000P 할인",
    "discountType": "AMOUNT",
    "usageValue": 1000,
    "expiresAt": "2025-12-31T23:59:59.000Z"
  }
  

  • name: 쿠폰 이름 (필수)
  • discountType: AMOUNT(금액 할인) | PERCENTAGE(비율 할인)
  • usageValue: 할인 값 (정수, 금액 또는 퍼센트)
  • expiresAt: 만료일 (ISO 8601)
• Response: 201 Created

[판매자/관리자] 내가 만든 쿠폰 목록 조회

• URL: GET /coupons
• Header: Authorization 필수
• Response: 200 OK (내가 발급한 쿠폰 템플릿 목록)

[판매자/관리자] 쿠폰 지급

특정 유저에게 쿠폰을 발급합니다.

• URL: POST /coupons/give
• Header: Authorization 필수 (SELLER 또는 ADMIN)
• Body:

  {
    "userId": "user_cuid",
    "templateId": "template_cuid"
  }
  

• Response: 201 Created

[본인/관리자] 특정 유저 쿠폰함 조회

본인은 자신의 쿠폰함, 관리자는 모든 유저 쿠폰함 조회 가능.

• URL: GET /coupons/user/:userId
• Header: Authorization 필수
• Response: 200 OK (해당 유저의 보유 쿠폰 목록)
• Error Codes:
  • 403: 본인 또는 ADMIN이 아닌 경우

[판매자/관리자] 쿠폰 템플릿 수정

• URL: PUT /coupons/:id
• Header: Authorization 필수 (SELLER 또는 ADMIN)
• Body (모든 필드 선택):

  {
    "name": "수정된 쿠폰명",
    "discountType": "PERCENTAGE",
    "usageValue": 10,
    "expiresAt": "2025-12-31T23:59:59.000Z"
  }
  

• Response: 200 OK

[판매자/관리자] 쿠폰 템플릿 삭제

• URL: DELETE /coupons/:id
• Header: Authorization 필수 (SELLER 또는 ADMIN)
• Response: 200 OK — { "success": true, "message": "쿠폰이 삭제되었습니다." }

인증 (Auth)

회원가입

• URL: POST /auth/signup
• Body:

  {
    "email": "user@example.com",
    "password": "password123",
    "nickname": "헬린이",
    "phone": "010-1234-5678",
    "role": "CUSTOMER" // SELLER
  }
  

로그인

• URL: POST /auth/login
• Body: { "email": "...", "password": "..." }
• Response: 200 OK

  {
    "success": true,
    "data": {
      "accessToken": "jwt_access_token",
      "refreshToken": "jwt_refresh_token",
      "user": { ... }
    }
  }
  

토큰 갱신 (Silent Refresh)

Access Token 만료 시 호출합니다. (쿠키 기반)

• URL: POST /auth/refresh
• Response: 200 OK (새로운 토큰 발급)

로그아웃

• URL: POST /auth/logout
• Response: 200 OK (쿠키 제거)

[로그인 유저] 내 정보 조회

• URL: GET /auth/me
• Header: Authorization 필수
• Response: 200 OK (현재 로그인 유저 정보)