[WORKSOUT] 피드 메인

화면 정보

Screen ID	Screen Title	Screen Path
FEED-01	피드 메인	`/feed`

개요

에디토리얼, 뉴스, 숏폼, 웨어(WEAR) 네 가지 콘텐츠 유형을 하나의 통합 그리드로 노출하는 피드 메인 화면. HBLAB 통합 Feed API로 콘텐츠를 편성하고, 찜(좋아요) 기능과 무한 스크롤을 제공한다.

용어 정의

용어	설명
피드	사용자에게 제공되는 콘텐츠의 흐름식 표시 형태
Masonry Grid	다양한 높이의 콘텐츠를 타일 형태로 배치하는 레이아웃 방식
무한스크롤	화면 하단 도달 시 자동으로 추가 콘텐츠를 로드하는 방식
찜(좋아요)	사용자가 콘텐츠에 관심을 표시하는 기능
스켈레톤 UI	콘텐츠 로딩 중 보여주는 임시 레이아웃

화면 구성

통합 피드 그리드

항목	기준
레이아웃	Masonry Grid 2열
썸네일 비율	세로형/가로형에 따라 카드 높이 자동 조정
기본 정렬	최신순, 실제 편성 결과는 통합 Feed API 응답 순서 우선
WEAR 삽입 규칙	정책상 5번째마다 배치 (서버 편성 규칙)
스크롤 방식	무한 스크롤
빈 상태 문구	`표시할 컨텐츠가 없습니다`
리프레시	맨 위로 당겨서 새로고침

콘텐츠 카드 공통 구성

요소	규칙
썸네일	`imageUrl`. 가로형 비율 썸네일이면 상세 화면도 가로비율에 맞춰 노출
제목	카드 너비에 맞춰 표시, 초과 시 말줄임표
하트 버튼	로그인 사용자만 사용 가능. 비로그인 클릭 시 로그인 안내 팝업 노출
비디오 자동 재생	왼쪽 위 카드부터 순차 재생, 동시 재생 방지, 소리 없이 재생
이미지 썸네일	정적으로 표시

콘텐츠 타입별 제목 필드

타입	제목 필드
WEAR	`ProductName`
Shortform	어드민 설정 Title
Editorial / News	Strapi `title` 필드

카드 클릭 시 상세 분기

타입	이동 화면
Editorial	에디토리얼 상세
News	뉴스 상세 (에디토리얼 상세 템플릿 재사용 — 아래 미결 사항 참조)
Shortform	숏폼 상세
Wear	웨어 상세

로딩 상태

시점	처리
초기 로딩	전체 영역 스켈레톤 UI
무한 스크롤 추가 로딩	하단 스켈레톤 카드
개별 이미지 로딩	카드 단위 스켈레톤 유지

소스별 운영 기준

콘텐츠 타입	관리 소스	운영 기준
Editorial / News	Strapi	게시 상태, 제목, 썸네일, 노출기간 관리
Shortform	HBLAB / ByteDance	승인 상태(`APPROVED`), 노출 상태(`exposureStatus = true`)
Wear	상품 시스템	상품 노출 상태 + 피팅컷(20번째 이미지) + `along_with_product_codes` not null + `new_arrival = 1`

WEAR 자동 노출 조건

WEAR는 별도 어드민 등록 없이 상품 데이터 조건을 만족할 때만 자동으로 피드에 편성된다.

조건	관리 위치
상품 노출 상태	상품 어드민
20번째 이미지(피팅컷) 보유	상품 이미지 관리
`along_with_product_codes` not null	상품 어드민
`new_arrival = 1`	상품 어드민

조건 중 하나라도 미충족하면 실시간으로 피드에서 자동 제거된다.
피팅컷 이미지 유무가 WEAR 노출의 핵심 조건이다.
웨어 노출 조건 요약: 신상품이면서 피팅컷 이미지가 있고 노출 설정이 되어있는 상품.

찜한 피드 카드 및 상세

