PicSel Backend

PicSel 결제 추천 서비스 백엔드 (NestJS + Prisma).

빠른 링크

• API Prefix: /api (예: /api/health)
• Swagger UI: /swagger
• Health Check: GET /api/health

기술 스택

• Node.js + TypeScript
• NestJS
• Prisma (MySQL)
• Swagger (OpenAPI)
• Jest / Vitest

로컬 실행 (Quick Start)

1) 의존성 설치

pnpm install

2) 환경변수 설정

루트에 .env 파일을 생성하고 아래 변수를 설정합니다. 이 프로젝트는 src/config/env.validation.ts에서 환경변수를 강하게 검증합니다.

필수(누락 시 부팅 실패):

NODE_ENV=development

DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/DB_NAME"

JWT_SECRET="your-jwt-secret"
ENCRYPTION_KEY="your-encryption-key"

GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
KAKAO_CLIENT_ID="..."
KAKAO_CLIENT_SECRET="..."
NAVER_CLIENT_ID="..."
NAVER_CLIENT_SECRET="..."

GEMINI_API_KEY="..."
GEMINI_MODEL="" # optional

선택(환경/배포에 따라 유용):

PORT=3000

# OAuth Redirect (옵션)
GOOGLE_REDIRECT_DEV_URI=""
GOOGLE_REDIRECT_PROD_URI=""
KAKAO_REDIRECT_DEV_URI=""
KAKAO_REDIRECT_PROD_URI=""
NAVER_REDIRECT_DEV_URI=""
NAVER_REDIRECT_PROD_URI=""

# CORS
CORS_ORIGINS="https://example.com,http://localhost:5173"
FRONTEND_URL="https://example.com" # CORS_ORIGINS 미설정 시 대체
CORS_ALLOW_LOCALHOST=false
CORS_ALLOW_PICSEL_SUBDOMAINS=true

# Logging
LOG_LEVEL=info

# 개발 환경 자동 시드(옵션)
AUTO_DB_SEED=true
REQUIRE_DB_SEED=false
AUTO_DB_SEED_RETRIES=5
AUTO_DB_SEED_RETRY_DELAY_MS=1500

3) DB 준비 (Prisma)

MySQL을 준비한 뒤 아래 중 하나를 사용합니다.

# 마이그레이션 적용(개발용)
pnpm db:migrate

# 클라이언트 생성
pnpm db:generate

# 시드 실행
pnpm db:seed

4) 서버 실행

# 개발(Watch)
pnpm dev

# 빌드
pnpm build

# 프로덕션 실행(빌드 산출물 기준)
pnpm start

실행 후:

• Swagger: http://localhost:3000/swagger
• Health: http://localhost:3000/api/health

주요 명령어

pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check

pnpm test
pnpm test:e2e
pnpm test:cov

pnpm test:vitest
pnpm test:vitest:watch
pnpm test:vitest:cov

API 확인 방법

엔드포인트 상세 스펙/요청·응답 예제는 Swagger UI(/swagger)를 기준으로 확인합니다.

• 인증/사용자: docs/guide/01_AUTH_INTEGRATION_GUIDE.md, docs/guide/02_USERS_INTEGRATION_GUIDE.md
• 결제수단: docs/guide/03_PAYMENT_METHODS_GUIDE.md
• 혜택 비교: docs/guide/04_BENEFITS_GUIDE.md
• 결제 내역: docs/guide/06_PAYMENTS_GUIDE.md
• Swagger 사용 가이드: docs/guide/SWAGGER/SWAGGER_DOCUMENTATION_GUIDE.md

배포 (AWS EC2, no Docker)

이 레포는 GitHub Actions에서 EC2에 SSH 접속 후 서버에서 run.sh를 실행하는 방식의 무도커 배포를 사용합니다.

• Workflow: .github/workflows/deploy.yml
• Deploy script: run.sh

필수 GitHub Secrets (워크플로 기준):

• SERVER_HOST
• SERVER_USER
• SERVER_PASSWORD

EC2 준비 사항(예시):

• 코드 위치: /home/ec2-user/app/picsel-backend
• pnpm 설치
• pm2 설치 및 권한 설정
• 런타임 환경변수 .env 배치(서버 내에서 관리, Git 커밋 금지)

Docker

Dockerfile이 포함되어 있습니다.

docker build -t picsel-backend .
docker run --rm -p 3000:3000 --env-file .env picsel-backend

Redis cache for AI summaries (optional)

This project supports using Redis to persist AI-generated summaries and recommendations across restarts and instances.

To enable, set REDIS_URL in your .env, e.g.:

REDIS_URL=redis://:password@redis-host:6379/0
AI_CACHE_TTL_SEC=3600

When REDIS_URL is present the server will attempt to write summaries to Redis (still keeping an in-memory cache for fast reads). Redis failures are non-fatal and the service falls back to in-memory cache.

디렉토리 구조

src/
  auth/                 인증/소셜 로그인
  users/                사용자/마이페이지
  payment-methods/      결제수단
  payments/             결제/기록
  benefits/             혜택 비교/추출
  dashboard/            대시보드 통계
  analytics/            소비 분석
  admin/                관리자/디버그용 API
  crawler/              외부 데이터 수집/크롤러
  external/             외부 연동(예: AI 추천, Popbill 등)
  common/               공통 유틸/가드/필터/로거/Swagger DTO
  prisma/               Prisma 연동 서비스
prisma/
  schema.prisma         DB 스키마(MySQL)
  migrations/           마이그레이션
  seed.ts               시드 스크립트
docs/
  guide/                FE 연동/Swagger 가이드
  db-migration/         DB 마이그레이션 문서
test/                   e2e 및 테스트 설정