그룹 관리

[SongMinQQ]

#️⃣연관된 이슈

#14

📝작업 내용

1) API 최신화 (e2254e9)

• 그룹/인증 API 경로를 최신 명세에 맞게 정리했습니다.
• REQUEST_PATHS.GROUPS.MEMBERS, KICK_MEMBER, TRANSFER_OWNER를 추가/정비했습니다.
• 인증 응답 타입(OAuthLoginResponse)과 세션 체크(hasUserSession) 기준 상태코드를 최신 규격으로 반영했습니다.
• 공개 그룹 목록 조회는 keyword/cursor/size 파라미터를 기준으로 정리했습니다.
• 파일 업로드 API는 신규/레거시 응답 키(presignedUrlResponses, presignedUrlResponseDtos)를 모두 대응하도록 보완했습니다.

2) 멤버 목록/관리 기능 구현 (71d7722)

• /group/[id]/members 페이지에서 멤버 목록 조회를 구현했습니다.
• 그룹장(role=OWNER)일 때만 멤버 카드에 그룹장 양도, 추방 액션을 노출하도록 분기했습니다.
• 액션 실행 전 확인 모달을 거치도록 구성했습니다.
• 처리 중에는 동일 멤버 중복 요청을 막고(processingMemberId), 성공/실패 토스트를 표시합니다.
• 성공 시 detail/menu/members 쿼리를 함께 무효화해서 화면 상태를 즉시 동기화합니다.

3) 그룹 쿼리 구조 분리 (0bd495c)

• 기존 group.queries.ts에 몰려 있던 쿼리를 페이지/목적 단위 훅으로 분리했습니다.
• group.query-keys.ts, group.query-utils.ts를 추가했습니다.
• useGroupDetailQuery, useGroupMenuQuery, useGroupMembersQuery, usePublicGroupsInfiniteQuery로 역할을 분리했습니다.
• 상세/사이드바/멤버/목록 화면에서 필요한 훅만 사용하도록 의존성을 정리했습니다.

문제 해결

• API 명세 변경으로 발생한 경로/타입 불일치 문제를 문서 기준으로 맞췄습니다.
• 라우트 id(string) 사용으로 생길 수 있는 파싱/유효성 문제를 공통 유틸로 방어했습니다.
• 멤버 관리 액션 후 stale UI가 남는 문제를 관련 쿼리 동시 invalidate로 해결했습니다.
• 에러 처리와 메시지가 분산되던 문제는 showErrorToast + 도메인별 TOAST_MESSAGES로 일원화했습니다.

유의사항

• transferGroupOwner, logout 요청은 빈 바디여도 application/x-www-form-urlencoded 헤더를 유지해야 합니다.
• 멤버 관리 액션은 OWNER 권한에서만 노출/실행되며, OWNER 본인에게는 액션을 표시하지 않도록 유지해야 합니다.
• routeGroupId가 유효하지 않으면 쿼리를 실행하지 않도록(enabled) 방어 로직을 유지해야 합니다.
• 그룹 관련 mutation 추가 시 GROUP_QUERY_KEYS 기준 invalidate 범위를 함께 설계해야 회귀를 줄일 수 있습니다.

주요 변경 파일

• shared/constants/paths.ts
• entities/group/model/api/types.ts
• entities/group/model/api/getGroupMembers.ts
• entities/group/model/api/kickGroupMember.ts
• entities/group/model/api/transferGroupOwner.ts
• features/group/members/model/useGroupMemberManageAction.ts
• app/group/[id]/members/page.tsx
• entities/group/queries/group.query-keys.ts
• entities/group/queries/group.query-utils.ts
• entities/group/queries/useGroupDetailQuery.ts
• entities/group/queries/useGroupMembersQuery.ts
• entities/group/queries/useGroupMenuQuery.ts
• entities/group/queries/usePublicGroupsInfiniteQuery.ts

검증/리스크

• 현재 문서는 브랜치 커밋 이력(feat/manage-group) 기준으로 정리했습니다.
• 멤버 관리 권한/오류 코드(401/403/404/409) 및 쿼리 무효화 범위에 대한 회귀 테스트는 별도 점검이 필요합니다.

스크린샷 (선택)

그룹장일시

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 Pull Request는 그룹 관리 기능을 대폭 강화하고, 백엔드 API 명세 변경에 맞춰 프론트엔드 로직을 최신화합니다. 사용자 경험을 개선하기 위해 그룹 멤버 관리, 가입 신청 처리, 그룹 정보 수정 및 삭제 기능을 추가했으며, React Query 훅을 재구성하여 데이터 관리의 효율성과 코드의 모듈성을 높였습니다. 또한, 전반적인 에러 처리 방식을 개선하여 사용자에게 더욱 명확한 피드백을 제공합니다.

Highlights

