본문으로 건너뛰기

Homepage 모듈

학원 테넌트별 공개 랜딩 홈페이지 설정(섹션 구성, 템플릿 선택)을 저장·조회·공개 전환하는 모듈입니다.

모듈 개요​

항목내용
Gradle 서브프로젝트modules/homepage
베이스 패키지com.lumie.homepage
데이터베이스PostgreSQL (멀티테넌트 RLS, homepage_config 테이블)
내부 의존TenantService (public 조회 시 테넌트 슬러그 검증)

주요 책임​

  • 테넌트별 홈페이지 설정(템플릿 ID, 섹션 JSON) 저장·수정 (OWNER 전용)
  • 미저장 테넌트에는 기본 설정(transient default)을 반환 — GET /v1/homepage가 항상 200을 반환
  • published 플래그를 통한 공개/비공개 전환
  • 커스텀 ID 기반 익명 공개 조회 (/public/by-custom-id/{customId}, published=true인 경우만)

도메인 모델​

HomepageConfig 엔티티​

@Entity
@Table(name = "homepage_config")
public class HomepageConfig extends TenantScopedEntity {
    Long id; @Version Long version;
    TemplateId templateId;      // SOLO_INSTRUCTOR 등 템플릿 유형
    int templateVersion;        // 현재 CURRENT_TEMPLATE_VERSION = 3
    boolean published;
    String sections;            // 섹션별 설정 JSON (JSONB)
}

기본 설정 (defaultConfig)​

테넌트가 한 번도 저장하지 않은 경우 HomepageConfig.defaultConfig()가 반환됩니다. 이 객체는 DB에 저장되지 않으며 (id == null), 프런트엔드가 항상 유효한 구조를 렌더링할 수 있도록 합니다.

{
  "hero": {
    "enabled": true,
    "welcomeMessage": "",
    "kakaoChannelUrl": "",
    "backgroundImageId": null,
    "backgroundImageUrl": null
  }
}

TemplateId​

현재 지원 템플릿: SOLO_INSTRUCTOR (단일 강사형)

REST API​

기본 경로: /v1/homepage

메서드경로인증설명
GET/v1/homepage인증 필요현재 테넌트 홈페이지 설정 조회 (미설정 시 기본값 반환)
PUT/v1/homepageOWNER홈페이지 설정 저장·수정 (upsert)
POST/v1/homepage/publishOWNER공개(published=true) 또는 비공개 전환
GET/v1/homepage/public/by-custom-id/\{customId\}익명커스텀 ID 기준 공개 홈페이지 조회 (published=false이면 404)

PUT /v1/homepage 요청 예시​

{
  "templateId": "SOLO_INSTRUCTOR",
  "templateVersion": 3,
  "sections": {
    "hero": {
      "enabled": true,
      "welcomeMessage": "환영합니다",
      "kakaoChannelUrl": "https://pf.kakao.com/...",
      "backgroundImageId": 42,
      "backgroundImageUrl": "https://..."
    }
  }
}

POST /v1/homepage/publish 요청 예시​

{ "published": true }

sections이 비어 있거나 {} / []인 경우 NOT_READY_TO_PUBLISH 오류가 발생합니다.

공개 조회 흐름​

GET /v1/homepage/public/by-custom-id/{customId}
  └─> HomepageQueryService.getPublicByCustomId(customId)
        ├─ TenantLookupPort(TenantService) — customId → tenantId 조회
        ├─ HomepageConfigRepository.findByTenantId()
        └─ published=true인 경우만 반환, 그 외 Optional.empty() → 404

멀티테넌시​

homepage_config 테이블에 tenant_id BIGINT NOT NULL이 있으며 RLS 정책이 적용됩니다. 테넌트당 최대 1건의 설정 레코드를 가집니다.

관련 문서​