[어드민] 카테고리 상품 진열 (category_sort)

화면 정보

Screen ID	Screen Title	메뉴 경로
ADM-PROD-SORT-01	상품 진열 설정	상품 진열 설정 > 카테고리 상품 진열

개요

WORKSOUT 스토어 카테고리별 상품 노출 순서를 관리하는 기능. Dooson ERP 동기화 시 자동 등록되는 경로와 백오피스에서 수동 등록하는 경로가 공존한다.

데이터 구조

category_sort 테이블의 핵심 컬럼:

컬럼	설명
`main_category_id`	메인 카테고리 (ERP `genderCode`로 매칭)
`sub_category_id`	서브 카테고리 (ERP `category2Code` → 서브카테고리 설정의 `categoryCodes`로 매칭)
`brand_id`	브랜드 (ERP `brandId` 그대로 복사)
`product_id`	상품 ID
`sort`	노출 순서

등록 경로

자동 등록 — ERP 동기화

ProductSyncService가 ERP에서 상품 정보를 가져올 때 is_sort 값을 함께 수신한다.

is_sort = false 인 상품 → 동기화 시점에 CategorySortService.addCategorySortAuto() 자동 호출
is_sort = true 인 상품 → 자동 등록 대상 아님

자동 등록 레코드 생성 패턴

동기화 배치가 아래 세 가지 조합으로 category_sort 레코드를 생성한다:

패턴	조합
1	메인카테고리 + 상품
2	메인카테고리 + 브랜드 + 상품
3	메인카테고리 + 서브카테고리 + 상품

중복 처리

동일한 (main_category_id, sub_category_id, brand_id, product_id) 조합이 이미 존재하면 스킵
sort 값은 기존 max + 1로 자동 부여

수동 등록 — 백오피스

백오피스 “상단 노출 상품 등록” 메뉴에서 관리자가 직접 추가. 자동 등록과 별개로 동작하며, 동일 테이블(category_sort)에 기록된다.

UI 노출 조건

category_sort에 레코드가 존재하더라도 상품 노출이 ON인 경우에만 어드민 UI에 표시된다.

알려진 이슈 및 원인

이슈 1 — 상품 노출 ON 했는데 진열 목록에 보이지 않는다

원인: 자동 등록은 ERP 동기화 시점에만 실행된다. 이후 노출 상태를 변경해도 category_sort 레코드가 소급 생성되지 않는다.

동기화 시점에 아래 조건 중 하나라도 맞지 않으면 레코드가 생성되지 않는다:

조건	설명
`is_sort = false`	ERP에서 자동 정렬 대상으로 설정되어 있어야 함
brand 활성화 타이밍	동기화 시점에 해당 브랜드가 활성(enable) 상태여야 함
`root_category` 설정	상품의 루트 카테고리가 설정되어 있어야 함
`category visible`	카테고리가 노출 상태여야 함

→ 현재는 로그가 심어져 있어, 특정 상품이 자동 등록되지 않은 경우 로그에서 원인 확인 가능.

이슈 2 — 서브카테고리에 상품이 보이지 않는다

원인: 서브카테고리 매칭은 ERP category2Code를 기준으로 서브카테고리 설정의 categoryCodes와 비교한다. 동기화 시점에 해당 상품의 category2Code가 서브카테고리의 categoryCodes에 포함되어 있지 않으면 패턴 3 (메인카테고리 + 서브카테고리 + 상품) 레코드가 생성되지 않는다.

→ 서브카테고리 categoryCodes 설정 누락 여부를 먼저 확인.

트러블슈팅 가이드

상품이 진열 목록에 없다고 문의가 오면 아래 순서로 확인한다:

로그 확인 — 해당 product_id의 addCategorySortAuto 호출 로그 조회
ERP is_sort 값 — 해당 상품이 is_sort = false인지 확인
브랜드 활성화 여부 — 동기화 시점 기준 brand enable 상태 확인
root_category 설정 여부 — 상품에 루트 카테고리가 설정되어 있는지 확인
카테고리 노출 상태 — 해당 카테고리가 visible 상태인지 확인
서브카테고리 categoryCodes — 상품의 category2Code가 서브카테고리 설정에 포함되어 있는지 확인

복수 검색 추가 — sort 배정 규칙

개선 배경

기존 동작에서 아래 두 가지 문제가 있었다:

문제	증상
입력 순서 불일치	코드1~코드4 순서로 입력해도 검색 결과 목록이 다른 순서로 표시됨
sort 일괄 1 배정	추가되는 모든 상품의 sort가 1로 일괄 배정 → 추가 후 수동 재정렬 필요

→ 개선 완료 (v1.1 기준 적용)

핵심 규칙

1. 입력 순서 보존

복수 입력창에 줄바꿈으로 입력·붙여넣기한 코드 순서 = 검색 결과 목록 표시 순서.

2. sort 값 배정

전체 선택 후 추가 시 입력 순서 그대로 sort 배정:

입력 순서	sort
1번째 코드	1
2번째 코드	2
N번째 코드	N

3. 기존 항목 재번호 — 일반 케이스

N개를 추가하면 기존 항목들은 N+1부터 연속값으로 재번호된다 (단순 +N이 아닌 재번호 방식, gap 방지).

[추가 전]          복수 입력: 코드X(1번), 코드Y(2번) → N=2
sort 1 : 코드A
sort 2 : 코드B     [추가 후]
sort 3 : 코드C     sort 1 : 코드X  ← 신규
                   sort 2 : 코드Y  ← 신규
                   sort 3 : 코드A  ← 기존 재번호
                   sort 4 : 코드B  ← 기존 재번호
                   sort 5 : 코드C  ← 기존 재번호

4. 이미 목록에 있는 코드 포함 시 — 재추가 케이스

[추가 전]          복수 입력: 코드X(1번), 코드B(2번) → N=2 / 코드B는 기존 존재
sort 1 : 코드A
sort 2 : 코드B     처리 순서:
sort 3 : 코드C     1. 코드B 기존 row → deleted=1
                   2. 나머지(코드A, 코드C)를 sort 순서 유지하며 N+1(=3)부터 재번호
                   3. 새 row 생성: 코드X(sort 1), 코드B(sort 2)

                   [추가 후]
                   sort 1 : 코드X
                   sort 2 : 코드B
                   sort 3 : 코드A
                   sort 4 : 코드C  ← gap 없음

5. 단일 검색 모드

단일 검색 모드의 동작에는 영향 없음.

합격 기준

복수 입력창에 코드1~코드4 순서로 입력하면 검색 결과 목록도 코드1이 최상단에 표시된다
전체 선택 후 추가 시 코드1 → sort 1, 코드2 → sort 2, … 순서로 배정된다
추가 후 기존 항목들의 sort 값이 N+1부터 연속값으로 재번호된다 (gap 없음)
이미 목록에 있는 코드를 포함해 추가하면 해당 row만 deleted=1 처리 후 새 sort 위치로 재생성된다
추가 후 전체 sort 값이 1부터 연속값을 유지한다
단일 검색 모드 동작에 영향이 없다

변경 이력

버전	날짜	변경 내용
v1.1	2026-07-08	복수 검색 sort 배정 규칙 추가 — 입력 순서 보존, 재번호 로직, 재추가 케이스(deleted=1)
v1.0	2026-07-08	최초 작성 — ERP 자동 등록 구조, 수동 등록, 알려진 이슈 및 트러블슈팅