[WORKSOUT] 검색 오버레이

화면 정보

Screen ID	Screen Title	진입 조건
SRCH-OVR-01	검색 메인 / 검색 중 (SH_120_Search, SH_121_Searching)	헤더 검색 버튼 클릭 → 검색어 입력 전(SH_120)/입력 중(SH_121)

개요

검색 버튼 클릭 시 진입하는 검색 오버레이. 검색어 입력 전(최근 검색어·추천 검색어·추천 브랜드·최근 본 상품·인기 상품)과 입력 중(자동완성 드롭다운)의 두 상태를 다룬다. 검색 실행 후 결과 화면은 search-results.md 참고.

원본: 검색 마스터.md(SH_120_Search + SH_121_Searching) + 검색 정책.md(최근검색어/추천검색어/추천브랜드/최근본상품 섹션) 병합.

---

화면 구성 — SH_120 검색 메인 (입력 전)

상단 검색바

항목	기준
플레이스홀더	검색어를 입력하세요
기본 상태	돋보기 아이콘
입력 중	X 아이콘 표시 / 클릭 시 전체 삭제 / 자동완성 드롭다운 표시
검색 실행 트리거	Enter 키 · 연관 검색어 클릭 · 검색 버튼 클릭
최대 입력 길이	50자 (초과 시 추가 입력 제한)
특수문자	허용
최소 길이 제한	없음

최근 검색어

항목	기준
최대 개수	20개 (최신순)
초과 시	21번째 검색 시 가장 오래된 항목 자동 삭제
개별 삭제	X 버튼 클릭 시 즉시 삭제
전체 삭제	전체 삭제 버튼 클릭 → 전체 삭제 + 영역 숨김
스크롤	가로 스크롤
검색어 클릭	해당 검색어로 검색 실행
동일 키워드 재검색	기존 항목 삭제 후 최신 항목으로 갱신
빈 상태 (앱)	섹션 자체가 표시되지 않음 (문구 노출 없음)
빈 상태 (웹)	“최근 검색어가 존재하지 않습니다” 메시지 표시

추천 검색어

항목	기준
데이터 기준	검색 빈도 상위 10개 키워드
관리	어드민에서 편집 가능. 관리자 설정 검색어는 어드민에 “관리자” 태그, 자동 생성은 “자동” 표시
스크롤	가로 스크롤
검색어 클릭	검색 실행 + 점수 증가 API 호출
빈 상태 (웹/앱 공통)	추천 검색어 섹션 자체가 표시되지 않음

추천 브랜드

항목	기준
데이터 기준	검색 빈도 상위 10개 브랜드
관리	어드민에서 편집 가능
표시 정보	브랜드 이미지 · 영문 브랜드명 · 한글 브랜드명 · 관심 브랜드 설정 수(포커스 브랜드 설정 회원 수) · 신상품 뱃지
관심 브랜드 토글	북마크 아이콘 클릭 시 설정/해제
브랜드 보기 버튼	브랜드 필터 적용된 SH_100_Main(plp-main.md)으로 이동
브랜드 카드 클릭	점수 증가 API 호출하지 않음
빈 상태 (웹/앱 공통)	추천 브랜드 섹션 자체가 표시되지 않음

최근 본 상품

항목	기준
최대 개수	24개 (마스터 기준, 미결 사항 참고)
로그인 사용자	계정 기반
비로그인 사용자	브라우저(로컬) 기반
정렬	최신순
스크롤	가로 스크롤
상품 클릭	상품 상세 이동 + 점수 증가 API 호출
빈 상태 (웹/앱 공통)	“최근 본 상품이 존재하지 않습니다” 메시지 표시

인기 상품 — 조회수 기준 (“많이 본 상품”)

항목	기준
데이터 기준	최근 24시간 조회수 상위 20개
리셋 주기	매일 자정 (00:00)
품절 상품	포함
비노출 상품	제외 (visible = 0)
정렬 우선순위	조회수(view_score) → 최신 업데이트(updated_ts) → 어드민 추천
관리	어드민 패널에서 수정 가능
상품 클릭	상품 상세 이동 + 점수 증가 API 호출
빈 상태 (웹/앱 공통)	“많이 본 상품이 존재하지 않습니다” 메시지 표시

인기 상품 — 구매량 기준 (“많이 산 상품”)

