공급사 상품 등록 — 기술 명세서 (데이터 모델·API)

0. 범위·전제

📦 이 문서는 「상품 등록」(퍼즈3) 기술명세입니다. 「단가·품절 업데이트」(퍼즈2)는 별도 문서 → 단가 기획 · 단가 프로토타입.

구현 성격: 신규 구축이 아니라 기존 어드민 위에 얇은 워크플로우 레이어. 상품·권한·매칭 화면/로직은 대부분 이미 존재. 새로 만드는 핵심은 ① 로그인 공급사 스코프 ② 제출 → MD 검수 큐 ③ 메뉴. 코어 구조는 기존과 동일.

이 명세 = 공급사 셀프 상품 등록 + MD 검수 + 상품 정보 변경의 워크플로우 레이어(퍼즈3). 기존 상품·히어로코드·공급사 테이블 참조/연동.
탑재 위치 = 공급사 상품 관리 어드민(qa-admin 뒤의 운영 어드민). ※ orderhero-ai-v2/backend(사장님 AI)는 별개 시스템.
퍼즈 구성: 단가·품절 업데이트 = 퍼즈2(별도). 이 문서 = 상품 등록·정보 변경(퍼즈3).
핵심 원칙: 공급사 제출/변경은 전부 초안·요청 상태 → MD 검수 후 반영(자동 반영 없음). 모든 처리는 감사 로그.

1. 데이터 모델

신규 테이블 5개(워크플로우) + 기존 테이블 참조. 컬럼명은 예시(실 DB 컨벤션에 맞춰 조정).

주의: 아래 테이블·컬럼은 기획 단계 제안(참고용)이다. 상품·단가 관련은 이미 운영 DB에 스키마가 존재하므로, 실제 구현은 운영 DB 스키마를 쿼리해 확정하고 여기서는 대기 큐(change_request·price_batch)·감사(audit_log) 레이어만 새로 얹는다.

1.1 submission — 제출 건(batch)

컬럼	타입	설명
id	PK
supplier_id	FK supplier	제출 공급사
type	enum	single / excel
file_name	varchar null	엑셀 원본 파일명(+스토리지 경로)
status	enum(파생)	pending / partial / done / rejected (item 집계)
created_at, created_by	ts, FK user

1.2 submission_item — 등록 상품(신규/매칭)

컬럼	타입	설명
id	PK
submission_id	FK
status	enum	draft / pending / approved / rejected / hold
name, supplier_product_name	varchar	표시 상품명 / 공급사 상품명
supplier_product_code	varchar	공급사 내부코드(공급사간 키 불가)
category_l/m/s	varchar	대/중/소
weight, qty, origin, manufacturer, brand	varchar	중량·수량·원산지·제조사·브랜드
taxable, store, delivery_type	enum	과세여부 / 보관(상온·냉장·냉동) / 배송유형(MFC·택배·허브)
price, net_price, discount_base	int	단가 / net공급가 / 할인기준가
hero_code	varchar null	매칭/발급된 히어로코드 (MD 확정 전 null 가능)
candidates	json	매칭 후보 [{hero_code, name, score}]
images	json	{main, sub1, sub2} URL
warns	json	["대표 이미지 없음","중량 단위 모호" …]
reject_reason	varchar null
linked_product_id	FK product null	승인 시 생성/연결된 실제 상품
created_at, decided_at, decided_by

1.3 change_request — 상품 정보 변경 요청 핵심

컬럼	타입	설명
id	PK
product_id	FK product	대상(승인완료) 상품
supplier_id	FK
source	enum	single (정보 변경은 단건)
diff	json	[{field, label, from, to}] — 변경된 정보 필드만(name·category·weight·origin·supplier_product_name·opt …). 단가·재고·품절은 퍼즈2
apply_at	ts null	null=컨펌 즉시 / 값=예약 적용일시
status	enum	pending / confirmed / rejected
reason	varchar	요청 사유 / 반려 사유
created_at, created_by, decided_at, decided_by, applied_at

1.4 단가·품절 업데이트 → 퍼즈2

