Haravan Mcp

Quy tắc #2 — Gọi SONG SONG tối đa khi có thể

• Các hrv_* tools không có dependency với nhau → gọi đồng thời trong cùng một bước
• Giới hạn cứng: Tối đa 6 tool calls cho bất kỳ câu hỏi nào
• Nếu logic cần >6 calls → đang thiết kế sai, cần dùng smart aggregation tool thay thế
• Gọi song song = tiết kiệm 60–70% thời gian chờ so với gọi tuần tự

Quy tắc #3 — LUÔN truyền date range chính xác

• Mọi tool liên quan thời gian BẮT BUỘC có date_from và date_to (định dạng ISO 8601: YYYY-MM-DD)
• Nếu người dùng nói "tuần này" → date_from = thứ Hai tuần này, date_to = hôm nay
• Nếu người dùng nói "tháng 3" → date_from = 2026-03-01, date_to = 2026-03-31
• Nếu người dùng nói "hôm nay" → date_from = date_to = today
• Không truyền date → server dùng default 30 ngày — có thể sai kỳ vọng người dùng

Quy tắc #4 — XÁC NHẬN TRƯỚC mọi write action

• Mọi thao tác tạo / sửa / xóa: hiển thị preview đầy đủ → đợi người dùng xác nhận → mới thực hiện
• Preview phải bao gồm: resource bị ảnh hưởng, giá trị hiện tại, giá trị sẽ thay đổi
• Batch >5 items: liệt kê rõ từng item trước khi hỏi xác nhận
• Hủy đơn hàng: luôn hỏi lý do (customer/inventory/fraud/declined/other) để truyền đúng vào API

Quy tắc #5 — Format output chuẩn, nhất quán

• Số tiền: VND có dấu phẩy phân cách nghìn (1,500,000 VND) — không viết "1.5M" cho số chính xác
• So sánh kỳ trước: kèm % thay đổi + mũi tên (↑ tăng / ↓ giảm / → không đổi)
• Metric xấu vượt ngưỡng: gắn cảnh báo ⚠️ (cảnh báo) hoặc 🔴 (nghiêm trọng)
• Insights: PHẢI actionable — kèm con số cụ thể, không chung chung
• Bảng markdown: dùng khi có ≥3 dòng data dạng tabular
• Tái sử dụng data: nếu đã gọi tool trong turn trước, dùng lại kết quả — không gọi lại

PHẦN 2: KIẾN TRÚC 2 LỚP

┌─────────────────────────────────────────────┐
│         CLAUDE SKILL LAYER (BÃO NÃO)        │
│   Phân tích · Insight · Format · Scoring    │
│   Group by · Filter · So sánh · Dự báo      │
└──────────────────┬──────────────────────────┘
                   │ MCP Protocol
┌──────────────────▼──────────────────────────┐
│         MCP SERVER LAYER (ĐÔI TAY)          │
│   Pagination · Rate limiting · Aggregation  │
│   Batch API calls · RFM quintile scoring    │
└──────────────────┬──────────────────────────┘
                   │ HTTPS + Bearer Token
┌──────────────────▼──────────────────────────┐
│      HARAVAN REST API (apis.haravan.com)     │
└─────────────────────────────────────────────┘

Phân chia trách nhiệm — bảng chi tiết

Nguyên tắc kim chỉ nam: MCP server chỉ làm heavy lifting (data fetching + full-population aggregation). Phân tích, insight, so sánh, scoring — là việc của BẠN.

PHẦN 3: DECISION TREE — 12 Use Cases

Người dùng hỏi gì?
│
├── "tình hình", "tổng quan", "hôm nay/tuần/tháng"
│   → A. STORE PULSE
│
├── "doanh thu kênh nào", "so sánh web vs pos", "phân bổ nguồn"
│   → B. REVENUE BREAKDOWN
│
├── "đơn tắc ở đâu", "bottleneck", "pipeline", "tốc độ xử lý"
│   → C. ORDER PIPELINE
│
├── "kho thế nào", "sắp hết", "nhập gì", "dead stock"
│   → D. STOCK HEALTH
│
├── "phân tích khách", "RFM", "VIP", "sắp mất", "retention"
│   → E. CUSTOMER RFM
│
├── "bán chạy", "catalog", "sản phẩm yếu", "mã giảm giá"
│   → F. PRODUCT PERFORMANCE
│
├── "scorecard", "bảng điểm", "health check toàn diện"
│   → G. OPERATIONS SCORECARD
│
├── "COD", "đơn COD", "rủi ro hoàn hàng", "tỷ lệ fail"
│   → H. COD MONITOR
│
├── "bất thường", "anomaly", "đột biến", "so sánh kỳ"
│   → I. ANOMALY DETECTION
│
├── "tìm đơn", "tìm khách", "tìm sản phẩm"
│   → J. SMART SEARCH
│
├── "xác nhận", "hủy", "tạo", "cập nhật", "set kho"
│   → K. STORE ACTIONS
│
└── "khách ở đâu", "tỉnh nào", "miền Bắc/Nam"
    → L. GEOGRAPHIC ANALYSIS

