Group API

1️⃣ Group APIs 명세서

• V1: Group API
• V2: Group API

2️⃣ V2 모임 서비스 킥오프

V2 모임(Group) 서비스 개편

🗣 기획자

이번 모임 서비스 V2의 목표는 단순합니다.
“사람들이 약속을 더 쉽게 만들고, 더 가볍게 참여할 수 있게 만드는 것”이에요.

사용자는 더 이상 복잡한 절차 없이,
언제(startTime), 어디서(location), 어떤 모임인지(description)가 명확한 모임을 직접 만들 수 있어야 합니다.
그리고 만들어진 모임은 목록에서 찾아보고, 마음에 들면 참여하고(attend),
상황이 바뀌면 부담 없이 나갈 수(left) 있어야 해요.

🗣 기획자 – 모임의 기본 구조

모임은 단순한 게시글이 아니라, 하나의 “약속 단위”입니다.

그래서 모임에는 항상 다음 정보가 포함됩니다.

• 모임 제목 (무엇을 하는지)
• 모임 장소 (어디서 하는지)
• 시작 시간과 종료 시간 (언제 하는지)
• 모임 설명 (어떤 분위기인지)
• 최대 참여 인원 (몇 명까지 가능한지)

이 정보들은 모임의 신뢰도를 결정하는 핵심이기 때문에,
필수 값이 빠진 모임은 만들 수 없도록 설계했습니다.

🗣 기획자 – 모임 상태는 항상 예측 가능해야 합니다

모임은 아무 상태로나 왔다 갔다 하면 안 됩니다.
사용자는 “지금 이 모임에 참여할 수 있는지”를 한눈에 알 수 있어야 해요.

그래서 모임은 아래의 정해진 흐름으로만 움직입니다.

RECRUITING (모집중)

• 기본 상태입니다. 참여가 가능합니다.

FULL (정원마감)

• 인원이 꽉 찼을 때 자동으로 전환됩니다.
• 더 이상 참여할 수 없습니다.

CLOSED (모집마감)

• 운영자가 모집을 닫은 상태입니다.
• 인원이 남아 있어도 참여는 불가능합니다.

CANCELLED (모임취소)

• 운영자가 모임을 취소한 상태입니다.

FINISHED (모임종료)

• 모임 시간이 지나거나, 운영자가 종료 처리한 상태입니다.

이 상태들은 허용된 전이 규칙 안에서만 변경됩니다.
임의로 상태를 바꾸는 일은 없고,
취소되거나 종료된 모임은 다시 수정할 수 없도록 해서
데이터와 사용자 경험의 일관성을 지킵니다.

🗣 기획자 – 모임 참여는 가볍고, 명확해야 합니다

모임 참여는 최대한 단순해야 합니다.

• 모집중(RECRUITING)일 때만 참여 가능
• 정원이 차면 자동으로 FULL로 변경
• 이미 참여한 사용자는 다시 참여할 수 없음
• 나간 사용자(LEFT, KICKED)는 다시 참여 가능
• 차단된 사용자(BANNED)는 다시 참여 불가

운영자(HOST)는 모임의 주최자이기 때문에
참여/탈퇴 개념이 없고, 항상 모임에 속해 있습니다.

🗣 기획자 – “보기 좋은 모임”을 위한 이미지 정책

모임은 결국 사람이 고르는 콘텐츠이기 때문에,
이미지의 역할이 굉장히 중요합니다.

사용자는 모임 이미지를 최대 3장까지 등록할 수 있습니다.
이미지를 업로드하면 서버가 자동으로 두 가지 버전을 만들어 관리합니다.

• 카드용 이미지 (440 × 240)
• 썸네일 이미지 (100 × 100)

모든 이미지는 WEBP 형식으로 통일됩니다.

이렇게 서버가 규격을 보증하기 때문에,
프론트는 화면 크기에 맞게 안정적으로 이미지를 표시할 수 있습니다.

만약 사용자가 이미지를 하나도 등록하지 않더라도,
서비스는 기본 이미지를 제공해서
빈 화면이나 깨진 UI가 나오지 않도록 합니다.

🗣 기획자 – 이미지 업로드는 “선 업로드 방식”입니다

이미지는 모임 생성/수정과 분리해서 먼저 업로드합니다.

1. 사용자가 이미지를 먼저 업로드합니다.
2. 서버가 imageKey를 발급합니다.
3. 모임 생성/수정 시 imageKey를 전달해 이미지를 확정합니다.

이 방식의 목적은,
모임 생성 도중 실패해도 이미지 정합성이 깨지지 않게 하고
서버가 이미지 URL 규격을 직접 보증하기 위함입니다.

imageKey는 2시간 동안만 유효하며,
업로드한 사람만 사용할 수 있고,
모임 생성 또는 수정에서 한 번 사용되면 즉시 소비됩니다.

🗣 기획자 – 태그는 분위기를 전달하는 장치입니다

태그는 모임을 설명하는 보조 수단입니다.
“이 모임이 어떤 분위기인지”를 빠르게 전달해 줍니다.

• 최대 10개까지 등록 가능
• 중복 태그는 허용하지 않음
• 수정 시에는 기존 태그를 모두 교체

