别再盲找了！GhostTrack 开源项目让设备追踪变得如此简单

┌─────────────────────────────────────────────────────────────┐
│                      GhostTrack 架构                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐ │
│   │ 设备层   │───▶│ 协议层   │───▶│ 数据层   │───▶│ 展示层   │ │
│   │         │    │         │    │         │    │         │ │
│   │ • GPS   │    │ • MQTT  │    │ • 存储   │    │ • Dashboard │
│   │ • BLE   │    │ • HTTP  │    │ • 计算   │    │ • API   │ │
│   │ • WiFi  │    │ • CoAP  │    │ • 分析   │    │ • 告警   │ │
│   └─────────┘    └─────────┘    └─────────┘    └─────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

最低配置：
- CPU: 2 cores
- RAM: 4GB
- 磁盘: 20GB 可用空间
- 操作系统: Linux/macOS/Windows (WSL2)

推荐配置：
- CPU: 4+ cores
- RAM: 8GB+
- 磁盘: 50GB+ SSD
- 操作系统: Ubuntu 20.04+ / macOS 12+

# 检查 Python 版本（需要 Python 3.8+）
python3 --version
# 输出示例：Python 3.10.12

# 检查 Git 是否可用
git --version
# 输出示例：git version 2.34.1

# 检查 Docker（推荐使用 Docker 部署）
docker --version
# 输出示例：Docker version 24.0.7

# 克隆 GhostTrack 仓库
git clone https://github.com/HunxByts/GhostTrack.git

# 进入项目目录
cd GhostTrack

# 查看项目结构
ls -la

GhostTrack/
├── docs/                 # 项目文档
├── examples/             # 示例代码
├── ghosttrack/           # 核心源码
│   ├── __init__.py
│   ├── api/              # API 接口
│   ├── core/             # 核心模块
│   ├── models/           # 数据模型
│   └── utils/            # 工具函数
├── tests/                # 测试用例
├── docker-compose.yml    # Docker 编排文件
├── requirements.txt      # Python 依赖
└── README.md             # 项目说明

# 方式一：使用默认配置启动
docker-compose up -d

# 方式二：查看启动日志确认服务状态
docker-compose logs -f

[INFO] GhostTrack API Server started on port 8000
[INFO] WebSocket endpoint available at ws://localhost:8000/ws
[INFO] Dashboard available at http://localhost:8000/dashboard
[INFO] Database connection established
[INFO] All services initialized successfully

# 创建虚拟环境（推荐）
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

# 安装开发依赖（可选）
pip install -r requirements-dev.txt

# 运行开发服务器
python -m ghosttrack.server

# 创建一个测试脚本 verify_installation.py

import requests
import json

# 测试 API 服务
base_url = "http://localhost:8000"

# 检查服务健康状态
response = requests.get(f"{base_url}/health")
health_data = response.json()

print("=" * 50)
print("GhostTrack 安装验证")
print("=" * 50)
print(f"服务状态: {health_data.get('status', 'unknown')}")
print(f"版本号: {health_data.get('version', 'unknown')}")
print(f"运行时间: {health_data.get('uptime', 'unknown')}")
print("=" * 50)

# 测试设备追踪核心功能
test_device = {
    "device_id": "TEST001",
    "latitude": 39.9042,
    "longitude": 116.4074,
    "timestamp": "2024-01-15T10:30:00Z"
}

response = requests.post(
    f"{base_url}/api/v1/track",
    json=test_device,
    headers={"Content-Type": "application/json"}
)

print(f"追踪测试: {response.status_code}")
print(f"响应数据: {json.dumps(response.json(), indent=2, ensure_ascii=False)}")

python verify_installation.py

==================================================
GhostTrack 安装验证
==================================================
服务状态: healthy
版本号: 1.2.0
运行时间: 42 seconds
==================================================
追踪测试: 201
响应数据: {
  "success": true,
  "device_id": "TEST001",
  "message": "位置数据已成功接收"
}

import requests
import time

class GhostTrackClient:
    """GhostTrack API 客户端封装"""

    def __init__(self, base_url, api_key=None):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.session = requests.Session()
        if api_key:
            self.session.headers.update({"X-API-Key": api_key})

    def report_location(self, device_id, latitude, longitude, **kwargs):
        """
        上报设备位置信息

        Args:
            device_id: 设备唯一标识
            latitude: 纬度
            longitude: 经度
            **kwargs: 附加参数（altitude, speed, heading, accuracy 等）

        Returns:
            dict: 包含处理结果的响应
        """
        payload = {
            "device_id": device_id,
            "latitude": latitude,
            "longitude": longitude,
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
            **kwargs
        }

        response = self.session.post(
            f"{self.base_url}/api/v1/track",
            json=payload
        )

        return response.json()

# 使用示例
client = GhostTrackClient("http://localhost:8000")

# 追踪一辆快递车的位置
result = client.report_location(
    device_id="TRUCK-2024-001",
    latitude=31.2304,
    longitude=121.4737,
    altitude=10.5,
    speed=45.2,
    heading=90.0,
    accuracy=5.0
)

print(f"上报结果: {result}")

import paho.mqtt.client as mqtt
import json
import time

