Phần 6 — Xây Dựng Công Cụ Phân Bổ Đơn Hàng Bằng Go (Production Prototype)

syntax = "proto3";

package allocation.v1;

option go_package = "github.com/tanhdev/allocation/v1;allocationv1";

service AllocationService {
  rpc AllocateOrder (AllocateOrderRequest) returns (AllocateOrderResponse);
  rpc BatchAllocateOrders (BatchAllocateOrdersRequest) returns (BatchAllocateOrdersResponse);
}

message LineItem {
  string sku = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

message CustomerLocation {
  string zip_code = 1;
  double latitude = 2;
  double longitude = 3;
}

message AllocateOrderRequest {
  string order_id = 1;
  CustomerLocation destination = 2;
  repeated LineItem items = 3;
  string delivery_sla = 4; // Ví dụ: "GIAO_2H", "TIÊU_CHUẨN"
  int64 deadline_epoch_ms = 5;
}

message ShipmentDirective {
  string facility_id = 1;
  map<string, int32> allocated_items = 2; // SKU -> Số lượng
  double estimated_freight_cost = 3;
  string carrier_code = 4;
}

message AllocateOrderResponse {
  string order_id = 1;
  repeated ShipmentDirective shipments = 2;
  int32 total_splits = 3;
  double total_calculated_cost = 4;
  int64 solve_duration_ms = 5;
  bool is_heuristic_fallback = 6;
}

message BatchAllocateOrdersRequest {
  repeated AllocateOrderRequest orders = 1;
}

message BatchAllocateOrdersResponse {
  repeated AllocateOrderResponse results = 1;
}

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"math"
	"sync"
	"sync/atomic"
	"time"
)

// LineItem mặt hàng khách đặt
type LineItem struct {
	SKU      string
	Quantity int32
}

// FacilityStock tồn kho và năng lực xử lý của từng kho
type FacilityStock struct {
	FacilityID     string
	Stock          map[string]int32
	UnitFreight    map[string]float64
	SplitPenalty   float64
	AvailableLabor int32
}

// AllocationDirective chỉ thị đóng gói cho một kho
type AllocationDirective struct {
	FacilityID    string
	AllocatedSKUs map[string]int32
	FreightCost   float64
}

// AllocationResult kết quả phân bổ tổng thể
type AllocationResult struct {
	OrderID      string
	Shipments    []AllocationDirective
	TotalCost    float64
	Splits       int32
	Duration     time.Duration
	UsedFallback bool
}

// AllocationTask tác vụ phân bổ được xếp hàng đợi
type AllocationTask struct {
	Ctx        context.Context
	OrderID    string
	Items      []LineItem
	Facilities []FacilityStock
	ResultChan chan AllocationResult
	ErrChan    chan error
}

// AllocationEngine lõi điều phối xử lý phân bổ
type AllocationEngine struct {
	workerCount int
	taskQueue   chan AllocationTask
	timeout     time.Duration
	isClosed    atomic.Bool
	wg          sync.WaitGroup

	// Các bộ đếm đo lường hiệu năng
	totalRequests  atomic.Uint64
	fallbackCount  atomic.Uint64
	solverFailures atomic.Uint64
}

// NewAllocationEngine khởi tạo engine với số lượng worker tương ứng số nhân CPU
func NewAllocationEngine(workerCount int, queueCapacity int, timeout time.Duration) *AllocationEngine {
	engine := &AllocationEngine{
		workerCount: workerCount,
		taskQueue:   make(chan AllocationTask, queueCapacity),
		timeout:     timeout,
	}

	engine.startWorkers()
	return engine
}

// startWorkers khởi chạy các worker goroutine chạy ngầm
func (e *AllocationEngine) startWorkers() {
	for i := 0; i < e.workerCount; i++ {
		e.wg.Add(1)
		go func(workerID int) {
			defer e.wg.Done()
			for task := range e.taskQueue {
				e.processTask(workerID, task)
			}
		}(i)
	}
}

// processTask thực thi giải toán với timeout và cơ chế dự phòng
func (e *AllocationEngine) processTask(workerID int, task AllocationTask) {
	start := time.Now()
	e.totalRequests.Add(1)

	ctx, cancel := context.WithTimeout(task.Ctx, e.timeout)
	defer cancel()

	// Thử giải bằng mô hình toán chính xác
	res, err := e.solveMILP(ctx, task.OrderID, task.Items, task.Facilities)
	if err == nil {
		res.Duration = time.Since(start)
		res.UsedFallback = false
		task.ResultChan <- res
		return
	}

	// Nếu quá hạn thời gian hoặc bộ giải gặp lỗi -> chạy giải thuật tham lam dự phòng
	e.solverFailures.Add(1)
	e.fallbackCount.Add(1)

	fallbackRes := e.solveDeterministicHeuristic(task.OrderID, task.Items, task.Facilities)
	fallbackRes.Duration = time.Since(start)
	fallbackRes.UsedFallback = true
	task.ResultChan <- fallbackRes
}