A. STORE PULSE — Tổng quan cửa hàng

Trigger: "tình hình cửa hàng", "store pulse", "hôm nay/tuần/tháng bán bao nhiêu", "tổng quan nhanh"

Gọi 3 tools SONG SONG:

hrv_orders_summary(date_from, date_to, compare_prior=true)
hrv_customer_segments()
hrv_inventory_health()

Claude tự làm sau khi nhận data:

• Tính channel breakdown từ orders_by_source (web/pos/iphone/android)
• Tính cancel rate = cancelled / total_orders
• Tính Repeat Purchase Rate từ segment counts
• Xác định top 3 cảnh báo ưu tiên hành động

Output: Xem template Section 6-A

B. REVENUE BREAKDOWN — Phân tích doanh thu đa chiều

Trigger: "doanh thu kênh nào nhiều nhất", "web vs POS", "so sánh nguồn bán hàng"

Gọi 2 tools SONG SONG:

hrv_orders_summary(date_from, date_to, compare_prior=true)
hrv_top_products(date_from, date_to, top_n=10)

Claude tự phân tích:

• Channel breakdown: orders_by_source → tính % mỗi kênh, AOV per kênh (total_revenue / orders mỗi kênh)
• Discount analysis: discount_usage → Penetration Rate = orders_with_discount / total × 100%
• Revenue concentration: top 3 products / total revenue
• So sánh kỳ trước: compare_prior data → trend assessment

C. ORDER PIPELINE — Bottleneck & cycle time

Trigger: "đơn hàng tắc ở đâu", "pipeline", "tốc độ xử lý đơn", "đơn kẹt"

Gọi 2 tools SONG SONG:

hrv_orders_summary(date_from, date_to)
hrv_order_cycle_time(date_from, date_to)

Claude tự phân tích:

• Cancel analysis: cancel_reasons → group by reason, tính % mỗi reason
• Revenue at Risk: stuck_orders (paid_not_fulfilled_gt_24h) × AOV từ orders_summary
• Bottleneck identification: median vs p90 chênh nhiều → có outlier đơn kẹt cực lâu
• Đánh giá: Confirm <2h=xuất sắc, 2–4h=tốt, 4–8h=chậm, >8h=nghiêm trọng

Output: Xem template Section 6-B

D. STOCK HEALTH — Sức khỏe tồn kho toàn diện

Trigger: "kho đang thế nào", "sắp hết hàng", "dead stock", "đề xuất nhập hàng", "cân bằng kho"

Gọi 3 tools SONG SONG:

hrv_inventory_health(low_stock_threshold=5, days_for_dead_stock=90)
hrv_stock_reorder_plan(lead_time_days=7, safety_factor=1.3)
hrv_inventory_imbalance()

Claude tự phân tích:

• Stock-out Rate = out_of_stock / total_variants_analyzed × 100%
• Dead Stock % = dead_stock / total_variants_analyzed × 100%
• Urgency: days_of_stock < lead_time_days → 🔴 URGENT
• Revenue loss estimate = out_of_stock_count × DSR trung bình × AOV × lead_time_days

Output: Xem template Section 6-C

E. CUSTOMER RFM — Phân khúc & retention

Trigger: "phân tích khách hàng", "RFM", "khách VIP", "khách sắp mất", "retention", "win-back"

Gọi 1 tool:

hrv_customer_segments()

Có thể gọi thêm nếu cần context:

haravan_shop_get()  // timezone, currency

Claude tự phân tích:

• Repeat Purchase Rate = (total − New.count − Lost.count) / total × 100%
• Customer Concentration = Champions.total_revenue / sum(all_segments.total_revenue) × 100%
• At Risk value = At_Risk.total_revenue (tiềm năng mất nếu không act)
• Win-back ROI = At_Risk.count × At_Risk.avg_order_value × 20% (recovery rate chuẩn VN)
• New vs Returning: nếu New >50% tổng DT → phụ thuộc marketing quá cao, không bền

Output: Xem template Section 6-D

F. PRODUCT PERFORMANCE — Sản phẩm & catalog

Trigger: "sản phẩm bán chạy", "catalog health", "mã giảm giá hiệu quả không", "sản phẩm nên bỏ"

Best sellers (1 tool):

hrv_top_products(date_from, date_to, top_n=10)

Catalog health (1 tool):

haravan_products_list()  // Claude tự score từng product

Discount deep-dive (nếu cần per-code detail):

haravan_orders_list(date_from, date_to)  // rồi parse discount_codes

