공급사 상품 등록 — 기획 문서 v3

0. 개요 · 배경 — 왜 자동 매칭인가

문제의 뿌리는 "공급사는 자기 상품이 오더히어로에 이미 있는지 모른다"는 것.

공급사는 자기가 파는 상품을 오더히어로에 등록한다. 그런데 그 상품이 오더히어로에 이미 등록돼 판매 중인 상품인지, 완전히 새로운 상품인지 공급사는 알 수 없다. 같은 "요쿠르트 1000ml 냉장"을 A 공급사가 이미 올려놨어도, B 공급사는 그걸 모른 채 또 올린다.

그대로 두면 같은 상품이 중복 등록되거나, MD가 검수할 때마다 "이거 우리한테 이미 있는 거 아닌가?"를 수동으로 하나하나 찾아야 한다. 1,000줄짜리 엑셀을 올리면 그 수고가 1,000번 반복된다.

0-1. 왜 지금 이 순서인가 — 로드맵 (회의 2026-09-10)

공급사 상품 등록은 단독 기능이 아니라 세 단계 로드맵의 첫 칸이다. ① 공급사 상품 등록을 시스템이 통제한다(누가 무엇을 언제 올렸는지, 기존 상품과 어떻게 이어지는지). ② 그 위에 계약 조건을 DB화한다 — 지금은 공급사별 계약 조건이 로컬 문서로만 관리된다. ③ 마지막으로 재무·정산을 시스템 안으로 들인다 — 현재는 매달 1~10일에 MD·재무가 수기로 피드백을 주고받은 뒤 계산서를 끊는다. ①이 서야 ②③의 기준 데이터(공급사·상품·가격)가 생기므로, 이번 1차는 범위를 좁혀 빨리 "돌아가는 것"을 만드는 데 집중한다.

0-2. 1차 범위 = 엑셀 업로드만 회의 2026-09-10

0-3. 1차 일정 회의 2026-09-10

개발·QA가 하루 차이라 유사도 산식(§2-1)은 개발이 먼저 정하고 문서는 결과만 받는다. 일정이 밀리면 §5의 "비동기 배치"를 동기 처리로 낮추는 것이 1순위 축소 후보(가정).

1. 사용자 · 역할 · 화면 분리

두 주체가 등장한다. 각자 하는 일과 보지 않아도 되는 일이 명확히 갈린다.

확인 못 함: 🟡 후보 목록을 공급사 화면에도 보여줄지는 회의에서 정하지 않았다. 이 문서는 "공급사에겐 상태만, 후보 목록은 MD 화면"으로 가정한다 — 뒤집히면 §5 결과 표에 후보 열이 추가된다.

1-2. 두 화면은 완전히 분리 — 권한 자동 분기 확정

공급사 포털과 어드민(MD)은 별개의 화면이다. 로그인 계정의 권한(공급사 / MD)에 따라 자동으로 분기되며, 공급사 계정엔 MD 검수 화면이 아예 보이지 않는다.

1-3. 어드민 메뉴 위치 — 신규 메뉴 공존 확정

어드민 상품 관리 아래에서, 기존 메뉴는 그대로 두고 이 프로젝트를 별도 메뉴로 추가한다. 셋은 공존한다(기존 메뉴 대체 아님).

세 메뉴의 데이터소스를 하나로 합칠지, 계속 나눠 둘지는 미정(§10 M-6).

1-4. 입력 주체 — 필드 역할 4종, 단가는 미노출 회의 2026-09-10

MD만 다루는 자동/숨김 항목은 v3에서도 공급사에게 노출하지 않는다. 히어로코드 · MFC노출기준 · 검수필요여부 등은 시스템이 매칭·확정 시 내부 처리.

1·5. 공급사 포털 — 내 상품 리스트 확정

공급사가 로그인하면 자기 공급사에 귀속된 모든 상품이 리스트로 먼저 뜬다(남의 상품은 안 보임).

리스트의 상품 노출·구분은 기존 공급사 상품 관리(product/manage)와 동일한 방식·컬럼을 따른다. 새 표 형식을 만들지 않고 이미 익숙한 리스트를 그대로 재사용한다.

