🧩

브랜드위크 CMS 만들기: 템플릿화된 CMS와 폴리몰픽 JSONB

Created
2026/07/22
Tags
Kotlin
SpringBoot
Design Pattern
DB
json
 
2026-07-22 @이영훈
 

개요

브랜드위크 같은 프로모션 페이지는 브랜드/시즌마다 레이아웃은 비슷한데 섹션이 한두 개씩 더 붙거나 빠져요. 이걸 매번 새 화면으로 개발/배포하면 "마케팅 의사결정 → 개발 큐 진입 → 배포 → 노출" 사이클이 너무 길고, 딜 상품 그리드, 카운트다운, 보상 요약 같은 컴포넌트가 매번 조금씩 변형된 코드로 복제됩니다.
그래서 어드민에서 페이지를 조립해 앱/웹으로 내려주는 CMS를 만들었어요. 이 글은 그 과정에서 했던 핵심 설계 의사결정을 정리합니다. 왜 SDUI가 아니라 "템플릿화된 CMS"인지, 왜 섹션을 폴리몰픽 JSONB로 저장했는지, sealed class로 얻은 컴파일 타임 안전망, 그리고 운영하며 겪은 함정들을 다뤘어요.
 
 

본문

의사결정: SDUI가 아닌 "템플릿화된 CMS"

본격적인 SDUI(서버가 임의의 위젯 트리를 내려주는 방식)는 자유도가 큰 만큼 비용도 커요. 클라이언트가 임의의 위젯 컴포지션을 렌더할 수 있어야 하고, 에디터/시각화 도구까지 같이 만들어야 합니다. 현 단계에서는 절충안을 택했어요.
  • 템플릿은 개발자가 코드로 정의: PageTemplate sealed class. 어드민은 템플릿 안에서 허용된 섹션을 켜고/끄고/순서 바꾸고/콘텐츠를 채우는 일만 함
  • 섹션 종류는 서버에서 고정: CmsSectionType enum. 클라이언트는 각 타입을 어떻게 그릴지 이미 앎
  • 섹션 콘텐츠는 폴리몰픽 JSONB: SectionData sealed class, 타입마다 스키마가 다름
 
커머스로 치면 Airbnb/Lyft식 Server Driven UI보다 Shopify의 테마+섹션 모델에 가까워요. 운영 자유도와 구현 비용을 저울질한 결과이고, 나중에 필요해지면 자연스럽게 SDUI로 진화할 수 있는 기반이기도 합니다.
 

핵심 개념

한 페이지에 깔리는 그림은 이렇습니다.
javascript
CmsPage (1) ──── 1:N ──── CmsPageSection
  - templateType                - sectionType
  - title / 노출기간             - displayOrder / isHidden
  - theme (primary/secondary/point)  - sectionData (JSONB, 폴리몰픽)
  └ PageTemplate(코드): requiredSections / allowedSections / defaultLayout
  • Page: 어드민이 만드는 인스턴스. 어느 템플릿을 따르는지 + 노출 기간/제목/테마
  • Template: 코드 상수(sealed object). 이 템플릿의 필수 섹션/허용 섹션/기본 레이아웃 규칙
  • Section: 페이지에 붙는 콘텐츠 블록. 타입 + 순서 + 데이터
  • SectionData: 섹션 타입별 sealed 데이터 클래스. JSONB로 저장되고 @JsonTypeInfo(name="type")로 폴리몰픽 직렬화
 
페이지가 "템플릿을 따른다"는 건 저장 시 CmsPageDomainService가 강제합니다. 필수 섹션이 다 있는지, 허용되지 않은 섹션이 없는지, 그리고 앵커 탭이 가리키는 dealId가 같은 페이지의 그리드 섹션에 실제로 존재하는지(무결성)를 검증해요.
 

왜 섹션을 JSONB로 저장했나

가장 큰 선택은 SectionData를 JSONB + sealed class 폴리몰픽으로 저장한 것입니다. 섹션 타입별 정규화 테이블(section_image_banner, section_reward_summary …)과 비교했어요.
ㅤ
JSONB (채택)
정규화 테이블
섹션 타입 추가
sealed 서브타입 + @JsonSubTypes 한 줄
신규 테이블 + 마이그레이션 + JPA 매핑
조회
row → 직렬화로 끝
polymorphic query / join
내부 필드 검색
GIN 인덱스 별도 필요
표준 인덱스
 
CMS는 "페이지 단위로 통째로 읽고 통째로 쓰는" 패턴이고, 섹션 내부 필드를 SQL로 검색할 일이 거의 없어요. 그래서 JSONB가 명백히 우위라고 판단했습니다. 섹션 내부 검색이 필요해지는 시점이 오면 핵심 필드만 정규화 컬럼으로 빼는 보조 패턴을 도입하면 돼요.
 

sealed class = 컴파일 타임 안전망

