🚀 [기능개선][PRD][점검] 맵시 PRD에 맞는 기능 구현 확인 점검 필요

[Cassiiopeia]

📝 현재 문제점

• 📄 [문서][프로젝트] 프로젝트 PRD 설계 #1
• 다음 PRD를 확인하고 프론트에서 필요한 기능의 순서를 지정하여 하나씩 완료해야함

🛠️ 해결 방안 / 제안 기능

• 현재 구현상태를 확인하고 백엔드로직을 확인하여 엮어야함

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260128_#14_맵시_PRD에_맞는_기능_구현_확인_점검_필요

커밋 메시지

맵시 PRD에 맞는 기능 구현 확인 점검 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/14

[Cassiiopeia]

MapSy PRD 기능 구현 현황 분석 보고서

이슈: #14 맵시 PRD에 맞는 기능 구현 확인 점검 필요

---

📌 작업 개요

MapSy PRD 문서를 기반으로 백엔드/프론트엔드 구현 현황을 점검하고, 프론트엔드 기능 구현 우선순위를 수립한 분석 보고서

---

1. PRD 핵심 요약

프로젝트 비전

"SNS 속 숨은 맛집과 핫플레이스를 AI가 찾아주는 스마트 장소 큐레이션 플랫폼"

핵심 기능 6가지

기능	설명
AI 장소 추출	Instagram/YouTube URL → 자동 장소 추출 (정확도 목표: 80%+)
홈 피드	최신/인기 장소 + 트렌드 키워드
키워드/태그 피드	필터링, 정렬 (최신순/인기순/거리순)
장소 상세 정보	영업시간, 지도, 길찾기, 출처 링크
개인 북마크 관리	폴더/메모/별점/방문기록, Soft Delete(30일 복구)
소셜 기능	컬렉션 공유, 팔로우 (Phase 2)

---

2. 백엔드 구현 현황 ✅

모듈별 구현 상태

모듈	상태	주요 API
MS-Auth	✅ 완성	sign-in, reissue, logout, withdraw
MS-Member	✅ 완성	프로필, 온보딩(약관/생일/성별), 닉네임 중복확인
MS-Place	✅ 완성	장소 상세, 임시/저장 장소, 폴더 관리
MS-SNS	✅ 완성	AI 분석 요청, 콘텐츠 조회
MS-AI	✅ 완성	비동기 분석, Webhook 콜백
MS-Common	✅ 완성	공통 에러처리, 로깅, 유틸리티
MS-Web	✅ 완성	REST API 게이트웨이

API 엔드포인트 (총 25개)

인증 API

POST   /api/auth/sign-in          소셜 로그인
POST   /api/auth/reissue          토큰 재발급
POST   /api/auth/logout           로그아웃
DELETE /api/auth/withdraw         회원 탈퇴

회원 API

POST   /api/members                         회원 생성
POST   /api/members/onboarding/terms       약관 동의
POST   /api/members/onboarding/birth-date  생일 정보
POST   /api/members/onboarding/gender      성별 정보
POST   /api/members/profile                프로필 업데이트
GET    /api/members/check-name             닉네임 중복 확인

장소 API

GET    /api/place/{placeId}              장소 상세 정보
GET    /api/place/temporary              임시 저장 장소 목록
GET    /api/place/saved                  저장된 장소 목록
POST   /api/place/{placeId}/save         장소 저장
DELETE /api/place/{placeId}/temporary    임시 장소 삭제

콘텐츠 API (AI 추출)

POST   /api/content/analyze              SNS URL 분석 요청
GET    /api/content/{contentId}          콘텐츠 정보 조회
GET    /api/content/member               회원 콘텐츠 목록
GET    /api/content/recent               최근 콘텐츠
GET    /api/content/place/saved          저장된 장소 목록

---

3. 프론트엔드 구현 현황 ⚠️

기술 스택 (설정 완료)

• Flutter SDK: ^3.9.2
• 상태 관리: Riverpod 2.6.1
• 라우팅: go_router 17.0.1
• 네트워킹: dio 5.9.0 + retrofit 4.7.2
• 인증: Firebase Auth + Google/Apple Sign-In

구현 현황