class GhostTrackMQTT:
    """基于 MQTT 协议的 GhostTrack 客户端"""

    def __init__(self, broker_host, broker_port=1883, 
                 username=None, password=None):
        self.client = mqtt.Client()
        self.broker_host = broker_host
        self.broker_port = broker_port

        # 设置认证信息
        if username and password:
            self.client.username_pw_set(username, password)

        # 设置回调函数
        self.client.on_connect = self._on_connect
        self.client.on_disconnect = self._on_disconnect
        self.client.on_message = self._on_message

    def _on_connect(self, client, userdata, flags, rc):
        """连接成功回调"""
        if rc == 0:
            print(f"成功连接到 MQTT Broker: {self.broker_host}:{self.broker_port}")
            # 订阅设备主题（支持通配符）
            client.subscribe("ghosttrack/devices/+/location")
        else:
            print(f"连接失败，返回码: {rc}")

    def _on_disconnect(self, client, userdata, rc):
        """断开连接回调"""
        print("与 MQTT Broker 断开连接，正在尝试重连...")
        time.sleep(5)
        client.reconnect()

    def _on_message(self, client, userdata, msg):
        """收到消息回调"""
        try:
            payload = json.loads(msg.payload.decode())
            print(f"收到设备位置数据: {payload}")
        except json.JSONDecodeError:
            print(f"消息解析失败: {msg.payload}")

    def connect(self):
        """建立连接"""
        self.client.connect(self.broker_host, self.broker_port, keepalive=60)
        self.client.loop_start()

    def disconnect(self):
        """断开连接"""
        self.client.loop_stop()
        self.client.disconnect()

    def publish_location(self, device_id, latitude, longitude, **kwargs):
        """
        发布设备位置信息

        Topic 格式: ghosttrack/devices/{device_id}/location
        """
        topic = f"ghosttrack/devices/{device_id}/location"
        payload = {
            "latitude": latitude,
            "longitude": longitude,
            "timestamp": int(time.time()),
            **kwargs
        }

        self.client.publish(topic, json.dumps(payload))
        print(f"已发布位置数据到 {topic}")

# 使用示例
mqtt_client = GhostTrackMQTT(
    broker_host="localhost",
    broker_port=1883,
    username="your_username",
    password="your_password"
)

mqtt_client.connect()

# 模拟持续追踪
try:
    while True:
        # 模拟设备移动
        for lat in [31.2, 31.21, 31.22, 31.23]:
            mqtt_client.publish_location(
                device_id="BIKE-001",
                latitude=lat,
                longitude=121.47,
                speed=25.0,
                heading=45.0
            )
            time.sleep(2)
except KeyboardInterrupt:
    print("\n停止追踪")
    mqtt_client.disconnect()

from ghosttrack.engine import StreamProcessor
from ghosttrack.filters import (
    GeoFenceFilter,
    SpeedFilter,
    AccuracyFilter,
    DuplicateFilter
)
from ghosttrack.alerts import AlertManager

# 创建流处理器
processor = StreamProcessor(
    buffer_size=1000,
    flush_interval=5.0  # 每5秒刷新一次
)

# 配置数据过滤器链
processor.add_filter(DuplicateFilter(tolerance_seconds=1.0))
processor.add_filter(AccuracyFilter(min_accuracy=50.0))  # 过滤精度低于50米的数据
processor.add_filter(SpeedFilter(max_speed=200.0))       # 过滤速度异常数据

# 配置电子围栏
processor.add_filter(GeoFenceFilter(
    name="北京市中心区域",
    coordinates=[
        (39.8, 116.3),
        (39.8, 116.5),
        (40.0, 116.5),
        (40.0, 116.3)
    ],
    action="allow"  # allow=允许区域内的数据, deny=禁止区域内的数据
))

# 配置告警管理
alert_manager = AlertManager()

# 添加告警规则
alert_manager.add_rule({
    "name": "超速告警",
    "condition": lambda data: data.get("speed", 0) > 120,
    "severity": "warning",
    "message": "设备 {device_id} 检测到超速行驶，速度: {speed} km/h"
})

alert_manager.add_rule({
    "name": "设备离线告警",
    "condition": lambda data: data.get("offline_duration", 0) > 300,
    "severity": "critical",
    "message": "设备 {device_id} 已离线超过 {offline_duration} 秒"
})

# 设置告警回调
def on_alert(alert):
    print(f"🚨 告警触发 [{alert['severity']}]: {alert['message']}")
    # 可以在这里添加邮件通知、短信通知、webhook 等逻辑

alert_manager.on_alert = on_alert

# 启动处理器
processor.start()

# 提交数据进行处理
test_data = {
    "device_id": "VEHICLE-001",
    "latitude": 39.9042,
    "longitude": 116.4074,
    "speed": 85.0,
    "accuracy": 10.0,
    "timestamp": "2024-01-15T10:30:00Z"
}

processor.submit(test_data)

from ghosttrack.storage import StorageManager
from ghosttrack.models import LocationRecord, DeviceInfo
from datetime import datetime, timedelta

# 初始化存储管理器
storage = StorageManager(
    backend="postgresql",  # 支持: sqlite, postgresql, mysql, timescaledb
    connection_string="postgresql://user:pass@localhost:5432/ghosttrack"
)

# 保存单条位置记录
record = LocationRecord(
    device_id="BIKE-001",
    latitude=31.2304,
    longitude=121.4737,
    altitude=10.0,
    speed=25.0,
    heading=90.0,
    accuracy=5.0,
    timestamp=datetime.now()
)

storage.save_location(record)

# 批量保存位置记录
records = [
    LocationRecord(
        device_id="BIKE-001",
        latitude=31.2304 + i * 0.001,
        longitude=121.4737 + i * 0.001,
        timestamp=datetime.now() - timedelta(minutes=i)
    )
    for i in range(10)
]

storage.save_locations_batch(records)

# 查询设备历史轨迹
trajectory = storage.get_trajectory(
    device_id="BIKE-001",
    start_time=datetime.now() - timedelta(hours=24),
    end_time=datetime.now(),
    limit=1000
)

print(f"获取到 {len(trajectory)} 条轨迹记录")

# 计算轨迹总距离
def calculate_distance(points):
    """使用 Haversine 公式计算轨迹总距离"""
    from math import radians, sin, cos, sqrt, atan2

    def haversine(lat1, lon1, lat2, lon2):
        R = 6371  # 地球半径（公里）
        lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
        dlat = lat2 - lat1
        dlon = lon2 - lon1
        a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
        c = 2 * atan2(sqrt(a), sqrt(1-a))
        return R * c

    total_distance = 0
    for i in range(1, len(points)):
        total_distance += haversine(
            points[i-1].latitude, points[i-1].longitude,
            points[i].latitude, points[i].longitude
        )

    return total_distance

total_km = calculate_distance(trajectory)
print(f"总行程: {total_km:.2f} 公里")

