yakenator/web-inspector
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
web-inspector/PLAN.md
jungwoo choi b5fa5d96b9 feat: 웹사이트 표준화 검사 도구 구현 
- 4개 검사 엔진: HTML/CSS, 접근성(WCAG), SEO, 성능/보안 (총 50개 항목)
- FastAPI 백엔드 (9개 API, SSE 실시간 진행, PDF/JSON 리포트)
- Next.js 15 프론트엔드 (6개 페이지, 29개 컴포넌트, 반원 게이지 차트)
- Docker Compose 배포 (Backend:8011, Frontend:3011, MongoDB:27022, Redis:6392)
- 전체 테스트 32/32 PASS

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 13:57:27 +09:00

11 KiB
Raw Permalink Blame History

Web Inspector - 리서치 및 전략 기획안

Executive Summary (핵심 요약)

  • 웹 표준 검사 시장은 Google Lighthouse, W3C Validator, WAVE, PageSpeed Insights 등이 각각 개별 영역을 커버하지만, 4개 카테고리(HTML/CSS, 접근성, SEO, 성능/보안)를 통합 검사하는 올인원 오픈소스 솔루션은 부재
  • Python 생태계에 검사 엔진별 라이브러리(py_w3c, axe-selenium-python, BeautifulSoup, securityheaders)가 충분히 성숙하여 자체 검사 엔진 구축이 현실적
  • **FastAPI SSE(Server-Sent Events)**를 활용한 실시간 진행 상태 스트리밍이 기술적으로 안정적이며, sse-starlette 라이브러리가 프로덕션 수준
  • MongoDB + Redis 조합으로 검사 결과 영구 저장 + 캐싱/실시간 상태 관리를 효과적으로 분리 가능

1. 리서치 개요

연구 배경 및 목적

웹사이트 품질 검사는 개발/운영의 필수 단계이나, 현재 도구들은 특정 영역에 특화되어 있어 종합적인 검사를 위해 여러 서비스를 개별 이용해야 하는 불편함이 존재한다. Web Inspector는 URL 하나로 4개 핵심 카테고리를 동시 검사하고, 통합 리포트를 제공하는 올인원 웹 표준 검사 도구이다.

리서치 차원

  • 차원 A: 시장/경쟁 분석 (기존 도구 비교, 차별화 포인트)
  • 차원 B: 기술/구현 가능성 (Python 라이브러리, 검사 엔진 아키텍처)
  • 차원 C: 사용자 경험/UI (대시보드, 리포트, 실시간 피드백)

방법론

3개 관점 병렬 리서치 -> 교차 평가 -> 종합

2. 관점별 리서치 결과

2.1 시장/경쟁 분석

기존 서비스 비교

서비스 HTML/CSS 접근성 SEO 성능/보안 통합 리포트 이력 관리
Google Lighthouse - O (일부) O O (성능) O -
W3C Validator O - - - - -
WAVE - O - - O -
PageSpeed Insights - - O (일부) O O -
Total Validator O O - - O -
SortSite O O O - O O (유료)
Web Inspector (우리) O O O O O O

핵심 발견

  1. 통합 검사 도구 부재: 4개 카테고리를 모두 커버하는 무료/오픈소스 도구가 없음
  2. 이력 관리 기능 희소: 대부분 일회성 검사만 제공, 시계열 트렌드 비교는 유료 서비스에서만 제한적 제공
  3. 리포트 내보내기 한계: JSON 출력은 보편적이나, PDF 리포트 생성은 프리미엄 기능으로 분류
  4. 한국어 지원 부족: 대부분 영문 서비스로, 한국어 UI/리포트 제공 도구 부재

차별화 포인트

  • 4개 카테고리 동시 검사 (병렬 처리)
  • 검사 이력 저장 + 트렌드 비교 차트
  • PDF/JSON 이중 리포트 내보내기
  • 실시간 진행 상태 SSE 스트리밍
  • 한국어 우선 UI

2.2 기술/구현 가능성 분석

검사 엔진별 기술 스택

카테고리 핵심 라이브러리 용도 성숙도
HTML/CSS 표준 py_w3c, html5validator W3C API 호출 높음
HTML/CSS 표준 BeautifulSoup4, html5lib 로컬 파싱/시맨틱 분석 매우 높음
접근성 (WCAG) axe-selenium-python axe-core 엔진 (Selenium 통합) 높음
접근성 (WCAG) Playwright + axe-core JS 헤드리스 브라우저 기반 높음
SEO BeautifulSoup4, lxml meta/OG 태그 파싱 매우 높음
SEO httpx/aiohttp robots.txt, sitemap 크롤링 매우 높음
성능 Lighthouse CLI / API 성능 메트릭 수집 매우 높음
보안 헤더 securityheaders, httpx CSP/HSTS/XFO 분석 높음