• 그룹 관리 기능 구현: 그룹 멤버 목록 조회, 멤버 추방, 그룹장 양도, 가입 신청 승인, 그룹 정보 수정 및 삭제 등 그룹 관리와 관련된 다양한 기능이 추가되었습니다.
• API 경로 및 응답 타입 최신화: 그룹 및 인증 관련 API 경로가 최신 명세에 맞춰 정리되었으며, OAuthLoginResponse와 세션 체크 기준 상태 코드가 업데이트되었습니다. 파일 업로드 API는 신규/레거시 응답 키를 모두 대응하도록 보완되었습니다.
• React Query 훅 구조 개선: 기존 group.queries.ts 파일에 집중되어 있던 쿼리 로직이 페이지/목적별 전용 훅(useGroupDetailQuery, useGroupMembersQuery, usePublicGroupsInfiniteQuery 등)으로 분리되어 코드의 가독성과 유지보수성이 향상되었습니다.
• 공통 에러 처리 및 UI 동기화: showErrorToast 유틸리티를 도입하여 에러 메시지 처리를 일원화하고, 멤버 관리 액션 성공 시 관련 쿼리를 즉시 무효화하여 UI 상태를 동기화하는 로직이 추가되었습니다.

Changelog

• AGENTS.md
  • API 예외 처리 시 showErrorToast 함수 사용에 대한 린트 규칙이 추가되었습니다.
• app/group/[id]/edit/layout.tsx
  • 그룹 ID 유효성 검사를 포함하는 그룹 편집 페이지 레이아웃이 추가되었습니다.
• app/group/[id]/edit/page.tsx
  • 그룹 정보 편집 페이지가 추가되었으며, 그룹장 권한 확인 로직이 포함되었습니다.
• app/group/[id]/members/page.tsx
  • 그룹 멤버 목록 조회 기능이 구현되었고, 그룹장에게 멤버 추방 및 양도 액션 버튼이 노출되도록 수정되었습니다. 초대 링크 및 멤버 액션 확인 모달이 통합되었습니다.
• app/group/[id]/page.tsx
  • useGroupDetailQuery의 import 경로가 업데이트되었습니다.
• app/kakao/page.tsx
  • 카카오 로그인 관련 토스트 메시지가 TOAST_MESSAGES.AUTH를 사용하도록 변경되었고, showErrorToast가 적용되었습니다.
• entities/group/model/api/approveGroupJoinApply.ts
  • 그룹 가입 신청을 승인하는 API 함수가 추가되었습니다.
• entities/group/model/api/deleteGroup.ts
  • 그룹을 삭제하는 API 함수가 추가되었습니다.
• entities/group/model/api/getGroupJoinApplies.ts
  • 그룹 가입 신청 목록을 조회하는 API 함수가 추가되었습니다.
• entities/group/model/api/getGroupMembers.ts
  • 그룹 멤버 목록을 조회하는 API 함수가 추가되었습니다.
• entities/group/model/api/getPublicGroups.ts
  • 공개 그룹 조회 시 keyword 파라미터가 추가되었고, size의 기본값이 설정되었습니다.
• entities/group/model/api/kickGroupMember.ts
  • 그룹 멤버를 추방하는 API 함수가 추가되었습니다.
• entities/group/model/api/transferGroupOwner.ts
  • 그룹장 권한을 양도하는 API 함수가 추가되었습니다.
• entities/group/model/api/types.ts
  • 그룹 멤버, 가입 신청, 그룹 업데이트/삭제 관련 DTO 및 응답 타입이 추가/확장되었습니다.
• entities/group/model/api/updateGroup.ts
  • 그룹 정보를 업데이트하는 API 함수가 추가되었습니다.
• entities/group/model/mappers.ts
  • applyGroupDetailToGroup 함수에 groupKind 매핑 로직이 추가되었습니다.
• entities/group/model/mock-data.ts
  • mockGroup에 groupKind 속성이 추가되었습니다.
• entities/group/model/types.ts
  • Group 인터페이스에 groupKind 속성이 추가되었습니다.
• entities/group/queries/group.queries.ts
  • 기존 쿼리 로직이 분리된 파일들에서 재export되도록 리팩토링되었습니다.
• entities/group/queries/group.query-keys.ts
  • 그룹 관련 React Query 키를 정의하는 파일이 추가되었습니다.
• entities/group/queries/group.query-utils.ts
  • 그룹 ID 유효성 검사 및 파싱 유틸리티 함수 파일이 추가되었습니다.
• entities/group/queries/useGroupDetailQuery.ts
  • 그룹 상세 정보를 위한 전용 React Query 훅이 추가되었습니다.
• entities/group/queries/useGroupJoinAppliesInfiniteQuery.ts
  • 그룹 가입 신청 목록 무한 스크롤을 위한 React Query 훅이 추가되었습니다.