# 按设备分组统计
stats = storage.get_device_stats(
    start_time=datetime.now() - timedelta(days=30)
)

for device_stat in stats:
    print(f"设备 {device_stat.device_id}: "
          f"记录数={device_stat.record_count}, "
          f"总距离={device_stat.total_distance:.2f}km, "
          f"平均速度={device_stat.avg_speed:.1f}km/h")

import asyncio
import websockets
import json

async def websocket_demo():
    """WebSocket 实时追踪演示"""

    # 连接到 GhostTrack WebSocket 服务
    uri = "ws://localhost:8000/ws/stream"

    async with websockets.connect(uri) as websocket:
        print("已连接到 GhostTrack 实时流")

        # 订阅特定设备
        subscribe_msg = {
            "action": "subscribe",
            "device_ids": ["BIKE-001", "BIKE-002", "TRUCK-001"]
        }
        await websocket.send(json.dumps(subscribe_msg))
        print(f"已订阅设备: {subscribe_msg['device_ids']}")

        # 持续接收实时数据
        while True:
            try:
                message = await websocket.recv()
                data = json.loads(message)

                # 处理不同类型的消息
                msg_type = data.get("type")

                if msg_type == "location_update":
                    device_id = data["device_id"]
                    lat = data["latitude"]
                    lon = data["longitude"]
                    speed = data.get("speed", 0)

                    print(f"📍 {device_id}: ({lat:.6f}, {lon:.6f}) "
                          f"速度: {speed:.1f} km/h")

                elif msg_type == "alert":
                    print(f"🚨 告警: {data['message']}")

                elif msg_type == "device_status":
                    status = data["status"]
                    print(f"📶 设备状态: {data['device_id']} -> {status}")

            except websockets.exceptions.ConnectionClosed:
                print("连接已断开")
                break

# 运行演示
asyncio.run(websocket_demo())

┌─────────────────────────────────────────────────────────────────┐
│                    车辆追踪系统架构                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐               │
│   │ 车载 GPS │────▶│ GhostTrack│────▶│ Dashboard│               │
│   │  设备    │     │  Server  │     │   前端   │               │
│   └──────────┘     └────┬─────┘     └──────────┘               │
│                         │                                       │
│                         ▼                                       │
│                   ┌──────────┐                                  │
│                   │ 数据存储 │                                  │
│                   │ PostgreSQL│                                 │
│                   └──────────┘                                  │
│                                                                 │
│   ┌──────────────────────────────────────────────────┐         │
│   │                    告警通知层                     │         │
│   │  ┌─────────┐  ┌─────────┐  ┌─────────────────┐  │         │
│   │  │  邮件   │  │  短信   │  │   Webhook      │  │         │
│   │  └─────────┘  └─────────┘  └─────────────────┘  │         │
│   └──────────────────────────────────────────────────┘         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

# models/fleet_models.py

from ghosttrack.models import BaseModel, LocationRecord
from datetime import datetime
from typing import List, Optional
from pydantic import BaseModel as PydanticBase, Field

class Vehicle(BaseModel):
    """车辆基础信息模型"""
    vehicle_id: str = Field(..., description="车辆唯一标识")
    license_plate: str = Field(..., description="车牌号")
    vehicle_type: str = Field(default="sedan", description="车辆类型")
    driver_name: Optional[str] = Field(None, description="司机姓名")
    driver_phone: Optional[str] = Field(None, description="司机电话")
    max_speed: float = Field(default=120.0, description="最大允许速度 km/h")
    geofence_ids: List[str] = Field(default_factory=list, description="绑定的电子围栏")

class VehicleLocation(LocationRecord):
    """车辆位置扩展模型"""
    vehicle_id: str = Field(..., description="车辆ID")
    fuel_level: Optional[float] = Field(None, ge=0, le=100, description="油量百分比")
    engine_status: str = Field(default="off", description="发动机状态")
    door_status: str = Field(default="locked", description="车门状态")
    odometer: Optional[float] = Field(None, description="总里程 km")

class VehicleAlert(BaseModel):
    """车辆告警模型"""
    alert_id: str = Field(default_factory=lambda: f"ALT-{datetime.now().strftime('%Y%m%d%H%M%S')}")
    vehicle_id: str = Field(..., description="关联车辆ID")
    alert_type: str = Field(..., description="告警类型")
    severity: str = Field(default="info", description="严重程度")
    message: str = Field(..., description="告警详情")
    location: dict = Field(..., description="告警位置")
    timestamp: datetime = Field(default_factory=datetime.now)
    acknowledged: bool = Field(default=False, description="是否已确认")
    acknowledged_by: Optional[str] = Field(None, description="确认人")
    acknowledged_at: Optional[datetime] = Field(None, description="确认时间")

# server/fleet_tracker.py

import asyncio
import json
from datetime import datetime, timedelta
from typing import Dict, Set
from contextlib import asynccontextmanager

from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from ghosttrack import GhostTrack
from ghosttrack.storage import StorageManager
from ghosttrack.engine import StreamProcessor, GeoFenceFilter, SpeedFilter

from models.fleet_models import Vehicle, VehicleLocation, VehicleAlert

# 全局变量
ghosttrack = GhostTrack()
storage = StorageManager(backend="postgresql")
stream_processor = StreamProcessor()
alert_callbacks: Dict[str, Set] = {}

# 创建 FastAPI 应用
app = FastAPI(
    title="车队追踪系统",
    description="基于 GhostTrack 的企业级车辆追踪解决方案",
    version="1.0.0"
)

# 配置 CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# =============================================================================
# 辅助函数
# =============================================================================

def create_speed_alert(vehicle_id: str, speed: float, max_speed: float) -> VehicleAlert:
    """创建超速告警"""
    return VehicleAlert(
        vehicle_id=vehicle_id,
        alert_type="overspeed",
        severity="warning",
        message=f"车辆超速！当前速度 {speed:.1f} km/h，超过限速 {max_speed} km/h",
        location={"overspeed": speed - max_speed}
    )

