Ghost 태그 체계 개편 및 Next.js 홈 큐레이션 연동 개발 구현 명세

다음은 Ghost 태그 체계 개편 및 Next.js 홈 큐레이션 연동 개발 구현 명세의 정식 문안이다

1. 문서 목적

본 명세는 Ghost CMS의 태그 구조를 재정의하고, 해당 태그를 기반으로 Next.js 홈 화면 큐레이션 영역을 일관되게 구성하기 위한 개발 구현 기준을 정의한다.
대상 범위는 다음과 같다.

• Ghost 태그 분류 체계
• Ghost Content API 조회 규칙
• Next.js 내부 정규화 응답 구조
• 홈 큐레이션 섹션 필터링 및 노출 규칙
• 타입 설계 기준
• 예외 처리 및 운영 규칙

2. 전제 조건

현재 시스템은 다음 구조를 전제로 한다.

• Ghost는 콘텐츠 원본 저장소(CMS)이다.
• Next.js는 고객 노출용 프론트엔드이다.
• FOLDERS 설정은 폴더(대분류) 순서 및 메타데이터를 담당한다.
• 게시물 조회는 Ghost Content API를 통해 수행한다.
• 현재 목록 정렬 기본값은 published_at DESC이다.

3. 태그 체계 개편 기준

3.1 태그 유형

Ghost 태그는 아래 3종으로 구분한다.

3.2 폴더 태그 규칙

• 각 게시물은 고객 탐색 기준이 되는 대표 분류를 가져야 한다.
• 해당 분류는 Ghost의 primary_tag로 해석한다.
• primary_tag.slug는 Next.js의 FOLDERS.slug와 정확히 일치해야 한다.
• 폴더 태그는 URL 경로 및 브레드크럼 기준값으로 사용한다.

3.3 홈 큐레이션 태그 규칙

• 홈 큐레이션 태그는 섹션 편성 전용 태그로 사용한다.
• 운영 입력 예시는 다음과 같다.

• name은 운영자 식별용 표기값이다.
• slug는 프로그램 식별값이다.
• description은 섹션 제목 또는 운영 메모의 원천 데이터로 사용할 수 있다.
• 고객 화면에는 # 접두사를 직접 노출하지 않는다.

4. 홈 큐레이션 도메인 모델

4.1 섹션 정의 기준

홈 큐레이션 섹션은 Ghost 태그만으로 완결하지 않고, 프론트엔드 설정과 결합하여 정의한다.

4.2 설계 원칙

• Ghost 태그는 “게시물 포함 여부”만 결정한다.
• 홈 화면 문구, 순서, 개수, UI 메타데이터는 Next.js 설정이 최종 기준이다.
• 따라서 Ghost는 편집 권한, Next.js는 표현 권한을 가진다.

5. 데이터 조회 규칙

5.1 Ghost 조회 단위

홈 큐레이션은 섹션별로 Ghost에서 게시물을 조회한 뒤 정규화한다.

기본 조회 기준:

5.2 필수 조회 필드

게시물 정규화에 필요한 최소 필드는 다음과 같다.

6. 내부 응답 구조 명세

6.1 홈 큐레이션 응답 단위

Next.js 내부에서는 홈 데이터를 아래 구조로 정규화한다.

HomeResponse

HomeSection

CuratedPostSummary

FolderRef

TagRef

7. 타입 설계 기준

7.1 Ghost 원본 타입

Ghost 응답 타입은 CMS 원형 보존 목적의 소스 타입으로 유지한다.

• GhostPost
• GhostTag

7.2 애플리케이션 타입

프론트엔드에서 직접 사용하는 타입은 별도 정규화 타입으로 분리한다.

7.3 분리 원칙

• Ghost 타입과 화면 타입을 혼용하지 않는다.
• Ghost 필드명(published_at)은 정규화 후 앱 표준 필드명(publishedAt)으로 변환한다.
• 화면 컴포넌트는 정규화 타입만 소비한다.

8. 필터링 규칙

8.1 기본 포함 조건

게시물이 특정 홈 섹션에 포함되려면 아래 조건을 모두 만족해야 한다.

1. 게시물 상태가 published일 것
2. tags 배열에 해당 curationTagSlug가 존재할 것
3. primary_tag.slug가 존재할 것
4. primary_tag.slug가 FOLDERS 설정에 존재할 것

8.2 제외 조건

아래 조건 중 하나라도 만족하면 홈 큐레이션에서 제외한다.