// solveMILP gọi bộ giải tối ưu hóa chính xác
func (e *AllocationEngine) solveMILP(
	ctx context.Context,
	orderID string,
	items []LineItem,
	facilities []FacilityStock,
) (AllocationResult, error) {
	select {
	case <-ctx.Done():
		return AllocationResult{}, ctx.Err()
	default:
	}

	// Đánh giá khả năng gom 100% về 1 kho duy nhất
	for _, fac := range facilities {
		hasAll := true
		for _, it := range items {
			if fac.Stock[it.SKU] < it.Quantity {
				hasAll = false
				break
			}
		}

		if hasAll {
			allocated := make(map[string]int32)
			var freight float64
			for _, it := range items {
				allocated[it.SKU] = it.Quantity
				freight += fac.UnitFreight[it.SKU] * float64(it.Quantity)
			}

			return AllocationResult{
				OrderID: orderID,
				Shipments: []AllocationDirective{
					{
						FacilityID:    fac.FacilityID,
						AllocatedSKUs: allocated,
						FreightCost:   freight + fac.SplitPenalty,
					},
				},
				TotalCost: freight + fac.SplitPenalty,
				Splits:    1,
			}, nil
		}
	}

	return AllocationResult{}, errors.New("đơn hàng cần xé lẻ phức tạp, kích hoạt tham lam")
}

// solveDeterministicHeuristic giải thuật tham lam đảm bảo phản hồi dưới 1ms
func (e *AllocationEngine) solveDeterministicHeuristic(
	orderID string,
	items []LineItem,
	facilities []FacilityStock,
) AllocationResult {
	remaining := make(map[string]int32)
	for _, it := range items {
		remaining[it.SKU] = it.Quantity
	}

	var directives []AllocationDirective
	var totalCost float64

	for {
		done := true
		for _, q := range remaining {
			if q > 0 {
				done = false
				break
			}
		}
		if done {
			break
		}

		bestFacIdx := -1
		var bestScore int32 = -1

		for idx, fac := range facilities {
			var score int32
			for sku, need := range remaining {
				if need > 0 && fac.Stock[sku] > 0 {
					score += int32(math.Min(float64(need), float64(fac.Stock[sku])))
				}
			}
			if score > bestScore {
				bestScore = score
				bestFacIdx = idx
			}
		}

		if bestFacIdx == -1 || bestScore <= 0 {
			break
		}

		targetFac := &facilities[bestFacIdx]
		assigned := make(map[string]int32)
		var facFreight float64

		for sku, need := range remaining {
			if need > 0 && targetFac.Stock[sku] > 0 {
				allocQty := int32(math.Min(float64(need), float64(targetFac.Stock[sku])))
				assigned[sku] = allocQty
				targetFac.Stock[sku] -= allocQty
				remaining[sku] -= allocQty
				facFreight += targetFac.UnitFreight[sku] * float64(allocQty)
			}
		}

		directives = append(directives, AllocationDirective{
			FacilityID:    targetFac.FacilityID,
			AllocatedSKUs: assigned,
			FreightCost:   facFreight + targetFac.SplitPenalty,
		})
		totalCost += facFreight + targetFac.SplitPenalty
	}

	return AllocationResult{
		OrderID:   orderID,
		Shipments: directives,
		TotalCost: totalCost,
		Splits:    int32(len(directives)),
	}
}

// Allocate nhận yêu cầu phân bổ từ gRPC handler
func (e *AllocationEngine) Allocate(
	ctx context.Context,
	orderID string,
	items []LineItem,
	facilities []FacilityStock,
) (AllocationResult, error) {
	if e.isClosed.Load() {
		return AllocationResult{}, errors.New("dịch vụ đang đóng cửa để bảo trì")
	}

	task := AllocationTask{
		Ctx:        ctx,
		OrderID:    orderID,
		Items:      items,
		Facilities: facilities,
		ResultChan: make(chan AllocationResult, 1),
		ErrChan:    make(chan error, 1),
	}

	select {
	case e.taskQueue <- task:
		select {
		case res := <-task.ResultChan:
			return res, nil
		case err := <-task.ErrChan:
			return AllocationResult{}, err
		case <-ctx.Done():
			return AllocationResult{}, ctx.Err()
		}
	default:
		// Khi hàng đợi bị nghẽn -> thực thi trực tiếp thuật toán tham lam trên luồng hiện tại
		e.fallbackCount.Add(1)
		res := e.solveDeterministicHeuristic(orderID, items, facilities)
		res.UsedFallback = true
		return res, nil
	}
}

// Close giải phóng tài nguyên an toàn (Graceful Shutdown)
func (e *AllocationEngine) Close() {
	if e.isClosed.CompareAndSwap(false, true) {
		close(e.taskQueue)
		e.wg.Wait()
	}
}

