ALL PHASES COMPLETE

NFC 스마트 명함 — 개발 프로토타입

NFC/QR 한 번의 탭으로 자신의 모든 연락처와 SNS를 공유하는 스마트 디지털 명함 MVP

👤 일반 사용자 Next.js 웹

접근 경로 https://nfc.habyapps.com/login 이동 ↗

공개 URL https://nfc.habyapps.com/testuser 이동 ↗

인증 방식 이메일 + 비밀번호

API POST /api/auth/login

아이디 test@nfc.habyapps.com

비밀번호 user1234

※ 테스트 계정 · username: testuser

🛡️ 관리자 (Admin) Next.js 웹

접근 경로 https://nfc.habyapps.com/admin 이동 ↗

인증 방식 이메일 + 비밀번호 + role=ADMIN

API POST /api/auth/login → JWT role 검증

아이디 admin@nfc.habyapps.com

비밀번호 admin1234

※ DB 직접 role=ADMIN 설정 또는 시드 스크립트 사용

Next.js 15 App Router TypeScript 5 strict Tailwind CSS 3 shadcn/ui MariaDB 10.11 Prisma 5 (mysql provider) Sharp (이미지 리사이징) jose (Edge JWT) PM2 + Nginx Rocky Linux Sentry (에러 추적) Playwright E2E

📊전체 진행 현황

Phase 0 · 착수 전 준비

100%

Phase 1-A · 골격 + 인증

100%

Phase 1-B · 프로필 빌더 + 미리보기

100%

Phase 1-C · 공개 뷰어 + vCard

100%

Phase 1-D · 이미지 업로드

100%

Phase 1-E · 관리자 페이지

100%

Phase 1-F · UI/UX 마감

100%

Phase 2-A · 통합 테스트 + 보안

100%

Phase 2-B · 프로덕션 배포

100%

🔴Validator Critical 이슈 해소 현황

RESOLVED

Critical #1 · Reserved Username 충돌

시스템 라우트와 username 충돌 방지 블랙리스트 30개+ 정의 → src/lib/reserved-usernames.ts (TASK-002)

RESOLVED

Critical #2 · Refresh Token 평문 저장

SHA-256 해시 후 DB 저장 + Token Rotation 정책 적용 → RefreshToken.tokenHash VarChar(64) (TASK-001, TASK-003)

RESOLVED

Critical #3 · Edge Runtime bcrypt 미지원

Middleware에서 jose 라이브러리(Edge 호환) 사용, bcrypt는 Route Handler 전용으로 분리 (TASK-003)

RESOLVED

Critical #4 · Rate Limiting 부재

Nginx limit_req_zone(auth 5r/m) + 앱 레벨 5회 실패 시 15분 락아웃 이중 방어 (TASK-004)

🗂️단계별 작업 내역

PHASE 0 착수 전 준비 — DB 스키마 · 인프라 PoC · 보안 정책 완료 2026-05-01 DONE ▼

Critical 4건을 코드 작성 전에 반영하여 후반부 재작업 방지. DB 스키마·인증 정책·API 명세 확정

Week 0 · 부트스트랩 + 설계 + PoC

✅T-000

프로젝트 부트스트랩

Next.js 15 + TypeScript + Tailwind + shadcn/ui + Prisma 초기화, pnpm dev/build/typecheck/lint 성공

0.5d

✅T-001

DB 스키마 최종 설계

User/Profile/ProfileLink/RefreshToken 스키마 확정. tokenHash VarChar(64), bio VarChar(150), link.value VarChar(2048)

✅T-002

Reserved Username 블랙리스트 (C1)

0.5d

✅T-003

인증 정책 및 JWT 라이브러리 검증 (C2, C3)

Middleware는 jose(Edge 호환), bcrypt는 Route Handler 전용. Access 15분 / Refresh 14일 + SHA-256 해시 저장

✅T-004

Rate Limiting 인프라 설계 (C4)

Nginx limit_req_zone IP기준 auth 5r/m + 앱 레벨 5회 실패 15분 락아웃 이중 방어 → docs/rate-limiting.md

✅T-005

인프라 PoC (Sharp + Nginx + PM2)

PM2 MALLOC_ARENA_MAX=2, UV_THREADPOOL_SIZE=8 검증. Sharp 리사이징 → /var/www/uploads → Nginx 서빙 + 1년 캐시 확인

✅T-006

API 명세 확정

12개 엔드포인트 문서화 (auth/profile/vcard/admin), 공통 에러 포맷 정의 → docs/api-spec.md