1. primary_tag가 없는 경우
2. primary_tag.slug가 프론트엔드 폴더 설정에 없는 경우
3. 큐레이션 태그만 있고 공개 분류 태그가 없는 경우
4. 비공개/초안/예약 상태인 경우
5. 필수 필드(id, slug, title)가 비어 있는 경우

8.3 폴더 제한 규칙

• 섹션별로 allowedFolderSlugs를 둘 수 있다.
• 값이 지정된 경우, 해당 목록에 포함되는 폴더의 게시물만 노출한다.
• 값이 비어 있으면 모든 폴더 허용으로 간주한다.

8.4 중복 규칙

• 동일 게시물이 여러 큐레이션 태그를 가진 경우 복수 섹션에 포함될 수 있다.
• 단, 홈 화면 전체 중복 노출을 금지하려면 섹션 우선순위 기준으로 1회만 노출한다.
• 기본 권장 정책은 중복 제거이다.
• 중복 제거 순서는 priority ASC 기준으로 처리한다.

8.5 정렬 규칙

기본 정렬은 다음과 같다.

1. 최신 발행일 내림차순
2. 동률 시 제목 오름차순

별도 수동 정렬 기능은 본 범위에 포함하지 않는다.

8.6 개수 제한 규칙

• 각 섹션은 limit 수만큼만 노출한다.
• 필터링 후 남은 게시물이 limit보다 적으면 가능한 수량만 노출한다.
• 결과가 0건이면 해당 섹션은 숨김 처리한다.

9. 홈 화면 연동 규칙

9.1 렌더링 순서

홈 섹션은 프론트엔드 설정의 priority 또는 배열 순서대로 렌더링한다.
Ghost 태그 생성 순서나 발행 순서는 섹션 순서에 영향을 주지 않는다.

9.2 카드 노출 기준

각 카드에는 최소 아래 정보를 노출한다.

• 제목
• 요약
• 폴더명
• 발행일
• 썸네일(있을 경우)

9.3 링크 규칙

게시물 상세 링크는 아래 규칙을 따른다.

• 경로 형식: /{folderSlug}/{postSlug}
• folderSlug는 반드시 primary_tag.slug 기준으로 생성한다.

10. API 계약 기준

10.1 Ghost Content API 입력 계약

Ghost 조회 시 애플리케이션이 의존하는 최소 계약은 다음과 같다.

10.2 프론트엔드 내부 서비스 계약

홈 데이터 생성 서비스는 아래 입력/출력 계약을 가진다.

입력

• 홈 섹션 설정 목록
• Ghost 조회 결과 목록

출력

• HomeResponse

10.3 장애 시 계약

• 특정 섹션 조회 실패 시 전체 페이지를 실패 처리하지 않는다.
• 실패 섹션은 빈 배열로 대체하거나 숨김 처리한다.
• 전체 Ghost 연결 실패 시 홈 큐레이션 전체를 비노출 처리하고, 폴더 기반 기본 화면만 유지할 수 있어야 한다.

11. 검증 규칙

11.1 설정 검증

배포 전 아래 항목을 검증한다.

1. sectionKey 중복 금지
2. curationTagSlug 중복 금지
3. FOLDERS.slug 중복 금지
4. 홈 섹션의 allowedFolderSlugs가 모두 유효한 폴더 slug인지 검증
5. limit는 1 이상의 정수인지 검증

11.2 콘텐츠 검증

운영 시 아래 상태를 검출 가능해야 한다.

1. 큐레이션 태그는 있으나 primary_tag가 없는 게시물
2. primary_tag는 있으나 프론트엔드 폴더 설정에 없는 게시물
3. 홈 섹션에 0건만 반환되는 큐레이션 태그
4. 동일 게시물이 과도하게 중복 편성된 상태

12. 운영 규칙

12.1 운영자 작업 규칙

운영자가 홈에 게시물을 노출하려면 다음 절차를 따른다.

1. 게시물에 공개 분류용 폴더 태그를 지정한다.
2. 필요 시 홈 큐레이션용 태그를 추가한다.
3. 홈 섹션 제목/설명/순서는 프론트엔드 설정에서 관리한다.

12.2 변경 책임 분리

13. 최종 결론

본 개편의 핵심은 다음 두 가지다.

1. 폴더 태그와 홈 큐레이션 태그의 역할을 분리한다.
   • 폴더 태그: 정보 구조
   • 큐레이션 태그: 편성 구조
2. Ghost는 포함 여부만, Next.js는 표현 정책을 담당한다.
   • Ghost 태그만으로 화면 구조를 결정하지 않는다.
   • 화면 제목, 설명, 정렬, 제한 개수는 프론트엔드 명세가 최종 기준이다.