yakenator/web-inspector
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
web-inspector/SCREEN_DESIGN.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

295 lines
9.3 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
Reference in New Issue View Git Blame Copy Permalink