구분	상태	설명
프로젝트 구조	✅ 완성	Clean Architecture 기반
Firebase 인증	✅ 완성	Google/Apple 로그인 동작
FCM 푸시 알림	✅ 기본 완성	토큰 발급, 메시지 처리
디자인 시스템	✅ 완성	색상, 텍스트, 간격 정의
라우팅	✅ 기본 완성	GoRouter 설정
백엔드 API 연동	❌ 미구현	Dio 클라이언트 미설정
온보딩 플로우	❌ 미구현	스켈레톤만 존재
홈 피드 화면	❌ 미구현	빈 페이지
AI 장소 추출	❌ 미구현	-
장소 상세 화면	❌ 미구현	-
북마크 관리	❌ 미구현	-

---

4. 구현 우선순위 (권장)

Phase 1: 인프라 & 인증 완성

목표: 백엔드 연동 기반 구축

Step	작업	설명
1.1	API 클라이언트 구축	Dio 설정, 토큰 인터셉터, 에러 처리
1.2	인증 API 연동	Firebase → 백엔드 토큰 교환
1.3	온보딩 플로우	약관→생일→성별→닉네임 4단계
1.4	라우팅 업데이트	온보딩 경로 추가, 리다이렉트 로직

Phase 2: 홈 피드 구현

목표: 메인 화면 완성

작업	API 연동
최신 장소 목록	GET /api/feed/latest/cursor
인기 장소 목록	GET /api/feed/popular
트렌드 키워드	GET /api/feed/trending-keywords

Phase 3: AI 장소 추출 (핵심 기능)

목표: 핵심 차별화 기능 구현

작업	설명
URL 입력 바텀시트	FAB → BottomSheet → URL 입력
추출 진행 화면	폴링 기반 상태 확인 (2초 간격)
추출 결과 화면	장소 선택 → 폴더 선택 → 저장

Phase 4: 장소 상세 & 북마크

목표: 저장된 장소 관리

작업	API 연동
장소 상세 페이지	GET /api/place/{placeId}
북마크 관리	GET /api/bookmarks/cursor
폴더 관리	GET /api/bookmarks/folders

---

5. 기술적 결정 사항

항목	결정	비고
구현 순서	Phase 1 → 2 → 3 → 4	의존성 기반 순서
지도 SDK	네이버 지도	한국 장소 데이터 최적화
개발 서버	https://api.mapsy.suhsaechan.kr	별도 개발 서버 사용

---

6. Phase 1 완료 기준

• 개발 서버 연결 성공
• Google/Apple 로그인 → 백엔드 토큰 발급
• 토큰 저장 (flutter_secure_storage)
• 401 에러 시 자동 토큰 갱신
• 온보딩 4단계 완료 가능
• 온보딩 완료 후 홈 화면 진입
• 기존 사용자는 온보딩 스킵

---

7. 예상 파일 구조

lib/
├── core/
│   ├── network/                 # ❌ 추가 필요
│   │   ├── api_client.dart
│   │   ├── api_interceptor.dart
│   │   └── token_storage.dart
│
├── features/
│   ├── auth/                    # 🟡 수정 필요
│   │   ├── data/datasources/
│   │   │   └── auth_remote_datasource.dart  # ❌ 추가
│   │   └── domain/usecases/
│   │       └── sign_in_usecase.dart         # ❌ 추가
│   │
│   ├── onboarding/              # ❌ 새로 생성
│   │   └── presentation/pages/
│   │       ├── terms_step.dart
│   │       ├── birth_date_step.dart
│   │       ├── gender_step.dart
│   │       └── nickname_step.dart
│   │
│   ├── home/                    # ❌ 대폭 수정 필요
│   ├── place/                   # ❌ 새로 생성
│   ├── bookmark/                # ❌ 새로 생성
│   └── extraction/              # ❌ 새로 생성 (AI 추출)

---

8. 다음 단계

1. Phase 1 구현 시작: /implement 명령으로 API 클라이언트 + 인증 연동
2. 상세 분석 필요시: /analyze 명령으로 Phase 1 세부 설계
3. 백엔드 API 테스트: 개발 서버 연결 확인 필요

---

📌 참고사항

• 백엔드는 25개 API 엔드포인트가 모두 구현 완료 상태
• 프론트엔드는 Firebase 인증만 완성, 백엔드 연동은 0%
• Phase 1 완료 후 실제 사용자 플로우 테스트 가능

---

보고서 파일: .report/20260128_#14_맵시_PRD_기능_구현_현황_분석.md

[Cassiiopeia]

