[WORKSOUT] 브랜드 메인

화면 정보

Screen ID	Screen Title	Screen Path
BRND-01	브랜드 메인 (BM_100_Main)	`/brand`

개요

전체 브랜드 목록과 포커스 브랜드(관심 브랜드) 목록을 탐색하는 화면. 앵커링(#/숫자/A-Z) 탐색, 로컬 검색, 포커스 브랜드 최대 100개 제한을 제공한다.

원본: 브랜드 마스터 문서.md(베이스, 앵커링/로컬검색/100개제한/API) + 브랜드 정책.md 병합(신상품 알림 배치 오후 5시 등 추가).

화면 구성

화면 구조 개요

BM_100_Main
├── 헤더                    ← 뒤로가기 / 검색 버튼
├── 탭 영역                 ← 전체 브랜드 / 포커스 브랜드
├── 앵커링 영역             ← 전체 브랜드 탭에서만 표시 (# / 숫자 / A-Z)
└── 브랜드 목록 영역
    ├── 전체 브랜드 목록
    └── 포커스 브랜드 목록

섹션별 관리 주체

섹션	관리 어드민	관리 경로	비고
브랜드 목록	자체 어드민	브랜드 관리	`visible = 1` 기준 노출
포커스 브랜드	사용자 데이터	사용자 북마크	로그인 사용자 기준
검색 기능	앱 로컬 데이터	클라이언트	서버 검색 API 없음

전체 브랜드 목록

항목	기준
노출 조건	`brand.visible = 1`
정렬 순서	기호(#) → 숫자(0-9) → 알파벳(A-Z)
정렬 처리	클라이언트에서 브랜드명 기준 정렬

브랜드 카드 표시 요소

요소	기준
브랜드명	`brand.name`
북마크 아이콘	포커스 브랜드 설정/해제 버튼, 항상 브랜드명 옆에 표시
신상품 점 표시	`brand.newArrival = 1` → 브랜드명 우측 상단 노란색 점

브랜드 클릭 동작: 브랜드명 클릭 → 쇼핑 메인(plp-main.md)으로 이동 + 해당 브랜드 필터 자동 적용

앵커링 동작

항목	기준
표시 탭	전체 브랜드 탭에서만 표시 (포커스 탭에서는 숨김)
앵커 범위	# → 숫자 → A-Z
앵커 클릭	해당 섹션 첫 번째 브랜드로 부드러운 스크롤 이동
스크롤 연동	목록 스크롤 시 현재 구간 앵커 자동 활성화
활성 앵커	선택된 앵커가 화면 중앙에 오도록 자동 정렬

포커스 브랜드

로그인/비로그인 정책

항목	로그인	비로그인
섹션 제목	“{user.name}의 포커스 브랜드”	“포커스 브랜드”
전체보기 버튼	“{user.name}의 포커스 브랜드 전체보기 >”	“포커스 브랜드 전체보기 >”
표시 브랜드	사용자가 북마크한 브랜드	기본 포커스 브랜드 16개
북마크 설정/해제	가능	불가 (클릭 시 로그인 유도)

기본 포커스 브랜드 (비로그인 고정, 16개)

aries, brain dead, carhartt wip, cav empt, fucking awesome,
human made, hockey, jordan, nike, no problemo, nostasy,
obey, palace, pop trading company, vans, worksout

포커스 브랜드 미설정 시 (로그인 상태): [북마크 아이콘] 포커스 브랜드 설정하고 관심있는 브랜드 소식을 받아보세요.

포커스 브랜드 제한사항

항목	기준
최대 개수	100개
초과 시도 시	“포커스 브랜드는 100개까지 추가할 수 있습니다.” 토스트 메시지
초과 시 상태	북마크 상태 변경하지 않음

전체보기 버튼 동작: 쇼핑 메인으로 이동 + 포커스 브랜드 필터 적용 (로그인/비로그인 동일)

브랜드 화면 상세 표시 요소 (검색 결과·필터 화면 공통 참조용)

정책 문서 기준으로 브랜드 하나당 아래 정보를 함께 노출한다:

브랜드 로고
포커스 브랜드 설정/해제 버튼
브랜드명
신상품 뱃지(신상품이 있을 경우)
브랜드 한글명
포커스 브랜드 설정한 회원 수
“브랜드 보러가기” 버튼

검색 운영

항목	기준
검색 방식	로컬 검색 (이미 로드된 데이터 내 필터링, 서버 API 없음)
검색 대상	브랜드명(`brand.name`)만 — 상품·콘텐츠·큐레이션 제외
검색 조건	부분 일치, 대소문자 구분 없음
반응 방식	실시간 필터링 (입력과 동시에 결과 반영)
결과 없음	“검색 결과가 없습니다” 메시지
검색 모드 종료	취소 버튼 / 뒤로가기 / 검색어 전체 삭제 → 전체 목록 복원

정책

신상품 알림 정책 (정책 문서에서 흡수)

신상품은 입고 후 2주 동안 신상품으로 간주된다.
신상품이 입고되면 당일 오후 5시에 배치 프로세스를 통해 신상품을 필터링하고 푸시 알림을 발송한다.
- 알림 형식 예시: "{브랜드명}의 신상품이 입고됐으니 확인해보세요"
- 3개 이상의 브랜드에 신상품이 입고된 경우, 첫 3개 브랜드만 표시하고 나머지는 “…“으로 대체한다.
- 푸시 알림은 포커스 브랜드를 설정한 모든 사용자에게 동일하게 발송된다.
알림은 기기의 알림 설정에 따라 소리·진동·배너 형태로 표시된다.
알림을 탭하면 해당 관심목록 브랜드의 탭으로 이동한다.
포커스 브랜드 알림은 알림센터의 설정에서 관리할 수 있다.

포커스 브랜드 설정 예외 처리 (정책 문서에서 흡수)

상황	메시지
네트워크 오류	“네트워크 연결을 확인해주세요”
서버 오류	“일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요”

오류 발생 후 재시도 버튼을 제공한다.

API 연동

브랜드 목록 조회

엔드포인트: GET /v1/brands 호출 시점: 화면 진입 시

응답 주요 필드

필드	활용
`brandId`	북마크 API 요청 시 `targetId`로 사용
`name`	브랜드명 표시 / 클라이언트 정렬 기준
`visible`	`1`인 브랜드만 목록에 표시
`newArrival`	`1`이면 노란색 점 표시
`isBookmarked`	북마크 아이콘 초기 상태 결정

클라이언트 정렬 처리: 기호(#) → 숫자(0-9) → 알파벳(A-Z) 순

포커스 브랜드 조회 (로그인)

엔드포인트: GET /v1/bookmarks?type=BRAND 호출 시점: 포커스 브랜드 탭 선택 시 (로그인 상태)

응답 주요 필드

필드	활용
`id`	브랜드 식별
`name`	브랜드명 표시
`newArrival`	신상품 점 표시
`bookmarkUpdateAt`	정렬 참고용

포커스 브랜드 조회 (비로그인)

엔드포인트: GET /v1/brands 처리 방식: 응답에서 기본 포커스 브랜드 16개 필터링

brand.name IN ('aries', 'brain dead', 'carhartt wip', 'cav empt',
'fucking awesome', 'human made', 'hockey', 'jordan', 'nike',
'no problemo', 'nostasy', 'obey', 'palace', 'pop trading company',
'vans', 'worksout')

북마크 설정/해제

엔드포인트: POST /v1/bookmarks 호출 시점: 북마크 아이콘 클릭 시 (로그인 상태에서만)

{
  "targetId": 1,
  "targetType": "BRAND"
}

처리 방식

성공 → UI 즉시 반영 (북마크 상태 변경)
실패 → 원래 상태로 롤백 + “북마크 처리에 실패했습니다” 토스트
100개 초과 → 서버에서 오류 응답 + 제한 메시지 표시

노출이 안 될 때 체크리스트

확인 항목	확인 방법	정상 기준
특정 브랜드 미노출	어드민 > 브랜드 관리에서 해당 브랜드 확인	`visible = 1`
신상품 점 미표시	어드민 > 브랜드 데이터 확인	`newArrival = 1`
포커스 브랜드 미노출	로그인 상태 + 북마크 설정 여부 확인	북마크된 브랜드 존재
북마크 설정이 반영 안 됨	`POST /v1/bookmarks` 응답 확인	성공 응답 후 UI 즉시 반영
앵커 클릭 후 스크롤 안 됨	클라이언트 로그 확인	부드러운 스크롤 → 실패 시 즉시 이동으로 대체
검색 결과 없음	검색어 대소문자/철자 확인	부분 일치 + 대소문자 무시

에러 처리 요약

증상	예상 원인	1차 조치
브랜드 목록 전체 미로드	`GET /v1/brands` 실패	API 로그 확인
특정 브랜드 미노출	`visible = 0`	어드민 브랜드 데이터 확인
포커스 브랜드 탭 미로드	`GET /v1/bookmarks` 실패	API 응답 확인
북마크 동작 실패	`POST /v1/bookmarks` 오류	요청 파라미터 및 응답 확인
100개 제한 오류 미표시	서버 오류 응답 처리 누락	오류 응답 분기 처리 확인
검색 동작 안 됨	클라이언트 필터링 오류	앱 로그 확인
앵커 스크롤 실패	위치 계산 오류	즉시 이동으로 폴백 처리 확인

미결 사항

항목	내용
신상품 알림 발송 배치 시각과 최초 API 문서 간 정합성	브랜드 마스터 문서에는 신상품 알림 배치 시각이 언급되지 않았고, 브랜드 정책 문서(2025-10-29)에만 “당일 오후 5시” 배치가 명시됨. 실제 배치 스케줄러 설정과 일치하는지 개발팀 확인 필요

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 — `브랜드 마스터 문서.md`(베이스) + `브랜드 정책.md` 병합 (신상품 알림 배치 오후 5시 등 추가)