⚙️[기능추가][폴더] 폴더 CRUD 및 저장 장소 관리 UI 구현

[Cassiiopeia]

📝 현재 문제점

• 백엔드 이슈 MapSee-Lab/MapSy-BE#26에서 폴더 CRUD 및 폴더-장소 관리 API 7종이 구현 완료되었으나, 프론트엔드에 해당 기능이 전혀 없는 상태
• 현재 AI 추출 후 장소 저장 시 폴더 선택 없이 단순 저장만 가능
• 저장된 장소 목록을 조회하거나 폴더별로 분류하는 화면이 없음
• 마이페이지에 폴더 관련 정보가 전혀 표시되지 않음

🛠️ 해결 방안 / 제안 기능

• 마이페이지에 폴더 미리보기 섹션 추가 (가로 스크롤 칩)
• 마이페이지 하위에 저장 장소 관리 페이지(SavedPlacesPage) 신규 구현
• 폴더 탭 바 (칩 형태), 장소 카드 목록, 생성/수정/삭제 바텀시트 구현
• 백엔드 폴더 API 7종 연동 (GET/POST/PUT/DELETE)

⚙️ 작업 내용

데이터 레이어:

• API Endpoints 추가 (폴더 관련 4개 경로)
• Freezed DTO 4개 파일 생성 (FolderModel, CreateFolderRequest, UpdateFolderRequest, FolderPlaceModel 등)
• SavedPlacesRemoteDataSource 생성 (Dio 기반 API 호출 7종)
• SavedPlacesRepository 인터페이스 + 구현체 생성

프레젠테이션 레이어:

• SavedPlacesNotifier (Riverpod) 상태 관리 생성
• SavedPlacesPage 메인 화면 구현
• FolderTabBar 위젯 (가로 스크롤 칩 탭)
• FolderPlaceCard 위젯 (장소 카드)
• CreateFolderBottomSheet (폴더 생성)
• EditFolderBottomSheet (폴더 수정/삭제)
• EmptyFolderState (빈 폴더 상태)
• FolderPreviewSection (마이페이지 미리보기)

라우팅:

• /mypage/saved-places 경로 추가
• GoRouter 라우트 등록

기존 파일 수정:

• api_endpoints.dart: 폴더 API 엔드포인트 추가
• route_paths.dart / app_router.dart: 라우트 추가
• mypage_page.dart: 폴더 미리보기 섹션 삽입

빌드:

• build_runner 실행 필요 (Freezed/Riverpod 코드 생성)

🙋‍♂️ 담당자