태그는 목록과 검색에서도 함께 사용되어,
사용자가 원하는 모임을 더 쉽게 찾을 수 있게 도와줍니다.

🗣 기획자 – 운영 안정성도 중요합니다

모임 생성이 너무 쉽게 반복되면 서비스 품질이 떨어집니다.
그래서 같은 사용자는 짧은 시간 안에 연속으로 모임을 만들 수 없도록
쿨다운 정책을 적용했습니다.

• 모임 생성 후 일정 시간 동안 재생성 불가
• 스팸성 모임 생성 방지 목적

또한,

• 운영자(HOST)만 수정/삭제 가능
• 취소되거나 종료된 모임은 수정 불가
• 삭제 시 DB 삭제 후 이미지 파일 정리

이런 제약들은 모두 데이터 일관성과 운영 안정성을 위한 선택입니다.

3️⃣ V2 모임 서비스 요구사항 확인

• V2: Group Requirements

V2 모임 서비스 요구사항의 자세한 설명은 V2: Group Requirements에서 확인할 수 있습니다.

1. 🖼️ 이미지 정책(사전 업로드 방식)

핵심 내용 정리

• 모임 이미지는 “사전 업로드 → imageKey로 등록” 방식입니다.
• 업로드는 최대 3장, 변형은 440x240 / 100x100 WEBP 2종입니다.
• pre-upload imageKey는 2시간 유효하며, 업로더만 사용할 수 있고, 사용 시 1회 소비됩니다.
• 수정의 imageKeys는 “최종 상태”이며, null=변경 없음, []=전체 삭제, [..]=그대로 최종 반영(0번째 대표)입니다.
• 모임 삭제는 DB 삭제 확정 후(커밋 후) 이미지 파일을 삭제합니다.

2. 👥 모임 상태 · 참가 · 정원 · 역할 정책

핵심 내용 정리

• 모임은 RECRUITING / FULL / CLOSED / CANCELLED / FINISHED 5가지 상태를 가집니다.
• 참가 가능 여부는 모집중(RECRUITING) + 남은 자리 있음 조건으로 판단합니다.
• HOST는 참가·탈퇴가 불가능하며, 수정·삭제 권한을 가집니다.
• 참가자 수는 ATTEND 상태만 집계합니다.
• FULL 상태는 자동 전환/복귀되며, CANCELLED·FINISHED는 최종 상태입니다.

3. 📝 모임 생성 정책 (입력값 검증 · 쿨다운 · 기본 동작)

핵심 내용 정리

• 모임 생성은 로그인한 사용자만 가능하며, 생성자는 자동으로 HOST가 됩니다.
• 모임 생성에는 5초 쿨다운이 적용됩니다.
• 제목·설명·위치·시간·정원은 필수 또는 조건부 필수입니다.
• 태그는 최대 10개까지 가능하며, 중복은 허용되지 않습니다.
• 이미지는 사전 업로드된 imageKey를 통해 최대 3장까지 등록할 수 있습니다.

4. 🔍 모임 목록 조회 정책 (검색 · 필터 · 커서 페이징)

핵심 내용 정리

• 모임 목록 조회는 커서 기반 페이징 방식입니다.
• 기본 필터는 ACTIVE이며, 상태 기준으로 노출 범위가 결정됩니다.
• 키워드 검색은 제목·위치·설명을 대상으로 합니다.
• 목록에서는 대표 이미지 최대 3장과 태그만 요약 노출합니다.
• 참가 가능 여부(joinable)와 남은 자리(remainingSeats)는 서버에서 계산합니다.

5. 📄 모임 수정 정책 상세 (부분 수정 · 불변 조건 · 이미지/태그 연계)

핵심 내용 정리

• 모임 수정은 HOST만 가능합니다.
• 수정 요청은 “부분 수정”이지만, 각 필드는 최종 상태 기준으로 반영됩니다.
• CANCELLED·FINISHED 상태의 모임은 수정할 수 없습니다.
• 태그·이미지는 null과 []의 의미가 명확히 다릅니다.
• 이미지 수정은 최종 imageKeys 리스트 기준으로 동작합니다.

6. 🧩 예외 · 에러 정책 (주요 실패 시나리오 정리)

핵심 내용 정리

• 모든 실패는 명확한 원인과 메시지를 가진 에러로 응답됩니다.
• 인증·권한·상태·입력값·정합성 오류를 구분합니다.
• 서버 오류가 아닌 경우, 대부분은 사용자 행동에 따른 예측 가능한 실패입니다.
• 실패한 요청은 부분 반영 없이 전체 롤백됩니다.

7. 🔐 권한 · 보안 정책 정리 (HOST / MEMBER / 비로그인 행동 기준)

핵심 내용 정리

• 모든 모임 관련 행동은 사용자 역할(HOST / MEMBER / 비로그인) 기준으로 제한됩니다.
• 인증(Authentication)과 권한(Authorization)은 명확히 구분됩니다.
• 서버는 항상 권한을 우선 검증하며, 프론트 요청을 전적으로 신뢰하지 않습니다.
• “보여줄 수 있음”과 “행동할 수 있음”은 별개의 개념입니다.