# KẾ HOẠCH PHÁT TRIỂN TÍNH NĂNG ĐỊNH VỊ LỘ TRÌNH (AGENT SPECIFICATION)

## 1. Phân Tích Trạng Thái Giao Diện Hiện Tại (Context Analysis)
* **Màn hình**: Tour Dashboard (Tên tour người dùng tự đặt khi tạo tour mới).
* **Tab Active**: Lộ trình (Mặc định).
* **Sub-view Active**: Bản đồ (Component bản đồ đang hiển thị ở nửa dưới màn hình).
* **Thành phần cần can thiệp**: Lớp tương tác (Interaction Layer) của thư viện Bản đồ (Mapbox / Google Maps API / Leaflet) đang render phía dưới.
  │

## 2. Đặc Tả Kỹ Thuật Đóng Gói (Functional Requirements)

### 2.1. Quản lý Trạng thái Thực thể (Data State Management)
Agent cần ánh xạ sự kiện trên UI vào hai trường dữ liệu trong Database Schema:
* **Điểm xuất phát (StartLocation)**: Ánh xạ vào Location đầu tiên của Tour với sequence: 0 hoặc cấu hình tọa độ trực tiếp vào cấu trúc metadata của Tour.
* **Điểm kết thúc (EndLocation)**: Ánh xạ vào Location cuối cùng của Tour hoặc trường đích của Tour.

### 2.2. Chi Tiết Bản Ghép Logic Sự Kiện (Event Mapping)

| Thao tác Người dùng | Trình kích hoạt (Trigger) | Hành động Hệ thống (System Action) | Phản hồi Giao diện (UI Feedback) |
| :--- | :--- | :--- | :--- |
| **Xác định Điểm xuất phát** | - Tìm kiếm trên Map Search Box<br>- Hoặc Right-Click (Desktop)<br>- Hoặc Long-Press (Mobile) | 1. Trích xuất tọa độ (lat, lng).<br>2. Gọi API khởi tạo điểm đầu.<br>3. Cập nhật nhãn "Điểm xuất phát:..." trên Top Banner. | Tạo 1 Ghim (Marker) Màu Xanh Blue tại tọa độ được chọn. |
| **Xác định Điểm kết thúc** | - Tìm kiếm trên Map Search Box<br>- Hoặc Right-Click (Desktop)<br>- Hoặc Long-Press (Mobile) | 1. Trích xuất tọa độ (lat, lng).<br>2. Gọi API khởi tạo điểm cuối.<br>3. Cập nhật nhãn "Điểm kết thúc:..." trên Top Banner. | Tạo 1 Ghim (Marker) Màu Xanh Green tại tọa độ được chọn. |

## 3. Kiến Trúc Mã Nguồn Gợi Ý Cho AI Agent (Pseudocode / Implementation Guide)
Agent cần triển khai component bản đồ với cấu trúc xử lý sự kiện (Context Menu) như sau:

### 3.1. Cấu trúc Menu Ngữ Cảnh (Custom Context Menu Component)
Khi sự kiện click chuột phải/nhấn giữ xảy ra, lấy ra tọa độ (lat, lng) của điểm chạm và hiển thị menu pop-up tại vị trí con trỏ:

```typescript
interface ContextMenuProps {
  x: number; // Tọa độ pixel trên màn hình
  y: number;
  latLng: { lat: number; lng: number };
  onSelectStart: (latLng: { lat: number; lng: number }) => void;
  onSelectEnd: (latLng: { lat: number; lng: number }) => void;
}
```

### 3.2. Thuật toán xử lý ghim (Marker Rendering Logic)
Mô tả logic bằng mã giả để Agent tiến hành sinh code xử lý:

```javascript
// Trạng thái lưu trữ tọa độ trên Frontend
const [startCoords, setStartCoords] = useState(null);
const [endCoords, setEndCoords] = useState(null);

// Hàm xử lý khi chọn "Bắt đầu từ đây"
function handleSetStartPoint(latLng) {
    // 1. Cập nhật state để render ghim Blue
    setStartCoords(latLng);
    
    // 2. Gọi API cập nhật Database thông qua UUID của Tour hiện tại
    API.updateTourStartPoint(tourId, {
        latitude: latLng.lat,
        longitude: latLng.lng,
        locationType: 'START'
    });
    
    // 3. Render Marker Blue lên Bản đồ
    map.renderMarker({
        position: latLng,
        icon: 'blue-pin.png',
        label: 'S'
    });
}

// Hàm xử lý khi chọn "Kết thúc ở đây"
function handleSetEndPoint(latLng) {
    // 1. Cập nhật state để render ghim Green
    setEndCoords(latLng);
    
    // 2. Gọi API cập nhật Database
    API.updateTourEndPoint(tourId, {
        latitude: latLng.lat,
        longitude: latLng.lng,
        locationType: 'END'
    });
    
    // 3. Render Marker Green lên Bản đồ
    map.renderMarker({
        position: latLng,
        icon: 'green-pin.png',
        label: 'E'
    });
}
```