• entities/group/queries/useGroupMembersQuery.ts
  • 그룹 멤버 목록 조회를 위한 React Query 훅이 추가되었습니다.
• entities/group/queries/useGroupMenuQuery.ts
  • 그룹 메뉴 정보를 위한 전용 React Query 훅이 추가되었습니다.
• entities/group/queries/usePublicGroupsInfiniteQuery.ts
  • 공개 그룹 목록 무한 스크롤을 위한 전용 React Query 훅이 추가되었습니다.
• entities/member/ui/member-card.tsx
  • 멤버 카드 컴포넌트에 액션 버튼을 위한 action prop이 추가되었습니다.
• features/auth/api/hasUserSession.ts
  • 세션 체크 시 404 상태 코드도 유효한 응답으로 처리하도록 로직이 업데이트되었습니다.
• features/auth/api/logout.ts
  • 사용자 로그아웃 API 함수가 추가되었습니다.
• features/auth/api/types.ts
  • OAuthLoginResponse 인터페이스에 publicUuid 속성이 추가되었습니다.
• features/group/detail/lib/groupManageModalActions.ts
  • 그룹 관리 모달의 액션 및 버튼 정의 파일이 추가되었습니다.
• features/group/detail/lib/groupMembershipAction.ts
  • 그룹 멤버십 상태 및 액션 결정을 위한 유틸리티 파일이 추가되었습니다.
• features/group/detail/model/useGroupJoinApplyManageAction.ts
  • 그룹 가입 신청 관리를 위한 훅이 추가되었습니다.
• features/group/detail/model/useGroupManageOptionAction.ts
  • 그룹 관리 옵션(수정, 가입 신청 관리, 삭제) 처리를 위한 훅이 추가되었습니다.
• features/group/detail/model/useGroupMembershipAction.ts
  • 그룹 멤버십 액션(가입/탈퇴) 훅의 에러 처리가 showErrorToast를 사용하도록 변경되었습니다.
• features/group/detail/ui/GroupDeleteConfirmModal.tsx
  • 그룹 삭제 확인 모달 컴포넌트가 추가되었습니다.
• features/group/detail/ui/GroupJoinRequestsModal.tsx
  • 그룹 가입 신청 목록 관리 모달 컴포넌트가 추가되었습니다.
• features/group/detail/ui/GroupManageModal.tsx
  • 그룹 관리 옵션을 표시하는 범용 모달 컴포넌트가 추가되었습니다.
• features/group/detail/ui/GroupMembershipActionButton.tsx
  • 그룹 멤버십 액션 버튼 컴포넌트가 그룹 관리 모달 및 삭제 확인 모달과 통합되도록 리팩토링되었습니다.
• features/group/generate/GroupEditForm.tsx
  • 그룹 정보 편집을 위한 폼 컴포넌트가 추가되었습니다.
• features/group/generate/GroupGenerateForm.tsx
  • 그룹 생성 폼이 편집 기능에 재사용될 수 있도록 리팩토링되었고, 썸네일 미리보기 및 제거 로직이 추가되었습니다.
• features/group/generate/ui/GroupGenerateOptionalFields.tsx
  • 그룹 썸네일 이미지 미리보기 및 제거 기능이 추가되었습니다.
• features/group/generate/ui/GroupGenerateSubmitBtn.tsx
  • 그룹 생성 제출 버튼의 에러 처리가 showErrorToast를 사용하도록 변경되었습니다.
• features/group/generate/ui/GroupUpdateSubmitBtn.tsx
  • 그룹 정보 업데이트를 위한 제출 버튼 컴포넌트가 추가되었습니다.
• features/group/members/model/memberManageAction.ts
  • 멤버 관리 액션(추방, 양도) 관련 타입 및 유틸리티 파일이 추가되었습니다.
• features/group/members/model/useGroupMemberManageAction.ts
  • 그룹 멤버 추방 및 그룹장 양도 액션을 처리하는 훅이 추가되었습니다.
• features/group/members/ui/actions/KickMemberButton.tsx
  • 멤버 추방 버튼 컴포넌트가 추가되었습니다.
• features/group/members/ui/actions/MemberManageActionButtons.tsx
  • 멤버 관리 액션 버튼들을 묶는 컴포넌트가 추가되었습니다.
• features/group/members/ui/actions/TransferOwnerButton.tsx
  • 그룹장 양도 버튼 컴포넌트가 추가되었습니다.
• features/group/members/ui/modals/InviteLinkModal.tsx
  • 그룹 초대 링크를 표시하고 복사하는 모달 컴포넌트가 추가되었습니다.
• features/group/members/ui/modals/MemberActionConfirmModal.tsx
  • 멤버 관리 액션(추방, 양도) 확인 모달 컴포넌트가 추가되었습니다.