실시간 스트리밍 기술

  • SSE (Server-Sent Events) 채택 (WebSocket 대비 단순, HTTP 호환)
  • sse-starlette 라이브러리: FastAPI/Starlette 네이티브 지원, W3C SSE 규격 준수
  • 검사 4개 카테고리의 진행률(0~100%)을 개별 스트리밍

PDF 리포트 생성

  • WeasyPrint 채택: HTML/CSS -> PDF 변환, Python 네이티브, 디자인 자유도 높음
  • Jinja2 템플릿 + Tailwind CSS -> WeasyPrint -> PDF

기술적 리스크

  1. axe-core 실행 환경: Selenium/Playwright 필요 (헤드리스 브라우저)
    • 대응: Docker 환경에서 Playwright + Chromium 사전 설치
  2. W3C Validator API 속도 제한: 외부 API 의존
    • 대응: vnu.jar (W3C 로컬 검증기) 내장 옵션 준비
  3. 대형 사이트 검사 타임아웃
    • 대응: 검사 타임아웃 설정 (기본 60초), 페이지 단위 검사로 범위 제한

2.3 사용자 경험/UI 분석

사용자 워크플로우

URL 입력 -> 검사 시작 -> 실시간 진행 표시 -> 결과 대시보드 -> 상세 이슈 확인 -> 리포트 내보내기
                                                      |
                                                      v
                                              이력 저장 -> 트렌드 비교

UI 핵심 요소

  1. URL 입력 화면: 심플한 단일 입력 필드 + 검사 시작 버튼
  2. 실시간 진행 화면: 4개 카테고리별 프로그레스 바 + 현재 검사 단계 텍스트
  3. 결과 대시보드: 종합 점수 (도넛 차트) + 4개 카테고리 개별 점수 (레이더 차트)
  4. 상세 이슈 목록: 심각도별 필터링 (Critical/Major/Minor/Info)
  5. 이력 페이지: 검사 이력 테이블 + 트렌드 라인 차트
  6. 리포트 내보내기: PDF/JSON 다운로드 버튼

참고 서비스 UX 분석

  • Lighthouse: 원형 게이지 점수 표시가 직관적 -> 채택
  • WAVE: 이슈를 페이지 위에 오버레이로 표시 -> 참고만 (구현 복잡)
  • PageSpeed Insights: 카테고리별 점수 + 개선 제안이 명확 -> 채택

3. 교차 평가 결과

3.1 합의점 (모든 관점이 동의)

  1. 4개 카테고리 통합 검사가 명확한 시장 차별점
  2. SSE 기반 실시간 진행 표시가 UX 핵심 (WebSocket은 과잉)
  3. BeautifulSoup + httpx 기반 로컬 검사가 외부 API 의존보다 안정적
  4. MongoDB의 유연한 스키마가 다양한 검사 결과 저장에 적합

3.2 논쟁점 (관점 간 충돌 및 결론)

  1. 접근성 검사 엔진: Selenium 기반 vs Playwright 기반
    • 결론: Playwright 채택 (더 빠르고, async 지원, Docker 친화적)
  2. W3C 검증: 외부 API vs 로컬 vnu.jar
    • 결론: 1차 로컬(html5lib 기반 파싱), 2차 옵션으로 W3C API 제공

3.3 보완점 (교차 평가에서 추가 발견)

  1. 구조화 데이터 검사 (Schema.org) 추가 가능 -> SEO 카테고리에 포함
  2. Core Web Vitals (LCP, FID, CLS) 메트릭 -> 성능 카테고리 핵심 지표로 승격
  3. 검사 결과 캐싱: 동일 URL 재검사 시 최근 결과 비교 표시

4. 종합 인사이트

데이터 기반 핵심 결론

  • 기술적으로 Python 생태계만으로 4개 카테고리 검사 엔진 구축이 충분히 가능
  • Playwright 헤드리스 브라우저가 접근성 + 성능 검사의 핵심 인프라
  • SSE + Redis Pub/Sub로 실시간 진행 상태를 효율적으로 스트리밍 가능
  • WeasyPrint로 전문적인 PDF 리포트 생성 가능