그룹 행 컬럼 (기존 product/manage와 동일)

리스트의 그룹 상품명·카테고리는 기존 상품 데이터의 값이다(양식 v3에서는 제거된 필드 — 공급사가 적는 게 아니라 매칭 결과로 붙는다). 예시 행 값은 설명용.

• 그룹 행 펼침(▶). 그룹 행을 열면 하위에 공급사별 상품(약 47컬럼, 가로스크롤)이 뜬다 — 히어로코드·마진율·net공급가·판매가 등 내부 컬럼 포함. 단, 하위 행의 복제 버튼·복제/복제코드 컬럼은 제거한다(회의 2026-09-02).
• 상단 검색/필터바. 검색 프리셋(공용 기본필터) · 검색 필터(히어로코드·유통사 상품코드/명·제조사·그룹명·검수필요·중량·그룹ID·배송유형·보관·노출·과세 등) · 검색. 공급사 필터는 자기 공급사로 고정.
• 등록 진입점. 테이블 위 우측 툴바의 ➕ 상품 등록/수정 ▾ → 📄 엑셀 등록·수정(1차) / 📝 상품 단건 등록(2차 — 1차에서는 미노출 또는 비활성). 사이드에는 신규 공급사 상품 등록 · 등록 이력.

2. 핵심 정책 · 유사도 매칭

v3의 뼈대. 단어 유사도 점수제 · 매칭 후 승계 · 양식/정규화 · 이미지 승계.

2-1. 매칭 = 단어 유사도(Similarity) 점수제 v3 핵심 · 회의 2026-09-10

엑셀의 각 줄을 기존 상품과 비교해 0~1.0 점수를 낸다. 재료는 ★ 필수 6 필드(상품명·과세여부·보관상태·중량·원산지 세부사항·브랜드), 보조로 ☆ 3 필드(원산지·등급·주문 배수 단위). 점수로 셋 중 하나로 판정한다.

• 비교 대상은 기존 등록 상품 전체(히어로 단위). 대분류·그룹명으로 미리 범위를 자르지 않는다 — 두 필드가 양식에서 빠졌기 때문.
• ⭐ 🟢 자동 매칭된 건은 후보를 노출하지 않고 시스템이 붙여 확정(자동확정)한다. 여기서 "확정"은 매칭이 확정됐다는 뜻이지 판매 등록이 아니다 — 이후 검수 대기로 올라간다(§3).
• 🟡 후보 선택은 MD 검수 화면에서 한다(§7). 공급사는 상태만 본다(§1 가정 참조).

1,000줄 업로드 시 배분 예시(650/250/92/8)는 프로토 예시 기반 가정이며, 유사도 산식이 정해진 뒤 QA 실파일로 재측정한다.

2-2. 매칭이 붙으면 — 기존 상품 값을 승계 v3

🟢 자동 매칭 또는 🟡에서 MD가 후보를 고르면, 그 줄은 기존 상품(그룹)에 편입된다. 공급사가 적은 필수 9는 그대로 저장하고, 그룹 공통 정보는 기존 상품에서 승계한다.

🔴 신규(0.74 이하)는 승계할 상품이 없다. 공급사 값 9 + 선택 필드로 검수 대기에 올라가고, 그룹을 새로 만들지 / 어느 그룹에 넣을지는 미정(§10 M-1). 이미지는 공급사 업로드 또는 MD 보완.

2-3. 비교 범위 = 기존 상품 전체 · 카테고리 선행 필터 없음 회의 2026-09-10

비교 대상 건수가 커서 성능이 문제면(§10 M-4) 인덱스·사전 필터는 개발이 내부적으로 둘 수 있다 — 단, 공급사에게 카테고리를 입력시키는 방식으로는 돌아가지 않는다.

2-4. 엑셀 업로드 — 양식 v3 고정 · 정규화

