# 랜딩 페이지 SaaS 전략 문서 작성일: 2026-03-01 ## 1. 제품 방향 - 대상: 광고 운영자가 고객 랜딩 페이지를 빠르게 생성·수정·배포·분석 가능한 SaaS - 핵심 가치: "빠른 제작 + 안정적인 발행 + 성과 측정 + 팀 협업" - 기술 스택(기준): Nuxt 4, Elysia, Prisma, SQLite(개발), PostgreSQL(운영), Bun, Nuxt UI, Pinia ## 2. 아키텍처 개요 - Frontend: Nuxt 4 + Nuxt UI + Pinia - Backend: Elysia REST API - ORM: Prisma - DB: 개발 SQLite, 운영 PostgreSQL - 파일/정적 자산: Object Storage + CDN - 배포: Docker + CI/CD ## 3. 구현 우선순위(권장) ### 3.1 MVP (필수) - 사용자/조직 관리 (회원가입, 로그인, 역할 기반 접근) - 프로젝트/페이지 CRUD - 랜딩 페이지 빌더(섹션 단위 블록) - 초안/발행 상태 관리(드래프트/퍼블리시/아카이브) - 페이지 미리보기 - 폼 제출 수집(기본 리드 저장) - 기본 분석 이벤트(조회/클릭/제출) - 템플릿 기반 시작 템플릿 제공 ### 3.2 확장판 - 버전 히스토리 + 롤백 - 커스텀 도메인 연결 - 캠페인별 KPI 대시보드 - 자동화 알림(이메일/슬랙) - 결제/구독 모델(요금제) - 팀 협업(댓글, 승인 플로우) ## 4. 데이터/도메인 모델 핵심 엔티티 - User: 인증/프로필 - Team: 팀/고객사 단위 소유권 - Project: 고객별 랜딩 프로젝트 - LandingPage: 페이지 메타 정보 - LandingPageVersion: 버전 히스토리 - PublishLog: 발행 이력 - FormSubmission: 랜딩 폼 제출 - LeadEvent: 트래킹 이벤트 - Subscription(선택): 요금제/사용량 ## 5. 기능 상세 체크리스트 ### 인증/권한 - JWT 또는 세션 기반 인증 - 역할: Owner/Admin/Editor/Viewer - 팀 단위 ACL + 프로젝트 단위 권한 - 감사 로그 필수 ### 멀티테넌시 - team_id/project_id 기반 강제 분리 - 리소스 조회 시 항상 소유권 조건 적용 - 교차 접근 방지 테스트 필수 ### 배포/발행 - 페이지 상태: draft, scheduled, published, archived - 발행 동작은 큐 기반 비동기 처리 고려 - 발행 로그/실패 사유 저장 ### SEO/마케팅 설정 - 메타 태그(og,title,description) - 스크립트 태깅 (GA, 픽셀 등) - OG 이미지/파비콘/robots 설정 ### 분석/리포트 - 이벤트 모델 최소화: page_view, section_view, cta_click, form_submit - 지표 집계(일 단위) - 기간별 조회 및 CSV 내보내기 ### 보안 - 입력 유효성/인젝션 방지 - rate limit, CORS, CSP, 보안 헤더 - 파일 업로드 확장자/용량 정책 ### 운영 - 로그, 모니터링, 에러 추적(Sentry) - 백업/복구 절차 정리 - 릴리스 전 Prisma migration 검사 ## 6. SQLite → PostgreSQL 전환 전략 1. Prisma schema를 PostgreSQL/SQLite 타입 호환 위주로 작성 2. DB 특화 함수/타입(특히 JSON/날짜/enum) 사용 최소화 3. `prisma migrate` 기반 migration 기록을 운영 분기와 동기화 4. 전환 전: - 마이그레이션 dry-run - 샘플 데이터 이관 스크립트 작성 - 무중단 전환 테스트 ## 7. 권장 개발 규칙 - TypeScript strict 사용 - ESLint/Prettier 통일 - API 계약 우선 (DTO, zod/valibot 등 검증) - 페이지 빌더 스키마 버전 관리 - CI에서 테스트(요청 시 실행) ## 8. 다음 액션(요청하면 바로 진행) - Prisma 스키마 초안 작성 - DB ERD/시퀀스 다이어그램 정리 - MVP API 엔드포인트 목록 도출 - 실제 폴더 구조 제안 ## 9. 최소 라우트/페이지 설계(1차) ### 9.1 공개 라우트(인증 불필요) - `/` 또는 `/{path?}`: 도메인 기반 랜딩 라우팅 진입점 - 동작: 요청 호스트 + path 기준으로 매핑된 랜딩 조회 후 렌더 - 조건 엔진 적용: 요일/시간/기간 규칙을 먼저 검사해 매칭 페이지 렌더 - `/_lead/success`: 폼 제출 성공 화면(선택) - `/_lead/error`: 폼 제출 실패 화면(선택) ### 9.2 운영자 라우트(인증 필요) - `/login`: 로그인 - `/admin` (Dashboard): 캠페인·리드 개요 - `/admin/campaigns`: 캠페인 목록 - `/admin/campaigns/new`: 캠페인 생성 - `/admin/campaigns/[id]/edit`: 캠페인 편집 - `/admin/pages`: 랜딩 페이지 목록(캠페인 필터) - `/admin/pages/new`: 랜딩 페이지 생성 - `/admin/pages/[id]`: 랜딩 상세/조회 - `/admin/pages/[id]/builder`: 블록형 빌더 편집 - 하위 탭: 콘텐츠 / 블록 / 도메인 라우팅 / 조건 규칙 / 미리보기 - `/admin/pages/[id]/conditions`: 조건 규칙 전용(요청 시 별도 탭으로 분리 가능) - `/admin/pages/[id]/routes`: 도메인+경로 매핑 관리 - `/admin/leads`: 리드 조회 목록 - `/admin/leads/[campaignId]`: 캠페인별 리드 목록 - `/admin/users`: 사용자/역할 관리(관리자, 리드관리자) ### 9.3 API 엔드포인트 권장(요청 도메인 라우팅/조건 렌더링 중심) - `GET /api/public/route-by-host`: 호스트+path 기반 랜딩 조회 - `POST /api/public/lead`: 리드 생성(폼 제출) - `GET /api/admin/campaigns` - `POST /api/admin/campaigns` - `GET /api/admin/pages` - `POST /api/admin/pages` - `GET/PUT /api/admin/pages/{id}/builder` - `GET/POST /api/admin/pages/{id}/conditions` - `POST /api/admin/pages/{id}/routes` - `GET /api/admin/leads` - `GET /api/admin/users` ### 9.4 1차 최소 화면(권장) - 로그인 - 관리자 대시보드 - 캠페인 목록/생성/수정 - 랜딩 목록/빌더 - 조건 규칙 편집(요일/시간 슬롯) - 도메인 라우팅 편집 - 리드 목록 조회 - 사용자/역할 관리(선택) ### 9.5 1차 제외(유지보수/확장으로 미루기) - 버전관리/롤백 - 예약 발행 - 내부 트래픽 분석 대시보드 - 결제/구독 - 다국어/SEO 고도화 ## 10. 1차 핵심 데이터 모델 설계(시작안) ### 10.1 엔티티 개요 - `Campaign`: 종목(광고 그룹) - 한 종목 아래 여러 랜딩 페이지 보유 - `LandingPage`: 실제 렌더링 대상 페이지 - 블록 데이터 저장(이미지/폼/버튼 등) - `LandingRoute`: 요청 도메인+경로의 기본 매핑 - 예: `aaa.com` + `/`, `aaa.com/google` - `RouteCondition`: 특정 시간/요일 규칙 매칭 시 교체할 페이지 지정 - `Lead`: 폼 제출 데이터 - `User`: 관리자/리드관리자 계정 ### 10.2 엔티티 관계 - Campaign 1:N LandingPage - Campaign 1:N LandingRoute - LandingRoute 1:N RouteCondition - LandingRoute N:1 LandingPage (기본 랜딩) - RouteCondition N:1 LandingPage (조건 매칭 시 보여줄 랜딩) - LandingPage 1:N Lead - Campaign 1:N Lead ### 10.3 권한 설계(최소) - `ADMIN` - 모든 관리자 화면 접근 - 캠페인/페이지/조건/도메인/사용자 관리 - `LEAD_MANAGER` - 리드 목록 조회만 가능 ### 10.4 최소 Prisma 스키마 초안(개념용) ```prisma enum UserRole { ADMIN LEAD_MANAGER } model Campaign { id String @id @default(cuid()) name String description String? isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt landingPages LandingPage[] routes LandingRoute[] leads Lead[] } model LandingPage { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) name String slug String? blocks Json // 블록형 에디터 JSON isDefault Boolean @default(false) isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt routes LandingRoute[] @relation("RouteDefaultPage") conditions RouteCondition[] leads Lead[] @@index([campaignId, isActive]) } model LandingRoute { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) host String // 예: aaa.com path String // 예: /, /google defaultPageId String defaultPage LandingPage @relation("RouteDefaultPage", fields: [defaultPageId], references: [id], onDelete: Restrict) isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt conditions RouteCondition[] leads Lead[] @@unique([host, path]) } model RouteCondition { id String @id @default(cuid()) routeId String route LandingRoute @relation(fields: [routeId], references: [id], onDelete: Cascade) pageId String page LandingPage @relation(fields: [pageId], references: [id], onDelete: Restrict) label String // 운영자 확인용 priority Int @default(0) // 높을수록 우선 isActive Boolean @default(true) startDate DateTime? endDate DateTime? timezone String? @default("Asia/Seoul") // 7자리 문자열: 0(sun)~6(sat) 1=적용 weekMask String @default("0000000") // 분 단위(0~1439) startMinute Int? endMinute Int? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Lead { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) pageId String page LandingPage @relation(fields: [pageId], references: [id], onDelete: Restrict) routeId String? route LandingRoute? @relation(fields: [routeId], references: [id], onDelete: SetNull) payload Json // 폼 데이터 sourceMeta Json? // ip, userAgent, referer 등 submittedAt DateTime @default(now()) } model User { id String @id @default(cuid()) email String @unique name String? password String // bcrypt 해시 role UserRole @default(ADMIN) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } ``` ### 10.5 조건 평가 규칙(우선순위) 1. 요청 호스트+path로 `LandingRoute` 조회 2. 해당 라우트의 `RouteCondition` 중 `isActive = true`만 대상 3. 현재 `day/time/date`가 조건(`weekMask`, `startMinute~endMinute`, `startDate~endDate`)에 일치하면 후보로 포함 4. 후보가 여러 개면 `priority desc, createdAt desc`로 정렬해 첫 번째 사용 5. 후보가 없으면 `defaultPageId` 페이지 렌더 ### 10.6 렌더 우선순위 및 폴백 - 매칭은 `exact` 방식(요청 path와 저장된 path가 완전 일치)으로 수행 - 라우트 미존재: 404 또는 안내 페이지 - `startMinute`/`endMinute`가 교차 구간(예: 20:00~06:00)인 경우 자정 넘김 처리 ### 10.7 버튼 블록 설정(카카오 포함) - 공통: `buttonType`, `label`, `style`, `url`, `target` - 카카오 버튼: - `kakaoClientId` - `kakaoSyncCode` 또는 `isKakaoSyncCodeInput` - `redirectUri` - 필요 시 스크립트 코드 블록 - 버튼 설정은 페이지 JSON 블록 단위로 저장 ### 10.8 빌더 최소 블록 타입 - `hero`(문구/배경) - `image_gallery`(이미지 나열) - `form`(입력 폼) - `button`(일반/카카오 버튼) - `footer` ## 11. 생성 규칙(공식 방식 고정) ### 11.1 원칙 - Nuxt 4, Elysia, Prisma, Bun의 프로젝트 생성/설정은 공식 문서/공식 CLI 기준으로만 수행 - 임의 경로/구조를 새로 만들지 않고, 공식 권장 생성물을 우선 사용 - 추후 코드 생성은 공식 패턴의 레이어를 유지하며, 기존 공식 파일 위에 기능만 추가 ### 11.2 프로젝트 초기화 규칙(요약) - Nuxt는 공식 `nuxi` 초기화/레이아웃/라우트 규칙 준수 - Elysia는 공식 앱 생성 및 플러그인 미들웨어 등록 순서 준수 - Prisma는 `backend` 기준 `prisma init` + `backend/prisma/schema.prisma` + `migrate` 기준 - Bun은 공식 실행 스크립트/패키지 실행 규칙 준수 ### 11.3 다음 작업 시 준수할 실행 순서(예정) 1. `Nuxt` 공식 생성 및 폴더 구조 확보 2. `Elysia` 공식 방식으로 API 엔트리 포인트 생성 3. `Prisma` 스키마를 공식 스키마 문법으로 정식화 4. `Pinia` 공식 store 패턴으로 상태영역 분리 5. 위 규칙에 맞는 페이지/라우트 파일만 추가 ## 12. 네트워크/운영 결정 반영(최종 합의안) ### 12.1 환경 기본값 - 로컬 DB: `dev.db` (SQLite) - 프론트엔드 포트: `3000` - API 포트: `4000` - 기본 타임존: `Asia/Seoul` ### 12.2 블록 편집 정책 - 블록은 드래그 앤 드롭으로 순서 변경 지원 - 핵심 블록 타입: 이미지 기반 섹션, 폼, 버튼, 푸터 - 카카오 버튼은 블록 단위 설정값으로 `kakaoSyncCode`(카카오 싱크 고유값) 입력 지원 ### 12.3 권한 정책 - 역할: `ADMIN`, `LEAD_MANAGER` 2개로 확정 - `ADMIN`: 모든 관리 기능 - `LEAD_MANAGER`: 리드 조회만 ### 12.4 도메인/경로 규칙 - 기본 도메인 예시: `aaa.com` 사용 - 경로 규칙은 현재 도메인+패스 매칭으로 처리하되, `/`(슬래시 단독 루트) 경로 사용 - 경로 충돌 방지를 위해 `aaa.com` 자체와 `/` 매핑을 동일한 기본 기준으로 운용 ### 12.5 exact와 prefix의 의미(확인용) - exact 매칭: 요청 경로가 저장된 경로와 완전히 같아야 매칭 - 예: 저장 경로가 `/google`이면 요청도 정확히 `/google`일 때만 매칭 - prefix 매칭: 저장된 경로가 요청 경로의 시작 부분이면 매칭 - 예: 저장 경로가 `/`이면 `/google`, `/landing` 모두 매칭(루트가 모든 경로 포괄) - 현재 1차는 `exact`로 고정 ## 13. 1차 정식 Prisma 스키마(실행형 초안) > SQLite 기준(예: `backend/prisma/schema.prisma`)으로 작성. PostgreSQL 전환 시에는 `provider = "postgresql"`로 교체. ```prisma generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } enum UserRole { ADMIN LEAD_MANAGER } model Campaign { id String @id @default(cuid()) name String description String? isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt landingPages LandingPage[] routes LandingRoute[] leads Lead[] } model LandingPage { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) name String slug String? blocks Json // 블록형 에디터 데이터(배열) isDefault Boolean @default(false) isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt defaultRoutes LandingRoute[] @relation("RouteDefaultPage") conditions RouteCondition[] leads Lead[] @@index([campaignId, isActive]) } model LandingRoute { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) host String // ex) aaa.com path String // ex) /, /google defaultPageId String defaultPage LandingPage @relation("RouteDefaultPage", fields: [defaultPageId], references: [id], onDelete: Restrict) isActive Boolean @default(true) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt conditions RouteCondition[] leads Lead[] @@unique([host, path]) } model RouteCondition { id String @id @default(cuid()) routeId String route LandingRoute @relation(fields: [routeId], references: [id], onDelete: Cascade) pageId String page LandingPage @relation(fields: [pageId], references: [id], onDelete: Restrict) label String priority Int @default(0) // 높을수록 우선 isActive Boolean @default(true) startDate DateTime? endDate DateTime? timezone String @default("Asia/Seoul") // 7자 문자열(일~토) ex) 0111100 weekMask String @default("0000000") startMinute Int? endMinute Int? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Lead { id String @id @default(cuid()) campaignId String campaign Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade) pageId String page LandingPage @relation(fields: [pageId], references: [id], onDelete: Restrict) routeId String? route LandingRoute? @relation(fields: [routeId], references: [id], onDelete: SetNull) payload Json // 폼 submit payload sourceMeta Json? submittedAt DateTime @default(now()) @@index([campaignId, submittedAt]) } model User { id String @id @default(cuid()) email String @unique name String? password String role UserRole @default(ADMIN) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } ``` 주의: - 위 스키마는 개념 정리 목적이며, SQLite에서 지원되지 않는 제약/체크 조건은 실제 마이그레이션 환경에서 조정 필요. - `RouteRelationDefaultPage`와 같은 별도 보조 모델은 사용하지 않음. ## 14. 라우팅/조건 매칭 알고리즘(1차: exact) ### 14.1 목적 - 요청 host/path에 대해 기본 페이지를 찾아서, 조건 규칙 매칭이 있으면 변형 페이지로 전환. ### 14.2 pseudocode ```ts // Elysia 핸들러에서 사용 function isWeekMatch(weekMask: string, now: Date, timezone: string): boolean { const tzNow = new Date(now.toLocaleString("en-US", { timeZone: timezone })) const day = tzNow.getDay() // 0=Sun..6=Sat return weekMask[day] === "1" } function inTimeRange(startMinute?: number | null, endMinute?: number | null, nowMinute: number): boolean { if (startMinute == null || endMinute == null) return true // no time restriction if (startMinute <= endMinute) { return nowMinute >= startMinute && nowMinute <= endMinute } // cross midnight: 예) 20:00~06:00 return nowMinute >= startMinute || nowMinute <= endMinute } function inDateRange(startDate: Date | null, endDate: Date | null, now: Date): boolean { if (startDate && now < startDate) return false if (endDate && now > endDate) return false return true } async function resolveLandingPage(host: string, path: string) { const route = await prisma.landingRoute.findFirst({ where: { host, path, isActive: true }, include: { defaultPage: true, conditions: true } }) if (!route) return null const now = new Date() const nowMinute = now.getHours() * 60 + now.getMinutes() const matched = route.conditions .filter((c) => c.isActive) .filter((c) => inDateRange(c.startDate, c.endDate, now)) .filter((c) => isWeekMatch(c.weekMask, now, c.timezone ?? "Asia/Seoul")) .filter((c) => inTimeRange(c.startMinute, c.endMinute, nowMinute)) .sort((a, b) => b.priority - a.priority || +new Date(b.updatedAt) - +new Date(a.updatedAt)) return matched.length > 0 ? matched[0].pageId : route.defaultPageId } ``` ### 14.3 라우트 우선순위 - 1단계: exact host+path 조회 (`AAA.com`, `/google` 정확히 일치) - 2단계: 조건 일치 페이지 선택(우선순위/최신 업데이트 순) - 3단계: 일치 조건 없으면 `defaultPageId` ## 15. 1차 API 계약(구현 시작점) ### 15.1 공개 API - `GET /api/public/route-by-host` - Query: `host`, `path` - Response: - `page`: blocks 포함 렌더 데이터 - `campaignId`, `pageId`, `routeId` - `status`: `ok | not_found` - `POST /api/public/lead` - Body: `campaignId`, `pageId`, `routeId`, `payload`, `sourceMeta` - Response: `{ ok: true }` ### 15.2 관리자 API(필수) - `POST /api/admin/auth/login` - `GET /api/admin/campaigns`, `POST /api/admin/campaigns` - `GET /api/admin/pages`, `POST /api/admin/pages`, `GET /api/admin/pages/:id`, `PUT /api/admin/pages/:id` - `GET /api/admin/pages/:id/route`, `PUT /api/admin/pages/:id/route` - `GET /api/admin/pages/:id/conditions`, `POST /api/admin/pages/:id/conditions`, `PATCH /api/admin/pages/:id/conditions/:conditionId` - `GET /api/admin/leads` - `GET /api/admin/users`, `POST /api/admin/users`, `PUT /api/admin/users/:id/role` ### 15.3 공통 응답 규칙(제안) - 인증 필요: `{ error: "unauthorized" }` - 권한 부족: `{ error: "forbidden" }` - 검증 실패: `{ error: "validation", details: [...] }` ## 16. 문서 분리(운영 모드) - 전략/결정: `docs/strategy.md` - DB/스키마: `docs/database.md` - 라우팅/조건 엔진: `docs/routing-conditions.md` - 화면/라우팅: `docs/ui-flow.md` - API 계약: `docs/api-spec.md` - 실행 코드(초안): - Prisma 스키마: `backend/prisma/schema.prisma` - 조건 라우팅 엔진: `backend/src/routing/resolveLandingPage.ts` 향후 구현을 진행할 때는 위 문서를 기준으로 업데이트하고, 필요 시 `landing-strategy.md`는 요약본으로 유지한다.