기회 영역

  • 한국어 웹 표준 검사 도구 시장 선점
  • 검사 이력 + 트렌드 비교 기능으로 지속적 모니터링 유스케이스 확보
  • 추후 API 공개로 CI/CD 파이프라인 통합 가능

리스크 요인

  • Playwright + Chromium Docker 이미지 크기 (약 1GB)
  • 외부 사이트 크롤링 시 robots.txt 준수 및 속도 제한 필요
  • 대규모 사이트 검사 시 리소스 소모 관리

5. 전략 기획

핵심 전략 방향

"URL 하나로 웹사이트 건강 진단" - 4개 카테고리 동시 검사 + 실시간 피드백 + 이력 관리

MVP 기능 범위 (Phase 1)

우선순위 기능 설명
Must URL 입력 및 검사 시작 단일 URL 입력 -> 4개 카테고리 동시 검사
Must HTML/CSS 표준 검사 HTML5 문법, 시맨틱 태그, CSS 유효성
Must 접근성(WCAG) 검사 WCAG 2.1 AA 기준, axe-core 기반
Must SEO 검사 meta/OG 태그, robots.txt, sitemap, 구조화 데이터
Must 성능/보안 검사 보안 헤더, HTTPS, 기본 성능 메트릭
Must 실시간 진행 상태 SSE 기반 4개 카테고리 진행률 스트리밍
Must 결과 대시보드 종합 점수 + 카테고리별 점수 + 이슈 목록
Should 검사 이력 저장 MongoDB에 결과 저장, 이력 목록 조회
Should 트렌드 비교 동일 URL 검사 이력 시계열 차트
Should PDF 리포트 내보내기 WeasyPrint 기반 PDF 생성/다운로드
Should JSON 리포트 내보내기 검사 결과 JSON 다운로드
Could 다크 모드 UI 테마 전환
Could 검사 설정 커스터마이징 카테고리별 검사 항목 on/off

기술 스택 확정

영역 기술 선택 근거
Frontend Next.js 15 (App Router) + TypeScript 프로젝트 표준 스택
UI 컴포넌트 shadcn/ui + Tailwind CSS 프로젝트 표준 스택
차트 Recharts React 친화적, 가벼움
Backend FastAPI + Python 3.11 프로젝트 표준 스택, async 네이티브
실시간 SSE (sse-starlette) 단방향 스트리밍에 최적
DB MongoDB 7.0 (Motor) 유연한 스키마, 검사 결과 저장
Cache Redis 7 검사 상태 관리, 캐싱
HTML 파싱 BeautifulSoup4 + html5lib HTML 구조 분석
접근성 검사 Playwright + axe-core 헤드리스 브라우저 기반 WCAG 검사
HTTP 클라이언트 httpx (async) 비동기 HTTP 요청
보안 헤더 자체 구현 (httpx) 간단한 헤더 분석
PDF 생성 WeasyPrint HTML -> PDF 변환
컨테이너 Docker Compose 프로젝트 표준 배포

타임라인 (예상)

Phase 내용 에이전트
Phase 1 리서치 & 기획 research-planner
Phase 2 아키텍처 설계 system-architect
Phase 3 백엔드 + 프론트엔드 구현 (병렬) backend-dev + frontend-dev
Phase 4 시스템 테스트 system-tester
Phase 5 Docker 배포 devops-deployer

6. 예상 성과 및 리스크

기대 효과

  • 단일 URL로 4개 영역 종합 검사 -> 개발자 생산성 향상
  • 검사 이력 + 트렌드로 웹사이트 품질 지속 모니터링 가능
  • PDF 리포트로 이해관계자 공유 용이

잠재 리스크 및 대응방안

리스크 영향 대응방안
Playwright Docker 이미지 크기 배포 시간 증가 멀티스테이지 빌드, 경량 이미지 사용
외부 사이트 접근 차단 검사 실패 타임아웃 처리, 에러 메시지 명확화
대형 페이지 메모리 소모 서버 불안정 HTML 크기 제한 (10MB), 타임아웃 (60초)
W3C API 속도 제한 검사 지연 로컬 파싱 우선, API는 선택적

7. Next Steps

즉시 실행 항목

  1. ARCHITECTURE.md 작성 (시스템 아키텍처 설계)
  2. DB_SCHEMA.md 작성 (MongoDB 컬렉션 설계)
  3. 백엔드/프론트엔드 구현 시작

추가 검토 필요 사항

  • Playwright Docker 이미지 최적화 전략
  • 외부 사이트 크롤링 시 법적/윤리적 고려사항
  • 향후 API 공개 시 인증/과금 체계