[WORKSOUT] PLP 필터

화면 정보

Screen ID	Screen Title	Screen Path
SHOP-FLT-01	필터 선택 (FT_110_Filter_Selected)	쇼핑 메인 하단 필터 버튼 진입

개요

쇼핑 메인(plp-main)에서 필터 버튼 클릭 시 열리는 필터 바텀시트의 구조·상태 관리·API 스펙을 정의한다. 다른 화면(검색 결과 등)에서 필터를 클릭하면 이 화면(필터가 켜진 쇼핑 화면)으로 이동한다.

원본: 필터 마스터 문서.md(베이스) + 필터 정책.md 병합.

화면 구성

전체 구조

필터 선택 화면 (FT_110_Filter_Selected)
├── 상단 필터 탭                ← 필터명 + 선택 수 표시
├── 중간 옵션 영역              ← 선택된 필터의 상세 옵션
├── 구분 필터                   ← 단일 선택, 쇼핑 진입 시 남성 디폴트
├── 컬렉션 필터                 ← 단일 선택, 정적 필터, 선택 시 전체 초기화
├── 브랜드 필터                 ← 다중 선택, 포커스 브랜드 포함
├── 가격대 필터                 ← 단일 선택 + 직접 입력
├── 색상 필터                   ← 다중 선택, 조건부 노출
├── 사이즈 필터                 ← 다중 선택, API 개편 예정
└── 하단 버튼 영역              ← 전체상품보기 / 초기화 / N개 상품보기

접근 방식

필터는 쇼핑 화면 하단 필터 버튼을 클릭하면 열린다.
바텀시트 형태로 노출된다.
다른 화면에서 필터를 클릭하면 쇼핑 화면에서 필터가 켜진 화면으로 이동한다.

섹션별 관리 주체

섹션	관리 주체	데이터 출처	비고
필터 탭	앱 자체 처리	현재 필터 상태	선택 수를 탭에 표시
구분/컬렉션/가격	상품 필터 시스템 + 앱 자체 처리	`GET /v1/products/newFilter`	일부 정적 규칙 포함
브랜드	상품 필터 시스템 + 북마크 시스템	`GET /v1/products/newFilter`, `GET/POST /v1/bookmarks`	포커스 브랜드 별도 제공
색상	상품 필터 시스템	`GET /v1/products/newFilter`	조건부 노출
사이즈	상품 필터 시스템	`GET /v1/products/newFilter`	향후 `sizeType` 추가 예정
하단 버튼	앱 자체 처리	현재 선택 상태 + 상품 수	적용/초기화

상단 필터 칩

항목	기준
기본 표시	필터명 표시 (예: “브랜드”, “색상”, “사이즈”)
선택 상태 표시	Chip 색상 변경으로 선택 여부 구분
칩 전환 방식	칩 클릭 또는 좌우 스와이프
레이아웃	가로 스크롤 가능
인터랙션	모든 칩 클릭 시 모달(card) 형태로 열림
세부 선택 표시	세부 필터 옵션 선택 시 필터명 옆에 선택한 수가 `(N)`으로 표시

구분 필터 Chip 특수 규칙 — 구분 필터는 단일 선택이며 현재 선택값이 중요하므로, 다른 필터들과 달리 chip 라벨에 선택값을 직접 표시한다. 다른 필터는 필터명만 표시하고 선택 개수를 함께 표시한다.

항목	기준
Chip 라벨	현재 선택된 값을 직접 표시 (예: “남성”)
라벨 동적 변경	사용자가 다른 구분을 선택하면 chip 라벨이 해당 값으로 자동 업데이트
동적 필터 적용 시	다른 필터로 인해 구분 옵션이 변경되면 chip 라벨도 자동 업데이트
구분 옵션 1개만 남는 경우	해당 구분값을 chip으로 표시하되 비활성화 또는 숨김 처리

선택된 필터 표시 (카테고리 내비게이션 하단)