5.1 Phase 1 완료 조건
 로그인 후 백엔드 토큰 발급 성공
 온보딩 4단계 완료 가능
 토큰 자동 갱신 동작
5.2 Phase 2 완료 조건
 홈 화면에서 최신/인기 장소 표시
 트렌드 키워드 클릭 → 필터링
 무한 스크롤 (Cursor 페이지네이션)
5.3 Phase 3 완료 조건
 URL 입력 → AI 분석 요청 성공
 폴링으로 결과 수신
 장소 선택 후 저장 완료
5.4 Phase 4 완료 조건
 장소 상세 정보 표시
 지도 미리보기 동작
 북마크 폴더별 조회/편집

[Cassiiopeia]

MapSy 프론트엔드 Phase 1 구현 계획

📊 분석 요약

프로젝트 타입: Flutter Mobile App 기술 스택: Flutter 3.9.2 + Riverpod 2.6.1 + GoRouter 17.0.1 + Dio 5.9.0 코드 스타일: Clean Architecture, @riverpod 어노테이션, Freezed 데이터 클래스

---

🎯 Phase 1 구현 목표

Firebase 로그인 → 백엔드 토큰 교환 → 온보딩 플로우 완성

---

📝 Step별 상세 구현 계획

Step 1.1: API 클라이언트 구축 (가장 먼저!)

이유: 모든 백엔드 연동의 기반. 이것 없이는 Step 1.2~1.4 진행 불가

생성할 파일

lib/core/network/
├── api_client.dart           # Dio 싱글톤 + Provider
├── auth_interceptor.dart     # Access Token 자동 주입
├── token_refresh_interceptor.dart  # 401 → 토큰 갱신 → 재시도
├── error_interceptor.dart    # 서버 에러 → AppException 변환
└── token_storage.dart        # flutter_secure_storage 래퍼

api_client.dart 구조

@riverpod
Dio dio(Ref ref) {
  final dio = Dio(BaseOptions(
    baseUrl: ApiEndpoints.baseUrl,  // https://api.mapsy.suhsaechan.kr
    connectTimeout: Duration(seconds: 30),
    receiveTimeout: Duration(seconds: 30),
    headers: {'Content-Type': 'application/json'},
  ));
dio.interceptors.addAll([

AuthInterceptor(ref),

TokenRefreshInterceptor(ref),

ErrorInterceptor(),

]);
return dio;

}

token_storage.dart 구조

class TokenStorage {

static const _accessTokenKey = 'access_token';

static const _refreshTokenKey = 'refresh_token';

Future<void> saveTokens(String accessToken, String refreshToken);

Future<String?> getAccessToken();

Future<String?> getRefreshToken();

Future<void> clearTokens();

}

수정할 파일

• lib/core/constants/api_endpoints.dart - 엔드포인트 상수 추가

class ApiEndpoints {

static String get baseUrl => 'https://api.mapsy.suhsaechan.kr';

// Auth

static const String signIn = '/api/auth/sign-in';

static const String reissue = '/api/auth/reissue';

static const String logout = '/api/auth/logout';
// Member

static const String onboardingTerms = '/api/members/onboarding/terms';

static const String onboardingBirthDate = '/api/members/onboarding/birth-date';

static const String onboardingGender = '/api/members/onboarding/gender';

static const String memberProfile = '/api/members/profile';

static const String checkName = '/api/members/check-name';

}

---

Step 1.2: 인증 API 연동

이유: Firebase 로그인만으로는 백엔드 API 호출 불가. 백엔드 JWT 토큰 필요

생성할 파일

lib/features/auth/

├── data/

│   ├── datasources/

│   │   └── auth_remote_datasource.dart   # 백엔드 API 호출

│   ├── models/

│   │   ├── sign_in_request.dart          # Freezed

│   │   ├── sign_in_response.dart         # Freezed

│   │   └── member_dto.dart               # Freezed

│   └── repositories/

│       └── auth_repository_impl.dart

├── domain/

│   ├── entities/

│   │   └── member.dart                   # Freezed

│   ├── repositories/

│   │   └── auth_repository.dart          # abstract class

│   └── usecases/

│       └── sign_in_usecase.dart

백엔드 API 스펙 (분석 완료)

POST /api/auth/sign-in

// Request

@freezed

class SignInRequest with _$SignInRequest {

const factory SignInRequest({

required String firebaseIdToken,

String? fcmToken,

String? deviceType,  // IOS, ANDROID

String? deviceId,

}) = _SignInRequest;

}

