추가 기능 - 승인제 참여 확장 명세

[claudia99503]

V2 Group API – 승인제 참여 확장 명세

---

18. 모임 참여 신청 (승인제 전용)

POST /api/v2/groups/{groupId}/attendance/request

APPROVAL_REQUIRED 모임에 대해
참여를 “신청(PENDING)” 하는 API입니다.

FREE 모임에서는 사용할 수 없습니다.

---

📥 Request

POST /api/v2/groups/{groupId}/attendance/request

Headers

이름	값	필수
Authorization	Bearer {JWT}	O
Content-Type	application/json	O

Path Variables

이름	타입	필수	설명
groupId	Long	O	모임 ID

Body

{
  "message": "저도 참여하고 싶습니다!"
}

---

참여 신청 정책

1. 로그인 사용자만 가능
   JWT 필수

2. 승인제 모임에서만 가능
   joinPolicy = APPROVAL_REQUIRED
   FREE 모임 호출 시 오류

3. 기존 멤버십 상태에 따른 처리

기존 상태	처리 결과
멤버십 없음	신규 생성 (PENDING)
ATTEND	오류
PENDING	오류
REJECTED	오류
LEFT	오류
KICKED	오류
BANNED	오류

4. 신청 메시지 정책

• 최대 50자
• null 허용

5. 처리 결과

• 멤버십 생성
  • role = MEMBER
  • status = PENDING
• 방장에게 참여 신청 알림 생성

---

📤 Response (200 OK)

{
  "status": 200,
  "success": true,
  "data": {
    "groupId": 10,
    "joinPolicy": "APPROVAL_REQUIRED",
    "myMembership": {
      "groupUserId": 55,
      "role": "MEMBER",
      "status": "PENDING"
    },
    "serverTime": "2025-12-24T13:22:01.123456"
  }
}

---

오류 케이스

HTTP	ErrorCode	조건
401	UNAUTHORIZED	인증 실패
404	GROUP_NOT_FOUND_BY_ID	모임 없음
409	GROUP_JOIN_POLICY_NOT_APPROVAL_REQUIRED	승인제 모임 아님
409	GROUP_ALREADY_PENDING	이미 신청 대기중
409	GROUP_ALREADY_ATTEND	이미 참여 중
409	GROUP_TARGET_STATUS_NOT_REQUESTABLE	신청 불가 상태

---

19. 참여 신청 취소 (PENDING 전용)

POST /api/v2/groups/{groupId}/attendance/request/cancel

승인 대기 중(PENDING)인 참여 신청을 취소하는 API입니다.

---

📥 Request

POST /api/v2/groups/{groupId}/attendance/request/cancel

Headers

이름	값	필수
Authorization	Bearer {JWT}	O

Path Variables

이름	타입	필수	설명
groupId	Long	O	모임 ID

Body 없음

---

참여 신청 취소 정책

1. 로그인 사용자만 가능

2. 대상 멤버십 상태 제한

• 반드시 PENDING 상태여야 함

3. 처리 결과

• 해당 멤버십 삭제
• ATTEND 인원 변화 없음
• 모임 상태 변화 없음

---

📤 Response (200 OK)

{
  "status": 200,
  "success": true,
  "data": {
    "groupId": 10,
    "canceled": true,
    "serverTime": "2025-12-24T13:25:11.789012"
  }
}

---

오류 케이스

HTTP	ErrorCode	조건
401	UNAUTHORIZED	인증 실패
404	GROUP_NOT_FOUND_BY_ID	모임 없음
404	GROUP_USER_NOT_FOUND	멤버십 없음
409	GROUP_TARGET_STATUS_NOT_PENDING	PENDING 아님

---

20. 승인 대기자 목록 조회 (승인 페이지)

GET /api/v2/groups/{groupId}/attendance/pending

승인제 모임에 대해
현재 PENDING 상태인 신청자 목록을 조회하는 API입니다.

---

📥 Request

GET /api/v2/groups/{groupId}/attendance/pending

Headers

이름	값	필수
Authorization	Bearer {JWT}	O

Path Variables

이름	타입	필수	설명
groupId	Long	O	모임 ID

---

조회 정책

1. HOST만 조회 가능

2. 승인제 모임에서만 가능

3. 반환 대상

• status = PENDING 인 멤버십만 반환
• 신청 메시지 포함

4. 정렬 기준

• requestedAt asc (먼저 신청한 순)

5. 페이징 정책

• 페이징 없이 전체 조회

---

📤 Response (200 OK)

{
  "status": 200,
  "success": true,
  "data": {
    "groupId": 10,
    "joinPolicy": "APPROVAL_REQUIRED",
    "pendingMembers": [
      {
        "userId": 201,
        "groupUserId": 55,
        "nickName": "Applicant1",
        "profileImage": null,
        "profileMessage": "백엔드 개발자",
        "requestMessage": "참여하고 싶습니다!",
        "requestedAt": "2025-12-24T13:20:10.123456"
      }
    ],
    "serverTime": "2025-12-24T13:30:00.000000"
  }
}

---

오류 케이스

HTTP	ErrorCode	조건
401	UNAUTHORIZED	인증 실패
403	GROUP_HOST_ONLY	HOST 아님
404	GROUP_NOT_FOUND_BY_ID	모임 없음
409	GROUP_JOIN_POLICY_NOT_APPROVAL_REQUIRED	승인제 모임 아님

---

(중요) 승인제 모임 조회 API 적용 규칙

기존 V2 API에서
승인제 모임(APPROVAL_REQUIRED) + 사용자 멤버십 상태가 PENDING 인 경우
다음 UI 동작을 보장해야 합니다.

---

적용 대상 API

• 모임 목록 조회
  GET /api/v2/groups

• 내 모임 목록 조회
  GET /api/v2/groups/me

• 모임 상세 조회
  GET /api/v2/groups/{groupId}

---

공통 규칙

• myMembership.status = PENDING 인 경우

  • 사용자에게 “대기중” 상태를 명확히 노출해야 합니다.

• PENDING 상태의 모임에 대해

  • 참여 신청 취소가 가능해야 합니다.

[claudia99503]

@HopeFullee

[HopeFullee]

좋은데용?! 고생하셨습니당

[claudia99503]

@HopeFullee 피드백 팍팍 해주세요 배고파요