카테고리 내비게이션 아래 줄에 선택된 필터 옵션이 노출된다.
“초기화” 버튼이 가장 왼쪽에 고정 위치한다.
선택된 필터는 필터 옵션 순서(구분 → 컬렉션 → 브랜드 → 가격대 → 색상 → 의류 사이즈 → 신발 사이즈 → 기타 사이즈)대로 표시된다.
각 필터 내에서는 사용자가 선택한 순서대로 옵션이 표시된다.

하단 버튼 영역

버튼	동작
전체상품보기	모든 필터 초기화 + 전체 상품 상태 복귀. 아무 필터도 선택하지 않았을 때 이 버튼만 하단에 표시됨
초기화	모든 필터 리셋, 현재 탭 위치 유지
N개 상품보기	현재 선택된 필터 적용 + 상품 목록 갱신. 필터를 하나 이상 선택하면 초기화 버튼과 함께 표시됨

공통 상태 규칙

필터 탭 전환 시 선택 상태 유지
Bottom Sheet 재열기 시 이전 선택 복원
동적 필터는 다른 필터 선택에 따라 옵션 변동

필터별 정책

구분 필터

항목	기준
선택 방식	단일 선택
필터 타입	동적 필터(마스터 기준) — 정책 문서에는 정적 필터로 기재, 미결 사항 참고
옵션	남성 · 여성 · 생활
쇼핑 화면 진입 시 디폴트	`남성` 자동 선택
Chip 표시	현재 선택된 값 직접 표시 (예: “남성”)

연동 규칙

다른 구분 선택 시 기존 구분 선택 자동 해제
선택된 구분에 따라 브랜드·카테고리·사이즈 등 다른 필터 옵션도 재계산
카테고리 ’U’는 유니섹스로 남성/여성 옵션 모두에 속함

구분 필터 기본값 디폴트 적용 범위에 대한 원문 표기 차이는 미결 사항에 기록.

컬렉션 필터

항목	기준
선택 방식	단일 선택
필터 타입	정적 필터
옵션 출처	어드민에서 관리
특이 정책	선택 즉시 기존에 적용된 모든 필터 초기화

운영 주의: 컬렉션 필터는 일반 필터 UX와 다르게, 선택하는 순간 다른 필터가 전부 해제된다. 컬렉션 해제 후에는 다른 필터를 다시 개별 선택할 수 있다.

브랜드 필터

항목	기준
선택 방식	다중 선택
필터 타입	동적 필터
정렬 기준	알파벳 순 (포커스 브랜드·일반 브랜드 모두)

포커스 브랜드 영역

항목	기준
노출 조건	사용자가 설정한 포커스 브랜드가 있을 때
미설정 상태 문구	`설정한 포커스 브랜드가 없습니다.`
넘김 단위	5개 단위로 우측 스와이프하며 열람
위치 표시 점	4개까지는 점 표시 없음, 6개 이상일 때 가로 스와이프 + 하단 위치 표시 점 노출

일반 브랜드 목록 영역

위치	표시 항목
좌측	북마크 버튼
중앙	브랜드명
중앙 우측 상단	신상품 점 표시 (`isNewArrival`)
하단	브랜드별 상품 개수(이전 필터로 인해 적용된 해당 브랜드의 상품 수)
우측	필터 체크박스

북마크 vs 필터 체크박스 구분

기능	동작
북마크 버튼	포커스 브랜드 설정/해제, 포커스 브랜드 영역 즉시 업데이트
체크박스	실제 필터 적용. 브랜드 리스트에서 선택한 브랜드가 포커스 브랜드와 동일하면 포커스 브랜드 옆 체크박스도 함께 체크됨
관계	독립적 — 북마크만 해도 필터 적용 안 됨

동적 갱신

다른 필터 변경 시 브랜드별 count 실시간 갱신
상품 수가 0인 브랜드는 목록 하단으로 이동