• 업로드 양식은 공급사상품등록_양식_v3.xlsx(§양식 v3)를 그대로 쓴다 — 임의 컬럼을 만들지 않는다.
• 중량(예 1KG)·주문 배수 단위·상품단위·라벨용 수량 단위 등 단위성 필드를 양식에서 규정해 정규화(1L/1000ml → 1000ML). 필수 9가 비거나 허용값(과세여부·보관상태 등) 밖이면 ⛔ 오류로 걸러진다.
• 우리가 요청·배포하는 양식이므로 기존 엑셀 양식을 수정해도 된다. v3에서 그룹 상품명·대분류 열을 뺐고 원산지 세부사항을 필수로 올렸다.

2-5. 이미지 자동 승계

• 기존 상품에 매칭되면 그룹 이미지를 자동으로 따온다. 공급사가 이미지를 안 올려도 된다.
• 매칭이 확정되면 하위 정보가 자동으로 들어온다(이미지 포함 — 메인·서브1·서브2).
• 🔴 신규일 때만 이미지를 직접 업로드하거나 Zip으로 일괄 제공한다.

2-6. 유사도 점수 걸어보기 (예시)

공급사가 감귤 · 면세 · 냉장 · 1KG · 제주 · (브랜드 없음)을 올렸다고 하자. 기존 상품 세 건과 비교하면:

점수는 설명용 가정. 실제 값은 개발이 정한 토큰화·가중치에 따른다. 이 예시에서 후보가 하나라도 0.75 이상이면 그 줄은 🟡, 모두 0.74 이하면 🔴.

엑셀 양식 v3 (필수 9 · 선택 23 · 제거 2) 회의 2026-09-10

등록 양식은 공급사상품등록_양식_v3.xlsx로 고정한다. 필드마다 역할(★ 유사도 필수 / 입력만 / ☆ 유사도 보조 / 선택)을 붙였다 — 임의 필드가 아니다.

필수 9

선택 23 = ☆ 유사도 보조 3 + 선택 20

v2에서 필수였던 배송예정일수·배송유형·외부 적재·최소 주문 수량·주문 배수 단위·등급·원산지·특성은 v3에서 선택으로 내려갔다. 총량피킹은 v2 §1-4에서 "공급사 미노출"로 적었으나 v3 양식에는 선택 열로 남는다 — 노출 여부 불일치, 확인 못 함(양식 기준으로 표기). 할인기준가는 열은 남기되 필요 여부 미정(§10 M-10).

제거 2

3. 상태 모델

두 축을 구분해야 한다 — 매칭 상태(시스템이 점수로 붙인 결과)와 검수 상태(MD가 처리한 결과).

3-1. 매칭 상태 — 업로드된 각 줄의 판정

업로드된 각 줄은 아래 넷 중 하나로 판정된다. 사람이 실제로 손대는 건 🟡🔴⛔ 셋뿐(🟢은 확인·승인만).

3-2. 자동확정 ≠ 판매 등록 🟠 자동 승인 정책 미정

3-3. 검수 상태 — MD 처리 결과

제출된 줄은 MD 화면에서 세 탭으로 관리된다: 검수 대기 · 승인됨 · 거절됨(§7). 승인되면 판매 등록에 반영되고, 거절되면 사유가 공급사에 전달돼 보완·재제출한다.

매칭이 도는 중(서버 배치)에는 업로드 화면의 진행률로만 보이고, 등록 이력에는 남지 않는다 — 이력은 "제출 완료분"만(§6).

4. 화면 흐름 — 단건 등록 2차 · 이번 범위 아님

공급사가 상품 하나를 등록할 때. 실제 어드민 "상품 등록" 모달을 그대로 쓴다는 방향은 유지하되, 1차(9/16)에는 개발하지 않는다.

모달 구조 — 3섹션 + 이미지 3 2차

• 이미지 3. 메인 · 서브1 · 서브2. 매칭되면 그룹 이미지 자동 승계, 신규일 때만 직접 업로드.
• 3섹션. 필수 정보 / 주요 노출 정보 / 부가 정보. 필수 항목엔 *. 필드 구성은 양식 v3(필수 9 / 선택 23)에 맞춘다.
• 상단 "상품 그룹 입력 [검색]" — v2 자동채움 진입점 → 폐기. 2차 재기획.

1. 입력 → 유사도 판정
   상단 검색으로 그룹 추천 대신, 필수 6 필드를 채우면 시스템이 점수를 낸다(어느 시점에 어떻게 보여줄지는 2차 재기획).