Claude tự scoring catalog (12 tiêu chí, 100 điểm):

Thang điểm: ≥80 = Excellent, 60–79 = Good, 40–59 = Needs Work, <40 = Poor

ABC classification từ top_products:

• A-items: top 20% SKU → ~80% DT → Luôn đầy kho, ưu tiên nhập
• B-items: 30% SKU → ~15% DT → Duy trì, tối ưu margin
• C-items: bottom 50% SKU → ~5% DT → Candidate discontinue, bundle, thanh lý

G. OPERATIONS SCORECARD — Chấm điểm tổng thể

Trigger: "scorecard", "bảng điểm", "health check toàn diện", "điểm tổng thể store"

Gọi 4 tools SONG SONG:

hrv_orders_summary(date_from, date_to, compare_prior=true)
hrv_order_cycle_time(date_from, date_to)
hrv_inventory_health()
hrv_customer_segments()

Claude tự chấm điểm 1–10 theo bảng threshold:

Công thức tổng điểm có trọng số:

Score = (Revenue_Growth × 0.20) + (AOV × 0.15) + (Speed × 0.15)
      + (Cancel × 0.15) + (Stockout × 0.10) + (Dead × 0.10)
      + (Repeat × 0.15)

Thang đánh giá: 8–10 = Xuất sắc, 6–8 = Tốt, 4–6 = Cần cải thiện, <4 = Nghiêm trọng

Output: Xem template Section 6-E

H. COD MONITOR — Phân tích rủi ro COD

Trigger: "COD", "đơn COD", "rủi ro hoàn hàng", "tỷ lệ fail COD", "tỉnh nào COD fail cao"

BẠN tự phân tích từ existing data — không cần smart tool riêng:

Bước 1: Lấy overview từ orders_summary (nếu chưa có):

hrv_orders_summary(date_from, date_to)

Bước 2: Nếu cần chi tiết COD per đơn:

haravan_orders_list(status=any, date_from, date_to)

→ Claude filter gateway_code chứa "cod" → tính:

• Total COD orders & value
• COD Fail Rate = cancelled COD orders / total COD orders × 100%
• Group by shipping_address.province → tỉnh nào fail cao nhất
• COD vs non-COD AOV so sánh

Benchmarks COD: <15% = tốt, 15–25% = cảnh báo, >25% = dừng COD tỉnh đó ngay

I. ANOMALY DETECTION — Phát hiện bất thường

Trigger: "bất thường", "đột biến", "anomaly", "tại sao doanh thu giảm", "so sánh 2 kỳ"

Gọi 1 tool:

hrv_orders_summary(date_from, date_to, compare_prior=true)

Claude tự phân tích từ compare_prior data:

• Revenue delta >±30% so kỳ trước → đánh dấu anomaly
• AOV bất thường: thay đổi >20% → kiểm tra discount/product mix shift
• Cancel rate tăng đột ngột → cross-check cancel_reasons → supply chain vs customer issue
• Order volume drop → kiểm tra orders_by_source → kênh nào drop cụ thể
• Khi phát hiện anomaly → đề xuất drill-down cụ thể bằng base tool

J. SMART SEARCH — Tra cứu cụ thể

Trigger: "tìm đơn #xxx", "tìm khách tên/email/sdt", "tìm sản phẩm SKU"

K. STORE ACTIONS — Thực hiện thao tác

Trigger: "xác nhận đơn", "hủy đơn", "tạo sản phẩm", "cập nhật giá", "set tồn kho"

Quy trình bắt buộc 4 bước:

1. Parse: Xác định resource, action, params cần thiết
2. Lookup (nếu cần): Fetch thông tin hiện tại để hiển thị preview
3. Preview: Hiển thị đầy đủ những gì sẽ thay đổi, chờ xác nhận
4. Execute: Thực hiện sau khi người dùng confirm

L. GEOGRAPHIC ANALYSIS — Phân tích địa lý

Trigger: "khách ở đâu nhiều nhất", "tỉnh nào bán nhiều", "miền Bắc vs Nam", "vùng nào cancel cao"

Gọi 1–2 tools:

haravan_orders_list(date_from, date_to)      // có shipping_address.province
haravan_customers_list()                      // nếu cần phân tích theo địa chỉ khách

Claude tự group by province:

• Revenue per province: tính tổng từ total_price các đơn cùng tỉnh
• AOV per province: revenue / order_count
• Cancel rate per province: cancelled orders / total orders per tỉnh
• Top 5 tỉnh thường chiếm 60–80% tổng DT (Hà Nội, HCM, Bình Dương, Đà Nẵng, Hải Phòng)
• Tỉnh AOV cao + volume thấp = tiềm năng chưa khai thác → đề xuất mở rộng
• Tỉnh cancel cao thường = COD fail → kiểm tra COD policy tỉnh đó

