web-page/CLAUDE.md

web-ui — CLAUDE.md

개인 웹페이지 프론트엔드 프로젝트에 대한 컨텍스트 문서입니다.

프로젝트 개요

• 스택: React 18 + Vite + react-router-dom v6
• 목적: 개인 블로그, 로또 실험, 주식 뉴스/트레이딩, 여행 기록을 한 곳에 모은 개인 웹 UI
• 배포 대상: Synology NAS (gahusb.synology.me) Docker 컨테이너 내 nginx

페이지 구조

경로	컴포넌트	설명
/	Home	메인 허브
/blog	Blog	마크다운 기반 블로그
/lotto	Lotto	로또 추천/통계
/stock	Stock	주식 뉴스/지수
/stock/trade	StockTrade	주식 트레이딩
/travel	Travel	여행 사진 갤러리
/lab	EffectLab	UI/UX 실험

라우트 정의: src/routes.jsx / 라우터 설정: src/Router.jsx

---

API 설정

핵심 원칙

• 항상 상대 경로 사용: 프로덕션에서 프론트와 백엔드는 nginx 리버스 프록시로 동일 도메인에서 서비스됨
• 절대 URL 사용 금지: https:// 절대 URL을 fetch에 직접 사용하면 Mixed Content 오류 발생
• VITE_API_BASE 환경변수는 사용하지 않음

API 헬퍼 (src/api.js)

// 모든 API 호출은 이 헬퍼를 통해 사용
import { apiGet, apiPost, apiPut, apiDelete } from './api';

// 예시
apiGet('/api/lotto/latest')
apiPost('/api/portfolio', { ... })

제공 함수: apiGet, apiPost, apiPut, apiDelete

개발 서버 프록시 (vite.config.js)

proxy: {
  '/api': {
    target: 'https://gahusb.synology.me',
    changeOrigin: true,
    secure: true,
  },
}

개발 중 /api/* 요청은 NAS 백엔드로 프록시됨. 개발 서버 포트: 3007

API 엔드포인트 목록

분류	메서드	경로
로또	GET	/api/lotto/latest, /api/lotto/stats, /api/lotto/recommend
로또	GET	/api/lotto/best, /api/lotto/analysis
로또	POST	/api/admin/simulate
히스토리	GET	/api/history
히스토리	DELETE	/api/history/:id
주식	GET	/api/stock/news, /api/stock/indices
트레이딩	GET	/api/trade/balance
트레이딩	POST	/api/trade/order
포트폴리오	GET/POST	/api/portfolio
포트폴리오	PUT/DELETE	/api/portfolio/:id

---

NAS 배포 설정

배포 경로

환경	경로
Windows	Z:\docker\webpage\frontend\ (NAS 네트워크 드라이브 마운트)
macOS (SMB)	/Volumes/gahusb.synology.me/docker/webpage/frontend/
macOS (SSH)	/volume1/docker/webpage/frontend/

배포 명령어

# 빌드 + 배포 (권장)
npm run release:nas

# 빌드만
npm run build

# 배포만 (dist 폴더가 이미 있을 때)
npm run deploy:nas

Windows 배포

NAS가 Z: 드라이브로 마운트되어 있어야 함. robocopy로 /MIR 동기화하며 로그는 robocopy.log에 저장됨.

macOS 배포 — SSH 방식 (권장)

# 환경변수 설정 후 배포
NAS_SSH_TARGET=user@gahusb.synology.me NAS_SSH_PORT=22 npm run release:nas

NAS_SSH_TARGET이 설정되면 rsync로 SSH 배포. SMB 마운트 방식보다 안정적.

macOS 배포 — SMB 마운트 방식

SMB 마운트 후 ditto로 복사. NAS_CLEAN=1 설정 시 배포 전 기존 파일 전체 삭제.

NAS_CLEAN=1 npm run release:nas

배포 스크립트 파일

scripts/deploy-nas.cjs — Node.js CJS 모듈, 플랫폼 자동 감지

---

개발 환경

npm install
npm run dev        # localhost:3007 에서 개발 서버 실행
npm run build      # dist/ 로 프로덕션 빌드
npm run lint       # ESLint 검사
npm run preview    # 빌드 결과물 미리보기

주요 파일 위치

파일	역할
src/api.js	API 헬퍼 함수 모음
src/routes.jsx	라우트 및 네비게이션 링크 정의
src/Router.jsx	BrowserRouter 설정
vite.config.js	개발 서버 및 프록시 설정
scripts/deploy-nas.cjs	NAS 배포 스크립트
src/content/blog/	블로그 마크다운 파일
public/	정적 파일 (로고, API 스펙 등)