def create_geofence_alert(vehicle_id: str, fence_name: str, action: str) -> VehicleAlert:
    """创建电子围栏告警"""
    return VehicleAlert(
        vehicle_id=vehicle_id,
        alert_type="geofence",
        severity="info",
        message=f"车辆{action}电子围栏: {fence_name}",
        location={"fence_name": fence_name, "action": action}
    )

async def broadcast_to_subscribers(vehicle_id: str, data: dict):
    """向订阅该车辆的 WebSocket 客户端广播消息"""
    if vehicle_id in alert_callbacks:
        for websocket in alert_callbacks[vehicle_id]:
            try:
                await websocket.send_json(data)
            except Exception as e:
                print(f"广播消息失败: {e}")

async def save_and_process_location(location: VehicleLocation):
    """保存位置数据并进行实时处理"""
    # 保存到数据库
    await storage.save_location(location)

    # 提交到流处理器进行实时分析
    await stream_processor.submit(location.dict())

    # 广播实时更新
    await broadcast_to_subscribers(location.vehicle_id, {
        "type": "location_update",
        "data": location.dict()
    })

# =============================================================================
# WebSocket 端点
# =============================================================================

@app.websocket("/ws/vehicles/{vehicle_id}")
async def vehicle_websocket(websocket: WebSocket, vehicle_id: str):
    """车辆实时数据 WebSocket 连接"""
    await websocket.accept()

    # 添加到订阅列表
    if vehicle_id not in alert_callbacks:
        alert_callbacks[vehicle_id] = set()
    alert_callbacks[vehicle_id].add(websocket)

    try:
        while True:
            # 保持连接，可以在这里处理客户端发送的消息
            data = await websocket.receive_text()
            message = json.loads(data)

            if message.get("action") == "ping":
                await websocket.send_json({"type": "pong"})

    except WebSocketDisconnect:
        alert_callbacks[vehicle_id].discard(websocket)
        if not alert_callbacks[vehicle_id]:
            del alert_callbacks[vehicle_id]

# =============================================================================
# REST API 端点
# =============================================================================

@app.post("/api/v1/vehicles", response_model=Vehicle)
async def register_vehicle(vehicle: Vehicle):
    """注册新车辆"""
    existing = await storage.get_vehicle(vehicle.vehicle_id)
    if existing:
        raise HTTPException(status_code=400, detail="车辆已存在")

    await storage.save_vehicle(vehicle)
    return vehicle

@app.get("/api/v1/vehicles/{vehicle_id}", response_model=Vehicle)
async def get_vehicle(vehicle_id: str):
    """获取车辆信息"""
    vehicle = await storage.get_vehicle(vehicle_id)
    if not vehicle:
        raise HTTPException(status_code=404, detail="车辆不存在")
    return vehicle

@app.post("/api/v1/vehicles/{vehicle_id}/location")
async def report_vehicle_location(vehicle_id: str, location: VehicleLocation):
    """上报车辆位置"""
    location.vehicle_id = vehicle_id
    location.timestamp = datetime.now()

    # 获取车辆配置用于告警判断
    vehicle = await storage.get_vehicle(vehicle_id)
    if vehicle and vehicle.max_speed and location.speed and location.speed > vehicle.max_speed:
        alert = create_speed_alert(vehicle_id, location.speed, vehicle.max_speed)
        await storage.save_alert(alert)
        await broadcast_to_subscribers(vehicle_id, {
            "type": "alert",
            "alert": alert.dict()
        })

    await save_and_process_location(location)

    return {"status": "success", "timestamp": location.timestamp}

@app.get("/api/v1/vehicles/{vehicle_id}/trajectory")
async def get_vehicle_trajectory(
    vehicle_id: str,
    start_time: datetime = None,
    end_time: datetime = None,
    limit: int = 1000
):
    """获取车辆轨迹"""
    if not start_time:
        start_time = datetime.now() - timedelta(hours=24)
    if not end_time:
        end_time = datetime.now()

    trajectory = await storage.get_trajectory(
        vehicle_id=vehicle_id,
        start_time=start_time,
        end_time=end_time,
        limit=limit
    )

    return {
        "vehicle_id": vehicle_id,
        "start_time": start_time,
        "end_time": end_time,
        "point_count": len(trajectory),
        "trajectory": [p.dict() for p in trajectory]
    }

@app.get("/api/v1/vehicles/{vehicle_id}/alerts")
async def get_vehicle_alerts(
    vehicle_id: str,
    start_time: datetime = None,
    end_time: datetime = None,
    acknowledged: bool = None
):
    """获取车辆告警记录"""
    alerts = await storage.get_alerts(
        vehicle_id=vehicle_id,
        start_time=start_time,
        end_time=end_time,
        acknowledged=acknowledged
    )
    return {"alerts": [a.dict() for a in alerts]}

@app.post("/api/v1/alerts/{alert_id}/acknowledge")
async def acknowledge_alert(alert_id: str, acknowledged_by: str):
    """确认告警"""
    alert = await storage.get_alert(alert_id)
    if not alert:
        raise HTTPException(status_code=404, detail="告警不存在")

    alert.acknowledged = True
    alert.acknowledged_by = acknowledged_by
    alert.acknowledged_at = datetime.now()

    await storage.update_alert(alert)

    return {"status": "success", "alert": alert.dict()}

@app.get("/api/v1/dashboard/stats")
async def get_dashboard_stats():
    """获取仪表盘统计数据"""
    stats = await storage.get_fleet_stats()
    return stats

@app.get("/health")
async def health_check():
    """健康检查端点"""
    return {
        "status": "healthy",
        "version": "1.0.0",
        "timestamp": datetime.now().isoformat(),
        "active_connections": sum(len(subs) for subs in alert_callbacks.values()),
        "registered_vehicles": await storage.count_vehicles()
    }

# =============================================================================
# 启动和关闭事件
# =============================================================================

