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                   │
│    • Cache offline vào SQLite khi mất mạng                      │
│    • Tự động upload khi có mạng trở lại                         │
└───────────────────────────────┬─────────────────────────────────┘
                                │  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/fleetwork-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)          │
│    • Hooks + Controllers (tự build UI riêng)                    │
└─────────────────────────────────────────────────────────────────┘

1. App khởi động
   └─ configure(apiKey)                       ← Khởi tạo SDK với API key

2. Xin quyền vị trí
   └─ requestLocationPermissions()            ← Foreground
   └─ requestAlwaysLocationPermissions()      ← Background

3. Bắt đầu tracking
   └─ startTracking(config)
        ├─ intervalMs: 5000                   ← Chế độ timer (mỗi 5 giây)
        └─ distanceFilter: 10.0              ← Hoặc chế độ khoảng cách (mỗi 10m)

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.configure('YOUR_API_KEY');
controller.registerLifecycleObserver();

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

await controller.startTracking(
  LocationTrackingConfig(
    intervalMs: 5000,
    distanceFilter: 0,
    accuracy: LocationAccuracy.high,
    backgroundMode: true,
    userId: 'EMPLOYEE_ID',
    vehicleId: 'VEHICLE_ID',
  ),
);

import {
  FleetworkProvider,
  Dashboard,
} from "@vietmap/fleetwork-tracking-sdk-react";

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

  return (
    <FleetworkProvider apiKey="YOUR_API_KEY">
      <Dashboard date={today.getTime()} />
    </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