<!-- Nhúng CSS và JavaScript từ CDN Mapvina -->
<link rel="stylesheet" href="https://unpkg.com/mapvina-gl@1.1.0/dist/mapvina-gl.css" />
<script src="https://unpkg.com/mapvina-gl@1.1.0/dist/mapvina-gl.js"></script>

<div id="map" style="width: 100%; height: 600px;"></div>

Khởi tạo bản đồ với style đường phố streets.json và tọa độ trung tâm:^[1]

const map = new mapvinagl.Map({
  container: 'map',
  style: 'https://maps.mapvina.com/styles/v2/streets.json?key=public_key',
  center: [106.68, 10.77], // Trung tâm TP. Hồ Chí Minh [lng, lat]
  zoom: 11
});

Bước 3: Nạp GeoJSON Source và bật tham số Cluster

Lắng nghe sự kiện load của bản đồ để đảm bảo các tài nguyên kiểu dáng đã sẵn sàng, sau đó thêm nguồn dữ liệu khách hàng với tùy chọn gom cụm:^[1][3]

map.on('load', () => {
  map.addSource('customers', {
    type: 'geojson',
    data: customerGeoJsonData, // Hoặc đường dẫn URL trả về GeoJSON
    cluster: true,
    clusterRadius: 50,         // Gom cụm trong bán kính 50px
    clusterMaxZoom: 14         // Zoom từ cấp 15 trở lên sẽ tách thành điểm đơn lẻ
  });
});

Bước 4: Khai báo 3 lớp hiển thị đồ họa bằng WebGL

Sử dụng hàm map.addLayer() để thêm 3 lớp đồ họa theo thứ tự: vòng tròn cụm, nhãn số lượng và điểm lẻ:^[2]

// 1. Lớp vòng tròn cụm
map.addLayer({
  id: 'clusters',
  type: 'circle',
  source: 'customers',
  filter: ['has', 'point_count'],
  paint: {
    'circle-color': [
      'step',
      ['get', 'point_count'],
      '#38bdf8', // Dưới 50 khách hàng: màu xanh lam nhạt
      50,
      '#fbbf24', // Từ 50 đến 200 khách hàng: màu vàng cam
      200,
      '#f87171'  // Trên 200 khách hàng: màu đỏ san hô
    ],
    'circle-radius': [
      'step',
      ['get', 'point_count'],
      18,        // < 50 điểm: bán kính 18px
      50,
      24,        // 50 - 200 điểm: bán kính 24px
      200,
      30         // > 200 điểm: bán kính 30px
    ],
    'circle-stroke-width': 2,
    'circle-stroke-color': '#ffffff'
  }
});

// 2. Lớp chữ hiển thị số lượng khách trong cụm
map.addLayer({
  id: 'cluster-count',
  type: 'symbol',
  source: 'customers',
  filter: ['has', 'point_count'],
  layout: {
    'text-field': '{point_count_abbreviated}',
    'text-font': ['Noto Sans Regular'],
    'text-size': 12
  },
  paint: {
    'text-color': '#0f172a'
  }
});

// 3. Lớp điểm khách hàng lẻ (khi đã zoom sâu hoặc điểm đứng tách biệt)
map.addLayer({
  id: 'unclustered-point',
  type: 'circle',
  source: 'customers',
  filter: ['!', ['has', 'point_count']],
  paint: {
    'circle-color': '#0284c7',
    'circle-radius': 6,
    'circle-stroke-width': 2,
    'circle-stroke-color': '#ffffff'
  }
});

Bước 5: Bắt sự kiện tương tác thu phóng và cửa sổ thông tin (Popup)

Để mang lại trải nghiệm tiện lợi cho người dùng, chúng ta gắn hai sự kiện tương tác chính:^[1]

Thao tác 1 — Nhấp vào cụm để mở rộng vùng hiển thị: Sử dụng hàm getClusterExpansionZoom() của Mapvina GL JS để tự động tính toán cấp độ zoom cần thiết và chuyển cảnh mượt mà bằng map.easeTo():^[1]

map.on('click', 'clusters', (e) => {
  const features = map.queryRenderedFeatures(e.point, { layers: ['clusters'] });
  const clusterId = features[0].properties.cluster_id;

  map.getSource('customers').getClusterExpansionZoom(clusterId, (err, zoom) => {
    if (err) return;
    map.easeTo({
      center: features[0].geometry.coordinates,
      zoom: zoom + 0.5,
      duration: 500
    });
  });
});

Thao tác 2 — Nhấp vào điểm đơn lẻ để mở popup: Mở popup hiển thị thông tin chi tiết của khách hàng đó:^[1]