@app.on_event("startup")
async def startup_event():
    """应用启动时的初始化"""
    # 初始化存储
    await storage.connect()

    # 配置流处理器
    stream_processor.add_filter(SpeedFilter(max_speed=200.0))

    # 设置告警回调
    async def alert_handler(alert_data):
        alert = VehicleAlert(**alert_data)
        await storage.save_alert(alert)
        await broadcast_to_subscribers(alert.vehicle_id, {
            "type": "alert",
            "alert": alert.dict()
        })

    stream_processor.on_alert = alert_handler
    stream_processor.start()

    print("车队追踪系统已启动")

@app.on_event("shutdown")
async def shutdown_event():
    """应用关闭时的清理"""
    stream_processor.stop()
    await storage.disconnect()
    print("车队追踪系统已关闭")

# 启动服务
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

# scripts/simulate_fleet.py

import asyncio
import random
import time
from datetime import datetime
from models.fleet_models import Vehicle, VehicleLocation

# 模拟车辆列表
SIMULATED_VEHICLES = [
    {"vehicle_id": "TRUCK-001", "license_plate": "京A12345", "max_speed": 100},
    {"vehicle_id": "TRUCK-002", "license_plate": "京B67890", "max_speed": 100},
    {"vehicle_id": "VAN-001", "license_plate": "沪C11111", "max_speed": 120},
    {"vehicle_id": "VAN-002", "license_plate": "沪D22222", "max_speed": 120},
    {"vehicle_id": "CAR-001", "license_plate": "粤E33333", "max_speed": 140},
]

class FleetSimulator:
    """车队位置模拟器"""

    def __init__(self, api_base_url):
        self.api_base_url = api_base_url.rstrip('/')
        self.running = False

        # 模拟车辆位置（起始点）
        self.vehicle_positions = {
            v["vehicle_id"]: {
                "latitude": 39.9042 + random.uniform(-0.1, 0.1),
                "longitude": 116.4074 + random.uniform(-0.1, 0.1),
                "heading": random.uniform(0, 360),
                "speed": 0
            }
            for v in SIMULATED_VEHICLES
        }

    async def register_vehicles(self):
        """注册模拟车辆"""
        import requests

        for vehicle_data in SIMULATED_VEHICLES:
            vehicle = Vehicle(
                vehicle_id=vehicle_data["vehicle_id"],
                license_plate=vehicle_data["license_plate"],
                vehicle_type="truck" if "TRUCK" in vehicle_data["vehicle_id"] else "van",
                max_speed=vehicle_data["max_speed"]
            )

            try:
                response = requests.post(
                    f"{self.api_base_url}/api/v1/vehicles",
                    json=vehicle.dict(),
                    timeout=5
                )
                if response.status_code == 200:
                    print(f"✓ 车辆 {vehicle.vehicle_id} 注册成功")
                elif response.status_code == 400:
                    print(f"- 车辆 {vehicle.vehicle_id} 已存在")
                else:
                    print(f"✗ 车辆 {vehicle.vehicle_id} 注册失败: {response.text}")
            except Exception as e:
                print(f"✗ 车辆 {vehicle.vehicle_id} 注册失败: {e}")

    def update_position(self, vehicle_id):
        """更新单个车辆位置"""
        pos = self.vehicle_positions[vehicle_id]

        # 模拟移动
        speed_kmh = random.uniform(30, 80)  # 随机速度 30-80 km/h
        speed_ms = speed_kmh / 3.6  # 转换为米/秒

        # 更新方向（模拟道路转弯）
        heading_change = random.uniform(-30, 30)
        pos["heading"] = (pos["heading"] + heading_change) % 360

        # 根据速度和方向计算新位置
        distance_m = speed_ms * 2  # 2秒的移动距离
        heading_rad = pos["heading"] * 3.14159 / 180

        lat_change = (distance_m / 111000) * (-1 if pos["heading"] > 180 else 1) * abs(1 - abs(90 - pos["heading"]) / 90)
        lon_change = (distance_m / (111000 * abs(39.9042))) * (-1 if 90 < pos["heading"] < 270 else 1)

        pos["latitude"] += lat_change * random.uniform(0.8, 1.2)
        pos["longitude"] += lon_change * random.uniform(0.8, 1.2)
        pos["speed"] = speed_kmh

        # 偶尔模拟异常情况
        if random.random() < 0.02:  # 2% 概率超速
            pos["speed"] = random.uniform(120, 150)

        return pos

    async def run_simulation(self, interval=2):
        """运行模拟循环"""
        import requests

        self.running = True
        print(f"\n开始模拟 {len(SIMULATED_VEHICLES)} 辆车的位置追踪...")
        print("按 Ctrl+C 停止模拟\n")

        while self.running:
            for vehicle_id in self.vehicle_positions:
                pos = self.update_position(vehicle_id)

                location_data = {
                    "vehicle_id": vehicle_id,
                    "latitude": round(pos["latitude"], 6),
                    "longitude": round(pos["longitude"], 6),
                    "altitude": random.uniform(0, 100),
                    "speed": round(pos["speed"], 1),
                    "heading": round(pos["heading"], 1),
                    "accuracy": random.uniform(3, 10),
                    "fuel_level": random.uniform(20, 100),
                    "engine_status": "running",
                    "door_status": "locked"
                }

                try:
                    response = requests.post(
                        f"{self.api_base_url}/api/v1/vehicles/{vehicle_id}/location",
                        json=location_data,
                        timeout=5
                    )

                    if response.status_code == 200:
                        print(f"[{datetime.now().strftime('%H:%M:%S')}] "
                              f"{vehicle_id}: ({pos['latitude']:.6f}, {pos['longitude']:.6f}) "
                              f"速度: {pos['speed']:.1f} km/h")
                except Exception as e:
                    print(f"位置上报失败 {vehicle_id}: {e}")

            await asyncio.sleep(interval)

    def stop(self):
        """停止模拟"""
        self.running = False

async def main():
    simulator = FleetSimulator("http://localhost:8000")

    # 注册车辆
    await simulator.register_vehicles()

    # 运行模拟
    try:
        await simulator.run_simulation(interval=2)
    except KeyboardInterrupt:
        print("\n\n停止模拟...")
        simulator.stop()

if __name__ == "__main__":
    asyncio.run(main())

