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

[Cassiiopeia]

📝 현재 문제점

• 📄 [문서][프로젝트] 프로젝트 PRD 설계 MapSy-FE#1
• 다음 PRD를 확인하고 백엔드에서 해당 API 기능들이 다 준비가되었는지 확인을 해야함

🛠️ 해결 방안 / 제안 기능

• 구체적인 명세를 상관하지말고
• 기능적으로 접근해서 해당 기능이 지금 구현이되었는지를 확인해야함

🙋‍♂️ 담당자

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

[Cassiiopeia]

Guide by SUH-LAB

브랜치

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

커밋 메시지

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

[Cassiiopeia]

MapSy-BE PRD 기능 구현 점검 보고서

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

---

📌 작업 개요

MapSy-FE#1 PRD(Product Requirements Document) 문서와 현재 백엔드 구현 상태를 비교 분석하여 기능 구현 완료 여부를 점검.
API URL 명세가 아닌 기능적 관점에서 구현 상태를 확인.

---

📊 점검 결과 요약

카테고리	PRD 요구	구현 완료	구현률
인증 API	4개	4개	100%
회원 관리 API	6개	8개	100%+
콘텐츠/AI API	3개	5개	100%+
장소 관리 API	4개	5개	100%+
북마크 API	3개	0개	0%
키워드 API	2개	0개	0%
피드 API	4개	0개	0%
전체	26개	22개	~85%

핵심 결과

• 구현 완료: 인증, 회원관리, AI 콘텐츠 추출, 장소 기본 관리
• 미구현: 피드 API, 키워드 API (Controller), 북마크 고급 기능

---

✅ 구현 완료 기능

1. 인증 API (/api/auth) - 100% 완료

기능	상태	설명
소셜 로그인	✅	Firebase OAuth (Google/Kakao)
토큰 갱신	✅	JWT Access/Refresh Token
로그아웃	✅	토큰 블랙리스트 처리
회원 탈퇴	✅	Soft Delete 방식

구현 파일: MS-Web/.../controller/AuthController.java

---

2. 회원 관리 API (/api/members) - 100% 완료

기능	상태	설명
약관 동의	✅	온보딩 1단계
생년월일 입력	✅	온보딩 2단계 (만 14세 이상 검증)
성별 선택	✅	온보딩 3단계
프로필 수정	✅	닉네임, 생년월일, 성별 수정
닉네임 중복 검사	✅	실시간 검증
회원 정보 조회	✅	ID, Email 기반 조회

구현 파일: MS-Web/.../controller/MemberController.java

---

3. 콘텐츠/AI 추출 API (/api/content) - 100% 완료

기능	상태	설명
SNS URL 장소 추출 요청	✅	Instagram/YouTube URL → AI 서버 전송
콘텐츠 정보 조회	✅	추출 결과 및 상태 확인
내 콘텐츠 목록	✅	페이지네이션 지원
최근 콘텐츠 조회	✅	추가 구현
저장 장소 조회	✅	추가 구현

AI 콜백 API (/api/ai): ✅ 완료

• Webhook 수신 및 장소/키워드 생성
• FCM 푸시 알림 발송

구현 파일:

• MS-Web/.../controller/ContentController.java
• MS-Web/.../controller/AiController.java
• MS-SNS/.../service/AiCallbackService.java

---

4. 장소 관리 API (/api/place) - 기본 기능 완료

기능	상태	설명
장소 상세 정보	✅	영업시간, 미디어 포함
임시 저장 장소 목록	✅	AI 추출 후 미확정 장소
저장 장소 목록	✅	확정 저장된 장소
장소 저장 (확정)	✅	TEMPORARY → SAVED
임시 장소 삭제	✅	TEMPORARY 상태만 삭제 가능

구현 파일: MS-Web/.../controller/PlaceController.java

---

❌ 미구현 기능

1. 피드 API (/api/feed) - 완전 미구현

기능	상태	PRD 요구사항
최신 장소 피드	❌	무한 스크롤, 페이지네이션
인기 장소 피드	❌	가중치 알고리즘 적용
내 저장 TOP	❌	최대 10개
트렌드 키워드	❌	7일 기준 인기 키워드

참고: FeedController 자체가 존재하지 않음

---

2. 키워드 API (/api/keywords) - Controller 미구현

기능	상태	PRD 요구사항
키워드 상세 정보	❌	게시물 수, 트렌드 점수
키워드별 장소 목록	❌	필터/정렬 지원

참고:

• KeywordService는 구현되어 있음 (getTrendingKeywords, findPlacesByKeyword 등)
• Controller만 추가하면 됨

---

3. 북마크 고급 API (/api/bookmarks) - 미구현

