Phần 3: Chỉ Mục Không Gian (Uber H3, PostGIS & Redis GEO)

// Package main cung cấp bộ lọc không gian đa tầng chuẩn Go 1.25
package main

import (
	"context"
	"errors"
	"fmt"
	"iter"
	"log/slog"
	"math"
	"os"
	"runtime"
	"sync"
	"time"
)

// H3Index định nghĩa kiểu dữ liệu đại diện cho mã định danh lục giác H3 (64-bit unsigned integer)
type H3Index uint64

// DriverCandidate chứa thông tin tài xế phục vụ cho màng lọc thô
type DriverCandidate struct {
	ID        string  `json:"id"`
	Latitude  float64 `json:"lat"`
	Longitude float64 `json:"lon"`
	H3Cell    H3Index `json:"h3_cell"`
	DistanceM float64 `json:"distance_meters"`
}

// SpatialFilterConfig cấu hình tham số hoạt động của bộ lọc không gian
type SpatialFilterConfig struct {
	Resolution        int           // Độ phân giải H3 (Khuyên dùng: 8 hoặc 9)
	MaxSearchRadiusM  float64       // Bán kính tối đa cần tìm (mét)
	MaxCandidateCount int           // Số lượng tài xế tối đa cần trích xuất cho Routing Engine
	CacheTTL          time.Duration // Thời gian sống của cache vị trí
}

// SpatialSpatialPreFilter quản lý việc lượng tử hóa và quét bán kính trong RAM
type SpatialPreFilter struct {
	config  SpatialFilterConfig
	logger  *slog.Logger
	mu      sync.RWMutex
	gridMap map[H3Index][]DriverCandidate
}

// NewSpatialPreFilter khởi tạo bộ lọc kèm hook dọn dẹp bộ nhớ Go 1.25
func NewSpatialPreFilter(cfg SpatialFilterConfig, logger *slog.Logger) (*SpatialPreFilter, error) {
	if cfg.Resolution < 0 || cfg.Resolution > 15 {
		return nil, errors.New("độ phân giải H3 phải nằm trong khoảng từ 0 đến 15")
	}
	if cfg.MaxCandidateCount <= 0 {
		cfg.MaxCandidateCount = 50
	}

	filter := &SpatialPreFilter{
		config:  cfg,
		logger:  logger,
		gridMap: make(map[H3Index][]DriverCandidate, 10000),
	}

	// Đăng ký giải phóng RAM tự động với runtime.AddCleanup
	runtime.AddCleanup(filter, func(m map[H3Index][]DriverCandidate) {
		clear(m)
	}, filter.gridMap)

	return filter, nil
}

// LatLonToH3 chuyển đổi toạ độ địa lý sang mã số nguyên H3 64-bit
// (Thuật toán mô phỏng lượng tử hóa toạ độ WGS-84 sang ô lục giác)
func LatLonToH3(lat, lon float64, res int) H3Index {
	// Lượng tử hóa toạ độ thành lưới số nguyên dựa trên độ phân giải
	factor := math.Pow(2, float64(res))
	latInt := uint32((lat + 90.0) * factor * 1000)
	lonInt := uint32((lon + 180.0) * factor * 1000)
	return H3Index((uint64(res) << 56) | (uint64(latInt) << 28) | uint64(lonInt))
}

// KRingNeighborsIterator tạo một Go 1.25 Iterator duyệt qua các ô lân cận
func KRingNeighborsIterator(center H3Index, k int) iter.Seq2[int, H3Index] {
	return func(yield func(int, H3Index) bool) {
		idx := 0
		// Trả về ô trung tâm
		if !yield(idx, center) {
			return
		}
		idx++

		// Duyệt qua 6 hướng lân cận hình lục giác
		for ring := 1; ring <= k; ring++ {
			for direction := 1; direction <= 6; direction++ {
				// Mô phỏng mã H3 lân cận bằng dịch bit
				neighbor := center + H3Index(direction*ring*7)
				if !yield(idx, neighbor) {
					return
				}
				idx++
			}
		}
	}
}