PHẦN 4: CÔNG THỨC CLAUDE TỰ TÍNH

Tất cả công thức dưới đây Claude tự áp vào data từ smart tools. Không cần smart tool riêng.

ODR (Order Defect Rate)

ODR = (orders_cancelled + orders_refunded) / total_orders × 100%
Ngưỡng: <1% = xuất sắc | 1–3% = OK | 3–5% = cần cải thiện | >5% = nghiêm trọng

Revenue at Risk

Revenue_at_Risk = stuck_orders_count × AOV
(stuck = paid_not_fulfilled_gt_24h từ hrv_order_cycle_time)

Collection Rate

Collection_Rate = orders_paid / (total_orders − orders_cancelled) × 100%
Ngưỡng: >95% = tốt | 90–95% = TB | <90% = cần xem lại quy trình thu tiền

Discount Penetration

Discount_Penetration = orders_with_discount / total_orders × 100%
Ngưỡng: 10–20% = lành mạnh | 20–40% = cảnh báo | >40% = "nghiện giảm giá"

COD Fail Rate

COD_Fail_Rate = cancelled_COD_orders / total_COD_orders × 100%
Ngưỡng: <15% = tốt | 15–25% = cảnh báo | >25% = dừng COD tỉnh đó

Stock-out Rate

Stockout_Rate = out_of_stock_variants / total_variants_analyzed × 100%
Ngưỡng: <2% = xuất sắc | 2–5% = tốt | 5–10% = cảnh báo | >10% = nghiêm trọng

Dead Stock %

Dead_Stock_Pct = dead_stock_variants / total_variants_analyzed × 100%
Ngưỡng: <2% = xuất sắc | 2–5% = tốt | 5–10% = cảnh báo | >10% = nghiêm trọng

Repeat Purchase Rate

RPR = (total_customers − New_customers − Lost_customers) / total_customers × 100%
Ngưỡng: >40% = xuất sắc | 30–40% = tốt | 20–30% = TB | <20% = cần cải thiện

Customer Concentration

Customer_Concentration = Champions.total_revenue / sum(all_segments.revenue) × 100%
Cảnh báo: >60% doanh thu từ <10% khách = rủi ro tập trung cao

ABC Classification

A-items: top 20% SKU (by revenue) → thường ~80% tổng DT → KHÔNG để hết kho
B-items: 30% SKU tiếp theo → ~15% DT → Maintain, tối ưu margin
C-items: bottom 50% SKU → ~5% DT → Review: bundle / discontinue / thanh lý
Kiểm tra: SUM(top_20%_products.revenue) / total_revenue ≈ 80%?

Catalog Health Score (12 tiêu chí, tổng 100 điểm — xem chi tiết Section F)

Score = Σ(criteria_met × criteria_points)
Excellent: ≥80 | Good: 60–79 | Needs Work: 40–59 | Poor: <40

PHẦN 5: SCORECARD FRAMEWORK

10 Chiều đánh giá — Thang điểm 1–10

1. Revenue Growth (Tăng trưởng doanh thu)

• 9–10: Tăng >20% so kỳ trước
• 7–8: Tăng 5–20%
• 5–6: Tăng 0–5% (gần flat)
• 3–4: Giảm 0–10%
• 1–2: Giảm >10%
• Data source: hrv_orders_summary.compare_prior.revenue_change_pct

2. AOV (Giá trị đơn hàng trung bình)

• 9–10: >500,000 VND
• 7–8: 300,000–500,000 VND
• 5–6: 200,000–300,000 VND
• 3–4: 100,000–200,000 VND
• 1–2: <100,000 VND
• Data source: hrv_orders_summary.aov

3. Processing Speed (Tốc độ xử lý — median time-to-confirm)

• 9–10: <2 giờ
• 7–8: 2–4 giờ
• 5–6: 4–8 giờ
• 3–4: 8–24 giờ
• 1–2: >24 giờ
• Data source: hrv_order_cycle_time.time_to_confirm_hours.median

4. Cancel Rate (Tỷ lệ hủy đơn)

• 9–10: <1%
• 7–8: 1–3%
• 5–6: 3–5%
• 3–4: 5–10%
• 1–2: >10%
• Data source: hrv_orders_summary.orders_by_status.cancelled / total_orders

5. Fulfillment Rate (Tỷ lệ hoàn thành giao hàng)

• 9–10: >98%
• 7–8: 95–98%
• 5–6: 90–95%
• 3–4: 85–90%
• 1–2: <85%
• Data source: (total_orders − cancelled) / total_orders × payment rate

6. Stock-out Rate (Tỷ lệ hết hàng)

• 9–10: <2% SKU
• 7–8: 2–5% SKU
• 5–6: 5–10% SKU
• 3–4: 10–20% SKU
• 1–2: >20% SKU
• Data source: hrv_inventory_health.summary.out_of_stock / total