항목	기준
데이터 기준	최근 24시간 결제 완료 상품 중 최소 2개 이상 판매
리셋 주기	매일 자정 (00:00)
품절 상품	마스터 기준: 포함 — 정책 문서와 정면 충돌, 미결 사항 참고
비노출 상품	제외
정렬 우선순위	결제 완료 건수 → 판매 금액 → 상품 등록 순서
관리	어드민 패널에서 수정 가능
상품 클릭	상품 상세 이동 + 점수 증가 API 호출
빈 상태 (웹/앱 공통)	“많이 산 상품이 존재하지 않습니다” 메시지 표시

화면 이동 정책 — SH_120

액션	이동 화면
검색 실행 (검색 중 상태)	SH_121_Searching (본 문서 하단)
검색 결과 표시	search-results.md (SH_122_Searched)
브랜드 보기 버튼	SH_100_Main (브랜드 필터 적용)
상품 클릭	해당 상품 상세

---

화면 구성 — SH_121 검색 중 (입력 중)

상단 검색바

항목	기준
진입 시 동작	검색바 자동 포커스 + 키보드 자동 노출
API 호출 방식	입력할 때마다 즉시 호출 (디바운싱 없음)
입력 제한	SH_120과 동일 (최대 50자, 특수문자 허용, 최소 길이 없음)

운영 주의: 디바운싱 없이 즉시 호출하므로 짧은 시간에 여러 요청이 발생할 수 있다. 렌더링은 가장 마지막 입력값에 대한 응답을 우선한다.

자동완성 드롭다운

항목	기준
노출 위치	검색바 바로 아래 드롭다운
노출 조건	검색어 입력 시에만 표시
결과 없을 시	드롭다운 전체 숨김

브랜드 섹션 (자동완성 내)

항목	기준
노출 조건	자동완성 응답 중 isBrand = true 항목
최대 개수	5개
표시 형식	검색어 + 브랜드 라벨 (예: 칼하트 브랜드) — 브랜드 라벨이 표시된 검색어가 최상위 노출
정렬 기준	API 응답 순서. 브랜드가 여럿이면 검색 빈도수 상위 5개 순
클릭 동작	점수 증가 API 호출 → SH_100_Main (브랜드 필터 적용) 이동

운영 주의: 브랜드 클릭은 검색 결과 화면이 아닌 쇼핑 메인의 브랜드 필터 화면으로 이동한다. 점수 증가 API는 호출하지만 targetType은 SEARCH이다.

일반 연관 검색어 섹션

항목	기준
노출 조건	자동완성 응답 중 isBrand = false 항목
노출 위치	브랜드 섹션 아래
정렬 기준	API 응답 순서
클릭 동작	점수 증가 API 호출 → SH_122_Searched(search-results.md) 이동

화면 이동 정책 — SH_121

액션	이동 화면
일반 연관 검색어 클릭	SH_122_Searched
Enter 키 / 검색 버튼 클릭	SH_122_Searched
브랜드 추천 클릭	SH_100_Main (브랜드 필터 적용)
뒤로가기	SH_120_Search

---

정책

• 검색을 수행하면 해당 키워드가 자동으로 최근 검색어에 저장된다.
• 검색어 입력 시 실시간으로 관련 키워드가 제안된다.
• 브랜드 키워드는 검색 빈도수(모든 사용자의 일일 검색 데이터를 수집, 매월 업데이트)가 높은 5개 순으로 정렬된다.

---

API 연동

최근 검색어

항목	내용
엔드포인트	GET /v1/search/history
호출 시점	검색 화면 진입 시
활용 필드	searchKeyword (표시), updatedAt (정렬 기준)
최대 표시	20개

추천 검색어 및 브랜드

항목	내용
엔드포인트	GET /v1/score
파라미터	targetType=SEARCH (추천 검색어) / targetType=BRAND (추천 브랜드)
호출 시점	검색 화면 진입 시

• 추천 검색어 응답 주요 필드: targetType, targetId, name, sort
• 추천 브랜드 응답 주요 필드: targetType, targetId, name, korName, likeCnt, imageUrl, newArrival

최근 본 상품

항목	내용
엔드포인트	GET /v1/products/{productIds}
호출 시점	검색 화면 진입 시
데이터 처리	로그인: 계정 기반 / 비로그인: 로컬 저장 ID 목록 기반
최대 표시	24개 (마스터), 정책은 20개 — 미결 사항 참고

인기 상품

항목	내용
엔드포인트	GET /v1/score
파라미터	scoreSortType=DAILY_VIEW (조회수) / scoreSortType=DAILY_SALE (구매량)
호출 시점	검색 화면 진입 시
활용 필드	targetId, name, brandName, currentPrice, discountedRate, thumbnailUrl, sizes