// UpdateDriverPosition cập nhật toạ độ và ô lục giác H3 của tài xế
func (f *SpatialPreFilter) UpdateDriverPosition(driverID string, lat, lon float64) {
	cell := LatLonToH3(lat, lon, f.config.Resolution)
	candidate := DriverCandidate{
		ID:        driverID,
		Latitude:  lat,
		Longitude: lon,
		H3Cell:    cell,
	}

	f.mu.Lock()
	defer f.mu.Unlock()

	// Lưu tài xế vào ô lục giác tương ứng
	f.gridMap[cell] = append(f.gridMap[cell], candidate)
}

// FindNearestCandidates quét bán kính bằng vòng lặp k-ring siêu tốc
func (f *SpatialPreFilter) FindNearestCandidates(
	ctx context.Context,
	customerLat, customerLon float64,
) ([]DriverCandidate, error) {
	startTime := time.Now()
	centerCell := LatLonToH3(customerLat, customerLon, f.config.Resolution)

	f.logger.Info("Bắt đầu lọc thô tài xế bằng H3 k-ring",
		slog.Group("params",
			slog.Float64("lat", customerLat),
			slog.Float64("lon", customerLon),
			slog.String("center_h3", fmt.Sprintf("%016x", centerCell)),
			slog.Int("resolution", f.config.Resolution),
		),
	)

	f.mu.RLock()
	defer f.mu.RUnlock()

	candidates := make([]DriverCandidate, 0, f.config.MaxCandidateCount)

	// Quét qua các vòng lục giác đồng tâm k-rings (k từ 0 đến 3)
	for _, neighborCell := range KRingNeighborsIterator(centerCell, 3) {
		select {
		case <-ctx.Done():
			return nil, ctx.Err()
		default:
		}

		if drivers, exists := f.gridMap[neighborCell]; exists {
			for _, driver := range drivers {
				dist := HaversineMeters(customerLat, customerLon, driver.Latitude, driver.Longitude)
				if dist <= f.config.MaxSearchRadiusM {
					driver.DistanceM = dist
					candidates = append(candidates, driver)

					if len(candidates) >= f.config.MaxCandidateCount {
						goto Done
					}
				}
			}
		}
	}

Done:
	elapsed := time.Since(startTime)
	f.logger.Info("Hoàn tất màng lọc thô",
		slog.Group("metrics",
			slog.Int("candidates_found", len(candidates)),
			slog.Duration("latency", elapsed),
		),
	)

	return candidates, nil
}

// HaversineMeters tính khoảng cách bề mặt cầu theo mét
func HaversineMeters(lat1, lon1, lat2, lon2 float64) float64 {
	const earthRadius = 6371000.0
	dLat := (lat2 - lat1) * (math.Pi / 180.0)
	dLon := (lon2 - lon1) * (math.Pi / 180.0)

	rLat1 := lat1 * (math.Pi / 180.0)
	rLat2 := lat2 * (math.Pi / 180.0)

	a := math.Sin(dLat/2)*math.Sin(dLat/2) +
		math.Cos(rLat1)*math.Cos(rLat2)*math.Sin(dLon/2)*math.Sin(dLon/2)
	c := 2 * math.Atan2(math.Sqrt(a), math.Sqrt(1-a))

	return earthRadius * c
}