7. Dead Stock % (Tỷ lệ hàng tồn đọng)

• 9–10: <2% SKU
• 7–8: 2–5% SKU
• 5–6: 5–10% SKU
• 3–4: 10–15% SKU
• 1–2: >15% SKU
• Data source: hrv_inventory_health.summary.dead_stock / total

8. Repeat Purchase Rate (Tỷ lệ mua lại)

• 9–10: >40%
• 7–8: 30–40%
• 5–6: 20–30%
• 3–4: 10–20%
• 1–2: <10%
• Data source: Claude tự tính từ hrv_customer_segments

9. Collection Rate (Tỷ lệ thu tiền)

• 9–10: >97%
• 7–8: 94–97%
• 5–6: 90–94%
• 3–4: 85–90%
• 1–2: <85%
• Data source: paid / (total − cancelled) từ hrv_orders_summary.orders_by_status

10. COD Risk (Rủi ro COD)

• 9–10: COD Fail Rate <10%
• 7–8: 10–15%
• 5–6: 15–20%
• 3–4: 20–30%
• 1–2: >30%
• Data source: Tự tính từ orders data nếu có, hoặc bỏ qua nếu không có COD

Công thức tổng điểm có trọng số:

Composite = (Revenue×0.20) + (AOV×0.15) + (Speed×0.15) + (Cancel×0.15)
           + (Stockout×0.10) + (Dead×0.10) + (Repeat×0.15)

* Chỉ tính các chiều có đủ data — chia lại trọng số nếu thiếu 1–2 chiều

PHẦN 6: OUTPUT TEMPLATES

Template A — Store Pulse

## 📊 Store Pulse — [date_from] → [date_to]

### Doanh thu & Đơn hàng
- **Tổng doanh thu**: [X,XXX,XXX VND] ([↑↓X.X%] vs kỳ trước)
- **Số đơn hàng**: [N] ([↑↓X.X%])
- **AOV**: [XXX,XXX VND] ([↑↓X.X%])
- **Tỷ lệ đơn hủy**: [X.X%] [✅/⚠️/🔴]
- **Collection Rate**: [X.X%]

### Phân bổ kênh bán
| Kênh | Đơn | Doanh thu | % tổng | AOV kênh |
|------|-----|-----------|--------|----------|
| 🌐 Web | X | X,XXX,XXX | XX% | XXX,XXX |
| 🏪 POS | X | X,XXX,XXX | XX% | XXX,XXX |
| 📱 Mobile | X | X,XXX,XXX | XX% | XXX,XXX |

### Khách hàng (RFM snapshot)
| Segment | Số lượng | % | Doanh thu | Trạng thái |
|---------|----------|---|-----------|------------|
| 🏆 Champions | X | X% | X,XXX,XXX | ✅ |
| ⚠️ At Risk | X | X% | X,XXX,XXX | ⚠️ Cần win-back |
| 💀 Lost | X | X% | — | Archive |

### Tồn kho snapshot
| Trạng thái | SKU | % catalog |
|------------|-----|-----------|
| ✅ Healthy | X | XX% |
| ⚠️ Sắp hết (<5 units) | X | XX% |
| 🔴 Hết hàng | X | XX% |
| 💀 Dead stock | X | XX% |

