PIAAR OPERATION GUIDE
재고·품절 관리 사용 설명서
SellerTool 재고 동기화부터 품절 기록, 안전재고, NAVER 검색 추세와 Dooray 알림까지 현재 운영 규칙을 한곳에 정리했습니다.
운영 기준일 2026-09-21
수치 기준은 현재 배포 코드와 동일
수치 기준은 현재 배포 코드와 동일
01 · SETUP
시작 전 준비
SellerTool 계정별 연결과 무인 자동화 비밀정보를 분리해 보호합니다.
| 항목 | 사용 목적 | 저장 위치 / 주의사항 |
|---|---|---|
| 상단 API 연결 | SellerTool Key 검증·전용 보안 세션·최초 재고 동기화 | API Key와 Secret Key는 서버에서 암호화하며 브라우저 저장소와 API 응답에 남기지 않습니다. |
| 보안 세션 유지 | 사이트 로그인 토큰이 없어도 SellerTool Key 검증 후 발급 | HttpOnly 쿠키로 30일 유지되어 매일 Key를 다시 입력할 필요가 없고, 연결 전에는 모든 재고·SKU·검색어 화면이 비어 있습니다. |
| 기존 데이터 유지 | 기존 운영 SellerTool Key는 원래 데이터 공간에 연결 | 과거 품절 이력, 확인 검색어, 추가 모니터링과 NAVER 이력을 삭제하거나 새로 만들지 않고 계속 사용합니다. |
| Azure Function App 설정 | Azure Functions Timer의 SellerTool·NAVER·Dooray 자동화 | API Key, Secret Key, MongoDB, 암호화 키와 Dooray Webhook은 Azure Function App의 환경변수로만 관리합니다. |
| 사용자 데이터 공간 | 재고·검색어·추가 모니터링 격리 | 로그인 토큰의 사용자 ID로 자동 결정되며 화면에서 다른 값을 지정할 수 없습니다. |
신규 사용자는 SellerTool 연결 전에는 재고·SKU·검색어 데이터를 표시하지 않습니다. `SellerTool 테스트`는 저장된 서버 연결로 동기화를 재확인하고, `서버 연결 확인`은 로컬/배포 서버의 기본 상태만 확인합니다.
02 · INVENTORY
재고 동기화와 대시보드 사용
SellerTool 현재 재고와 MongoDB의 품절 이력을 결합해 오늘 필요한 조치를 보여줍니다.
- 1. SellerTool 동기화
입출고 이력이 있는 활성 옵션의 현재 재고·입고·출고·ETA 정보를 가져옵니다.
- 2. 품절 이벤트 판정
당일 출고가 있으면서 재고가 0 이하가 된 SKU만 품절 후보로 판정하고 7일 중복 제거를 적용합니다.
- 3. 대시보드 갱신
이번 달 품절, 위험 SKU, 안전재고, 최근 입고, 판매중지 목록을 다시 계산합니다.
- 4. 업무 처리
오늘 처리할 항목에서 구매프로세스를 확인하거나 판매중지하고, 필요하면 판매중지 목록에서 복구합니다.
| 화면 | 의미와 사용법 |
|---|---|
| 상단 KPI | 이번 달 전체 품절 횟수, 품절 옵션 수, 고위험, 긴급 수량입니다. `!`에서 집계 기준을 확인하고 고위험·긴급 카드를 눌러 SKU 목록을 봅니다. |
| 오늘 처리할 항목 | 오늘 새로 기록된 품절 SKU입니다. `확인하기`는 구매프로세스 Google Sheet의 옵션코드를 찾아 정확한 셀로 이동합니다. |
| 판매중지 | 입고 예정이 없거나 더 이상 판매하지 않을 SKU를 소프트 삭제합니다. 기록은 남고 자동 모니터링에서 제외됩니다. |
| 복구 | 판매중지 전체 목록에서 SKU를 검색해 복구하면 다음 동기화부터 다시 모니터링합니다. |
| 비상 파일 업로드 | API 장애나 과거 이관 시 CSV·TSV·XLSX를 사용할 수 있습니다. 평상시에는 SellerTool 자동 동기화를 우선합니다. |
03 · STOCKOUT
품절 이벤트 기록 규칙
매일 재고가 0이라고 해서 매일 품절 횟수를 추가하지 않습니다. 실제 출고와 회복 여부를 함께 봅니다.
최초 품절일을 1회로 기록하고, 1~6일차의 반복 보고는 같은 품절 1회로 처리하며, 7일차부터 새 품절 1회로 다시 기록합니다.
| 상황 | 기록 결과 |
|---|---|
| 당일 출고 수량이 0 | 현재 재고가 0 이하라도 새 품절 이벤트를 만들지 않습니다. |
| 당일 출고 있음 + 현재 재고 0 이하 | 품절 후보가 되며 아래 중복 제거 규칙을 적용합니다. |
| 최근 기록 후 1~6일 안에 계속 재고 0 | 같은 품절 상태로 보고 추가 기록하지 않습니다. |
| 최초 기록일 기준 7일차 도달 | 재고가 계속 0이어도 새로운 품절 1회로 기록합니다. |
| 중간에 재고가 양수로 회복된 뒤 다시 0 | 7일 이내라도 새로운 품절로 기록합니다. |
| 당일 입고 후 같은 날 다시 품절 | 재입고 후 재품절이므로 새로운 품절로 기록합니다. |
모든 월간 횟수, 위험도, S/A/B/C 우선순위는 이 중복 제거가 끝난 `유효 품절 이벤트`를 기준으로 계산합니다.
04 · RATING
위험도와 S·A·B·C 입고 우선순위
두 값은 모두 최근 3개월 품절 이력을 사용하지만 목적과 조건이 다릅니다. 높은 조건부터 먼저 적용합니다.
위험도: 현재 품절 반복의 심각도
| 위험도 | 조건 | 화면 의미 |
|---|---|---|
| 위험 | 이번 달 4회 이상 또는 최근 3개월 합계 7회 이상 | 긴급 확인 대상 |
| 주의 | 이번 달 3회 이상 또는 최근 3개월 합계 5회 이상 | 고위험 확인 대상 |
| 관심 | 최근 3개월 합계 2회 이상 | 반복 품절 모니터링 대상 |
| 안정 | 최근 3개월 합계 2회 미만 | 위험도 알림 대상 아님 |
입고 우선순위: 다음 발주·입고의 우선 정도
| 등급 | 조건 | 추천수량 가중치 |
|---|---|---|
| S | 최근 3개월 모두 1회 이상 품절 또는 합계 7회 이상 | 최근 입고수량 × 1.5 |
| A | 이번 달 3회 이상 또는 최근 3개월 합계 5회 이상 | 최근 입고수량 × 1.2 |
| B | 이번 달 2회 이상 또는 최근 3개월 합계 3회 이상 | 최근 입고수량 × 1.0 |
| C | 최근 3개월 합계 2회 이상 | 최근 입고수량 × 1.0 |
| 등급 없음 | 최근 3개월 합계 2회 미만 | 최근 입고수량 × 1.0 |
예: 최근 3개월이 `1회 / 1회 / 1회`이면 합계는 3회지만 매월 품절이 발생했으므로 S입니다. 반대로 `0회 / 0회 / 4회`이면 위험도는 위험이고 입고 우선순위는 A입니다.
05 · SAFETY STOCK
추천수량과 안전재고 규칙
최근 입고수량을 기준값으로 사용하며, 품절 빈도가 높은 S·A SKU에 추가 완충수량을 둡니다.
| 계산 | 공식 |
|---|---|
| 추천수량 | 최근 입고수량 × 등급 가중치 후 올림. 최근 입고수량이 없으면 0 |
| 안전재고 | MAX(추천수량 − 최근 입고수량, 0) |
| S 예시 | 최근 입고 20개 → 추천 30개 → 안전재고 10개 |
| A 예시 | 최근 입고 20개 → 추천 24개 → 안전재고 4개 |
| B·C 예시 | 최근 입고 20개 → 추천 20개 → 추가 완충분 0개 |
| 안전재고 상태 | 판정 조건 (높은 단계 우선) |
|---|---|
| Critical | 재고 0이고 ETA 없음, 또는 재고가 안전재고 미만이고 ETA 없음, 또는 S 등급 재고가 안전재고 이하 |
| High | 재고가 안전재고 이하이고 ETA 있음, 또는 A 등급 재고가 안전재고 이하, 또는 재고가 안전재고의 절반 이하 |
| Warning | 현재 재고가 안전재고 + 2개 이하 |
| 알림 목록 포함 조건 | 최근 3개월 유효 품절 2회 이상 + 최근 입고수량 있음 + 위 세 상태 중 하나 |
07 · ADDITIONAL MONITORING
추가 SKU와 시장 조사 키워드
자동 품절 감시 밖의 판매중 SKU와 아직 판매하지 않는 시장 키워드를 같은 주간 일정으로 조사하되 운영 목적은 분리합니다.
| 구분 | 등록 방법 | 자동 처리 | Dooray |
|---|---|---|---|
| 판매중 SKU 추가 | SellerTool 상품명 검색 → 옵션 확인 → 대표·연관 검색어·NAVER 카테고리·담당자 저장 | 매주 월요일 NAVER 추이를 수집합니다. 이후 품절 이력으로 자동 감시 조건에 진입하면 검색어 관리로 자동 전환됩니다. | 검색량 급등락과 연결된 위험 SKU가 있으면 발송 대상에 포함 |
| 시장 조사 키워드 | SellerTool 상품 없이 대표·연관 검색어·NAVER 카테고리·담당자 저장 | 매주 월요일 전주·전월·전년 동기 상대 지수를 저장하고 화면에서 차트를 조회합니다. | 시장 조사 키워드는 Dooray 알림에서 제외 |
| 상태 | 시스템 동작 |
|---|---|
| 이미 검색어 관리에 있는 SKU | 중복 등록을 차단하고 이미 자동 모니터링 중임을 안내합니다. |
| 이미 추가 모니터링 중인 SKU | 중복 등록을 차단하고 기존 추가 모니터링 항목을 유지합니다. |
| 추가 SKU가 자동 감시 대상이 됨 | 별도 복사 작업 없이 기존 검색어와 누적 추이를 보존한 채 검색어 관리 목록으로 이동합니다. |
| 추가 SKU 삭제 | 추가 모니터링과 Dooray 참여만 중단하는 소프트 삭제입니다. 검색어 설정과 기존 NAVER 추이 기록은 보존됩니다. |
| 시장 조사 키워드 | 재고·품절 SKU 등급에는 연결하지 않고 시장 수요 판단 자료로만 사용합니다. |
| 시장 조사 키워드 삭제 | 삭제 확인 후 키워드와 저장된 모든 NAVER 추이 데이터를 물리 삭제합니다. 복구할 수 없으며 이후 주간 조사도 중단됩니다. |
두 유형 모두 카테고리 칸에서 검색어 관련 NAVER 카테고리를 선택하거나 코드를 직접 입력할 수 있습니다. 카테고리를 입력하면 Shopping Insight가 주 조사 지표이고 Search Trend는 참고 지표가 됩니다. 비워 두면 Search Trend가 주 조사 지표가 됩니다.
`검색어 관리`의 SKU는 SellerTool 전체 0재고 목록이 아니라 최근 3개월 입출고 이력에서 발견되어 재고 위험 시스템이 관리하는 활성 SKU입니다. 추가 모니터링은 이 자동 범위 밖을 담당자가 보완하는 기능입니다.
08 · CATEGORY DEMAND
카테고리 검색량 현황
판매 SKU와 관계없이 선택한 NAVER 쇼핑 카테고리 전체의 수요 방향을 수동으로 조사합니다.
조회 대상은 가구/인테리어, 생활/건강, 패션의류, 패션잡화의 1,948개 카테고리이며, 다른 대분류는 요청량 절감을 위해 제외합니다. 이 기능은 예약 작업이나 페이지 접속으로 실행되지 않고 담당자가 `전체 카테고리 조회`를 확인했을 때만 시작합니다.
| 항목 | 운영 규칙 |
|---|---|
| 30일 내 재조회 | 30일 안에 다시 누르면 현재 남은 사용량과 이번 조회 예상 사용량을 먼저 보여줍니다. 담당자가 확인하면 즉시 다시 조회하고, 취소하면 API를 호출하지 않습니다. |
| 비교 기간 | 최근 완료 7일 평균을 직전 7일, 직전 달 전체, 전년 같은 7일과 각각 비교합니다. |
| 행 색상 | 긴급 SKU와 동일한 기준으로 상승은 연한 빨강, 하락은 연한 파랑, 기준 미충족은 흰색으로 표시합니다. |
| 추세 필터 | `상승만` 또는 `하락만`을 눌러 해당 판정만 확인합니다. 두 필터는 서로 동시에 선택되지 않으며, 선택된 버튼을 다시 누르면 전체 판정으로 돌아갑니다. 대분류·카테고리 검색과 함께 사용할 수 있습니다. |
| 상품 보러가기 | 각 행의 버튼을 누르면 해당 경로의 마지막 소분류와 세분류를 검색어로 조합해 NAVER Shopping의 SmartStore 상품 검색 결과를 새 창에서 엽니다. |
| 1688 상품 찾기 | 상승으로 판정된 카테고리에만 표시합니다. NAVER 카테고리 전용 구매 용어를 우선하고, 없는 경우 마지막 소분류와 세분류를 중국어 구매 검색어로 번역합니다. GB18030으로 인코딩해 1688 중국 사이트의 동종 상품을 찾으며, 번역이 실패하면 깨진 검색어로 이동하지 않고 재시도를 안내합니다. |
| 고정 표 머리글 | 결과 목록 안에서 아래로 스크롤해도 최근 1주 지수·전주·전월·전년 비교와 판정 머리글을 상단에 계속 표시합니다. |
| Dooray 키워드 요약 | 매주 월요일 10시에 확인 완료 검색어의 최신 NAVER 추세를 자동 수집해 급등락 키워드와 연결 위험 SKU를 발송합니다. 자동 메시지가 오지 않았을 때에는 `Dooray 키워드 요약 발송`으로 즉시 다시 실행할 수 있습니다. |
| 판정 기준 | 전주·전월은 ±30%, 전년 동기는 ±50% 중 하나를 넘으면 상승 또는 하락으로 분류합니다. |
| API 이용량 | 1회 예상 650회입니다. 화면은 이 서버가 수행한 SKU·시장 조사 키워드·카테고리 Shopping Insight 호출을 모두 합산해 당월 사용량과 실시간 잔여량을 표시합니다. |
이 화면의 값은 실제 검색 횟수가 아니라 NAVER 통합검색 쇼핑 영역과 NAVER 쇼핑에서 발생한 클릭의 0~100 상대 지수입니다.
NAVER API HUB는 Client ID/Secret으로 호출할 수 있는 사용량 조회 API를 제공하지 않습니다. 따라서 화면의 잔여량은 이 서버가 기록한 호출 기준이며, 다른 프로그램에서 같은 API Key를 사용한 호출까지 포함한 공식 당월 사용량은 NAVER Cloud Console에서 확인해야 합니다. 콘솔 값은 약 1분 뒤 반영될 수 있습니다.
09 · TREND RATING
NAVER 검색 추세의 등급 반영
품절 이력으로 기본 S/A/B/C를 계산하고, SKU별 주 수요 지표를 반영해 운영에 사용하는 최종 등급을 계산합니다.
| 신호 | 조건 | 최종 등급 |
|---|---|---|
| 강한 급상승 | 전주 +30%, 전월 +30%, 전년 +50% 기준 중 2개 이상 충족 | 즉시 1단계 상승 |
| 상승 반복 | 상승 기준을 하나 이상 충족한 신호가 2회 연속 | 1단계 상승 |
| 상승 관찰 | 상승 기준 1개 충족, 연속성 없음 | 기본 등급 유지 |
| 강한 급하락 반복 | 하락 기준 2개 이상 충족한 상태가 2회 연속 | 보호 조건이 없을 때 1단계 하락 |
| 하락 보호 | 현재 재고가 안전재고 이하, 재고 0 이하, 또는 ETA 없음 | 급하락이어도 기본 등급 유지 |
| 혼합·안정·데이터 없음 | 상승과 하락 방향이 충돌하거나 조정 기준 미충족 | 기본 등급 유지 |
카테고리 코드가 있으면 Shopping Insight를 주 판정 지표로 사용하고 NAVER 검색량은 참고합니다. 카테고리 코드가 없으면 Search Trend와 검색량을 주 판정·조사 지표로 사용합니다.
등급은 `등급 없음 → C → B → A → S` 순서로 한 단계씩 이동하고 S보다 높아지지 않습니다. 기본 등급과 최종 등급은 화면에 함께 표시되며, 최종 등급은 화면 필터와 Dooray의 SKU 등급에 사용됩니다.
Dooray 급등락 알림과 최종 등급 조정은 서로 다른 규칙입니다. Dooray는 전주·전월 ±30% 또는 전년 ±50% 중 하나만 넘어도 키워드 변동을 알리지만, 등급 상승은 2개 기준 동시 충족 또는 2회 연속 상승이 필요합니다.
카테고리 코드가 없는 SKU가 Search Trend로 등급 조정을 받으면 최종 등급 옆에 `NAVER 검색량 참고`를 표시하고, 같은 문구를 Dooray SKU 항목에도 표시합니다. Shopping Insight보다 범위가 넓은 NAVER 검색 데이터를 사용한 결과임을 담당자가 즉시 구분하기 위한 표시입니다.
10 · AUTOMATION
Dooray 알림과 자동화 일정
재고와 키워드 추세 Dooray는 Azure Functions Timer가 자동 발송하며, 키워드 수동 발송은 자동 작업 실패 시의 비상 수단으로 사용합니다.
| 일정 | 자동 실행 내용 | 실패 시 |
|---|---|---|
| 월~금 17:00 (한국시간) | SellerTool 재고 동기화 → 품절·안전재고 재계산 → 통합 Dooray 알림 | SellerTool 동기화가 실패하면 오래된 재고로 통합 알림을 보내지 않습니다. |
| 매주 월요일 10:00 (한국시간) | 확인 완료 대표 검색어 자동 조회 → 급등락 키워드와 연결 위험 SKU Dooray 발송 | 한 키워드 실패는 기록하고 나머지 키워드는 계속 처리합니다. |
| 자동 미발송 시 수동 실행 | 검색량 현황 → `Dooray 키워드 요약 발송` → 자동 작업과 같은 수집·판정·발송을 즉시 재실행 | 완료 결과에서 조회·이상 변동·실패 건수를 확인합니다. |
재고 자동화는 SellerTool 동기화가 성공한 뒤 통합 재고 알림을 발송하며, 순서가 바뀌거나 중간 단계가 실패하면 다음 단계로 진행하지 않습니다.
GitHub Actions에서는 예약 실행이나 Dooray 발송을 하지 않습니다. 프론트엔드는 Vercel, 백엔드와 평일 재고·월요일 키워드 자동화 Timer는 Azure Functions가 담당합니다. `검색량 현황`의 수동 버튼은 월요일 자동 메시지가 오지 않았을 때 사용하는 비상 발송 경로입니다.
| Dooray 유형 | 포함 대상 |
|---|---|
| 통합 재고 알림 | 품절 위험과 안전재고 대상을 SKU 코드로 합쳐 `즉시 확인`과 `재고 주의`로 분류합니다. |
| 키워드 추세 알림 | 먼저 급상승·급하락 대표 검색어를 보여주고, 그 아래에 해당 검색어에 연결된 현재 재고 위험 SKU만 표시합니다. |
| 수동 발송 | 재고 화면에서 현재 전체 상태를 즉시 발송합니다. 자동 증분 알림의 발송 기준선은 변경하지 않습니다. |
재고 위험 Dooray에서는 추천수량 대비 현재 재고가 70% 이상이면 건강한 재고로 제외합니다. 최근 3일 안에 입고된 S·A SKU는 알림 표시 우선순위를 각각 A·B로 한 단계 완화합니다.
운영 점검 순서
- 월요일 10시 자동 키워드 메시지를 확인하고, 미발송 시 검색량 현황의 `Dooray 키워드 요약 발송`으로 재실행합니다.
- 평일 17시 통합 재고 메시지에서 즉시 확인 SKU의 구매·입고 계획을 확인합니다.
- 입고 계획이 없으면 판매중지하고, 재판매가 결정되면 판매중지 목록에서 복구합니다.
- 검색어가 부정확하면 검색어 관리에서 수정 후 `확인 저장`합니다.