API Phân hạng Hội viên & Báo cáo Insights

Cơ chế phân hạng thành viên của Zodutcan xét duyệt hoàn toàn dựa trên Tổng doanh số chi tiêu thực tế (Spend Threshold) và gắn liền với Quỹ chia thưởng (Profit Sharing Pool). Các endpoint này cung cấp dữ liệu cho màn hình Lộ trình thăng hạng và Bảng xếp hạng trên zodutcan-user.

---

1. Lộ trình Phân hạng Thành viên

Trả về thông tin hạng hiện tại của hội viên, tiến độ chi tiêu để lên hạng tiếp theo và danh sách tất cả các hạng thành viên kèm tỷ lệ chia thưởng từ quỹ (profit_sharing_percentage).

• Method: GET
• Endpoint: /api/{locale}/v1/member/insights/tiers
• Auth: auth:member_api (Bearer Token)

Query Parameters

Tham số	Kiểu	Mô tả
club_id	string	UUID của chi nhánh/câu lạc bộ muốn xem (tùy chọn).
year_month	string	Tháng chu kỳ chốt quỹ (YYYY-MM). Mặc định: tháng hiện tại.

Response Thành công

{
  "status": "success",
  "data": {
    "current_tier": {
      "id": "019b8d48-tier-gold",
      "name": "Hạng Vàng (Gold)",
      "level": 3,
      "profit_sharing_percentage": 5.0,
      "achieved_at": "2026-04-10T14:20:00Z",
      "expires_at": "2027-04-10T23:59:59Z",
      "is_upgrade": true,
      "color": "#F59E0B"
    },
    "spending_progress": {
      "current_period_spend": 28500000,
      "next_tier_spend_required": 50000000,
      "spending_percentage": 57.0,
      "remaining_spend": 21500000,
      "next_tier_name": "Hạng Kim Cương"
    },
    "pool_metrics": {
      "net_profit": 150000000,
      "estimated_pool_share": 750000
    },
    "all_tiers": [
      {
        "level": 1,
        "name": "Hạng Đồng (Bronze)",
        "spend_threshold": 0,
        "profit_sharing_percentage": 1.0
      },
      {
        "level": 2,
        "name": "Hạng Bạc (Silver)",
        "spend_threshold": 10000000,
        "profit_sharing_percentage": 3.0
      },
      {
        "level": 3,
        "name": "Hạng Vàng (Gold)",
        "spend_threshold": 20000000,
        "profit_sharing_percentage": 5.0
      },
      {
        "level": 4,
        "name": "Hạng Kim Cương (Diamond)",
        "spend_threshold": 50000000,
        "profit_sharing_percentage": 8.0
      }
    ]
  }
}

---

2. Bảng Xếp hạng Hội viên Hàng tháng

Hiển thị thứ hạng đóng góp doanh số của hội viên và top các thành viên dẫn đầu trong tháng.

• Method: GET
• Endpoint: /api/{locale}/v1/member/insights/monthly-ranking
• Auth: auth:member_api (Bearer Token)

Query Parameters

Tham số	Kiểu	Mô tả
month	string	Tháng xem xếp hạng dạng YYYY-MM.

Response Thành công

{
  "status": "success",
  "data": {
    "my_ranking": {
      "rank": 8,
      "name": "Nguyễn Văn A",
      "total_spending": 8200000,
      "tier_name": "Hạng Vàng"
    },
    "top_rankings": [
      {
        "rank": 1,
        "name": "Trần *** Hùng",
        "total_spending": 32000000,
        "tier_name": "Hạng Kim Cương"
      },
      {
        "rank": 2,
        "name": "Lê *** Mai",
        "total_spending": 24500000,
        "tier_name": "Hạng Vàng"
      }
    ]
  }
}

---

3. Thống kê & Hiệu suất Tích luỹ

• GET /api/{locale}/v1/member/analytics: Tổng quan tỷ lệ chi tiêu, tỷ lệ đóng góp từ F1.
• GET /api/{locale}/v1/member/analytics/monthly-performance: Biểu đồ chi tiêu và tiền thưởng nhận được theo từng tháng.
• Auth: auth:member_api (Bearer Token)