Hyungseoky/QPIDS

Q-PIDS — QP Manual Search System

SK실트론 사내 지침서·가이드·매뉴얼 문서를 멀티모달 RAG 파이프라인으로 검색하는 웹 서비스. 백엔드 FastAPI(qp_rag_pipeline.py)의 /search 엔드포인트를 호출하여 텍스트/비전 트랙 통합 검색 결과를 사용자에게 시각적으로 제공한다.

---

1. 개요

항목	내용
서비스명	Q-PIDS (QP Process Information Document Search)
도메인	반도체 웨이퍼 제조 공정 사내 문서 검색
프런트엔드	React 19 + TypeScript + Vite + Tailwind CSS v4 + Motion
백엔드 (BFF)	Node.js + Express (프록시 + 정적 서빙)
검색 엔진	FastAPI + LangGraph 멀티모달 RAG 파이프라인 (qp_rag_pipeline.py)
기본 포트	3000 (웹 UI), 18504 (FastAPI), 4275/4276 (Search/Dict API)

---

2. 아키텍처

┌──────────────┐       ┌────────────────┐        ┌────────────────────┐
│   Browser    │──────►│  Express BFF   │───────►│  FastAPI Pipeline  │
│ (React UI)   │ /api  │  (server.ts)   │ /search│ (qp_rag_pipeline)  │
│              │       │                │        │                    │
│              │       │  /snap_data/*  │        │ Search/Dict/LLM/   │
│              │◄──────│  (정적 이미지) │        │ Reranker 호출      │
└──────────────┘       └────────────────┘        └────────────────────┘

데이터 흐름

1. 사용자가 쿼리 입력 + 필터(공장정보 / 제품 정보) 선택
2. React → POST /api/search (Express BFF)
3. BFF → FastAPI POST /search 프록시 (filters에 apply_region, apply_product 포함)
4. FastAPI 내부에서 LangGraph 파이프라인 실행 (쿼리 분석 → 멀티쿼리 생성 → 텍스트/비전 병렬 검색 → WRRF 융합 → Answerability 평가)
5. 응답을 SearchResult[]로 매핑하여 카드 그리드 + 상세 모달로 렌더링
6. 썸네일은 /snap_data/<doc_id>/<image> 경로로 정적 서빙

---

3. 주요 화면

3.1 검색 화면 (view: 'search')

• 중앙 정렬된 검색 입력창 (예시 placeholder: "300mm DSP공정 Pad 교체주기 알려줘")
• 검색조건 토글 → 2개 필터(공장정보 / 제품 정보) 노출
• "제품Size와 공정명을 함께 기재하면 정보탐색의 정확도를 올릴 수 있습니다" 가이드 문구

3.2 결과 화면 (view: 'results')

• 좌 사이드바: 새 검색 / 검색 조건 설정 / 과거 세션 목록
• 메인 영역: 결과 카드 그리드 (1/2/3 columns 반응형, 최대 9개, "더보기" 토글로 6→9)
• 우 사이드바 (xl 이상): 파이프라인 진행률, 인사이트(Complexity / Strategy / Answerability), Top Results 리스트

3.3 상세 모달 (DetailModal)

• 좌 60% — 페이지 이미지 (4:3, 클릭 시 전체화면 확대), 페이지 네비게이션
• 우 40% — 검색 쿼리, 문서 제목, 선택 페이지 / 관련 페이지 버튼, AI 분석 요약 + 페이지 본문 발췌
• 시스템 링크(main_doc_link) / 다운로드 버튼

---

4. 검색 필터

기존 3개 필터(공장정보 / 제품 정보 / Document Type) 중 Document Type을 제거하고 2개로 축소.

4.1 공장정보 (apply_region)

실데이터 분포(doc_cate_2) 기반:

옵션	문서 수
전체	(필터 없음)
3공장	710
전사공통	376
2공장	349
2공장SiC	263
공장공통	244
1공장	138
청주공장	123
서울	1

4.2 제품 정보 (apply_product)

실데이터 분포(doc_cate_3) 기반:

옵션	문서 수
전체	(필터 없음)
300mm	686
지원부문	584
제품공통	486
200mm	286
150mm	162

"전체" 선택 시 해당 키는 filters dict에서 제외 → 백엔드에 무필터로 전달.

---

5. API 명세

5.1 POST /api/search (BFF)

요청:

{
  "query": "TTV 규격 기준",
  "region": "3공장",
  "product": "300mm",
  "topK": 10
}

응답 (PipelineResult):

{
  "results": [
    {
      "id": "I812-E8001-1_300mm 청주 EPI Auto Box Cleaning 작업 운전 지침서",
      "title": "300mm 청주 EPI Auto Box Cleaning 작업 운전 지침서",
      "summary": "...",
      "relevance": 87,
      "priority": "Standard",
      "type": "Both",
      "thumbnail": "/snap_data/I812-.../I812-..._3.jpg",
      "url": "https://mail.sksiltron.co.kr/...",
      "page": 3,
      "relatedPages": [3, 5, 12],
      "totalPages": 24,
      "docId": "I812-E8001-1_...",
      "applyRegion": "3공장",
      "applyProduct": "300mm",
      "deptName": "EPI기술1팀",
      "regDate": "2025-...",
      "pages": [{ "page": 3, "thumbnail": "...", "content": "..." }]
    }
  ],
  "meta": {
    "complexity": "Complex",
    "strategy": "Hybrid",
    "answerabilityScore": 0.83,
    "total": 9
  }
}

5.2 GET /snap_data/<rel-path>

페이지 스크린샷 정적 서빙. display_rel_path(예: I000-50001-0_출하차량 작업 지침/I000-50001-0_출하차량 작업 지침_5.jpg)를 그대로 사용.

---

6. 환경변수

변수	기본값	설명
PORT	3000	Express 서버 포트
QP_API_BASE	http://10.150.6.46:18504	FastAPI 베이스 URL
SNAP_DATA_DIR	<repo>/snap_data	페이지 이미지 정적 폴더 절대경로
SNAP_DATA_PUBLIC_BASE	/snap_data	클라이언트 노출 prefix
NODE_ENV	(없음)	production이면 dist/ 정적 서빙

---

7. 디렉토리 구조

q-pids/
├── server.ts                         # Express BFF (프록시 + snap_data 서빙)
├── vite.config.ts
├── package.json
├── index.html
├── src/
│   ├── App.tsx                       # 메인 React 컴포넌트
│   ├── main.tsx
│   ├── index.css                     # Tailwind v4 + 디자인 토큰
│   ├── types.ts                      # SearchResult / SearchMeta / SearchSession
│   └── services/
│       └── searchPipeline.ts         # FastAPI 클라이언트 + 응답 매퍼
└── README.md

상위 폴더의 snap_data/에는 <doc_id>_<문서명>/<doc_id>_<문서명>_<page>.jpg 형식으로 페이지별 스크린샷이 저장된다.

---

8. 실행

8.1 개발 모드

cd q-pids
npm install
npm run dev
# → http://localhost:3000

8.2 프로덕션 빌드

npm run build
NODE_ENV=production npm start

8.3 환경변수 예시 (실서버)

PORT=3000 \
QP_API_BASE=http://10.150.6.46:18504 \
SNAP_DATA_DIR=/data/qp/snap_data \
NODE_ENV=production \
node server.ts

---

9. 응답 매핑 규칙

FastAPI SearchResponse.doc_results[i] → 프런트 SearchResult 변환 (searchPipeline.ts 내 mapDocToResult):

백엔드 필드	프런트 필드	변환
doc_id	id, docId	그대로
doc_id (앞 ID 제거)	title	_ 이후 부분
pages[0].content[:220]	summary	content 있으면 우선
best_rerank_score 또는 best_score	relevance	× 100, 0~100 클램프
source	type	Text / Vision / Both
pages[*].display_rel_path	thumbnail	/snap_data/<encoded path>
main_doc_link	url	그대로
representative_page	page	fallback: pages 첫 항목
pages[*].page	relatedPages	페이지 번호 배열
page_count	totalPages	그대로
complexity	meta.complexity	"Low"→Simple, 그 외→Complex
query_type	meta.strategy	Text / Vision / Hybrid 그대로
answerability_score	meta.answerabilityScore	0~1

---

10. 디자인 시스템

색상 토큰 (Tailwind 사용자 지정)

• Primary: #E1251B (SK 레드)
• Primary Hover: #C01F18 / #B00020
• Surface: surface, surface-container-{low/lowest/high/highest}
• Text: on-surface, on-surface-variant, tertiary
• Outline: outline-variant

타이포그래피

• Headline: 굵은 헤드라인용 (font-headline font-black)
• Sans: 본문
• 한국어 + 영문 혼용, 영문은 uppercase + tracking-widest로 라벨화

모션

• motion/react(Motion One) 기반 등장/소실 애니메이션
• 카드 hover 시 scale-105 줌, 드롭다운 rotate-180 등

---

11. 향후 작업 (선택)

• FastAPI /search/stream SSE 연동 — 노드별 진행률 실시간 표시
• POST /search/doc-detail 연동 — 문서 카드 클릭 시 VLM 종합 답변 표시
• 세션 영속화 (현재는 메모리 보관, 새로고침 시 소실)
• 다운로드 버튼 → attach_link 직접 다운로드 처리
• 모바일 반응형 사이드바 토글
• 로그인 / 권한 기반 필터 자동 적용

---

12. 관련 문서

• 백엔드: qp_rag_pipeline.py
• API 예시: API_call_output_example.md, API_example.md
• 배포 가이드: DEPLOY_GUIDE.md
• CLAUDE 규칙: CLAUDE.md