항목	기준
노출 조건	찜한 콘텐츠 1개 이상일 때만 표시
위치	피드 레이아웃 최상단 왼쪽 (고정)
카드 표기	`찜한 피드(N)` — N = 찜한 콘텐츠 총 수
미리보기 썸네일	최신 3개, 가장 최근 찜한 이미지가 왼쪽부터 배치
카드 클릭	찜한 피드 전체 목록 페이지로 이동

찜한 피드 상세 페이지

항목	기준
레이아웃	메인 피드와 동일한 Masonry Grid
정렬	`likeTime DESC` — 최근 찜한 순서
하트 해제	UI 즉시 반영, 실제 목록 제거는 새로고침 후 (실수 방지 목적)

찜하기 기능

상태	처리
로그인 사용자	하트 탭 시 찜 상태 토글
비로그인 사용자	로그인 화면으로 자동 이동 / 로그인 안내 팝업
세션 만료	`로그인이 필요합니다` 메시지 후 로그인 화면 이동
성공	`visible: true` → 채워진 하트 / `visible: false` → 빈 하트
실패	하트 상태 롤백 + 오류 토스트 또는 재시도 버튼

찜 추가 실패 메시지: 관심 목록 추가에 실패했습니다
찜 제거 실패 메시지: 관심 목록 제거에 실패했습니다

네비게이션

각 콘텐츠 클릭 시 해당 콘텐츠 타입에 맞는 상세 페이지로 이동한다.
상세 페이지에서 뒤로가기 시 이전 스크롤 위치가 유지된다.

컨텐츠 정책 (피드 전체 공통, 피드 메인 관련 범용 규칙)

컨텐츠 유형

피드에는 에디토리얼, 뉴스, 숏폼, 웨어 네 가지 유형이 표시된다. 컨텐츠 타입은 랜덤으로 섞여 표시되며 모든 타입은 동일한 카드 표시 형식을 따른다(썸네일 미디어 유형만 차이).

컨텐츠 관리 방식

유형	관리 방식
에디토리얼 / 뉴스	어드민 컨텐츠 관리에서 관리, 에디터 도구로 생성
숏폼	어드민 숏폼 관리에서 등록, 관리자 승인 시 노출 설정 가능
웨어(WEAR)	조건 충족 시 배치 프로세스를 통해 자동 노출 (어드민 별도 등록 없음)

조회수 집계 방식

웨어를 제외한 모든 콘텐츠는 조회수·관심수(좋아요)를 DB에서 수집한다. 웨어 콘텐츠는 앰플리튜드(Amplitude)로 데이터 수집.
조회수 집계 기준:
- 비디오 콘텐츠: 재생이 실제로 시작될 때 집계
- 이미지 콘텐츠: 이미지가 완전히 로드되어 화면에 표시될 때 집계
- 복합 콘텐츠: 첫 번째 콘텐츠가 위 조건을 충족할 때 집계
view_score는 콘텐츠 클릭 시 집계되며 IP당 1시간 제한이 적용된다. 숏폼은 조회수(total) 방식으로 집계된다.
백오피스는 약 5분 간격으로 조회수를 실시간에 가깝게 업데이트한다.
위 조건은 피드에서 상세 페이지로 이동하는 경로와 공유 링크를 통한 접근 모두에 동일하게 적용된다.

사용자 상호작용 (공통)

모든 콘텐츠에는 좋아요와 공유하기 버튼이 제공된다. 좋아요는 토글 방식.
콘텐츠 공유 시 링크와 썸네일 이미지 형태로 공유되며, 공유 링크는 웹과 앱 모두에서 접근 가능하고 앱 설치 유도 기능을 포함한다(숏폼 제외 — 숏폼은 앱에서만 접근 가능).

API 연동 명세

통합 피드 조회

