🚀[기능개선][홈][API] 홈 물품 목록 정렬 기준을 추천 알고리즘(RECOMMENDED)으로 변경

[Cassiiopeia]

📝 현재 문제점

• 홈 화면에서 물품 목록을 불러올 때 항상 **최신순(LATEST)**으로 요청하고 있음
• 사용자 맞춤 추천 물품이 아닌 단순 최신 등록 물품만 노출되어, 홈 화면의 탐색 효율이 떨어짐

🛠️ 해결 방안 / 제안 기능

• 홈 화면의 물품 목록 API 요청 시 정렬 필드를 RECOMMENDED(추천 알고리즘)로 변경
• 백엔드 API의 요청 파라미터(sort/field 등)를 최신순에서 추천순으로 수정

⚙️ 작업 내용

• 홈 화면에서 물품 목록을 가져오는 API 호출부의 정렬 파라미터를 RECOMMENDED로 변경
• 관련 Repository/Service 레이어의 요청 파라미터 확인 및 수정

🙋‍♂️ 담당자

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

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260224_#575_홈_물품_목록_정렬_기준을_추천_알고리즘_RECOMMENDED_으로_변경

커밋 메시지

홈 물품 목록 정렬 기준을 추천 알고리즘(RECOMMENDED)으로 변경 : feat : {변경 사항에 대한 설명} https://github.com/TEAM-ROMROM/RomRom-FE/issues/575

[Chuseok22]

TEAM-ROMROM/RomRom-BE#538

해당 이슈랑 연결됩니다

[Cassiiopeia]

참고사항 백엔드 itemSortField

package com.romrom.common.constant;

import lombok.AllArgsConstructor;

@AllArgsConstructor
public enum ItemSortField implements SortField {

  CREATED_DATE("createdDate"),

  DISTANCE("distance"),

  PREFERRED_CATEGORY("preferredCategory"),

  RECOMMENDED("recommended");

  private final String property;

  @Override
  public String getProperty() {
    return property;
  }
}

[Cassiiopeia]

📌 작업 개요

홈 화면에서 물품 목록을 불러올 때 정렬 기준을 기존 최신순(CREATED_DATE)에서 추천 알고리즘(RECOMMENDED)으로 변경.
사용자 맞춤 추천 물품이 홈 피드에 노출되도록 API 요청 파라미터 수정.

🎯 구현 목표

• 홈 화면 물품 목록 API 요청 시 sortField를 RECOMMENDED로 명시적 전달
• 백엔드 ItemSortField enum과 1:1 매핑되는 프론트 enum 추가
• 향후 다른 정렬 기준(거리순, 선호 카테고리순 등) 확장 가능하도록 구조화

✅ 구현 내용

1. ItemSortField enum 신규 추가

• 파일: lib/enums/item_sort_field.dart (신규)
• 변경 내용: 백엔드 ItemSortField enum 4개 값을 프론트에 1:1 매핑
  • createdDate → CREATED_DATE (최신순)
  • distance → DISTANCE (거리순)
  • preferredCategory → PREFERRED_CATEGORY (선호 카테고리순)
  • recommended → RECOMMENDED (추천순)
• 이유: 프로젝트 규칙에 따라 모든 enum은 lib/enums/ 폴더에 개별 파일로 관리. 기존 enum 패턴(label + serverName + fromServerName 헬퍼) 동일하게 적용

2. 물품 리스트 조회 API에 sortField 전달 로직 추가

• 파일: lib/services/apis/item_api.dart
• 변경 내용: getItems() 메서드에서 request.sortField가 있을 경우 fields에 sortField 파라미터 추가
• 이유: 홈 화면에서 명시적으로 정렬 기준을 전달할 수 있도록 구현

3. 홈 화면에서 RECOMMENDED 정렬 기준 적용

• 파일: lib/screens/home_tab_screen.dart
• 변경 내용: _loadInitialItems()와 _loadMoreItems()에서 ItemRequest 생성 시 sortField: ItemSortField.recommended.serverName 명시적 전달
• 이유: 홈 피드에서 추천 알고리즘 기반 물품 목록이 노출되도록 변경

🔧 주요 변경사항 상세

item_sort_field.dart (신규)

백엔드 ItemSortField enum과 동일한 구조로 프론트 enum 생성. label(한글 표시용)과 serverName(API 전송용)을 분리하여 관리. fromServerName 헬퍼 메서드로 서버 응답에서 enum 변환 가능.

item_api.dart

getItems() 메서드의 fields Map에 sortField 조건부 추가. 기존 pageNumber, pageSize만 전송하던 구조에서 정렬 기준도 함께 전송하도록 확장.

home_tab_screen.dart

ItemSortField enum import 추가. 초기 로드(_loadInitialItems)와 추가 로드(_loadMoreItems) 모두 동일하게 RECOMMENDED 정렬 기준 적용.

🧪 테스트 및 검증

• 홈 화면 진입 시 물품 목록이 추천순으로 정렬되어 노출되는지 확인
• 스크롤 시 추가 로드(페이징)에서도 동일하게 추천순 적용 확인
• 백엔드 연동 이슈: 🚀[기능개선][물품조회] 추천 물품 리스트 조회 시 사용자 반경(radiusInMeters) 내 물품만 반환하도록 개선 RomRom-BE#538

📌 참고사항

• 백엔드 ItemSortField enum: CREATED_DATE, DISTANCE, PREFERRED_CATEGORY, RECOMMENDED 4개 지원
• ItemRequest 모델에 sortField, sortDirection 필드는 기존에 이미 정의되어 있었음 (이번 작업에서는 sortField만 활용)
• sortDirection은 별도 전달하지 않음 (백엔드 기본값 사용)

[Cassiiopeia]

@suh-lab app build