[BE/ADR] 큐레이션 피드 Read Model 분리

[Whale0928]

배경

현재 큐레이션 피드는 원본 JSON payload를 조회한 뒤 Response Spec의 x-feed 기준으로 투영하고, 필요한 x-graphql 값을 조회 시점에 보강한다.

원본 payload는 건당 최대 128KB이며 페이지 크기 10과 다음 페이지 확인용 1건을 함께 읽으면 이론상 약 1.4MB를 DB에서 애플리케이션으로 전송할 수 있다. 피드 조회 최적화는 필요하지만 이번 작업 범위에서는 구현하지 않고 후속 과제로 남긴다.

결정

• curation_extension.payload는 원본 데이터의 SSOT로 유지한다.
• 피드 조회용 파생 Read Model인 feed_source_payload를 별도로 저장하는 방향을 채택한다.
• feed_source_payload에는 Response Spec의 x-feed 필드와 피드 GraphQL 보강에 필요한 숨은 입력값(alcoholId 등)만 포함한다.
• GraphQL로 계산되는 통계값은 저장하지 않고 조회 시점에 보강한다.
• 큐레이션명, 이미지, 노출 기간 등 payload 외 공통 필드는 기존 Curation 값을 그대로 사용한다.
• 피드 API의 codes는 1개 이상 필수이며 여러 스펙 코드를 받을 수 있도록 한다.
• 기존 피드 응답 구조는 변경하지 않는다.

후속 작업

• feed_source_payload 및 스펙 버전 관리 방식 결정
• 생성·수정 트랜잭션에서 원본 payload와 피드 Read Model을 함께 갱신
• 기존 큐레이션 데이터 backfill 절차 마련
• x-feed 변경 시 대상 스펙의 Read Model 재생성 정책 마련
• 노출 조건, keyword, codes, cursor를 DB 조회 단계에서 적용
• Extension과 Spec 일괄 조회로 N+1 제거
• 동일 GraphQL 실행 계획 단위의 배치 보강 검토
• 기존 Product 피드 응답 호환성 회귀 테스트 추가

비고

동적 JSON_EXTRACT로 매 요청마다 스펙별 필드를 조합하는 방식은 중첩 배열 복원과 동적 SQL 복잡도가 높아 우선안에서 제외한다.

[Whale0928]

쓰기 경로와 읽기 경로가 모두 반영됐습니다. 후속 작업 체크리스트 현황을 갱신합니다.

완료

• 생성·수정 트랜잭션에서 원본 payload와 피드 Read Model을 함께 갱신 — API-server #677
• x-feed 변경 시 대상 스펙의 Read Model 재생성 정책 마련 — API-server #680
• 기존 큐레이션 데이터 backfill 절차 마련 — 별도 절차 없이 재생성이 겸합니다. feed_payload가 NULL인 레거시 행도 재생성 대상에 포함시켰습니다
• 기존 Product 피드 응답 호환성 회귀 테스트 추가 — 4개 스펙 각각 원본 경로와 feed_payload 경로 결과를 실제 파이프라인으로 비교합니다

남음

• 노출 조건, keyword, codes, cursor를 DB 조회 단계에서 적용
• Extension과 Spec 일괄 조회로 N+1 제거
• 동일 GraphQL 실행 계획 단위의 배치 보강 검토
• 스펙 버전 관리 방식 결정 (아래 참고)

ADR과 달라진 점

• 컬럼명: ADR은 feed_source_payload였으나 실제 구현은 feed_payload 입니다
• 빈 결과 표현: 남길 값이 없으면 NULL이 아니라 빈 컨테이너([]/{})를 저장합니다. NULL은 backfill 이전 레거시 행 전용 표시로 두어, 읽기 경로의 fallback 판정을 NULL 하나로 단순화했습니다

동작 확인 (개발 환경)

스펙 변경이 실제로 재생성을 유발하는지 배포로 확인했습니다.

큐레이션 스펙 리소스 동기화 완료: created=0, updated=4
큐레이션 feed_payload 무효화: specIds=[3], curations=14
큐레이션 feed_payload 재생성 완료: specIds=[3], curations=14

4개 스펙이 모두 갱신 대상이었지만 responseSpec이 실제로 바뀐 스펙 하나만 재생성됐습니다. PROGRAM은 requestSpec만 바뀌어 제외됐습니다. 변경 감지는 canonical JSON(키 재귀 정렬 + 실수 trailing zero 제거) SHA-256 비교로 판정합니다. MySQL JSON 컬럼이 키를 자체 정렬하고 Jackson 직렬화 표기가 경로마다 달라 단순 비교로는 매번 오탐하기 때문입니다.

재생성 후 시음회 14건의 feed_payload가 모두 채워져 backfill이 함께 해결됐습니다.

스펙 버전 관리 — 미결 항목이 실제 문제로 드러났습니다

Admin FE가 스펙 상세 schema를 specId + version 키로 브라우저에 캐시합니다 (#321). 그런데 스펙 리소스의 내용만 바꾸고 info.version을 올리지 않으면 이미 캐시한 어드민에게는 변경이 반영되지 않습니다. 재검증 시점에도 version만 비교하므로 무기한 stale입니다.

#344 작업에서 실제로 이 상황이 발생해, 스펙 리소스의 info.version을 올리는 것으로 조치했습니다. CurationSpecResourceReader.parseMajorVersion이 major 자리만 사용하므로 2.0.0 → 3.0.0처럼 major를 올려야 DB version이 바뀝니다.

스펙 내용 변경 시 version 승격을 강제하는 규칙이 필요합니다. 이 이슈의 "스펙 버전 관리 방식 결정" 항목으로 남깁니다.

관련 PR

• API-server #677 — feed_payload 컬럼 및 쓰기 경로
• API-server #680 — 변경 감지, 재생성, 읽기 경로 전환
• API-server #681 — 시음회·프로그램 장소검색 계약 정렬 ([BE] Curation v2 시음회·프로그램 장소검색 requestSpec 계약 정렬 #344)

[bottlenote-app]

리포지토리 동기화 근거입니다.

• 소스 보고서: /home/hgkim/.hermes/profiles/arran/reports/repo-activity/2026-07-28/bottle-note-api-server.md (SHA-256: 16e0303a1393d9c88dd294011123d0e9990fb00c93ecbfebb9149e28962ffe5f)
• API-server PR #677과 PR #680은 본문에서 workspace #322를 명시 참조하며, main 병합 SHA는 각각 0676c74b90d9a0e0f5ea22d08a58fa167029850e, 28976f65f2b66488e76bba75ce75297685e0cad3입니다.
• 같은 SHA의 개발 배포 run 30324667121과 run 30342688307은 모두 completed/success입니다.
• 최신 backend/v1.1.16 릴리즈의 target SHA는 2c29c1aa89e956e2195f9971ccac9eff8ef4a3ed이며, 릴리즈 노트에 workspace [BE/ADR] 큐레이션 피드 Read Model 분리 #322 명시 참조가 없습니다.

현재 상태: 개발배포를 유지합니다. 이슈 본문의 미완료 후속 작업, 실제 개발 환경 수용 QA, 운영 릴리즈·배포 및 운영 QA가 미확인이므로 상태: 운영배포 또는 종결 근거는 없습니다.