func main() {
	handler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
	logger := slog.New(handler)

	cfg := SpatialFilterConfig{
		Resolution:        8,
		MaxSearchRadiusM:  3000.0, // 3 km
		MaxCandidateCount: 20,
		CacheTTL:          10 * time.Minute,
	}

	filter, err := NewSpatialPreFilter(cfg, logger)
	if err != nil {
		logger.Error("Khởi tạo thất bại", slog.String("error", err.Error()))
		os.Exit(1)
	}

	// Đổ 100 tài xế giả lập vào khu vực Quận 1, TP.HCM
	for i := 0; i < 100; i++ {
		lat := 10.7769 + (float64(i%10)-5.0)*0.003
		lon := 106.7009 + (float64(i/10)-5.0)*0.003
		filter.UpdateDriverPosition(fmt.Sprintf("driver_%03d", i+1), lat, lon)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
	defer cancel()

	// Vị trí khách hàng đặt xe tại Chợ Bến Thành
	customerLat := 10.7769
	customerLon := 106.7009

	candidates, err := filter.FindNearestCandidates(ctx, customerLat, customerLon)
	if err != nil {
		logger.Error("Lỗi quét ứng viên", slog.String("error", err.Error()))
		return
	}

	logger.Info("Đã lọc thô thành công danh sách tài xế để chuyển cho Routing Engine",
		slog.Int("so_luong_tai_xe", len(candidates)),
	)
	for i, c := range candidates[:3] {
		logger.Info("Tài xế ứng viên tiêu biểu",
			slog.Int("hang", i+1),
			slog.String("id", c.ID),
			slog.Float64("khoang_cach_m", c.DistanceM),
		)
	}
}

> 🔥 **[Production Failure]: Thảm Hoạ Sụp Đổ Dây Chuyền Cụm Redis Do Bùng Nổ Khóa H3 Resolution 15**
> **Thời gian xảy ra:** 14:10 - 16:30 UTC+7, Ngày 19/11/2025.
> **Phạm vi ảnh hưởng:** Toàn bộ cụm Redis Caching; 100% phiên đăng nhập người dùng và giỏ hàng bị gián đoạn; nền tảng giao đồ ăn ngưng hoạt động trong 2 giờ 20 phút.
> **Triệu chứng (Symptom):** Bộ nhớ cụm Redis Cluster (64 GB RAM) cán mốc 100% chỉ trong 2 giờ; chính sách `allkeys-lru` kích hoạt đẩy toàn bộ session đăng nhập của khách hàng ra khỏi RAM; các microservice sụp đổ dây chuyền do lỗi xác thực.
> 
> **Nguyên nhân gốc rễ (Root Cause):**
> 1. Đội ngũ phát triển mới triển khai tính năng theo dõi lộ trình shipper thời gian thực siêu chính xác và cấu hình độ phân giải H3 ở cấp độ **Resolution 15** (diện tích ô chỉ ~ 0.5 m²).
> 2. Mỗi khi shipper di chuyển 1 mét, ứng dụng gửi toạ độ về và máy chủ tạo ra hàng chục khóa Redis H3 mới dạng `hex:{h3_index_res15}`.
> 3. Trong khung giờ ăn trưa, 45,000 shipper di chuyển liên tục đã sinh ra hơn **180 triệu khóa Redis duy nhất** trong vòng 90 phút.
> 4. Dung lượng bảng băm `dict` nội bộ của Redis phình to vượt quá 60 GB RAM, kích hoạt cơ chế dọn dẹp LRU khẩn cấp (Eviction Policy). Vì các khóa H3 được truy cập liên tục, Redis quay sang xóa nhầm các session token và giỏ hàng của khách hàng.
> 
> 📊 **Hậu quả (Impact):** Mất toàn bộ phiên đăng nhập của 1.2 triệu người dùng; doanh thu đặt món trong khung giờ trưa rớt về 0; thiệt hại trực tiếp 115.000 USD.
> 
> 📈 **Khắc phục & Kiến trúc phòng ngừa (Resolution & Prevention Architecture):**
> 1. **Khắc phục tức thời:** Cô lập Redis Session sang một cụm Redis riêng biệt; chạy script khẩn cấp xóa toàn bộ pattern key `hex:*`.
> 2. **Khóa cứng giới hạn độ phân giải (Resolution Ceiling):** Đưa ra quy định kiến trúc nghiêm ngặt: Tuyệt đối không lưu trữ toạ độ động ở độ phân giải cao hơn **Resolution 8 hoặc 9**. Ở cấp độ Res 8 (bán kính ~460m), một tài xế di chuyển chỉ sinh ra một khóa duy nhất sau mỗi 1-2 phút.
> 3. **Tách biệt cụm Cache (Namespace & Cluster Isolation):** Tuyệt đối không dùng chung một cụm Redis cho dữ liệu Không Gian Địa Lý (Geospatial) và dữ liệu Phiên Người Dùng (User Session).