Backend 공통 모듈

일반적인 애플리케이션에 필요한 공통 기능을 골라서 조립하는 기능 블록입니다.

개요

Vortex Backend 모듈은 인증·CRUD·로깅·파일 업로드처럼 거의 모든 애플리케이션이 필요로 하는 기능을 독립 블록으로 제공합니다. init --backend의 모듈 선택 단계에서 고르거나, 나중에 npx @vortex/cli add backend/<module>로 추가합니다. 모든 모듈은 Zod 스키마 기반이라 OpenAPI 문서와 프론트엔드 타입에 자동 반영됩니다.

모듈 카탈로그 (v1)

인증 (auth)

JWT 기반 인증. 엔드포인트:

• POST /auth/register — 회원가입 → 토큰 발급
• POST /auth/login — 로그인 → 액세스/리프레시 토큰
• POST /auth/refresh — 리프레시 토큰으로 갱신
• GET /auth/me — 내 정보 (Bearer 토큰 필요)

다른 모듈에서 @UseGuards(JwtAuthGuard)로 보호 가능. 환경 변수: JWT_SECRET, JWT_EXPIRES_IN, JWT_REFRESH_EXPIRES_IN.

CRUD + DB (crud-db)

Prisma ORM + 표준 구조의 게시글 CRUD 예시. 목록은 페이지네이션·정렬(?sort=-createdAt)·검색(?search=)을 지원합니다.

• GET /posts · GET /posts/:id · POST /posts · PATCH /posts/:id · DELETE /posts/:id
• DB 변형: --db postgresql 또는 --db mysql (schema.prisma provider 자동 설정)
• 설치 후: npx prisma generate && npx prisma db push
• 환경 변수: DATABASE_URL

복잡한 쿼리(UNION/CTE 등)는 Prisma의 TypedSQL(.sql 파일)로 타입 안전하게 작성합니다.

에러·로깅 (error-logging)

표준 에러 응답 포맷 { code, message, details? }은 프론트엔드 axios 인터셉터 규약과 정합합니다. 모든 HTTP 요청/응답을 pino로 구조화 로깅하며, Authorization·Cookie 헤더는 자동 마스킹됩니다. 환경 변수: LOG_LEVEL.

파일 업로드 (file-upload)

S3 presigned URL 패턴. 파일이 서버를 거치지 않고 브라우저에서 S3로 직접 업로드됩니다.

• POST /uploads/presign — { fileName, contentType } → presigned PUT URL + 객체 키
• 환경 변수: AWS_REGION, S3_BUCKET (자격증명은 IAM 역할/프로파일 권장)

모듈 조합 예시

# 게시판 + 회원 + 파일첨부 = 전형적인 웹 애플리케이션
npx @vortex/cli init board-app --backend nest --db postgresql \
  --modules auth,crud-db,error-logging,file-upload