<!-- frontend/dashboard.html -->

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>车队追踪系统 - 实时监控</title>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: #f5f7fa;
            color: #333;
        }

        .header {
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
            padding: 20px 30px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }

        .header h1 {
            font-size: 24px;
            margin-bottom: 5px;
        }

        .header .status {
            font-size: 14px;
            opacity: 0.9;
        }

        .status.connected { color: #4ade80; }
        .status.disconnected { color: #f87171; }

        .main-container {
            display: flex;
            height: calc(100vh - 80px);
        }

        .sidebar {
            width: 320px;
            background: white;
            border-right: 1px solid #e5e7eb;
            overflow-y: auto;
            padding: 20px;
        }

        .vehicle-card {
            background: #f9fafb;
            border: 1px solid #e5e7eb;
            border-radius: 12px;
            padding: 15px;
            margin-bottom: 12px;
            cursor: pointer;
            transition: all 0.2s;
        }

        .vehicle-card:hover {
            border-color: #667eea;
            box-shadow: 0 2px 8px rgba(102, 126, 234, 0.2);
        }

        .vehicle-card.selected {
            border-color: #667eea;
            background: #f0f1ff;
        }

        .vehicle-card .vehicle-header {
            display: flex;
            justify-content: space-between;
            align-items: center;
            margin-bottom: 10px;
        }

        .vehicle-card .vehicle-id {
            font-weight: 600;
            color: #1f2937;
        }

        .vehicle-card .license-plate {
            background: #667eea;
            color: white;
            padding: 2px 8px;
            border-radius: 4px;
            font-size: 12px;
        }

        .vehicle-card .vehicle-info {
            font-size: 13px;
            color: #6b7280;
        }

        .vehicle-card .vehicle-info span {
            margin-right: 15px;
        }

        .vehicle-card .alert-badge {
            background: #ef4444;
            color: white;
            padding: 2px 6px;
            border-radius: 10px;
            font-size: 11px;
            margin-left: 5px;
        }

        .map-container {
            flex: 1;
            position: relative;
        }

        #map {
            width: 100%;
            height: 100%;
        }

        .stats-panel {
            position: absolute;
            top: 20px;
            right: 20px;
            background: white;
            border-radius: 12px;
            padding: 20px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
            z-index: 1000;
            min-width: 200px;
        }

        .stats-panel h3 {
            font-size: 14px;
            color: #6b7280;
            margin-bottom: 15px;
        }

        .stat-item {
            margin-bottom: 12px;
        }

        .stat-item .label {
            font-size: 12px;
            color: #9ca3af;
        }

        .stat-item .value {
            font-size: 24px;
            font-weight: 600;
            color: #667eea;
        }

        .alert-panel {
            position: absolute;
            bottom: 20px;
            right: 20px;
            width: 350px;
            max-height: 300px;
            background: white;
            border-radius: 12px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
            z-index: 1000;
            overflow: hidden;
        }

        .alert-panel .alert-header {
            background: #fef2f2;
            padding: 12px 15px;
            font-weight: 600;
            color: #dc2626;
            display: flex;
            align-items: center;
            gap: 8px;
        }

        .alert-panel .alert-list {
            max-height: 250px;
            overflow-y: auto;
        }

        .alert-item {
            padding: 12px 15px;
            border-bottom: 1px solid #f3f4f6;
            font-size: 13px;
        }

        .alert-item.warning {
            border-left: 3px solid #f59e0b;
        }

        .alert-item.critical {
            border-left: 3px solid #ef4444;
        }

        .alert-item .alert-time {
            color: #9ca3af;
            font-size: 11px;
            margin-top: 4px;
        }

        .vehicle-popup {
            font-size: 13px;
        }

        .vehicle-popup h4 {
            margin-bottom: 8px;
            color: #667eea;
        }

        .vehicle-popup p {
            margin: 4px 0;
            color: #6b7280;
        }

        .leaflet-container {
            font-family: inherit;
        }
    </style>
</head>
<body>
    <div class="header">
        <h1>🚌 车队追踪系统</h1>
        <div class="status disconnected" id="connectionStatus">
            🔌 正在连接服务器...
        </div>
    </div>

    <div class="main-container">
        <div class="sidebar">
            <h2 style="font-size: 16px; margin-bottom: 15px;">📋 车辆列表</h2>
            <div id="vehicleList">
                <!-- 动态生成的车辆卡片 -->
            </div>
        </div>

        <div class="map-container">
            <div id="map"></div>

            <div class="stats-panel">
                <h3>📊 实时统计</h3>
                <div class="stat-item">
                    <div class="label">在线车辆</div>
                    <div class="value" id="onlineCount">0</div>
                </div>
                <div class="stat-item">
                    <div class="label">活跃告警</div>
                    <div class="value" id="alertCount">0</div>
                </div>
                <div class="stat-item">
                    <div class="label">今日行程</div>
                    <div class="value" id="todayDistance">0 km</div>
                </div>
            </div>

            <div class="alert-panel">
                <div class="alert-header">
                    🚨 最新告警
                </div>
                <div class="alert-list" id="alertList">
                    <div class="alert-item" style="color: #9ca3af; text-align: center; padding: 20px;">
                        暂无告警
                    </div>
                </div>
            </div>
        </div>
    </div>

    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
    <script>
        // =====================================================================
        // 全局状态
        // =====================================================================

        const state = {
            vehicles: {},
            selectedVehicleId: null,
            websocket: null,
            markers: {},
            vehiclePaths: {}
        };

        // 初始化地图
        const map = L.map('map').setView([39.9042, 116.4074], 12);

        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
            attribution: '© OpenStreetMap contributors'
        }).addTo(map);

        // 自定义车辆图标
        const vehicleIcon = L.divIcon({
            html: '<div style="background: #667eea; width: 24px; height: 24px; border-radius: 50%; border: 3px solid white; box-shadow: 0 2px 6px rgba(0,0,0,0.3);"></div>',
            iconSize: [24, 24],
            iconAnchor: [12, 12],
            className: 'vehicle-marker'
        });

        const selectedVehicleIcon = L.divIcon({
            html: '<div style="background: #ef4444; width: 28px; height: 28px; border-radius: 50%; border: 3px solid white; box-shadow: 0 2px 10px rgba(239,68,68,0.5);"></div>',
            iconSize: [28, 28],
            iconAnchor: [14, 14],
            className: 'vehicle-marker-selected'
        });

        // =====================================================================
        // WebSocket 连接
        // =====================================================================

        function connectWebSocket() {
            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
            const wsUrl = `${protocol}//${window.location.host}/ws/vehicles`;

            state.websocket = new WebSocket(wsUrl);

            state.websocket.onopen = () => {
                console.log('WebSocket 连接成功');
                document.getElementById('connectionStatus').textContent = '✓ 已连接到服务器';
                document.getElementById('connectionStatus').className = 'status connected';

                // 订阅所有车辆
                state.websocket.send(JSON.stringify({
                    action: 'subscribe',
                    vehicle_ids: Object.keys(state.vehicles)
                }));
            };

            state.websocket.onclose = () => {
                console.log('WebSocket 连接断开，5秒后重连');
                document.getElementById('connectionStatus').textContent = '🔌 连接断开，重新连接中...';
                document.getElementById('connectionStatus').className = 'status disconnected';
                setTimeout(connectWebSocket, 5000);
            };

            state.websocket.onerror = (error) => {
                console.error('WebSocket 错误:', error);
            };

            state.websocket.onmessage = (event) => {
                const data = JSON.parse(event.data);
                handleWebSocketMessage(data);
            };
        }

        function handleWebSocketMessage(data) {
            if (data.type === 'location_update') {
                updateVehicleLocation(data.data);
            } else if (data.type === 'alert') {
                handleAlert(data.alert);
            }
        }

        // =====================================================================
        // 车辆管理
        // =====================================================================

        function updateVehicleLocation(locationData) {
            const { vehicle_id, latitude, longitude, speed, heading } = locationData;

            // 更新状态
            if (!state.vehicles[vehicle_id]) {
                state.vehicles[vehicle_id] = {};
            }

            state.vehicles[vehicle_id].location = locationData;
            state.vehicles[vehicle_id].lastUpdate = new Date();

            // 更新或创建标记
            if (state.markers[vehicle_id]) {
                state.markers[vehicle_id].setLatLng([latitude, longitude]);

                // 更新路径
                if (state.vehiclePaths[vehicle_id]) {
                    const latlngs = state.vehiclePaths[vehicle_id].getLatLngs();
                    latlngs.push([latitude, longitude]);
                    if (latlngs.length > 100) latlngs.shift();  // 保持最多100个点
                    state.vehiclePaths[vehicle_id].setLatLngs(latlngs);
                }
            } else {
                // 创建新标记
                const marker = L.marker([latitude, longitude], {
                    icon: vehicleIcon,
                    rotationAngle: heading || 0
                }).addTo(map);

                marker.bindPopup(`
                    <div class="vehicle-popup">
                        <h4>${vehicle_id}</h4>
                        <p>📍 位置: ${latitude.toFixed(6)}, ${longitude.toFixed(6)}</p>
                        <p>⚡ 速度: ${speed || 0} km/h</p>
                        <p>🧭 方向: ${heading || 0}°</p>
                    </div>
                `);

                state.markers[vehicle_id] = marker;

                // 创建轨迹线
                state.vehiclePaths[vehicle_id] = L.polyline([], {
                    color: '#667eea',
                    weight: 3,
                    opacity: 0.7
                }).addTo(map);
            }

            // 更新UI
            updateVehicleCard(vehicle_id);
            updateStats();
        }

        function selectVehicle(vehicleId) {
            // 取消之前的选中
            if (state.selectedVehicleId) {
                const prevCard = document.querySelector(`[data-vehicle-id="${state.selectedVehicleId}"]`);
                if (prevCard) prevCard.classList.remove('selected');

                if (state.markers[state.selectedVehicleId]) {
                    state.markers[state.selectedVehicleId].setIcon(vehicleIcon);
                }
            }

            state.selectedVehicleId = vehicleId;

            // 选中新车辆
            const card = document.querySelector(`[data-vehicle-id="${vehicleId}"]`);
            if (card) card.classList.add('selected');

            if (state.markers[vehicleId]) {
                state.markers[vehicleId].setIcon(selectedVehicleIcon);
                map.setView(state.markers[vehicleId].getLatLng(), 15);
            }
        }

        // =====================================================================
        // UI 更新
        // =====================================================================

        function updateVehicleCard(vehicleId) {
            let card = document.querySelector(`[data-vehicle-id="${vehicleId}"]`);
            const vehicle = state.vehicles[vehicleId];

            if (!card) {
                // 创建新卡片
                card = document.createElement('div');
                card.className = 'vehicle-card';
                card.dataset.vehicleId = vehicleId;
                card.onclick = () => selectVehicle(vehicleId);

                card.innerHTML = `
                    <div class="vehicle-header">
                        <span class="vehicle-id">${vehicleId}</span>
                        <span class="license-plate">--</span>
                    </div>
                    <div class="vehicle-info">
                        <span>⚡ -- km/h</span>
                        <span>📍 --</span>
                    </div>
                `;

                document.getElementById('vehicleList').appendChild(card);
            }

            // 更新卡片信息
            if (vehicle.location) {
                const { speed, latitude, longitude } = vehicle.location;
                card.querySelector('.vehicle-info').innerHTML = `
                    <span>⚡ ${(speed || 0).toFixed(0)} km/h</span>
                    <span>📍 ${latitude.toFixed(4)}, ${longitude.toFixed(4)}</span>
                `;
            }
        }

        function updateStats() {
            const onlineVehicles = Object.values(state.vehicles)
                .filter(v => v.location);

            document.getElementById('onlineCount').textContent = onlineVehicles.length;

            // 计算总行程（简化版本）
            let totalDistance = 0;
            Object.values(state.vehiclePaths).forEach(path => {
                totalDistance += path.getLatLngs().length * 0.01;  // 估算
            });
            document.getElementById('todayDistance').textContent = `${totalDistance.toFixed(1)} km`;
        }

        function handleAlert(alert) {
            const alertList = document.getElementById('alertList');
            const alertCount = document.getElementById('alertCount');

            // 更新告警计数
            const currentCount = parseInt(alertCount.textContent) || 0;
            alertCount.textContent = currentCount + 1;

            // 添加告警到列表
            const alertItem = document.createElement('div');
            alertItem.className = `alert-item ${alert.severity}`;
            alertItem.innerHTML = `
                <div>${alert.message}</div>
                <div class="alert-time">${new Date(alert.timestamp).toLocaleString()}</div>
            `;

            // 清空"暂无告警"提示
            if (alertList.querySelector('div[style*="text-align"]')) {
                alertList.innerHTML = '';
            }

            // 添加到列表开头
            alertList.insertBefore(alertItem, alertList.firstChild);

            // 保持最多显示10条
            while (alertList.children.length > 10) {
                alertList.removeChild(alertList.lastChild);
            }
        }

        // =====================================================================
        // 初始化
        // =====================================================================

        async function init() {
            try {
                // 从API获取车辆列表
                const response = await fetch('/api/v1/vehicles');
                if (response.ok) {
                    const vehicles = await response.json();
                    vehicles.forEach(vehicle => {
                        state.vehicles[vehicle.vehicle_id] = {
                            info: vehicle
                        };
                        updateVehicleCard(vehicle.vehicle_id);
                    });
                }
            } catch (error) {
                console.error('获取车辆列表失败:', error);
            }

            // 连接 WebSocket
            connectWebSocket();

            // 每30秒更新一次统计数据
            setInterval(updateStats, 30000);
        }

        // 启动应用
        init();
    </script>
