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
parent c37cda5b13
commit b5fa5d96b9
93 changed files with 18735 additions and 22 deletions
--- a/SCREEN_DESIGN.md
+++ b/SCREEN_DESIGN.md
@ -0,0 +1,294 @@
+# Web Inspector — 화면설계서
+
+> 자동 생성: `pptx_to_md.py` | 원본: `SCREEN_DESIGN.pptx`
+> 생성 시각: 2026-02-12 16:21
+> **이 파일을 직접 수정하지 마세요. PPTX를 수정 후 스크립트를 재실행하세요.**
+
+## 페이지 목록
+
+| ID | 페이지명 | 경로 | 설명 |
+|-----|---------|------|------|
+| P-001 | 메인 페이지 (URL 입력) | `/` | URL 입력 폼 + 최근 검사 이력 요약 |
+| P-002 | 검사 진행 페이지 | `/inspections/{id}/progress` | 실시간 SSE 기반 4개 카테고리 프로그레스 표시 |
+| P-003 | 검사 결과 대시보드 | `/inspections/{id}` | 종합 점수 게이지 + 카테고리별 점수 카드 + 이슈 요약 |
+| P-004 | 상세 이슈 페이지 | `/inspections/{id}/issues` | 카테고리/심각도 필터 + 이슈 카드 목록 |
+| P-005 | 검사 이력 페이지 | `/history` | 검사 이력 테이블 + URL 검색 + 페이지네이션 |
+| P-006 | 트렌드 비교 페이지 | `/history/trend?url=...` | 동일 URL 시계열 라인 차트 + 점수 비교 |
+
+---
+
+## P-001: 메인 페이지 (`/`)
+
+### 레이아웃
+
+Web Inspector
+[검사 이력]    [트렌드]
+웹사이트 표준 검사
+URL을 입력하면 HTML/CSS, 접근성, SEO, 성능/보안을 한 번에 검사합니다
+https://example.com
+검사 시작
+최근 검사 이력
+example1.com  점수: 85점 (A)  2026-02-12
+example2.com  점수: 75점 (B)  2026-02-11
+example3.com  점수: 65점 (B)  2026-02-10
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `HeroSection` | title, subtitle | default |
+| `UrlInputForm` | onSubmit, placeholder | default, loading, error |
+| `RecentInspections` | inspections, onItemClick | loading, empty, data |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| URL 입력 후 검사 시작 버튼 클릭 | `POST /api/inspections {url}` | 검사 시작, /inspections/{id}/progress 페이지로 이동 |
+| URL 입력 필드에서 Enter 키 | `POST /api/inspections {url}` | 검사 시작, /inspections/{id}/progress 페이지로 이동 |
+| 유효하지 않은 URL 입력 | `클라이언트 검증` | 입력 필드 아래 에러 메시지 표시 |
+| 최근 검사 카드 클릭 | `navigate` | /inspections/{id} 결과 페이지로 이동 |
+| 검사 이력 네비 클릭 | `navigate` | /history 페이지로 이동 |
+
+### 반응형: sm, md, lg
+
+---
+
+## P-002: 검사 진행 페이지 (`/inspections/{id}/progress`)
+
+### 레이아웃
+
+Web Inspector
+검사 중: https://example.com
+전체 진행률: 45%
+HTML/CSS 표준
+완료
+100%
+접근성 (WCAG)
+색상 대비 검사 중...
+60%
+SEO 최적화
+robots.txt 확인 중...
+30%
+성능/보안
+대기 중
+0%
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `InspectionProgress` | inspectionId, url | connecting, running, completed, error |
+| `OverallProgressBar` | progress | running, completed |
+| `CategoryProgressCard` | categoryName, status, progress, currentStep | pending, running, completed, error |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| 페이지 로드 | `SSE 연결 GET /api/inspections/{id}/stream` | 실시간 진행 상태 수신 시작 |
+| SSE progress 이벤트 수신 | `상태 업데이트` | 해당 카테고리 프로그레스 바 + 단계 텍스트 업데이트 |
+| SSE category_complete 이벤트 수신 | `카테고리 완료 표시` | 해당 카테고리 초록색 완료 + 점수 표시 |
+| SSE complete 이벤트 수신 | `navigate` | /inspections/{id} 결과 페이지로 자동 이동 |
+| SSE error 이벤트 수신 | `에러 표시` | 에러 메시지 표시 + 재검사 버튼 표시 |
+
+### 반응형: sm, md, lg
+
+---
+
+## P-003: 검사 결과 대시보드 (`/inspections/{id}`)
+
+### 레이아웃
+
+Web Inspector
+종합 점수
+76
+등급: B
+HTML/CSS 표준
+85
+A
+이슈 5건
+접근성
+72
+B
+이슈 8건
+SEO
+68
+C
+이슈 6건
+성능/보안
+78
+B
+이슈 4건
+검사 일시: 2026-02-12 10:00  |  소요 시간: 35초
+이슈 상세
+PDF 리포트
+JSON 내보내기
+Critical: 2    Major: 9    Minor: 8    Info: 4    |    총 23건
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `OverallScoreGauge` | score, grade | default |
+| `CategoryScoreCard` | categoryName, score, grade, issueCount | default |
+| `IssueSummaryBar` | critical, major, minor, info, total | default |
+| `InspectionMeta` | url, createdAt, duration | default |
+| `ActionButtons` | onViewIssues, onExportPdf, onExportJson | default, exporting |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| 카테고리 점수 카드 클릭 | `navigate` | /inspections/{id}/issues?category={category} 이슈 페이지로 이동 |
+| 이슈 상세 버튼 클릭 | `navigate` | /inspections/{id}/issues 이슈 페이지로 이동 |
+| PDF 리포트 버튼 클릭 | `GET /api/inspections/{id}/report/pdf` | PDF 파일 다운로드 시작 |
+| JSON 내보내기 버튼 클릭 | `GET /api/inspections/{id}/report/json` | JSON 파일 다운로드 시작 |
+| 재검사 버튼 클릭 | `POST /api/inspections {url}` | 새 검사 시작, 진행 페이지로 이동 |
+
+### 반응형: sm, md, lg
+
+---
+
+## P-004: 상세 이슈 페이지 (`/inspections/{id}/issues`)
+
+### 레이아웃
+
+Web Inspector
+필터:
+전체
+HTML/CSS
+접근성
+SEO
+성능/보안
+전체
+Cri
+Maj
+Min
+Inf
+Critical
+H-07
+중복 ID 발견: 'main-content'
+요소: <div id="main-content">
+개선: 각 요소에 고유한 ID를 부여하세요
+Major
+A-02
+텍스트-배경 색상 대비 부족 (2.3:1)
+요소: <p class="light-text">
+개선: 대비율 4.5:1 이상으로 조정하세요
+Major
+S-04
+Open Graph 태그 누락: og:image
+개선: <meta property="og:image"> 추가
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `FilterBar` | categories, severities, selectedCategory, selectedSeverity, onChange | default |
+| `IssueCard` | code, severity, message, element, line, suggestion | default, expanded |
+| `IssueList` | issues, filters | loading, empty, data |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| 카테고리 필터 클릭 | `필터 적용` | 선택 카테고리의 이슈만 표시 |
+| 심각도 필터 클릭 | `필터 적용` | 선택 심각도의 이슈만 표시 |
+| 이슈 카드 클릭 | `토글 확장` | 이슈 상세 정보 확장/축소 |
+| 뒤로가기/대시보드 링크 클릭 | `navigate` | /inspections/{id} 결과 대시보드로 이동 |
+
+### 반응형: sm, md, lg
+
+---
+
+## P-005: 검사 이력 페이지 (`/history`)
+
+### 레이아웃
+
+Web Inspector
+URL 검색...
+검색
+<  1  2  3  ...  10  >
+
+| URL | 검사 일시 | 종합 점수 | 등급 | 이슈 수 | 액션 |
+| --- | --- | --- | --- | --- | --- |
+| https://example1.com | 2026-02-12 10:00 | 85 | A | 12 | [보기] [트렌드] |
+| https://example2.com | 2026-02-11 14:30 | 72 | B | 18 | [보기] [트렌드] |
+| https://example1.com | 2026-02-10 09:15 | 78 | B | 15 | [보기] [트렌드] |
+| https://example3.com | 2026-02-09 16:45 | 65 | C | 22 | [보기] [트렌드] |
+| https://example2.com | 2026-02-08 11:20 | 68 | C | 20 | [보기] [트렌드] |
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `SearchBar` | query, onSearch, placeholder | default, searching |
+| `InspectionHistoryTable` | inspections, page, totalPages, onPageChange, onRowClick | loading, empty, data |
+| `Pagination` | currentPage, totalPages, onPageChange | default |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| URL 검색 입력 후 검색 버튼 클릭 | `GET /api/inspections?url={query}` | 필터링된 이력 목록 표시 |
+| 테이블 행 클릭 | `navigate` | /inspections/{id} 결과 페이지로 이동 |
+| 트렌드 버튼 클릭 | `navigate` | /history/trend?url={url} 트렌드 페이지로 이동 |
+| 페이지네이션 번호 클릭 | `GET /api/inspections?page={n}` | 해당 페이지의 이력 표시 |
+
+### 반응형: sm, md, lg
+
+---
+
+## P-006: 트렌드 비교 페이지 (`/history/trend?url=...`)
+
+### 레이아웃
+
+Web Inspector
+트렌드: https://example.com
+점수 추이 차트
+100
+80
+60
+40
+20
+0
+종합
+HTML/CSS
+접근성
+SEO
+성능/보안
+02-01
+02-03
+02-05
+02-07
+02-09
+02-11
+최근 vs 이전 검사 비교
+종합: 78 -> 82 (+4)  |  HTML/CSS: 80 -> 85 (+5)  |  접근성: 65 -> 72 (+7)
+
+### 컴포넌트
+
+| 컴포넌트 | Props | 상태 |
+|---------|-------|------|
+| `Header` | logo, navItems | default |
+| `TrendChart` | dataPoints, categories | loading, empty, data, error |
+| `ChartLegend` | categories, colors, onToggle | default |
+| `ComparisonSummary` | latestResult, previousResult | default, noComparison |
+
+### 인터랙션
+
+| 트리거 | 동작 | 결과 |
+|--------|------|------|
+| 페이지 로드 | `GET /api/inspections/trend?url={url}` | 트렌드 데이터 로드 및 차트 렌더링 |
+| 범례 항목 클릭 | `차트 라인 토글` | 해당 카테고리 라인 표시/숨김 |
+| 차트 데이터 포인트 호버 | `툴팁 표시` | 해당 시점의 상세 점수 표시 |
+| 차트 데이터 포인트 클릭 | `navigate` | /inspections/{id} 해당 검사 결과 페이지로 이동 |
+| 검사 결과 1건만 있을 때 | `빈 상태 표시` | "비교할 이력이 없습니다" 메시지 + 재검사 버튼 |
+
+### 반응형: sm, md, lg