[request]: 카테고리 레퍼런스 API에 categoryGroup 필드 추가 요청

[hyejj19]

who

BE (@Whale0928)

what

GET /admin/api/v1/alcohols/categories/reference 응답에 categoryGroup 필드 추가 요청

why

현재 카테고리 레퍼런스 API 응답은 korCategory, engCategory 두 필드만 내려주고 있습니다.

// 현재 응답
[
  { "korCategory": "싱글 몰트", "engCategory": "Single Malt" },
  { "korCategory": "블렌디드", "engCategory": "Blend" },
  ...
]

그런데 어드민 위스키 등록/수정 API(POST/PUT /admin/api/v1/alcohols)에서는 categoryGroup (SINGLE_MALT, BLEND, BLENDED_MALT, BOURBON, RYE, OTHER) 값을 필수로 요구합니다.

서버가 korCategory ↔ categoryGroup 매핑 정보를 내려주지 않기 때문에, 프론트엔드에서 하드코딩으로 매핑하고 있는 상황입니다:

// 프론트엔드 하드코딩 (alcohol.api.ts)
const GROUP_TO_CATEGORY = {
  SINGLE_MALT: { korCategory: '싱글 몰트', engCategory: 'Single Malt' },
  BLEND: { korCategory: '블렌디드', engCategory: 'Blend' },
  BLENDED_MALT: { korCategory: '블렌디드 몰트', engCategory: 'Blended Malt' },
  BOURBON: { korCategory: '버번', engCategory: 'Bourbon' },
  RYE: { korCategory: '라이', engCategory: 'Rye' },
};

const CATEGORY_TO_GROUP_MAP = {
  '싱글 몰트': 'SINGLE_MALT',
  '블렌디드': 'BLEND',
  // ...
};

이로 인해 #220 에서 보고된 위스키 등록 오류(카테고리 초기값 매핑 실패)가 발생했고, 백엔드에서 카테고리가 추가/변경될 때마다 프론트 하드코딩도 동기화해야 하는 문제가 있습니다.

요청 사항

카테고리 레퍼런스 응답에 categoryGroup 필드를 추가해주세요:

// 희망하는 응답
[
  { "korCategory": "싱글 몰트", "engCategory": "Single Malt", "categoryGroup": "SINGLE_MALT" },
  { "korCategory": "블렌디드", "engCategory": "Blend", "categoryGroup": "BLEND" },
  { "korCategory": "테네시", "engCategory": "Tennessee", "categoryGroup": "OTHER" },
  ...
]

이렇게 되면 프론트엔드의 하드코딩 매핑(GROUP_TO_CATEGORY, CATEGORY_TO_GROUP_MAP)을 제거하고 서버 데이터를 단일 소스로 사용할 수 있습니다.

비고

• 프론트엔드는 우선 기존 하드코딩 매핑으로 [issue]: 어드민 위스키 등록 오류 #220 버그를 수정합니다 (긴급)
• 이 API 변경이 반영되면 후속으로 프론트 하드코딩을 제거하는 작업을 진행합니다

[hyejj19]

논의 결과

응답 형식 2가지 안을 검토했습니다:

1안 (flat) — 기존 배열에 categoryGroup 필드 추가

[
  { "korCategory": "싱글 몰트", "engCategory": "Single Malt", "categoryGroup": "SINGLE_MALT" },
  { "korCategory": "블렌디드", "engCategory": "Blend", "categoryGroup": "BLEND" },
  { "korCategory": "테네시", "engCategory": "Tennessee", "categoryGroup": "OTHER" }
]

2안 (grouped) — categoryGroup을 key로 그룹핑

{
  "SINGLE_MALT": [
    { "korCategory": "싱글 몰트", "engCategory": "Single Malt" }
  ],
  "OTHER": [
    { "korCategory": "테네시", "engCategory": "Tennessee" }
  ]
}

결정: 2안 (grouped)

• korCategory/engCategory는 서버 입장에서 자유 입력이라, 같은 categoryGroup에 여러 표기가 들어올 수 있음 (예: "싱글 몰트", "싱글_몰트" 등)
• 어드민 UI에서 메인 5개 그룹(SINGLE_MALT, BLEND, BLENDED_MALT, BOURBON, RYE)은 카테고리명이 고정(readonly)이고, "기타(OTHER)"일 때만 사용자 입력을 받아서 중복 가능성은 낮음
• 그러나 서버 입장에서는 UI 제약을 보장할 수 없으므로, grouped 구조로 categoryGroup 관계를 명확하게 표현
• 프론트에서도 그룹별로 접근하기 용이

[Whale0928]

구현 방향 확정

2안 (grouped) 으로 진행하며, 응답 구조는 아래와 같습니다.

• categoryGroup enum을 key로, 해당 그룹에 속한 카테고리 목록을 value로 갖는 Map 구조
• 데이터가 0건인 그룹도 빈 배열 []로 응답에 포함 (프론트에서 그룹 목록 자체를 이 응답으로 인식 가능하도록)
• 응답 키 순서는 AlcoholCategoryGroup enum 선언 순서를 따름: SINGLE_MALT → BLEND → BLENDED_MALT → BOURBON → RYE → OTHER

{
  "SINGLE_MALT": [
    { "korCategory": "싱글 몰트", "engCategory": "Single Malt" },
    { "korCategory": "싱글_몰트", "engCategory": "Single Malt" }
  ],
  "BLEND": [
    { "korCategory": "블렌디드", "engCategory": "Blend" },
    { "korCategory": "블렌디드 위스키", "engCategory": "Blended Whisky" }
  ],
  "BLENDED_MALT": [
    { "korCategory": "블렌디드 몰트", "engCategory": "Blended Malt" }
  ],
  "BOURBON": [
    { "korCategory": "버번", "engCategory": "Bourbon" }
  ],
  "RYE": [],
  "OTHER": [
    { "korCategory": "테네시", "engCategory": "Tennessee" },
    { "korCategory": "콘", "engCategory": "Corn" },
    { "korCategory": "휘트", "engCategory": "Wheat" },
    { "korCategory": "싱글 그레인", "engCategory": "Single Grain" },
    { "korCategory": "싱글 팟 스틸", "engCategory": "Single Pot Still" }
  ]
}

변경 포인트

• GET /admin/api/v1/alcohols/categories/reference 응답 타입을 List → Map<AlcoholCategoryGroup, List<{korCategory, engCategory}>> 로 변경
• QueryDSL 조회에 categoryGroup 컬럼 추가 후 그룹핑
• 빈 그룹은 []로 채워 모든 enum 키가 응답에 포함되도록 보장

[Whale0928]

@hyejj19 개발계 반영 완료 FE 대응 요청