map.on('click', 'unclustered-point', (e) => {
  const coordinates = e.features[0].geometry.coordinates.slice();
  const props = e.features[0].properties;

  new mapvinagl.Popup()
    .setLngLat(coordinates)
    .setHTML(`<strong>${props.name}</strong><br>Mã KH: ${props.id}<br>Hạng: ${props.tier}`)
    .addTo(map);
});

Thao tác 3 — Đổi con trỏ chuột khi di chuột qua cụm và điểm:

map.on('mouseenter', 'clusters', () => { map.getCanvas().style.cursor = 'pointer'; });
map.on('mouseleave', 'clusters', () => { map.getCanvas().style.cursor = ''; });
map.on('mouseenter', 'unclustered-point', () => { map.getCanvas().style.cursor = 'pointer'; });
map.on('mouseleave', 'unclustered-point', () => { map.getCanvas().style.cursor = ''; });

5. File mã nguồn HTML mẫu hoàn chỉnh (Chạy ngay không cần cài đặt)

Toàn bộ giải pháp trên được tích hợp trong một file HTML duy nhất dưới đây. Bạn chỉ cần lưu đoạn mã này thành file index.html và mở bằng bất kỳ trình duyệt nào (Chrome, Edge, Safari, Firefox) có thể thử 5.000 điểm dữ liệu giả lập quanh một số đô thị Việt Nam với public_key thử nghiệm sẵn có:^[1][4]

<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Mapvina GL JS - Demo Gom cụm 5.000 Khách hàng</title>
  <link rel="stylesheet" href="https://unpkg.com/mapvina-gl@1.1.0/dist/mapvina-gl.css" />
  <script src="https://unpkg.com/mapvina-gl@1.1.0/dist/mapvina-gl.js"></script>
  <style>
    body, html, #map { width: 100%; height: 100%; margin: 0; padding: 0; font-family: sans-serif; }
    .info-box {
      position: absolute; top: 16px; left: 16px; z-index: 10;
      background: rgba(255, 255, 255, 0.95); padding: 14px 18px;
      border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); max-width: 300px;
    }
  </style>
</head>
<body>
  <div class="info-box">
    <h3 style="margin: 0 0 8px 0; font-size: 15px;">Mapvina 5.000 Khách hàng</h3>
    <div style="font-size: 13px; color: #475569;">Gom cụm tự động bằng GPU WebGL Canvas. Nhấp vào cụm để mở rộng.</div>
  </div>

  <div id="map"></div>

  <script>
    // Khởi tạo bản đồ Mapvina GL JS
    const map = new mapvinagl.Map({
      container: 'map',
      style: 'https://maps.mapvina.com/styles/v2/streets.json?key=public_key',
      center: [106.68, 10.77],
      zoom: 10
    });

    map.on('load', () => {
      // Sinh ngẫu nhiên 5.000 điểm mẫu tại khu vực đô thị Việt Nam
      const features = [];
      for (let i = 1; i <= 5000; i++) {
        const lng = 106.68 + (Math.random() - 0.5) * 0.35;
        const lat = 10.77 + (Math.random() - 0.5) * 0.35;
        features.push({
          type: 'Feature',
          geometry: { type: 'Point', coordinates: [lng, lat] },
          properties: { id: `KH-${i}`, name: `Khách hàng #${i}` }
        });
      }

      // Thêm GeoJSON Source bật tính năng cluster
      map.addSource('customers', {
        type: 'geojson',
        data: { type: 'FeatureCollection', features: features },
        cluster: true,
        clusterRadius: 50,
        clusterMaxZoom: 14
      });

      // Lớp vòng tròn cụm đổi màu theo số lượng
      map.addLayer({
        id: 'clusters',
        type: 'circle',
        source: 'customers',
        filter: ['has', 'point_count'],
        paint: {
          'circle-color': ['step', ['get', 'point_count'], '#38bdf8', 50, '#fbbf24', 200, '#f87171'],
          'circle-radius': ['step', ['get', 'point_count'], 18, 50, 24, 200, 30],
          'circle-stroke-width': 2,
          'circle-stroke-color': '#fff'
        }
      });

      // Lớp chữ số đếm
      map.addLayer({
        id: 'cluster-count',
        type: 'symbol',
        source: 'customers',
        filter: ['has', 'point_count'],
        layout: {
          'text-field': '{point_count_abbreviated}',
          'text-font': ['Noto Sans Regular'],
          'text-size': 12
        },
        paint: { 'text-color': '#0f172a' }
      });

      // Lớp điểm khách hàng lẻ
      map.addLayer({
        id: 'unclustered-point',
        type: 'circle',
        source: 'customers',
        filter: ['!', ['has', 'point_count']],
        paint: {
          'circle-color': '#0284c7',
          'circle-radius': 6,
          'circle-stroke-width': 2,
          'circle-stroke-color': '#fff'
        }
      });

      // Click zoom cụm
      map.on('click', 'clusters', (e) => {
        const features = map.queryRenderedFeatures(e.point, { layers: ['clusters'] });
        const clusterId = features[0].properties.cluster_id;
        map.getSource('customers').getClusterExpansionZoom(clusterId, (err, zoom) => {
          if (!err) map.easeTo({ center: features[0].geometry.coordinates, zoom: zoom + 0.5 });
        });
      });

      // Click điểm lẻ xem popup
      map.on('click', 'unclustered-point', (e) => {
        const coords = e.features[0].geometry.coordinates.slice();
        const props = e.features[0].properties;
        new mapvinagl.Popup()
          .setLngLat(coords)
          .setHTML(`<strong>${props.name}</strong><br>Mã: ${props.id}`)
          .addTo(map);
      });

      map.on('mouseenter', 'clusters', () => map.getCanvas().style.cursor = 'pointer');
      map.on('mouseleave', 'clusters', () => map.getCanvas().style.cursor = '');
    });
  </script>