2. 판정 분기
   🟢 1.0 기존 상품에 붙여 그룹 공통값 승계
   🟡 0.75~0.99 후보 목록 → 선택(2차에서는 공급사가 고를지 MD가 고를지 재결정)
   🔴 0.74 이하 신규 → 3섹션 전체 직접 입력 + 이미지 업로드
3. [등록] 제출
   입력 완료 후 등록. 제출 내역은 등록 이력에 쌓이고 검수 대기로 올라간다.
4. MD 검수 → 판매 반영
   🟢도 검수 대기를 거쳐 MD 승인 시 판매 등록에 반영(자동 승인 정책 미정). 이후 MD 사후 수정 가능.

승인 프로세스 1차·2차 공통

어떤 경로로 들어오든 곧바로 등록되지 않는다. 아래 승인 프로세스를 거친다(엑셀 §5도 동일).

1. 공급사 제출
   엑셀(1차) 또는 단건(2차)으로 제출.
2. MD 검수
   제출 건이 검수 대기로 올라가고 MD가 개별 행으로 검수(§7). 🟡는 여기서 후보 선택.
3. 승인 / 거절 / 수정 후 승인
   MD가 셋 중 하나로 처리. 거절 시 사유가 공급사에 전달돼 보완·재제출.
4. 승인 시 등록
   승인된 건만 판매 등록에 반영. (🟢 자동 매칭 건도 현재는 이 승인을 거친다 — 자동 승인 정책 미정, §10 M-2.)

5. 화면 흐름 — 엑셀 일괄 등록 · 성능 1차 범위

1,000줄 대량 업로드. 서버가 비동기로 유사도를 매기고, 결과를 검토·보완한 뒤 한 번에 MD 검수로 제출한다. 9/17 시연은 이 흐름 엔드투엔드.

1. 양식 다운로드 → 업로드
   ⬇ 양식 다운로드로 공급사상품등록_양식_v3.xlsx를 받아 채운 뒤 업로드(1,000줄). 이미지는 신규분만 별도/Zip.
2. 양식 검증 → ⛔ 분리
   필수 9 누락 · 단위 없음 · 허용값 외(과세·보관 등) 줄은 ⛔ 오류로 즉시 분리. 나머지만 매칭으로.
3. 서버 비동기 유사도 계산 · 진행률
   업로드 직후엔 접수만. 서버가 배치로 점수를 매기며 진행률(0 → 1,000줄)을 보여주고, 끝나면 완료 알림. 이 진행 상태는 이력에 남지 않는다(§3).
4. 결과 요약 배분
   🟢 자동 매칭(1.0) / 🟡 후보(0.75~0.99) / 🔴 신규(0.74 이하) / ⛔ 오류(제외). 예: 650 / 250 / 92 / 8(가정).
5. 결과 표에서 보완 (공급사)
   줄별 상태 뱃지가 붙은 표. 공급사가 손대는 건 🔴 이미지 보완과 ⛔ 양식 교정(재업로드)뿐. 🟡 후보 선택은 MD 몫이라 공급사 화면엔 상태만 표시(§1 가정). 업로드 파일은 다시 다운로드 가능.
6. [MD 검수로 제출]
   ⛔만 제외되고, 🟢🟡🔴는 이번 제출에 함께 담겨 검수 대기로 넘어간다. 🔴 이미지 미첨부는 제출 차단이 아니라 MD 보완 대상(가정 — 차단으로 바꾸면 신규 비율만큼 제출이 막힌다).
7. MD 검수 → 판매 반영
   제출된 전 건이 MD 검수 대기로. 🟢 승인 · 🟡 후보 선택 후 승인 · 🔴 카테고리 지정 후 승인/거절. 거절 시 사유 전달·재제출.

대량 매칭 성능 — 동기 즉시 로딩 지양 🟠 방식 미정

100~1,000건을 업로드하면서 전 건을 기존 상품 전체와 즉시 비교하면(사전 필터 없음, §2-3) 로딩이 오래 걸려 화면이 멈춘다. 동기 즉시 처리는 지양한다.