</body>
</html>

# 1. 启动后端服务
cd /path/to/GhostTrack
python -m uvicorn server.fleet_tracker:app --host 0.0.0.0 --port 8000 --reload

# 2. 在另一个终端启动模拟器（生成测试数据）
python scripts/simulate_fleet.py

# 3. 在浏览器中打开 Dashboard
# http://localhost:8000/dashboard

# 物流追踪集成示例

from ghosttrack import GhostTrack
from datetime import datetime, timedelta

class LogisticsTracker:
    """物流追踪管理器"""

    def __init__(self):
        self.ghosttrack = GhostTrack()
        self.fleet = {}

    def register_delivery_vehicle(self, vehicle_id, max_range_km=500):
        """注册配送车辆"""
        self.fleet[vehicle_id] = {
            "type": "delivery",
            "max_range": max_range_km,
            "deliveries": [],
            "current_charge": 100
        }
        return self.fleet[vehicle_id]

    def assign_delivery(self, vehicle_id, destination, package_id):
        """分配配送任务"""
        if vehicle_id not in self.fleet:
            raise ValueError(f"车辆 {vehicle_id} 未注册")

        delivery = {
            "package_id": package_id,
            "destination": destination,
            "assigned_at": datetime.now(),
            "status": "assigned"
        }

        self.fleet[vehicle_id]["deliveries"].append(delivery)
        return delivery

    def update_location(self, vehicle_id, latitude, longitude, battery_level=None):
        """更新车辆位置并检查配送状态"""
        # 上报位置
        self.ghosttrack.report_location(
            device_id=vehicle_id,
            latitude=latitude,
            longitude=longitude
        )

        # 检查是否到达配送点
        vehicle = self.fleet[vehicle_id]
        for delivery in vehicle["deliveries"]:
            if delivery["status"] == "assigned":
                # 计算距离（简化版）
                distance = self.calculate_distance(
                    latitude, longitude,
                    delivery["destination"]["lat"],
                    delivery["destination"]["lon"]
                )

                if distance < 0.1:  # 100米内视为到达
                    delivery["status"] = "delivered"
                    delivery["delivered_at"] = datetime.now()
                    print(f"📦 包裹 {delivery['package_id']} 已送达！")

        # 更新电量（如果有）
        if battery_level is not None:
            vehicle["current_charge"] = battery_level

            # 低电量告警
            if battery_level < 20:
                self.ghosttrack.trigger_alert(
                    device_id=vehicle_id,
                    alert_type="low_battery",
                    severity="warning",
                    message=f"车辆 {vehicle_id} 电量过低: {battery_level}%"
                )

    @staticmethod
    def calculate_distance(lat1, lon1, lat2, lon2):
        """计算两点间距离（公里）"""
        from math import radians, sin, cos, sqrt, atan2

        R = 6371
        lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
        dlat = lat2 - lat1
        dlon = lon2 - lon1
        a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
        c = 2 * atan2(sqrt(a), sqrt(1-a))
        return R * c

    def get_delivery_summary(self, vehicle_id):
        """获取配送汇总"""
        if vehicle_id not in self.fleet:
            return None

        vehicle = self.fleet[vehicle_id]
        deliveries = vehicle["deliveries"]

        return {
            "vehicle_id": vehicle_id,
            "total_deliveries": len(deliveries),
            "delivered": sum(1 for d in deliveries if d["status"] == "delivered"),
            "pending": sum(1 for d in deliveries if d["status"] == "assigned"),
            "current_charge": vehicle["current_charge"]
        }

# 使用示例
tracker = LogisticsTracker()

# 注册车辆
tracker.register_delivery_vehicle("VAN-SH-001", max_range_km=300)

# 分配配送任务
tracker.assign_delivery(
    vehicle_id="VAN-SH-001",
    destination={"lat": 31.2304, "lon": 121.4737},
    package_id="PKG-2024-001"
)

# 模拟配送过程
current_lat, current_lon = 31.2, 121.4
for i in range(20):
    current_lat += 0.0015
    current_lon += 0.0036
    tracker.update_location("VAN-SH-001", current_lat, current_lon, battery_level=100-i*2)

# 查看配送汇总
summary = tracker.get_delivery_summary("VAN-SH-001")
print(f"配送汇总: {summary}")