shopport 0.1.13 → 0.2.0

package/dist/skills/weekly-analysis/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: sppt-weekly-analysis
+description: |
+  전주 대비 매출 변화 원인 분석 + 채널 수수료 최적화 컨설팅 워크플로우.
+  Use when asked to "주간 분석", "왜 매출이 줄었어", "채널별 원인 분석", "지난 주 비교",
+  "매출이익률 분석", "수수료율 변화", "원인 분석해줘".
+---
+
+# weekly-analysis
+
+## 채널 분류 컨텍스트
+
+`channelMeta` 응답의 각 채널에는 `type`(own-mall/open-market/vertical-specialist), `entryRequirement`(open/contract), `hasChannelBrandValue`가 정의되어 있다.
+
+**수수료 최적화 시 주의:**
+- `entryRequirement: "contract"` 채널은 계약 관계이므로 단순 수수료 비교로 비중 축소를 권고하면 안 된다.
+- `hasChannelBrandValue: true` 채널은 높은 수수료에 마케팅·브랜딩·노출 가치가 포함된다.
+- 채널 간 이동보다 **같은 채널 내 최적화**(유입경로, 단가, 프로모션)가 실행 가능성이 높다.
+
+## Data Collection
+
+커맨드 **1회**로 모든 데이터를 가져옵니다:
+
+```bash
+sppt report weekly --json
+```
+
+옵션:
+- `--period 7d` (기본값) — 채널/상품 비교 기간
+- `--top 10` (기본값) — 채널/상품 표시 개수
+- `--settlement-days 30` (기본값) — 정산 집계 기간
+
+응답 구조:
+- `channelMeta` — 채널 특성 (type/entryRequirement/hasChannelBrandValue)
+- `channelFees` — 채널별 수수료 전체 (유입경로별 포함)
+- `reportByChannel` — 채널별 현재/전주 비교 + diff
+- `reportByProduct` — 상품별 현재/전주 비교 + diff (top 10)
+- `settlement` — 채널별 정산 요약 (매출/수수료/순수익/실효수수료율)
+- `costs` — SKU별 원가 목록 (미등록 시 null)
+
+## Analysis Steps
+
+### Step 1: 채널 수수료율 분석
+
+1. **채널별 수수료율 랭킹** — 채널 분류(자사몰/오픈마켓/버티컬)와 함께 표시. 표본 < 5건은 신뢰도 낮음 표기.
+2. **실효수수료율** = Σ(채널_비중 × 채널_수수료율), 오픈마켓 채널 간 비중과 버티컬 채널 비중을 분리해서 보여줌.
+3. **스마트스토어 유입경로 분석** — `fee list smartstore` 결과로 마케팅링크 유입 비중이 실효율에 미치는 영향 추정. 규칙 미등록 시 annualRevenue/브랜드스토어 여부에 따른 오차 가능성 언급.
+4. **오픈마켓 내 믹스 최적화** — smartstore ↔ cafe24 비중 이동 시 절감 효과. 버티컬 채널은 별도 분석.
+5. **집중 리스크** — 단일 채널 비중 > 70% 경고. 단, 버티컬 채널의 비중 감소는 리스크가 아닌 채널 특성으로 해석.
+6. **전주 대비 변화** (데이터 있을 때만) — 채널믹스 효과 vs 채널내 수수료율 변화로 분해.
+
+### Step 2: 채널별 매출 변화 분해
+
+`reportByChannel.diff` 배열에서 직접 읽는다.
+
+- 채널별 매출 증감, volumeEffect / priceEffect 요약
+- 채널 점유율 변화 (이전주 비중 → 이번주 비중)
+
+### Step 3: Top Mover 상품 귀속
+
+`reportByProduct.diff` 배열 상위 항목을 채널 변화에 귀속시킨다.
+
+- 매출 변화 상위 5개 상품: revenueChange, volumeDiff%, priceDiff%
+- 특이값 (신규 등장 또는 완전 소멸 상품) 별도 언급
+
+### Step 4: 공헌이익률 분석 (원가 있을 때만)
+
+- 이번주 vs 지난주 공헌이익률 변화
+- 상품 믹스 효과 vs 단가 변화 효과로 분해
+
+## AI Interpretation
+
+위 데이터를 바탕으로 각 변화에 대해:
+1. 가능한 원인 (내부/외부 구분)
+2. 우선순위 조치 (즉각 / 단기 / 검토)
+3. 수수료 최적화: 채널 특성과 진입 가능성을 고려한 실행 가능한 방안만 제안. "버티컬 채널 축소" 같은 계약 외 조치는 제안하지 않는다.
+
+## Error Handling
+
+- **이번주 매출이 이전주 대비 -80% 이상**: 데이터 수집 공백 가능성 → `sppt order pull` 재실행 안내 후 분석
+- **원가 미등록**: Step 4 skip
+- **채널 1개만**: 수수료 비교 skip, 단가/볼륨 분석 집중
+- **settlement 표본 부족** (채널별 < 5건): 수수료율 신뢰도 낮음 표기, `--settlement-days 90` 권장
+- **smartstore fee rule 미등록**: 실효율 신뢰도 낮음 표기. `sppt settlement hints smartstore`로 annualRevenue 설정 권장.

package/dist/skills/weekly-analysis/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "주간 매출 분석"
+  short_description: "전주 대비 매출 변화 원인 분석 + 채널 수수료 최적화"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-weekly-analysis 이번 주 매출 분석해줘"
+
+policy:
+  allow_implicit_invocation: true

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shopport",
-	"version": "0.1.13",
+	"version": "0.2.0",
 	"description": "커머스 운영 자동화 CLI — Cafe24, Coupang, SmartStore, Shopify 통합 관리",
 	"type": "module",
 	"bin": {