예시 배분 (1,000줄, 가정)

수치는 프로토 예시 배분(650/250/92/8)을 참고한 가정이며 운영 실측이 아니다. 산식이 정해진 뒤 QA 실파일로 배분을 재측정한다.

6. 등록 이력 확정

공급사가 제출 완료한 내역만 쌓이는 페이지. 매칭 진행 중인 건은 여기 안 들어온다.

페이지네이션 20/50/100개씩 보기. 1차에는 구분 열에 엑셀만 뜬다. 예시 수치는 프로토 표기 기준.

7. MD 검수 화면 확정 · 1차 범위

MD 내부 화면. 제출된 줄을 엑셀 파일이 아니라 개별 상품 행으로 검수한다 — 1,000줄짜리 엑셀도 1,000개 행으로 펼쳐져 행별로 승인/거절된다. 🟡 후보 선택이 이 화면으로 왔다.

검색·필터 + 상태 탭

• 필터바. 공급사(전체/개별) · 상품명·유통사 상품명 검색 · 매칭 상태(전체 / 🟢 자동 / 🟡 후보 / 🔴 신규) · 요청자 · 요청일 범위 · 검색·초기화.
• 상태 탭. 검수 대기 N · 승인됨 · 거절됨.

검수 대기 표 컬럼

유사도 열 = 최고 후보 점수. 🟡는 후보 드롭다운(점수순)에서 하나를 고르거나 "해당 없음 → 신규". net공급가 = 공급사가 직접 입력한 값(단가 필드는 없음). 예시 점수는 가정.

행별 액션 + 일괄

8. 정책 · 예외

9. 변경 이력 (v13 → v2 → v3)

무엇이 언제 바뀌었나. v3에서 v2 서술을 교체·폐기한 항목은 아래에 그대로 남긴다.

v3 변경점 (2026-09-10)

v2 변경점 (2026-09-02) — 유지 / 교체 표시

10. 미정 항목 🟠 6건

진짜 미확정만 남긴다. 회의 2026-09-10으로 결정된 것은 먼저 표시하고 목록에서 뺐다.

결정됨 (2026-09-10)

남은 🟠 6건

개발 결정(기획 미정 아님): 유사도 산식(토큰화·필드 가중치·보조 필드 비율·1.0 복수 처리·브랜드 공란 처리) · 판정 API 분리 구조 · 임계 설정값 노출 여부.

11. 오픈 이슈

• 결정 그룹 생성 로직(M-1) — 신규=새 그룹? 매칭=히어로 그룹 편입? 9/16 전. 승계·1.0 복수 처리의 전제.
• 결정 자동 승인 정책(M-2) — 1차는 전건 검수. 정해지면 검수 물량과 MD 화면이 바뀐다.
• 결정 엑셀 대량 성능 방식(M-4) — 1차 동기+상한 vs 비동기 배치. 9/16 일정과 직결.
• 결정 그룹 메인 상품 정의(M-8) · 할인기준가(M-10) · 두 메뉴 데이터소스(M-6).
• 의존 유사도 산식(개발) — 9/16까지 확정돼야 QA 9/17에서 🟢🟡🔴 배분을 볼 수 있다. 임계 1.0/0.75는 설정값으로.
• 진행 양식 v3 파일 확정 — 공급사상품등록_양식_v3.xlsx 필수 9 / 선택 23 열 + 허용값 드롭다운(과세·보관). 공급사 배포 전 QA 실파일로 1회 업로드 통과.
• 진행 확인 못 함 2건 — 🟡 후보를 공급사 화면에도 보여줄지(§1 가정: 상태만) · 총량피킹 공급사 노출 여부(§양식 v3, v2 미노출 vs v3 선택 열).
• 진행 이미지 Zip 업로드 규격(파일명↔행 매핑)은 🔴 신규분에만 필요 — v13 방식 승계 여부 확인. 1차 시연 범위에 넣을지는 개발 판단.
• 2차 단건 등록 재기획 — 점수제 위에서 "입력 값에 따라 추천이 뜨는" UX, 후보 선택 주체(공급사/MD) 재결정.