JS-HUB 기획서 · 진승 딜리버리 포털

기획 목적 · 접근 방식

본 문서는 요구사항정의서의 "무엇을"을 이어받아 "어떻게 · 어떤 원칙으로" JS-HUB를 만드는지를 정의합니다. JS-HUB는 화면이 거의 없는 연동 · 관리 계층이지만, 여러 판매 채널이 함께 의존하는 가격 · 재고의 단일한 기준이라 설계 안전성이 무엇보다 중요합니다.

두 가지를 최우선 원칙으로 삼았습니다. 첫째 오버셀 방지 — 실제 재고보다 많이 팔리는 사고를 구조적으로 차단합니다. 둘째 주문 반영 정확성 — 이카운트에 대한 매출 반영이 이중으로 되거나, 반대로 누락되는 사고를 막습니다. 속도나 자동화보다 이 두 원칙이 항상 우선합니다.

이카운트 연동 원칙

진승몰 · 진승B2B · 통합 인증은 이카운트에 직접 접속하지 않고, 항상 JS-HUB가 보관한 최신 값을 조회합니다. 이카운트에 대한 조회는 사용자 요청이 있을 때마다 발생하지 않고, 정해진 주기로 미리 당겨와 갱신하는 방식으로만 이뤄집니다.

재고짧은 주기(약 10분)로 자주 재확인합니다. 재고는 변화가 생기면 이카운트에 즉시 반영되는 것으로 확인되어, 정해진 주기 확인만으로도 신뢰할 수 있는 최신 값을 유지할 수 있습니다.

상품 판매가(단가)재고보다 변동이 적어 더 느슨한 주기로 확인합니다.

이카운트 쓰기(반영)확정된 주문을 매출로 반영할 때만 발생합니다. 그 외에는 이카운트에 쓰지 않습니다.

이카운트 접속 정보(자격증명)는 JS-HUB만 단독으로 보관하며, 다른 서비스는 이카운트의 존재 자체를 알 필요가 없습니다.

재고 정합 · 오버셀 방지

여러 판매 채널이 동시에 같은 재고를 파는 구조에서는, 채널 간 경쟁만이 아니라 이카운트 쪽에서 발생하는 변화(창고 실사 · 폐기 · 관리자의 수동 조정 등)도 오버셀 원인이 됩니다. JS-HUB는 이 두 경우를 모두 봉쇄하도록 설계했습니다.

정기 대조 방식

매 확인 주기마다 "JS-HUB가 처리한 판매 내역을 감안했을 때 이 정도 남아있어야 한다"는 예상치와, 이카운트에서 실제로 받아온 값을 비교합니다. 실제 값이 예상보다 적으면 — JS-HUB가 모르는 경로로 재고가 줄어든 것이므로 — 즉시 사고로 취급해 해당 상품의 판매를 멈추고 운영팀에 경보를 보냅니다. 실제 값이 예상과 같거나 많으면(입고 등 안전한 방향) 정상적으로 최신 값을 갱신합니다.

안전 여유분(버퍼)

소비자에게 보여주는 "구매 가능 수량"은 실제 재고 그대로가 아니라, 판매 속도와 과거 변동 이력을 반영한 안전 여유분을 뺀 값입니다. 정합이 오래 지연되거나 최근 이상이 감지된 상품은 여유분을 자동으로 더 크게 잡아 보수적으로 판매합니다.

시작 시점 안전장치

서비스가 처음 켜지거나 보관하고 있던 값이 통째로 유실된 경우, 신뢰할 수 있는 재고 기준을 다시 확보하기 전까지는 전체 상품 판매를 일시 중단합니다. 불확실한 상태로 판매를 계속하는 대신, 확실해질 때까지 멈추는 쪽을 택했습니다.

확정 상태 — 재고 데이터가 이카운트에 즉시 반영된다는 점을 실제 확인했고, 이를 바탕으로 위 정기 대조 방식을 설계 확정했습니다(2026-07-13).

주문 반영 안전장치

확정된 주문을 이카운트에 매출로 반영하는 과정은 돈이 걸린 구간이라 가장 보수적으로 설계했습니다. 자동화보다 "확실하지 않으면 사람이 확인한다"는 원칙을 우선합니다.

1한 번에 한 건씩만 반영합니다. 여러 주문을 묶어 한 번에 보내면, 일부만 성공했을 때 어느 것이 성공했는지 구분하기 어려워지는 문제가 생깁니다. 이 규칙으로 그 문제 자체를 원천적으로 없앴습니다.

