-
Notifications
You must be signed in to change notification settings - Fork 0
Group API
🗣 기획자
이번 모임 서비스 V2의 목표는 단순합니다.
“사람들이 약속을 더 쉽게 만들고, 더 가볍게 참여할 수 있게 만드는 것”이에요.
사용자는 더 이상 복잡한 절차 없이,
언제(startTime), 어디서(location), 어떤 모임인지(description)가 명확한 모임을 직접 만들 수 있어야 합니다.
그리고 만들어진 모임은 목록에서 찾아보고, 마음에 들면 참여하고(attend),
상황이 바뀌면 부담 없이 나갈 수(left) 있어야 해요.
🗣 기획자 – 모임의 기본 구조
모임은 단순한 게시글이 아니라, 하나의 “약속 단위”입니다.
그래서 모임에는 항상 다음 정보가 포함됩니다.
- 모임 제목 (무엇을 하는지)
- 모임 장소 (어디서 하는지)
- 시작 시간과 종료 시간 (언제 하는지)
- 모임 설명 (어떤 분위기인지)
- 최대 참여 인원 (몇 명까지 가능한지)
이 정보들은 모임의 신뢰도를 결정하는 핵심이기 때문에,
필수 값이 빠진 모임은 만들 수 없도록 설계했습니다.
🗣 기획자 – 모임 상태는 항상 예측 가능해야 합니다
모임은 아무 상태로나 왔다 갔다 하면 안 됩니다.
사용자는 “지금 이 모임에 참여할 수 있는지”를 한눈에 알 수 있어야 해요.
그래서 모임은 아래의 정해진 흐름으로만 움직입니다.
RECRUITING (모집중)
- 기본 상태입니다. 참여가 가능합니다.
FULL (정원마감)
- 인원이 꽉 찼을 때 자동으로 전환됩니다.
- 더 이상 참여할 수 없습니다.
CLOSED (모집마감)
- 운영자가 모집을 닫은 상태입니다.
- 인원이 남아 있어도 참여는 불가능합니다.
CANCELLED (모임취소)
- 운영자가 모임을 취소한 상태입니다.
FINISHED (모임종료)
- 모임 시간이 지나거나, 운영자가 종료 처리한 상태입니다.
이 상태들은 허용된 전이 규칙 안에서만 변경됩니다.
임의로 상태를 바꾸는 일은 없고,
취소되거나 종료된 모임은 다시 수정할 수 없도록 해서
데이터와 사용자 경험의 일관성을 지킵니다.
🗣 기획자 – 모임 참여는 가볍고, 명확해야 합니다
모임 참여는 최대한 단순해야 합니다.
- 모집중(RECRUITING)일 때만 참여 가능
- 정원이 차면 자동으로 FULL로 변경
- 이미 참여한 사용자는 다시 참여할 수 없음
- 나간 사용자(LEFT, KICKED)는 다시 참여 가능
- 차단된 사용자(BANNED)는 다시 참여 불가
운영자(HOST)는 모임의 주최자이기 때문에
참여/탈퇴 개념이 없고, 항상 모임에 속해 있습니다.
🗣 기획자 – “보기 좋은 모임”을 위한 이미지 정책
모임은 결국 사람이 고르는 콘텐츠이기 때문에,
이미지의 역할이 굉장히 중요합니다.
사용자는 모임 이미지를 최대 3장까지 등록할 수 있습니다.
이미지를 업로드하면 서버가 자동으로 두 가지 버전을 만들어 관리합니다.
- 카드용 이미지 (440 × 240)
- 썸네일 이미지 (100 × 100)
모든 이미지는 WEBP 형식으로 통일됩니다.
이렇게 서버가 규격을 보증하기 때문에,
프론트는 화면 크기에 맞게 안정적으로 이미지를 표시할 수 있습니다.
만약 사용자가 이미지를 하나도 등록하지 않더라도,
서비스는 기본 이미지를 제공해서
빈 화면이나 깨진 UI가 나오지 않도록 합니다.
🗣 기획자 – 이미지 업로드는 “선 업로드 방식”입니다
이미지는 모임 생성/수정과 분리해서 먼저 업로드합니다.
- 사용자가 이미지를 먼저 업로드합니다.
- 서버가 imageKey를 발급합니다.
- 모임 생성/수정 시 imageKey를 전달해 이미지를 확정합니다.
이 방식의 목적은,
모임 생성 도중 실패해도 이미지 정합성이 깨지지 않게 하고
서버가 이미지 URL 규격을 직접 보증하기 위함입니다.
imageKey는 2시간 동안만 유효하며,
업로드한 사람만 사용할 수 있고,
모임 생성 또는 수정에서 한 번 사용되면 즉시 소비됩니다.
🗣 기획자 – 태그는 분위기를 전달하는 장치입니다
태그는 모임을 설명하는 보조 수단입니다.
“이 모임이 어떤 분위기인지”를 빠르게 전달해 줍니다.
- 최대 10개까지 등록 가능
- 중복 태그는 허용하지 않음
- 수정 시에는 기존 태그를 모두 교체
태그는 목록과 검색에서도 함께 사용되어,
사용자가 원하는 모임을 더 쉽게 찾을 수 있게 도와줍니다.
🗣 기획자 – 운영 안정성도 중요합니다
모임 생성이 너무 쉽게 반복되면 서비스 품질이 떨어집니다.
그래서 같은 사용자는 짧은 시간 안에 연속으로 모임을 만들 수 없도록
쿨다운 정책을 적용했습니다.
- 모임 생성 후 일정 시간 동안 재생성 불가
- 스팸성 모임 생성 방지 목적
또한,
- 운영자(HOST)만 수정/삭제 가능
- 취소되거나 종료된 모임은 수정 불가
- 삭제 시 DB 삭제 후 이미지 파일 정리
이런 제약들은 모두 데이터 일관성과 운영 안정성을 위한 선택입니다.
V2 모임 서비스 요구사항의 자세한 설명은 V2: Group Requirements에서 확인할 수 있습니다.
핵심 내용 정리
- 모임 이미지는 “사전 업로드 → imageKey로 등록” 방식입니다.
- 업로드는 최대 3장, 변형은 440x240 / 100x100 WEBP 2종입니다.
- pre-upload imageKey는 2시간 유효하며, 업로더만 사용할 수 있고, 사용 시 1회 소비됩니다.
- 수정의 imageKeys는 “최종 상태”이며,
null=변경 없음,[]=전체 삭제,[..]=그대로 최종 반영(0번째 대표)입니다. - 모임 삭제는 DB 삭제 확정 후(커밋 후) 이미지 파일을 삭제합니다.
핵심 내용 정리
- 모임은 RECRUITING / FULL / CLOSED / CANCELLED / FINISHED 5가지 상태를 가집니다.
- 참가 가능 여부는 모집중(RECRUITING) + 남은 자리 있음 조건으로 판단합니다.
- HOST는 참가·탈퇴가 불가능하며, 수정·삭제 권한을 가집니다.
- 참가자 수는 ATTEND 상태만 집계합니다.
- FULL 상태는 자동 전환/복귀되며, CANCELLED·FINISHED는 최종 상태입니다.
핵심 내용 정리
- 모임 생성은 로그인한 사용자만 가능하며, 생성자는 자동으로 HOST가 됩니다.
- 모임 생성에는 5초 쿨다운이 적용됩니다.
- 제목·설명·위치·시간·정원은 필수 또는 조건부 필수입니다.
- 태그는 최대 10개까지 가능하며, 중복은 허용되지 않습니다.
- 이미지는 사전 업로드된 imageKey를 통해 최대 3장까지 등록할 수 있습니다.
핵심 내용 정리
- 모임 목록 조회는 커서 기반 페이징 방식입니다.
- 기본 필터는 ACTIVE이며, 상태 기준으로 노출 범위가 결정됩니다.
- 키워드 검색은 제목·위치·설명을 대상으로 합니다.
- 목록에서는 대표 이미지 최대 3장과 태그만 요약 노출합니다.
- 참가 가능 여부(joinable)와 남은 자리(remainingSeats)는 서버에서 계산합니다.
핵심 내용 정리
- 모임 수정은 HOST만 가능합니다.
- 수정 요청은 “부분 수정”이지만, 각 필드는 최종 상태 기준으로 반영됩니다.
- CANCELLED·FINISHED 상태의 모임은 수정할 수 없습니다.
- 태그·이미지는 null과 []의 의미가 명확히 다릅니다.
- 이미지 수정은 최종 imageKeys 리스트 기준으로 동작합니다.
핵심 내용 정리
- 모든 실패는 명확한 원인과 메시지를 가진 에러로 응답됩니다.
- 인증·권한·상태·입력값·정합성 오류를 구분합니다.
- 서버 오류가 아닌 경우, 대부분은 사용자 행동에 따른 예측 가능한 실패입니다.
- 실패한 요청은 부분 반영 없이 전체 롤백됩니다.
핵심 내용 정리
- 모든 모임 관련 행동은 사용자 역할(HOST / MEMBER / 비로그인) 기준으로 제한됩니다.
- 인증(Authentication)과 권한(Authorization)은 명확히 구분됩니다.
- 서버는 항상 권한을 우선 검증하며, 프론트 요청을 전적으로 신뢰하지 않습니다.
- “보여줄 수 있음”과 “행동할 수 있음”은 별개의 개념입니다.