• 백엔드: 이름 (API 구현 완료 - MapSy-BE#26)
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260223_#25_폴더_CRUD_및_저장_장소_관리_UI_구현

커밋 메시지

폴더 CRUD 및 저장 장소 관리 UI 구현 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/25

[Cassiiopeia]

📌 작업 개요

백엔드(MapSy-BE#26)에서 구현 완료된 폴더 CRUD 및 폴더-장소 관리 API 7종을 프론트엔드에 연동.
마이페이지에 폴더 미리보기 섹션 추가, 저장 장소 관리 전용 페이지(SavedPlacesPage) 신규 구현.
Clean Architecture 패턴(DataSource → Repository → Provider → Page)으로 전체 레이어 구축.

🎯 구현 목표

• 폴더 목록 조회 / 생성 / 수정 / 삭제 UI
• 폴더 내 장소 목록 조회 / 추가 / 제거 UI
• 마이페이지에 폴더 미리보기 (가로 스크롤 칩)
• 기본 폴더 보호 (삭제/편집 불가 처리)

✅ 구현 내용

1. Freezed DTO 모델 4개 파일

• 파일: data/models/folder_model.dart, create_folder_request.dart, update_folder_request.dart, folder_place_model.dart
• 변경 내용: 백엔드 API 응답 구조에 맞춘 Freezed DTO 생성. FolderModel(폴더 목록), FolderPlaceModel(폴더 내 장소), 각 CRUD용 Request/Response DTO 정의
• 이유: json_serializable 기반 자동 직렬화/역직렬화, @Default 활용한 null-safe 처리

2. Remote DataSource (API 호출 레이어)

• 파일: data/saved_places_remote_datasource.dart
• 변경 내용: Dio 기반 API 호출 메서드 7개 구현. @riverpod Provider로 DI 처리
• 이유: 기존 AiExtractionRemoteDataSource 패턴과 동일한 구조 유지

메서드	API	용도
getFolders()	GET /api/folders	폴더 목록 조회
createFolder()	POST /api/folders	폴더 생성
updateFolder()	PUT /api/folders/{id}	폴더 수정
deleteFolder()	DELETE /api/folders/{id}	폴더 삭제
getFolderPlaces()	GET /api/folders/{id}/places	폴더 내 장소 조회
addPlaceToFolder()	POST /api/folders/{id}/places	폴더에 장소 추가
removePlaceFromFolder()	DELETE /api/folders/{id}/places/{placeId}	폴더에서 장소 제거

3. Repository 인터페이스 + 구현체

• 파일: data/saved_places_repository.dart, data/saved_places_repository_impl.dart
• 변경 내용: abstract 인터페이스 정의 + @riverpod Provider 구현체. DataSource 위임 패턴
• 이유: 테스트 가능성 확보, 레이어 분리 유지

4. Riverpod Notifier (상태 관리)

• 파일: presentation/saved_places_provider.dart
• 변경 내용: SavedPlacesState (Freezed) + SavedPlacesNotifier (@riverpod) 구현
• 주요 로직:
  • loadFolders(): 폴더 목록 로드 → 기본 폴더 자동 선택
  • selectFolder(): 폴더 선택 → 해당 폴더 장소 목록 로드
  • createFolder() / updateFolder() / deleteFolder(): CRUD 후 목록 자동 갱신
  • addPlaceToFolder() / removePlaceFromFolder(): 장소 관리 후 목록 + 폴더 카운트 갱신

특이사항:

• 마이페이지 미리보기와 상세 페이지가 동일한 Provider를 공유하여 상태 일관성 유지
• 폴더 삭제/장소 제거 후 loadFolders() 재호출로 placeCount 동기화

5. SavedPlacesPage (저장 장소 관리 페이지)

• 파일: presentation/pages/saved_places_page.dart
• 변경 내용: 폴더 탭 바 + 장소 목록 + CRUD 액션이 포함된 전체 페이지 구현
• 주요 기능:
  • AppBar: 폴더 추가 버튼 + 현재 폴더 편집 버튼 (기본 폴더일 때 숨김)
  • 폴더 탭 바 (가로 스크롤 칩)
  • 장소 목록 (ListView.builder)
  • 에러 상태 / 빈 상태 / 로딩 상태 각각 처리

6. 위젯 6개

• folder_tab_bar.dart: 가로 스크롤 칩 형태 폴더 탭. 선택 시 반전 스타일, placeCount 표시
• folder_place_card.dart: 장소 카드 (썸네일 + 이름 + 주소 + 별점). X 버튼으로 장소 제거
• create_folder_bottom_sheet.dart: 폴더 생성 바텀시트 (이름 입력 + 공개 설정 라디오)
• edit_folder_bottom_sheet.dart: 폴더 수정/삭제 바텀시트. 기본 폴더는 삭제 버튼 숨김. 삭제 시 확인 다이얼로그
• empty_folder_state.dart: 빈 폴더 안내 (아이콘 + 메시지)
• folder_preview_section.dart: 마이페이지용 폴더 미리보기. 가로 스크롤 칩 + "전체보기" 버튼. 기본 폴더에 특별 아이콘 표시

7. 마이페이지 연동

• 파일: mypage/presentation/pages/mypage_page.dart
• 변경 내용: 프로필 카드 아래에 FolderPreviewSection 위젯 삽입
• 이유: 마이페이지에서 폴더 목록 바로 확인 가능, "전체보기" 탭으로 SavedPlacesPage 진입

🔧 주요 설계 결정

결정	선택	이유
폴더 UI 위치	마이페이지 하위 + 미리보기	기존 네비게이션 4탭 구조 유지, Instagram 패턴 참조
상태 관리	단일 SavedPlacesNotifier	미리보기/상세 페이지 간 상태 공유로 일관성 확보
기본 폴더 보호	isDefault 필드 기반 UI 분기	백엔드 정책(삭제 불가)과 프론트 UI 동기화
DTO 구조	Response를 Request 파일에 함께 정의	파일 수 최소화, 관련 DTO 응집도 향상

📦 의존성 변경

• 없음 (기존 Dio, Riverpod, Freezed, flutter_screenutil, GoRouter만 사용)

🧪 테스트 및 검증

• build_runner 실행 필요 (Freezed .freezed.dart, .g.dart 코드 생성)
• 폴더 목록 조회 API 연동 확인
• 폴더 생성/수정/삭제 후 목록 자동 갱신 확인
• 기본 폴더 삭제 시도 시 버튼 미노출 확인
• 마이페이지 → 전체보기 → SavedPlacesPage 라우팅 동작 확인

📌 참고사항

• api_endpoints.dart, route_paths.dart, app_router.dart 수정도 함께 진행됨 (폴더 엔드포인트 추가, /mypage/saved-places 라우트 등록)
• 코드 리뷰 시 발견된 Major 이슈 3건 수정 완료: _selectedFolder 반환 타입 누락, 중복 호출, DTO 미사용
• 향후 AI 추출 저장 플로우에 폴더 선택 바텀시트 연동 예정