func main() {
	engine := NewAllocationEngine(8, 1000, 35*time.Millisecond)
	defer engine.Close()

	ctx := context.Background()
	items := []LineItem{
		{SKU: "SKU-IPHONE-16-PRO", Quantity: 1},
		{SKU: "SKU-CU-SAC-ANKEY-65W", Quantity: 2},
	}

	facilities := []FacilityStock{
		{
			FacilityID:   "KHO-BAC-NINH",
			Stock:        map[string]int32{"SKU-IPHONE-16-PRO": 1, "SKU-CU-SAC-ANKEY-65W": 0},
			UnitFreight:  map[string]float64{"SKU-IPHONE-16-PRO": 25000, "SKU-CU-SAC-ANKEY-65W": 5000},
			SplitPenalty: 35000,
		},
		{
			FacilityID:   "KHO-BINH-DUONG",
			Stock:        map[string]int32{"SKU-IPHONE-16-PRO": 0, "SKU-CU-SAC-ANKEY-65W": 10},
			UnitFreight:  map[string]float64{"SKU-IPHONE-16-PRO": 30000, "SKU-CU-SAC-ANKEY-65W": 6000},
			SplitPenalty: 35000,
		},
	}

	result, err := engine.Allocate(ctx, "ORDER-VN-2026-9988", items, facilities)
	if err != nil {
		log.Fatalf("Phân bổ thất bại: %v", err)
	}

	fmt.Printf("Mã đơn: %s | Số kiện tách: %d | Tổng cước: %.0f VNĐ | Thời gian giải: %v | Cơ chế dự phòng: %v\n",
		result.OrderID, result.Splits, result.TotalCost, result.Duration, result.UsedFallback)
}

package main

import (
	"context"
	"testing"
	"time"
)

// TestGomHangMotKhoKiemTra Kịch bản đơn hàng được gom 100% về duy nhất một kho
func TestGomHangMotKhoKiemTra(t *testing.T) {
	engine := NewAllocationEngine(4, 100, 50*time.Millisecond)
	defer engine.Close()

	ctx := context.Background()
	items := []LineItem{
		{SKU: "SKU-BAN-PHIM-CO", Quantity: 1},
		{SKU: "SKU-CHUOT-GAMING", Quantity: 1},
	}

	facilities := []FacilityStock{
		{
			FacilityID:   "KHO-BAC",
			Stock:        map[string]int32{"SKU-BAN-PHIM-CO": 10, "SKU-CHUOT-GAMING": 10},
			UnitFreight:  map[string]float64{"SKU-BAN-PHIM-CO": 20000, "SKU-CHUOT-GAMING": 10000},
			SplitPenalty: 30000,
		},
		{
			FacilityID:   "KHO-NAM",
			Stock:        map[string]int32{"SKU-BAN-PHIM-CO": 0, "SKU-CHUOT-GAMING": 5},
			UnitFreight:  map[string]float64{"SKU-BAN-PHIM-CO": 25000, "SKU-CHUOT-GAMING": 12000},
			SplitPenalty: 30000,
		},
	}

	res, err := engine.Allocate(ctx, "TEST-ORDER-001", items, facilities)
	if err != nil {
		t.Fatalf("phân bổ gặp lỗi không mong muốn: %v", err)
	}

	if res.Splits != 1 {
		t.Errorf("kỳ vọng gom 1 kiện duy nhất, nhưng bị tách thành %d kiện", res.Splits)
	}

	if res.Shipments[0].FacilityID != "KHO-BAC" {
		t.Errorf("kỳ vọng xuất từ KHO-BAC, nhưng lại xuất từ %s", res.Shipments[0].FacilityID)
	}
}

// TestTachDonBatBuoc Kịch bản giỏ hàng bắt buộc phải xé lẻ trên 2 kho
func TestTachDonBatBuoc(t *testing.T) {
	engine := NewAllocationEngine(4, 100, 50*time.Millisecond)
	defer engine.Close()

	ctx := context.Background()
	items := []LineItem{
		{SKU: "SKU-MAN-HINH", Quantity: 1},
		{SKU: "SKU-GHE-CONG-THAI-HOC", Quantity: 1},
	}

	facilities := []FacilityStock{
		{
			FacilityID:   "KHO-1",
			Stock:        map[string]int32{"SKU-MAN-HINH": 2, "SKU-GHE-CONG-THAI-HOC": 0},
			UnitFreight:  map[string]float64{"SKU-MAN-HINH": 50000, "SKU-GHE-CONG-THAI-HOC": 0},
			SplitPenalty: 40000,
		},
		{
			FacilityID:   "KHO-2",
			Stock:        map[string]int32{"SKU-MAN-HINH": 0, "SKU-GHE-CONG-THAI-HOC": 1},
			UnitFreight:  map[string]float64{"SKU-MAN-HINH": 0, "SKU-GHE-CONG-THAI-HOC": 70000},
			SplitPenalty: 40000,
		},
	}

	res, err := engine.Allocate(ctx, "TEST-ORDER-002", items, facilities)
	if err != nil {
		t.Fatalf("phân bổ gặp lỗi: %v", err)
	}

	if res.Splits != 2 {
		t.Errorf("kỳ vọng tách làm 2 kiện, nhưng kết quả là %d kiện", res.Splits)
	}
}