4-5_JQL-고급-검색

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

연관 문서

개발 일정 > Phase 4 서버 개발 | UI 개발 | 3-2_검색-필터-API-UI

---

개요

JQL(CIRA Query Language) 파서를 구현하여 고급 이슈 검색을 지원한다.
Jira JQL과 유사한 문법으로 복잡한 조건 조합을 가능하게 한다.

• 예상 소요: 5~7일
• 선행 조건: 3-2_검색-필터-API-UI 완료

---

CQL 문법 정의 (CIRA Query Language)

project = "CIRA" AND status = "In Progress" AND assignee = currentUser()
priority in (HIGH, HIGHEST) AND due <= "2026-06-30"
text ~ "로그인" AND createdDate >= -7d
sprint in openSprints() ORDER BY priority DESC, updated DESC

---

Claude Code 작업 수행서

작업 지시

CIRA 서버 + UI에 CQL(CIRA Query Language) 고급 검색을 구현해줘.

[서버 수행 작업]

1. CQL 파서 구현
   파일: src/main/java/.../search/cql/
   ├── CqlLexer.java       — 토크나이저
   ├── CqlParser.java      — 파서 (재귀 하강 파싱)
   ├── CqlAst.java         — AST 노드 정의
   └── CqlQueryBuilder.java — AST → JPA Specification 변환

   지원 연산자:
   - 비교: =, !=, <, <=, >, >=
   - 텍스트: ~ (contains), !~ (not contains)
   - 컬렉션: in (...), not in (...)
   - 논리: AND, OR, NOT
   - 정렬: ORDER BY {field} ASC/DESC

   지원 필드:
   - project, status, assignee, reporter, priority
   - issueType, sprint, text, created, updated, due
   - storyPoints, labels

   지원 함수:
   - currentUser(): 현재 로그인 사용자
   - openSprints(): 현재 활성 스프린트
   - closedSprints(): 종료된 스프린트
   - now(): 현재 시각
   - startOfDay(), endOfDay()

2. CQL API
   POST /api/v1/search/cql
   Request: { "cql": "project = CIRA AND status = 'In Progress'", "page": 0, "size": 20 }
   Response: PageResponse<IssueSummaryResponse>
   - CQL 파싱 오류 시: 400 + 오류 위치 및 메시지

3. CQL 유효성 검증 API
   POST /api/v1/search/cql/validate
   Request: { "cql": "..." }
   Response: { "valid": true } 또는 { "valid": false, "error": "...", "position": 15 }
   → 에디터 실시간 검증에 활용

4. 자동완성 API 확장
   GET /api/v1/search/cql/autocomplete
   파라미터: cql(현재 입력 중 CQL), cursor(커서 위치)
   Response: { "suggestions": ["In Progress", "In Review", "Done"] }
   → 현재 커서 위치의 필드/값 자동완성

[UI 수행 작업]

5. CQL 에디터 컴포넌트
   파일: src/components/search/CqlEditor.tsx
   - CodeMirror 6 기반 에디터
   - 구문 하이라이팅 (키워드: 파란색, 문자열: 초록색, 연산자: 주황색)
   - 자동완성: 300ms 디바운스 후 서버 API 호출
   - 실시간 유효성 검증 (입력 중지 500ms 후)
   - 에러 언더라인 + 툴팁
   - 이전 CQL 히스토리 (localStorage, 최대 20건)

6. CQL 검색 페이지
   파일: src/app/(main)/search/advanced/page.tsx
   - 상단: CQL 에디터 (전체 너비)
   - "기본 검색으로 전환" 링크 (↔ [[3-2_검색-필터-API-UI]] 기본 검색)
   - 결과: 이슈 목록 테이블
   - 저장된 CQL 필터 사이드바

7. Basic ↔ Advanced 전환
   - 기본 검색 필터 → CQL 자동 변환
     예: status=In Progress, assignee=나 → "status = 'In Progress' AND assignee = currentUser()"
   - CQL → 기본 검색 변환 (단순 쿼리만 지원, 복잡한 경우 고급 모드 유지)

---

완료 기준

항목	기준
CQL 파싱	기본 5종 연산자 동작
함수 지원	currentUser(), openSprints()
실시간 자동완성	필드값 후보 300ms 내 반환
에러 표시	오류 위치 언더라인 + 메시지
기본↔고급 전환	단순 쿼리 양방향 변환
응답 속도	CQL 실행 1초 이내 (10,000 이슈 기준)