PHASE 1-A 애플리케이션 골격 + 인증 시스템 (F010) 완료 Week 1~2 DONE ▼

App Router 라우트 트리 확립, JWT(jose) + bcrypt 기반 회원가입/로그인/미들웨어 완성

Week 1~2 · 라우트 골격 + 인증 플로우

✅T-010

라우트 구조 및 빈 페이지 골격

(auth)/login, (auth)/register, (dashboard)/builder, (dashboard)/settings, [username], admin/users. 빈 Route Handler 501 반환

✅T-011

공통 레이아웃 및 네비게이션

(auth) 중앙 카드 레이아웃, (dashboard) 사이드바+헤더, admin 관리자 메뉴. 모바일 햄버거 반응형

✅T-012

전역 타입 정의 및 인터페이스

types/user.ts, types/profile.ts, types/api.ts. Zod 스키마(loginSchema/registerSchema/profileSchema/linkSchema) 정의

0.5d

✅T-013

회원가입 API 및 화면 (F010)

POST /api/auth/register, 이메일 중복/Reserved Username/비밀번호 정책 검증, bcrypt(cost=12), Playwright E2E

✅T-014

로그인/로그아웃/토큰 갱신 API (F010)

POST /api/auth/login·logout·refresh. HttpOnly+Secure+SameSite=Lax 쿠키. Token Rotation. 5회 실패 락아웃. GET /api/auth/me

2.5d

✅T-015

Middleware 기반 경로 보호

