[WORKSOUT] 라플 메인 화면

화면 정보

Screen ID	Screen Title	Screen Path
RAF-LIST-01	라플 메인	`HM_110_Raffle`

개요

라플(응모) 메인 화면. 응모 소식(Strapi CMS)과 응모 상품(자체 어드민/라플 시스템) 두 영역으로 구성된다. 응모 클릭 시 알림·마케팅 동의 여부에 따른 선행 동의 절차가 분기된다.

연동 시스템: Strapi (응모 소식) · 자체 어드민/라플 시스템 (응모 상품) · 회원/알림/결제 시스템

화면 구성

응모 소식 영역

항목	기준
노출 조건	`contentsType = RAFFLE` + `publishedAt` not null + `displayDate` 기간 내
정렬	`sort ASC` — 숫자가 낮을수록 먼저 노출
최대 노출 수	8개
레이아웃	가로 스크롤, 진입 시 약 1.5개 카드 노출
전체보기 버튼	노출 소식 2개 이상일 때만 표시, 1개 이하면 숨김
타이틀 표시	최대 2줄, 초과 시 말줄임표
이미지	Strapi 썸네일 설정 > 리스트 페이지 썸네일
빈 상태 문구	“현재 응모 소식이 없습니다”
상세 이동	`documentId` 기반 상세 화면으로 이동

응모 상품 영역

항목	기준
관리 주체	자체 어드민 / 라플 상품 관리 시스템
상태 우선순위	1순위: Active (`availableUntil >= now`) → 2순위: Closed (`availableUntil < now`)
Active 정렬	서버 전달 `sort` 기준 DESC, 클라이언트 추가 정렬 없음
Closed 정렬	`availableUntil DESC` — 가장 최근 종료 건이 먼저 노출
빈 상태 문구	“현재 진행중인 응모가 없습니다”
비로그인 클릭	“로그인이 필요합니다” 팝업 노출

상품 카드 표시 정보

항목	필드
상품명	`productName` + `color`
이미지	`thumbnailUrl` (첫 번째 이미지만 사용)
가격	`{currentPrice}원`
응모 기간	`availableFrom ~ availableUntil`

응모 기간 표시 포맷

연도가 같은 경우: YYYY년 MM월 DD일 (요일) ~ MM월 DD일 (요일) 오전/오후 HH:MM
연도가 다른 경우: YYYY년 MM월 DD일 (요일) ~ YYYY년 MM월 DD일 (요일) 오전/오후 HH:MM
12시간제, 오전/오후 표기, 분 단위까지 표시

버튼 상태

상태	조건	버튼 텍스트	버튼 상태
진행 중	`isExpired = false`	`{currentPrice}원`	Enabled
종료	`isExpired = true`	종료된 응모입니다.	Disabled

응모 상품은 응모 컬렉션명으로 그룹핑되어 있으며, 컬렉션명이 같은 상품은 동일한 줄에 노출된다. 최근 생성된 순서대로 정렬된다.

정책

응모 참여 전 동의 확인 프로세스

사용자가 응모를 시도할 때, 푸시 알림 설정(pushOn)과 마케팅 수신 동의(marketingApproved) 여부에 따라 선행 동의 절차가 분기된다. 라플은 알림 허용과 마케팅 수신동의 모두 동의해야 한다.

케이스 1. pushOn = false + marketingApproved = false

알림 및 마케팅 수신 동의 팝업 표시
OS 알림 권한 요청
허용 시: [동의] 선택 → POST /v1/notification/settings + PUT /v1/users/agreements → 상세 페이지 이동 + 토스트 “[WORKSOUT] 마케팅 정보 수신 동의가 완료되었습니다”
허용 안함 시: 팝업 내 재선택 가능, 거부 시 현재 페이지 유지

케이스 2. pushOn = true + marketingApproved = false

마케팅 수신 동의 팝업 표시
동의 시: PUT /v1/users/agreements 처리 후 상세 이동
거부 시: 현재 페이지 유지 + 거부 안내 메시지

케이스 3. pushOn = false + marketingApproved = true

알림 권한 요청 팝업 표시
허용 시: POST /v1/notification/settings 후 상세 이동
거부 시: 현재 페이지 유지

케이스 4. pushOn = true + marketingApproved = true

동의 절차 없이 즉시 상세 페이지로 이동

예외 처리

알림 권한 거부 후 재시도: OS 설정 페이지 링크 제공
마케팅 동의 거부: “라플 참여를 위해서는 마케팅 정보 수신 동의가 필요합니다”
동의 처리 실패: “동의 처리 중 오류가 발생했습니다. 다시 시도해주세요”

어드민 작업 절차 — Strapi > 컨텐츠 관리 (응모 소식)

등록 필드