</body>
</html>

6. Phân công vai trò, KPI kỹ thuật và chi phí vận hành

Để triển khai giải pháp này vào hệ thống thực tế một cách an toàn và có kiểm soát, sự phối hợp giữa các bộ phận kỹ thuật là yếu tố quyết định.^[4]

Phân công trách nhiệm các bộ phận

• Frontend Engineer: Chịu trách nhiệm nhúng thư viện mapvina-gl, cấu hình các biểu thức paint động cho lớp cụm, xử lý sự kiện tương tác chuột và đảm bảo giao diện responsive trên cả thiết bị di động lẫn máy tính bàn.^[1][2]
• Backend / Data Engineer: Chuẩn hóa dữ liệu tọa độ khách hàng (Geocoding), xây dựng API truy vấn không gian theo Bounding Box (sử dụng PostGIS hoặc GeoJSON nén), thiết lập bộ nhớ đệm (Redis/CDN) cho các truy vấn lặp lại.^[5]
• Product Manager / Tech Lead: Thiết lập các tiêu chuẩn về bán kính gom cụm phù hợp với từng nghiệp vụ (bán lẻ, bưu chính hay giao hàng) và kiểm soát ngân sách lưu lượng gọi API.^[4]

Chỉ số cần đo trong thử nghiệm

Không có một ngưỡng hiệu năng chung cho mọi thiết bị. Trước khi đưa vào sản phẩm, hãy ghi lại bốn chỉ số trên máy tính và điện thoại đại diện: FPS khi kéo/zoom, thời gian từ lúc nhận GeoJSON đến lúc layer ổn định, bộ nhớ của tab và dung lượng phản hồi sau nén. Đội dự án tự đặt ngưỡng chấp nhận dựa trên thiết bị người dùng, số điểm thực tế và mục tiêu trải nghiệm; các con số trong demo không phải cam kết hiệu năng của Mapvina.^[1][6]

Chi phí và Quản trị rủi ro vận hành

1. Kiểm soát chi phí Map Tiles: Việc người dùng zoom và pan liên tục sẽ tạo ra các request tải mảnh bản đồ (Vector Tiles).^[4] Doanh nghiệp cần đo số lượt tải bản đồ theo hành vi thật và đối chiếu với gói giá Mapvina hiện hành; không nên suy ra tỷ lệ tiết kiệm nếu chưa có số liệu sử dụng và báo giá cùng kỳ.^[4]
2. Bảo vệ dữ liệu khách hàng: Không bao giờ đưa toàn bộ thông tin nhạy cảm (doanh thu, số điện thoại cá nhân) vào thuộc tính của FeatureCollection công khai trên trình duyệt. Chỉ trả về id, tên hiển thị và hạng khách hàng; thông tin nhạy cảm chỉ được truy vấn qua API riêng biệt khi người dùng đã đăng nhập và được phân quyền hợp lệ.^[5]

7. Kết luận

Hiển thị dữ liệu không gian quy mô lớn là bài toán thường gặp khi doanh nghiệp số hóa mạng lưới phân phối và chăm sóc khách hàng tại Việt Nam. Bằng việc chuyển từ cách cắm ghim DOM truyền thống sang cơ chế WebGL Canvas kết hợp kỹ thuật gom cụm (Clustering) của Mapvina GL JS, website có thể tránh tạo hàng nghìn DOM Marker và trình bày dữ liệu theo mức zoom dễ đọc hơn. Quy mô chấp nhận được phải được xác nhận bằng benchmark trên thiết bị đại diện.^[1][3][6]

Khi mở rộng quy mô lên hàng trăm nghìn hoặc hàng triệu điểm, việc kết hợp thêm phương pháp truy vấn theo khung nhìn (Bounding Box) tại backend giúp giới hạn lượng dữ liệu gửi xuống mỗi khung nhìn; backend, phân quyền và kiểm thử tải vẫn là trách nhiệm của đội triển khai.^[7]