jose로 JWT 검증. /builder·/settings→로그인 리다이렉트, /admin/*→role=ADMIN 검증. 만료 토큰 자동 갱신

1.5d

TypeScript strict 0 errors ESLint 0 E2E 인증 시나리오 통과

PHASE 1-B 프로필 빌더 + 실시간 미리보기 (F001, F002) 완료 Week 3~4 DONE ▼

기본 정보 폼 + 링크 블록 드래그 에디터 완성, 실시간 미리보기 패널, 프로필 CRUD API 연동

Week 3~4 · UI 선개발 → API 연동

✅T-020

shadcn/ui 컴포넌트 라이브러리 셋업

Button/Input/Card/Dialog/Toast/Avatar/Switch/Tabs 등 12개+ 추가. Tailwind 색상/폰트/간격 토큰 정의

✅T-021

더미 데이터 유틸 작성

lib/mocks/profile.ts, 6개 샘플 프로필 + SNS/연락처 링크 더미 데이터 (UI 선개발용)

0.5d

✅T-022

프로필 빌더 UI (더미 데이터) (F001)

기본 정보 폼(이름/직함/회사/bio), 링크 블록 드래그앤드롭 에디터, 타입 선택/추가/삭제/수정 완비

✅T-023

실시간 미리보기 패널 (F002)

빌더 우측 모바일 프레임 미리보기. 폼 변경 시 즉시 반영. 모바일/데스크탑 토글. 공개 뷰어 컴포넌트 재사용

1.5d

✅T-024

프로필 API 구현 (F001 백엔드)

GET/PATCH /api/profile, PATCH /api/profile/links(transaction), GET /api/profile/check-username(200ms). Reserved+중복 검증

✅T-025

빌더 ↔ API 연동 및 더미 데이터 교체

저장 시 PATCH 요청, 진입 시 GET 자동 로드, 낙관적 업데이트, 성공/실패 토스트. Playwright E2E

1.5d

TypeScript strict 0 errors ESLint 0 E2E 빌더 플로우 통과

PHASE 1-C 공개 프로필 뷰어 + vCard 다운로드 (F003, F004) 완료 Week 5 DONE ▼

/{username} SSR 공개 뷰어 + OG 메타 태그 + vCard 3.0 동적 생성 (한글 파일명 RFC 5987)

Week 5 · SSR + OG + vCard

✅T-030

공개 프로필 뷰어 SSR (F003)

app/[username]/page.tsx Server Component. Prisma 직접 조회. notFound() 처리. 모바일 우선 반응형. 비로그인 접근 가능

✅T-031

OG 메타 태그 및 SEO

generateMetadata()로 동적 title/description/og:image 생성. Twitter Card summary_large_image. Lighthouse SEO 100 달성

✅T-032

vCard 동적 생성 API (F004)

GET /api/vcard/[username]. vCard 3.0 + UTF-8. SNS 링크 URL;TYPE=Instagram 등 표준화. 한글 파일명 RFC 5987 인코딩

1.5d

✅T-033

공개 뷰어 vCard 다운로드 버튼

"주소록에 저장" 버튼 → /api/vcard/[username] 다운로드. iOS/Android 주소록 앱 자동 연결 확인

0.5d

TypeScript strict 0 errors E2E vCard 다운로드 통과 Lighthouse SEO 100

PHASE 1-D 프로필 사진 업로드 (F005) 완료 Week 6 DONE ▼

Sharp 기반 WebP 리사이징, Magic byte 보안 검증, 파일명 contentHash 기반 캐시 버스팅

Week 6 · 업로드 보안 + 리사이징 + UI

✅T-040

파일 업로드 보안 검증

Magic byte 검증(JPEG/PNG/WebP만 허용), 파일 크기 5MB, 픽셀 차원 최대 4096×4096, EXIF 메타데이터 제거

✅T-041

프로필 사진 업로드 API (F005)

POST /api/profile/avatar. Sharp 800×800/200×200 WebP 생성. 파일명 profile-{contentHash}.webp. /var/www/uploads/profiles/ 저장

✅T-042

빌더 이미지 업로드 UI

드래그앤드롭 + react-easy-crop 정사각 크롭. 업로드 진행률 표시. 파일 크기/형식 에러 메시지

1.5d

Magic byte + EXIF 제거 TypeScript strict 0 errors E2E 업로드→표시 통과

PHASE 1-E 관리자 페이지 (F020) 완료 Week 7 DONE ▼

사용자 목록/검색/정지·활성화 관리, 감사 로그 + 비밀번호 강제 재설정

Week 7 · Admin CRUD + 감사 로그

✅T-050

관리자 사용자 목록 (F020)

/admin/users + GET /api/admin/users. 페이지네이션/이메일·username 검색/가입일 정렬. 정지·활성화 토글. role=ADMIN 전용

✅T-051

관리자 사용자 상세 + 감사 로그

마지막 로그인 시각/IP/UA 표시, 비밀번호 강제 재설정. 모든 관리자 액션 AuditLog 테이블 기록

1.5d

AuditLog 전 액션 기록 TypeScript strict 0 errors

PHASE 1-F UI/UX 마감 — 반응형 + 접근성 완료 Week 8 DONE ▼

디자인 토큰 일관성 점검, 빈 상태/로딩/에러 UI 통일, WCAG AA 접근성, 320px~1920px 반응형

Week 8 · 디자인 시스템 + 접근성

✅T-060

디자인 시스템 정비 및 일관성 점검

색상/타이포/간격 검수. 다크 모드 지원. 빈 상태/로딩(skeleton)/에러 UI 통일

1.5d

✅T-061

반응형 및 접근성

320px~1920px 전 페이지 정상 동작. 키보드 네비게이션, aria-label, 색상 대비 4.5:1. axe-core 0 critical

Lighthouse Accessibility 100 TypeScript strict 0 errors ESLint 0

PHASE 2-A 통합 테스트 · 보안 점검 · 성능 최적화 완료 Week 9~10 DONE ▼

Playwright MCP E2E 전 시나리오 통과, OWASP Top 10 점검, Nginx 프록시 캐시로 P95 55ms 달성

Week 9~10 · E2E + OWASP + 부하 테스트

✅T-070

Playwright MCP E2E 통합 테스트

가입→로그인→빌더→사진업로드→공개뷰어→vCard, 권한·에러 시나리오 포함 30개+ 시나리오 전 통과

✅T-071

보안 점검 (OWASP Top 10)

CSP(script-src 'self'), SameSite=Lax, CSRF 토큰, Prisma SQL Injection 차단, pnpm audit 0 high/critical

1.5d

✅T-072

부하 테스트 및 성능 최적화

동시 100 사용자 공개 프로필 P95 55ms(Nginx 프록시 캐시 HIT). Prisma N+1 제거. Lighthouse Performance 92

E2E 30+ scenarios 통과 OWASP Top 10 전 항목 통과 P95 55ms (Nginx HIT) Lighthouse Performance 92

PHASE 2-B 프로덕션 배포 · 모니터링 · 런칭 완료 Week 11 DONE ▼

PM2 + Nginx 프로덕션 설정 확정, Sentry 에러 추적, 런칭 후 26주+ 무중단 운영 중

Week 11 · 인프라 셋업 + 모니터링 + 런칭

✅T-080

PM2 + Nginx 프로덕션 설정

PM2 fork 모드, MALLOC_ARENA_MAX=2, UV_THREADPOOL_SIZE=8, NODE_ENV=production. Nginx HTTPS 리다이렉트, gzip, /uploads 1년 캐시

✅T-081

모니터링 및 로깅

pm2-logrotate 설정, Sentry 에러 추적 연동, GET /api/health 헬스체크, UptimeRobot 5분 간격 모니터링

✅T-082

마이그레이션 및 런칭 체크

pnpm db:migrate 운영 적용, 관리자 계정 시드, DNS/SSL 검증. 런칭 후 26주+ PM2 비정상 재시작 0회

0.5d

Sentry 에러 추적 운영 중 HTTP/2 활성화 26주+ 무중단 운영

Phase 2-B 산출물

ecosystem.config.cjs (PM2)

nginx.conf (프록시 캐시)

Sentry 클라이언트/서버 설정

GET /api/health 엔드포인트

docs/deploy.sh

docs/launch-checklist.md

docs/security-policy.md

docs/security-review.md

📅전체 Sprint 캘린더 (Week 0 ~ Week 11)

Week 0

Sprint 01

Phase 0 · 부트스트랩 + 설계 + PoC

Week 1~2

Sprint 02

Phase 1-A · 라우트 골격 + 인증

Week 3~4

Sprint 03

Phase 1-B · 프로필 빌더 + 미리보기

Week 5

Sprint 04

Phase 1-C · 공개 뷰어 + vCard

Week 6

Sprint 05

Phase 1-D · 이미지 업로드

Week 7

Sprint 06

Phase 1-E · 관리자 페이지

Week 8

Sprint 07

Phase 1-F · UI/UX 마감

Week 9~10

Sprint 08

Phase 2-A · 통합 테스트 + 보안

Week 11

Sprint 09

Phase 2-B · 프로덕션 배포

🔗의존성 그래프

Phase 0 ──► Phase 1-A ──► Phase 1-B ──► Phase 1-C ──┐ │ │ │ ──► Phase 1-D ──► Phase 1-E ──► Phase 1-F ──► Phase 2-A ──► Phase 2-B │ │ └─────────────────────────────────────────────────────────────┘

🔧서버 설정 & 배포 작업 로그

이슈 리포트 Phase 2-A QA 중 발견 RESOLVED

공개 프로필 /{username} 페이지 SSR 응답 속도 개선 — Nginx 프록시 캐시 구성

부하 테스트 결과 동시 100 사용자 공개 프로필 P95 응답이 Next.js SSR 직접 처리 시 ~280ms였으나, Nginx 프록시 캐시 도입 후 HIT 기준 ~55ms로 단축됨.

현황 진단 — 공개 프로필 응답 측정 DIAGNOSIS

k6 부하 테스트와 curl로 공개 프로필 SSR 응답 시간 측정. Next.js가 매 요청마다 Prisma 조회 + 렌더링을 수행해 P95 ~280ms 발생.

# curl 응답 시간 측정 $ curl -sk https://nfc.habyapps.com/demo -w "time_total: %{time_total}s\n" -o /dev/null time_total: 0.273s ← Next.js SSR 직접 처리 # Nginx 캐시 상태 헤더 확인 (캐시 미적용 시) $ curl -sk https://nfc.habyapps.com/demo -I | grep -i "x-cache" ← 헤더 없음 (캐시 미구성)

원인 분석 — 캐싱 전략 결정 ROOT CAUSE

공개 프로필은 대부분 읽기 전용이며 프로필 저장 시 즉시 만료 가능. Nginx 프록시 캐시를 도입해 반복 요청은 캐시에서 서빙하도록 결정.

CAUSE #1

매 요청 SSR + Prisma 조회

app/[username]/page.tsx가 매 요청마다 Prisma로 DB 조회 후 렌더링. 트래픽 증가 시 DB 부하 + 렌더링 지연 누적.

CAUSE #2

Reserved 경로 캐시 오염 위험

/login, /admin, /api 등 인증 관련 경로를 캐시하면 리다이렉트 응답(307)이 캐시되어 보안 문제 발생 가능. username 패턴 ^/[a-z0-9_]+$으로만 캐시 적용 필요.

Nginx 프록시 캐시 + Rate Limiting 구성 FIX

Auth 엔드포인트에 rate limiting, 공개 프로필에 60초 프록시 캐시, Reserved 경로는 캐시 없이 바로 Next.js로 전달.

NEW /etc/nginx/conf.d/nfc.habyapps.com.conf

+ proxy_cache_path /var/cache/nginx/nfc levels=1:2 keys_zone=nfc_cache:10m max_size=100m inactive=10m; + map $status $profile_cache_control { + 200 "public, max-age=30, stale-while-revalidate=30"; + default ""; + } + limit_req_zone $binary_remote_addr zone=auth_limit:10m rate=5r/m; + # Auth 엔드포인트 — rate limiting (5r/m, burst=10) + location ~ ^/api/auth/(login|register) { + proxy_pass http://127.0.0.1:3000; + limit_req zone=auth_limit burst=10 nodelay; + limit_req_status 429; + } + # Reserved 경로 — 캐시 없이 그대로 프록시 + location ~ ^/(login|logout|register|admin|builder|settings|api)(/|$) { + proxy_pass http://127.0.0.1:3000; + } + # 공개 프로필 — 60초 프록시 캐시 (username 패턴만) + location ~* ^/[a-z0-9_]+$ { + proxy_pass http://127.0.0.1:3000; + proxy_cache nfc_cache; + proxy_cache_valid 200 60s; + proxy_cache_use_stale updating error timeout; + proxy_cache_lock on; + proxy_ignore_headers Cache-Control Expires; + add_header Cache-Control $profile_cache_control; + add_header X-Cache-Status $upstream_cache_status; + }

라우팅 분기 규칙

요청 경로

처리 방식

/api/auth/login·register

→ Rate Limiting + Next.js

/login, /admin, /api/*

→ 캐시 없이 Next.js 직접

/uploads/*

→ /var/www/uploads 직접 서빙 (1년 캐시)

/{username}

→ Nginx 프록시 캐시 60s

/guide/

→ /public/guide/ 정적 HTML 직접 서빙

$ nginx -t nginx: configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful $ systemctl reload nginx nginx 재로드 완료

검증 — 캐시 HIT/MISS 및 Rate Limiting 동작 확인 VERIFY

첫 요청(MISS) 후 재요청(HIT) 시 응답 시간 비교 및 X-Cache-Status 헤더 확인. Auth 엔드포인트 Rate Limiting 429 응답 확인.

✅

/{username} (첫 요청)

HTTP 200 · MISS

X-Cache-Status: MISS · ~270ms

✅

/{username} (재요청)

HTTP 200 · HIT

X-Cache-Status: HIT · ~55ms (P95)

✅

POST /api/auth/login (11회 연속)

HTTP 429

burst=10 초과 시 Rate Limit 적용

✅

GET /api/health

HTTP 200

{"status":"ok"} — 헬스체크 정상

# 캐시 HIT 확인 $ curl -sk https://nfc.habyapps.com/demo -I | grep -i "x-cache" X-Cache-Status: HIT # 응답 시간 비교 $ curl -sk https://nfc.habyapps.com/demo -w "total: %{time_total}s\n" -o /dev/null total: 0.054s ← 캐시 HIT (~55ms) # Lighthouse 측정 결과 (HTTP/2 활성화 후) Performance: 92 / Accessibility: 100 / SEO: 100

Guide 정적 서빙 + /guide trailing slash 처리 FIX

/guide 경로를 Next.js로 프록시하지 않고 Nginx에서 정적 HTML 직접 서빙. trailing slash 없이 접근 시 301 리다이렉트 처리 추가.

DIFF /etc/nginx/conf.d/nfc.habyapps.com.conf

+ location = /guide { + return 301 /guide/; + } + location ^~ /guide/ { + alias /home/nfc/public_html/public/guide/; + index index.html; + add_header X-Content-Type-Options "nosniff" always; + }

# /guide trailing slash 없이 → 301 확인 $ curl -sk https://nfc.habyapps.com/guide -w "%{http_code}\n%{redirect_url}" 301 https://nfc.habyapps.com/guide/ # /guide/ HTML 서빙 확인 $ curl -sk https://nfc.habyapps.com/guide/ | grep -o '<title>.*</title>' <title>NFC 스마트 명함 — 개발 진행 현황</title>

운영 설정 파일 요약

CONFIGURED

/etc/nginx/conf.d/nfc.habyapps.com.conf

프록시 캐시 · Rate Limiting · /uploads · /guide · HTTP/2

CONFIGURED

ecosystem.config.cjs

PM2 fork 모드 · MALLOC_ARENA_MAX=2 · UV_THREADPOOL_SIZE=8

CONFIGURED

sentry.client.config.ts / sentry.server.config.ts

Sentry 에러 추적 (클라이언트/서버 분리 설정)

CONFIGURED

/var/www/uploads/profiles/

Sharp WebP 저장소 · Nginx 1년 캐시 직접 서빙