// Response

@freezed

class SignInResponse with _$SignInResponse {

const factory SignInResponse({

required String accessToken,

required String refreshToken,

required bool isFirstLogin,

required bool requiresOnboarding,

String? onboardingStep,  // TERMS, BIRTH_DATE, GENDER, NICKNAME

}) = _SignInResponse;

}

수정할 파일

• lib/features/auth/presentation/providers/auth_provider.dart

// 기존: Firebase 로그인만 수행

// 변경: Firebase 로그인 → 백엔드 로그인 → 토큰 저장 → 온보딩 체크

Future<void> signInWithGoogle() async {

state = const AsyncValue.loading();
try {

// 1. Firebase 로그인 (기존)

final userCredential = await dataSource.signInWithGoogle();
// 2. Firebase ID Token 획득
final idToken = await dataSource.getIdToken();

// 3. FCM 토큰 + 디바이스 정보 수집
final fcmToken = await fcmService.getFcmToken();
final deviceInfo = await deviceInfoService.getDeviceInfo();

// 4. 백엔드 로그인 API 호출 (NEW!)
final signInResponse = await authRepository.signIn(
  SignInRequest(
    firebaseIdToken: idToken,
    fcmToken: fcmToken,
    deviceType: deviceInfo.deviceType,
    deviceId: deviceInfo.deviceId,
  ),
);

// 5. 토큰 저장 (NEW!)
await tokenStorage.saveTokens(
  signInResponse.accessToken,
  signInResponse.refreshToken,
);

// 6. 온보딩 필요 여부 저장 (NEW!)
await _saveOnboardingState(signInResponse);

state = AsyncValue.data(userCredential.user);

} catch (e, stack) {

// 에러 처리...

}

}

---

Step 1.3: 온보딩 플로우 구현

이유: 신규 사용자는 약관동의 → 생년월일 → 성별 → 닉네임 순서로 입력 필요

생성할 파일

lib/features/onboarding/

├── data/

│   ├── datasources/

│   │   └── onboarding_remote_datasource.dart

│   └── repositories/

│       └── onboarding_repository_impl.dart

├── domain/

│   ├── repositories/

│   │   └── onboarding_repository.dart

│   └── usecases/

│       ├── agree_terms_usecase.dart

│       ├── update_birth_date_usecase.dart

│       ├── update_gender_usecase.dart

│       └── update_nickname_usecase.dart

└── presentation/

├── pages/

│   ├── onboarding_flow_page.dart     # PageView 컨테이너

│   ├── terms_step.dart               # 약관 동의 화면

│   ├── birth_date_step.dart          # 생년월일 선택

│   ├── gender_step.dart              # 성별 선택

│   └── nickname_step.dart            # 닉네임 입력

├── providers/

│   └── onboarding_provider.dart

└── widgets/

├── step_indicator.dart           # 진행 표시

└── onboarding_button.dart        # 공통 버튼

온보딩 API 스펙

// POST /api/members/onboarding/terms

{ "serviceAgreement": true, "privacyAgreement": true }

// POST /api/members/onboarding/birth-date

{ "birthDate": "1995-03-15" }
// POST /api/members/onboarding/gender

{ "gender": "MALE" }  // MALE, FEMALE, OTHER
// POST /api/members/profile

{ "name": "홍길동" }
// GET /api/members/check-name?name=홍길동

// Response: { "available": true }

온보딩 플로우 상태 관리

@freezed

class OnboardingState with _$OnboardingState {

const factory OnboardingState({

@Default(OnboardingStep.terms) OnboardingStep currentStep,

@Default(false) bool termsAgreed,

DateTime? birthDate,

String? gender,

String? nickname,

@Default(false) bool isLoading,

String? errorMessage,

}) = _OnboardingState;

}

enum OnboardingStep { terms, birthDate, gender, nickname, completed }

---

Step 1.4: 라우팅 업데이트

이유: 온보딩 경로 추가 + 온보딩 완료 여부에 따른 리다이렉트

수정할 파일

lib/router/route_paths.dart

// 추가할 경로

static const String onboardingTerms = '/onboarding/terms';

static const String onboardingBirthDate = '/onboarding/birth-date';

static const String onboardingGender = '/onboarding/gender';

static const String onboardingNickname = '/onboarding/nickname';