관심 브랜드

기능	API
목록 조회	GET /v1/bookmarks
추가/제거	POST /v1/bookmarks (targetId, targetType: "BRAND")

자동완성 (SH_121)

항목	내용
엔드포인트	GET /v1/search/autoCompleteKeyword
파라미터	searchKeyword: 현재 입력값
호출 방식	입력할 때마다 즉시 호출 (디바운싱 없음)
활용 필드	isBrand (섹션 분리), targetId (점수 증가/이동), targetSearchKeyword (표시 텍스트)
표시 규칙	isBrand=true 최대 5개 상단 / isBrand=false 브랜드 아래

점수 증가

호출 시점	scoreType	targetType
추천 검색어 클릭	VIEW	SEARCH
최근 본 상품 클릭	VIEW	PRODUCT
인기 상품 클릭	VIEW	PRODUCT
브랜드 또는 일반 연관 검색어 클릭 (SH_121)	SEARCH	SEARCH

---

노출이 안 될 때 체크리스트

확인 항목	확인 방법	정상 기준
최근 검색어 미노출	GET /v1/search/history 응답	searchKeyword 1개 이상
추천 검색어/브랜드 미노출	GET /v1/score?targetType=SEARCH/BRAND 응답	1개 이상
최근 본 상품 미노출	GET /v1/products/{productIds} 응답	로컬 ID 목록 존재 여부 확인
인기 상품 미노출	GET /v1/score?scoreSortType=DAILY_VIEW/DAILY_SALE 응답	1개 이상
관심 브랜드 토글 미반영	GET /v1/bookmarks 응답	targetType BRAND 정상 여부
드롭다운 전체 미노출	입력값 + API 응답 확인	payload 1개 이상
브랜드/일반 섹션 분리 오류	isBrand 매핑 확인	true → 브랜드, false → 일반
이전 검색어 결과 잔류	마지막 입력값 기준 렌더링 여부	최신 입력값 응답 우선
브랜드 클릭 이동 오류	클릭 이벤트 라우팅 파라미터 확인	SH_100_Main + 브랜드 필터
점수 증가 미호출	POST /v1/score/scoreUp 호출 여부	targetId / scoreType 정상

에러 처리 요약

증상	예상 원인	1차 조치
추천 검색어/브랜드 미노출	score API 실패 또는 데이터 없음	GET /v1/score 파라미터 및 응답 확인
자동완성 드롭다운 미노출	자동완성 API 실패 또는 빈 입력 처리 오류	입력값 + API 응답 확인
브랜드/일반 섹션 분리 오류	isBrand 매핑 오류	응답 파싱 로직 확인
이전 검색 결과 잔류	최신 응답 비교 처리 누락	마지막 입력 기준 렌더링 여부 확인

---

관련 QA 패턴

검색은 “검색 → 상세 → 뒤로가기” 네비게이션 스택 관리와 필터 상태가 다른 탭으로 새어나가는 문제가 반복되는 영역이다. 재진입 시 상태 유지, 탭 간 상태 격리를 체크할 것.

자세히: QA 체크리스트 §3 화면 전환·재진입

---

미결 사항

항목	내용
최근 본 상품 최대 개수 충돌	검색 마스터.md(SH_120 섹션 5)는 24개, 검색 정책.md(4.4.1)는 20개. 정면 충돌. 최신 문서 확인 필요 — 두 문서 모두 최종 수정일이 명시되어 있으나 어느 쪽이 실제 구현 기준인지 운영팀 확인 필요. 현재 문서는 마스터(24개)를 기본으로 기재
“많이 산 상품” 품절 표시 여부 정면 충돌	검색 마스터.md(SH_120 섹션 7, 인기 상품 — 구매량 기준)는 품절 상품 포함으로 명시. 검색 정책.md(4.6.1, 많이 산 상품)는 “품절 상품은 표시되지 않습니다”로 명시 — 정면 충돌. 실제 구현 기준 운영팀 확정 필요
웹/앱 빈 상태 문구 차이	최근 검색어 빈 상태는 웹(문구 노출)과 앱(섹션 숨김)이 다르게 동작 — 의도된 차이인지 확인 필요

---

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 — 검색 마스터.md(SH_120_Search + SH_121_Searching) + 검색 정책.md(최근검색어/추천검색어/추천브랜드/최근본상품 섹션) 병합