docs: README.md 갱신 — 프로젝트 구조, 기능, API, 스택 정보 반영

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -1,39 +1,142 @@
-# web-inspector
+# Web Inspector
 
-## Overview
-프로젝트 설명을 여기에 작성하세요.
+웹 페이지 및 사이트 품질 검사 도구. 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
-- **Template**: fullstack
-- **Stack**: Next.js + FastAPI + MongoDB + Redis
-- **Created**: 2026-02-12
+
+| 구분 | 기술 |
+|------|------|
+| 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 up -d
 
 # 서비스 로그
-docker-compose logs -f
+docker compose logs -f
 
-# 서비스 중지
-docker-compose down
+# 빌드 후 시작
+docker compose build --no-cache && docker compose up -d
 ```
 
-## Project Structure
+## API Endpoints
+
+### 단일 검사
 ```
-web-inspector/
-├── backend/           # FastAPI 백엔드
-│   ├── app/
-│   │   └── main.py    # 엔트리포인트
-│   ├── Dockerfile
-│   └── requirements.txt
-├── frontend/          # Next.js 프론트엔드
-├── docker-compose.yml
-├── .env
-└── CLAUDE.md
+POST   /api/inspections                    # 검사 시작
+GET    /api/inspections/{id}               # 결과 조회
+GET    /api/inspections/{id}/stream        # SSE 스트림
+GET    /api/inspections                    # 이력 (페이지네이션)
 ```
 
-## Git
-- **Gitea**: http://gitea.yakenator.io/yakenator/web-inspector
+### 사이트 크롤링
+```
+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 리버스 프록시 + Let's Encrypt 와일드카드 SSL