단가·품절 변경(승인 큐·예약·엑셀 배치·변경률 경고)은 퍼즈2 별도 문서 — 단가 업데이트 기획 참조. 관련 실 테이블: seller_price_schedule_manage·seller_product_price_excel_raw·seller_product_price_reservation_history.

1.5 audit_log — 감사 로그

컬럼	타입	설명
id, at	PK, ts
entity_type, entity_id	varchar	submission_item / change_request / price_batch
actor, action	varchar	supplier\|md · 제출/컨펌/반려/보류/수정후승인 …
before, after	json	필드 단위 전/후

1.6 기존 테이블 (참조·연동)

product(공급사 상품) — 승인 시 submission_item → product 생성/연결. 단가·재고·품절·이미지는 change_request 컨펌 시 갱신.
hero_group(히어로코드/그룹) — hero_code·parent_hero·그룹상품명. 매칭/발급 대상.
supplier — 공급사 + 공급사 상품코드 매핑(재업로드 자동 prefill의 키).

2. 열거형·상태

열거	값
submission_item.status	draft → pending → (approved \| rejected \| hold)
change_request.status	pending → (confirmed \| rejected)
stock_status(판매상태)	on_sale(판매중) / soldout_temp(일시품절) / soldout_long(장기품절)
store(보관)	room / cold / frozen
delivery_type	mfc / parcel / hub
warns(예외)	no_image / weight_unit_ambiguous / match_none / weight_outlier / code_not_found

3. API — 공급사

베이스 /api/supplier · 인증=공급사 토큰(자기 데이터만, §6). 목록은 ?q=&status=&page=&size=.

메서드·경로	설명
GET `/products`	본인 상품 목록(검색·필터·페이지)
GET `/products/{id}`	상세 + 변경 이력(audit) + 진행중 변경요청
GET `/match?name=&weight=&origin=&category=`	히어로코드 매칭 후보 top-N(§5)
POST `/submissions`	단건 등록(초안 제출). body=상품필드+hero_code?(매칭선택)
POST `/submissions/bulk`	엑셀 등록. multipart(file) → 행별 자동매칭+버킷 결과 반환
GET `/submissions`	등록 이력(제출 건 목록)
POST `/products/{id}/change-requests`	상품 정보 변경 요청(diff) — 단가·품절은 퍼즈2

범위: 이 API는 상품 등록·정보 변경(퍼즈3). 단가·품절 업데이트 API는 퍼즈2 → 단가 업데이트 기획.

예시: 변경 요청 생성 POST /products/{id}/change-requests

// request
{
  "source": "single",
  "apply_at": null,                 // null=컨펌 즉시, "2026-07-01T09:00"=예약
  "reason": "원가 변동",
  "diff": [
    {"field":"name","label":"상품명","from":"쥬시쿨 180","to":"쥬시쿨 180ML"},
    {"field":"origin","label":"원산지","from":"국산","to":"수입산"}
  ]
}
// response 201
{ "id": 9012, "status": "pending", "product_id": 4737 }

예시: 매칭 GET /match

// GET /match?name=쥬시쿨&weight=180ML&category=가공품/음료
{ "candidates": [
  {"hero_code":"HERO-00E516","name":"쥬시쿨 180ML(자두)","weight":"180ML","score":0.92,"image":"…"},
  {"hero_code":"HERO-00E517","name":"쥬시쿨 190ML","weight":"190ML","score":0.71}
]}  // 없으면 candidates:[] → 신규 플로우

4. API — MD 검수

베이스 /api/admin/supplier-review · 인증=MD role. 메뉴 "공급사 등록 상품 검수".

메서드·경로	설명
GET `/queue?type=submission\|change&filter=risk`	검수 대기(제출건/변경요청). "수상한 것만" 필터
POST `/items/{id}/approve`	승인/수정후승인. body=수정필드+hero_code(연결/발급)
POST `/items/{id}/reject`	반려(reason)
POST `/items/{id}/hold`	보류
POST `/submissions/{id}/bulk-approve`	위험 플래그 없는 건 일괄 승인
POST `/change-requests/{id}/confirm`	변경 컨펌 → diff를 product에 반영(apply_at 반영)
POST `/change-requests/{id}/reject`	변경 반려(reason)
POST `/change-requests/bulk-confirm`	전체 일괄 컨펌