2이카운트로부터 응답을 받지 못해 성공 · 실패를 확인할 수 없는 경우, 시스템이 임의로 재시도하지 않고 사람이 직접 확인하는 대기열로 넘깁니다. 자동 재시도로 인한 이중 반영(중복 매출 · 중복 재고차감) 사고를 막기 위함입니다.

3재고 정기 대조(§3)는 특정 주문 하나를 자동으로 콕 집어 판정하는 데 쓰지 않습니다. 같은 시간대에 다른 주문 · 수동 조정이 섞이면 어느 주문이 문제인지 가려낼 수 없어, 잘못 판단하면 "결제는 됐는데 미출고" 같은 사고로 이어질 수 있습니다. 대신 "무언가 어긋났다"는 것을 운영팀에 알리는 사후 점검 신호로만 사용합니다.

확정 대기 사람 확인 없이 자동으로 안전하게 재시도할 수 있는 조건(같은 요청을 다시 보내도 결과가 달라지지 않는지 등)을 검증하는 실측이 진행 중입니다. 검증이 완료되면 이 조건을 만족하는 범위 안에서만 자동 재시도 경로를 추가합니다.

거래처별 단가 설계 확정

이카운트는 상품마다 여러 단계의 판매단가를 제공하지만, "어느 거래처가 어느 단가 단계를 쓰는지"는 이카운트에서 조회할 방법이 없다는 점을 공식 자료로 최종 확인했습니다. 이에 따라 거래처별 차등단가를 실제로 계산하는 역할은 JS-HUB가 전담한다는 설계가 다시 한번 검증됐습니다.

JS-HUB는 거래처마다 어느 단가 단계를 적용받는지를 직접 관리 · 매핑하고, 매핑이 없거나 누락된 거래처는 판매불가로 처리(안전 우선)합니다.

설계 확정 사항 요약

아래는 2026-07-13 기준 설계 단계에서 확정된 핵심 항목입니다.

항목	확정 내용
가격 · 재고 확인 주기	재고는 짧은 주기(약 10분), 상품 판매가는 더 느슨한 주기로 확인 — 이카운트 사용 한도 안에서 여유 있게 운영
거래처별 단가 해석	JS-HUB가 전담 소유 — 이카운트에 거래처별 단가 조회 기능이 없음을 공식 자료로 최종 확인
재고 정합 방식	정기 대조 + 지급여력 검사 + 안전 여유분 + 시작 시점 판매불가(§3)
주문 반영 안전장치	1건씩 반영 + 응답 유실 시 사람 확인 대기열 + 재고 대조는 사후 경보로만 사용(§4)
발주 취소 처리	이카운트 반영취소 · 재고 원복 · 주문 상태 갱신 · 소비 서비스 알림을 JS-HUB가 하나의 처리로 묶어 실행
오버라이드 우선순위	거래처 예외단가 절대우선 → 그 외(프로모션 · 수량할인 · 등급가) 중 가장 유리한 하나만 적용 → 최종 하한가 보장

확정 대기 · 다음 단계

아래 항목은 현시점에서 확정되지 않았으며, 후속 검토 또는 실측으로 확정합니다.

주문 반영 자동 재시도 조건

사람 확인 없이 자동 재시도를 허용할 수 있는 안전 조건 실측이 진행 중입니다(§4).

JS-HUB 관리자 화면 노출 형태

통합 관리자 포털의 일부로 둘지, 별도 화면으로 둘지 확정 대기.

복수 할인 충돌 시 세부 규칙

여러 프로모션이 동시에 해당할 때의 구체적 처리 방식은 후속 검토로 확정 예정.

진승몰(JS-MALL) 연동 상세

옵션 조합 · 상품 가격 조회 연동 방식은 확정 예정.

다음 단계 산출물

JS-HUB는 구매자 화면이 거의 없는 연동 계층으로, 다음 단계는 관리자 화면 노출 형태가 확정되는 대로 필요한 범위에서 정보구조(IA) · 화면 설계를 진행하고, 개발설계 산출물(아키텍처 · API 개요)을 순차 보완합니다.

본 문서는 초안(v0.1)이며 검수 대기 상태입니다. 내용 확인 · 수정 요청은 상단의 수정 요청을, 검수 완료 시 검수 승인을 이용해 주세요.