David Brain

3-2_검색-필터-API-UI

4 min read

ID: key_26_22_05_25_P3_3_2 Created date: 5월 25 2026 월요일

연관 문서

개발 일정 > Phase 3 서버 개발 | UI 개발

개요

이슈 전문 검색 및 고급 필터 API와 UI를 구현한다.
PostgreSQL Full-Text Search 또는 Elasticsearch를 활용한다.

  • 예상 소요: 3~4일
  • 선행 조건: Phase 2 완료, 검색 엔진 선택 결정
  • 완료 기준: 키워드 검색 결과 500ms 이내 반환 확인

Claude Code 작업 수행서

작업 지시

CIRA 서버 + UI에 이슈 검색 기능을 구현해줘.

[검색 엔진 선택]
- Phase 1: PostgreSQL Full-Text Search (FTS)
- Phase 2 (선택): Elasticsearch 전환

[서버 수행 작업]

1. PostgreSQL FTS 설정
   V140__add_search_vector.sql:
   ALTER TABLE issues ADD COLUMN search_vector TSVECTOR;
   CREATE INDEX idx_issues_search ON issues USING GIN(search_vector);
   -- 트리거: issues INSERT/UPDATE 시 search_vector 자동 갱신
   CREATE OR REPLACE FUNCTION update_issue_search_vector()
   RETURNS TRIGGER AS $$
   BEGIN
     NEW.search_vector := to_tsvector('simple',
       COALESCE(NEW.title, '') || ' ' || COALESCE(NEW.description, ''));
     RETURN NEW;
   END;
   $$ LANGUAGE plpgsql;
   CREATE TRIGGER issue_search_vector_update
   BEFORE INSERT OR UPDATE ON issues
   FOR EACH ROW EXECUTE FUNCTION update_issue_search_vector();

2. 검색 API
   GET /api/v1/search/issues
   파라미터:
   - q: 검색어 (FTS)
   - projectId: 프로젝트 필터 (복수)
   - status: 상태 필터 (복수)
   - priority: 우선순위
   - assigneeId: 담당자
   - reporterId: 보고자
   - issueType: 이슈 타입
   - sprintId: 스프린트
   - createdAfter / createdBefore: 날짜 범위
   - page, size, sort

   구현:
   - JPA Specification 또는 QueryDSL로 동적 쿼리 빌드
   - q가 있는 경우 FTS 적용 (ts_rank로 relevance 정렬)
   - 없는 경우 일반 필터만 적용
   - 검색 결과 하이라이팅 (ts_headline)

3. 저장된 필터 API
   POST   /api/v1/saved-filters    — 현재 필터 저장
   GET    /api/v1/saved-filters    — 내 저장 필터 목록
   DELETE /api/v1/saved-filters/{id}

4. 자동완성 API
   GET /api/v1/autocomplete
   - type: ASSIGNEE / ISSUE_TYPE / SPRINT / STATUS
   - keyword: 입력 중인 텍스트
   - 디바운스 적용 (300ms)

[UI 수행 작업]

5. 글로벌 검색 바
   파일: src/components/layout/GlobalSearch.tsx
   - 헤더 중앙 검색 바 (단축키: Cmd+K)
   - 검색어 입력 시 실시간 결과 팝업
   - 결과: 이슈 목록 (최대 5건) + "전체 결과 보기" 링크
   - 이슈 클릭 → 이슈 상세 이동

6. 고급 검색 페이지
   파일: src/app/(main)/search/page.tsx
   구성:
   - 좌측: 필터 패널
     * 프로젝트 (체크박스)
     * 상태 (체크박스)
     * 우선순위 (체크박스)
     * 담당자 (멀티 셀렉트)
     * 날짜 범위 (DateRangePicker)
   - 우측: 검색 결과 목록
     * 페이지네이션
     * 정렬 (관련도 / 최신순 / 업데이트순)
   - 상단: 현재 필터 요약 태그 + 초기화 버튼
   - 필터 저장 버튼 → 이름 입력 → saved_filters 저장

7. URL 상태 동기화
   - 모든 필터 파라미터를 URL 쿼리 스트링에 반영
   - 공유 가능한 검색 URL

완료 기준

항목기준
FTS 검색한국어 포함 키워드 검색 동작
다중 필터 조합필터 5종 동시 적용
응답 속도500ms 이내
필터 저장/불러오기저장 후 재적용 동작
하이라이팅검색어 매칭 부분 강조

Graph View

Backlinks