풀스택 URL 단축 서비스 구축

## 🚀 URL 단축 서비스 - 풀스택 애플리케이션 ### 📋 프로젝트 개요 현대적이고 접근성이 뛰어난 프론트엔드와 강력한 RESTful 백엔드 API를 갖춘 프로덕션 레디 URL 단축 서비스를 구축합니다. 애플리케이션은 단축 링크의 전체 수명 주기(생성, 리디렉션, 추적, 관리, 만료)를 처리해야 합니다. 모든 디바이스에서 성능, 보안, 탁월한 사용자 경험을 최우선으로 합니다. --- ### 🛠️ 기술 스택 **프론트엔드:** - 접근성을 위한 ARIA 속성을 갖춘 시맨틱 HTML5 (WCAG 2.1 AA 준수) - CSS 커스텀 속성(변수), Flexbox, CSS Grid를 사용한 CSS3 - 모듈형 아키텍처(ES 모듈)를 사용한 바닐라 JavaScript (ES2022+) - 무거운 프레임워크 없음 - 번들을 가볍고 빠르게 유지 **백엔드 API:** - OpenAPI 3.0 사양을 따르는 RESTful API 설계 - 적절한 HTTP 상태 코드를 사용한 JSON 요청/응답 형식 - 교차 출처 요청을 위한 CORS 설정 - IP 및 API 키별 속도 제한 **라이브러리 (CDN 또는 번들):** - QR 코드 생성 (예: `qrcode.js` 또는 `qr-creator`) - 분석용 차트 라이브러리 (예: Chart.js 또는 경량 대안) - 만료 날짜 선택기 (예: `flatpickr`) - 토스트 알림 시스템 (커스텀 빌드, 의존성 없음) --- ### 🎨 프론트엔드 - UI/UX 요구사항 **레이아웃 및 디자인:** - 페이지 중앙에 **크고 눈에 띄는 URL 입력 필드**가 있는 히어로 섹션을 갖춘 깔끔하고 미니멀한 디자인 - 시스템 환경 설정 감지(`prefers-color-scheme`)와 `localStorage` 영속성을 갖춘 **다크/라이트 모드 토글** 구현 - 일관된 디자인 시스템 사용: 타이포그래피 스케일, 간격 토큰, 색상 팔레트 - 모든 인터랙티브 요소에 부드러운 마이크로 애니메이션 및 전환(페이드인, 슬라이드업, 버튼 리플) - 비동기 콘텐츠(분석, 기록 테이블)를 위한 스켈레톤 로딩 상태 **반응형 디자인:** - 480px, 768px, 1024px, 1440px 중단점을 사용한 모바일 우선 접근 방식 - 터치 친화적인 탭 대상 (최소 44×44px) - 모바일에서 접이식 내비게이션 메뉴 (애니메이션이 있는 햄버거 메뉴) - `clamp()`를 사용한 유동적 타이포그래피 **접근성:** - 전체 키보드 내비게이션 지원 (탭 순서, 모달 내 포커스 트래핑) - 동적 콘텐츠에 대한 화면 리더 알림 (`aria-live` 영역) - 모든 인터랙티브 요소에 보이는 포커스 표시기 - 충분한 색상 대비 비율 (텍스트의 경우 최소 4.5:1) - 동작 감소 지원 (`prefers-reduced-motion`) --- ### ⚙️ 핵심 기능 #### 1. URL 단축 엔진 - 플레이스홀더 텍스트와 실시간 유효성 검사 피드백이 있는 눈에 띄는 입력 필드 - **URL 유효성 검사**: 유효한 프로토콜(`http://`, `https://`) 확인, 올바른 도메인 구조 확인, 정규식과 `URL` 생성자 API를 모두 사용하여 잘못된 URL 거부 - **URL 정리**: 추적 매개변수(UTM, fbclid, gclid) 제거, 중복 슬래시 제거, 프로토콜 및 대소문자 정규화 - 프로토콜이 제공되지 않은 경우 `https://` 자동 추가 - 성공 애니메이션과 함께 생성 직후 단축 URL 표시 - **대량 URL 단축**: 사용자가 여러 URL(줄당 하나)을 붙여넣고 한 번에 모두 단축할 수 있음 #### 2. 커스텀 별칭 지원 - 선택적 커스텀 별칭 필드 (예: `short.ly/my-brand`) - 사용자가 입력하는 동안 실시간 사용 가능 여부 확인 (디바운스 API 호출, 300ms) - 별칭 유효성 검사 규칙: 영숫자, 하이픈, 밑줄만 허용; 3~30자; 예약어 블랙리스트 (예: `admin`, `api`, `login`, `static`) - 별칭이 사용 중이거나 유효하지 않은 경우 명확한 오류 메시지 #### 3. QR 코드 생성 - 생성 시 모든 단축 URL에 대한 QR 코드 자동 생성 - QR 코드 모달/패널에서 다음 옵션 제공: - PNG로 다운로드 (고해상도, 1024×1024) - SVG로 다운로드 (벡터, 확장 가능) - 전경/배경 색상 커스터마이즈 - 중앙에 작은 로고 오버레이 추가 (선택 사항) - QR 코드가 전체 단축 URL을 인코딩하고 작은 크기에서도 스캔 가능한지 확인 #### 4. 클릭 추적 및 분석 대시보드 - 다음 데이터 포인트로 모든 리디렉션 추적: - 타임스탬프 (UTC) - 국가 및 도시 (IP 지리적 위치 API 사용) - 디바이스 유형 (모바일, 태블릿, 데스크톱) - 운영 체제 및 브라우저 (User-Agent 파싱 사용) - 리퍼러 URL - 고유 vs. 재방문 사용자 (쿠키/핑거프린트 사용) - 링크별 **분석 대시보드** 포함: - 총 클릭 수 및 고유 클릭 수 카운터 - 시간 경과별 클릭 수 선 차트 (필터 가능: 최근 24시간, 7일, 30일, 90일, 전체) - 지리적 분포 지도 또는 막대 차트 (상위 10개 국가) - 디바이스/OS/브라우저 분석 (도넛 또는 파이 차트) - 상위 리퍼러 테이블 - 요일 및 시간별 클릭 히트맵 - 메인 대시보드의 집계 분석 개요 (총 링크 수, 총 클릭 수, 가장 인기 있는 링크) #### 5. 링크 만료 - 링크 생성 시 선택적 만료 날짜/시간 선택기 - 사전 설정 지원: 1시간, 24시간, 7일, 30일, 커스텀 날짜 - 활성 링크에 카운트다운 또는 "X 후 만료" 배지 표시 - 만료된 링크 자동 비활성화 및 리디렉션 시도 시 친숙한 "이 링크는 만료되었습니다" 페이지 표시 - 기존 링크의 만료 연장 또는 제거 허용 #### 6. 비밀번호 보호 - 링크 생성 시 선택적 비밀번호 토글 - 활성화된 경우 대상 URL로 리디렉션 전에 비밀번호 입력 게이트 페이지 표시 - 서버 측에서 bcrypt 또는 Argon2를 사용하여 비밀번호 해시 (평문 저장 금지) - 비밀번호 시도 속도 제한 (IP당 분당 최대 5회) 및 잠금 메시지 - 기록 보기에서 비밀번호 보호 링크에 시각적 표시기(자물쇠 아이콘 🔒) #### 7. 클립보드 복사 - 모든 단축 URL 옆에 원클릭 복사 버튼 - `document.execCommand('copy')` 폴백과 함께 Clipboard API(`navigator.clipboard.writeText()`) 사용 - 시각적 확인: 버튼 아이콘이 체크 표시 ✅로 변경되고 2초 후 자동으로 사라지는 "복사됨!" 툴팁/토스트 표시 - 키보드 단축키 지원 (예: `Ctrl+Shift+C`로 가장 최근에 생성된 링크 복사) #### 8. URL 기록 및 관리 - 모든 단축 URL의 영구 기록 테이블/그리드 (게스트는 `localStorage`에 저장, 인증된 사용자는 데이터베이스에 저장) - 각 항목 표시: 원본 URL(툴팁이 있는 잘림), 단축 URL, 생성 날짜, 클릭 수, 상태(활성/만료/비밀번호 보호), 작업 버튼 - **검색**: 원본 URL, 별칭, 태그 전체 텍스트 검색 - **필터링**: 상태(활성, 만료, 보호), 날짜 범위, 클릭 수 범위, 태그별 - **정렬**: 생성 날짜, 클릭 수, 알파벳순(오름차순/내림차순) - 대규모 기록을 위한 **페이지네이션 또는 무한 스크롤** (페이지당 25개 항목) - **일괄 작업**: 여러 링크를 선택하여 삭제, 비활성화, CSV/JSON으로 내보내기 - **태그/라벨**: 사용자가 링크를 구성하기 위해 커스텀 태그 추가 허용 (예: "마케팅", "소셜", "캠페인-q4") --- ### 🔒 보안 요구사항 - XSS 공격 방지를 위한 클라이언트 및 서버 양쪽의 입력 정리 - 모든 상태 변경 API 엔드포인트에 CSRF 보호 - 오픈 리디렉션 취약점 방지를 위한 리디렉션 대상 검증 및 정리 (허용 프로토콜 화이트리스트, `javascript:`, `data:`, `file:` 스킴 차단) - CSP(Content Security Policy) 헤더 구현 - 속도 제한: IP당 분당 최대 20개 링크 생성; 분당 최대 100개 API 요청 - 보안 HTTP 헤더: `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security` - 내부 ID 노출 금지; 공개 링크 식별자에는 nanoid 또는 UUID 사용 --- ### ⚡ 성능 요구사항 - Lighthouse 점수 목표: 성능 >90, 접근성 >95, 모범 사례 >95, SEO >90 - 분석 차트 및 중요하지 않은 자산 지연 로드 - 모든 검색 및 유효성 검사 입력 디바운스 - 스크롤 기반 애니메이션 및 지연 로딩에 `IntersectionObserver` 사용 - 리플로우 및 리페인트 최소화; 애니메이션에 CSS `transform` 및 `opacity` 사용 - 적절한 경우 API 응답 캐시 (예: 60초 TTL의 분석 데이터) - 리디렉션은 서버 측에서 100ms 이내에 해결되어야 함 --- ### 🧪 오류 처리 및 엣지 케이스 - 네트워크 오류, API 시간 초과, 잘못된 URL, 중복 별칭, 서버 오류(500), 속도 제한 초과(429)에 대한 우아한 오류 메시지 - 오프라인 감지: 사용자가 연결을 잃었을 때 배너 표시 및 재시도를 위한 작업 대기열 - 레이아웃을 깨지 않고 매우 긴 URL(최대 2048자) 처리 - 유니코드/국제화 도메인 이름(IDN) 올바르게 처리 - 사용자에게 링크나 분석 데이터가 없을 때 빈 상태 일러스트레이션 --- ### 📦 결과물 1. 명확한 폴더 구조를 갖춘 완전하고 주석이 잘 달린 소스 코드 2. 설정 지침, API 문서, 기능 목록이 포함된 `README.md` 3. API 엔드포인트 참조 테이블 (메서드, 경로, 매개변수, 응답 형식) 4. 즉시 미리보기를 위해 샘플 데이터가 미리 로드된 `demo` 모드 5. Chrome, Firefox, Safari, Edge(최신 2개 버전)에서 반응형 지원 --- > **참고:** 증분 방식으로 구축하세요 - 핵심 단축 흐름(입력 → 검증 → 단축 → 표시 → 복사)으로 시작한 다음 QR 코드, 분석, 커스텀 별칭, 만료, 비밀번호 보호, 전체 기록 대시보드를 레이어링하세요. 각 기능이 완전히 작동하고 다음 기능으로 이동하기 전에 테스트되었는지 확인하세요.