# 처리 주체 정리 문서

작성일: 2026-05-11
범위: "처리 주체"와 "연결 직후 처리 흐름"만 정리

## 1) 한 줄 요약
- 이 시스템은 **FastAPI 서버 내부에서 동기 처리**되며, 주체는 `API 라우트 -> SiteCrawler/Pipeline -> Extractor -> Repository(DB)` 순서다.
- LM Studio(Qwen)는 **외부 AI 추론 주체**이고, 크롤링 제어/저장은 백엔드가 담당한다.

## 2) 주체별 역할

### A. 프론트(UI) 주체
- 사용자 입력(config/source/url/provider/model/base_url) 수집
- API 호출 시작(`/extractors/models`, `/crawl`, `/crawl-site`)
- 파일: `crawler_platform/app/web/static/app.js`

### B. API 라우트 주체(FastAPI)
- 요청 검증 및 처리 경로 분기
- `/crawl-site`에서 `SiteCrawler` 생성 및 실행
- `/crawl`에서 `CrawlPipeline` 생성 및 실행
- 파일: `crawler_platform/app/api/routes.py`

### C. 크롤링 실행 주체
- `SiteCrawler`: 사이트 단위(queue 기반), 링크 확장, 페이지 분류, 분석 여부 판단
- `CrawlPipeline`: 단일 URL 단위 처리
- 파일:
  - `crawler_platform/app/core/crawler/site_crawler.py`
  - `crawler_platform/app/core/crawler/pipeline.py`

### D. 수집(Fetch) 주체
- `RequestsFetcher` 또는 `PlaywrightFetcher`
- robots.txt 검사: `RobotsPolicy`
- 파일: `crawler_platform/app/core/crawler/fetchers.py`

### E. 파싱 주체
- HTML 정리/텍스트 추출: `GenericProductParser -> clean_html`
- 파일:
  - `crawler_platform/app/core/crawler/plugins.py`
  - `crawler_platform/app/core/crawler/html_cleaner.py`

### F. 추출(엔티티/클레임 생성) 주체
- provider가 `lm_studio/openai/ollama`면 `LLMJsonExtractor`
- 아니면 domain 기반 rule-based extractor
- 파일:
  - `crawler_platform/app/core/extractor/factory.py`
  - `crawler_platform/app/core/extractor/ai_provider.py`
  - `crawler_platform/app/domains/perfume/extractor.py`

### G. 저장(DB) 주체
- `KnowledgeRepository`가 pages/entities/claims/evidence/extraction_logs 저장
- 중복은 upsert/hash로 병합됨
- 파일: `crawler_platform/app/core/database/repository.py`

### H. DB 세션/트랜잭션 주체
- `session_scope`에서 commit/rollback 책임
- 파일: `crawler_platform/app/core/database/session.py`

## 3) "처음 연결" 시 처리 주체

### 3-1. Analyzer 연결 테스트
- UI -> `/extractors/models`
- 백엔드 -> provider 모델 목록 조회 (`/v1/models`)
- 이 단계 주체: **API + 모델 목록 조회 함수**
- 이 단계에서 **크롤링/추출/DB 저장은 수행되지 않음**

관련 파일:
- `crawler_platform/app/web/static/app.js`
- `crawler_platform/app/api/routes.py`
- `crawler_platform/app/core/extractor/ai_provider.py`

## 4) "실제 처리" 시작 시 주체 체인
- UI `/crawl-site` 호출
- API 라우트가 `SiteCrawler` 실행
- Fetcher가 페이지 수집, Parser가 텍스트화
- Extractor(LLM 또는 룰기반)가 엔티티/클레임 생성
- Repository가 DB 저장

즉 최종 책임:
- **제어 책임**: FastAPI + SiteCrawler
- **AI 생성 책임**: LM Studio(Qwen) 또는 OpenAI/Ollama
- **저장 책임**: KnowledgeRepository