기능	상태	PRD 요구사항
북마크 목록 (페이징)	❌	Page 객체 사용
북마크 수정	❌	메모/별점/폴더 변경

참고:

• MemberPlace 엔티티에 folder, memo, rating, visited 필드는 이미 존재
• API 엔드포인트만 추가 필요

---

🔧 기술적 구현 현황

페이지네이션 전략

PRD 명세: Cursor 기반 + Offset 기반 하이브리드

실제 구현 방향: Page 객체로 통일

• Spring Data JPA의 Page<T> + Pageable 사용
• 파라미터: page, size, sort
• 응답: totalElements, totalPages, hasNext 등

Cursor 미사용 이유:

• MapSy 데이터 특성상 실시간 대량 추가가 아님
• Page 객체가 전체 개수 표시에 유리
• 구현 복잡도 감소

---

가중치 알고리즘

PRD 요구사항:

인기도 점수 = (최근 7일 저장 횟수 × 2) + (7일 이전 저장 횟수 × 1)

현재 상태: ⚠️ 부분 구현

• Keyword 엔티티에 trendScore 필드 존재
• 트렌드 점수 기준 정렬 쿼리 존재
• 미구현: 최근 7일 가중치 계산 배치 작업

---

Firebase 인증

현재 상태: ✅ 완료

• Firebase Admin SDK 연동
• ID Token 검증 → JWT 발급
• Refresh Token Redis 저장
• 온보딩 단계 관리 (TERMS → BIRTH_DATE → GENDER → COMPLETED)

---

AI 서버 연동

현재 상태: ✅ 완료

• POST /api/ai/callback - Webhook 수신
• X-API-Key 헤더 인증
• SUCCESS: 장소/키워드 생성, MemberPlace 연결, FCM 알림
• FAILED: 실패 상태 처리

---

📋 미구현 기능 구현 가이드

P0 (필수 - MVP 기능)

순서	기능	예상 작업량
1	KeywordController 생성	0.5일
2	FeedController 기본 구현	1일
3	북마크 수정 API (PATCH)	0.5일

P1 (중요 - 사용자 경험)

순서	기능	예상 작업량
4	가중치 알고리즘 구현	1일
5	북마크 Page API	0.5일

P2 (개선 - 성능/품질)

순서	기능	예상 작업량
6	Redis 캐싱 (트렌드 키워드)	0.5일
7	배치 스케줄러	0.5일

예상 총 작업량: 약 4-5일

---

📁 주요 파일 위치

Controllers

MS-Web/src/main/java/kr/suhsaechan/mapsy/web/controller/
├── AuthController.java        ✅ 완료
├── MemberController.java      ✅ 완료
├── ContentController.java     ✅ 완료
├── PlaceController.java       ✅ 완료
├── AiController.java          ✅ 완료
├── FeedController.java        ❌ 없음
├── KeywordController.java     ❌ 없음
└── BookmarkController.java    ❌ 없음

Services (구현 완료)

MS-Place/src/main/java/.../service/
├── PlaceService.java          ✅
├── MemberPlaceService.java    ✅
└── KeywordService.java        ✅ (Controller만 필요)

MS-SNS/src/main/java/.../service/
├── ContentService.java        ✅
└── AiCallbackService.java     ✅

---

📌 결론

구현 완료된 핵심 기능

• ✅ Firebase 인증 및 JWT 토큰 관리
• ✅ 회원 온보딩 플로우 (약관 → 생년월일 → 성별)
• ✅ AI 서버 콜백 처리 및 장소 저장
• ✅ 장소 임시저장/확정저장 상태 관리
• ✅ FCM 푸시 알림 기반 구조

추가 구현 필요한 기능

• ❌ 피드 API (FeedController) - 홈 화면 데이터
• ❌ 키워드 API (KeywordController) - 탐색 기능
• ❌ 북마크 고급 기능 - 메모/별점/폴더 수정
• ❌ 가중치 기반 인기도 계산

전체 평가

PRD 대비 백엔드 구현률: 약 85%

핵심 비즈니스 로직(인증, AI 추출, 장소 저장)은 완료되었으나,
프론트엔드 연동에 필요한 피드/키워드/북마크 조회 API가 미구현 상태.

---

🚀 다음 단계

1. 즉시 구현 권장: KeywordController (Service 이미 존재)
2. MVP 필수: FeedController (홈 화면 데이터)
3. UX 개선: 북마크 수정 API

참고 문서:

• PRD 원본: MapSy-FE#1
• 플랜 파일: C:\Users\USER\.claude\plans\foamy-sauteeing-twilight.md

[Cassiiopeia]

문서 작업 완료