브랜드 표시 세부 규칙은 브랜드 메인 문서와 동일하다.

가격대 필터

항목	기준
선택 방식	단일 선택
필터 타입	정적 필터

고정 가격대 옵션: 5만원 이하 · 5~~10만원 · 10~~20만원 · 20~~50만원 · 50~~100만원 · 100만원 이상 · 직접 입력

직접 입력 규칙

항목	기준
노출 조건	직접 입력 항목 선택 시
플레이스홀더	현재 필터로 설정된 상품 목록의 최소/최대 값
입력 형식	숫자만 허용
유효성 검사	최소 금액 > 최대 금액 시 오류

색상 필터

항목	기준
선택 방식	다중 선택
필터 타입	동적 필터
기본 옵션 수	14개

색상 옵션 14개: 블랙 · 화이트 · 골드 · 실버 · 레드 · 핑크 · 블루 · 퍼플 · 옐로우 · 오렌지 · 브라운 · 그레이 · 그린 · 믹스

노출 조건 — 아래 중 하나 이상 만족 시 표시

카테고리 · 컬렉션 · 브랜드 · 가격대 중 하나 이상 선택됨
(1차 카테고리가 ’전체상품’이면 미노출)

사이즈 필터

항목	기준
선택 방식	다중 선택
필터 타입	동적 필터
노출 조건	기본값 필터 옵션(구분/컬렉션/브랜드/색상) 중 하나라도 선택했을 때 노출
현재 상태	단일 목록 반환
향후 변경 예정	의류 / 신발 / 기타 분류 추가 (`sizeType` 필드)

분류별 표시 규칙 (API 개편 후 적용)

해당 분류에 사이즈가 있을 때만 섹션 노출
사이즈가 없는 분류는 섹션 전체 숨김
해당 필터가 적용된 상품이 가지고 있는 모든 사이즈만 노출

필터 결과 화면

필터 적용 시 해당 조건에 맞는 상품만 표시된다.
상품은 신상품 순으로 기본 정렬된다.
필터링된 상품은 무한 스크롤 방식으로 로드된다.
필터 조건에 맞는 상품이 없을 경우 “해당하는 상품이 존재하지 않습니다” 메시지와 “필터 초기화” 버튼이 표시된다.
필터 초기화 버튼 클릭 시 모든 필터가 초기화되고 전체 상품이 표시된다.

API 연동

필터 옵션 조회

엔드포인트: GET /v1/products/newFilter?mainCategoryId={id}

호출 시점

필터 화면 열릴 때
다른 필터 선택으로 옵션 재계산이 필요할 때

응답 주요 필드

필드	설명
`divisions`	구분 옵션 (`남자` / `여자` / `생활`)
`collections`	컬렉션 목록 (어드민 관리)
`brands[].brandId`	브랜드 ID
`brands[].brandName`	브랜드명
`brands[].isNewArrival`	신상품 여부
`brands[].count`	현재 필터 기준 상품 수
`brands[].isBookmarked`	포커스 브랜드 여부
`colors`	색상 목록
`sizes`	사이즈 목록 (현재 단일, 향후 `sizeType` 추가 예정)
`priceRange.minPrice` / `maxPrice`	직접 입력 플레이스홀더 기준값

포커스 브랜드 조회 / 설정·해제

기능	엔드포인트	비고
조회	`GET /v1/bookmarks?type=BRAND`	브랜드 필터 탭 진입 시 / 포커스 브랜드 영역 갱신 시
설정/해제	`POST /v1/bookmarks`	요청 필드: `targetId`(브랜드 ID), `targetType: "BRAND"`. 브랜드 목록에서 북마크 버튼 클릭 시

구분 필터 디폴트 처리