폴리몰픽을 Map이나 generic 구조가 아니라 sealed class로 간 이유는 컴파일러가 모든 케이스를 검사해주기 때문입니다. 어드민이 보낸 sectionData JSON은 "type" 필드로 어느 서브타입으로 역직렬화될지 결정되고, PageTemplate.of()의 when이나 GraphQL union resolver에서 새 섹션을 잊고 빠뜨리면 컴파일이 깨지거나 스키마 검증이 실패해요. 실수를 런타임이 아니라 빌드 타임에 잡는 의도된 안전망입니다.
 
⚠️
가장 디버그하기 어려웠던 함정: Hibernate가 JSON 컬럼을 다룰 때 Spring의 ObjectMapper를 쓰도록 강제하지 않으면(CmsHibernateJsonConfig의 FormatMapper 주입 누락), Kotlin/sealed/Jackson 옵션 차이로 라운드트립이 깨집니다. "저장은 되는데 읽을 때 null/예외"라는 최악의 형태로 나타나요. admin/api 양쪽에 동일하게 있어야 하고, 새 모듈이 cms 엔티티를 다루면 이 설정을 복제해야 합니다.
 

PUT 전체 갈아끼우기

어드민 수정은 PATCH per 섹션이 아니라 PUT으로 sections 배열을 통째로 받아요.
  • 요청 섹션에 id가 있고 기존에 있으면 → in-place update (타입 변경은 reject)
  • id가 없으면 → 신규 insert
  • 요청에 없는 기존 id → soft delete
 
장점은 어드민 UI가 "현재 화면 상태 그대로 보내기"만 하면 되고(diff 책임을 서버로 위임), 검증을 페이지 단위로 한 번에 해서 중간 상태가 invalid해지지 않는다는 것이에요. 단점은 동시 편집이 last-write-wins라는 점인데, 현재 운영 규모(어드민 소수, 동시 편집 거의 없음)에서는 단순함이 더 큰 가치라 판단했고, 문제가 되면 updatedAt 기반 optimistic lock을 붙이는 걸 다음 step으로 남겨뒀습니다.
 

v2 프리미티브: 타입 폭발을 축으로 분리

운영하다 보니 "비슷한데 조금씩 다른" 섹션 변형(딜 그리드/추천 리스트/태그 리스트 같은 큐레이션 표현들)이 계속 늘었어요. 매번 새 섹션 타입을 찍는 대신, 직교하는 축을 분리해 정규화한 v2 프리미티브를 추가형으로 도입했습니다(기존 타입은 무손상 유지, JSONB라 DB 마이그레이션 없음).
  • source: 무엇을, 어떤 순서로 가져올까 (BY_DEAL/BY_TAGS/BY_DEAL_PRODUCT_IDS/BY_MONGO_PRODUCT_IDS + sort)
  • layout: 모양의 하위 형태 (columns/rows/variant)
  • style: 제목, 색, cardStyle 등 표현
 
"새 변형"이 이제 새 타입이 아니라 이 축들의 값이 바뀌는 것이 돼요. GRID가 기존 DEAL_PRODUCT_GRID/FEATURED_PRODUCT_LIST/TAGGED_PRODUCT_LIST를 흡수하는 식입니다. 여러 리프 섹션을 공통 배경/헤더로 묶는 GROUP 컨테이너도 넣었는데, 복잡도 폭발을 막으려고 GROUP 안의 GROUP은 금지(1단계 중첩만)했어요.
 
💡
source/layout/style을 sealed가 아니라 flat한 data class로 둔 건, 어드민 폼 자동 생성기가 중첩 data class/enum/List는 풀지만 sealed 필드는 UNKNOWN으로 떨구기 때문입니다. 그래서 ProductSource는 kind enum + nullable 필드 + init 검증의 평평한 구조예요. 도구의 제약이 모델 설계를 역으로 규정한 케이스.
 

정리 / 배운 것

  • 자유도와 비용의 절충: 풀 SDUI 대신 템플릿화된 CMS. 지금 필요한 운영 자유도를 최소 비용으로 확보하고, 진화 경로(섹션 트리 중첩 → 템플릿 데이터화)를 열어둠
  • 읽기/쓰기 패턴이 저장 방식을 결정: 페이지 통째 read/write라서 JSONB가 정답. 검색 요구가 생기면 그때 정규화
  • sealed class로 실수를 빌드 타임에: 새 타입 누락 = 컴파일 에러
  • 검증은 4계층에 의도적으로 분산: DTO / VO init / 엔티티 / 도메인 서비스. 어느 입구(REST, GraphQL, 배치)로 들어와도 금지된 상태는 영속화 안 됨
  • 함정은 대부분 경계에 있다: Hibernate JSON FormatMapper처럼 프레임워크 기본값에 맡기면 조용히 깨지는 지점
 
❄️
최초 작업: COM-2545, PR #4625. 코드 위치: packages/product/{domain,admin,api}/.../cms, DDL: ddl/cms/. 온보딩 문서: docs/domain/cms/README.md