# Web Inspector

웹 페이지 및 사이트 품질 검사 도구. HTML/CSS, 접근성, SEO, 성능/보안 4개 카테고리 기준으로 웹 페이지를 분석하고 점수와 개선 사항을 제공한다.

## 주요 기능

### 3가지 검사 모드
| 모드 | 설명 |
|------|------|
| **한 페이지 검사** | 단일 URL 입력 → AI 기반 품질 분석 → 점수/등급/이슈 리포트 |
| **사이트 크롤링** | 루트 URL 입력 → BFS 크롤링으로 페이지 자동 발견 → 전체 사이트 일괄 검사 |
| **목록 업로드** | .txt 파일로 URL 목록 업로드 → 일괄 검사 |

### 검사 카테고리 (4개)
- **HTML/CSS** — 마크업 품질, 시맨틱 태그, CSS 모범 사례
- **접근성 (Accessibility)** — WCAG 가이드라인 준수, ARIA, 키보드 접근성
- **SEO** — 메타태그, 구조화 데이터, 크롤러 친화성
- **성능/보안** — 로딩 속도, HTTPS, CSP 헤더 등

### 실시간 진행 상태
- SSE (Server-Sent Events) + Redis Pub/Sub로 크롤링/검사 진행 상태 실시간 스트리밍
- 페이지별 검사 상태(대기→검사 중→완료) 실시간 업데이트

### 크롤러 특징
- BFS 기반 동일 도메인 링크 탐색
- URL 정규화: fragment 제거, trailing slash 제거, www. 제거, scheme/netloc 소문자화
- 리다이렉트 추적 → 최종 URL 기준 중복 제거
- 쿼리 파라미터가 다르면 유니크 URL로 판단
- max_pages는 유니크 URL 기준 카운트

## Tech Stack

| 구분 | 기술 |
|------|------|
| Frontend | Next.js 15 (App Router), TypeScript, TailwindCSS, shadcn/ui |
| State | Zustand, TanStack React Query |
| Backend | FastAPI (Python 3.11), Pydantic v2 |
| Database | MongoDB 7.0 (Motor async driver) |
| Cache/PubSub | Redis 7 |
| AI | Claude API (검사 분석) |
| Infra | Docker Compose, Nginx (리버스 프록시 + SSL) |

## Project Structure

```
web-inspector/
├── backend/
│   └── app/
│       ├── main.py                    # FastAPI 엔트리포인트
│       ├── core/
│       │   ├── config.py              # 환경변수 설정
│       │   └── database.py            # MongoDB + Redis 연결
│       ├── models/
│       │   ├── schemas.py             # 단일 검사 스키마
│       │   ├── site_schemas.py        # 사이트 크롤링 스키마
│       │   └── batch_schemas.py       # 배치 검사 스키마
│       ├── routers/
│       │   ├── inspections.py         # 단일 검사 API
│       │   ├── site_inspections.py    # 사이트 크롤링 API
│       │   ├── batch_inspections.py   # 배치 검사 API
│       │   ├── reports.py             # 리포트 API
│       │   └── health.py              # 헬스체크
│       └── services/
│           ├── inspection_service.py        # 단일 검사 서비스
│           ├── site_inspection_service.py   # 사이트 크롤링 + 검사
│           ├── batch_inspection_service.py  # 배치 검사 서비스
│           ├── link_crawler.py              # BFS 크롤러
│           └── report_service.py            # 리포트 생성
├── frontend/
│   └── src/
│       ├── app/
│       │   ├── page.tsx                           # 홈 (탭 UI)
│       │   ├── history/page.tsx                   # 이력 (탭별)
│       │   ├── inspections/[id]/page.tsx           # 단일 검사 결과
│       │   ├── inspections/[id]/progress/page.tsx  # 단일 검사 진행
│       │   ├── site-inspections/[id]/page.tsx      # 사이트 검사 결과
│       │   ├── site-inspections/[id]/progress/     # 사이트 검사 진행
│       │   └── batch-inspections/[id]/             # 배치 검사 결과/진행
│       ├── components/
│       │   ├── inspection/          # 탭 UI, 폼 컴포넌트
│       │   ├── site-inspection/     # 페이지 트리, 진행 상태
│       │   ├── batch-inspection/    # 배치 URL 목록, 진행
│       │   ├── dashboard/           # 점수 대시보드, 이슈 목록
│       │   └── history/             # 이력 테이블
│       ├── stores/                  # Zustand 스토어
│       ├── hooks/                   # SSE 훅, React Query 훅
│       ├── lib/                     # API 클라이언트, 유틸리티
│       └── types/                   # TypeScript 타입 정의
├── nginx/
│   └── nginx.conf                   # 리버스 프록시 + SSE 설정
├── docker-compose.yml
└── .env
```

## Getting Started

```bash
# 환경변수 설정
cp .env.example .env
# ANTHROPIC_API_KEY 설정 필요

# 서비스 시작
docker compose up -d

# 서비스 로그
docker compose logs -f

# 빌드 후 시작
docker compose build --no-cache && docker compose up -d
```

## API Endpoints

### 단일 검사
```
POST   /api/inspections                    # 검사 시작
GET    /api/inspections/{id}               # 결과 조회
GET    /api/inspections/{id}/stream        # SSE 스트림
GET    /api/inspections                    # 이력 (페이지네이션)
```

### 사이트 크롤링
```
POST   /api/site-inspections               # 크롤링 + 검사 시작
GET    /api/site-inspections/{id}          # 결과 조회
GET    /api/site-inspections/{id}/stream   # SSE 스트림
GET    /api/site-inspections               # 이력 (페이지네이션)
```

### 배치 검사
```
POST   /api/batch-inspections              # 파일 업로드 + 검사 시작
GET    /api/batch-inspections/{id}         # 결과 조회
GET    /api/batch-inspections/{id}/stream  # SSE 스트림
GET    /api/batch-inspections              # 이력 (페이지네이션)
```

## Deployment

- **URL**: https://web-inspector.yakenator.io
- **Gitea**: https://gitea.yakenator.io/yakenator/web-inspector
- **Server**: Nginx 리버스 프록시 + Namecheap 와일드카드 SSL