항목	처리 기준
초기 진입	`divisions` 파라미터를 `남자`로 설정한 상태로 `GET /v1/products/newFilter` 호출
사용자 변경 시	선택된 구분값으로 파라미터 교체 후 재호출
초기화 버튼 클릭 시	전체 필터 리셋 — 디폴트(`남자`) 복귀 여부는 구현 정책 확인 필요

노출이 안 될 때 체크리스트

확인 항목	확인 방법	정상 기준
쇼핑 진입 시 남성 미선택	초기 진입 상태 확인	남성
Chip 라벨이 “구분”으로만 표시됨	Chip 표시 확인	선택된 값(“남성” 등) 직접 표시
남자/여자 동시 선택됨	선택 상태 확인	단일 선택, 기존 값 자동 해제
구분 변경 후 다른 필터 그대로임	브랜드/사이즈 목록 확인	구분에 따라 옵션 재계산
컬렉션 선택 후 다른 필터 잔존	필터 상태 확인	다른 필터 전체 해제
컬렉션 복수 선택 가능	선택 상태 확인	단일 선택만 허용
포커스 브랜드 미노출	`GET /v1/bookmarks?type=BRAND` 응답	북마크된 브랜드 존재 여부 확인
북마크만 했는데 필터 적용됨	체크박스 상태 확인	북마크와 필터 체크박스는 별도 상태
특정 브랜드가 아래로 내려감	동적 필터 결과 count 확인	상품 없는 브랜드 하단 이동 정책
구간과 직접 입력 동시 적용됨	선택 상태 확인	단일 선택, 하나만 유효
최소 > 최대 저장됨	유효성 검사 동작 확인	오류 메시지 노출 후 저장 차단
색상 필터 미노출	현재 필터 선택 상태 확인	노출 조건 중 1개 이상 충족
사이즈 분류 이상	API `sizeType` 지원 여부 확인	미지원 시 단일 목록 노출이 현재 기준

에러 처리 요약

증상	예상 원인	1차 조치
탭 클릭 시 내용이 안 바뀜	탭 상태와 본문 상태 분리 오류	현재 선택 탭과 렌더링 대상 확인
포커스 브랜드 미노출	북마크 조회 실패 또는 빈 상태	`GET /v1/bookmarks?type=BRAND` 응답 확인
컬렉션 선택 후 필터 일부 잔존	전체 초기화 로직 미완료	컬렉션 선택 후 필터 상태 초기화 확인
가격 입력 저장 실패	유효성 검사 오류	최소/최대 입력 값 확인
사이즈 분류 이상	API 개편 전후 버전 차이	`sizeType` 지원 여부 확인
쇼핑 진입 시 남성 미선택	초기 디폴트 처리 누락	구분 필터 초기화 로직 확인

미결 사항

항목	내용
구분 필터 기본값 “일본 전역 변경사항” 범위	필터 마스터 문서 내에서 표기가 두 가지로 혼재: 섹션 2(구분 필터)에서는 “일본 전역 변경사항”(JP 한정처럼 서술)이라고 적혀 있고, PART 2 API 섹션에서는 “전역 변경사항”(국가 한정 없이 서술)이라고 적혀 있다. `남성` 디폴트 선택이 KR/JP 중 어느 쪽에 적용되는 것인지, 혹은 양쪽 모두인지 운영팀 확인 필요
구분 필터 타입(동적/정적) 불일치	필터 마스터 문서는 구분 필터를 “동적 필터”로 분류하나, 필터 정책 문서(4.2)는 “정적 필터”로 분류. 실제 구현 기준 확인 필요
사이즈 필터 `sizeType`(의류/신발/기타) 개편	마스터 기준 API 개편 예정(향후), 정책 문서는 이미 “의류 사이즈, 신발 사이즈, 기타 사이즈로 구분”된다고 서술 — 실제 API 반영 여부 개발팀 확인 필요

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 — `필터 마스터 문서.md`(베이스) + `필터 정책.md` 병합 (색상옵션 14개 상세, 필터 노출순서, 타화면 필터클릭 이동 등 흡수)