# PHASE INDEX - Semantic Page Classification Layer

작성일: 2026-05-22

범위: `ontology_platform`의 `crawler_platform.app.core.crawler.page_classifier` 및 page classification과 직접 연결된 crawler/extractor 흐름.

기준 문서:
- `README.md`
- `docs/PHASE_PLANNING.md`
- `ontology_platform/README.md`
- `ontology_platform/docs/semantic_page_classification_codex_spec.md`

핵심 원칙:
- 기존 엔진을 폐기하거나 대규모로 교체하지 않는다.
- 기존 `classify_page(...) -> str` 호출부가 깨지지 않도록 legacy compatibility를 유지한다.
- 기존 `ProductPage`, `CategoryPage`, `SearchPage`, `BoardPage`, `BrandStoryPage`, `UnknownPage` 문자열은 alias 또는 compatibility mapping으로 유지한다.
- URL substring 중심 if-return 확장이 아니라 signal extraction -> evidence scoring -> classification result -> analyze strategy -> LLM policy 구조로 확장한다.
- protected page는 안전하게 skip하고, UnknownPage는 evidence와 confidence를 남긴다.
- pytest 또는 현재 프로젝트 테스트 명령으로 회귀 검증한다.

---

PHASE 1. 현재 흐름 기준선 고정 및 영향 범위 정리
FILE: ./26_05_22_semantic_page_classification/phase_01_001_current_flow_boundary.md

1) `page_classifier.py`의 현재 public API와 legacy page_type 문자열 목록 고정 [완료]
2) `should_analyze_page()` 호출부와 crawler의 `classify_page()` 호출 위치 문서화 [완료]
3) Extractor/HybridExtractor에서 page_type과 LLM skip 정책이 연결되는 흐름 정리 [완료]
4) 기존 page_type 문자열을 기대하는 테스트, config, adapter, ontology rule 경로 목록화 [완료]

---

PHASE 2. Taxonomy와 Classification Result 모델 추가
FILE: ./26_05_22_semantic_page_classification/phase_02_001_taxonomy_result_model.md

1) PageDomain/PageArchetype/PageType/EntityType/ActionIntent/GraphRole/AnalyzeStrategy/LLMPolicy 상수 또는 enum 추가 [완료]
2) `EvidenceItem`, `PageClassificationResult` dataclass 추가 [완료]
3) legacy alias 및 normalize helper 추가 [완료]
4) 기존 `classify_page()` 문자열 반환 호환을 유지하면서 semantic result API 추가 [완료]

---

PHASE 3. Raw Snapshot 및 Signal Extraction 레이어 추가
FILE: ./26_05_22_semantic_page_classification/phase_03_001_signal_extraction_layer.md

1) `RawPageSnapshot`와 `PageSignals` 모델 추가 [완료]
2) JSON-LD, OpenGraph, Twitter Card, meta, headings, links, forms, buttons, inputs 추출 [완료]
3) commerce/listing/editorial/community/docs/corporate/protected/system signal 추출 [완료]
4) HTML 일부가 깨지거나 필드가 누락되어도 예외 없이 빈 값으로 처리 [완료]

---

PHASE 4. Evidence Scoring 기반 Semantic Classification 구현
FILE: ./26_05_22_semantic_page_classification/phase_04_001_evidence_scoring_classifier.md

1) 주요 page type별 scoring function과 evidence recording 구조 추가 [완료]
2) 최소 20개 semantic page type 분류 구현 [완료]
3) confidence, alternatives, secondary_page_types 산출 [완료]
4) low confidence 또는 모호한 결과를 evidence 포함 UnknownPage로 처리 [완료]

---

PHASE 5. Analyze Strategy 및 LLM Policy 분리
FILE: ./26_05_22_semantic_page_classification/phase_05_001_analysis_llm_policy.md

1) PageClassificationResult 기반 `decide_analyze_strategy()` 추가 [TODO]
2) PageClassificationResult 기반 `decide_llm_policy()` 추가 [TODO]
3) `should_analyze_page(result_or_page_type, analyze_page_types=None)` compatibility 구현 [TODO]
4) Category/Search/Board 계열을 무조건 skip하지 않고 strategy 기반으로 처리 [TODO]
5) Login/Checkout/Payment/Captcha/AccessDenied 계열은 SkipProtected/Skip 정책으로 처리 [TODO]

---

PHASE 6. Crawler, Cleaner, Extractor, Discovery/Relevance 통합
FILE: ./26_05_22_semantic_page_classification/phase_06_001_pipeline_integration.md

1) `site_crawler.py`와 `pipeline.py` metadata에 semantic classification payload 저장 [TODO]
2) `ExtractionPageContext` 또는 metadata를 통해 analyze_strategy/llm_policy 전달 [TODO]
3) `HybridExtractor`가 LLMPolicy를 우선 사용하고 legacy page_type fallback을 유지하도록 수정 [TODO]
4) `page_cleaner.py`, `domain_discovery.py`, `relevance_engine.py`의 legacy page_type 기대 경로와 신규 semantic type을 호환 [TODO]

---

PHASE 7. Unknown Pattern 저장 기반 추가
FILE: ./26_05_22_semantic_page_classification/phase_07_001_unknown_pattern_storage.md

1) UnknownPage 또는 low confidence 페이지의 evidence payload 정의 [TODO]
2) text/html/link/schema/button/form summary와 fingerprint hook 추가 [TODO]
3) DB schema 변경 없이 metadata_json에 저장 가능한 초기 구조 구현 [TODO]
4) 향후 clustering/embedding 확장을 위한 hook만 추가하고 실제 clustering은 이번 범위에서 제외 [TODO]

---

PHASE 8. 테스트 Fixture 및 회귀 검증
FILE: ./26_05_22_semantic_page_classification/phase_08_001_tests_regression.md

1) 최소 10개 이상의 HTML fixture 추가 [TODO]
2) ProductDetailPage, CategoryListingPage, SearchResultsPage, ArticlePage, QAPage, FAQPage, ForumThreadPage, DocumentationPage, JobPostingPage, LoginPage, CheckoutPage, TermsPage, SitemapPage, UnknownPage 단위 테스트 추가 [TODO]
3) legacy `classify_page()`와 `should_analyze_page()` 호환성 테스트 추가 [TODO]
4) HybridExtractor LLMPolicy 회귀 테스트 추가 [TODO]
5) pytest 또는 현재 프로젝트 테스트 명령 실행 및 결과 기록 [TODO]