lib/router/app_router.dart

redirect: (context, state) {

final authUser = ref.read(authStateProvider).value;

final isAuthenticated = authUser != null;

// 기존 로직...
// 온보딩 체크 (NEW!)

if (isAuthenticated) {

final onboardingState = ref.read(onboardingStateProvider);

if (onboardingState.requiresOnboarding) {

// 현재 온보딩 단계로 리다이렉트

return _getOnboardingPath(onboardingState.currentStep);

}

}
return null;

}

---

✅ Phase 1 완료 기준

•  flutter pub get 성공
•  dart run build_runner build 성공 (Freezed, Riverpod 코드 생성)
•  개발 서버 연결 테스트 (https://api.mapsy.suhsaechan.kr)
•  Google 로그인 → 백엔드 토큰 발급 성공
•  Apple 로그인 → 백엔드 토큰 발급 성공
•  토큰 저장 확인 (flutter_secure_storage)
•  401 에러 시 자동 토큰 갱신 동작
•  온보딩 4단계 순차 진행 가능
•  온보딩 완료 후 홈 화면 진입
•  앱 재시작 시 토큰 자동 복원 + 홈 직행

---

⚠️ 주의사항

1. 의존성 순서: Step 1.1(API 클라이언트) 없이 Step 1.2~1.4 불가
2. 코드 생성 필수: Freezed, Riverpod 모델 추가 시 build_runner 실행 필요
3. 기존 코드 보존: FirebaseAuthDataSource는 수정하지 않고 AuthRepository에서 조합
4. 에러 처리: 네트워크 에러, 서버 에러, 검증 에러 각각 다르게 처리

---

🔧 구현 순서 요약

1️⃣ Step 1.1: API 클라이언트 (network/ 폴더)

└─► Dio 설정 + 인터셉터 + 토큰 저장소

2️⃣ Step 1.2: 인증 API 연동

└─► SignIn Request/Response 모델 + Repository + Provider 수정
3️⃣ Step 1.3: 온보딩 플로우

└─► 4단계 화면 + API 연동 + 상태 관리
4️⃣ Step 1.4: 라우팅 업데이트

└─► 온보딩 경로 + 리다이렉트 로직

---

1. 현재 상황 분석

1.1 PRD 핵심 요약

프로젝트 비전: "SNS 속 숨은 맛집과 핫플레이스를 AI가 찾아주는 스마트 장소 큐레이션 플랫폼"

핵심 기능 6가지:

1. AI 장소 추출 (Instagram/YouTube URL → 자동 장소 추출)
2. 홈 피드 (최신/인기 장소 + 트렌드 키워드)
3. 키워드/태그 피드 (필터링, 정렬)
4. 장소 상세 정보 (영업시간, 지도, 길찾기)
5. 개인 북마크 관리 (폴더/메모/별점/방문기록)
6. 소셜 기능 (Phase 2)

1.2 백엔드 구현 현황 (✅ 완성도 높음)

모듈	상태	주요 API
MS-Auth	✅ 완성	sign-in, reissue, logout, withdraw
MS-Member	✅ 완성	프로필, 온보딩(약관/생일/성별), 닉네임
MS-Place	✅ 완성	장소 상세, 임시/저장 장소, 폴더 관리
MS-SNS	✅ 완성	AI 분석 요청, 콘텐츠 조회
MS-AI	✅ 완성	비동기 분석, Webhook 콜백

API 클라이언트 설정 예시

// lib/core/constants/api_endpoints.dart
class ApiEndpoints {
  static const String baseUrl = 'https://api.mapsy.suhsaechan.kr';
// Auth

static const String signIn = '/api/auth/sign-in';

static const String reissue = '/api/auth/reissue';

static const String logout = '/api/auth/logout';
// Member

static const String members = '/api/members';

static const String onboardingTerms = '/api/members/onboarding/terms';

static const String onboardingBirthDate = '/api/members/onboarding/birth-date';

static const String onboardingGender = '/api/members/onboarding/gender';

static const String memberProfile = '/api/members/profile';

static const String checkName = '/api/members/check-name';
// Place

static const String place = '/api/place';

static const String temporaryPlaces = '/api/place/temporary';

static const String savedPlaces = '/api/place/saved';
// Content (AI 추출)

static const String contentAnalyze = '/api/content/analyze';

static const String content = '/api/content';

}