필드명	설명	입력 형식	필수
`contentsType`	콘텐츠 분류	`RAFFLE` 고정	필수
`title`	목록 제목	텍스트	필수
`thumbnailContainer.listPageThumbnail`	썸네일 > 리스트 페이지	이미지 업로드	필수
`sort`	노출 순서	숫자 (낮을수록 먼저)	필수
`displayDate`	노출 기간	시작일 ~ 종료일	선택
`CKEditor`	상세 본문	HTML / 리치 텍스트	필수
`publishedAt`	게시 상태	Published 설정	필수

publishedAt이 Draft 상태이면 앱에 노출되지 않는다.
displayDate가 설정된 경우 기간이 지나면 목록에서 자동 제외된다.
sort 값이 없으면 의도한 순서로 노출되지 않을 수 있다.
삭제 시 복구가 어려우므로, 일시 숨김은 Unpublish 또는 displayDate 조정을 권장한다.
모든 소식을 비노출하면 화면에 “현재 응모 소식이 없습니다” 문구만 표시된다.

라플 상품 등록 (어드민)

라플 상품은 두손ERP에서 등록한다.
어드민의 라플 관리에서 다음 일정을 설정할 수 있다: 노출 일시, 응모 시작일/종료일, 발표일(1차, 2차), 결제 시작일/종료일(1차, 2차).

노출이 안 될 때 체크리스트

응모 소식

확인 항목	확인 위치	정상 기준
`contentsType`	Strapi > Articles	`RAFFLE`
게시 상태	Strapi > 해당 콘텐츠	Published
노출 기간	`displayDate`	현재 시각이 범위 안 또는 null
썸네일	`thumbnailContainer.listPageThumbnail`	값 존재
정렬값	`sort`	숫자 입력

응모 상품

확인 항목	확인 위치	정상 기준
상품 존재 여부	라플 상품 API / 자체 어드민	1개 이상
노출 상태	자체 어드민	노출 취소 아님
종료 여부	`availableUntil`	진행 중이면 현재 시각보다 미래
정렬값	`sort`	서버 정렬값 존재

API 연동

응모 소식 조회

엔드포인트: GET /api/articles (Strapi API) — 라플 화면 진입 시 / 응모 소식 전체보기 화면 진입 시 요청 파라미터: contentsType = RAFFLE, publishedAt not null

필드	활용
`title`	목록 제목 (최대 2줄)
`thumbnailContainer.listPageThumbnail`	썸네일 이미지 URL
`documentId`	상세 이동 식별자
`displayDate`	노출 기간
`sort`	정렬 기준 (ASC)
`CKEditor`	상세 본문 HTML

응모 소식 상세 조회

엔드포인트: GET /api/articles/{documentId} (Strapi API) — 응모 소식 항목 클릭 시. CKEditor HTML 렌더링 (이미지/링크/서식 모두 지원)

응모 상품 조회

엔드포인트: GET /v1/raffle/products — 라플 화면 진입 시

필드	활용
`availableFrom` / `availableUntil`	응모 기간 표시 및 만료 판단
`sort`	정렬 기준 (DESC)
`productId`	내부 식별
`raffleProductId`	상세 이동 및 응모 처리
`currentPrice`	가격 표시
`thumbnailUrl`	목록 이미지
`productName`	상품명
`color`	컬러

사용자 상태 확인

목적	API	확인/처리 값
사용자 정보 조회	`GET /v1/users/info`	`marketingApproved`
마케팅 동의 처리	`PUT /v1/users/agreements`	마케팅 수신 동의 저장
푸시 설정 조회	`GET /v1/notification/settings`	`pushOn`
푸시 설정 저장	`POST /v1/notification/settings`	`pushOn: true` 저장

에러 처리 요약

증상	예상 원인	1차 조치
응모 소식 영역 전체 비어 있음	Strapi 콘텐츠 없음 / 기간 만료 / API 실패	Strapi Published 상태 · `displayDate` 확인
전체보기 버튼 안 보임	노출 콘텐츠 1개 이하	기간 필터 후 노출 개수 확인
응모 상품 하나도 안 보임	API 실패 / 노출 취소	라플 상품 API 응답 확인
종료 상품 정렬 이상함	Closed 후처리 정렬 미적용	`availableUntil DESC` 적용 여부 확인
응모 클릭 후 아무 반응 없음	로그인/동의 플로우 실패	사용자 상태 조회 및 동의 API 로그 확인
화면 전체 로딩 실패	네트워크 또는 서버 장애	다른 네트워크·기기에서 재현 후 개발팀 전달

미결 사항

항목	내용
—	—

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 (라플 화면 마스터.md “라플 메인 화면” + 응모(라플) 정책.md 3.1~3.2 병합 이전)