예시: 변경 컨펌 POST /change-requests/{id}/confirm

// 처리: status=confirmed, decided_by/at 기록
//   apply_at=null → 즉시 product 필드 반영 / 값 → 스케줄러가 해당 시각에 반영
//   audit_log에 before/after(diff) 기록
{ "ok": true, "applied_at": "2026-07-01T09:00", "product_id": 4737 }

5. 매칭 API 상세

입력 다필드: 이름 + 중량 + 원산지 + 카테고리. (실측 top-1: 이름만 75% → +중량 86%)
v1: DB 풀텍스트(이름) + 중량/원산지 가중 필터로 top-N. 인덱스 조회라 단건 ms, 대량 1,000건 수 초.
v2: 임베딩/벡터(ANN) 도입 — 동의어·표기변형 대응. 응답 형식 동일.
자동확정 임계(대량): top-1 단독 금지 — 이름강 + (중량|원산지|바코드) 일치 + top1−top2 점수차 충족 시만. 신선/수산 순수 자동확정 금지.
오매칭 비용 큼(가격비교 키 오염) → 보수적 임계.

6. 인증·권한

기존 권한 체계 재사용: 신규 인증 설계가 아니라 어드민의 기존 로그인·메뉴 권한에 공급사 role 추가 — 로그인 시 「공급사 상품 관리」 메뉴만 노출. (파트너 계정 일부 기존재 가능 → 실 구조 확인 필요, §9)
공급사 스코핑: 모든 /api/supplier/*는 본인 supplier_id로 강제 필터(타사 데이터 접근 차단) — 프로토타입의 "공급사 선택"은 없고 로그인 idx로 자동 고정.
공급사 편집 가능 = 공급가(net)·재고·품절·공급사상품명·옵션. 플랫폼/MD 전용(읽기/쓰기 불가) = 마진율·세금(과세/면세)·배송단가·최종 판매가·히어로코드·MFC노출·총량피킹 — 응답에서 제외.

7. 에러·예외

상황	처리
필수 누락(상품명·카테고리·중량·단가·이미지[신규])	400 + 누락 필드 목록
중량 단위 없음	경고(warn) + 검수필요 플래그(차단 아님)
엑셀 파싱 오류 행	행 단위 분리(⛔), 정상 행만 진행
중복 등록(같은 hero/상품코드)	409 또는 확인 플래그
단가 일괄 — 공급사 상품코드 미매칭	해당 행 제외(code_not_found), 결과에 표시
컨펌 시 히어로코드 미지정	422 — 연결/발급 후 승인

8. 비기능

예약 실행: change_request.apply_at / price_batch.schedule_at → 스케줄러(크론/큐)가 해당 시각에 반영, done_at 기록.
감사 로그: 모든 제출·컨펌·반려·수정후승인을 audit_log에 before/after로. 상품 이력 화면이 이걸 조회.
동시성: 같은 상품에 변경요청 중복 시 최신 우선/충돌 표시. 컨펌은 멱등.
재업로드 prefill: (supplier_id, supplier_product_code) ↔ hero_code 매핑 캐시 → 다음 업로드 자동 연결.

9. 미정 · 협의 필요

단가 계산식·종합 단가 등 단가 관련 미정은 퍼즈2로 이동 → 단가 기획.
실 DB 스키마 대조: §1 컬럼은 제안 → 운영 DB 쿼리로 실제 스키마 확정.
공급사 권한/계정 구조: 기존 파트너 로그인이 어디까지 되어 있는지 실 어드민 확인.
바코드(GTIN) 필드 신설 + 백필 = v2/v3(가공식품 정확매칭 인에이블러).
착수 전 게이트: 실사용 MD 미팅(다음 주 워크샵)·신규 중 기존 매칭 비율(실측 ≈65%)·MD 시간배분(인터뷰).