프론트 ↔ 백엔드 매핑
프론트엔드 화면·기능을 보고, 거기에 대응하는 백엔드 기능을 골라 만드는 규칙입니다.
개요
Vortex는 “기획 → 프론트 → 백엔드까지 하나로”를 지향합니다. 프론트를 vortex로 만든 뒤, AI나 개발자가 그 화면·기능을 보고 대응하는 백엔드를 매핑해 만들 수 있도록, 이 페이지가 매핑 규칙을 제공합니다. 핵심 원칙은 프론트 화면/기능 1개 ≈ 백엔드 feature 1개이며, 흔한 기능은 모듈로 덮고(add) 없는 것만 커스텀으로 만듭니다.
매핑 표 — 프론트 기능 → 백엔드 모듈/API
| 프론트 화면·기능 | 백엔드 모듈 | add 명령 | 생기는 API |
|---|---|---|---|
| 로그인·회원가입·내 정보·인증가드 | auth | add backend/auth | /auth/register·login·refresh·me |
| 목록·상세·작성·수정·삭제 (게시판·CRUD형) | crud-db | add backend/crud-db | /posts CRUD (페이지네이션·정렬·검색) |
| 파일 첨부·이미지 업로드 | file-upload | add backend/file-upload | /uploads/presign (S3 직행) |
| (운영) 에러 표준화·요청 로깅 | error-logging | add backend/error-logging | 표준 에러 포맷 + 구조화 로깅 |
| 위에 없는 도메인 고유 기능 | (커스텀 feature) | — | 직접 작성 (아래 참조) |
AI 워크플로 — 프론트 보고 백엔드 만들기
AI 에이전트가 이 문서를 읽고 수행하는 표준 흐름:
- 프론트 결과물 분석 — 어떤 화면·기능이 있는지 식별 (로그인 화면? 목록/폼? 파일 첨부?)
- 매핑 — 위 표로 각 프론트 기능을 백엔드 모듈에 대응시킨다. 표에 없으면 커스텀 feature 후보.
- 사용자 확인 — 백엔드 스택(
nest|hono|egov-spring)과 매핑된 모듈 목록을 사용자에게 제시·확정. - 생성 — 확정된 선택으로 CLI 실행:
npx @vortex/cli init <app> --backend nest --db postgresql --modules <매핑된 모듈들> - 커스텀 feature — 표에 없는 기능은 생성된 프로젝트의
FEATURE_GUIDE.md패턴으로 추가 (example 폴더 복사). - 계약 연결 —
pnpm contracts:generate로 백엔드 OpenAPI에서 프론트 타입·TanStack Query 훅·MSW mock 생성. 프론트와 백엔드가 같은 계약으로 맞물린다.
커스텀 feature (모듈에 없는 기능)
생성된 백엔드의 src/example/이 복사용 템플릿입니다. 프론트 화면 하나당 feature 폴더 하나:
src/<feature>/
├─ <feature>.dto.ts # Zod 스키마 = 계약의 단일 진실 (검증 + OpenAPI + 프론트 타입)
├─ <feature>.controller.ts # 엔드포인트 (@ApiTags·@ApiOkResponse 로 swagger 노출)
├─ <feature>.service.ts # 비즈니스 로직
└─ <feature>.module.ts # 묶음 → app.module.ts <vortex:modules> 마커에 등록모든 입출력을 Zod DTO로 정의하면 OpenAPI·프론트 타입·런타임 검증이 한 번에 맞물립니다. 자세한 절차는 공통 모듈·계약 파이프라인 참고.
Last updated on