엔드포인트: GET /v1/contents/feed-list
호출 시점: 피드 화면 진입 시 / 무한 스크롤 추가 로드 시
활용 필드: FeedType(상세 화면 분기: editorial/news/shortform/wear), imageUrl(썸네일), title(제목), 노출기간, isLiked(하트 UI 상태)
운영 메모: FeedType 값의 대소문자 표기가 원문에서 혼재(editorial, News, shortform, wear). 실제 처리 시 서버 enum 스펙을 최종 기준으로 확인해야 한다.

찜한 피드 조회

엔드포인트: GET /v1/contents/feed/wishlist
찜 개수 조회: GET /v1/contents/feed/wishlist-count
호출 시점: 피드 화면 진입 시 / 찜한 피드 목록 페이지 진입 시
활용 필드: totalElements(찜한 피드 카드 N값), content[0~2].imageUrl(미리보기 최신 3개), content(전체 목록), likeTime(정렬 기준), feedType, documentId/id/slug/vid(상세 이동 식별값)

엔드포인트: PUT /v1/contents/feed/like
호출 시점: 하트 버튼 클릭 시
요청 데이터: targetId(콘텐츠 ID), targetType(EDITORIAL/NEWS/WEAR/SHORTFORM), source(CARHARTT/WORKSOUT)
응답 처리: payload.visible = true → 채워진 하트 / payload.visible = false → 빈 하트 / 실패 시 하트 상태 롤백

정책

에러 처리 및 예외 상황

증상	예상 원인	1차 조치
피드 전체 비어 있음	통합 Feed API 실패 / 데이터 없음	API 응답 확인 후 서버 로그 요청
찜한 피드 카드 안 뜸	Wishlist API 실패 / 찜 0개	찜 개수와 인증 상태 확인
WEAR만 전부 사라짐	피팅컷/연관상품/신상품 조건 미충족	상품 데이터 조건 재점검
자동 재생 안 됨	비디오 재생 실패 / 네트워크 이슈	정적 썸네일 fallback 여부 확인
무한 스크롤 추가 로딩 실패	페이지네이션 오류 / 네트워크 불안정	재시도 버튼 노출 여부 확인
이미지 로딩 실패	CDN 오류 / URL 오류	기본 플레이스홀더 이미지 대체 여부 확인

성능 및 최적화

초기 로딩은 전체 영역 스켈레톤 UI, 무한 스크롤 추가 로딩은 하단 스켈레톤 카드로 처리한다.
개별 이미지 로딩 중에도 카드 단위 스켈레톤을 유지한다.

시나리오

케이스	동작
로그인 사용자가 하트 탭	찜 상태 즉시 토글, API 호출 후 실패 시 롤백
비로그인 사용자가 하트 탭	로그인 안내 팝업 노출 후 로그인 화면 이동
찜한 피드 상세에서 하트 해제	UI 즉시 하트 비움, 목록에서 실제 제거는 새로고침 후 반영
하단 스크롤 도달	무한 스크롤로 추가 콘텐츠 로드
콘텐츠 0개	`표시할 컨텐츠가 없습니다` 빈 상태 문구 표시

미결 사항

항목	내용
콘텐츠 제목 줄수	마스터 문서 기준(2025-08-19 최종 수정) “최대 2줄, 초과 시 말줄임표”, 정책 문서 기준(2025-10-29 최종 수정, 더 최신) “최대 1줄로 카드 너비에 맞춰 표시”. 날짜가 더 최신인 정책 문서 값(1줄)을 본문에 채택했으나 실제 프로덕트 스펙과 재확인 필요 — 마스터 문서 값(2줄)이 오히려 최신 기획일 가능성도 있음
컨텐츠 타입 표시 순서	정책 문서는 “랜덤으로 섞여 표시”라 기술하나, 마스터 문서는 “최신순, 실제 편성 결과는 통합 Feed API 응답 순서 우선”이라 기술. 두 기준이 상충되므로 실제 정렬 로직 확인 필요
News 상세 화면	마스터 문서에 News 타입의 별도 상세 화면 규격이 명시되어 있지 않음. 에디토리얼 상세 템플릿을 그대로 재사용하는지 확인 필요