[Feat/#94] 검색 화면 구현

[jjunh33]

#️⃣연관된 이슈

• Closes 검색 화면 구현 (진입·검색 중·검색 결과·결과 없음) #94

🎯 해결하려는 문제가 무엇인가요?

검색 화면이 없어서 홈·행사·공지·열린피드백·빌릴게 헤더의 검색 아이콘이 동작하지 않습니다. Figma 검색 프레임(진입 / 검색 중 / 검색 완료 / 결과 없음)과 화면설계서(FLW_HOM_001)를 기준으로 검색 화면을 구현합니다.

❓ 왜 해결해야 하나요?

검색 아이콘이 이미 각 헤더에 노출되어 있는데 눌러도 아무 일도 일어나지 않습니다. 사용자가 행사·공지·피드백·빌릴게·아카이빙을 한곳에서 찾을 수 있어야 합니다.

⭐ 어떻게 해결했나요?

• /search 라우트와 SearchScreen을 추가했습니다. 진입(최근 검색어) → 응답 대기(스켈레톤) → 결과 / 결과 없음 흐름입니다.

• 결과는 전체 / 행사 / 공지 / 열린피드백 / 빌릴게 / 아카이빙 탭으로 보여주고, 탭명에 결과 수를 붙입니다. 전체 탭은 카테고리별 2개까지만 보여주고 n개 더보기로 해당 탭으로 이동합니다.

• 홈 검색은 전체 탭부터, 행사·공지·열린피드백·빌릴게 헤더의 검색은 해당 탭부터 시작합니다 (/search?tab=).

• 최근 검색어는 localStorage(stream:search:recent, 최대 10개)에 저장하고, 개별 삭제와 전체 삭제를 지원합니다.

• 카드는 기존 것을 재사용했습니다. 설계서 4번에서 UI가 달라지는 두 가지만 바꿨습니다: 아카이빙(SearchArchivingCard 신규), 빌릴게(BililgeItemCard의 bordered 옵션).

• 용어 사전에 검색 ↔ search를 추가했고, wds-component-usage.md에 검색 화면에서 확정한 WDS 매핑을 기록했습니다.

• 데이터는 main의 로딩 구조(entities/<도메인> API + mockupApi + use()/Suspense)를 따릅니다. entities/search/searchApi.ts의 fetchSearchResults(keyword)를 SearchResultContent가 use()로 읽고, 응답 대기는 Suspense가 SearchResultSkeleton으로 받습니다.

커밋 구성: 문서 → 아카이빙 목데이터 → 빌릴게 카드 bordered → 검색 화면 → 헤더 아이콘 연결 → 데이터 로딩 구조 전환(main 리베이스 후 추가)

2026-10-04.12.21.55.mov

🧩 이 PR의 한계 & 트레이드오프

• 검색은 목데이터 기반입니다. API가 없어서 fetchSearchResults()가 mockupApi로 기존 목데이터를 제목류 필드(행사·공지 title, 피드백 question, 빌릴게 name, 아카이빙 title)로 대소문자 무시 부분 일치 필터링해 돌려줍니다. 개발 서버에서는 mockupApi의 500ms 지연으로 스켈레톤을 볼 수 있고, 배포 빌드에서는 바로 응답합니다. 본문은 목데이터가 전부 같은 글이라 검색 대상에서 뺐습니다.
• 최근 검색어는 임시로 localStorage에 저장합니다. API 연동 후에는 localStorage 대신 서버(DB)에서 가져오도록 바꿀 예정이라, 이 PR의 useRecentSearches 훅(저장·조회·개별 삭제·전체 삭제)은 그때 API 호출로 교체됩니다. 훅의 반환 형태는 유지하므로 화면 쪽 변경은 크지 않을 것으로 봅니다.
• API 연동 시 fetchSearchResults 안쪽만 요청 코드로 교체하면 됩니다(화면은 이 함수로만 데이터를 받습니다). 다만 search라는 용어와 응답 형태(/api/search, 카테고리별 전체 개수 제공 여부)는 백엔드와 맞춰야 합니다. 지금은 배열 길이를 탭 숫자로 쓰므로 서버가 페이지네이션하면 숫자가 틀어집니다.
• 아카이빙은 상세 화면이 없어서 카드를 링크로 연결하지 않았습니다. 목데이터 5개도 이 PR에서 새로 추가했습니다.
• 검색 중 헤더 슬롯에 입력창을 넣으면 한글 IME 조합이 깨져서(컨트롤드 input이 한 단계 더 렌더링됨) 검색 헤더를 화면 본문에 두었습니다. WDS SearchField는 배경·패딩·지움 버튼 노출 조건이 Figma와 달라 쓰지 않고 로컬 컴포넌트로 만들었습니다 (근거는 wds-component-usage.md).
• 열린피드백은 아직 entities로 옮겨지지 않아 searchApi가 features/feedbacks/constants의 목데이터를 직접 읽습니다.
• 에러 상태는 구현하지 않았습니다. 목데이터라 실패하지 않고 Figma에도 프레임이 없습니다.

⛓️ 기존 기능에 미치는 영향

• 홈·행사·공지·열린피드백·빌릴게 목록 화면의 검색 아이콘에 onClick만 추가했습니다(행사·공지·빌릴게는 main의 Suspense 리팩터링 위에 다시 적용).
• 아카이빙 목데이터 위치를 entities/archives/(types + mock)로 두었습니다.
• BililgeItemCard에 선택 prop bordered를 추가했습니다. 기본값은 기존 동작과 같습니다.
• /search 라우트는 hasBottomNav: false입니다.

🔀 Edge Case & 실패 시나리오

• 공백만 입력하고 제출하면 무시합니다.
• 결과 확인 후 검색어를 고치면 결과를 걷고 최근 검색어로 돌아갑니다 (진행 중이던 조회도 취소).
• 같은 검색어를 다시 제출하면 mockupApi가 Promise를 재사용해서 스켈레톤 없이 바로 결과가 나옵니다.
• 전체 결과가 0개면 탭 없이 empty 화면만 보여주고, 특정 탭만 0개면 탭은 유지한 채 empty를 보여줍니다.
• 딥링크·WebView로 바로 진입해 히스토리가 없으면 뒤로가기는 홈으로 이동합니다 (replace).
• localStorage 접근이 막힌 환경에서는 최근 검색어만 저장되지 않고 검색 자체는 동작합니다.
• 탭 라벨이 Figma 안에서 15px/17px로 섞여 있어(앞의 두 탭은 15px, 나머지 네 탭은 17px) 15px로 통일했습니다.

📋 검토한 대안과 선택 이유

• WDS SearchField 사용: 스펙 차이(배경색, 패딩, 지움 버튼 노출 조건)가 있고 내부 오버라이드는 컨벤션상 금지라 로컬 컴포넌트로 구현했습니다.
• ScreenLayout 헤더 슬롯에 입력창 배치: 위 IME 문제로 제외했습니다.
• 최근 검색어를 서버(DB)에 저장: 최종적으로는 서버에서 가져올 예정이지만 아직 API가 없어서, 그 전까지 새로고침 후에도 남도록 localStorage를 임시로 택했습니다.

💬 리뷰 포인트

• [c] 빌릴게 검색 결과의 "대여 신청"은 대여 바텀시트가 빌릴게 화면 안의 상태라 /bililge로 이동만 합니다. 검색에서 바로 바텀시트를 열어야 하는지 확인이 필요합니다.
• [c] 검색어를 고치면 결과가 사라지고 최근 검색어로 돌아가는 동작이 설계서 의도와 맞는지 봐주세요.
• [a] 최근 검색어 최대 10개는 설계서에 명시가 없어 임의로 정했습니다.
• [a] empty 화면의 세로 위치는 Figma 프레임 높이 기준으로 맞췄고, WebView 높이에 따라 약 7px 차이가 날 수 있습니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 24096aaf-1612-4fb4-b9ce-7084e9a25acd

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[xeoxxn]

구현 화면 사진도 같이 올려주세요~

[jjunh33]

네 수정했습니다~