• features/main/GroupList.tsx
  • usePublicGroupsInfiniteQuery의 import 경로가 업데이트되었습니다.
• shared/constants/paths.ts
  • 로그아웃, 그룹 멤버, 멤버 추방, 그룹장 양도, 가입 신청 승인 등 새로운 API 경로가 추가되었습니다.
• shared/constants/toast.ts
  • 토스트 메시지가 AUTH와 GROUP 도메인으로 구조화되었고, 그룹 관리 관련 다양한 메시지가 추가되었습니다.
• shared/hooks/use-disclosure.ts
  • 모달/드롭다운 등 UI 컴포넌트의 열림/닫힘 상태를 관리하는 커스텀 훅이 추가되었습니다.
• shared/lib/api/client.ts
  • 세션 만료 시 토스트 메시지가 TOAST_MESSAGES.AUTH.SESSION_EXPIRED를 사용하도록 변경되었습니다.
• shared/lib/api/uploadFile.ts
  • 파일 업로드 API 응답 타입이 레거시 호환성을 위해 업데이트되었고, uploadedUrl을 반환하도록 변경되었습니다.
• shared/lib/error-toast.ts
  • 에러 메시지를 추출하고 토스트로 표시하는 showErrorToast 유틸리티 파일이 추가되었습니다.
• tests/e2e/group-create.spec.js
  • 그룹 생성 E2E 테스트에서 파일 업로드 thumbNailUrl이 UPLOADED_URL을 사용하도록 업데이트되었습니다.
• widgets/group/detail/lib/manageModalActions.ts
  • 파일이 삭제되었습니다. 관련 기능은 features/group/detail/lib/groupManageModalActions.ts로 이동되었습니다.
• widgets/group/detail/ui/GroupDetailMobileOverviewSection.tsx
  • 모바일 그룹 상세 개요 섹션에 새로운 그룹 관리 훅과 모달이 통합되었습니다.
• widgets/group/detail/ui/GroupManageModal.tsx
  • 파일이 삭제되었습니다. 관련 기능은 features/group/detail/ui/GroupManageModal.tsx로 이동되었습니다.
• widgets/group/layout/group-sidebar.tsx
  • 그룹 사이드바에 새로운 그룹 관리 훅과 모달이 통합되었습니다.

Activity

• SongMinQQ님이 그룹 관리 기능 구현, API 최신화, React Query 훅 구조 분리 등 상세한 작업 내용을 PR 설명에 명시했습니다.
• PR 설명에 문제 해결 과정과 유의사항을 상세히 기술하여 변경 사항의 배경과 주의점을 명확히 했습니다.
• 그룹장일 때의 UI 스크린샷을 첨부하여 멤버 관리 기능의 시각적 변화를 보여주었습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

이번 PR은 그룹 관리 기능을 대폭 개선하고 관련 코드 구조를 체계적으로 리팩터링하는 중요한 변경사항을 담고 있습니다. API 명세 최신화, 멤버 관리 기능 구현, 쿼리 구조 분리 등 전반적인 코드 품질과 유지보수성을 크게 향상시킨 점이 인상적입니다. 특히, useGroupMemberManageAction과 같은 커스텀 훅을 통해 복잡한 로직을 캡슐화하고, showErrorToast 유틸리티를 도입하여 에러 처리를 일관되게 만든 점이 돋보입니다. 또한, GroupGenerateForm을 재사용 가능하도록 리팩터링하여 그룹 수정 기능을 효율적으로 구현한 것도 좋은 접근 방식입니다. 몇 가지 사소한 수정 제안(파일 인코딩, 문서 오타)을 드렸지만, 전반적으로 매우 완성도 높은 PR이라고 생각합니다.

[gemini-code-assist]

error-toast.tsdml 파일 확장자에 오타가 있는 것 같습니다. .ts가 정확한 확장자로 보입니다.

Suggested change

	- api 예외 처리시 shared/lib/api/error-toast.tsdml showErrorToast 함수를 사용한다. 기본적인 예외 toast 문구는 shared/constants/toast.ts에서 도메인별로 관리한다.
	- api 예외 처리시 shared/lib/api/error-toast.ts showErrorToast 함수를 사용한다. 기본적인 예외 toast 문구는 shared/constants/toast.ts에서 도메인별로 관리한다.

[gemini-code-assist]

파일 시작 부분에 보이지 않는 BOM(Byte Order Mark) 문자가 추가되었습니다. 이 문자는 예기치 않은 문제를 일으킬 수 있으므로 제거하는 것이 좋습니다. 이 PR에 포함된 다른 여러 파일에서도 동일한 문제가 발견되었습니다. 편집기에서 파일을 'UTF-8 without BOM' 형식으로 저장하도록 설정하는 것을 권장합니다.

Suggested change

	"use client";
	"use client";