Tổng quan hệ thống

┌─────────────────────────────────────────────────────────────────┐
│  Thiết bị di động  (Flutter App)                                │
│                                                                 │
│  VietmapTrackingPlugin                                          │
│    • Thu thập GPS theo timer HOẶC khoảng cách (loại trừ nhau)   │
│    • Cache offline vào SQLite khi mất mạng                      │
│    • Tự động upload khi có mạng trở lại                         │
│    • Phát hiện GPS giả + Speed fallback (thiết bị thiếu speed)  │
│    • Smart Battery (opt-in): đổi tần suất theo pin & chuyển động│
└───────────────────────────────┬─────────────────────────────────┘
                                │  POST /api/v1/gps-tracking
                                │  X-API-Key: <key>
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  GPS Tracking API  (live.fleetwork.vn)                          │
│                                                                 │
│  • Nhận dữ liệu GPS (single / batch)                            │
│  • Lưu vào time-series database                                 │
│  • Cache vị trí mới nhất (real-time query)                      │
└───────────────────────────────┬─────────────────────────────────┘
                                │  (internal)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  AnalyticsApi (internal :7102)                                  │
│                                                                 │
│  • KPI: users active, km hôm nay, nhiên liệu, chi phí           │
│  • Bảng trạng thái users (đang di chuyển / dừng / mất tín)     │
│  • Heatmap hoạt động theo giờ                                   │
│  • Báo cáo hành trình, nhiên liệu, thời gian hoạt động          │
└───────────────────────────────┬─────────────────────────────────┘
                                │  YARP proxy
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  Fleetwork.Web gateway  (live.fleetwork.vn)                     │
│                                                                 │
│  • Xác thực X-API-Key, inject X-Account-Id + X-Internal-Token  │
│  • Proxy đến AnalyticsApi :7102 (YARP)                          │
└───────────────────────────────┬─────────────────────────────────┘
                                │  GET /api/v1/dashboard/...
                                │  GET /api/v1/reports/...
                                │  X-API-Key: <key>
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│  Web Application  (React SDK)                                   │
│                                                                 │
│  @vietmap/tracking-sdk-react                                    │
│    • Dashboard component (full layout hoặc từng widget)         │
│    • LiveMap (bản đồ thời gian thực, marker nhân viên, lịch sử) │
│    • Report (hành trình / nhiên liệu / giờ hoạt động)           │
│    • Hooks + Controllers (tự build UI riêng)                    │
└─────────────────────────────────────────────────────────────────┘

1. App khởi động
   └─ initializeTracking(apiKey)              ← Xác thực API key phía server
   └─ registerLifecycleObserver()             ← Tự chuyển background/foreground

2. Xin quyền
   └─ requestLocationPermissions()            ← Vị trí foreground
   └─ requestAlwaysLocationPermissions()      ← Vị trí background
   └─ Permission.notification.request()       ← Notification (Android 13+ / iOS)

3. Bắt đầu tracking  (userId là BẮT BUỘC)
   └─ startTracking(config)
        ├─ intervalMs: 30000                  ← Chế độ timer (mỗi 30 giây)
        └─ distanceFilter: 70.0               ← HOẶC chế độ khoảng cách (sàn 25m)
                                                 Chỉ dùng 1 trong 2, cái kia = null

4. SDK tự động
   ├─ Thu thập GPS point
   ├─ [Có mạng]  → POST /api/v1/gps-tracking  (realtime)
   └─ [Mất mạng] → Lưu SQLite → Upload khi có mạng lại

5. Dừng tracking
   └─ stopTracking()

1. Khởi tạo React SDK
   └─ <FleetworkProvider apiKey="...">

2. Render dashboard
   └─ <Dashboard date={1713225600000} />
        ├─ GET /api/v1/dashboard/gps-manager/summary
        ├─ GET /api/v1/dashboard/gps-manager/users
        ├─ GET /api/v1/dashboard/gps-manager/activity-heatmap?from=...&to=...
        ├─ GET /api/v1/dashboard/gps-manager/fuel-tracking?from=...&to=...
        └─ GET /api/v1/dashboard/gps-manager/monthly-costs?from=...&to=...

3. Bản đồ thời gian thực
   └─ <LiveMap pollInterval={10000} />
        └─ Refresh vị trí nhân viên mỗi 10 giây

4. Lịch sử hành trình
   └─ GET /api/v1/gps-tracking/history?VehicleId=...

GET /api/v1/reports/trip/summary      ← Hành trình tổng hợp
GET /api/v1/reports/trip/detail       ← Hành trình chi tiết
GET /api/v1/reports/fuel/summary      ← Nhiên liệu tổng hợp
GET /api/v1/reports/fuel/detail       ← Nhiên liệu chi tiết
GET /api/v1/reports/activity-time     ← Thời gian hoạt động

# Thêm ?format=excel hoặc ?format=csv để tải file

Nhận GPS point gần nhất
│
├─ (now - lastSeenAt) > 15 phút  → statusCode = 0  (🔴 Mất tín hiệu)
├─ lastLocation.speed = 0         → statusCode = 2  (🟡 Đang dừng)
└─ lastLocation.speed > 0         → statusCode = 1  (🟢 Đang di chuyển)

X-API-Key: <your_api_key>

{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid X-API-Key header",
  "code": 401
}

final controller = VietmapTrackingController.instance;
await controller.initializeTracking('YOUR_API_KEY');
controller.registerLifecycleObserver();

await controller.requestLocationPermissions();
await controller.requestAlwaysLocationPermissions();

await controller.startTracking(
  LocationTrackingConfig(
    userId: 'EMPLOYEE_ID',   // bắt buộc
    vehicleId: 'VEHICLE_ID', // tuỳ chọn
    intervalMs: 30000,       // 30 giây / lần
    accuracy: LocationAccuracy.high,
    backgroundMode: true,
  ),
);

// Hoặc dùng preset dựng sẵn:
await controller.startTracking(
  TrackingPresets.general().copyWith(userId: 'EMPLOYEE_ID'),
);

import { FleetworkProvider, Dashboard, LiveMap } from "@vietmap/tracking-sdk-react";
import "@vietmap/tracking-sdk-react/styles.css";

function App() {
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  return (
    <FleetworkProvider apiKey="YOUR_API_KEY">
      <Dashboard date={today.getTime()} />
      <LiveMap apiKeyTilemap="YOUR_VIETMAP_TILE_KEY" height="600px" />
    </FleetworkProvider>
  );
}

GET https://live.fleetwork.vn/api/v1/gps-tracking/latest/users/{userId}
X-API-Key: YOUR_API_KEY

GET https://live.fleetwork.vn/api/v1/dashboard/gps-manager/summary
X-API-Key: YOUR_API_KEY