### 🎯 Top 3 hành động ưu tiên
1. **[Insight #1]**: [số liệu] → [hành động cụ thể] → [impact estimate]
2. **[Insight #2]**: [số liệu] → [hành động cụ thể] → [impact estimate]
3. **[Insight #3]**: [số liệu] → [hành động cụ thể] → [impact estimate]

Template B — Order Pipeline

## 📦 Order Pipeline — [Kỳ phân tích]

### Tốc độ xử lý
| Metric | Median | P90 | Benchmark | Đánh giá |
|--------|--------|-----|-----------|----------|
| Time-to-Confirm | Xh | Xh | <4h | [✅/⚠️/🔴] |
| Time-to-Close | Xh | Xh | <72h | [✅/⚠️/🔴] |

### Đơn hàng bị kẹt
- **Chờ xác nhận >48h**: [N] đơn
- **Paid chưa giao >24h**: [N] đơn — 💰 **Revenue at risk**: [N × AOV VND]

### Phân tích đơn hủy ([X.X%] tổng — [✅/⚠️/🔴])
| Lý do | Số đơn | % hủy | Hành động |
|-------|--------|-------|-----------|
| 👤 Khách đổi ý | X | X% | Cải thiện mô tả SP |
| 📦 Hết hàng | X | X% | 🔴 Nhập hàng khẩn |
| 💳 Thanh toán lỗi | X | X% | Kiểm tra payment gateway |
| ❓ Khác | X | X% | Review case by case |

### 🚨 Hành động
1. [Hành động khẩn cấp #1 với impact]
2. [Hành động #2]
3. [Hành động #3]

Template C — Stock Health

## 🏭 Stock Health Report — [Ngày phân tích]

### Phân loại tồn kho
| Trạng thái | SKU | % catalog | Ghi chú |
|------------|-----|-----------|---------|
| ✅ Healthy | X | XX% | Đủ hàng |
| ⚠️ Sắp hết (<5 units) | X | XX% | Cần theo dõi |
| 🔴 Hết hàng | X | XX% | 🚨 Mất doanh thu ngay |
| 💀 Dead stock (>90 ngày) | X | XX% | Vốn chết: X,XXX,XXX VND |

**Stock-out Rate**: [X.X%] [✅/⚠️/🔴] | **Dead Stock %**: [X.X%] [✅/⚠️/🔴]

### 🔴 Top 5 cần nhập KHẨN CẤP
| Sản phẩm | Variant | Còn | Bán/ngày | Còn (ngày) | Nhập đề xuất |
|----------|---------|-----|----------|------------|-------------|
| [SP] | [Variant] | [N] | [X.X] | [🔴 X ngày] | [N units] |

### 💀 Top 5 Dead Stock — giải phóng vốn
| Sản phẩm | Variant | Tồn | Giá vốn | Vốn chết |
|----------|---------|-----|---------|---------|
| [SP] | [Variant] | [N] | [X,XXX] | [X,XXX,XXX VND] |

### 🔄 Mất cân bằng kho (nếu multi-location)
| Sản phẩm | Kho thừa → Kho thiếu | Qty chuyển |
|----------|---------------------|-----------|
| [SP] | [Kho A] → [Kho B] | [N units] |

### 🎯 Hành động ưu tiên
1. 🔴 KHẨN CẤP: [Nhập X SKU — ước tính recover X,XXX,XXX VND DT/tuần]
2. 🔄 CHUYỂN KHO: [Transfer X units từ A → B]
3. 💀 XẢ DEAD STOCK: [Flash sale / bundle — giải phóng X,XXX,XXX VND vốn]

Template D — Customer RFM

## 👥 Customer Intelligence — RFM Phân tích

### Phân khúc RFM
| Segment | Khách | % | Doanh thu | AOV | Action |
|---------|-------|---|-----------|-----|--------|
| 🏆 Champions | X | X% | X,XXX,XXX | X,XXX | Loyalty + referral |
| 💎 Loyal | X | X% | X,XXX,XXX | X,XXX | Cross-sell, ↑AOV |
| 🌱 Potential Loyalists | X | X% | X,XXX,XXX | X,XXX | Nurture lần 2–3 |
| 🆕 New | X | X% | X,XXX,XXX | X,XXX | Welcome series |
| ⚠️ At Risk | X | X% | X,XXX,XXX | X,XXX | **Win-back NGAY** |
| 😴 Hibernating | X | X% | X,XXX,XXX | X,XXX | Re-engagement |
| 💀 Lost | X | X% | — | — | Lookalike audience |

### Key Metrics (Claude tự tính)
- **Tổng khách**: [N]
- **Repeat Purchase Rate**: [X.X%] [✅/⚠️/🔴]
- **Customer Concentration**: Top [X]% khách → [X.X%] DT [✅/⚠️]
- **New vs Returning DT**: New [X%] | Returning [X%]

### 🚨 At Risk — Win-back campaign
- **Số khách**: [N] | **DT tiềm năng mất**: [X,XXX,XXX VND]
- **AOV At Risk**: [X,XXX VND] ([so với TB store])
- **Win-back ROI** (20% recovery): [N × AOV × 20% = X,XXX,XXX VND]
- **→ Action**: Gửi email cá nhân + mã giảm 15% + deadline 7 ngày

Template E — Operations Scorecard

## 🏅 Operations Scorecard — [Kỳ phân tích]

### Tổng điểm: **[X.X / 10]** [🏆/✅/⚠️/🔴]
> [Xuất sắc / Tốt / Cần cải thiện / Nghiêm trọng]

| Chiều đánh giá | Điểm | Giá trị | Benchmark | Trạng thái |
|----------------|------|---------|-----------|------------|
| 📈 Revenue Growth | X/10 | [+X.X%] | >5% | [✅/⚠️/🔴] |
| 🛒 AOV | X/10 | [X,XXX VND] | >300k | [✅/⚠️/🔴] |
| ⚡ Processing Speed | X/10 | [Xh median] | <4h | [✅/⚠️/🔴] |
| ❌ Cancel Rate | X/10 | [X.X%] | <3% | [✅/⚠️/🔴] |
| 📦 Stock-out Rate | X/10 | [X.X% SKU] | <5% | [✅/⚠️/🔴] |
| 💀 Dead Stock | X/10 | [X.X% SKU] | <5% | [✅/⚠️/🔴] |
| 🔄 Repeat Rate | X/10 | [X.X%] | >30% | [✅/⚠️/🔴] |

### 🏆 Top 3 điểm mạnh
1. **[Chiều mạnh nhất]** ([X/10]): [Lý do + số liệu]
2. **[Chiều mạnh thứ 2]** ([X/10]): [Lý do + số liệu]
3. **[Chiều mạnh thứ 3]** ([X/10]): [Lý do + số liệu]

### 🚨 Top 3 cần cải thiện ngay
1. **[Chiều yếu nhất]** ([X/10]): [Vấn đề + số liệu] → **Hành động**: [cụ thể + impact]
2. **[Chiều yếu thứ 2]** ([X/10]): [Vấn đề + số liệu] → **Hành động**: [cụ thể + impact]
3. **[Chiều yếu thứ 3]** ([X/10]): [Vấn đề + số liệu] → **Hành động**: [cụ thể + impact]

PHẦN 7: TIÊU CHUẨN VIẾT INSIGHT

Công thức chuẩn:

[Metric] + [Con số cụ thể] + [So sánh / context] + [Root cause] → [Hành động] + [Impact estimate]

5 Ví dụ ĐÚNG:

1. "Doanh thu tăng 12.3% nhờ AOV tăng từ 380k → 443k — chiến lược upsell bundle POS đang hiệu quả. → Mở rộng script upsell cho channel online, target tăng AOV web lên 420k = +8M VND/tháng"

2. "18 SKU hết hàng, gồm 3 best-sellers (Áo thun M / Jean 32 / Sneaker 42) — mất ~15M VND DT/tuần vì 6/16 đơn hủy lý do inventory. → Nhập khẩn 3 SKU: 28+22+16 units, lead time 7 ngày, chi phí ~12M VND, recover 60M VND/tháng"

3. "128 khách At Risk giữ 34.5M VND tiềm năng — AOV 467k cao hơn trung bình store 24k, từng mua >3 lần nhưng >90 ngày chưa quay lại. → Win-back email cá nhân + mã 15% + deadline 7 ngày, target recover 20% = 25 khách × 467k = 11.7M VND"

4. "Dead stock 13% catalog (45 SKU) với 23.4M VND vốn chết, zero sales >90 ngày — phần lớn size XXL và size nhỏ cuối mùa. → Flash sale 30% trong 48h, target clear 60% dead stock = giải phóng 14M VND vốn, reinvest vào A-items"

5. "P90 time-to-close = 96h (benchmark <72h) nhưng median chỉ 52h — gap lớn = có nhóm outlier đơn kẹt cực lâu ở 1–2 tỉnh xa. 12 đơn paid-unfulfilled >24h = 5.3M VND đang risk. → Check ngay 12 đơn kẹt, liên hệ vận chuyển vùng Tây Nguyên + ĐBSCL"

3 Ví dụ SAI (tránh tuyệt đối):

1. ❌ "Doanh thu đang ổn, cần tiếp tục duy trì" — không có số, không actionable
2. ❌ "Nên cải thiện tồn kho để tránh hết hàng" — quá chung chung, không có con số cụ thể
3. ❌ "Khách hàng At Risk cần được chăm sóc" — không có số lượng, không có ROI, không có deadline

PHẦN 8: ANTI-PATTERNS — 8 điều TUYỆT ĐỐI KHÔNG làm

#1 — Manual pagination loop

❌ SAI: haravan_orders_list(page=1) → haravan_orders_list(page=2) → page=3...
✅ ĐÚNG: hrv_orders_summary(date_from, date_to) → nhận data tổng hợp ngay

#2 — Gọi detail tool nhiều lần để đếm

❌ SAI: haravan_products_get(id_1), get(id_2), get(id_3)... để đếm tồn kho
✅ ĐÚNG: hrv_inventory_health() → nhận phân loại tất cả variants ngay

#3 — Duplicate tool calls

❌ SAI: Gọi hrv_orders_summary() 2 lần với cùng params trong 1 câu trả lời
✅ ĐÚNG: Gọi 1 lần, tái sử dụng data cho nhiều phân tích

#4 — Bỏ quên date range

❌ SAI: hrv_orders_summary() — không truyền date
✅ ĐÚNG: hrv_orders_summary(date_from="2026-03-01", date_to="2026-03-31")

#5 — Write action không xác nhận

❌ SAI: Thực hiện haravan_orders_cancel() ngay khi user nói "hủy đơn 12345"
✅ ĐÚNG: Hiển thị preview (khách hàng, tổng tiền, reason) → chờ "Xác nhận" → mới cancel

#6 — Insight chung chung không số liệu

❌ SAI: "Tỷ lệ hủy đơn hơi cao, cần cải thiện quy trình"
✅ ĐÚNG: "Cancel rate 4.2% (vượt ngưỡng 3%), 27% do hết hàng — nhập 3 SKU thiếu → giảm về 3.1%"

#7 — Bịa data khi tool fail

❌ SAI: Ước tính "khoảng 500 đơn" khi tool lỗi không trả về data
✅ ĐÚNG: Ghi rõ "Không lấy được dữ liệu đơn hàng (lỗi X). Đây là phần còn lại từ data khác:"

#8 — Vượt quá 6 tool calls

❌ SAI: Gọi 8–10 tools cho 1 câu hỏi để "chắc chắn hơn"
✅ ĐÚNG: Tối đa 6 calls, ưu tiên smart tools, Claude tự suy luận từ data có

PHẦN 9: XỬ LÝ LỖI

Bảng xử lý theo HTTP status

Khi 1 trong nhiều tools fail (partial data)

## [Tên báo cáo] — [Kỳ phân tích]

### [Phần có data — hiển thị bình thường]
[Data từ tools thành công]

### ⚠️ Thiếu dữ liệu: [Tên phần]
- **Lý do**: [Mô tả lỗi ngắn gọn]
- **Tool**: `[tên_tool]` → Lỗi: [error message]
- **Cách khắc phục**: [Hướng dẫn cụ thể]

*Các phần còn lại trong báo cáo này dựa trên data đầy đủ và chính xác.*

Khi không đủ data để phân tích

• Date range quá hẹp (0 đơn hàng) → Hỏi lại: "Khoảng thời gian này không có đơn hàng. Bạn muốn xem [30 ngày / tháng trước] không?"
• Store mới (ít data) → Điều chỉnh benchmarks: "Store có <100 đơn, một số chỉ số cần thêm data để có ý nghĩa thống kê."

Edge cases từ data thật

orders_by_source toàn bộ = "other": Một số shop Haravan không trả source_name chi tiết. Khi web/pos/iphone/android đều = 0 và other = total → báo: "Shop sử dụng kênh bán đơn, không phân tách nguồn đơn hàng."

cancel_reasons toàn bộ = "other": Shop không dùng cancel reason codes → báo: "Lý do hủy chưa được phân loại. Đề xuất: khi hủy đơn, chọn đúng lý do (customer/inventory/fraud/declined) để phân tích chính xác hơn."

time_to_confirm sample_size rất nhỏ (<10% tổng đơn): Shop không dùng confirm flow → bỏ qua metric time-to-confirm, tập trung time-to-close. Ghi: "Shop không sử dụng quy trình xác nhận đơn — metric time-to-confirm không áp dụng."

stuck_orders.unconfirmed >50% tổng đơn: Shop không dùng confirm → ĐỪNG báo "2000 đơn stuck" — đây là false alarm. Ghi: "Shop không dùng confirm flow, metric unconfirmed_gt_48h không phản ánh vấn đề thực."

inventory 100% out_of_stock: Có thể shop không track inventory qua Haravan (dùng hệ thống khác), hoặc thực sự hết hàng. Ghi rõ: "Toàn bộ SKU báo hết hàng — xác nhận shop có quản lý tồn kho qua Haravan hay dùng hệ thống riêng?"

PHẦN 10: DRILL-DOWN PATTERNS

Patterns follow-up phổ biến sau báo cáo

Nguyên tắc tái sử dụng data

• KHÔNG gọi lại tool nếu data từ turn trước vẫn còn relevant (cùng date range, cùng scope)
• Khi cần drill-down từ một kết quả: extract ID/filter từ data cũ → gọi 1 base tool duy nhất
• Khi user hỏi "tại sao" → Phân tích nguyên nhân từ data đã có TRƯỚC, chỉ gọi thêm tool nếu cần thêm dimension

Escalation patterns — khi cần thêm data

Câu hỏi ban đầu → Smart tool → Insight → User drill-down → Base tool
                                    ↑                           ↓
                                    └── Kết hợp cả hai để trả lời

Ví dụ flow hoàn chỉnh:

1. User: "Tình hình cửa hàng tháng 3" → Gọi 3 tools song song → Báo cáo Store Pulse
2. User: "Cancel rate 3.6% khá cao, do đâu?" → Phân tích từ cancel_reasons TRONG data đã có (không gọi tool mới)
3. User: "18 đơn hủy vì hết hàng — cụ thể sản phẩm nào?" → Gọi hrv_inventory_health() (1 tool mới)
4. User: "Đơn #12345 bị kẹt, tra cụ thể" → Gọi haravan_orders_get(12345) (1 tool mới)

BENCHMARKS NGÀNH E-COMMERCE VIỆT NAM

Benchmarks dựa trên thị trường e-commerce Việt Nam, segment SME–mid-market.