pick-lunch/template/docs/02_IMPLEMENTATION_PLAN.md

직장인 점심 추천 미니앱 구현 계획

1. 기술 스택 제안

• MiniApp Frontend: Apps in Toss + Granite RN
• Backend API: Node.js (NestJS/Express) or Java Spring Boot
• DB: PostgreSQL
• Cache: Redis (선택)
• 지도/장소 데이터: Kakao/Google/Naver Place API 중 1개 선택

2. 프론트엔드 디렉터리 구조 제안

template/src/
  _app.tsx
  pages/
    index.tsx                # 홈/목록
    restaurants/[id].tsx     # 식당 상세
    reviews/edit.tsx         # 리뷰 작성/수정
    me/reviews.tsx           # 내 리뷰
    _404.tsx
  features/
    location/
      useCurrentLocation.ts
    restaurants/
      api.ts
      models.ts
      hooks.ts
    reviews/
      api.ts
      hooks.ts
    likes/
      api.ts
  components/
    RestaurantCard.tsx
    CategoryFilter.tsx
    SortSelector.tsx
    RatingStars.tsx
    EmptyState.tsx
  lib/
    httpClient.ts
    queryClient.ts
    error.ts
  constants/
    category.ts
    sort.ts

3. 백엔드 모듈 구조 제안

• auth
  • 토스 사용자 식별자 검증/매핑
• restaurants
  • 주변 조회, 상세 조회
• reviews
  • 리뷰 upsert/delete/list
• likes
  • 좋아요 토글
• users
  • 내 리뷰 조회
• integrations
  • 장소 API 클라이언트, 카테고리 매핑

4. 핵심 유스케이스별 처리

4.1 주변 식당 조회

1. FE가 현재 좌표(lat,lng) 획득
2. GET /v1/restaurants/nearby 호출
3. BE는 내부 캐시 우선 조회
4. 캐시 미스 시 장소 API 호출 + 표준 카테고리 매핑 + DB upsert
5. 통계(join restaurant_stat) 결합 후 반환

4.2 리뷰 작성/수정

1. FE가 rating/content 전송
2. BE가 (restaurant_id, user_id) unique 기준 upsert
3. refresh_restaurant_stat(restaurant_id) 호출
4. 최신 리뷰/평점 반환

4.3 좋아요 토글

1. row 존재 여부 확인
2. 있으면 delete, 없으면 insert
3. refresh_restaurant_stat 호출
4. liked 상태와 like_count 반환

5. API 에러 규약

• 공통 포맷

{
  "code": "INVALID_INPUT",
  "message": "rating must be between 1 and 5",
  "traceId": "..."
}

• 주요 코드
  • UNAUTHORIZED
  • FORBIDDEN
  • NOT_FOUND
  • INVALID_INPUT
  • RATE_LIMITED
  • INTERNAL_ERROR

6. 보안/악용 방지

• 리뷰/좋아요 API 인증 필수
• 리뷰 작성 rate limit (예: 사용자당 분당 5회)
• 욕설 필터(간단 키워드 + 신고 플래그)
• SQL injection/XSS 대비(파라미터 바인딩, escaping)

7. QA 체크리스트

• 위치 권한 허용/거부 둘 다 정상 동작
• 권한 거부 시 수동 지역 선택 제공
• 0개 결과(empty state) UI
• 느린 네트워크에서 skeleton/loading 표시
• 리뷰 저장 후 목록/평점 즉시 반영
• 좋아요 토글 연타 시 데이터 일관성 확인
• 앱 백그라운드 전환 후 복귀 시 상태 복원

8. 출시 전 운영 준비

• 개인정보처리방침/이용약관 페이지
• 고객 문의 채널(이메일/채팅 URL)
• 모니터링 대시보드
  • API 성공률
  • p95 latency
  • 에러율
• 장애 대응 runbook

9. 개발 일정(예시, 2주)

Day 1-2

• 프로젝트 구조 확장
• 공통 HTTP 클라이언트/에러 처리

Day 3-5

• 식당 목록/상세 API + 화면
• 위치 권한/좌표 처리

Day 6-8

• 리뷰 CRUD + 좋아요 토글
• 통계 반영

Day 9-10

• 내 활동 화면
• QA/버그 수정

Day 11-12

• 성능/로그 점검
• 검수 대응 문서 정리

10. 바로 시작할 개발 순서

1. granite.config.ts의 appName/brand 값 실서비스 값으로 변경
2. 홈 목록 화면에 위치 권한 + nearby API 연결
3. 식당 상세와 리뷰 작성 페이지 연결
4. 리뷰/좋아요 API 붙이고 optimistic update 적용
5. 검수 체크리스트 기준 점검 후 배포